ATMI COBOL Function Reference
TPUNSUBSCRIBE()
- unsubscribe to an event
01
TPEVTDEF-REC.
TPSTATUS-REC
COPY TPEVTDEF.
01 .
TPEVTDEF-REC
COPY TPSTATUS.
CALL "TPUNSUBSCRIBE" USING
TPSTATUS-REC.
The caller uses TPUNSUBSCRIBE()
to remove an event subscription or a set of event subscriptions from the BEA Tuxedo EventBroker's list of active subscriptions. SUBSCRIPTION-HANDLE
in TPEVTDEF-REC
is an event subscription handle returned by TPSUBSCRIBE()
. Setting SUBSCRIPTION-HANDLE
to the wildcard value, -1, directs TPUNSUBSCRIBE()
to unsubscribe to all non-persistent subscriptions previously made by the calling process. Non-persistent subscriptions are those made with TPEVNOPERSIST
set when TPSUBSCRIBE()
was called. Persistent subscriptions can be deleted only by using the handle returned by TPSUBSCRIBE()
.
Note that the -1
handle removes only those subscriptions made by the calling process and not any made by previous instantiations of the caller (for example, a server that dies and restarts cannot use the wildcard to unsubscribe to any subscriptions made by the original server).
The following is a list of valid settings in TPEVTDEF-REC
.
The subscription is not removed 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, TPUNSUBSCRIBE()
sets TP-STATUS
to [TPOK
]. In addition, TPUNSUBSCRIBE()
sets EVENT-COUNT
in TPEVTDEF-REC
to the number of subscriptions deleted (zero or greater) from the EventBroker's list of active subscriptions. EVENT-COUNT
may contain a number greater than 1 only when the wildcard handle, -1, is used. Also, EVENT-COUNT
may contain a number greater than 0 even when TPUNSUBSCRIBE()
completes unsuccessfully (that is, when the wildcard handle is used, the EventBroker may have successfully removed some subscriptions before it encountered an error deleting others).
Under the following conditions, TPUNSUBSCRIBE()
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.)
This error code indicates that either a timeout has occurred or TPUNSUBSCRIBE()
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 a transactional ATMI call 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
.
TPPOST(3cbl)
, TPSUBSCRIBE(3cbl)
, EVENTS(5), EVENT_MIB(5), TMSYSEVT(5), TMUSREVT(5)