Subscribing to Events


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Doc Home \| Programming \| Topic List \| Previous \| Next \| Contents

Programming a BEA Tuxedo Application Using COBOL

The TPSUBSCRIBE(3cbl) routine enables a BEA Tuxedo system 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 a BEA 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(31).
05 NAME-2        PIC X(31).
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 recomp, rematch(3c) as described in the Programming a BEA Tuxedo Application 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 BEA Tuxedo 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 BEA Tuxedo COBOL Function Reference

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 recomp, rematch(3c) as described in the Programming a BEA Tuxedo Application 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 BEA Tuxedo 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 BEA Tuxedo COBOL Function Reference

Refer to Using the BEA Tuxedo /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 a BEA Tuxedo system server process are considered to be trusted code.

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