Section 3c - C Functions

ATMI C Function Reference

tppost(3c)

Name

tppost()—Posts 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 BEA Tuxedo ATMI EventBroker 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 BEA Tuxedo ATMI system itself.

If data is non-NULL, it must point to a buffer previously allocated by tpalloc() 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 EventBroker. 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 EventBroker 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(). 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(), are also dispatched by the EventBroker but not as part of the posting process's transaction.

If the poster is outside a transaction, tppost() is a one-way post with no acknowledgement when the service associated with the event fails. This occurs even when TPEVTRAN is set for that event (using the ctl—>flags parameter passed to tpsubscribe()). If the poster is in a transaction, then tppost() returns TPESVCFAIL when the associated service fails in the event.

The 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 EventBroker 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 reissued. When TPSIGRSTRT is not specified and a signal interrupts a system call, then tppost() fails and tperrno is set to TPGOTSIG.

In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tppost().

Return Values

Upon successful return from tppost(), tpurcode() contains the number of event notifications dispatched by the EventBroker 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 EventBroker on behalf of eventname.

Upon failure, tppost() returns -1 sets tperrno to indicate the error condition.

Errors

Upon failure, tppost() 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 BEA Tuxedo User EventBroker.

[TPETRAN]

The caller is in transaction mode, TPNOTRAN was not set and tppost() contacted an EventBroker that does not support transaction propagation (that is, TMUSREVT(5) is not running in a BEA Tuxedo ATMI system group that supports transactions).

[TPETIME]

This error code indicates that either a timeout has occurred or tppost() has been attempted, in spite of the fact that the current transaction is already marked rollback only.

If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout cannot occur if TPNOBLOCK and/or TPNOTIME is specified.)

If a transaction timeout has occurred, then, with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller's transaction (that is, tpacall() with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set).

When tppost() fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME.

[TPESVCFAIL]

The EventBroker 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 EventBroker 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 improperly.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.