Writing Event-based Clients and Servers

This topic includes the following sections:

•	Overview of Events

•	Defining the Unsolicited Message Handler

•	Sending Unsolicited Messages

•	Checking for Unsolicited Messages

•	Getting Unsolicited Messages

•	Subscribing to Events

•	Unsubscribing from Events

•	Posting Events

Overview of Events

Event-based communication provides a method for an Oracle Tuxedo system process to be notified when a specific situation (event) occurs.

The Oracle Tuxedo system supports two types of event-based communication:

•	Unsolicited events

•	Brokered events

Unsolicited Events

Unsolicited events are messages used to communicate with client programs that are not waiting for and/or expecting a message.

Brokered Events

Brokered events enable a client and a server to communicate transparently with one another via an “anonymous” broker that receives and distributes messages. Such brokering is another client/server communication paradigm that is fundamental to the Oracle Tuxedo system.

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 Oracle Tuxedo system does not impose a fixed ratio of service requesters to service providers; an arbitrary number of posters can post a message for an arbitrary number of subscribers. The posters simply post events, without knowing which processes receive the information or how the information is handled. Subscribers are notified of specified events, without knowing who posted the information. In this way, the EventBroker provides complete location transparency.

Typically, EventBroker applications are designed to handle exception events. An application designer must decide which events in the application constitute exception events and need to be monitored. In a banking application, for example, it might be useful to post an event whenever an unusually large amount of money is withdrawn, but it would not be particularly useful to post an event for every withdrawal transaction. In addition, not all users would need to subscribe to that event; perhaps only the branch manager would need to be notified.

Notification Actions

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

Notification Action	Description
Unsolicited notification message	Clients may receive event notification messages in their unsolicited message handling routine, just as if they were sent by the TPNOTIFY routine.
Service call	Servers may receive event notification messages as input to service routines, just as if they were sent by TPACALL.
Reliable queue	Event notification messages may be stored in an Oracle Tuxedo system reliable queue, using TPDEQUEUE(3cbl). Event notification records are stored until requests for contents are issued. An Oracle Tuxedo system client or server process may call TPDEQUEUE(3cbl) to retrieve these notification records, or alternately TMQFORWARD(5) may be configured to automatically dispatch an Oracle Tuxedo system service routine that retrieves a notification record. 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:

•	Invokes a system command

•	Writes a message to the system’s log file on disk

Note:

Only the Oracle Tuxedo application administrator is allowed to create an EVENT_MIB(5) entry.

For information on the EVENT_MIB(5), refer to the File Formats, Data Descriptions, MIBs, and System Processes Reference.

EventBroker Servers

TMUSREVT is the Oracle Tuxedo system-supplied server that acts as an EventBroker for user events. TMUSREVT processes event report message records, 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.

System-defined Events

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.

System-defined events are defined in advance by the Oracle Tuxedo system code and do not require posting. The name of a system-defined event, unlike that of an application-defined event, always begins with a dot (“.”). Names of application-defined events may not begin with a leading dot.

Clients and servers can subscribe to system-defined events. These events, however, should be used mainly by application administrators, not by every client in the application.

When incorporating the EventBroker into your application, remember that it is not intended to provide a mechanism for high-volume distribution to many subscribers. Do not attempt to post an event for every activity that occurs, and do not expect all clients and servers to subscribe. If you overload the EventBroker, system performance may be adversely affected and notifications may be dropped. To minimize the possibility of overload, the application administrator should carefully tune the operating system IPC resources, as explained in Installing the Oracle Tuxedo System.

Programming Interface for the EventBroker

EventBroker programming interfaces are available for all Oracle Tuxedo system server and client processes, including Workstation, in both C and COBOL.

The programmer’s job is to code the following sequence:

1.	A client or server posts a record to an application-defined event name.

2.	The posted record is transmitted to any number of processes that have subscribed to the event.

Subscribers may be notified in a variety of ways (as discussed in “Notification Actions”), and events may be filtered. Notification and filtering are configured through the programming interface, as well as through the Oracle Tuxedo system administrative API.

Defining the Unsolicited Message Handler

To define the unsolicited message handler, use the TPSETUNSOL(3cbl) routine with the following signature:

01 CURR-ROUTINE PIC S9(9) COMP-5.
01 PREV-ROUTINE PIC S9(9) COMP-5.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPSETUNSOL" USING CURR-ROUTINE PREV-ROUTINE TPSTATUS-REC.

TPSETUNSOL allows a client to identify the routine that should be invoked when an unsolicited message is received by the Oracle Tuxedo system libraries. Before the first call to TPSETUNSOL, any unsolicited messages received by the Oracle Tuxedo system libraries on behalf of the client are logged and ignored. The method used by the system for notification and detection is determined by the application default, which can be overridden on a per-client basis. For more information, refer to TPINITIALIZE(3cbl) in the Oracle Tuxedo ATMI COBOL Function Reference.

The CURR-ROUTINE parameter identifies one of 16 predefined routines that provide unsolicited message handling: eight C routines, tm_displatch1 through _tm_dispatch8, and eight COBOL routines, TMDISPATCH9 through TMDISPATCH16. (Alternatively, if you set CURR-ROUTINE to a value of 0, any unsolicited messages received by the Oracle Tuxedo system libraries on behalf of the client are logged and ignored.) The C routines must conform to the parameter definition provided on TPSETUNSOL(3cbl). When a COBOL routine is used, TPGETUNSOL must be called to receive the data.

The following sample code shows how to set an unsolicited routine in a COBOL program.

Listing 8‑1 Setting an Unsolicited Routine

*
* Call TPSETUNSOL - Set a COBOL unsolicited message handler
* Routine TMDISPATCH9 will be called
*
   MOVE 9 to CURR-ROUTINE.
   CALL "TPSETUNSOL" USING
                       CURR-ROUTINE
                       PREV-ROUTINE
                       TPSTATUS-REC.
   IF NOT TPOK
             Routine TMDISPATCH9 will receive unsolicited messages
   ELSE
             Process error condition

 

Sending Unsolicited Messages

The Oracle Tuxedo system allows unsolicited messages to be sent to client processes without disturbing the processing of request/response calls or conversational communications.

Unsolicited messages can be sent to client processes by name, using TPBROADCAST(3cbl), or by an identifier received with a previously processed message, using TPNOTIFY(3cbl). Messages sent via TPBROADCAST can originate either in a service or in another client. Messages sent via TPNOTIFY can originate only in a service.

 

Broadcasting Messages by Name

The TPBROADCAST(3cbl) routine 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 TPINITIALIZE and have not yet made a call to TPTERM.

Use the following signature to call the TPBROADCAST routine:

01 TPBCTDEF-REC.
COPY TPBCTDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User Data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPBROADCAST" USING TPBCTDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

Table 8‑2 describes the members of the TPBCTDEF-REC data structure.

 

Table 8‑2 TPBCTDEF-REC Data Structure Members

Member	Description
LMID	Pointer to the logical machine identifier for the client. A value of SPACES acts as a wildcard, so that a message can be directed to groups of clients.
USRNAME	Username of the client process, if one exists. A value of SPACES acts as a wildcard, so that a message can be directed to groups of clients.
CLTNAME	Client name of the client process, if one exists. A value of NULL acts as a wildcard, so that a message can be directed to groups of clients.
Settings (such as TPBLOCK-FLAG)	Settings for the TPBROADCAST command. Refer to TPBROADCAST(3cbl) in the Oracle Tuxedo ATMI COBOL Function Reference for information on available settings.

Refer to “Defining a Service” in Programming Oracle Tuxedo ATMI Applications Using C for a description of the TPTYPE-REC record.

The following example illustrates a call to TPBROADCAST for which all clients are targeted. The message to be sent is contained in a STRING record.

Listing 8‑2 Using TPBROADCAST

    . . .
**************************************************
* Prepare the record to broadcasted
**************************************************
    MOVE "HELLO, WORLD" TO DATA-REC.
    MOVE 11 TO LEN.
    MOVE "STRING" TO REC-TYPE.
*
    SET TPNOBLOCK TO TRUE.
    SET TPNOTIME TO TRUE.
    SET TPSIGRSTRT TO TRUE.
*
    MOVE SPACES TO LMID.
    MOVE SPACES TO USRNAME.
    MOVE SPACES TO CLTNAME.
    CALL "TPBROADCAST" USING TPBCTDEF-REC
                        TPTYPE-REC
                        DATA-REC
                        TPSTATUS-REC.
    IF NOT TPOK
        error processing

 

Broadcasting Messages by Identifier

The TPNOTIFY(3cbl) routine is used to broadcast a message using an identifier received with a previously processed message. It can be called only from a service.

Use the following signature to call the TPNOTIFY routine:

01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User Data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPNOTIFY" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

Refer to “Writing Global Transactions” in Programming Oracle Tuxedo ATMI Applications Using C for information on the TPSVCDEF-REC data structure, and “Defining a Service” in Programming Oracle Tuxedo ATMI Applications Using C for a description of the TPTYPE-REC record.

Checking for Unsolicited Messages

To check for unsolicited messages while running the client in “dip-in” notification mode, use the TPCHKUNSOL(3cbl) routine with the following signature:

01 MSG-NUM PIC S9(9) COMP-5.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPCHKUNSOL" USING MSG-NUM TPSTATUS-REC.

If any messages are pending, the system invokes the unsolicited message handling routine that was specified using TPSETUNSOL. Upon completion, the routine returns either the number of unsolicited messages that were processed and sets TP-STATUS to [TPOK].

If you issue this routine when the client is running in SIGNAL-based, thread-based notification mode, or is ignoring unsolicited messages, the routine has no impact and returns immediately.

The following example shows how to check for the arrival of an unsolicited message.

Listing 8‑3 Arrival of an Unsolicited Message

*
* Check for unsolicited messages
*
    CALL "TPCHKUNSOL" USING MESS-NUM
                       TPSTATUS-REC.
*
    IF TPOK
         IF MESS-NUM IS = 0
             No messages were processed by the
             unsolicited routine
    ELSE
         MESS-NUM number of messages were
            processed by the unsolicited routine
    END-IF
    ELSE
       process error
    END-IF

 

Getting Unsolicited Messages

To get unsolicited messages, you must call the TPGETUNSOL(3cbl) routine. This routine can be called, however, only from an unsolicited message handler. Use the following signature to call the TPGETUNSOL routine:

01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPGETUNSOL" USING TPTYPE-REC DATA-REC TPSTATUS-REC.

Refer to “Defining a Service” in Programming Oracle Tuxedo ATMI Applications Using C for a description of the TPTYPE-REC record.

The following example shows how to get an unsolicited message.

Listing 8‑4 Getting an Unsolicited Message

 IDENTIFICATION DIVISION.
 PROGRAM-ID. TMDISPATCH9.
 ENVIRONMENT DIVISION.
 CONFIGURATION SECTION.
 SOURCE-COMPUTER. USL-486.
 OBJECT-COMPUTER. USL-486.
*
 DATA DIVISION.
 WORKING-STORAGE SECTION.
*
 01 TPTYPE-REC.
    COPY TPTYPE.
*
 01 TPSTATUS-REC.
    COPY TPSTATUS.
*
 01 DATA-REC PIC X(1000).
*
 PROCEDURE DIVISION.
*
 A-000.
*
   MOVE "CARRAY" TO REC-TYPE.
   MOVE 1000 TO LEN.
   CALL "TPGETUNSOL" USING TPTYPE-REC
                      DATA-REC
                      TPSTATUS-REC.
   IF NOT TPOK
             error processing
*
   Process message
   DISPLAY "TPGETUNSOL IS TPOK".
   DISPLAY "MESSAGE IS" DATA-REC.
   DISPLAY "LENGTH IS" LEN.
   EXIT PROGRAM.
*

 

Subscribing to Events

The TPSUBSCRIBE(3cbl) routine 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 routine:

01 TPEVTDEF-REC.
COPY TPEVTDEF.

01 TPQUEDEF-REC.
COPY TPQUEDEF.

01 TPSTATUS-REC.
COPY TPSTATUS.

CALL “TPSUBSCRIBE” USING TPEVTDEF-REC TPQUEDEF-REC TPSTATUS-REC

The TPEVTDEF-REC data structure signature is as follows:

05 TPBLOCK-FLAG PIC S9(9) COMP-5.
88 TPBLOCK VALUE 0.
88 TPNOBLOCK VALUE 1.
05 TPTRAN-FLAG PIC S9(9) COMP-5.
88 TPTRAN VALUE 0.
88 TPNOTRAN VALUE 1.
05 TPREPLY-FLAG PIC S9(9) COMP-5.
88 TPREPLY VALUE 0.
88 TPNOREPLY VALUE 1.
05 TPTIME-FLAG PIC S9(9) COMP-5.
88 TPTIME VALUE 0.
88 TPNOTIME VALUE 1.
05 TPSIGRSTRT-FLAG PIC S9(9) COMP-5.
88 TPNOSIGRSTRT VALUE 0.
88 TPSIGRSTRT VALUE 1.
05 TPEV-METHOD-FLAG PIC S9(9) COMP-5.
88 TPEVNOTIFY VALUE 0.
88 TPEVSERVICE VALUE 1.
88 TPEVQUEUE VALUE 2.
05 TPEV-PERSIST-FLAG PIC S9(9) COMP-5.
88 TPEVNOPERSIST VALUE 0.
88 TPEVPERSIST VALUE 1.
05 TPEV-TRAN-FLAG PIC S9(9) COMP-5.
88 TPEVNOTRAN VALUE 0.
88 TPEVTRAN VALUE 1.
*
05 EVENT-COUNT PIC S9(9) COMP-5.
05 SUBSCRIPTION-HANDLE PIC S9(9) COMP-5.
05 NAME-1 PIC X(127).
05 NAME-2 PIC X(127).
05 EVENT-NAME PIC X(31).
05 EVENT-EXPR PIC X(255).
05 EVENT-FILTER PIC X(255).

The following table describes the members of the TPEVTDEF-REC data structure.

 

Member	Description
EVENT-COUNT	Event count.
SUBSCRIPTION-HANDLE	Subscription handle.
NAME-1, NAME-2	Name of queued spaces. If the subscriber sets TPEVQUEUE, then event notifications are enqueued to the queue space named by NAME-1 and the queue named by NAME-2.
EVENT-NAME	Event name.
EVENT-EXPR	Set of events to which to 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 Programming Oracle Tuxedo ATMI Applications Using C. 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 A-Z. • ".*(ERR|err).*" — the caller is subscribing to all user events containing either the substring ERR or the substring err (for example, account_error and ERROR_STATE events would both qualify).
EVENT-FILTER	String containing a Boolean filter rule that must be evaluated successfully before the Event Broker posts the event. Upon receiving an event to be posted, the Event Broker applies the filter rule, if one exists, to the posted event’s data. If the data passes the filter rule, the Event Broker invokes the notification method specified; otherwise, the Event Broker ignores the notification method. The caller can subscribe to the same event multiple times with different filter rules. By using the event filtering capability, subscribers can be more discriminating about the events for which they are notified. For example, a poster can post an event for withdrawals greater than $10,000.00, but a subscriber may want to specify a higher threshold for being notified, such as $50,000.00. Or, a subscriber may want to be notified of large withdrawals only if made by customers with specified IDs. Filter rules are specific to the typed records to which they are applied. Refer to the TPSUBSCRIBE(3cbl) reference page in the Oracle Tuxedo ATMI COBOL Function Reference for further information on filter rules.
SETTINGS (TPBLOCK-FLAG, TPTRAN-FLAG, and so on)	Miscellaneous settings that control the server characteristics. For more information on the settings, refer to the Oracle Tuxedo ATMI COBOL Function Reference.

Refer to Using the ATMI /Q Component for more information on the TPQUEDEF-REC data structure.

You can subscribe to both system- and application-defined events using the TPSUBSCRIBE routine.

For purposes of subscriptions (and for MIB updates), service routines executed in an Oracle Tuxedo system server process are considered to be trusted code.

Refer to TPSUBSCRIBE(3cbl) in the Oracle Tuxedo ATMI COBOL Function Reference for more information on the routine.

Unsubscribing from Events

The TPUNSUBSCRIBE(3cbl) routine enables an Oracle Tuxedo system ATMI client or server to unsubscribe from an event.

Use the following signature to call the TPUNSUBSCRIBE routine:

01 TPEVTDEF-REC.
COPY TPEVTDEF.

01 TPSTATUS-REC.
COPY TPSTATUS.

CALL “TPUNSUBSCRIBE” USING TPEVTDEF-REC TPSTATUS-REC

Refer to “Subscribing to Events” on page 8‑11 for a detailed description of the TPEVTDEF-REC data structure, and to Using the ATMI /Q Component for more information on the TPQUEDEF-REC data structure.

Posting Events

The TPPOST(3cbl) routine enables an Oracle Tuxedo ATMI client or server to post an event.

Use the following signature to call the TPPOST routine:

01 TPEVTDEF-REC.
COPY TPEVTDEF.

01 TPTYPE-REC.
COPY TPSTATUS.

01 TPDATA-REC.
COPY TPSTATUS.

01 TPSTATUS-REC.
COPY TPSTATUS.

CALL “TPPST” USING TPEVTDEF-REC TPTYPE-REC TPDATA-REC TPSTATUS-REC

Refer to “Subscribing to Events” on page 8‑11 for a detailed description of the TPEVTDEF-REC data structure, and to “Defining a Service” in Programming Oracle Tuxedo ATMI Applications Using C for a description of the TPTYPE-REC record.