This topic includes the following sections:
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.
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 BEA Tuxedo system. To find out how to copy bankapp and run it as a demo, see Tu,torial for bankapp, a Full C Application in Tutorials for Developing BEA Tuxedo ATMI Applications. |
A client accesses the EventBroker through either of two servers provided by the BEA 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 BEA 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.
Note: | You can reduce the network traffic caused by event postings and notifications by assigning secondary servers to other machines in 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 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.
The following figure shows how clients and servers use the EventBroker to subscribe to events, to post events, and to unsubscribe to events.
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.
Your application can access the EventBroker through either the ATMI or the EVENT_MIB(5). The following table describes both methods.
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. |
The EventBroker supports a variety of methods for notifying subscribers of events, as shown in the following diagram.
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:
T_EVENT_CLIENT
class in the EVENT_MIB(5) entry in the File Formats, Data Descriptions, MIBs, and System Processes Reference.)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.)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.)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.)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.
NULL_TMS
parameter with the TMUSREVT(5) server for the server groups in which the EventBroker is running.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 a BEA Tuxedo service to be invoked, or that cause a record to be enqueued on a permanent queue. |
If both a poster and a subscriber agree to link their transactions, they create a form of voting. The poster makes an assertion that something is true and infects the message with this transaction. (In other words, the message that leaves the originating process is marked as being associated with the transaction.) The transaction goes to the EventBroker.
The EventBroker's actions, such as calling the service or putting a message in the queue for the subscriber, are also part of the same transaction. If a service routine that is running encounters an error, it can fail the transaction, rolling back everything, including all other transactional subscriptions and the poster's original transaction, which might have invoked other services and performed other database work. The poster makes an assertion ("I'm about to do this"), provides data, and links the data to its transaction.
A number of anonymous subscribers, that is, subscribers about which the poster knows nothing, are invoked transactionally. If any subscriber fails to link its work with the poster's work, the whole transaction is rolled back. All transactional subscribers must agree to link their work with the poster's work, or all the work is rolled back. If a poster has not allowed the posting to participate in its transaction, the EventBroker starts a separate transaction, and gathers all the transactional subscriptions into that transaction. If any of these transactions fail, all the work done on behalf of the transactional subscriptions is rolled back, but the poster's transaction is not rolled back. This process is controlled by the TPEVTRAN
flag.
A stock trade is about to be completed by a brokerage application. A number of database records have been updated by various services during the trade transaction. A posting states that the trade is about to happen.
An application responsible for maintaining an audit trail of such trades has subscribed to this event. Specifically, the application has requested the placement of a record in a specified queue whenever an event of this type is posted. A service routine responsible for determining whether trades can be performed, also subscribes to this type of event; it, too, is notified whenever such a trade is proposed.
If all goes well, the trade is completed and an audit trail is made.
If an error occurs in the queue and no audit trail can be made, the entire stock trade is rolled back. Similarly, if the service routine fails, the transaction is rolled back. If all is successful, the trade is made and the transaction is committed.