The EventBroker is an Oracle Tuxedo subsystem that receives and filters event posting messages, and distributes them to subscribers. A poster is an Oracle Tuxedo system process that detects when a specific event has occurred and reports (posts) it to the EventBroker. A subscriber is an Oracle Tuxedo system process with a standing request to be notified whenever a specific event has been posted.The EventBroker may be configured such that whenever an event is posted, the EventBroker invokes one or more notification actions for clients and/or servers that have subscribed. Table 8‑1 lists the types of notification actions that the EventBroker can take.
Table 8‑1 EventBroker Notification Actions Event notification messages may be stored in an Oracle Tuxedo system reliable queue, using the tpenqueue(3c) function. Event notification buffers are stored until requests for buffer contents are issued. An Oracle Tuxedo system client or server process may call the tpdequeue(3c) function to retrieve these notification buffers, or alternately TMQFORWARD(5) may be configured to automatically dispatch an Oracle Tuxedo system service routine that retrieves a notification buffer.For more information on /Q, see Using the ATMI /Q Component.In addition, the application administrator may create an EVENT_MIB(5) entry (by using the Oracle Tuxedo administrative API) that performs the following notification actions:For information on the EVENT_MIB(5), refer to the File Formats, Data Descriptions, MIBs, and System Processes Reference.TMUSREVT is the Oracle Tuxedo system-supplied server that acts as an EventBroker for user events. TMUSREVT processes event report message buffers, and then filters and distributes them. The Oracle Tuxedo application administrator must boot one or more of these servers to activate event brokering.TMSYSEVT is the Oracle Tuxedo system-supplied server that acts as an EventBroker for system-defined events. TMSYSEVT and TMUSREVT are similar, but separate servers are provided to allow the application administrator the ability to have different replication strategies for processing notifications of these two types of events. Refer to Setting Up an Oracle Tuxedo Application for additional information.The Oracle Tuxedo system itself detects and posts certain predefined events related to system warnings and failures. These tasks are performed by the EventBroker. For example, system-defined events include configuration changes, state changes, connection failures, and machine partitioning. For a complete list of system-defined events detected by the EventBroker, see EVENTS(5) in the File Formats, Data Descriptions, MIBs, and System Processes Reference.
1. A client or server posts a buffer to an application-defined event name.
2. The posted buffer is transmitted to any number of processes that have subscribed to the event.To define the unsolicited message handler function, use the tpsetunsol(3c) function with the following signature:int
tpsetunsol(*myfunc)The _TMDLLENTRY macro is required for Windows-based operating systems to obtain the proper calling conventions between the Tuxedo libraries and your code.On Unix systems, the _TMDLLENTRY macro is not required because it expands to the null string.Table 8‑2 describes the single argument that can be passed to the tpsetunsol() function.
Table 8‑2 tpsetunsol( ) Function Argument
• data—points to the typed buffer that contains the unsolicited message
• len—length of the buffer
• flags—currently not usedUnsolicited messages can be sent to client processes by name, using tpbroadcast(3c), or by an identifier received with a previously processed message, using tpnotify(3c). Messages sent via tpbroadcast() can originate either in a service or in another client. Messages sent via tpnotify() can originate only in a service.The tpbroadcast(3c) function allows a message to be sent to registered clients of the application. It can be called by a service or another client. Registered clients are those that have successfully made a call to tpinit() and have not yet made a call to tpterm().int
tpbroadcast(char *lmid, char *usrname, char *cltname, char *data, long len, long flags)Table 8‑3 describes the arguments to the tpbroadcast() function.
Table 8‑3 tpbroadcast( ) Function Arguments Size of the message buffer. If data points to a self-defining buffer type, for example, FML, then len can be set to 0. Flag options. Refer to tpbroadcast(3c) in the Oracle Tuxedo ATMI C Function Reference for information on available flags.Listing 8‑1 illustrates a call to tpbroadcast() for which all clients are targeted. The message to be sent is contained in a STRING buffer.Listing 8‑1 Using tpbroadcast( )char *strbuf;
if ((strbuf = tpalloc("STRING", NULL, 0)) == NULL) {
error routine
}
(void) strcpy(strbuf, "hello, world");
if (tpbroadcast(NULL, NULL, NULL, strbuf, 0, TPSIGRSTRT) == -1)
error routineThe tpnotify(3c) function is used to broadcast a message using an identifier received with a previously processed message. It can be called only from a service.int
tpnotify(CLIENTID *clientid, char *data, long len, long flags)Table 8‑4 describes the arguments to the tpnotify() function.
Table 8‑4 tpnotify( ) Function Arguments Pointer to a CLIENTID structure that is saved from the TPSVCINFO structure that accompanied the request to this service. Size of the message buffer. If data points to a self-defining buffer type, for example, FML, then len can be set to 0. Flag options. Refer to tpnotify(3c) in the Oracle Tuxedo ATMI C Function Reference for information on available flags.To check for unsolicited messages while running the client in “dip-in” notification mode, use the tpchkunsol(3c) function with the following signature:If any messages are pending, the system invokes the unsolicited message handling function that was specified using tpsetunsol(). Upon completion, the function returns either the number of unsolicited messages that were processed or -1 on error.If you issue this function when the client is running in SIGNAL-based, thread-based notification mode, or is ignoring unsolicited messages, the function has no impact and returns immediately.The tpsubscribe(3c) function enables an Oracle Tuxedo system ATMI client or server to subscribe to an event.A subscriber can be notified through an unsolicited notification message, a service call, a reliable queue, or other notification methods configured by the application administrator. (For information about configuring alternative notification methods, refer to Setting Up an Oracle Tuxedo Application.)Use the following signature to call the tpsubscribe() function:Table 8‑5 describes the arguments to the tpsubscribe() function.
Table 8‑5 tpsubscribe( ) Function Arguments Pointer to a set of one or more events to which a process can subscribe. Consists of a NULL-terminated string of up to 255 characters containing a regular expression. Regular expressions are of the form specified in tpsubscribe(3c), as described in the Oracle Tuxedo ATMI C Function Reference). For example, if eventexpr is set to:
• "\\..*"—the caller is subscribing to all system-defined events.
• "\\.SysServer.*"—the caller is subscribing to all system-defined events related to servers.
• "[A-Z].*"—the caller is subscribing to all user events starting with any uppercase letter between A and Z.
• ".*(ERR|err).*"—the caller is subscribing to all user events with names that contain either err or ERR, such as the account_error and ERROR_STATE events, respectively. Filter rules are specific to the typed buffers to which they are applied. For more information on filter rules, refer to tpsubscribe(3c) in the Oracle Tuxedo ATMI C Function Reference.
• NULL—sends unsolicited messages. Refer to “Notification via Unsolicited Message” on page 8‑10 for more information.
• Pointer to a valid TPEVCTL structure—sends information based on the TPEVCTL structure. Refer to “Notification via Service Call or Reliable Queue” on page 8‑10 for more information. Flag options. For more information on available flag options, refer to tpsubscribe(3c) in the Oracle Tuxedo ATMI C Function Reference.For purposes of subscriptions (and for MIB updates), service routines executed in an Oracle Tuxedo system server process are considered to be trusted code.If a subscriber is an Oracle Tuxedo system client process and ctl is NULL, when the event to which the client has subscribed is posted, the EventBroker sends an unsolicited message to the subscriber as follows. When an event name is posted that evaluates successfully against eventexpr, the EventBroker tests the posted data against the associated filter rule. If the data passes the filter rule (or if there is no filter rule for the event), then the subscriber receives an unsolicited notification along with any data posted with the event.In order to receive unsolicited notifications, the client must register an unsolicited message handling routine using the tpsetunsol() function.ATMI clients receiving event notification via unsolicited messages should remove their subscriptions from the EventBroker list of active subscriptions before exiting. This is done using the tpunsubscribe() function.Event notification via service call enables you to program actions that can be taken in response to specific conditions in your application without human intervention. Event notification via reliable queue ensures that event data is not lost. It also provides the subscriber the flexibility of retrieving the event data at any time.If the subscriber (either a client or a server process) wants event notifications sent to service routines or to stable-storage queues, then the ctl parameter of tpsubscribe() must point to a valid TPEVCTL structure.The TPEVCTL structure contains the following elements:Table 8‑6 summarizes the TPEVCTL typed buffer data structure.
Table 8‑6 TPEVCTL Typed Buffer Format Flag options. For more information on flags, refer to tpsubscribe(3c) in the Oracle Tuxedo ATMI C Function Reference. TPQCTL structure. For more information, refer to tpsubscribe(3c) in the Oracle Tuxedo ATMI C Function Reference.The tpunsubscribe(3c) function enables an Oracle Tuxedo system ATMI client or server to unsubscribe from an event.Use the following signature to call the tpunsubscribe() function:Table 8‑7 describes the arguments to the tpunsubscribe() function.
Table 8‑7 tpunsubscribe( ) Function Arguments Flag options. For more information on available flag options, refer to tpunsubscribe(3c) in the Oracle Tuxedo ATMI C Function Reference.The tppost(3c) function enables an Oracle Tuxedo ATMI client or server to post an event.Use the following signature to call the tppost() function:Table 8‑8 describes the arguments to the tppost() function.
Table 8‑8 tppost( ) Function Arguments Size of data buffer that should be posted with the event. If data points to a buffer of a type that does not require a length to be specified (for example, an FML fielded buffer) or if you set it to NULL, the len argument is ignored and the event is posted with no data. Flag options. For more information on available flag options, refer to tppost(3c) in the Oracle Tuxedo ATMI C Function Reference.Listing 8‑2 illustrates an event posting taken from the Oracle Tuxedo system sample application bankapp. This example is part of the WITHDRAWAL service. One of the functions of the WITHDRAWAL service is checking for withdrawals greater than $10,000 and posting an event called BANK_TLR_WITHDRAWAL.Listing 8‑2 Posting an Event with tppost( )The following example illustrates a portion of a bankapp application server that subscribes to BANK_TLR_.* events, which includes the BANK_TLR_WITHDRAWAL event shown in the previous example, as well as any other event names beginning with BANK_TLR_. When a matching event is posted, the application notifies the subscriber via a call to a service named WATCHDOG.Listing 8‑3 Subscribing to an Event with tpsubscribe( )