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 copy bankapp and run it as a demo, see “Tu,torial for bankapp, a Full C Application” in Tutorials 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.We recommend that you assign the principal server to the MASTER site, even though either server can reside anywhere on your network.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_secondsAs 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.Figure 6‑1 shows how clients and servers use the EventBroker to subscribe to events, to post events, and to unsubscribe to events.Figure 6‑1 Subscribing to an EventClients 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.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: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). Table 6‑1 describes both methods.
Table 6‑1 Accessing the EventBroker 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. 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(). 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(). 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 the Oracle Tuxedo ATMI COBOL Function Reference for details.The EventBroker supports a variety of methods for notifying subscribers of events, as shown in Figure 6‑2.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.
• 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.
• 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.
• 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.
•
•
•
• TPPOST(3cbl), TPSUBSCRIBE(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