Skip Headers

PL/SQL Packages and Types Reference
10g Release 1 (10.1)

Part Number B10802-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

98
DBMS_STREAMS_MESSAGING

The DBMS_STREAMS_MESSAGING package, one of a set of Streams packages, provides interfaces to enqueue messages into and dequeue messages from a SYS.AnyData queue.

See Also:

This chapter contains the following topic:


Summary of DBMS_STREAMS_MESSAGING Subprograms

Table 98-1  DBMS_STREAMS_MESSAGING Package Subprograms
Subprogram Description

DEQUEUE Procedures

Uses the specified Streams messaging client to dequeue a message from the specified queue

ENQUEUE Procedures

The current user enqueues a message into the specified queue


DEQUEUE Procedures

These procedures use the specified Streams messaging client to dequeue a message from the specified queue.


Note:

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  SYS.AnyData,   
   dequeue_mode  IN   VARCHAR2        DEFAULT 'REMOVE',
   navigation    IN   VARCHAR2        DEFAULT 'NEXT MESSAGE',
   wait          IN   BINARY_INTEGER  DEFAULT FOREVER,
   msgid         OUT  RAW);

Parameters

Table 98-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 SYS.AnyData type.

For example, to specify a queue named streams_queue in the strmadmin schema, enter strmadmin.streams_queue for this parameter. If the schema is not specified, then the current user is the default.

streams_name

The name of the Streams messaging client. For example, if the user strmadmin is the messaging client, then specify strmadmin.

If NULL and a relevant messaging client for the queue exists, then the relevant messaging client is used. If NULL and multiple relevant messaging clients for the queue exist, then an error is raised.

payload

The payload that is dequeued

dequeue_mode

Specify one of the following settings:

REMOVE: Read the message and delete it. This setting is the default. The message can be retained in the queue table based on the retention properties.

LOCKED: Read and obtain a write lock on the message. The lock lasts for the duration of the transaction. This setting is equivalent to a select for update statement.

BROWSE: Read the message without acquiring any lock on the message. This specification is equivalent to a select statement.

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:

NEXT MESSAGE: Retrieve the next message that is available and matches the search criteria. If the previous message belongs to a message group, then retrieve the next available message that matches the search criteria and belongs to the message group. This setting is the default.

NEXT TRANSACTION: Skip the remainder of the current message group (if any) and retrieve the first message of the next message group. This setting can only be used if message grouping is enabled for the current queue.

FIRST MESSAGE: Retrieves the first message which is available and matches the search criteria. This setting resets the position to the beginning of the queue.

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 FOREVER, then the dequeue call is blocked without a time out until a message is available in the queue.

If NO_WAIT, then a wait time of zero seconds is used. In this case, the dequeue will return immediately even if there are no messages in the queue.

msgid

Specifies the message identifier of the message that is dequeued

Exceptions

Table 98-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 NO_WAIT for the wait parameter should include an exception handler that handles this exception.


ENQUEUE Procedures

These procedures enable the current user to enqueue a message into the specified queue.


Note:

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   SYS.AnyData,  
   msgid       OUT  RAW);

Parameters

Table 98-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 SYS.AnyData type.

For example, to specify a queue named streams_queue in the strmadmin schema, enter strmadmin.streams_queue for this parameter. If the schema is not specified, then the current user is the default.

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"