Programming Guide


Places a message on a reliable queue


enqueue QSPACE queueSpace NAME queueName message 
[enqueueOption]... [ MSGID msgId]


QSPACE queueSpace
Specifies queueName's queue space.

NAME queueName
The name of the queue as defined in the JIF.

The message data to enqueue, as defined by the queue data type description in the JIF. For more information on message data types, refer to "Service Messages and Data Types" in JetNet/Oracle Tuxedo Guide.

One or more of the following options:

Associates the message with a queue-independent identifier of up to 32 characters. Because this identifier can be maintained across all queues, the dequeue command can use it to identify a message. Other related messages can also be enqueued with it, such as reply or failure messages that are associated with message.

DQTIME dequeueTime
Specifies when to make the message available for dequeuing. If you omit this option, the message can be dequeued immediately. This option is valid only if the queue has been configured for time-based ordering; that is, queue order is set to time. For more information, refer to the Oracle Tuxedo /Q Guide of the Oracle Tuxedo SDK in your Oracle Tuxedo documentation.

The server dequeues the message and calls the appropriate service if it is monitoring the queue. dequeueTime can be a relative time (time elapsed after the message is enqueued) or an absolute time. An absolute time must be greater than January 1 1970 00:00:00 UTC. In either case, Panther can dequeue the command only after the specified amount of time has elapsed.

A relative dequeueTime can be specified in this format:

	"[ +days hours::minutes::]seconds"

Seconds are required; minutes, hours, or days (space delimiter between days and hours) can also be specified. If more than seconds is specified, the + symbol and the quotation marks are mandatory. If only seconds are specified, both are optional.

Note: JPL's colon preprocessor expands colon-prefixed variables. To prevent expansion of variables that contain colons, you must prefix literal colons with another colon (::) or a backslash (\:).

An absolute dequeueTime can be specified in one of these ways:

Specify a failure queue for failure responses, or use NOFAILUREQ if no failure message is expected. If neither option is specified, the JIF is checked for the default failure queue.

Place the message in the queue:

Specifies that the enqueue operation is unaffected by the blocking timeout. This option has no effect on transaction timeouts. If you omit this option, Panther use the setting in the tp_timeout property.

Specifies to perform the enqueuing operation outside the current transaction. If message enqueuing fails, the current transaction is unaffected. If you specify this option, transaction-level exception and unload handlers are not executed when their corresponding events are generated.

PRIORITY priority
An integer between 1 and 100, inclusive, that establishes the message's priority, where 100 specifies the highest priority. This option is valid only if the queue's queue order parameter includes a priority setting. An out-of-range priority value generates the exception TP_INVALID_OPTION_VALUE. For further information on priority enqueuing, refer to the Oracle Tuxedo /Q Guide of the Oracle Tuxedo SDK in your Oracle Tuxedo documentation.

RCODE returnCode
An integer that specifies the return status to be made available to the dequeuing agent. The return code is handed to the reply queue from the service that replies to the message.

Specifies a reply queue for replies to the message, or that no reply message is wanted (NOREPLYQ). If neither option is specified, the JIF is checked for a reply queue.

On return, msgId contains the unique Oracle Tuxedo message identifier that is generated after enqueue executes successfully. You can use this identifier to reference the enqueued message as long as it remains on the original queue.


JetNet, Oracle Tuxedo


Client, Server


The enqueue command puts a message in the specified queue. You identify the queue by specifying its queue name and queue space. This queue must be defined in the JIF; otherwise, the command fails and generates the exception TP_IN VALID_QUEUE. The enqueued message must conform to the data type defined in the JIF for the designated queue.

An enqueued message can only be removed from its queue by the dequeue command, and only after the DQTIME time delay (if any) elapses. The reply to this message is put in the REPLYQ-specified reply queue or, if this option is omitted, in the reply queue specified in queueName's JIF definition. enqueue can also specify a failure queue to supersede the one specified by the JIF. You can prevent reply and failure queueing with the NOREPLYQ and NOFAILUREQ options, respectively.

By default, messages are enqueued in first-in/first-out (FIFO) order. You can rely on this ordering when dequeuing messages, or you can use specific identifiers. Two kinds of identifiers are available:

enqueue sets the tp_return property to NULL.

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

See Also

enqueue can generate the following exceptions:

Exception Severity Cause

Command syntax is invalid.


Unable to resolve reference to Panther variable.


An invalid time value is specified in the DQTIME option or PRIORITY value is out-of-range.


Queue is not defined in the JIF.


Queuespace not found in the JIF.


There is no current transaction.

See Also