Oracle® Database PL/SQL Packages and Types Reference 10g Release 2 (10.2) Part Number B14258-01 |
|
|
View PDF |
The DBMS_STREAMS_MESSAGING
package, one of a set of Streams packages, provides interfaces to enqueue messages into and dequeue messages from a ANYDATA
queue.
Note:
Currently, messaging clients cannot dequeue buffered messages. In addition, theDBMS_STREAMS_MESSAGING
package cannot be used to enqueue messages into or dequeue messages from a buffered queue.See Also:
Oracle Streams Concepts and Administration for more information about Streams and for an example that uses the procedures in this package
Oracle Streams Advanced Queuing User's Guide and Reference for more information about queues and messaging
This chapter contains the following topic:
Table 108-1 DBMS_STREAMS_MESSAGING Package Subprograms
Subprogram | Description |
---|---|
DEQUEUE Procedure |
Uses the specified Streams messaging client to dequeue a message from the specified queue |
ENQUEUE Procedure |
The current user enqueues a message into the specified queue |
Note:
The subprograms in this package do not commit.This procedure uses the specified Streams messaging client to dequeue a message from the specified queue.
This procedure is overloaded. One version of this procedure contains the msgid
OUT
parameter, and the other does not.
Syntax
DBMS_STREAMS_MESSAGING.DEQUEUE( queue_name IN VARCHAR2, streams_name IN VARCHAR2, payload OUT ANYDATA, dequeue_mode IN VARCHAR2 DEFAULT 'REMOVE', navigation IN VARCHAR2 DEFAULT 'NEXT MESSAGE', wait IN BINARY_INTEGER DEFAULT FOREVER, msgid OUT RAW); DBMS_STREAMS_MESSAGING.DEQUEUE( queue_name IN VARCHAR2, streams_name IN VARCHAR2, payload OUT ANYDATA, dequeue_mode IN VARCHAR2 DEFAULT 'REMOVE', navigation IN VARCHAR2 DEFAULT 'NEXT MESSAGE', wait IN BINARY_INTEGER DEFAULT FOREVER);
Parameters
Table 108-2 DEQUEUE Procedure Parameters
Parameter | Description |
---|---|
queue_name |
The name of the local queue from which messages will be dequeued, specified as [ schema_name .] queue_name . The current database must contain the queue, and the queue must be a secure queue of ANYDATA type.
For example, to specify a queue named |
streams_name |
The name of the Streams messaging client. For example, if the user strmadmin is the messaging client, then specify strmadmin .
If |
payload |
The payload that is dequeued |
dequeue_mode |
Specify one of the following settings:
|
navigation |
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.
Specify one of the following settings:
Note: Each message group contains the messages in a single transaction. See Also: Oracle Streams Advanced Queuing User's Guide and Reference for more information about dequeue options |
wait |
Either FOREVER or NO_WAIT
If If |
msgid |
Specifies the message identifier of the message that is dequeued |
Exceptions
Table 108-3 DEQUEUE Procedure Exceptions
Exception | Description |
---|---|
ENDOFCURTRANS |
Dequeue has reached the end of the messages in the current transaction. Specify this exception in the following way:
SYS.DBMS_STREAMS_MESSAGING.ENDOFCURTRANS Every dequeue procedure should include an exception handler that handles this exception. |
NOMOREMSGS |
There are no more messages in the queue for the dequeue operation. Specify this exception in the following way:
SYS.DBMS_STREAMS_MESSAGING.NOMOREMSGS A dequeue procedure that specifies |
This procedure enables the current user to enqueue a message into the specified queue.
This procedure is overloaded. One version of this procedure contains the msgid
OUT
parameter, and the other does not.
Syntax
DBMS_STREAMS_MESSAGING.ENQUEUE( queue_name IN VARCHAR2, payload IN ANYDATA, msgid OUT RAW); DBMS_STREAMS_MESSAGING.ENQUEUE( queue_name IN VARCHAR2, payload IN ANYDATA);
Parameters
Table 108-4 ENQUEUE Procedure Parameters
Parameter | Description |
---|---|
queue_name |
The name of the local queue into which messages will be enqueued, specified as [ schema_name .] queue_name . The current database must contain the queue, and the queue must be a secure queue of ANYDATA type.
For example, to specify a queue named |
payload |
The payload that is enqueued |
msgid |
Specifies the message identifier of the message that is enqueued |
Usage Notes
To successfully enqueue messages into a queue, the current user must be mapped to a unique Advanced Queuing agent with the same name as the current user. You can run the DBMS_STREAMS_ADM.SET_UP_QUEUE
procedure and specify a user as the queue user to grant the necessary privileges to the user to perform enqueues. The Advanced Queuing agent is created automatically when you run SET_UP_QUEUE
and specify a queue user.
See Also:
SET_UP_QUEUE Procedure