Use of the EventBroker requires the completion of several preparatory steps. The following flowchart lists these steps and indicates whether each step should be performed by an application administrator or programmer.

Figure 6-1 Preparatory Steps for using EventBroker

For instructions on any of these tasks, click on the appropriate box in the flowchart.

Note: A good way to learn how the EventBroker works is by running bankapp, the sample application delivered with the Oracle Tuxedo system. To find out how to copybankappand run it as a demo, see Tutorial for bankapp, a Full C Application in for Developing Oracle Tuxedo ATMI Applications.

A client accesses the EventBroker through either of two servers provided by the Oracle Tuxedo system: TMUSREVT(5), which handles application events, and TMSYSEVT(5), which handles system events. Both servers process events and trigger the sending of notification to subscribers.

To set up the Oracle Tuxedo EventBroker on your system, you must configure either or both of these servers in the SERVERS section of the UBBCONFIG file, as shown in the following example:

*SERVERS 
TMSYSEVT SRVGRP=ADMIN1 SRVID=100 RESTART=Y GRACE=900 MAXGEN=5 
CLOPT="-A --" 
TMSYSEVT SRVGRP=ADMIN2 SRVID=100 RESTART=Y GRACE=900 MAXGEN=5 
CLOPT="-A -- -S -p 90" 
TMUSREVT SRVGRP=ADMIN1 SRVID=100 RESTART=Y 
MAXGEN=5 GRACE=3600 
CLOPT="-A --" 
TMUSREVT SRVGRP=ADMIN2 SRVID=100 RESTART=Y 
MAXGEN=5 GRACE=3600
CLOPT="-A -- -S -p 120"

We recommend that you assign the principal server to the MASTER site, even though either server can reside anywhere on your network.

Periodically, the secondary server polls the primary server to obtain the current subscription list, which includes filtering and notification rules. By default, polling is done every 30 seconds. If necessary, however, you can specify a different interval.

You can configure the polling interval (represented in seconds) with the -p command-line option in TMUSREVT(5) or TMSYSEV(5) entries in the configuration file, as follows:

-p poll_seconds

It may appear that event messages are lost while subscriptions are being added and secondary servers are being updated.

As the administrator for your Oracle 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.

The following figure how clients and servers use the EventBroker to subscribe to events, to post events, and to unsubscribe to events.

Subscribing to an Event

Figure 6-2 Subscribing to an Event

• Identifying Event Categories Using eventexpr and filter
  
• Accessing the EventBroker
  

• Overview
  
• Dynamically Modifying the Event Configurations
  
• Interoperability
  

The EventBroker supports a variety of methods for notifying subscribers of events, as shown in the following figure.

Notification Methods Supported by the EventBroker

Figure 6-4 Notification Methods Supported by the EventBroker

Whichever notification method you choose, the procedure for implementing it is the same: in your call to tpsubscribe(), specify an argument that refers to a structure of type TPEVCTL.

If the value of the argument is NULL, the EventBroker sends an unsolicited message to the subscriber. Two of these methods, having the notification sent to a service and having it sent to a queue in stable storage, cannot be requested directly by a client. Instead, a client must invoke a service routine to subscribe on its behalf.

For each subscription, you can select any of the following notification methods. The EventBroker can:

• Notify the client—the EventBroker keeps track of events in which the client is interested and sends unsolicited notifications to the client when they occur. Some events are anonymously posted. A client can join an application, regardless of whether any other clients have subscribed, and post events to the EventBroker. The EventBroker matches these events against its database of subscriptions and sends an unsolicited notification to the appropriate clients. (See the definition of the T_EVENT_CLIENT class in the EVENT_MIB(5) entry in the File Formats, Data Descriptions, MIBs, and System Processes Reference.
• Invoke a service—if a subscriber wants event notifications to be sent to service calls, then the ctl parameter must point to a valid TPEVCTL structure. (See the definition of the T_EVENT_SERVICE class in the EVENT_MIB(5) entry in the File Formats, Data Descriptions, MIBs, and System Processes Reference.
• Enqueue messages to stable-storage queues—for subscriptions to stable-storage queues, a queue space, queue name, and correlation identifier are specified, in addition to values for eventexpr and filter, so that matching can be performed. The correlation identifier can be used to differentiate among several subscriptions characterized by the same event expression and filter rule, and destined for the same queue. (See the definition of the T_EVENT_QUEUE class in the EVENT_MIB(5) entry in the File Formats, Data Descriptions, MIBs, and System Processes Reference.
• Execute commands—using the T_EVENT_COMMAND class of the EVENT_MIB, subscribers can invoke an executable process. When a match is found, the data is used as the name of the executable process and any required options. (See the definition of the T_EVENT_COMMAND class in the EVENT_MIB(5) entry in the File Formats, Data Descriptions, MIBs, and System Processes Reference.
• Write messages to the user log (ULOG)—using the T_EVENT_USERLOG class of the EVENT_MIB, subscribers can write system USERLOG messages. When events are detected and matched, they are written to the USERLOG. (See the definition of the T_EVENT_USERLOG class in the EVENT_MIB(5) entry in the File Formats, Data Descriptions, MIBs, and System Processes Reference.

When a client leaves an application by calling tpterm(3c), all of its subscriptions are canceled unless the subscription is specified as persistent. (If persistent, the subscription continues to receive postings even after a client performs a tpterm().) If the client later rejoins the application and wants to renew those subscriptions, it must subscribe again.

A well-behaved client unsubscribes before calling tpterm(). This is accomplished by issuing a tpunsubscribe(3c) call before leaving an application.

Special handling is needed to use the EventBroker with transactions.

• Before you can use the EventBroker with transactions, you must configure the NULL_TMS parameter with the TMUSREVT(5) server for the server groups in which the EventBroker is running.
• The advantage of posting an event in a transaction is that all of the work, including work not related to the posting, is guaranteed to be complete if the transaction is successful. If any work performed within the transaction fails, it is guaranteed that all the work done within the transaction will be rolled back. The disadvantage is that the poster takes a risk that something may cause the transaction to be aborted, and the posting will be lost.
• To specify that a subscription is part of a transaction, use the TPEVTRAN flag with tpsubscribe(3c). If the subscription is made transactionally, the action taken in response to an event will be part of the caller’s transaction.

  Note:

  This method can be used only for subscriptions that cause an Oracle Tuxedo service to be invoked, or that cause a record to be enqueued on a permanent queue.

• How Transactions Work with the EventBroker