Oracle9i Supplied PL/SQL Packages and Types Reference Release 1 (9.0.1) Part Number A89852-02 |
|
DBMS_AQ, 18 of 24
This procedure dequeues a message from the specified queue.
DBMS_AQ.DEQUEUE ( queue_name IN VARCHAR2, dequeue_options IN dequeue_options_t, message_properties OUT message_properties_t, payload OUT "<type_name>", msgid OUT RAW);
Parameter | Description |
---|---|
queue_name |
Specifies the name of the queue. |
dequeue_options |
|
message_properties |
|
payload |
Not interpreted by Oracle AQ. The payload must be specified according to the specification in the associated queue table.
For the definition of < |
msgid |
System generated identification of the message. |
The search criteria for messages to be dequeued is determined by the consumer_name
, msgid
, correlation and deq_condition
parameters in dequeue_options
.
Msgid
uniquely identifies the message to be dequeued.
WHERE
clause of a SQL query. This Boolean expression can include conditions on message properties, user data properties (object payloads only), and PL/SQL or SQL functions (as specified in the where clause of a SQL query). Message properties include priority, corrid and other columns in the queue table.
To specify dequeue conditions on a message payload (object payload), use attributes of the object type in clauses. You must prefix each attribute with tab.user_data as a qualifier to indicate the specific column of the queue table that stores the payload.
Example: tab.user_data.orderstatus='EXPRESS''
Only messages in the READY
state are dequeued unless msgid
is specified.
The dequeue order is determined by the values specified at the time the queue table is created unless overridden by the msgid
and correlation ID in dequeue_options
.
The database-consistent read mechanism is applicable for queue operations. For example, a BROWSE
call may not see a message that is enqueued after the beginning of the browsing transaction.
The default NAVIGATION
parameter during dequeue is NEXT_MESSAGE
. This means that subsequent dequeues will retrieve the messages from the queue based on the snapshot obtained in the first dequeue. In particular, a message that is enqueued after the first dequeue command will be processed only after processing all the remaining messages in the queue. This is usually sufficient when all the messages have already been enqueued into the queue, or when the queue does not have a priority-based ordering. However, applications must use the FIRST_MESSAGE
n
avigation option when the first message in the queue needs to be processed by every dequeue command. This usually becomes necessary when a higher priority message arrives in the queue while messages already-enqueued are being processed.
Messages enqueued in the same transaction into a queue that has been enabled for message grouping will form a group. If only one message is enqueued in the transaction, then this will effectively form a group of one message. There is no upper limit to the number of messages that can be grouped in a single transaction.
In queues that have not been enabled for message grouping, a dequeue in LOCKED
or REMOVE
mode locks only a single message. By contrast, a dequeue operation that seeks to dequeue a message that is part of a group will lock the entire group. This is useful when all the messages in a group need to be processed as an atomic unit.
When all the messages in a group have been dequeued, the dequeue returns an error indicating that all messages in the group have been processed. The application can then use the NEXT_TRANSACTION
to start dequeuing messages from the next available group. In the event that no groups are available, the dequeue will time-out after the specified WAIT
period.
|
Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|