TPPOST(3cbl)


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| COBOL Function Reference \| Local Topics \| Previous Topic \| Next Topic \| Contents

TPPOST(3cbl)

Name

TPPOST() - post an event

Synopsis

01 TPEVTDEF-REC.
 COPY TPEVTDEF. 
 
01 TPTYPE-REC.
 COPY TPTYPE. 
 
01 DATA-REC.
 COPY User data. 
 
01 TPSTATUS-REC.
 COPY TPSTATUS. 
 
CALL "TPPOST" USING TPEVTDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

Description

The caller uses TPPOST() to post an event and any accompanying data. The event is named by EVENT-NAME in TPEVTDEF-REC and DATA-REC contains the data to be posted. The posted event and its data are dispatched by the BEA Tuxedo EventBroker to all subscribers whose subscriptions successfully evaluate against EVENT-NAME and whose optional filter rules successfully evaluate against DATA-REC.

EVENT-NAME must be 31 characters or less, but cannot be SPACES. EVENT-NAME's first character cannot be a dot (".") as this character is reserved as the starting character for all events defined by the BEA Tuxedo system itself.

DATA-REC is the typed record to be posted and LEN in TPTYPE-REC specifies the amount of data in DATA-REC that should be posted with the event. Note that if DATA-REC is a record of a type that does not require a length to be specified, then LEN is ignored (and may be 0). If DATA-REC is a record of a type that does require a length to be specified, then LEN must not be 0 (if it is 0, no data will be posted). If REC-TYPE in TPTYPE-REC is SPACES, DATA-REC and LEN are 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 TPTRAN is 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 had TPEVTRAN set in TPEVTDEF-REC when the subscription was made. Client notifications, and those service routine and stable-storage queue subscriptions that had TPEVNOTRAN set in TPEVTDEF-REC when the subscription was made, are also dispatched by the EventBroker but not as part of the posting process' transaction.

The following is a list of valid settings in TPEVTDEF-REC:

TPNOTRAN

If the caller is in transaction mode and this setting is used, then the event posting is not made on behalf of the caller's transaction. A caller in transaction mode that uses this setting is still subject to the transaction timeout (and no other). If the event posting fails, the caller's transaction is not affected. Either TPNOTRAN or TPTRAN must be set.

TPTRAN

If the caller is in transaction mode and this setting is used, then the event posting is made on behalf of the caller's transaction. This setting is ignored if the caller is not in transaction mode. Either TPNOTRAN or TPTRAN must be set.

TPNOREPLY

Informs TPPOST() not to wait for the EventBroker to process all subscriptions for EVENT-NAME before returning. When TPNOREPLY is set, EVENT-COUNT in TPEVTDEF-REC is set to zero regardless of whether TPPOST() returns successfully or not. When the caller is in transaction mode, this setting cannot be used when TPTRAN is also set. Either TPNOREPLY or TPREPLY must be set.

TPREPLY

Informs TPPOST() to wait for all subscriptions to be processed before returning. When TPREPLY is set, the routine returns [TPOK] on success and sets EVENT-COUNT in TPEVTDEF-REC to the number of event notifications dispatched by the EventBroker on behalf of EVENT-NAME. When the caller is in transaction mode, this setting must be used when TPTRAN is also set. Either TPNOREPLY or TPREPLY must be set.

TPNOBLOCK

The event is not posted if a blocking condition exists. If such a condition occurs, the call fails and sets TP-STATUS to [TPEBLOCK]. Either TPNOBLOCK or TPBLOCK must be set.

TPBLOCK

When TPBLOCK is specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either TPNOBLOCK or TPBLOCK must be set.

TPNOTIME

This setting signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur. Either TPNOTIME or TPTIME must be set.

TPTIME

This setting signifies that the caller will receive blocking timeouts if a blocking condition exists and the blocking time is reached. Either TPNOTIME or TPTIME must be set.

TPSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted system call is reissued. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

TPNOSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted system call is not restarted, the call fails and sets TP-STATUS to [TPGOTSIG]. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

Return Values

Upon successful completion, TPPOST() sets TP-STATUS to [TPOK]. In addition, EVENT-COUNT contains the number of event notifications dispatched by the EventBroker on behalf of EVENT-NAME (that is, postings for those subscriptions whose event expression evaluated successfully against EVENT-NAME and whose filter rule evaluated successfully against DATA-REC). Upon return where TP-STATUS is set to [TPESVCFAIL], EVENT-COUNT contains the number of non-transactional event notifications dispatched by the EventBroker on behalf of EVENT-NAME.

Errors

Under the following conditions, TPPOST() fails and sets TP-STATUS 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, EVENT-NAME is SPACES).

[TPENOENT]

Cannot access the BEA Tuxedo User EventBroker.

[TPETRAN]

The caller is in transaction mode, TPTRAN was set, and TPPOST() contacted an EventBroker that does not support transaction propagation (that is, TMUSREVT(5) is not running in a BEA Tuxedo ATMI 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 both TPBLOCK and TPTIME 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 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, EVENT-COUNT contains the number of non-transactional event notifications dispatched by the EventBroker on behalf of EVENT-NAME; 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.