Subscribing to Events

A subscriber can be notified through an unsolicited notification message, a service call, a reliable queue, or other notification methods configured by the application administrator. (For information about configuring alternative notification methods, refer to Setting Up a BEA Tuxedo Application.)

Use the following signature to call the tpsubscribe() function:

long handle
tpsubscribe (char *eventexpr, char *filter, TPEVCTL *ctl, long flags)

The following table describes the arguments to the tpsubscribe() function.

tpsubscribe( ) Function Arguments

Argument	Description
eventexpr	Pointer to a set of one or more events to which a process can subscribe. Consists of a NULL-terminated string of up to 255 characters containing a regular expression. Regular expressions are of the form specified in tpsubscribe(3c), as described in the BEA Tuxedo ATMI C Function Reference). For example, if eventexpr is set to: "\\..*"—the caller is subscribing to all system-defined events. "\\.SysServer.*"—the caller is subscribing to all system-defined events related to servers. "[A-Z].*"—the caller is subscribing to all user events starting with any uppercase letter between A and Z. ".*(ERR|err).*"—the caller is subscribing to all user events with names that contain either err or ERR, such as the account_error and ERROR_STATE events, respectively.
filter	Pointer to 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 specified; otherwise, the EventBroker ignores the notification method. The caller can subscribe to the same event multiple times with different filter rules. By using the event-filtering capability, subscribers can discriminate among the events about which they are notified. For example, a poster can post an event for withdrawals greater than $10,000, but a subscriber may want to specify a higher threshold for being notified, such as $50,000. Or, a subscriber may want to be notified of large withdrawals made by specific customers. Filter rules are specific to the typed buffers to which they are applied. For more information on filter rules, refer to tpsubscribe(3c) in the BEA Tuxedo ATMI C Function Reference.
ctl	Pointer to a flag for controlling how a subscriber is notified of an event. Valid values include: NULL—sends unsolicited messages. Refer to Notification via Unsolicited Message for more information. Pointer to a valid TPEVCTL structure—sends information based on the TPEVCTL structure. Refer to Notification via Service Call or Reliable Queue for more information.
flags	Flag options. For more information on available flag options, refer to tpsubscribe(3c) in the BEA Tuxedo ATMI C Function Reference.

For purposes of subscriptions (and for MIB updates), service routines executed in a BEA Tuxedo system server process are considered to be trusted code.

Notification via Unsolicited Message

If a subscriber is a BEA Tuxedo system client process and ctl is NULL, when the event to which the client has subscribed is posted, the EventBroker sends an unsolicited message to the subscriber as follows. When an event name is posted that evaluates successfully against eventexpr, the EventBroker tests the posted data against the associated filter rule. 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.

Notification via Service Call or Reliable Queue

Event notification via service call enables you to program actions that can be taken in response to specific conditions in your application without human intervention. Event notification via reliable queue ensures that event data is not lost. It also provides the subscriber the flexibility of retrieving the event data at any time.

If the subscriber (either a client or a server process) wants event notifications sent to service routines or to stable-storage queues, then the ctl parameter of tpsubscribe() must point to a valid TPEVCTL structure.

The TPEVCTL structure contains the following elements:

long   flags;
char   name1[32];
char   name2[32];
TPQCTL qctl;

The following table summarizes the TPEVCTL typed buffer data structure.

TPEVCTL Typed Buffer Format

Field	Description
flags	Flag options. For more information on flags, refer to tpsubscribe(3c) in the BEA Tuxedo ATMI C Function Reference.
name1	Character string of 32 characters or fewer.
name2	Character string of 32 characters or fewer.
qctl	TPQCTL structure. For more information, refer to tpsubscribe(3c) in the BEA Tuxedo ATMI C Function Reference.