The Event Broker is a BEA TUXEDO subsystem that receives event posting messages, filters them, and distributes them to subscribers. A poster is a BEA TUXEDO system process that detects when an event of interest has occurred and reports (posts) it to the Event Broker. A subscriber is a BEA TUXEDO system process that requests that some notification action be taken when a matching event is posted.
This concept of an "anonymous" broker that receives and distributes messages provides another client-server communication paradigm to BEA TUXEDO. Instead of a one-to-one relationship between a service requester and a service provider, an arbitrary number of posters can post a message buffer for an arbitrary number of subscribers. The posters simply post events, without having to know who receives the information and what is done about it. The subscribers can get whatever information they are interested in from the Event Broker, without having to know who posted it, and they can be notified and take action in a variety of ways.
Typically, Event Broker applications are designed to handle exception events. The application designer has to decide what events in the application need to be monitored. In a banking application, for example, an event might be posted for an unusually large withdrawal transaction; but it would not be particularly useful to post an event for every withdrawal transaction. And not all users would need to subscribe to that event; perhaps just the branch manager would need to be notified.
Following this introduction to the Event Broker's features and some guidelines on its use, this chapter explains how to post events, how to subscribe to events, and gives some examples.
When an event is posted, the Event Broker may be configured to invoke one or more of these notification actions for clients or servers who have subscribed:
Introduction
Notification Actions
tpnotify(3c).
Further information on the use of these notification actions is given later in this chapter.
In addition, the following notification actions may be configured by the system administrator only, using the BEA TUXEDO system administrative API to create an EVENT_MIB(5) entry:
For information on the The Event Broker is used to monitor and report application-defined events such as a large cash withdrawal as mentioned earlier for a banking application. BEA TUXEDO itself detects and posts certain pre-defined events related to system warnings and failures. This is done by the Event Monitor feature, which is a part of the general-purpose Event Broker communication mechanism. For example, system-generated events report on configuration changes, state changes, connection failures, and machine partitioning. A list of the system-generated events detected by the Event Monitor is given in the Note that a leading dot (".") in the event name is used to distinguish system-generated events from application-defined events.
System-generated events are defined in advance by BEA TUXEDO system code and as such do not have to be posted. System-generated events can be subscribed to by clients and servers just as application-defined events are. However, just as application-defined events should be used for exceptional conditions, subscriptions to system-generated events should be used mainly by system administrators, not by every client in the application.
When incorporating the features offered by the Event Broker/Event Monitor into your application, remember that it is not intended to be a mechanism for high volumes of postings going to many subscribers. Don't try to post an event for every activity that occurs, and don't think that everyone needs to subscribe. In an overload condition, system performance could be affected and notifications could be dropped. To minimize that possibility, the system administrator should ensure that the UNIX IPC resources are carefully tuned as explained in the BEA TUXEDO Installation Guide.
The Event Broker server is Event Broker programming interfaces are available to all BEA TUXEDO system server and client processes, including Workstation and COBOL. Basic operations are as follows:
EVENT_MIB(5), see the BEA TUXEDO Reference Manual.
User-Defined and System-Defined Events
EVENTS(5) reference page in the BEA TUXEDO Reference Manual.
Event Broker/Event Monitor Servers
TMUSREVT(5). This is a BEA TUXEDO system-provided server that processes event report message buffers and acts as an Event Broker to filter and distribute them. The BEA TUXEDO system administrator must boot one or more of these servers to activate event brokering.
TMSYSEVT(5) is the BEA TUXEDO system-provided server that acts as an Event Broker for system-generated events. TMSYSEVT and TMUSREVT are similar, but separate servers have been provided to allow the system administrator to have a different replication strategy for processing system event notifications. This is discussed in Administering the BEA TUXEDO System.
Programming Interface
To post an event, a BEA TUXEDO client or server calls The syntax of the The When choosing event names, keep in mind that subscribers can use wild card capabilities to subscribe to multiple events with a single function call. Using the same prefix for a category of related event names can be helpful.
The If Listing 6-1 shows an example of event posting taken from the BEA TUXEDO system sample application Posting Events
tppost(3c). The input is an event name, buffer pointer, buffer length, and flags.
tppost() function is:
tppost(char *
eventname, char *data, long len, long flags) tppost() Arguments: eventname
tppost() eventname can contain up to 31 characters plus a null character. The first character cannot be a dot ("."), as this character is reserved as the starting character for BEA TUXEDO system-generated events.
tppost() Arguments: data and len
tppost() data argument must point to a buffer previously allocated by tpalloc(3c), and len should specify the amount of data in the buffer that should be posted with the event. Note that if data points to a buffer of a type that does not require a length to be specified (for example, an FML fielded buffer), then len is ignored.
data is NULL, len is ignored and the event is posted with no data.
tppost() Arguments: flags
tppost() can be used with a number of flags, for example, to determine how transaction timeouts and blocking timeouts are to be handled. For details, see the tppost(3c) reference page in the BEA TUXEDO Reference Manual.
Example of Event Posting
bankapp. This example is part of the WITHDRAWAL service. One of the things that the WITHDRAWAL service does is check for withdrawals greater than $10,000.00. In this example, an event called BANK_TLR_WITHDRAWAL is posted whenever such a withdrawal is made.
Listing 6-1
Posting an Event with tppost()
.
.
.
/* Event logic related */
static float evt_thresh = 10000.00 ; /* default for event threshold */
static char emsg[200] ; /* used by event posting logic */
.
.
.
/* Post a BANK_TLR_WITHDRAWAL event ? */
if (amt < evt_thresh) {
/* no event to post */
tpreturn(TPSUCCESS, 0,transb->data , 0L, 0);
}
/* prepare to post the event */
if ((Fchg (transf, EVENT_NAME, 0, "BANK_TLR_WITHDRAWAL", (FLDLEN)0) == -1) ||
(Fchg (transf, EVENT_TIME, 0, gettime(), (FLDLEN)0) == -1) ||
(Fchg (transf, AMOUNT, 0, (char *)&amt, (FLDLEN)0) == -1)) {
(void)sprintf (emsg, "Fchg failed for event fields: %s",
Fstrerror(Ferror)) ;
}
/* post the event */
else if (tppost ("BANK_TLR_WITHDRAWAL", /* event name */
(char *)transf, /* data */
0L, /* len */
TPNOTRAN | TPSIGRSTRT) == -1) {
/* If event broker is not reachable, ignore the error */
if (tperrno != TPENOENT)
(void)sprintf (emsg, "tppost failed: %s", tpstrerror (tperrno));
}
Note that this example simply posts the event to the Event Broker: something noteworthy has occurred in the application. Subscription to the event by interested client(s), who can then take action as needed, is done independently.
To subscribe to an event, a BEA TUXEDO system client or server calls tpsubscribe(3c). The input is an event name(s), optional filter rules, and flags to specify the notification method. As mentioned earlier in this chapter, several notification methods are available: unsolicited notification message, service call, and reliable queue. (Other notification methods can be configured by the system administrator using the BEA TUXEDO system administrative API.)
The syntax of the tpsubscribe() function is:
tpsubscribe (char *eventexpr, char *filter, TPEVCTL *ctl, longflags)
Both system-generated events and application-defined events can be subscribed to with tpsubscribe().
For purposes of subscriptions (and for MIB updates), service routines executing in a BEA TUXEDO system server process are considered to be trusted code. This is a recent enhancement to BEA TUXEDO system security; it permits some operations that might have been prohibited in earlier versions.
The event or set of events being subscribed to is named by eventexpr, a null-terminated string of up to 255 characters containing a regular expression. Regular expressions are of the form specified in recomp(3c). For example:
eventexpr is "\\..*", the caller is subscribing to all system-generated events.
eventexpr is "[A-Z].*", the caller is subscribing to all user events starting with A-Z.
The By using the event filtering capability, subscribers can be more discriminating about the events they are notified of. For example, a poster can post an event for withdrawals greater than $10,000.00, as illustrated above, 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 buffers to which they are applied. See the The If the subscriber is a BEA TUXEDO system client process and In order to receive unsolicited notifications, the client must register (via Clients receiving event notification via unsolicited messages should remove their subscriptions from the Event Broker's list of active subscriptions before exiting. This is done using the Event notification via service call gives you the ability to program responses to specific conditions in your application and take action without human intervention. An example is given later in this chapter. Event notification via reliable queue ensures that event data will not get lost and also gives 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 to go to service routines or to stable-storage queues, then the The following is a list of valid bits for the ctl->flags element for controlling options for event subscriptions.
tpsubscribe() Arguments: filter
tpsubscribe() filter argument, if present, is a 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 does not invoke the notification method. The caller can subscribe to the same event multiple times with different filter rules.
tpsubscribe(3c) reference page in the BEA TUXEDO Reference Manual for further information on filter rules.
tpsubscribe() Arguments: ctl
ctl argument to tpsubscribe() controls how the subscriber is notified of the event.
Notification Via Unsolicited Message
ctl is NULL, then the Event Broker sends an unsolicited message to the subscriber when the event to which it is subscribed is posted. Basic operation is as follows. When an event name is posted that evaluates successfully against eventexpr, the Event Broker 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.
tpsetunsol(3c)) an unsolicited message handling routine.
tpunsubscribe(3c) function, as shown later in this chapter.
Notification Via Service Call or Reliable Queue
ctl parameter of tpsubscribe() must point to a valid TPEVCTL structure. This structure contains the following elements:
long flags;
char name1[32];
char name2[32];
TPQCTL qctl;
TPEVSERVICE
ctl->name1. Basic operation is as follows. When an event name is posted that evaluates successfully against eventexpr, the Event Broker 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 a service request is sent to ctl->name1 along with any data posted with the event. The service name in ctl->name1 can be any valid BEA TUXEDO system service name and it may or may not be active at the time the subscription is made. Service routines invoked by the Event Broker should return with no reply data (that is, they should call tpreturn(3c) with a NULL data argument). Any data passed to tpreturn() will be dropped.
TPEVQUEUE
ctl->name1 and the queue named in ctl->name2. Basic operation is as follows. When an event name is posted that evaluates successfully against eventexpr, the Event Broker 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 Event Broker enqueues a message to the specified queue space/queue name along with any data posted with the event. The queue space and queue name can be any valid BEA TUXEDO system queue space and queue name, either of which may or may not exist at the time the subscription is made. In the TPEVCTL structure, ctl->qctl can contain options further directing the Event Broker's enqueuing of the posted event. These are the same options that are used for control of the tpenqueue(3c) function. For example, the TPQTOP option can be used to place a message at the top of the queue. For further information on these options, see the tpenqueue(3c) reference page in the BEA TUXEDO Reference Manual.
TPEVSERVICE and TPEVQUEUE are mutually exclusive flags. For information on other flag bits that can be used with either TPEVSERVICE or TPEVQUEUE, see the tpsubscribe(3c) reference page in the BEA TUXEDO Reference Manual.
tpsubscribe() can be used with a number of flags, for example, to determine how transaction timeouts and blocking timeouts are to be handled. For details, see the tpsubscribe(3c) reference page in the BEA TUXEDO Reference Manual.
Listing 6-2 shows part of a bankapp application server that subscribes to BANK_TLR_.* events, which would include the BANK_TLR_WITHDRAWAL event from the previous example as well as any other event names beginning with BANK_TLR_. When a matching event is posted, the subscriber is notified via a service call to a service named WATCHDOG.
Listing 6-2 Subscribing to an Event with tpsubscribe()
.
.
.
/* Event Subscription handles */
static long sub_ev_largeamt = 0L ;
.
.
.
/* Preset default for option 'w' - watchdog threshold */
(void)strcpy (amt_expr, "AMOUNT > 10000.00") ;
.
.
.
/*
* Subscribe to the events generated
* when a "large" amount is transacted.
*/
evctl.flags = TPEVSERVICE ;
(void)strcpy (evctl.name1, "WATCHDOG") ;
/* Subscribe */
sub_ev_largeamt = tpsubscribe ("BANK_TLR_.*",amt_expr,&evctl,TPSIGRSTRT) ;
if (sub_ev_largeamt == -1L) {
(void)userlog ("ERROR: tpsubscribe for event BANK_TLR_.* failed: %s",
tpstrerror(tperrno)) ;
return -1 ;
}
.
.
.
{
/* Unsubscribe to the subscribed events */
if (tpunsubscribe (sub_ev_largeamt, TPSIGRSTRT) == -1)
(void)userlog ("ERROR: tpunsubscribe to event BANK_TLR_.* failed: %s",
tpstrerror(tperrno)) ;
return ;
}
/*
* Service called when a BANK_TLR_.* event is posted.
*/
void
#if defined(__STDC__) || defined(__cplusplus)
WATCHDOG(TPSVCINFO *transb)
#else
WATCHDOG(transb)
TPSVCINFO *transb;
#endif
{
FBFR *transf; /* fielded buffer of decoded message */
/* Set pointr to TPSVCINFO data buffer */
transf = (FBFR *)transb->data;
/* Print the log entry to stdout */
(void)fprintf (stdout, "%20s|%28s|%8ld|%10.2f\n",
Fvals (transf, EVENT_NAME, 0),
Fvals (transf, EVENT_TIME, 0),
Fvall (transf, ACCOUNT_ID, 0),
*( (float *)CFfind (transf, AMOUNT, 0, NULL, FLD_FLOAT)) );
/* No data should be returned by the event subscriber's svc routine */
tpreturn(TPSUCCESS, 0,NULL, 0L, 0);
}
In the above example, note the use of tpunsubscribe() before leaving the application. This removes the event subscription from the Event Broker's list of active subscriptions. For information on the options available for this function, see the tpunsubscribe(3c) reference page in the BEA TUXEDO Reference Manual.