Section 3(cbl) - COBOL Functions

ATMI COBOL Function Reference

TPSUBSCRIBE(3cbl)

Name

TPSUBSCRIBE() - subscribe to an event

Synopsis

01 TPEVTDEF-REC.
 COPY TPEVTDEF. 
 
01 TPQUEDEF-REC.
 COPY TPQUEDEF. 
 
01 TPSTATUS-REC.
 COPY TPSTATUS. 
 
CALL "TPSUBSCRIBE" USING TPEVTDEF-REC TPQUEDEF-REC TPSTATUS-REC.

Description

The caller uses TPSUBSCRIBE() to subscribe to an event or set of events named by EVENT-EXPR in TPEVTDEF-REC. Subscriptions are maintained by the BEA Tuxedo EventBroker, TMUSREVT(), and are used to notify subscribers when events are posted via TPPOST(). Each subscription specifies a notification method which can take one of three forms: client notification, service calls, or message enqueuing to stable-storage queues. Notification methods are determined by the subscriber's process type and the setting of the TPEV-METHOD-FLAG in TPEVTDEF-REC.

The event or set of events being subscribed to is named by the regular expression, EVENT-EXPR in TPEVTDEF-REC, and cannot be SPACES. Regular expressions are of the form specified in tpsubscribe(3c). For example, if EVENT-EXPR is "\e\e..*", the caller is subscribing to all system-generated events; if EVENT-EXPR is "\e\e.SysServer.*", the caller is subscribing to all system-generated events related to servers. If EVENT-EXPR is "[A-Z].*", the caller is subscribing to all user events starting with A-Z; if EVENT-EXPR is ".*(ERR|err).*", the caller is subscribing to all user events containing either the substring "ERR" or the substring "err" in the event name (for example, "account_error" and "ERROR_STATE" events would both qualify).

EVENT-FILTER in TPEVTDEF-REC is a string containing a Boolean filter rule that must be evaluated successfully before the EventBroker posts the event. Upon receiving an event to be posted, the EventBroker applies the filter rule, if one exists, to the posted event's data. If the data passes the filter rule, the EventBroker invokes the notification method; otherwise, the broker does not invoke the associated notification method. The caller can subscribe to the same event multiple times with different filter rules.

Filter rules are specific to the typed records to which they are applied. For FML and view records, the filter rule is a string that can be passed to each Boolean expression compiler (see Fboolco, Fboolco32, Fvboolco, Fvboolco32(3fml)) and evaluated against the posted record (see Fboolev, Fboolev32, Fvboolev, Fvboolev32(3fml)). For STRING records, the filter rule is a regular expression of the form specified in tpsubscribe(3c). All other record types require customized filter evaluators (see buffer(3c) and typesw(5) for details on adding customized filter evaluators). If no filter rule is associated with EVENT-EXPR, then EVENT-FILTER must be SPACES.

If the subscriber is a BEA Tuxedo ATMI client process and TPEVNOTIFY in TPEVTDEF-REC is set, then the EventBroker sends an unsolicited message to the subscriber when the event to which it subscribed is posted. That is, when an event name is posted that evaluates successfully against EVENT-EXPR, the EventBroker tests the posted data against the filter rule associated with EVENT-EXPR. If the data passes the filter rule or if there is no filter rule for the event, then the subscriber receives an unsolicited notification along with any data posted with the event. In order to receive unsolicited notifications, the client must register (via TPSETUNSOL()) an unsolicited message handling routine. If a BEA Tuxedo ATMI server process calls TPSUBSCRIBE() with TPEVNOTIFY set, then TPSUBSCRIBE() fails and sets TP-STATUS in TPSTATUS-REC to [TPEPROTO].

Clients receiving event notification via unsolicited messages should remove their subscriptions from the EventBroker's list of active subscriptions before exiting (see TPUNSUBSCRIBE() for details). Using TPUNSUBSCRIB()'s wildcard handle, -1, clients can conveniently remove all of their "non-persistent" subscriptions which include those associated with the unsolicited notification method (see the description of TPEVPERSIST below for subscriptions and their associated notification methods that persist after a process exits). If a client exits without removing its non-persistent subscriptions, then the EventBroker will remove them when it detects that the client is no longer accessible.

When TPEVNOTIFY is set, TPEVNOTRAN and TPEVNOPERSIST must also be set; otherwise TPSUBSCRIBE() fails and sets TP-STATUS to [TPEINVAL]. That is, an event subscription for a client having the unsolicited notification method cannot be transactional nor can it be persistent.

If the subscriber (regardless of process type) sets TPEVSERVICE() in TPEVTDEF-REC, then event notifications are sent to the BEA Tuxedo ATMI service routine named by NAME-1 in TPEVTDEF-REC. That is, when an event name is posted that evaluates successfully against EVENT-EXPR, the EventBroker tests the posted data against the filter rule associated with EVENT-EXPR. If the data passes the filter rule or if there is no filter rule for the event, then a service request is sent to NAME-1 along with any data posted with the event. The service name in NAME-1 can be any valid BEA Tuxedo ATMI service name and it may or may not be active at the time the subscription is made. Service routines invoked by the EventBroker should return with no reply data. That is, they should call TPRETURN() with REC-TYPE in TPTYPE-REC set to SPACES. Any data passed to TPRETURN() will be dropped.

If TPEVTRAN in TPEVTDEF-REC is also set, then if the process calling TPPOST() is in transaction mode, the EventBroker calls the subscribed service routine such that it will be part of the poster's transaction. Both the EventBroker, TMUSREVT(), and the subscribed service routine must belong to server groups that support transactions (see UBBCONFIG(5) for details). If TPEVNOTRAN is set, then the EventBroker calls the subscribed service routine such that it will not be part of the poster's transaction.

If the subscriber (regardless of process type) sets TPEVQUEUE() in TPEVTDEF-REC, then event notifications are enqueued to the queue space named by NAME-1 in TPEVTDEF-REC and the queue named by NAME-2 in TPEVTDEF-REC. That is, when an event name is posted that evaluates successfully against EVENT-EXPR, the EventBroker tests the posted data against the filter rule associated with EVENT-EXPR. If the data passes the filter rule or if there is no filter rule for the event, then the EventBroker enqueues a message to the queue space named by NAME-1 and the queue named by NAME-2 along with any data posted with the event. The queue space and queue name can be any valid BEA Tuxedo ATMI queue space and queue name, either of which may or may not exist at the time the subscription is made.

TPQUEDEF-REC can contain options further directing the EventBroker's enqueuing of the posted event. If the caller has no options to specify, then TPQUEDEF-REC should be set to LOW-VALUE. Otherwise, options can be set as described in the "Control Parameter" subsection of the TPENQUEUE() reference page (specifically, see the section describing the valid list of settings controlling input information for TPENQUEUE()).

If TPEVTRAN in TPEVTDEF-REC is also set, then if the process calling TPPOST() is in transaction mode, the EventBroker enqueues the posted event and its data such that it will be part of the poster's transaction. The EventBroker, TMUSREVT(), must belong to a server group that supports transactions (see UBBCONFIG(5) for details). If TPEVNOTRAN is set, then the EventBroker enqueues the posted event and its data such that it will not be part of the poster's transaction.

By default, the BEA Tuxedo EventBroker deletes subscriptions when the resource to which it is posting is not available (for example, the EventBroker cannot access a service routine and/or a queue space/queue name associated with an event subscription). Setting TPEVPERSIST in TPEVTDEF-REC indicates that the subscriber wants this subscription to persist across such errors (usually because the resource will become available again in the future). Persistent subscriptions are allowed only for TPEVSERVICE() and TPEVQUEUE() notification methods. TPEVPERSIST cannot be used when TPEVNOTIFY is set; otherwise, the function fails and sets TP-STATUS to [TPEINVAL]. When TPEVNOPERSIST is used, the EventBroker will remove this subscription if it encounters an error accessing either the client, the service name, or queue space/queue name designated in this subscription.

If TPEVPERSIST is used with TPEVTRAN and the resource is not available at the time of event notification, then the EventBroker will return to the poster such that its transaction must be aborted. That is, even though the subscription remains intact, the resource's unavailability will cause the poster's transaction to fail.

If the EventBroker's list of active subscriptions already contains a subscription that matches the one being requested by TPSUBSCRIBE(), then the function fails setting TP-STATUS to [TPEMATCH]. For a subscription to match an existing one, both EVENT-EXPR and EVENT-FILTER must match those of a subscription already in the EventBroker's active list of subscriptions. In addition, depending on the notification method, other criteria are used to determine matches.

If TPEVNOTIFY is set, then the caller's system-defined client identifier (known as a CLIENTID) is also used to detect matches. That is, TPSUBSCRIBE() fails if EVENT-EXPR, EVENT-FILTER, and the caller's CLIENTID match those of a subscription already known to the EventBroker.

If TPEVSERVICE() is set, then TPSUBSCRIBE() fails if EVENT-EXPR, EVENT-FILTER, and the service name set in NAME-1 match those of a subscription already known to the EventBroker.

If TPEVQUEUE() is set, then EventBroker uses the queue space, queue name, and correlation identifier, in addition to EVENT-EXPR and EVENT-FILTER, when determining matches. The correlation identifier can be used to differentiate among several subscriptions for the same event expression and filter rule, destined for the same queue. Thus, if the caller has set both TPEVQUEUE() and TPQNOCOORID(), then TPSUBSCRIBE() fails if EVENT-EXPR, EVENT-FILTER, the queue space name set in NAME-1, and the queue name set in NAME-2 match those of a subscription (which also does not have a correlation identifier specified) already known to the EventBroker. Further, if TPQCOORID() is set, then TPSUBSCRIBE() fails if EVENT-EXPR, EVENT-FILTER, NAME-1, NAME-2, and CORRID in TPQUEDEF-REC match those of a subscription (which has the same correlation identifier specified) already known to the EventBroker.

The following is a list of settings in TPEVTDEF-REC.

TPNOBLOCK

The subscription is not made if a blocking condition exists. If such a condition occurs, the call fails and sets TP-STATUS to [TPEBLOCK]. Either TPNOBLOCK or TPBLOCK must be set.

TPBLOCK

When TPBLOCK is specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either TPNOBLOCK or TPBLOCK must be set.

TPNOTIME

This setting signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur. Either TPNOTIME or TPTIME must be set.

TPTIME

This setting signifies that the caller will receive blocking timeouts if a blocking condition exists and the blocking time is reached. Either TPNOTIME or TPTIME must be set.

TPSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted system call is reissued. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

TPNOSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted system call is not restarted, the call fails and sets TP-STATUS to [TPGOTSIG]. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

Return Values

Upon successful completion, TPSUBSCRIBE() sets TP-STATUS to [TPOK]. In addition, TPSUBSCRIBE() sets SUBSCRIPTION-HANDLE in TPEVTDEF-REC to the handle for this subscription. SUBSCRIPTION-HANDLE can be used when calling TPUNSUBSCRIBE() to remove this subscription from the EventBroker's list of active subscriptions. Either the subscriber or any other process is allowed to use the returned handle to delete this subscription.

Errors

Under the following conditions, TPSUBSCRIBE() fails and sets TP-STATUS to one of the following values. (Unless otherwise noted, failure does not affect the caller's transaction, if one exists.)

[TPEINVAL]

Invalid arguments were given (for example, EVENT-EXPR is SPACES).

[TPENOENT]

Cannot access the BEA Tuxedo EventBroker.

[TPELIMIT]

The subscription failed because the EventBroker's maximum number of subscriptions has been reached.

[TPEMATCH]

The subscription failed because it matched one already listed with the EventBroker.

[TPEPERM]

The client is not attached as tpsysadm and the subscription action is either a service call or the enqueuing of a message.

[TPETIME]

This error code indicates that either a timeout has occurred or TPSUBSCRIBE() has been attempted, in spite of the fact that the current transaction is already marked rollback only.

If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout can occur only if both TPBLOCK and TPTIME are specified.)

If a transaction timeout has occurred, then, with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller's transaction (that is, TPACALL() with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set).

When a transactional ATMI call fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME.

[TPEBLOCK]

A blocking condition exists and TPNOBLOCK was specified.

[TPGOTSIG]

A signal was received and TPNOSIGRSTRT was specified.

[TPEPROTO]

TPSUBSCRIBE() was called improperly.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.