Subscribing, Posting, and Unsubscribing to Events with the ATMI and the EVENT


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| Administering a BEA Tuxedo Application at Run Time \| Local Topics \| Previous Topic \| Next Topic \| Contents

Subscribing, Posting, and Unsubscribing to Events with the ATMI and the EVENT_MIB

As the administrator for your BEA Tuxedo application, you can enter subscription requests on behalf of a client or server process through calls to the T_EVENT_COMMAND class of the EVENT_MIB(5). You can also use invoke the tpsubscribe(3c) function to subscribe, programmatically, to an event.

Identifying Event Categories Using eventexpr and filter

Clients or servers can subscribe to events by calling tpsubscribe(3c). The tpsubscribe() function takes one required argument: eventexpr. The value of eventexpr can be a wildcard string that identifies the set of event names about which the user wants to be notified. Wildcard strings are described on the tpsubscribe(3c) reference page in the BEA Tuxedo ATMI C Function Reference.

As an example, a user on a UNIX system platform who wants to be notified of all events related to the category of networking can specify the following value of eventexpr:

\.SysNetwork.*

The backslash preceding the period (.) indicates that the period is literal. (Without the preceding backslash, the period (.) would match any character except the end-of-line character.) The combination .* at the end of \.SysNetwork.* matches zero or more occurrences of any character except the end-of-line character.

In addition, clients or servers can filter event data by specifying the optional filter argument when calling tpsubscribe(). The value of filter is a string containing a Boolean filter rule that must be evaluated successfully before the EventBroker posts the event.

As an example, a user who wants to be notified only about system events having a severity level of ERROR can specify the following value of filter:

"TA_EVENT_SEVERITY='ERROR'"

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, the subscriber receives a notification along with any data posted with the event.

Accessing the EventBroker

Your application can access the EventBroker through either the ATMI or the EVENT_MIB(5). The following table describes both methods.

Method	Function	Purpose
ATMI	tppost(3c)	Notifies the EventBroker, or posts an event and any accompanying data. The event is named by the eventname argument and the data argument, if not NULL, points to the data. The posted event and data are dispatched by the BEA Tuxedo EventBroker to all subscribers with subscriptions that successfully evaluate against eventname and optional filter rules that successfully evaluate against data.
	tpsubscribe(3c)	Subscribes to an event or a set of events named by eventexpr. Subscriptions are maintained by the BEA Tuxedo EventBroker, and are used to notify subscribers when events are posted via tppost(). Each subscription specifies one of the following notification methods: client notification, service calls, message enqueuing to stable-storage queues, executing of commands, and writing to the user log. Notification methods are determined by the subscriber's process type (that is, whether the process is a client or a server) and the arguments passed to tpsubscribe().
	tpunsubscribe(3c)	Removes an event subscription or a set of event subscriptions from the BEA Tuxedo EventBroker's list of active subscriptions. subscription is an event subscription handle returned by tpsubscribe(). Setting subscription to the wildcard value, -1, directs tpunsubscribe to unsubscribe to all nonpersistent subscriptions previously made by the calling process. Nonpersistent subscriptions are those made without the TPEVPERSIST bit setting in the ctl->flags parameter of tpsubscribe(). Persistent subscriptions can be deleted only by using the handle returned by tpsubscribe().
EVENT_MIB(5)	N/A	The EVENT_MIB is a management information base (MIB) that stores subscription information and filtering rules. In your own application, you cannot define new events for the BEA Tuxedo EventBroker using EVENT_MIB, but you can customize the EventBroker to track events and notify subscribers of occurrences of special interest to the application. You can use the EVENT_MIB to subscribe to an event, or to modify or cancel a subscription.

Note: tppost(3c), tpsubscribe(3c), and tpunsubscribe(3c) are C functions. Equivalent routines (TPPOST(3cbl), TPSUBSCRIBE(3cbl), and TPUNSUBSCRIBE(3cbl)) are provided for COBOL programmers. See the BEA Tuxedo ATMI C Function Reference and the BEA Tuxedo ATMI COBOL Function Reference for details.