TPSUBSCRIBE-subscribe to an event
01TPEVTDEF-REC.
COPY TPEVTDEF.
01TPQUEDEF-REC.
COPY TPQUEDEF.
01TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPSUBSCRIBE" USINGTPEVTDEF-RECTPQUEDEF-RECTPSTATUS-REC.
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 System Event Broker, TMUSREVT(5), 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 recomp(3). 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" (for example, "account_error" and "ERROR_STATE" events would both qualify).
EVENT-FILTER in TPEVTDEF-REC is a string containing a boolean filter rule associated with EVENT-EXPR that must be evaluated successfully before the event broker posts the event. Upon receiving an event to be posted, the event broker applies the filter rule, if one exists, to the posted event's data. If the data passes the filter rule, the event broker invokes the notification method associated with EVENT-EXPR; 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's boolean expression complier (see Fboolco(3) and Fvboolco(3), respectively) and evaluated against the posted record (see Fboolev(3) and Fvboolev(3), respectively). For STRING records, the filter rule is a regular expression of the form specified in recomp(3). All other record types require customized filter evaluators (see buffer(3) 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 system client process and TPEVNOTIFY in TPEVTDEF-REC is set, then the event broker 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 event broker 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 system 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 event broker's list of active subscriptions before exiting (see TPUNSUBSCRIBE() for details). Using TPUNSUBSCRIBE'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 event broker 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 system service routine named by NAME-1 in TPEVTDEF-REC. That is, when an event name is posted that evaluates successfully against EVENT-EXPR, the event broker 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 system service name and it may or may not be active at the time the subscription is made. Service routines invoked by the event broker 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 event broker calls the subscribed service routine such that it will be part of the poster's transaction. Both the event broker, TMUSREVT(5), and the subscribed service routine must belong to server groups that support transactions (see ubbconfig(5) for details). If TPEVNOTRAN is set, then the event broker 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 event broker 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 event broker 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 system 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 event broker'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 event broker enqueues the posted event and its data such that it will be part of the poster's transaction. The event broker, TMUSREVT(5), must belong to a server group that supports transactions (see ubbconfig(5) for details). If TPEVNOTRAN is set, then the event broker enqueues the posted event and its data such that it will not be part of the poster's transaction.
By default, the BEA TUXEDO System Event Broker deletes subscriptions when the resource to which it is posting is not available (for example, the event broker 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 event broker 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 event broker 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 event broker'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 event broker'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 event broker.
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 event broker.
If TPEVQUEUE is set, then event broker 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 event broker. 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 event broker.
Following is a list of settings in TPEVTDEF-REC.
TPNOBLOCK
TP-STATUS to [TPEBLOCK]. Either TPNOBLOCK or TPBLOCK must be set.
TPBLOCK
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
TPNOTIME or TPTIME must be set.
TPTIME
TPNOTIME or TPTIME must be set.
TPSIGRSTRT
TPNOSIGRSTRT or TPSIGRSTRT must be set.
TPNOSIGRSTRT
TP-STATUS to [TPGOTSIG]. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.
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 event broker's list of active subscriptions. Either the subscriber or any other process is allowed to use the returned handle to delete this subscription.
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]
EVENT-EXPR is SPACES).
TPENOENT]
TPELIMIT]
TPEMATCH]
TPETIME]
TPBLOCK and TPTIME were specified. If a transaction timeout occurred, any attempts to do new work will fail with [TPETIME] until the transaction has been aborted.
TPEBLOCK]
TPNOBLOCK was specified.
TPGOTSIG]
TPNOSIGRSTRT was specified.
TPEPROTO]
TPSUBSCRIBE was called in an improper context.
TPESYSTEM]
TPEOS]
buffer(3), EVENTS(5), EVENT_MIB(5), Fboolco(3), Fboolev(3), Fvboolco(3), Fvboolev(3), recomp(3), TMSYSEVT(5), TMUSREVT(5), TPENQUEUE(), TPPOST(), TPSETUNSOL(), TPUNSUBSCRIBE(), tuxtypes(5), typesw(5), ubbconfig(5)