GET CONVERSATION GROUP (Transact-SQL)
Returns the conversation group identifier for the next message to be received, and locks the conversation group for the conversation that contains the message. The conversation group identifier can be used to retrieve conversation state information before retrieving the message itself.
Syntax
[ WAITFOR ( ]
GET CONVERSATION GROUP @conversation_group_id
FROM <queue>
[ ) ] [ , TIMEOUT timeout ]
[ ; ]
<queue> ::=
{
[ database_name . [ schema_name ] . | schema_name . ] queue_name
}
Arguments
- WAITFOR
Specifies that the GET CONVERSATION GROUP statement waits for a message to arrive on the queue if no messages are currently present.
- @conversation_group_id
Is a variable used to store the conversation group ID returned by the GET CONVERSATION GROUP statement. The variable must be of type uniqueidentifier. If there are no conversation groups available, the variable is set to NULL.
- FROM
Specifies the queue to get the conversation group from.
- database_name
Is the name of the database that contains the queue to get the conversation group from. When no database_name is provided, defaults to the current database.
- schema_name
Is the name of the schema that owns the queue to get the conversation group from. When no schema_name is provided, defaults to the default schema for the current user.
- queue_name
Is the name of the queue to get the conversation group from.
- TIMEOUT timeout
Specifies the length of time, in milliseconds, that Service Broker waits for a message to arrive on the queue. This clause may only be used with the WAITFOR clause. If a statement that uses WAITFOR does not include this clause or the timeout is -1, the wait time is unlimited. If the timeout expires, GET CONVERSATION GROUP sets the @conversation_group_id variable to NULL.
Remarks
Important
If the GET CONVERSATION GROUP statement is not the first statement in a batch or stored procedure, the preceding statement must be terminated with a semicolon (;), the Transact-SQL statement terminator.
If the queue specified in the GET CONVERSATION GROUP statement is unavailable, the statement fails with a Transact-SQL error.
This statement returns the next conversation group that the connection can successfully lock and that has available messages. Therefore, successive calls to GET CONVERSATION GROUP within the same transaction may lock more than one conversation group. If no conversation group is available, the statement returns NULL as the conversation group identifier.
When the WAITFOR clause is specified, the statement waits for the timeout specified, or until a conversation group is available. If the queue is dropped while the statement is waiting, the statement immediately returns an error.
GET CONVERSATION GROUP is not valid in a user-defined function.
Permissions
To get a conversation group identifier from a queue, the current user must have RECEIVE permission on the queue.
Examples
A. Getting a conversation group, waiting indefinitely
This example sets @conversation_group_id to the conversation group identifier for the next available message on ExpenseQueue. The command waits until a message becomes available.
DECLARE @conversation_group_id UNIQUEIDENTIFIER ;
WAITFOR (
GET CONVERSATION GROUP @conversation_group_id
FROM ExpenseQueue
) ;
B. Getting a conversation group, waiting one minute
This example sets @conversation_group_id to the conversation group identifier for the next available message on ExpenseQueue. If no message becomes available within one minute, GET CONVERSATION GROUP returns without changing the value of @conversation_group_id.
DECLARE @conversation_group_id UNIQUEIDENTIFIER
WAITFOR (
GET CONVERSATION GROUP @conversation_group_id
FROM ExpenseQueue ),
TIMEOUT 60000 ;
C. Getting a conversation group, returning immediately
This example sets @conversation_group_id to the conversation group identifier for the next available message on ExpenseQueue. If no message is available, GET CONVERSATION GROUP returns immediately without changing @conversation_group_id.
DECLARE @conversation_group_id UNIQUEIDENTIFIER ;
GET CONVERSATION GROUP @conversation_group_id
FROM AdventureWorks.dbo.ExpenseQueue ;
See Also
Reference
BEGIN DIALOG CONVERSATION (Transact-SQL)
MOVE CONVERSATION (Transact-SQL)