This chapter describes the Oracle Streams Advanced Queuing (AQ) basic components.
This chapter contains the following topics:
object_name := VARCHAR2 object_name := [schema_name.]name
This component names database objects. This naming convention applies to queues, queue tables, and object types.
Names for objects are specified by an optional schema name and a name. If the schema name is not specified, then the current schema is assumed. The name must follow the reserved character guidelines in Oracle Database SQL Reference. The schema name, agent name, and the object type name can each be up to 30 bytes long. However, queue names and queue table names can be a maximum of 24 bytes.
type_name := VARCHAR2 type_name := object_type | "RAW"
This component defines queue types. For details on creating object types refer to Oracle Database Concepts. The maximum number of attributes in the object type is limited to 900.
To store payloads of type
RAW, Oracle Streams AQ creates a queue table with a LOB column as the payload repository. The size of the payload is limited to 32K bytes of data. Because
LOB columns are used for storing
RAW payload, the Oracle Streams AQ administrator can choose the
LOB tablespace and configure the
LOB storage by constructing a
LOB storage string in the
storage_clause parameter during queue table creation time.
Note:Payloads containing LOBs require users to grant explicit
TYPE AQ$_AGENT IS OBJECT ( name VARCHAR2(30), address VARCHAR2(1024), protocol NUMBER);
All consumers that are added as subscribers to a multiconsumer queue must have unique values for the
AQ$_AGENT parameters. Two subscribers cannot have the same values for the
PROTOCOL attributes for the
AQ$_AGENT type. At least one of the three attributes must be different for two subscribers.
You can add subscribers by repeatedly using the
DBMS_AQADM.ADD_SUBSCRIBER procedure up to a maximum of 1024 subscribers for a multiconsumer queue.
This type has three attributes:
This attribute specifies the name of a producer or consumer of a message. It can be the name of an application or a name assigned by an application. A queue can itself be an agent, enqueuing or dequeuing from another queue. The name must follow the reserved character guidelines in Oracle Database SQL Reference.
This attribute is interpreted in the context of
protocol is 0 (default), then
address is of the form
This attribute specifies the protocol to interpret the address and propagate the message. The default value is 0.
TYPE AQ$_RECIPIENT_LIST_T IS TABLE OF aq$_agent INDEX BY BINARY_INTEGER;
This component identifies the list of agents that receive a message.
TYPE AQ$_AGENT_LIST_T IS TABLE OF aq$_agent INDEX BY BINARY INTEGER;
This component identifies the list of agents for
DBMS_AQ.LISTEN to listen for.
TYPE AQ$_SUBSCRIBER_LIST_T IS TABLE OF aq$_agent INDEX BY BINARY INTEGER;
This component identifies the list of subscribers that subscribe to this queue.
TYPE AQ$_REG_INFO_LIST AS VARRAY(1024) OF sys.aq$_reg_info;
This component identifies the list of registrations to a queue.
TYPE AQ$_POST_INFO_LIST AS VARRAY(1024) OF sys.aq$_post_info;
This component identifies the list of anonymous subscriptions to which messages are posted.
TYPE SYS.AQ$_REG_INFO IS OBJECT ( name VARCHAR2(128), namespace NUMBER, callback VARCHAR2(4000), context RAW(2000), qosflags NUMBER, timeout NUMBER);
This component identifies a producer or a consumer of a message. Its attributes are described in the following list. Attributes
timeout are part of Oracle Streams AQ 10g Release 2 (10.2) notification enhancements.
This attribute specifies the name of the subscription. If the registration is for a single-consumer queue, then it is of the form
queue. If the registration is for a multiconsumer queue, then it is of the form
This attribute specifies the namespace of the subscription. To receive notifications from Oracle Streams AQ queues, the namespace must be
DBMS_AQ.NAMESPACE_AQ. To receive notifications from other applications using
OCISubscriptionPost(), the namespace must be
This attribute specifies the action to be performed on message notification. For e-mail notifications, the form is
mailto://firstname.lastname@example.org. For Oracle Streams AQ PL/SQL callback, use
procedure?PR=0 for raw message payload or
?PR=1 for Oracle object type message payload converted to XML.
This attribute specifies the context that is to be passed to the callback function. The default is
This attribute specifies the notification quality of service, described in more detail in "Notification Quality of Service".
Clients can use this attribute to specify an automatic expiration period for the registration. If you want no timeout, then set this attribute to
qosflags attribute can be set to one or more of the following values to specify the notification quality of service:
This value specifies that reliable notification is required. Reliable notifications persist across instance and database restarts. The corresponding OCI flag is
This value specifies that payload delivery is required. It is supported only for client notification and only for RAW queues. The corresponding OCI flag is
This value specifies that the registration is to be purged automatically when the first notification is delivered to this registration location. The corresponding OCI flag is
TYPE SYS.AQ$_DESCRIPTOR IS OBJECT ( queue_name VARCHAR2(65), consumer_name VARCHAR2(30), msg_id RAW(16), msg_prop msg_prop_t, gen_desc AQ$_NTFN_DESCRIPTOR);
This component specifies the Oracle Streams AQ descriptor received by Oracle Streams AQ PL/SQL callbacks upon notification. It has the following attributes:
This attribute specifies the name of the queue in which the message was enqueued which resulted in the notification.
This attribute specifies the name of the consumer for a multiconsumer queue.
This attribute specifies the message identifier.
This attribute specifies the message properties.
This attribute indicates the timeout specifications
The message properties type
msg_prop_t has the following components:
TYPE AQ$_MSG_PROP_T IS OBJECT( priority number, delay number, expiration number, correlation varchar2(128), attempts number, recipent_list aq$_recipient_list_t, exception_queue varchar2(51), enqueue_time date, state number, sender_id aq$_agent, original_misgid raw(16), delivery_mode number);
See Also:"MESSAGE_PROPERTIES_T Type" in PL/SQL Packages and Types Reference
The timeout specifications type
AQ$_NTFN_DESCRIPTOR has a single component:
TYPE AQ$_NTFN_DESCRIPTOR IS OBJECT( NTFN_FLAGS number);
NTFN_FLAGS is set to
1 if the notifications are already removed after a stipulated timeout; otherwise the value is
TYPE SYS.AQ$_POST_INFO IS OBJECT ( name VARCHAR2(128), namespace NUMBER, payload RAW(2000));
This component specifies anonymous subscriptions to which you want to post messages. It has three attributes:
This attribute specifies the name of the anonymous subscription to which you want to post.
This attribute specifies the namespace of the anonymous subscription. To receive notifications from other applications using
OCISubscriptionPost(), the namespace must be
This attribute specifies the payload to be posted to the anonymous subscription. The default is
When enumerated constants such as
NORMAL_QUEUE are selected as values, the symbol must be specified with the scope of the packages defining it. All types associated with the administrative interfaces must be prepended with
DBMS_AQADM. For example:
Table 2-1 lists the enumerated constants in the Oracle Streams AQ administrative interface.
Note:Nonpersistent queues are deprecated in Oracle Streams AQ 10g Release 2 (10.2). Oracle recommends that you use buffered messaging instead.
When using enumerated constants such as
REMOVE, the PL/SQL constants must be specified with the scope of the packages defining them. All types associated with the operational interfaces must be prepended with
DBMS_AQ. For example:
Table 2-2 lists the enumerated constants in the Oracle Streams AQ operational interface.
Note:The sequence deviation feature is deprecated in 10g Release 2 (10.2).
You can specify parameters
JOB_QUEUE_PROCESSES in the
init.ora parameter file.
Prior to Oracle Database 10g, Oracle Streams AQ time manager processes were controlled by
AQ_TM_PROCESSES, which had to be set to nonzero to perform time monitoring on queue messages and for processing messages with delay and expiration properties specified. These processes were named QMNO-9, and the number of them could be changed using:
ALTER SYSTEM SET AQ_TM_PROCESSES=X
Parameter X ranged from
10. When X was set to 1 or more, that number of QMN processes were then started. If the parameter was not specified, or was set to
0, then queue monitor processes were not started.
Beginning in Oracle Streams AQ 10g Release 1 (10.1), this was changed to a coordinator-slave architecture, where a coordinator is automatically spawned if Oracle Streams AQ or Streams is being used in the system. This process, named QMNC, dynamically spawns slaves depending on the system load. The slaves, named qXXX, do various background tasks for Oracle Streams AQ or Streams. Because the number of processes is determined automatically and tuned constantly, you no longer need set
Even though it is no longer necessary to set
AQ_TM_PROCESSES when Oracle Streams AQ or Streams is used, if you do specify a value, then that value is taken into account. However, the number of qXXX processes can be different from what was specified by
QMNC only runs when you use queues and create new queues. It affects Streams Replication and Messaging users.
No separate API is needed to disable or enable the background processes. This is controlled by setting
AQ_TM_PROCESSES to zero or nonzero. Oracle recommends, however, that you leave the
AQ_TM_PROCESSES parameter unspecified and let the system autotune.
Note:If you want to disable the Queue Monitor Coordinator, then you must set
Propagation is handled by job queue (Jnnn) processes. The number of job queue processes started in an instance is controlled by the
JOB_QUEUE_PROCESSES. The default value of this parameter is 0. For message propagation to take place, this parameter must be set to at least 2. The database administrator can set it to higher values if there are many queues from which the messages must be propagated, or if there are many destinations to which the messages must be propagated, or if there are other jobs in the job queue.
See Also:Oracle Database SQL Reference for more information on