Skip Headers
Oracle® Streams Advanced Queuing User's Guide and Reference
10g Release 2 (10.2)

Part Number B14257-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

2 Basic Components

This chapter describes the Oracle Streams Advanced Queuing (AQ) basic components.

This chapter contains the following topics:

2.1 Object Name

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.

2.2 Type Name

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 Select, Insert and Update privileges on the queue table for doing enqueues and dequeues.

2.3 AQ Agent Type

TYPE AQ$_AGENT IS OBJECT (
   name            VARCHAR2(30), 
   address         VARCHAR2(1024),
   protocol        NUMBER);

This component identifies a producer or a consumer of a message.

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 NAME, ADDRESS, and 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:

2.4 AQ Recipient List Type

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.

2.5 AQ Agent List Type

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.

2.6 AQ Subscriber List Type

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.

2.7 AQ Registration Information List Type

TYPE AQ$_REG_INFO_LIST AS VARRAY(1024) OF sys.aq$_reg_info;

This component identifies the list of registrations to a queue.

2.8 AQ Post Information List Type

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.

2.9 AQ Registration Information Type

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 qosflags and timeout are part of Oracle Streams AQ 10g Release 2 (10.2) notification enhancements.

Notification Quality of Service

The qosflags attribute can be set to one or more of the following values to specify the notification quality of service:

2.10 AQ Notification Descriptor Type

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:

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 0.

2.11 AQ Post Information Type

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:

2.12 Enumerated Constants in the Oracle Streams AQ Administrative Interface

When enumerated constants such as INFINITE, TRANSACTIONAL, and 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:

DBMS_AQADM.NORMAL_QUEUE

Table 2-1 lists the enumerated constants in the Oracle Streams AQ administrative interface.

Table 2-1 Enumerated Constants in the Oracle Streams AQ Administrative Interface

Parameter Options
retention 0,1,2...INFINITE
message_grouping TRANSACTIONAL, NONE
queue_type NORMAL_QUEUE, EXCEPTION_QUEUE,NON_PERSISTENT_QUEUE
delivery_mode BUFFERED, PERSISTENT, PERSISTENT_OR_BUFFERED


Note:

Nonpersistent queues are deprecated in Oracle Streams AQ 10g Release 2 (10.2). Oracle recommends that you use buffered messaging instead.

2.13 Enumerated Constants in the Oracle Streams AQ Operational Interface

When using enumerated constants such as BROWSE, LOCKED, and 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:

DBMS_AQ.BROWSE

Table 2-2 lists the enumerated constants in the Oracle Streams AQ operational interface.

Table 2-2 Enumerated Constants in the Oracle Streams AQ Operational Interface

Parameter Options
visibility IMMEDIATE, ON_COMMIT
dequeue mode BROWSE, LOCKED, REMOVE, REMOVE_NODATA
navigation FIRST_MESSAGE, NEXT_MESSAGE, NEXT_TRANSACTION
state WAITING, READY, PROCESSED, EXPIRED
sequence deviation BEFORE, TOP
wait FOREVER, NO_WAIT
delay NO_DELAY
expiration NEVER
namespace NAMESPACE_AQ, NAMESPACE_ANONYMOUS
delivery_mode BUFFERED, PERSISTENT, PERSISTENT_OR_BUFFERED


Note:

The sequence deviation feature is deprecated in 10g Release 2 (10.2).

2.14 INIT.ORA Parameter File Considerations

You can specify parameters AQ_TM_PROCESSES and JOB_QUEUE_PROCESSES in the init.ora parameter file.

2.14.1 AQ_TM_PROCESSES Parameter No Longer Needed in init.ora

Prior to Oracle Database 10g, Oracle Streams AQ time manager processes were controlled by init.ora parameter 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 0 to 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 AQ_TM_PROCESSES.

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 AQ_TM_PROCESSES.

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 AQ_TM_PROCESSES = 0 in your pfile or spfile. Oracle strongly recommends that you do NOT set AQ_TM_PROCESSES = 0. If you are using Oracle Streams, then setting this parameter to zero (which Oracle Database respects no matter what) can cause serious problems.

2.14.2 JOB_QUEUE_PROCESSES Parameter

Propagation is handled by job queue (Jnnn) processes. The number of job queue processes started in an instance is controlled by the init.ora parameter 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 JOB_QUEUE_PROCESSES