END CONVERSATION (Transact-SQL)

**APPLIES TO:** ![yes](media/yes.png)SQL Server (starting with 2008) ![no](media/no.png)Azure SQL Database ![no](media/no.png)Azure SQL Data Warehouse ![no](media/no.png)Parallel Data Warehouse

Ends one side of an existing conversation.

Topic link icon Transact-SQL Syntax Conventions

Syntax

  
END CONVERSATION conversation_handle  
   [   [ WITH ERROR = failure_code DESCRIPTION = 'failure_text' ]  
     | [ WITH CLEANUP ]  
    ]  
[ ; ]  

Arguments

conversation_handle
Is the conversation handle for the conversation to end.

WITH ERROR =failure_code
Is the error code. The failure_code is of type int. The failure code is a user-defined code that is included in the error message sent to the other side of the conversation. The failure code must be greater than 0.

DESCRIPTION =failure_text
Is the error message. The failure_text is of type nvarchar(3000). The failure text is user-defined text that is included in the error message sent to the other side of the conversation.

WITH CLEANUP
Removes all messages and catalog view entries for one side of a conversation that cannot complete normally. The other side of the conversation is not notified of the cleanup. Microsoft Microsoft SQL Server drops the conversation endpoint, all messages for the conversation in the transmission queue, and all messages for the conversation in the service queue. Administrators can use this option to remove conversations which cannot complete normally. For example, if the remote service has been permanently removed, an administrator can use WITH CLEANUP to remove conversations to that service. Do not use WITH CLEANUP in the code of a Microsoft SQL Server Service Broker application. If END CONVERSATION WITH CLEANUP is run before the receiving endpoint acknowledges receiving a message, the sending endpoint will send the message again. This could potentially re-run the dialog.

Remarks

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 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 Service Broker notifies the remote side of the conversation that the conversation has ended. The messages that Service Broker Service Broker Service Broker sends to the remote service depend on the options specified:

After a conversation ends, a Transact\-SQL SEND statement that specifies the conversation handle causes a Transact\-SQL Transact\-SQL error. If messages for this conversation arrive from the other side of the conversation, Transact\-SQL Transact\-SQL 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.

Permissions

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.

Examples

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 ;  

See Also

BEGIN CONVERSATION TIMER (Transact-SQL)
BEGIN DIALOG CONVERSATION (Transact-SQL)
sys.conversation_endpoints (Transact-SQL)