Data Structures

The following chapters discuss the Advanced Queuing administrative and operational interfaces in which data structures are used:

• Chapter 9, "Administrative Interface"

• Chapter 11, "Operational Interface: Basic Operations"

Object Name (object_name)

Purpose

To name database objects. This naming convention applies to queues, queue tables, and object types.

Syntax

object_name := VARCHAR2
object_name := [<schema_name>.]<name>

Usage

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 the Oracle9i 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 (type_name)

Purpose

To define queue types.

Syntax

type_name := VARCHAR2
type_name := <object_type> | "RAW"

Usage

Table 2-1 lists usage information for type_name.

Table 2-1 Type Name (type_name)

Parameter	Description
<object_types>	For details on creating object types please refer to Oracle9i Database Concepts. The maximum number of attributes in the object type is limited to 900.
"RAW"	To store payload of type RAW, 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 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.

Agent Type (aq$_agent)

Purpose

To identify a producer or a consumer of a message.

Syntax

TYPE aq$_agent IS OBJECT (
   name            VARCHAR2(30), 
   address         VARCHAR2(1024),
   protocol        NUMBER)

Usage

All consumers that are added as subscribers to a multiconsumer queue must have unique values for the AQ$_AGENT parameters. You can add more subscribers by repeatedly using the DBMS_AQADM.ADD_SUBSCRIBER procedure up to a maximum of 1024 subscribers for a multiconsumer queue. 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.

Table 2-2 lists usage information for aq$_agent.

Table 2-2 Agent (aq$_agent)

Parameter	Description
name (VARCHAR2(30))	Name of a producer or consumer of a message.The name must follow the reserved character guidelines in the Oracle9i SQL Reference.
address (VARCHAR2(1024))	Protocol specific address of the recipient. If the protocol is 0 (default), the address is of the form [schema.]queue[@dblink].
protocol (NUMBER)	Protocol to interpret the address and propagate the message. The default value is 0.

AQ Recipient List Type (aq$_recipient_list_t)

Purpose

To identify the list of agents that will receive the message.

Syntax

TYPE aq$_recipient_list_t IS TABLE OF aq$_agent  
           INDEX BY BINARY_INTEGER; 

AQ Agent List Type (aq$_agent_list_t)

Purpose

To identify the list of agents for DBMS_AQ.LISTEN to listen for.

Syntax

TYPE aq$_agent_list_t IS TABLE OF aq$_agent 
           INDEX BY BINARY INTEGER; 

AQ Subscriber List Type (aq$_subscriber_list_t)

Purpose

To identify the list of subscribers that subscribe to this queue.

Syntax

TYPE aq$_subscriber_list_t IS TABLE OF aq$_agent  
          INDEX BY BINARY INTEGER; 

AQ Registration Info List Type (aq$_reg_info_list)

Purpose

To identify the list of registrations to a queue.

Syntax

TYPE aq$_reg_info_list AS VARRAY(1024) OF sys.aq$_reg_info

AQ Post Info List Type (aq$_post_info_list)

Purpose

To identify the list of anonymous subscriptions to which messages are posted.

Syntax

TYPE aq$_post_info_list AS VARRAY(1024) OF sys.aq$_post_info

AQ Registration Info Type

The aq$_reg_info data structure identifies a producer or a consumer of a message.

Syntax

TYPE sys.aq$_reg_info IS OBJECT (
   name      VARCHAR2(128),
   namespace NUMBER,
   callback  VARCHAR2(4000),
   context   RAW(2000));

Attributes

Table 2-3 AQ Registration Info Type Attributes

Attribute	Description
name	Specifies the name of the subscription. The subscription name is of the form <schema>.<queue> if the registration is for a single consumer queue and <schema>.<queue>:<consumer_name> if the registration is for a multiconsumer queues.
namespace	Specifies the namespace of the subscription. To receive notifications from AQ queues the namespace must be DBMS_AQ.NAMESPACE_AQ. To receive notifications from other applications via DBMS_AQ.POST or OCISubscriptionPost(), the namespace must be DBMS_AQ.NAMESPACE_ANONYMOUS.
callback	Specifies the action to be performed on message notification. For email notifications, the form is mailto://[e-mail] For AQ PL/SQL Callback, use plsql://<schema>.<procedure>?PR=0 for raw message payload OR plsql://<schema>.<procedure>?PR=1 for ADT message payload converted to XML
context	Specifies the context that is to be passed to the callback function. Default: NULL

Table 2-4 shows the actions performed when different notification mechanisms/presentations are specified for nonpersistent queues.

Table 2-4 Nonpersistent Queues

Queue Payload Type	Presentation Specified
	RAW			XML
	Notification Mechanism			Notification Mechanism
	OCI	Email	PL/SQL Callback	OCI	Email	PL/SQL Callback
RAW	The callback receives the RAW data in the payload.	Not supported	The PL/SQL callback receives the RAW data in the payload.	The callback receives the XML data in the payload.	The XML data is formatted as an IDAP message and emailed to the registered email address.	The PL/SQL callback receives the XML data in the payload.
ADT	Not supported.	Not supported.	Not supported.	The callback receives the XML data in the payload.	The XML data is formatted as an IDAP message and emailed to the registered email address.	The PL/SQL callback receives the XML data in the payload.

AQ Notification Descriptor Type

The aq$_descriptor data structure specifies the AQ Descriptor received by the AQ PL/SQL callbacks upon notification.

Syntax

TYPE sys.aq$_descriptor IS OBJECT (
  queue_name    VARCHAR2(30),
  consumer_name VARCHAR2(30),
  msg_id        RAW(16),
  msg_prop      msg_prop_t);

Attributes

Table 2-5 AQ Notification Descriptor Type

Attribute	Description
queue_name	Name of the queue in which the message was enqueued which resulted in the notification.
consumer_name	Name of the consumer for the multi-consumer queue
msg_id	Id of the message.
msg_prop	Message properties.

AQ Post Info Type

The aq$_post_info data structure specifies anonymous subscriptions to which you want to post messages.

Syntax

TYPE sys.aq$_post_info IS OBJECT (
  name       VARCHAR2(128),
  namespace  NUMBER,
  payload    RAW(2000));

Attributes

Table 2-6 AQ Post Info Type Attributes

Attribute	Description
name	name of the anonymous subscription to which you want to post to.
namespace	To receive notifications from other applications via DBMS_AQ.POST or OCISubscriptionPost(), the namespace must be DBMS_AQ.NAMESPACE_ANONYMOUS.
payload	The payload to be posted to the anonymous subscription Default: NULL