ATMI COBOL Function Reference
01
TPEVTDEF-REC
.
COPY TPEVTDEF.
01TPTYPE-REC
.
COPY TPTYPE.
01DATA-REC
.
COPY User data.
01TPSTATUS-REC
.
COPY TPSTATUS.
CALL "TPPOST" USINGTPEVTDEF-REC
TPTYPE-REC
DATA-REC
TPSTATUS-REC
.
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
:
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.
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.
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.
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.
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.
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.
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.
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.
If a signal interrupts any underlying system calls, then the interrupted system call is reissued. Either TPNOSIGRSTRT
or TPSIGRSTRT
must be set.
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
.
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.)
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).
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 can occur only if both TPBLOCK
and TPTIME
are 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
.
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).
TPSUBSCRIBE(3cbl)
, TPUNSUBSCRIBE(3cbl)
, EVENTS(5), TMSYSEVT(5), TMUSREVT(5)