SAS 9.1.3 Integration Technologies » Developer's Guide

Publish Event Interface
CALL Routines
EVENT_BEGIN
EVENT_BODY
EVENT_PUBLISH
EVENT_END
XML Specification for Generic Events
XML Specification for SASPackage Events
Examples of Published Events
Publishing Framework

EVENT_PUBLISH

The EVENT_PUBLISH CALL routine publishes the specified event. The method of publication depends on the following types of delivery transport:

Publish Event to HTTP

Publishes an event using the HTTP protocol.

Syntax

CALL EVENT_PUBLISH(eventId, publishType, rc,
properties,< propValue1, ...propValueN>, url <,url2, ...urlN>);

eventID
Numeric, input.
Identifies the event that is to be published.

publishType
Character, input.
Indicates how to publish the event. To publish the event using the HTTP protocol, specify a publishType of TO_HTTP.

rc
Numeric, output.
Receives a return code.

properties
Character, input.
Identifies a comma-separated list of optional property names. Specify any of the following property names, or specify double quotation marks to indicate that no properties are to be applied:

  • HTTP_PASSWORD
  • HTTP_PROXY_URL
  • HTTP_USER

propValue1, ...propValueN
Character/Numeric, input.
Specifies one value for each specified property name. The order of the property values must match the order of the property names in the properties parameter. A value must be specified for each property that is specified in the properties parameter. Valid property values are defined as follows:

HTTP_PASSWORD
specifies the password that is needed to bind to the network resources.

HTTP_PROXY_URL
specifies the URL of the proxy server.

HTTP_USER
specifies the user ID that is needed to bind to the network resources.

url <,url2, ...urlN>
Character, input.
Identifies the URL(s) that will be used to publish the event.

Details

If you specify multiple URLs, and if you specify the RESPONSE property in the EVENT_BEGIN CALL routine, then the response will be received and processed only for the URL that you specified first. The event is published to the first URL, and the response is written to the RESULT_URL location. For all remaining URLs, the event will be published, but the EVENT_PUBLISH CALL routine will not write the response to the RESULT_URL location. To process results from multiple URLs, issue EVENT_PUBLISH for each URL. Executing an EVENT_PUBLISH for each URL creates an explicit RESULT_URL for each response.

Example

The following example publishes the event to the network resource using the HTTP protocol. HTTP URL identifies the machine and port to use.

   pubType = "TO_HTTP";
   url = "http://myhost.com:40";
   CALL EVENT_PUBLISH(eventId, 
      pubType, rc, '', url);

Publish Event to Queues

Publishes an event to one or more message queues. After EVENT_PUBLISH creates the event and delivers it to a message queue, the Event Broker then retrieves the event and distributes it to other applications. EVENT_PUBLISH supports event delivery to the IBM MQSeries and MQSeries-C message queues, which are JMS compliant.

Syntax

CALL EVENT_PUBLISH(eventId, publishType, rc, properties,
<propValue1, ...propValueN>, queue1 <,queue2, ...queueN>);

eventID
Numeric, input.
Specifies the event that is to be published.

publishType
Character, input.
Specifies how to publish the event. To publish the event using the queue transport, specify a publishType of TO_QUEUE.

rc
Numeric, output.
Receives a return code.

properties
Character, input.
Identifies a comma-separated list of optional property names. Specify any of the following property names, or specify double quotation marks to indicate that no properties are to be applied:

  • QUEUE_TIMEOUT
  • RESPONSE_QUEUE
  • SELECTOR

propValue1, ...propValueN
Character/numeric, input.
Specifies one value for each specified property name. The order of the property values must match the order of the property names in the properties parameter. A value must be specified for each property that is specified in the properties parameter. Valid property values are defined as follows:

QUEUE_TIMEOUT
specifies the poll timeout value in seconds. If the event expects a result or acknowledgement response, the response queue will identify the queue to receive the response. By default, the EVENT_PUBLISH CALL routine will continue to poll until the response is received or until a 15-second timeout occurs. You can override the default timeout value by specifying an explicit queue timeout value. The value must be greater than zero.

RESPONSE_QUEUE
used by the Event Broker, specifies the name of a queue to receive the result or an acknowledgement. After the event is published, the queue is queried for the response, which is written to a target file that is specified by the RESULT_URL property value.

SELECTOR
specified on the CALL routine, it identifies the name/value properties to define on the event messages that are published. These properties can be used by the Event Broker to determine what messages should be removed from the queue. The Event Broker can be configured so that it only removes messages from the queue that match particular name/value selectors. If the Event Broker configures selectors, only messages that have properties that match the configured selector are delivered to the Event Broker. Other messages remain on the queue.

queue1 <,queue2, ...queueN>
Character, input.
Identifies the queue(s) that will be used to publish the event. IBM MQSeries queues are supported.

MQSERIES://queueManager:queueName
MQSERIES-C://queueManager:queueName

queueManager
specifies the name of the queue manager.

queueName
specifies the name of the queue.

Details

If you specify multiple queues, and if you specify the RESPONSE property in the EVENT_BEGIN CALL routine, then the response will be received and processed only for the queue that you specified first. The event is published to the first queue, and the response is written to the RESULT_URL location. For all remaining queues, the event will be published, but the EVENT_PUBLISH CALL routine will not query the response queue for a result. To process results from multiple queues, issue EVENT_PUBLISH for each queue. Executing an EVENT_PUBLISH for each queue creates an explicit RESULT_URL for each response.

Examples

Example 1

The following example publishes the event to one queue and does not apply any additional queue properties.

   pubType = "TO_QUEUE";
   firstQ = "MQSERIES://PCONE:MYQ";
   Call EVENT_PUBLISH(eventId, 
      pubType, rc, '', firstQ);

Example 2

The following example publishes the event to one queue. Because a response is expected, the RESPONSE_QUEUE property and a timeout value of 30 seconds are specified. If the response is not received in 30 seconds, a timeout will occur.

   pubType = "TO_QUEUE";
   firstQ = "MQSERIES://PCONE:MYQ";
   prop="RESPONSE_QUEUE, QUEUE_TIMEOUT";
   respQ = "PCONE:MYQ";
   timeout = "30";
   Call EVENT_PUBLISH(eventId, pubType, rc, 
      prop, respQ, timeout, firstQ);

Example 3

The following example publishes the event to one queue. The SELECTOR property is used in this example to publish only event messages that are fourth quarter reports from the HR department. The value of the SELECTOR property should be one or more name/value pairs.

   pubType = "TO_QUEUE";
   firstQ = "MQSERIES://PCONE:MYQ";
   prop="SELECTOR";
   propValue="type=report quarter=four dept=hr";
   qName="MQSERIES://QMGR:LocalQ";
   Call event_publish(pid, "TO_QUEUE", 
      rc, prop, propValue, qName);

Publish Event to Subscribers

Publishes an event to subscribers of the specified channel.

Syntax

CALL EVENT_PUBLISH(eventId, publishType, rc,
properties, < propValue1, ...propValueN>, channel);

eventID
Numeric, input.
Specifies the event that is to be published.

publishType
Character, input.
Indicates how to publish the event. To publish an event to the subscribers of a channel, specify a publishType value of TO_SUBSCRIBERS.

rc
Numeric, output.
Receives a return code.

properties
Character, input.
Specify the following property name, or specify double quotation marks to indicate that the property is not to be applied:

  • CHANNEL_STORE
  • SELECTOR

propValue1, ...propValueN
Character/Numeric, input.
Specifies one value for each specified property name. Valid property values are defined as follows:

CHANNEL_STORE
specifies a character string that indicates the repository containing the channel and subscriber metadata. The channel can be defined in a SAS Metadata Repository. See SAS Metadata Repository Channel Store Syntax for details on how to identify a channel defined in a SAS Metadata Repository.

SELECTOR
specified on the CALL routine, it identifies the name/value properties to define on the event messages that are published. These properties can be used by the Event Broker to determine what messages should be removed from the queue. The Event Broker can be configured so that it only removes messages from the queue that match particular name/value selectors. If the Event Broker configures selectors, only messages that have properties that match the configured selector are delivered to the Event Broker. Other messages remain on the queue.

channel
Character, input.
Specifies the name of the channel where the event will be published.

Details

When an event is published to a channel, the event is published to each subscriber of the channel. Each subscriber definition specifies the event publishing transport method to use for the subscriber. Valid transports are HTTP and message queues.

PUBLISH_EVENT ensures that the event is published to each subscriber only once, thus eliminating any duplication. For the message queue transport, the name of the queue is used as the key to enforce uniqueness. For an HTTP server transport, the URL is used as the key to enforce uniqueness.

Publishing an event to subscribers does not support the RESPONSE property.

Example

The following example publishes the event to all subscribers of the WeeklyPayroll channel.

   channelStore = 
      "SAS-OMA://alpair03.sys.com:4059/reposname=MyRepos";
   channelName = "WeeklyPayroll";
   prop = "CHANNEL_STORE,METAUSER,METAPASS";
   user = "myUserName";
   password = "myPassword";
   CALL EVENT_PUBLISH(eventId, "TO_SUBSCRIBERS", 
      rc, prop, channelStore, user, password, channelName);

See Also