PURPOSE

tpsubscribe - subscribe to an event

SYNOPSIS


#include <atmi.h>
long tpsubscribe(char *eventexpr, char *filter, TPEVCTL *ctl, long flags)

DESCRIPTION

The caller uses tpsubscribe to subscribe to an event or set of events named by eventexpr. Subscriptions are maintained by the TUXEDO System Event Broker, TMUSREVT(5), and are used to notify subscribers when events are posted via tppost(3c). 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 arguments passed to tpsubscribe.

The event or set of events being subscribed to is named by eventexpr, a NULL-terminated string of at most 255 characters containing a regular expression. For example, if eventexpr is "\\..*", the caller is subscribing to all system-generated events; if eventexpr is "\\.SysServer.*", the caller is subscribing to all system-generated events related to servers. If eventexpr is "[A-Z].*", the caller is subscribing to all user events starting with A-Z; if eventexpr 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).

If present, filter is a string containing a boolean filter rule associated with eventexpr 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 eventexpr; 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 buffers to which they are applied. For FML and view buffers, the filter rule is a string that can be passed to each's boolean expression complier (see Fboolco(3fml) and Fvboolco(3), respectively) and evaluated against the posted buffer (see Fboolev(3fml) and Fvboolev(3), respectively). For STRING buffers, the filter rule is a regular expression. All other buffer types require customized filter evaluators (see buffer(3) and typesw(5) for details on adding customized filter evaluators). filter is a NULL-terminated string of at most 255 characters.

If the subscriber is a TUXEDO System client process and ctl is NULL, 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 eventexpr, the event broker tests the posted data against the filter rule associated with eventexpr. 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(3c)) an unsolicited message handling routine. If a TUXEDO System server process calls tpsubscribe with a NULL ctl parameter, then tpsubscribe fails setting tperrno 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(3c) for details). Using tpunsubscribe's wild-card 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.

If the subscriber (regardless of process type) wants event notifications to go to service routines or to stable-storage queues, then the ctl parameter must point to a valid TPEVCTL structure. This structure contains the following elements: long flags; char name1[32]; char name2[32]; TPQCTL qctl;The following is a list of valid bits for the ctl->flags element controlling options for event subscriptions.

TPEVSERVICE

Setting this flag bit indicates that the subscriber wants event notifications to be sent to the TUXEDO System service routine named in ctl->name1. That is, when an event name is posted that evaluates successfully against eventexpr, the event broker tests the posted data against the filter rule associated with eventexpr. If the data passes the filter rule or if there is no filter rule for the event, then a service request is sent to ctl->name1 along with any data posted with the event. The service name in ctl->name1 can be any valid TUXEDO System service name and it may or may not be active at the time the subscription is made. It may not begin with "..". Service routines invoked by the event broker should return with no reply data. That is, they should call tpreturn(3c) with a NULL data argument. Any data passed to tpreturn(3c) will be dropped. TPEVSERVICE and TPEVQUEUE are mutually exclusive flags.

If TPEVTRAN is also set in ctl->flags, then if the process calling tppost(3c) 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 TPEVTRAN is not set in ctl->flags, then the event broker calls the subscribed service routine such that it will not be part of the poster's transaction.

TPEVQUEUE

Setting this flag bit indicates that the subscriber wants event notifications to be enqueued to the queue space named in ctl->name1 and the queue named in ctl->name2. That is, when an event name is posted that evaluates successfully against eventexpr, the event broker tests the posted data against the filter rule associated with eventexpr. 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 in ctl->name1 and the queue named in ctl->name2 along with any data posted with the event. The queue space and queue name can be any valid TUXEDO System queue space and queue name, either of which may or may not exist at the time the subscription is made.

ctl->qctl can contain options further directing the event broker's enqueuing of the posted event. If no options are specified, then ctl->qctl.flags should be set to TPNOFLAGS. Otherwise, options can be set as described in the "Control Parameter" subsection of the tpenqueue(3c) manual page (specifically, see the section describing the valid list of flags controlling input information for tpenqueue(3c)). TPEVSERVICE and TPEVQUEUE are mutually exclusive flags.

If TPEVTRAN is also set in ctl->flags, then if the process calling tppost(3c) 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 TPEVTRAN is not set in ctl->flags, then the event broker enqueues the posted event and its data such that it will not be part of the poster's transaction.

TPEVTRAN

Setting this flag bit indicates that the subscriber wants the event notification for this subscription to be included in the poster's transaction, if one exists. If this flag bit is not set, then any events posted for this subscription will not be done on behalf of any transaction in which the poster is participating. This flag can be used with either TPEVSERVICE or TPEVQUEUE.

TPEVPERSIST

By default, the 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 this flag bit indicates that the subscriber wants this subscription to persist across such errors (usually because the resource will become available again in the future). When this flag bit is not used, the event broker will remove this subscription if it encounters an error accessing either the service name or queue space/queue name designated in this subscription.

If this flag bit 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 tperrno to TPEMATCH. For a subscription to match an existing one, both eventexpr and 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 the subscriber is a TUXEDO System client process and ctl is NULL (such that the caller receives unsolicited notifications when events are posted), then its system-defined client identifier (known as a CLIENTID) is also used to detect matches. That is, tpsubscribe fails if eventexpr, filter, and the caller's CLIENTID match those of a subscription already known to the event broker.

If the caller has set ctl->flags to TPEVSERVICE, then tpsubscribe fails if eventexpr, filter, and the service name set in ctl->name1 match those of a subscription already known to the event broker.

For subscriptions to stable-storage queues, the queue space, queue name, and correlation identifier are used, in addition to eventexpr and 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 ctl->flags to TPEVQUEUE, and TPQCOORID is not set in ctl->qctl.flags, then tpsubscribe fails if eventexpr, filter, the queue space name set in ctl->name1, and the queue name set in ctl->name2 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 in ctl->qctl.flags, then tpsubscribe fails if eventexpr, filter, ctl->name1, ctl->name2, and ctl->qctl.corrid match those of a subscription (which has the same correlation identifier specified) already known to the event broker.

Following is a list of valid flags for tpsubscribe:

TPNOBLOCK: The subscription is not made if a blocking condition exists. If such a condition occurs, the call fails and tperrno is set to TPEBLOCK. When TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout).
TPNOTIME: This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
TPSIGRSTRT: If a signal interrupts any underlying system calls, then the interrupted system call is re-issued. When TPSIGRSTRT is not specified and a signal interrupts a system call, then tpsubscribe fails and tperrno is set to TPGOTSIG.

Upon successful completion, tpsubscribe returns a handle that can be used to remove this subscription from the event broker's list of active subscriptions. Otherwise the function returns -1 and sets tperrno to indicate the error condition. 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 tperrno 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, eventexpr is NULL).
[TPENOENT]: Cannot access the TUXEDO System Event Broker.
[TPELIMIT]: The subscription failed because the event broker's maximum number of subscriptions has been reached.
[TPEMATCH]: The subscription failed because it matched one already listed with the event broker.
[TPETIME]: A timeout occurred. If the caller is in transaction mode, then a transaction timeout occurred and the transaction is to be aborted; otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME were specified. If a transaction timeout occurred, any attempts to do new work will fail with TPETIME until the transaction has been aborted.
[TPEBLOCK]: A blocking condition exists and TPNOBLOCK was specified.
[TPGOTSIG]: A signal was received and TPSIGRSTRT was not specified.
[TPEPROTO]: tpsubscribe was called in an improper context.
[TPESYSTEM]: A System/T error has occurred. The exact nature of the error is written to a log file.
[TPEOS]: An operating system error has occurred.

PURPOSE

SYNOPSIS

DESCRIPTION

ERRORS

SEE ALSO