Posting Events

8.7 Posting Events

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:

tppost(char *eventname, char *data, long len, long flags)

The following table describes the arguments to the tppost() function.

Table 8-7 tppost( ) Function Arguments

Argument	Description
`eventname`	Pointer to an event name containing up to 31 characters plus NULL. The first character cannot be a dot (“.”) because the dot is reserved as the first character in names of Oracle Tuxedo system-defined events. When defining event names, keep in mind that subscribers can use wildcard 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.
`data`	Pointer to a buffer previously allocated using the `tpalloc()` function.
`len`	Size of data buffer that must 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.
`flags`	Flag options. For more information on available flag options, refer to tppost(3c) in the Oracle Tuxedo ATMI C Function Reference.

The following listing 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 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));
}

This example simply posts the event to the EventBroker to indicate a noteworthy occurrence in the application. Subscription to the event by interested clients, who can then take action as required, is done independently.

Parent topic: Writing Event-based Clients and Servers