Places a message on a reliable queue
enqueueOption]... [ MSGID
queueName's queue space.
- 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.
- 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.
dequeueTimecan 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.
dequeueTimecan be specified in this format:
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 (
dequeueTimecan be specified in one of these ways:
- Specify a failure queue for failure responses, or use
NOFAILUREQif 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:
FRONT—Put the message at the head of 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
- 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.
- 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.
- 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,
msgIdcontains 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
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
DQTIMEtime 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
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:
- The Oracle Tuxedo-assigned message identifier that is returned with a successful enqueue command; you obtain this identifier through the
- A correlation ID that you explicitly assign to the enqueued message. This identifier is independent of the queue in which the message is placed; you should assign a correlation ID in order to identify the reply or failure messages that are generated in response to a dequeued message.
enqueue sets the
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.
enqueue can generate the following exceptions:
Exception Severity Cause TP_INVALID_COMMAND_SYNTAX TP_COMMAND
Command syntax is invalid.
TP_INVALID_VARIABLE_REF TP_COMMAND or TP_WARNING
Unable to resolve reference to Panther variable.
An invalid time value is specified in the
PRIORITYvalue is out-of-range.
Queue is not defined in the JIF.
Queuespace not found in the JIF.
There is no current transaction.