|
|
 |
| e-docs > Tuxedo > ATMI C Function Reference > Section 3c - C Functions |
|
ATMI C Function Reference
|
Name
tpsubscribe()—Subscribes 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 BEA Tuxedo ATMI EventBroker, 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 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 "\e\e..*", the caller is subscribing to all system-generated events; if eventexpr is "\e\e.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 in the event name. Events called account_error and ERROR_STATE, for example, would both qualify. For more information on regular expressions, see Regular Expressions.
If present, filter 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 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 compiler (see Fboolco(3fml) and Fvboolco(3fml), respectively) and evaluated against the posted buffer (see Fboolev(3fml) and Fvboolev(3fml), respectively). For STRING buffers, the filter rule is a regular expression. All other buffer types require customized filter evaluators (see buffer(3c) 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 BEA Tuxedo ATMI system client process and ctl is NULL, 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 eventexpr, the EventBroker 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()) an unsolicited message handling routine. If a BEA Tuxedo ATMI 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 EventBroker's list of active subscriptions before exiting (see tpunsubscribe(3c) 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 EventBroker 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
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 tperrno to TPEMATCH. For a subscription to match an existing one, both eventexpr and 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 the subscriber is a BEA Tuxedo ATMI 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 EventBroker.
If the caller has set ctl
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
The following is a list of valid flags for tpsubscribe():
In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpsubscribe().
Regular Expressions
The regular expressions described in Table 12 are much like those used in the UNIX system editor, ed(1). The alternation operator, (|), has been added along with some other practical things. In general, however, there should be few surprises.
Regular expressions (REs) are constructed by applying any of the following production rules one or more times.
There are three levels of precedence. In order of decreasing binding strength they are:
As indicated above, parentheses are used to give explicit precedence.
Return Values
Upon successful completion, tpsubscribe() returns a handle that can be used to remove this subscription from the EventBroker's list of active subscriptions. The subscriber or any other process is allowed to use the returned handle to delete this subscription.
Upon failure, tpsubscribe() returns -1 and sets tperrno to indicate the error condition.
Errors
Upon failure, tpsubscribe() sets tperrno to one of the following values. (Unless otherwise noted, failure does not affect the caller's transaction, if one exists.)
See Also
buffer(3c), tpenqueue(3c), tppost(3c), tpsetunsol(3c), tpunsubscribe(3c), Fboolco, Fboolco32, Fvboolco, Fvboolco32(3fml), Fboolev, Fboolev32, Fvboolev, Fvboolev32(3fml), EVENTS(5), EVENT_MIB(5), TMSYSEVT(5), TMUSREVT(5), tuxtypes(5), typesw(5), UBBCONFIG(5)
|
|
|
|
||
 |
|
|
 |
 |
 |
|
||
