| Programming Guide | |
Releases a message from a reliable queue
dequeue QSPACEqueueSpaceNAMEqueuemessage[which]
[inputOption]... [outputOption]...
QSPACEqueueSpace- Names the queue space to which queue belongs.
NAMEqueue- Names the queue as defined in the JIF.
message- A message output argument to receive the dequeued message. The argument's format must conform to the message data type as specified in the queue's JIF definition. For more information on message data types, refer to "Service Messages and Data Types" in JetNet/Oracle Tuxedo Guide.
which- Specifies which message to dequeue; use one of the following arguments. If no argument is supplied, the first message in the queue is removed.
FIRST_AVAILABLE [WAIT]Remove the first message in the queue. This is the default behavior if no argument is supplied. If the queue is empty, the
WAIToption specifies to wait until a message becomes available for dequeuing; otherwise, an error message is posted.Note, you should only use
FIRST_AVAILABLE WAITif there is more than oneTMQUEUEserver running, otherwise the one server will wait indefinitely for a message that cannot be enqueued. For further information on Oracle Tuxedo-provided servers, consult your Oracle Tuxedo documentation.BY_MSGIDmsgId- Dequeue the message corresponding to
msgId. The message identifier is generated when the message is successfully enqueued.BY_CORRIDcorrID- Dequeue the message corresponding to
corrID. The correlation identifier is set by the application when enqueuing the message.inputOption- Use one or more of the following options to control the behavior of
dequeue:
NOTIMEOUT- Specifies that the dequeue operation is unaffected by the blocking timeout; however, transaction timeouts remain in effect.
OUTSIDE_TRANSACTION- Specifies to perform the dequeuing operation outside the current transaction. If message dequeuing 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.
outputOption- Use any the following keywords to set output arguments with information about the dequeued message:
APPL_AUTH_KEYkey- Returns the application authentication key associated with the client that enqueued the message.
CLIENTclientId- Returns the client ID of the agent that originated the request.
CORRIDcorrID- Returns the message's correlation ID, set by enqueue. For more information about using correlation IDs, refer to the enqueue command.
FAILUREQqueue- Returns the name of the queue where a failure message should be stored. The value is set if the dequeued message is associated with a failure queue.
MSGIDqMsgId- Returns the unique message ID if set and the dequeue was successful. The identifier is generated when the message is successfully enqueued.
PRIORITYpriority- Returns the message's priority relative to other messages in the queue as an integer between 1 and 100, where 100 indicates the highest priority. A message with the highest number is dequeued before all others.
RCODEreturnCode- Returns the return code specified by enqueue when the message was enqueued.
REPLYQqueue- Returns the name of queue where the reply message should be stored. The value is set if the dequeued message is associated with a reply queue.
Oracle Tuxedo
Client, Server
The dequeue command removes a message from the specified queue. You can identify the message you want dequeued; otherwise, dequeue uses the first message. The order of messages in the queue is specified when they are enqueued. You can request a particular message for dequeuing by specifying its message identifier (
BY_MSGIDmsgId) or correlation ID (BY_CORRIDcorrID). You can also indicate that the application wait for a message that is not immediately available.When
dequeueis successful, it can return additional information about the message:
- The message identifier for the dequeued message.
You can determine the success or failure of
dequeueby checking the severity level that is set in thetp_severityproperty.For more information about Oracle Tuxedo System /Q, refer to "Reliable Queues" in JetNet/Oracle Tuxedo Guide and refer to your Oracle Tuxedo documentation.
dequeuecan generate the following exceptions:
enqueue