This chapter describes the types used with Oracle Streams Advanced Queuing (AQ) packages for PL/SQL, DBMS_AQ,
and DBMS_AQADM
.
See Also:
Oracle Streams Advanced Queuing User's Guide and Reference for information about using Oracle Streams AQ.This chapter contains the following topics:
This type identifies a producer or a consumer of a message.
TYPE SYS.AQ$_AGENT IS OBJECT ( name VARCHAR2(30), address VARCHAR2(1024), protocol NUMBER DEFAULT 0);
Table 185-1 AQ$_AGENT Attributes
Attribute | Description |
---|---|
|
Name of a producer or consumer of a message. The name must follow object name guidelines in the Oracle Database SQL Reference with regard to reserved characters. |
|
Protocol-specific address of the recipient. If the protocol is For example, a queue named |
|
Protocol to interpret the address and propagate the message. Protocols 1-127 are reserved for internal use. If the protocol number is in the range 128 - 255, the address of the recipient is not interpreted by Oracle Streams AQ. |
This type identifies the list of agents for which DBMS_AQ
.LISTEN
listens.
See Also:
"AQ$_AGENT Type"TYPE SYS.AQ$_AGENT_LIST_T IS TABLE OF SYS.AQ$_AGENT INDEX BY BINARY INTEGER;
This type specifies the Oracle Streams AQ descriptor received by the AQ PL/SQL callbacks upon notification.
See Also:
"MESSAGE_PROPERTIES_T Type"TYPE SYS.AQ$_DESCRIPTOR IS OBJECT ( queue_name VARCHAR2(61), consumer_name VARCHAR2(30), msg_id RAW(16), msg_prop MSG_PROP_T, gen_desc AQ$_NTFN_DESCRIPTOR);
Table 185-2 AQ$_DESCRIPTOR Attributes
Attribute | Description |
---|---|
|
Name of the queue in which the message was enqueued which resulted in the notification |
|
Name of the consumer for the multiconsumer queue |
|
Identification number of the message |
|
Message properties specified by the |
|
Indicates the timeout specifications |
This type is for timeout specifications.
TYPE SYS.AQ$_NTFN_DESCRIPTOR IS OBJECT( ntfn_flags NUMBER)
Table 185-3 AQ$_DESCRIPTOR Attributes
Attribute | Description |
---|---|
|
Set to 1 if the notifications are already removed after a stipulated timeout; otherwise the value is 0. |
Specifies anonymous subscriptions to which you want to post messages.
TYPE SYS.AQ$_POST_INFO IS OBJECT ( name VARCHAR2(128), namespace NUMBER, payload RAW(2000) DEFAULT NULL);
Table 185-4 AQ$_POST_INFO Attributes
Attribute | Description |
---|---|
|
Name of the anonymous subscription to which you want to post |
|
To receive notifications from other applications through |
|
The payload to be posted to the anonymous subscription |
Identifies the list of anonymous subscriptions to which you want to post messages.
See Also:
AQ$_POST_INFO TypeTYPE SYS.AQ$_POST_INFO_LIST AS VARRAY(1024) OF SYS.AQ$_POST_INFO;
This type specifies the options available for purging a queue table.
See Also:
PURGE_QUEUE_TABLE Procedure.TYPE AQ$_PURGE_OPTIONS_T is RECORD ( block BOOLEAN DEFAULT FALSE delivery_mode PLS_INTEGER DEFAULT PERSISTENT);
Table 185-5 AQ$_PURGE_OPTIONS_T Type Attributes
Attribute | Description |
---|---|
|
|
|
Kind of messages to purge, either |
Identifies the list of agents that receive the message. This type can be used only when the queue is enabled for multiple dequeues.
See Also:
"AQ$_AGENT Type"TYPE SYS.AQ$_RECIPIENT_LIST_T IS TABLE OF SYS.AQ$_AGENT INDEX BY BINARY_INTEGER;
This type identifies a producer or a consumer of a message.
TYPE SYS.AQ$_REG_INFO IS OBJECT ( name VARCHAR2(128), namespace NUMBER, callback VARCHAR2(4000), context RAW(2000) DEFAULT NULL, qosflags NUMBER, timeout NUMBER);
Table 185-6 AQ$_REG_INFO Type Attributes
Attribute | Description |
---|---|
|
Specifies the name of the subscription. The subscription name is of the form |
|
Specifies the namespace of the subscription. To receive notification from Oracle Streams AQ queues, the namespace must be |
|
Specifies the action to be performed on message notification. For HTTP notifications, use |
|
Specifies the context that is to be passed to the callback function |
|
Can be set to one or more of the following values to specify the notification quality of service:
|
|
Specifies an automatic expiration period for the registration. If you want no timeout, then set this attribute to 0. |
You can use the following notification mechanisms:
OCI callback
e-mail callback
PL/SQL callback
Table 185-7 shows the actions performed for nonpersistent queues for different notification mechanisms when RAW presentation is specified. Table 185-8 shows the actions performed when XML presentation is specified.
Table 185-7 Actions Performed for Nonpersistent Queues When RAW Presentation Specified
Queue Payload Type | OCI Callback | PL/SQL Callback | |
---|---|---|---|
|
OCI callback receives the RAW data in the payload. |
Not supported |
PL/SQL callback receives the RAW data in the payload. |
|
Not supported |
Not supported |
Not supported |
Table 185-8 Actions Performed for Nonpersistent Queues When XML Presentation Specified
Queue Payload Type | OCI Callback | PL/SQL Callback | |
---|---|---|---|
|
OCI callback receives the XML data in the payload. |
XML data is formatted as a SOAP message and e-mailed to the registered e-mail address. |
PL/SQL callback receives the XML data in the payload. |
|
OCI callback receives the XML data in the payload. |
XML data is formatted as a SOAP message and e-mailed to the registered e-mail address. |
PL/SQL callback receives the XML data in the payload. |
Identifies the list of registrations to a queue.
See Also:
"AQ$_REG_INFO Type"TYPE SYS.AQ$_REG_INFO_LIST AS VARRAY(1024) OF SYS.AQ$_REG_INFO;
Identifies the list of subscribers that subscribe to a queue.
See Also:
"AQ$_AGENT Type"TYPE SYS.AQ$_SUBSCRIBER_LIST_T IS TABLE OF SYS.AQ$_AGENT INDEX BY BINARY_INTEGER;
Specifies the options available for the dequeue operation.
TYPE DEQUEUE_OPTIONS_T IS RECORD ( consumer_name VARCHAR2(30) DEFAULT NULL, dequeue_mode BINARY_INTEGER DEFAULT REMOVE, navigation BINARY_INTEGER DEFAULT NEXT_MESSAGE, visibility BINARY_INTEGER DEFAULT ON_COMMIT, wait BINARY_INTEGER DEFAULT FOREVER, msgid RAW(16) DEFAULT NULL, correlation VARCHAR2(128) DEFAULT NULL, deq_condition VARCHAR2(4000) DEFAULT NULL, signature aq$_sig_prop DEFAULT NULL, transformation VARCHAR2(61) DEFAULT NULL, delivery_mode PLS_INTEGER DEFAULT PERSISTENT);
Table 185-9 DEQUEUE_OPTIONS_T Attributes
Attribute | Description |
---|---|
|
Name of the consumer. Only those messages matching the consumer name are accessed. If a queue is not set up for multiple consumers, then this field should be set to For secure queues, consumer_name must be a valid AQ agent name, mapped to the database user performing the dequeue operation, through |
|
Specifies the locking behavior associated with the dequeue. Possible settings are:
|
|
Specifies the position of the message that will be retrieved. First, the position is determined. Second, the search criterion is applied. Finally, the message is retrieved. Possible settings are:
F
|
|
Specifies whether the new message is dequeued as part of the current transaction.The visibility parameter is ignored when using the
I |
|
Specifies the wait time if there is currently no message available which matches the search criteria. Possible settings are:
number: Wait time in seconds. |
|
Specifies the message identifier of the message to be dequeued. |
|
Specifies the correlation identifier of the message to be dequeued. Special pattern matching characters, such as the percent sign ( |
|
A conditional expression based on the message properties, the message data properties, and PL/SQL functions. A To specify dequeue conditions on a message payload (object payload), use attributes of the object type in clauses. You must prefix each attribute with |
|
Currently not implemented |
|
Specifies a transformation that will be applied after dequeuing the message. The source type of the transformation must match the type of the queue. |
|
The dequeuer specifies the delivery mode of the messages it wishes to dequeue in the dequeue options. It can be |
Specifies the options available for the enqueue operation.
TYPE SYS.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);
Table 185-10 ENQUEUE_OPTIONS_T Attributes
Attribute | Description |
---|---|
|
Specifies the transactional behavior of the enqueue request. Possible settings are:
|
|
Specifies the message identifier of the message which is referenced in the sequence deviation operation. This field is valid only if |
|
Specifies whether the message being enqueued should be dequeued before other messages already in the queue. Possible settings are:
|
|
Specifies a transformation that will be applied before enqueuing the message. The return type of the transformation function must match the type of the queue. |
|
Specifies a transformation that will be applied before enqueuing the message. The return type of the transformation function must match the type of the queue. |
This type is used in PL/SQL notification, as one field in aq$_descriptor
, to pass message properties of an AQ message to the PL/SQL notification client callback.
CREATE or replace TYPE sys.msg_prop_t AS OBJECT ( priority NUMBER, delay NUMBER, expiration NUMBER, correlation VARCHAR2(128), attempts NUMBER, exception_queue VARCHAR2(51), enqueue_time DATE, state NUMBER, sender_id aq$_agent, original_msgid RAW(16), delivery_mode NUMBER);
Table 185-11 SYS.MSG_PROP_T Type Attributes
Parameter | Description |
---|---|
|
Specifies the priority of the message. A smaller number indicates higher priority. The priority can be any number, including negative numbers. |
|
Specifies the delay of the enqueued message. The delay represents the number of seconds after which a message is available for dequeuing. Dequeuing by The possible settings follow:
number: The number of seconds to delay the message |
|
Specifies the expiration of the message. It determines, in seconds, the duration the message is available for dequeuing. This parameter is an offset from the time the message is ready for dequeue. Expiration processing requires the queue monitor to be running. However the queue monitor is started automatically by the system if needed. The possible settings follow:
number: The number of seconds message remains in |
|
Returns the identifier supplied by the producer of the message at enqueue time. |
|
Returns the number of attempts that have been made to dequeue the message. This parameter cannot be set at enqueue time. |
|
Specifies the name of the queue into which the message is moved if it cannot be processed successfully. Messages are moved automatically into the exception queue. Messages are moved into the exception queue in the following cases:
The default is the exception queue associated with the queue table. If the exception queue specified does not exist at the time of the move, then the message is moved to the default exception queue associated with the queue table, and a warning is logged in the alert log. If the default exception queue is specified, then the parameter returns a |
|
Specifies the time the message was enqueued. This value is determined by the system and cannot be set by the user at enqueue time. |
|
Specifies the state of the message at the time of the dequeue. This parameter cannot be set at enqueue time. The possible states follow:
|
|
The application-sender identification specified at enqueue time by the message producer. Sender id is of type Sender name is required for secure queues at enqueue time. This must be a valid AQ agent name, mapped to the database user performing the enqueue operation, through The Sender id in the message properties returned at dequeue time may have a sender address if the message was propagated from another queue. The value of the address is the |
|
This parameter is used by Oracle Streams AQ for propagating messages. |
|
|
This type is defined inside the DBMS_AQ package, and describes the information that AQ uses to convey the state of individual messages. These are set at enqueue time, and their values are returned at dequeue time.
See Also:
AQ$_RECIPIENT_LIST_T TypeTYPE message_properties_t IS RECORD ( priority BINARY_INTEGER NOT NULL DEFAULT 1, delay BINARY_INTEGER NOT NULL DEFAULT NO_DELAY, expiration BINARY_INTEGER NOT NULL DEFAULT NEVER, correlation VARCHAR2(128) DEFAULT NULL, attempts BINARY_INTEGER, recipient_list AQ$_RECIPIENT_LIST_T, exception_queue VARCHAR2(61) DEFAULT NULL, enqueue_time DATE, state BINARY_INTEGER, sender_id SYS.AQ$_AGENT DEFAULT NULL, original_msgid RAW(16) DEFAULT NULL, signature aq$_sig_prop DEFAULT NULL, transaction_group VARCHAR2(30) DEFAULT NULL, user_property SYS.ANYDATA DEFAULT NULL delivery_mode PLS_INTEGER NOT NULL DEFAULT DBMS_AQ.PERSISTENT);
Table 185-12 MESSAGE_PROPERTIES_T Attributes
Attribute | Description |
---|---|
|
Specifies the priority of the message. A smaller number indicates higher priority. The priority can be any number, including negative numbers. |
|
Specifies the delay of the enqueued message. The delay represents the number of seconds after which a message is available for dequeuing. Dequeuing by The possible settings follow:
number: The number of seconds to delay the message |
|
Specifies the expiration of the message. It determines, in seconds, the duration the message is available for dequeuing. This parameter is an offset from the time the message is ready for dequeue. Expiration processing requires the queue monitor to be running. However the queue monitor is started automatically by the system if needed. The possible settings follow:
number: The number of seconds message remains in |
|
Returns the identifier supplied by the producer of the message at enqueue time. |
|
Returns the number of attempts that have been made to dequeue the message. This parameter cannot be set at enqueue time. |
|
This parameter is only valid for queues that allow multiple consumers. The default recipients are the queue subscribers. This parameter is not returned to a consumer at dequeue time. For type definition, see the "AQ$_AGENT Type". |
|
Specifies the name of the queue into which the message is moved if it cannot be processed successfully. Messages are moved automatically into the exception queue. Messages are moved into the exception queue in the following cases:
The default is the exception queue associated with the queue table. If the exception queue specified does not exist at the time of the move, then the message is moved to the default exception queue associated with the queue table, and a warning is logged in the alert log. If the default exception queue is specified, then the parameter returns a |
|
Specifies the time the message was enqueued. This value is determined by the system and cannot be set by the user at enqueue time. |
|
Specifies the state of the message at the time of the dequeue. This parameter cannot be set at enqueue time. The possible states follow:
|
|
The application-sender identification specified at enqueue time by the message producer. Sender id is of type Sender name is required for secure queues at enqueue time. This must be a valid AQ agent name, mapped to the database user performing the enqueue operation, through The Sender id in the message properties returned at dequeue time may have a sender address if the message was propagated from another queue. The value of the address is the |
|
This parameter is used by Oracle Streams AQ for propagating messages. |
|
Currently not implemented |
|
Specifies the |
|
This optional attribute is used to store additional information about the payload. |
|
The message publisher specifies the delivery mode in the |
This type is used by dbms_aq.enqueue_array
and dbms_aq.dequeue_array
calls to hold the set of message properties. Each element in the payload_array
should have a corresponding element in the MESSAGE_PROPERTIES_ARRAY_T
VARRAY
.
See Also:
"MESSAGE_PROPERTIES_T Type"TYPE MESSAGE_PROPERTIES_ARRAY_T IS VARRAY (2147483647) OF MESSAGE_PROPERTIES_T;
The msgid_array_t
type is used in dbms_aq.enqueue_array
and dbms_aq.dequeue_array
calls to hold the set of message IDs that correspond to the enqueued or dequeued messages.
TYPE MSGID_ARRAY_T IS TABLE OF RAW(16) INDEX BY BINARY_INTEGER