Programming Guide


Subscribes to an event managed by the Oracle Tuxedo event broker


subscribe EVENT eventName NOTIFICATION notificationSpec


EVENT eventName
The name of an event. eventName is any regular expression containing up to 255 characters. For information about regular expressions, refer to recomp() in the Oracle Tuxedo Reference Manual.

NOTIFICATION notificationSpec
Method of notification to the subscriber when the event is posted, formatted as follows:
{SERVICE serviceName | ENQUEUE enqueueSpec}

SERVICE serviceName
Notification is done via a call to the service serviceName. The event broker calls serviceName to notify the agent of the event.

ENQUEUE enqueueSpec
Notification is done via enqueuing a message to a reliable queue. enqueueSpec has this format:
QSPACE queueSpace NAME queueName [queueOption [queueOption]...]

QSPACE queueSpace
The name of the queue space to which the queue belongs.

NAME queueName
The name of the queue.

One or more of the enqueuing options listed in the "Enqueue Options" section.

Specifies that event notifications are dispatched outside of the current transaction. If this option is not used, the default behavior is notification within the current transaction.

Maintains the event subscription regardless of any error situation. By default, subscriptions are deleted when a resource is not available to an event poster.

A filter rule to apply when the event broker determines that the subscriber should be notified of an event. rule is a string expression of up to 255 characters. The rule is applied to the message data of the event posting. This option is available for FML and STRING types only.

Specify that the execution of this command is unaffected by the blocking timeout.
Enqueue Options


Oracle Tuxedo


Client, Server


The subscribe command permits agents to subscribe to events managed by the event broker. Once an event is posted via the post command, subscribers to the event are notified in the manner determined by the arguments to this command.

When the subscribing agent is a client, event notification is done via an unsolicited message. A client can receive unsolicited notifications only if it has appropriate message handling. Refer to the client_init and receive commands for information on how to permit clients to receive unsolicited messages.

For servers subscribing to events, there are two methods of notification: notification by service call and notification by message queuing.

Before notification is initiated, the event broker, after successfully matching the event to its potential subscribers via the EVENT eventName, applies the subscribers filter rule if one was used. If the data passes through the filter rule, the subscriber is notified via the method selected with notificationSpec.

Successful execution of the subscribe command results in a unique subscription ID, which can be accessed from the tp_return property. If the command fails, tp_return is set to TP_FAILURE.

For additional information on message queuing, refer to "Reliable Queues" in JetNet/Oracle Tuxedo Guide and refer to your Oracle Tuxedo System /Q documentation.

Filter Rule Syntax

The filter rule is contained in a string of up to 255 characters. The rule format is specific to the type of event message data—FML or STRING—of the event's data to which it is applied.

FML filters can be built from primary expressions, regular expressions, and operators. A STRING filter must be in the form of a regular expression. For information about regular expressions, refer to recomp() in the Oracle Tuxedo Reference Manual; for information about operators and primary expressions, refer to the Oracle Tuxedo FML Guide.


Because subscribe uses message queues, it can raise some of the same exceptions as the enqueue command.

Exception Severity Cause

Command syntax is invalid.


Priority value is not between 1 and 100 or an invalid time value was specified


Queue is not declared in the JIF


Queuespace not found in the JIF.


// Client
// The client will receive an unsolicited message
// along with any data posted with the event.
subscribe EVENT "user*" FILTER "*something*"
// Server
// The server will receive notification via a call
// to the service "svc1"
subscribe EVENT "user*" FILTER "*something" \
// Server
// The server will receive notification via enqueuing the
// message to the queue "queue1" in queue space "qspace1."
"qspace1" NAME "queue1" PRIORITY 5 REPLYQ "rqueue1" NOTIMEOUT

See Also

enqueue, dequeue, post, unsubscribe