ATMI C Function Reference
tpsubscribe()
—Subscribes to an event.
#include <atmi.h>
long tpsubscribe(char *eventexpr, char *filter, TPEVCTL *ctl, long flags)
The caller uses tpsubscribe()
to subscribe to an event or set of events named by eventexpr
. Subscriptions are maintained by the BEA Tuxedo ATMI EventBroker, TMUSREVT(5), and are used to notify subscribers when events are posted via tppost()
. Each subscription specifies a notification method which can take one of three forms: client notification, service calls, or message enqueuing to stable-storage queues. Notification methods are determined by the subscriber's process type and the arguments passed to tpsubscribe()
.
The event or set of events being subscribed to is named by eventexpr
, a NULL-terminated string of at most 255 characters containing a regular expression. For example, if eventexpr
is "\e\e..*
", the caller is subscribing to all system-generated events; if eventexpr
is "\e\e.SysServer.*
", the caller is subscribing to all system-generated events related to servers. If eventexpr
is "[A-Z].*
", the caller is subscribing to all user events starting with A-Z; if eventexpr
is ".*(ERR|err).*
", the caller is subscribing to all user events containing either the substring ERR
or the substring err
in the event name. Events called account_error
and ERROR_STATE
, for example, would both qualify. For more information on regular expressions, see Regular Expressions.
If present, filter
is a string containing a Boolean filter rule that must be evaluated successfully before the EventBroker posts the event. Upon receiving an event to be posted, the EventBroker applies the filter rule, if one exists, to the posted event's data. If the data passes the filter rule, the EventBroker invokes the notification method; otherwise, the broker does not invoke the associated notification method. The caller can subscribe to the same event multiple times with different filter rules.
Filter rules are specific to the typed buffers to which they are applied. For FML and view buffers, the filter rule is a string that can be passed to each's Boolean expression compiler (see Fboolco
(3fml) and Fvboolco
(3fml), respectively) and evaluated against the posted buffer (see Fboolev
(3fml) and Fvboolev
(3fml), respectively). For STRING
buffers, the filter rule is a regular expression. All other buffer types require customized filter evaluators (see buffer(3c)
and typesw(5) for details on adding customized filter evaluators). filter
is a NULL-terminated string of at most 255 characters.
If the subscriber is a BEA Tuxedo ATMI system client process and ctl
is NULL, then the EventBroker sends an unsolicited message to the subscriber when the event to which it subscribed is posted. That is, when an event name is posted that evaluates successfully against eventexpr
, the EventBroker tests the posted data against the filter rule associated with eventexpr
. If the data passes the filter rule or if there is no filter rule for the event, then the subscriber receives an unsolicited notification along with any data posted with the event. In order to receive unsolicited notifications, the client must register (via tpsetunsol()
) an unsolicited message handling routine. If a BEA Tuxedo ATMI system server process calls tpsubscribe()
with a NULL ctl
parameter, then tpsubscribe()
fails setting tperrno
to TPEPROTO
.
Clients receiving event notification via unsolicited messages should remove their subscriptions from the EventBroker's list of active subscriptions before exiting (see tpunsubscribe(3c)
for details). Using tpunsubscribe()
's wildcard handle, -1, clients can conveniently remove all of their "non-persistent" subscriptions which include those associated with the unsolicited notification method (see the description of TPEVPERSIST
below for subscriptions and their associated notification methods that persist after a process exits). If a client exits without removing its non-persistent subscriptions, then the EventBroker will remove them when it detects that the client is no longer accessible.
If the subscriber (regardless of process type) wants event notifications to go to service routines or to stable-storage queues, then the ctl
parameter must point to a valid TPEVCTL
structure. This structure contains the following elements:
long flags;
char name1[32];
char name2[32];
TPQCTL qctl;
Note: The service name length limit is 15 bytes. If the service name length exceeds 15 bytes, TPEINVAL
is returned.
The following is a list of valid bits for the ctl
flags
element controlling options for event subscriptions:
Setting this flag indicates that the subscriber wants event notifications to be sent to the BEA Tuxedo ATMI system service routine named in ctl
name1
. That is, when an event name is posted that evaluates successfully against eventexpr
, the EventBroker tests the posted data against the filter rule associated with eventexpr
. If the data passes the filter rule or if there is no filter rule for the event, then a service request is sent to ctl
name1
along with any data posted with the event. The service name in ctl
name1
can be any valid BEA Tuxedo ATMI system service name and it may or may not be active at the time the subscription is made. Service routines invoked by the EventBroker should return with no reply data. That is, they should call tpreturn()
with a NULL data argument. Any data passed to tpreturn()
will be dropped. TPEVSERVICE
and TPEVQUEUE
are mutually exclusive flags.
If TPEVTRAN
is also set in ctl
flags
, then if the process calling tppost()
is in transaction mode, the EventBroker calls the subscribed service routine such that it will be part of the poster's transaction. Both the EventBroker, TMUSREVT(5), and the subscribed service routine must belong to server groups that support transactions (see UBBCONFIG(5) for details). If TPEVTRAN
is not set in ctl
flags
, then the EventBroker calls the subscribed service routine such that it will not be part of the poster's transaction.
Setting this flag indicates that the subscriber wants event notifications to be enqueued to the queue space named in ctl
name1
and the queue named in ctl
name2
. That is, when an event name is posted that evaluates successfully against eventexpr
, the EventBroker tests the posted data against the filter rule associated with eventexpr
. If the data passes the filter rule or if there is no filter rule for the event, then the EventBroker enqueues a message to the queue space named in ctl
name1
and the queue named in ctl
name2
along with any data posted with the event. The queue space and queue name can be any valid BEA Tuxedo ATMI system queue space and queue name, either of which may or may not exist at the time the subscription is made.
ctl
qctl
can contain options further directing the EventBroker's enqueuing of the posted event. If no options are specified, then ctl
qctl.flags
should be set to TPNOFLAGS
. Otherwise, options can be set as described in the "Control Parameter" subsection of tpenqueue(3c)
(specifically, see the section describing the valid list of flags controlling input information for tpenqueue(3c)
). TPEVSERVICE
and TPEVQUEUE
are mutually exclusive flags.
If TPEVTRAN
is also set in ctl
flags
, then if the process calling tppost()
is in transaction mode, the EventBroker enqueues the posted event and its data such that it will be part of the poster's transaction. The EventBroker, TMUSREVT(5), must belong to a server group that supports transactions (see UBBCONFIG(5) for details). If TPEVTRAN
is not set in ctl
flags
, then the EventBroker enqueues the posted event and its data such that it will not be part of the poster's transaction.
Setting this flag indicates that the subscriber wants the event notification for this subscription to be included in the poster's transaction, if one exists. If the poster is not a transaction, then a transaction is started for this event notification. If this flag is not set, then any events posted for this subscription will not be done on behalf of any transaction in which the poster is participating. This flag can be used with either TPEVSERVICE
or TPEVQUEUE
.
By default, the BEA Tuxedo EventBroker deletes subscriptions when the resource to which it is posting is not available (for example, the EventBroker cannot access a service routine and/or a queue space/queue name associated with an event subscription). Setting this flag indicates that the subscriber wants this subscription to persist across such errors (usually because the resource will become available again in the future). When this flag is not used, the EventBroker will remove this subscription if it encounters an error accessing either the service name or queue space/queue name designated in this subscription.
If this flag is used with TPEVTRAN
and the resource is not available at the time of event notification, then the EventBroker will return to the poster such that its transaction must be aborted. That is, even though the subscription remains intact, the resource's unavailability will cause the poster's transaction to fail.
If the EventBroker's list of active subscriptions already contains a subscription that matches the one being requested by tpsubscribe()
, then the function fails setting tperrno
to TPEMATCH
. For a subscription to match an existing one, both eventexpr
and filter
must match those of a subscription already in the EventBroker's active list of subscriptions. In addition, depending on the notification method, other criteria are used to determine matches.
If the subscriber is a BEA Tuxedo ATMI system client process and ctl
is NULL (such that the caller receives unsolicited notifications when events are posted), then its system-defined client identifier (known as a CLIENTID
) is also used to detect matches. That is, tpsubscribe()
fails if eventexpr
, filter
, and the caller's CLIENTID
match those of a subscription already known to the EventBroker.
If the caller has set ctl
flags
to TPEVSERVICE
, then tpsubscribe()
fails if eventexpr
, filter
, and the service name set in ctl
name1
match those of a subscription already known to the EventBroker.
For subscriptions to stable-storage queues, the queue space, queue name, and correlation identifier are used, in addition to eventexpr
and filter
, when determining matches. The correlation identifier can be used to differentiate among several subscriptions for the same event expression and filter rule, destined for the same queue. Thus, if the caller has set ctl
flags
to TPEVQUEUE
, and TPQCOORID
is not set in ctl
qctl.flags
, then tpsubscribe()
fails if eventexpr
, filter
, the queue space name set in ctl
name1
, and the queue name set in ctl
name2
match those of a subscription (which also does not have a correlation identifier specified) already known to the EventBroker. Further, if TPQCOORID
is set in ctl
qctl.flags
, then tpsubscribe()
fails if eventexpr
, filter
, ctl
name1
, ctl
name2
, and ctl
qctl.corrid
match those of a subscription (which has the same correlation identifier specified) already known to the EventBroker.
The following is a list of valid flags
for tpsubscribe()
:
The subscription is not made 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).
This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
In a multithreaded application, a thread in the TPINVALIDCONTEXT
state is not allowed to issue a call to tpsubscribe()
.
The regular expressions described in Table 11 are much like those used in the UNIX system editor, ed
(1). The alternation operator, (|
), has been added along with some other practical things. In general, however, there should be few surprises.
Regular expressions (REs) are constructed by applying any of the following production rules one or more times.
There are three levels of precedence. In order of decreasing binding strength they are:
As indicated above, parentheses are used to give explicit precedence.
Upon successful completion, tpsubscribe()
returns a handle that can be used to remove this subscription from the EventBroker's list of active subscriptions. The subscriber or any other process is allowed to use the returned handle to delete this subscription.
Upon failure, tpsubscribe()
returns -1 and sets tperrno
to indicate the error condition.
Upon failure, tpsubscribe()
sets tperrno
to one of the following values. (Unless otherwise noted, failure does not affect the caller's transaction, if one exists.)
The client is not attached as tpsysadm
and the subscription action is either a service call or the enqueuing of a message.
This error code indicates that either a timeout has occurred or tpsubscribe()
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 cannot occur if TPNOBLOCK
and/or TPNOTIME
is 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
.
buffer(3c)
, tpenqueue(3c)
, tppost(3c)
, tpsetunsol(3c)
, tpunsubscribe(3c)
, Fboolco, Fboolco32, Fvboolco, Fvboolco32(3fml), Fboolev, Fboolev32, Fvboolev, Fvboolev32(3fml), EVENTS(5), EVENT_MIB(5), TMSYSEVT(5), TMUSREVT(5), tuxtypes(5), typesw(5), UBBCONFIG(5)