6 Subscribing to Events
This topic includes the following sections:
- Process of Using the EventBroker
- How to Configure EventBroker Servers
- How to Set the Polling Interval
- Subscribing, Posting, and Unsubscribing to Events with the ATMI and the EVENT_MIB
- Subscribing, Posting, and Unsubscribing to Events Across Domains
- How to Select a Notification Method
- How to Cancel a Subscription to an Event
- How to Use the EventBroker with Transactions
6.1 Process of Using the EventBroker
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
![Preparatory Steps for using EventBroker Preparatory Steps for using EventBroker](img/evproc.gif)
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.
Parent topic: Subscribing to Events
6.2 How to Configure EventBroker Servers
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.
Note:
You can reduce the network traffic caused by event postings and notifications by assigning secondary servers to other machines in your network.Parent topic: Subscribing to Events
6.3 How to Set the Polling Interval
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.
Parent topic: Subscribing to Events
6.4 Subscribing, Posting, and Unsubscribing to Events with the ATMI and the EVENT_MIB
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
![Subscribing to an Event Subscribing to an Event](img/event1_1.gif)
Parent topic: Subscribing to Events
6.4.1 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 Oracle 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.
6.4.2 Accessing the EventBroker
Your application can access the EventBroker through either the ATMI or the (EVENT_MIB(5).
The following table describes both the methods.
Accessing the EventBroker
Table 6-1 Accessing the EventBroker
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 Oracle 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 Oracle 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 Oracle 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 Oracle 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 Oracle Tuxedo ATMI C Function Reference and Oracle Tuxedo ATMI COBOL Function Reference.6.5 Subscribing, Posting, and Unsubscribing to Events Across Domains
Parent topic: Subscribing to Events
6.5.1 Overview
Tuxedo is now equipped to subscribe, post, and unsubscribe brokered events in cross domain environment.
To realize such feature, two new sections,
DM_EVT_IN
and DM_EVT_OUT
, are added to
DMCONFIG
to manage static event in/out
information.
For details of DM_EVT_IN
and DM_EVT_OUT
, see DMCONFIG(5) in Tuxedo Reference Guide.
Note:
InUBBCONFIG
, the EvtBroker
server should be configured prior to the GWT
server as GWT
will subscribe the configured events to the EvtBroker when starting up.
6.5.1.1 How to Process Brokered Events Crossing Domains
The image below illustrates a typical processing flow of subscribing, posting, and unsubscribing a brokered event in cross domain environment.
Cross Domain Event Overall Flow
Figure 6-3 Cross Domain Event Overall Flow
![Cross Domain Event Overall Flow Cross Domain Event Overall Flow](img/adsevt-06.1.3.jpg)
Parent topic: Overview
6.5.1.2 How to Configure DMCONFIG — Case Study
This use case elaborates how to get DMCONFIG
well configured.
As shown on Figure 6-3, two clients (Client A and Client B) are located in two domains (Domain A and Domain B), each has one machine within SHM mode (Machine A and Machine B).
For machine A, use dmloadcf
to create new BDMCONFIG
with
additional configurations in DMCONFIG
as below, and then tmboot Tuxedo.
*DM_EVT_IN
MACHINEB_EVT
LACCESSPOINT=DOMAINA
*DM_EVT_OUTMACHINEA_EVT
LACCESSPOINT= DOMAINA
RACCESSPOINT= DOMAINB
For machine B, use dmloadcf
to create new BDMCONFIG
with
additional configurations in DMCONFIG
as below, and then tmboot Tuxedo.
*DM_EVT_IN MACHINEA_EVT /> LACCESSPOINT=DOMAINB
*DM_EVT_OUT
MACHINEB_EVT
LACCESSPOINT= DOMAINB
RACCESSPOINT= DOMAINA
After configuring as above, take a two-step test as below by two clients.
- Client B issues
tpsubscribe
(“MACHINEA_EVT
”) on Machine B; - Client A issues
tppost
(“MACHINEA_EVT
”) on Machine A.
Result: Client B will receive the event MACHINEA_EVT
if DMCONFIG
is configured correctly.
In cross domain environment, all events should be explicitly imported or exported — requests for an unknown domain will not be accepted. Once configured correctly, GWT
server will automatically subscribe every configured event to the local Event Broker when Tuxedo starts up. When receiving a remote event message, local GWT
will forward this request to Event Broker. On the other side, when a local event is posted, the Event Broker will forward this event to the local GWT
which has subscribed such event. After that, the local GWT
will forward this event to the configured remote domain’s GWT
.
Parent topic: Overview
6.5.2 Dynamically Modifying the Event Configurations
Besides allowing users to set up static configurations as above, Tuxedo provides two administration methods to dynamically modify the event configurations as needed without shutting the system down: dmadmin command and MIB
operations.
For “dmadmin
” command, two sub-commands (“advertiseevent
” and “unadvertiseevent
”) and two sections (“EVENTS_IN
” and “EVENTS_OUT
”) are added to support the modification of event configurations dynamically. Related classes are added in MIB operations.
For detailed information, see dmadmin(1) in Tuxedo Command Reference, and DM_MIB(5) in Tuxedo Reference Guide.
6.6 How to Select a Notification Method
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
![Notification Methods Supported by the EventBroker Notification Methods Supported by the EventBroker](img/event.gif)
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 validTPEVCTL
structure. (See the definition of theT_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
andfilter
, 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 theT_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 theEVENT_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 theT_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 theEVENT_MIB
, subscribers can write systemUSERLOG
messages. When events are detected and matched, they are written to theUSERLOG
. (See the definition of theT_EVENT_USERLOG
class in the EVENT_MIB(5) entry in the File Formats, Data Descriptions, MIBs, and System Processes Reference.
Parent topic: Subscribing to Events
6.7 How to Cancel a Subscription to an Event
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.
Parent topic: Subscribing to Events
6.8 How to Use the EventBroker with Transactions
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.
6.8.1 How Transactions Work with the EventBroker
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.
Parent topic: How to Use the EventBroker with Transactions
6.8.1.1 Example of Using the EventBroker with Transactions
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.
See Also
- What Is an Event?
- Managing Events Using EventBroker
- Using Event-based Communication in Tutorials for Developing Oracle Tuxedo ATMI Applications
- tppost(3c), tpsubscribe(3c), and tpunsubscribe(3c) in the Oracle Tuxedo ATMI C Function Reference
- TPPOST(3cbl), TPUNSUBSCRIBE(3cbl), and TPUNSUBSCRIBE(3cbl)in the Oracle Tuxedo ATMI COBOL Function Reference
- EVENT_MIB(5), EVENTS(5), TMSYSEVT(5), and TMUSREVT(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference
Parent topic: How Transactions Work with the EventBroker