Advanced Queuing

Dequeue Options

Note

This object is an extension to the DB API. It is returned by the deqoptions() call and is used in calls to deq().

DeqOptions.condition

This attribute specifies a boolean expression similar to the where clause of a SQL query. The boolean expression can include conditions on message properties, user data properties and PL/SQL or SQL functions.

DeqOptions.consumername

This attribute specifies the name of the consumer. Only messages matching the consumer name will be accessed. If the queue is not set up for multiple consumers this attribute should not be set.

DeqOptions.correlation

This attribute specifies the correlation identifier of the message to be dequeued. Special pattern-matching characters, such as the percent sign (%) and the underscore (_), can be used. If multiple messages satisfy the pattern, the order of dequeuing is indeterminate.

DeqOptions.deliverymode

This write-only attribute specifies whether persistent (cx_Oracle.MSG_PERSISTENT), buffered (cx_Oracle.MSG_BUFFERED) or both (cx_Oracle.MSG_PERSISTENT_OR_BUFFERED) types of messages should be dequeued.

DeqOptions.mode

This attribute specifies the locking behaviour associated with the dequeue operation. The valid values are cx_Oracle.DEQ_BROWSE (the message is read without acquiring any lock on the message), cx_Oracle.DEQ_LOCKED (the message is read and a write lock is obtained), cx_Oracle.DEQ_REMOVE (the message is read and updated or deleted, which is also the default value) or cx_Oracle.DEQ_REMOVE_NODATA (which confirms receipt of the message but does not deliver the actual message content).

DeqOptions.msgid

This attribute specifies the identifier of the message to be dequeued.

DeqOptions.navigation

This attribute specifies the position of the message that is retrieved. The valid values are cx_Oracle.DEQ_FIRST_MSG (retrieves the first available message that matches the search criteria), cx_Oracle.DEQ_NEXT_MSG (retrieves the next available message that matches the search criteria, which is also the default value), or cx_Oracle.DEQ_NEXT_TRANSACTION (skips the remainder of the current transaction group and retrieves the first message of the next transaction group).

DeqOptions.transformation

This attribute specifies the name of the transformation that must be applied after the message is enqueued from the database but before it is returned to the calling application. The transformation must be created using dbms_transform.

DeqOptions.visibility

This attribute specifies the transactional behavior of the enqueue request. It must be one of cx_Oracle.ENQ_ON_COMMIT indicating that the enqueue is part of the current transaction (the default) or cx_Oracle.ENQ_IMMEDIATE indicating that the enqueue operation constitutes a transaction of its own. This parameter is ignored when using the DEQ_BROWSE mode.

Enqueue Options

Note

This object is an extension to the DB API. It is returned by the enqoptions() call and is used in calls to enq().

EnqOptions.deliverymode

This write-only attribute specifies whether persistent (cx_Oracle.MSG_PERSISTENT) or buffered (cx_Oracle.MSG_BUFFERED) messages should be enqueued.

EnqOptions.transformation

This attribute specifies the name of the transformation that must be applied before the message is enqueued into the database. The transformation must be created using dbms_transform.

EnqOptions.visibility

This attribute specifies the transactional behavior of the enqueue request. It must be one of cx_Oracle.ENQ_ON_COMMIT indicating that the enqueue is part of the current transaction (the default) or cx_Oracle.ENQ_IMMEDIATE indicating that the enqueue operation constitutes a transaction of its own.

Message Properties

Note

This object is an extension to the DB API. It is returned by the msgproperties() call and is used in calls to deq() and enq().

MessageProperties.attempts

This read-only attribute specifies the number of attempts that have been made to dequeue the message.

MessageProperties.correlation

This attribute specifies the correlation used when the message was enqueued.

MessageProperties.delay

This attribute specifies the number of seconds to delay an enqueued message. Any integer is acceptable but the constant cx_Oracle.MSG_NO_DELAY can also be used indicating that the message is available for immediate dequeuing.

EnqOptions.deliverymode

This read-only attribute specifies whether a persistent (cx_Oracle.MSG_PERSISTENT) or buffered (cx_Oracle.MSG_BUFFERED) message was dequeued.

EnqOptions.enqtime

This read-only attribute specifies the time that the message was enqueued.

EnqOptions.exceptionq

This attribute specifies the name of the queue to which the message is moved if it cannot be processed successfully. Messages are moved if the number of unsuccessful dequeue attempts has exceeded the maximum number of retries or if the message has expired. All messages in the exception queue are in the EXPIRED state. The default value is the name of the exception queue associated with the queue table.

EnqOptions.expiration

This attribute specifies, in seconds, how long the message is available for dequeuing. This attribute is an offset from the delay attribute. Expiration processing requires the queue monitor to be running. Any integer is accepted but the constant cx_Oracle.MSG_NO_EXPIRATION can also be used indicating that the message never expires.

EnqOptions.msgid

This attribute specifies the id of the message in the last queue that generated this message.

EnqOptions.priority

This attribute specifies the priority of the message. A smaller number indicates a higher priority. The priority can be any integer, including negative numbers. The default value is zero.

EnqOptions.state

This read-only attribute specifies the state of the message at the time of the dequeue. It will be one of cx_Oracle.MSG_WAITING (the message delay has not yet been reached), cx_Oracle.MSG_READY (the message is ready to be processed), cx_Oracle.MSG_PROCESSED (the message has been processed and is retained) or cx_Oracle.MSG_EXPIRED (the message has been moved to the exception queue).