PURPOSE

tppost - post an event

SYNOPSIS

#include <atmi.h>
int tppost(char *eventname, char *data, long len, long flags)

DESCRIPTION

The caller uses tppost to post an event and any accompanying data. The event is named by eventname and data, if not NULL, points to the data. The posted event and its data are dispatched by the TUXEDO System event broker to all subscribers whose subscriptions successfully evaluate against eventname and whose optional filter rules successfully evaluate against data.

eventname is a NULL-terminated string of at most 31 characters. eventname's first character cannot be a dot (".") as this character is reserved as the starting character for all events defined by the TUXEDO System itself.

If data is non-NULL, it 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. If data is NULL, len is ignored and the event is posted with no data.

When tppost is used within a transaction, the transaction boundary can be extended to include those servers and/or stable-storage message queues notified by the event broker. When a transactional posting is made, some of the recipients of the event posting are notified on behalf of the poster's transaction (for example, servers and queues), while some are not (for example, clients).

If the poster is within a transaction and the TPNOTRAN flag is not set, the posted event goes to the event broker in transaction mode such that it dispatches the event as part of the poster's transaction. The broker dispatches transactional event notifications only to those service routine and stable-storage queue subscriptions that used the TPEVTRAN bit setting in the ctl->flags parameter passed to tpsubscribe(3c). Client notifications, and those service routine and stable-storage queue subscriptions that did not use the TPEVTRAN bit setting in the ctl->flags parameter passed to tpsubscribe(3c), are also dispatched by the event broker but not as part of the posting process' transaction.

Following is a list of valid flags.

TPNOTRAN

If the caller is in transaction mode and this flag is set, then the event posting is not made on behalf of the caller's transaction. A caller in transaction mode that sets this flag is still subject to the transaction timeout (and no other) when posting events. If the event posting fails, the caller's transaction is not affected.

TPNOREPLY

Informs tppost not to wait for the event broker to process all subscriptions for eventname before returning. When TPNOREPLY is set, tpurcode is set to zero regardless of whether tppost returns successfully or not. When the caller is in transaction mode, this setting cannot be used unless TPNOTRAN is also set.

TPNOBLOCK

The event is not posted if a blocking condition exists. If such a condition occurs, the call fails and tperrno is set to TPEBLOCK. When TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout).

TPNOTIME

This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.

TPSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted system call is re-issued. When TPSIGRSTRT is not specified and a signal interrupts a system call, then tppost fails and tperrno is set to TPGOTSIG.

RETURN VALUES

Upon successful return from tppost, tpurcode contains the number of event notifications dispatched by the event broker on behalf of eventname (that is, postings for those subscriptions whose event expression evaluated successfully against eventname and whose filter rule evaluated successfully against data). Upon return where tperrno is set to TPESVCFAIL, tpurcode contains the number of non-transactional event notifications dispatched by the event broker on behalf of eventname. This function returns -1 on error and sets tperrno to indicate the error condition.

ERRORS

Under the following conditions, tppost fails and sets tperrno to one of the following values. (Unless otherwise noted, failure does not affect the caller's transaction, if one exists.)

[TPEINVAL]

Invalid arguments were given (for example, eventname is NULL).

[TPENOENT]

Cannot access the TUXEDO System event broker.

[TPETRAN]

The caller is in transaction mode, TPNOTRAN was not set and tppost contacted an event broker that does not support transaction propagation (that is, TMUSREVT(5) is not running in a TUXEDO System group that supports transactions).

[TPETIME]

A timeout occurred. If the caller is in transaction mode, then a transaction timeout occurred and the transaction is to be aborted; otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME were specified. If a transaction timeout occurred, any attempts to do new work will fail with TPETIME until the transaction has been aborted.

[TPESVCFAIL]

The event broker encountered an error posting a transactional event to either a service routine or to a stable storage queue on behalf of the caller's transaction. The caller's current transaction is marked abort-only. When this error is returned, tpurcode contains the number of non-transactional event notifications dispatched by the event broker on behalf of eventname; transactional postings are not counted since their effects will be aborted upon completion of the transaction. Note that so long as the transaction has not timed out, further communication may be performed before aborting the transaction and that any work performed on behalf of the caller's transaction will be aborted upon transaction completion (that is, for subsequent communication to have any lasting effect, it should be done with TPNOTRAN set).

[TPEBLOCK]

A blocking condition exists and TPNOBLOCK was specified.

[TPGOTSIG]

A signal was received and TPSIGRSTRT was not specified.

[TPEPROTO]

tppost was called in an improper context.

[TPESYSTEM]

A System/T error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

SEE ALSO

tpsubscribe(3c),
tpunsubscribe(3c),
EVENTS(5),
TMSYSEVT(5),
TMUSREVT(5)