|
|
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:
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.)
See Also
tpsubscribe(3c), tpunsubscribe(3c), EVENTS(5), TMSYSEVT(5), TMUSREVT(5)
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|