Release 2 (9.2)
Part Number A96612-01
 Home |
 Book List |
 Contents |
 Index |
 Master Index |
 Feedback |
| Oracle9i Supplied PL/SQL Packages and Types Reference Release 2 (9.2) Part Number A96612-01 |
|
DBMS_AQ, 3 of 3
|
Note: The |
This procedure adds a message to the specified queue.
DBMS_AQ.ENQUEUE ( queue_name IN VARCHAR2, enqueue_options IN enqueue_options_t, message_properties IN message_properties_t, payload IN "<type_name>", msgid OUT RAW);
| Parameter | Description |
|---|---|
|
queue_name |
Specifies the name of the queue to which this message should be enqueued. The queue cannot be an exception queue. |
|
enqueue_options |
|
|
message_properties |
|
|
payload |
The payload must be specified according to the specification in the associated queue table. For the definition of < |
|
msgid |
System generated identification of the message. This is a globally unique identifier that can be used to identify the message at dequeue time. |
The sequence_deviation parameter in enqueue_options can be used to change the order of processing between two messages. The identity of the other message, if any, is specified by the enqueue_options parameter relative_msgid. The relationship is identified by the sequence_deviation parameter.
Specifying sequence_deviation for a message introduces some restrictions for the delay and priority values that can be specified for this message. The delay of this message must be less than or equal to the delay of the message before which this message is to be enqueued. The priority of this message must be greater than or equal to the priority of the message before which this message is to be enqueued.
If a message is enqueued to a multiconsumer queue with no recipient, and if the queue has no subscribers (or rule-based subscribers that match this message), then the Oracle error ORA_24033 is raised. This is a warning that the message will be discarded because there are no recipients or subscribers to whom it can be delivered.
For secure queues, you must specify the sender_id in the messages_properties parameter. See "MESSAGE_PROPERTIES_T Type" for more information about sender_id.
When you use secure queues, the following are required:
DBMS_AQADM.CREATE_AQ_AGENT. See "CREATE_AQ_AGENT Procedure" .sender_id to a database user with enqueue privileges on the secure queue. Use DBMS_AQADM.ENABLE_DB_ACCESS to do this. See "ENABLE_DB_ACCESS Procedure".
| See Also:
Oracle9i Streams for information about secure queues |
This procedure dequeues a message from the specified queue.
DBMS_AQ.DEQUEUE ( queue_name IN VARCHAR2, dequeue_options IN dequeue_options_t, message_properties OUT message_properties_t, payload OUT "<type_name>", msgid OUT RAW);
| Parameter | Description |
|---|---|
|
queue_name |
Specifies the name of the queue. |
|
dequeue_options |
|
|
message_properties |
|
|
payload |
Not interpreted by Oracle AQ. The payload must be specified according to the specification in the associated queue table. For the definition of < |
|
msgid |
System generated identification of the message. |
The search criteria for messages to be dequeued is determined by the consumer_name, msgid, correlation and deq_condition parameters in dequeue_options.
Msgid uniquely identifies the message to be dequeued.deq_condition is specified as a Boolean expression using syntax similar to the WHERE clause of a SQL query. This Boolean expression can include conditions on message properties, user data properties (object payloads only), and PL/SQL or SQL functions (as specified in the where clause of a SQL query). Message properties include priority, corrid and other columns in the queue table.
To specify dequeue conditions on a message payload (object payload), use attributes of the object type in clauses. You must prefix each attribute with tab.user_data as a qualifier to indicate the specific column of the queue table that stores the payload.
Example: tab.user_data.orderstatus='EXPRESS''
Only messages in the READY state are dequeued unless msgid is specified.
The dequeue order is determined by the values specified at the time the queue table is created unless overridden by the msgid and correlation ID in dequeue_options.
The database-consistent read mechanism is applicable for queue operations. For example, a BROWSE call may not see a message that is enqueued after the beginning of the browsing transaction.
The default NAVIGATION parameter during dequeue is NEXT_MESSAGE. This means that subsequent dequeues will retrieve the messages from the queue based on the snapshot obtained in the first dequeue. In particular, a message that is enqueued after the first dequeue command will be processed only after processing all the remaining messages in the queue. This is usually sufficient when all the messages have already been enqueued into the queue, or when the queue does not have a priority-based ordering. However, applications must use the FIRST_MESSAGE navigation option when the first message in the queue needs to be processed by every dequeue command. This usually becomes necessary when a higher priority message arrives in the queue while messages already-enqueued are being processed.
Messages enqueued in the same transaction into a queue that has been enabled for message grouping will form a group. If only one message is enqueued in the transaction, then this will effectively form a group of one message. There is no upper limit to the number of messages that can be grouped in a single transaction.
In queues that have not been enabled for message grouping, a dequeue in LOCKED or REMOVE mode locks only a single message. By contrast, a dequeue operation that seeks to dequeue a message that is part of a group will lock the entire group. This is useful when all the messages in a group need to be processed as an atomic unit.
When all the messages in a group have been dequeued, the dequeue returns an error indicating that all messages in the group have been processed. The application can then use the NEXT_TRANSACTION to start dequeuing messages from the next available group. In the event that no groups are available, the dequeue will time-out after the specified WAIT period.
For secure queues, you must specify consumer_name in the dequeue_options parameter. See "DEQUEUE_OPTIONS_T Type" for more information about consumer_name.
When you use secure queues, the following are required:
DBMS_AQADM.CREATE_AQ_AGENT. See "CREATE_AQ_AGENT Procedure" .DBMS_AQADM.ENABLE_DB_ACCESS to do this. See "ENABLE_DB_ACCESS Procedure".
| See Also:
Oracle9i Streams for information about secure queues |
This procedure listens on one or more queues on behalf of a list of agents. The address field of the agent indicates the queue the agent wants to monitor. Only local queues are supported as addresses. Protocol is reserved for future use.
If agent-address is a multiconsumer queue, then agent-name is mandatory. For single-consumer queues, agent-name must not be specified.
This is a blocking call that returns when there is a message ready for consumption for an agent in the list. If no messages are found when the wait time expires, an error is raised.
DBMS_AQ.LISTEN (
agent_list IN aq$_agent_list_t,
wait IN BINARY_INTEGER DEFAULT DBMS_AQ.FOREVER,
agent OUT sys.aq$_agent);
TYPE aq$_agent_list_t IS TABLE of aq$_agent INDEXED BY BINARY_INTEGER;
This procedure takes a list of agents as an argument. You specify the queue to be monitored in the address field of each agent listed. You also must specify the name of the agent when monitoring multiconsumer queues. For single-consumer queues, an agent name must not be specified. Only local queues are supported as addresses. Protocol is reserved for future use.
This is a blocking call that returns when there is a message ready for consumption for an agent in the list. If there are messages for more than one agent, only the first agent listed is returned. If there are no messages found when the wait time expires, an error is raised.
A successful return from the listen call is only an indication that there is a message for one of the listed agents in one the specified queues. The interested agent must still dequeue the relevant message.
Note that you cannot call listen on nonpersistent queues.
This procedure registers an email address, user-defined PL/SQL procedure, or HTTP URL for message notification.
DBMS_AQ.REGISTER ( reg_list IN SYS.AQ$_REG_INFO_LIST, count IN NUMBER);
| Parameter | Description |
|---|---|
|
reg_list |
Specifies the list of subscriptions to which you want to register for message notifications. It is a list of AQ$_REG_INFO Type. |
|
count |
Specifies the number of entries in the reg_list. |
This procedure is used to register for notifications. You can specify an email address to which message notifications are sent, register a procedure to be invoked on a notification, or register an HTTP URL to which the notification is posted. Interest in several subscriptions can be registered at one time.
If you register for email notifications, you should set the host name and port name for the SMTP server that will be used by the database to send email notifications. If required, you should set the send-from email address, which is set by the database as the sent from field. See Chapter 7, "DBMS_AQELM" for more information on email notifications. You need a Java-enabled database to use this feature.
If you register for HTTP notifications, you may want to set the host name and port number for the proxy server and a list of no-proxy domains that will be used by the database to post HTTP notifications. See Chapter 7, "DBMS_AQELM" for more information on HTTP notifications.
This procedure unregisters a subscription which turns off notifications.
DBMS_AQ.UNREGISTER ( reg_list IN SYS.AQ$_REG_INFO_LIST, count IN NUMBER);
| Parameter | Description |
|---|---|
|
reg_list |
Specifies the list of subscriptions to which you want to register for message notifications. It is a list of AQ$_REG_INFO Type. |
|
count |
Specifies the number of entries in the reg_list. |
This procedure is used to unregister a subscription which turns off notifications. Several subscriptions can be unregistered from at one time.
This procedure posts to a list of anonymous subscriptions that allows all clients who are registered for the subscriptions to get notifications.
DBMS_AQ.POST ( post_list IN SYS.AQ$_POST_INFO_LIST, count IN NUMBER);
| Parameter | Description |
|---|---|
|
post_list |
Specifies the list of anonymous subscriptions to which you want to post. It is a list of AQ$_POST_INFO Type. |
|
count |
Specifies the number of entries in the post_list. |
This procedure is used to post to anonymous subscriptions which allows all clients who are registered for the subscriptions to get notifications. Several subscriptions can be posted to at one time.
This procedure creates an entry for an AQ agent in the LDAP server.
DBMS_AQ.BIND_AGENT( agent IN SYS.AQ$_AGENT, certificate IN VARCHAR2 default NULL);
In the LDAP server, digital certificates are stored as an attribute (usercertificate) of the OrganizationalPerson entity. The distinguished name for this OrganizationalPerson must be specified when binding the agent.
This procedure removes the entry for an AQ agent from the LDAP server.
DBMS_AQ.UNBIND_AGENT( agent IN SYS.AQ$_AGENT);
| Parameter | Description |
|---|---|
|
agent |
Agent that is to be removed from the LDAP server |
|
 Copyright © 2000, 2002 Oracle Corporation. All Rights Reserved. |
|