Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
Tuxedo Doc Home   |   Reference   |   Topic List   |   Previous   |   Next   |   Contents

   BEA Tuxedo COBOL Function Reference

TPUNSUBSCRIBE() - unsubscribe to an event

01 TPEVTDEF-REC.
COPY TPEVTDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPUNSUBSCRIBE" USING TPEVTDEF-REC 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.

TPNOBLOCK

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.

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.

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.)

[TPEINVAL]

Invalid arguments were given (for example, SUBSCRIPTION-HANDLE is an invalid subscription handle).

[TPENOENT]

Cannot access the BEA Tuxedo EventBroker.

[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.

[TPEBLOCK]

A blocking condition exists and TPNOBLOCK was specified.

[TPGOTSIG]

A signal was received and TPNOSIGRSTRT was specified.

[TPEPROTO]

TPUNSUBSCRIBE() 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.

TPPOST(3cbl), TPSUBSCRIBE(3cbl), EVENTS(5), EVENT_MIB(5), TMSYSEVT(5), TMUSREVT(5)