PURPOSE

tpunsubscribe - unsubscribe to an event

SYNOPSIS

#include <atmi.h>
int tpunsubscribe(long subscription, long flags)

DESCRIPTION

The caller uses tpunsubscribe to remove an event subscription or a set of event subscriptions from the TUXEDO System Event Broker's list of active subscriptions. subscription is an event subscription handle returned by tpsubscribe(3c). Setting subscription to the wild-card value, -1, directs tpunsubscribe to unsubscribe to all non-persistent subscriptions previously made by the calling process. Non-persistent subscriptions are those made without the TPEVPERSIST bit setting in the ctl->flags parameter of tpsubscribe(3c). Persistent subscriptions can be deleted only by using the handle returned by tpsubscribe(3c).

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 wild-card to unsubscribe to any subscriptions made by the original server).

Following is a list of valid flags.

TPNOBLOCK

The subscription is not removed if a blocking condition exists. If such a condition occurs, the call fails and tperrno is set to TPEBLOCK. When TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout).

TPNOTIME

This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.

TPSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted system call is re-issued. When TPSIGRSTRT is not specified and a signal interrupts a system call, then tpunsubscribe fails and tperrno is set to TPGOTSIG.

RETURN VALUES

Upon completion of tpunsubscribe, tpurcode() contains the number of subscriptions deleted (zero or greater) from the event broker's list of active subscriptions. tpurcode may contain a number greater than 1 only when the wild-card handle, -1, is used. Also, tpurcode may contain a number greater than 0 even when tpunsubscribe completes unsuccessfully (that is, when the wild-card handle is used, the event broker may have successfully removed some subscriptions before it encountered an error deleting others). tpunsubscribe returns -1 on error and sets tperrno to indicate the error condition.

ERRORS

Under the following conditions, tpunsubscribe fails and sets tperrno 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 is an invalid subscription handle).

[TPENOENT]

Cannot access the TUXEDO System event broker.

[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 neither TPNOBLOCK nor TPNOTIME 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 TPSIGRSTRT was not specified.

[TPEPROTO]

tpunsubscribe was called in an improper context.

[TPESYSTEM]

A System/T error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

SEE ALSO

EVENTS(5),
EVENT_MIB(5),
TMSYSEVT(5),
TMUSREVT(5),
tppost(3c),
tpsubscribe(3c)