ENQUEUE v13
The ENQUEUE procedure adds an entry to a queue. The signature is:
ENQUEUE( <queue_name> IN VARCHAR2, <enqueue_options> IN DBMS_AQ.ENQUEUE_OPTIONS_T, <message_properties> IN DBMS_AQ.MESSAGE_PROPERTIES_T, <payload> IN <type_name>, <msgid> OUT RAW)
Parameters
queue_name
The name (optionally schema-qualified) of an existing queue. If you omit the schema name, the server will use the schema specified in the SEARCH_PATH. Please note that unlike Oracle, unquoted identifiers are converted to lower case before storing. To include special characters or use a case-sensitive name, enclose the name in double quotes.
For detailed information about creating a queue, see DBMS_AQADM.CREATE_QUEUE.
enqueue_options
enqueue_options is a value of the type, enqueue_options_t:
DBMS_AQ.ENQUEUE_OPTIONS_T IS RECORD( visibility BINARY_INTEGER DEFAULT ON_COMMIT, relative_msgid RAW(16) DEFAULT NULL, sequence_deviation BINARY INTEGER DEFAULT NULL, transformation VARCHAR2(61) DEFAULT NULL, delivery_mode PLS_INTEGER NOT NULL DEFAULT PERSISTENT);
Currently, the only supported parameter values for enqueue_options_t are:
visibility | ON_COMMIT. |
|---|---|
delivery_mode | PERSISTENT |
sequence_deviation | NULL |
transformation | NULL |
relative_msgid | NULL |
message_properties
message_properties is a value of the type, message_properties_t:
message_properties_t IS RECORD( priority INTEGER, delay INTEGER, expiration INTEGER, correlation CHARACTER VARYING(128) COLLATE pg_catalog.”C”, attempts INTEGER, recipient_list “AQ$_RECIPIENT_LIST_T”, exception_queue CHARACTER VARYING(61) COLLATE pg_catalog.”C”, enqueue_time TIMESTAMP WITHOUT TIME ZONE, state INTEGER, original_msgid BYTEA, transaction_group CHARACTER VARYING(30) COLLATE pg_catalog.”C”, delivery_mode INTEGER DBMS_AQ.PERSISTENT);
The supported values for message_properties_t are:
priority | If the queue table definition includes a sort_list that references priority, this parameter affects the order that messages are dequeued. A lower value indicates a higher dequeue priority. |
delay | Specify the number of seconds that will pass before a message is available for dequeueing or NO_DELAY. |
expiration | Use the expiration parameter to specify the number of seconds until a message expires. |
correlation | Use correlation to specify a message that will be associated with the entry; the default is NULL. |
attempts | This is a system-maintained value that specifies the number of attempts to dequeue the message. |
recipient_list | This parameter is not supported. |
exception_queue | Use the exception_queue parameter to specify the name of an exception queue to which a message will be moved if it expires or is dequeued by a transaction that rolls back too many times. |
enqueue_time | enqueue_time is the time the record was added to the queue; this value is provided by the system. |
state | This parameter is maintained by DBMS_AQ; state can be:DBMS_AQ.WAITING – the delay has not been reached.DBMS_AQ.READY – the queue entry is ready for processing.DBMS_AQ.PROCESSED – the queue entry has been processed.DBMS_AQ.EXPIRED – the queue entry has been moved to the exception queue. |
original_msgid | This parameter is accepted for compatibility and ignored. |
transaction_group | This parameter is accepted for compatibility and ignored. |
delivery_mode | This parameter is not supported; specify a value of DBMS_AQ.PERSISTENT. |
payload
Use the payload parameter to provide the data that will be associated with the queue entry. The payload type must match the type specified when creating the corresponding queue table (see DBMS_AQADM.CREATE_QUEUE_TABLE).
msgid
Use the msgid parameter to retrieve a unique (system-generated) message identifier.
Example
The following anonymous block calls DBMS_AQ.ENQUEUE, adding a message to a queue named work_order:
DECLARE
enqueue_options DBMS_AQ.ENQUEUE_OPTIONS_T;
message_properties DBMS_AQ.MESSAGE_PROPERTIES_T;
message_handle raw(16);
payload work_order;
BEGIN
payload := work_order('Smith', 'system upgrade');
DBMS_AQ.ENQUEUE(
queue_name => 'work_order',
enqueue_options => enqueue_options,
message_properties => message_properties,
payload => payload,
msgid => message_handle
);
END;