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.

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