END CONVERSATION (Transact-SQL)
Ends one side of an existing conversation.
Applies to: SQL Server (SQL Server 2008 through current version).
Ending a conversation locks the conversation group that the provided conversation_handle belongs to. When a conversation ends, Service Broker removes all messages for the conversation from the service queue.
After a conversation ends, an application can no longer send or receive messages for that conversation. Both participants in a conversation must call END CONVERSATION for the conversation to complete. If Service Broker has not received an end dialog message or an Error message from the other participant in the conversation, Service Broker notifies the other participant in the conversation that the conversation has ended. In this case, although the conversation handle for the conversation is no longer valid, the endpoint for the conversation remains active until the instance that hosts the remote service acknowledges the message.
If Service Broker has not already processed an end dialog or error message for the conversation, Service Broker notifies the remote side of the conversation that the conversation has ended. The messages that Service Broker sends to the remote service depend on the options specified:
If the conversation ends without errors, and the conversation to the remote service is still active, Service Broker sends a message of type http://schemas.microsoft.com/SQL/ServiceBroker/EndDialog to the remote service. Service Broker adds this message to the transmission queue in conversation order. Service Broker sends all messages for this conversation that are currently in the transmission queue before sending this message.
If the conversation ends with an error and the conversation to the remote service is still active, Service Broker sends a message of type http://schemas.microsoft.com/SQL/ServiceBroker/Error to the remote service. Service Broker drops any other messages for this conversation currently in the transmission queue.
The WITH CLEANUP clause allows a database administrator to remove conversations that cannot complete normally. This option removes all messages and catalog view entries for the conversation. Notice that, in this case, the remote side of the conversation receives no indication that the conversation has ended, and may not receive messages that have been sent by an application but not yet transmitted over the network. Avoid this option unless the conversation cannot complete normally.
After a conversation ends, a Transact-SQL SEND statement that specifies the conversation handle causes a Transact-SQL error. If messages for this conversation arrive from the other side of the conversation, Service Broker discards those messages.
If a conversation ends while the remote service still has unsent messages for the conversation, the remote service drops the unsent messages. This is not considered an error, and the remote service receives no notification that messages have been dropped.
Failure codes specified in the WITH ERROR clause must be positive numbers. Negative numbers are reserved for Service Broker error messages.
END CONVERSATION is not valid in a user-defined function.
To end an active conversation, the current user must be the owner of the conversation, a member of the sysadmin fixed server role or a member of the db_owner fixed database role.
A member of the sysadmin fixed server role or a member of the db_owner fixed database role may use the WITH CLEANUP to remove the metadata for a conversation that has already completed.
A. Ending a conversation
The following example ends the dialog specified by @dialog_handle.
END CONVERSATION @dialog_handle ;
B. Ending a conversation with an error
The following example ends the dialog specified by @dialog_handle with an error if the processing statement reports an error. Notice that this is a simplistic approach to error handling, and may not be appropriate for some applications.
DECLARE @dialog_handle UNIQUEIDENTIFIER, @ErrorSave INT, @ErrorDesc NVARCHAR(100) ; BEGIN TRANSACTION ; <receive and process message> SET @ErrorSave = @@ERROR ; IF (@ErrorSave <> 0) BEGIN ROLLBACK TRANSACTION ; SET @ErrorDesc = N'An error has occurred.' ; END CONVERSATION @dialog_handle WITH ERROR = @ErrorSave DESCRIPTION = @ErrorDesc ; END ELSE COMMIT TRANSACTION ;
C. Cleaning up a conversation that cannot complete normally
The following example ends the dialog specified by @dialog_handle. SQL Server immediately removes all messages from the service queue and the transmission queue, without notifying the remote service. Since ending a dialog with cleanup does not notify the remote service, you should only use this in cases where the remote service is not available to receive an EndDialog or Error message.
END CONVERSATION @dialog_handle WITH CLEANUP ;