Programming Guide

subscribe

Subscribes to an event managed by the Oracle Tuxedo event broker

Synopsis

subscribe EVENT eventName NOTIFICATION notificationSpec
	ENQUEUE enqueueSpec [OUTSIDE_TRANSACTION] [PERSIST]
	[FILTER rule] [NOTIMEOUT]

Arguments

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.

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

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

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

FILTER rule
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.

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

Environment

Oracle Tuxedo

Scope

Client, Server

Description

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.

Exceptions

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

Exception Severity Cause 
TP_INVALID_COMMAND_SYNTAX
 
TP_COMMAND

Command syntax is invalid. 

TP_INVALID_OPTION_VALUE
 
TP_COMMAND

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

TP_INVALID_QUEUE
 
TP_COMMAND

Queue is not declared in the JIF 

TP_QUEUE_SPACE_NOT_IN_JIF
 
TP_COMMAND

Queuespace not found in the JIF.

Example

// 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" \
	NOTIFICATION SERVICE "svc1" OUTSIDE_TRANSACTION
 
// Server
// The server will receive notification via enqueuing the
// message to the queue "queue1" in queue space "qspace1."
 
subscribe EVENT "user*" NOTIFICATION ENQUEUE QSPACE \
	"qspace1" NAME "queue1" PRIORITY 5 REPLYQ "rqueue1" NOTIMEOUT

See Also

enqueue, dequeue, post, unsubscribe