Skip to content

Latest commit

 

History

History
138 lines (100 loc) · 4.21 KB

sp-getbindtoken-transact-sql.md

File metadata and controls

138 lines (100 loc) · 4.21 KB
title description author ms.author ms.reviewer ms.date ms.service ms.subservice ms.topic f1_keywords helpviewer_keywords dev_langs
sp_getbindtoken (Transact-SQL)
sp_getbindtoken returns a unique identifier for the transaction.
markingmyname
maghan
randolphwest
03/07/2025
sql
system-objects
reference
sp_getbindtoken
sp_getbindtoken_TSQL
sp_getbindtoken
TSQL

sp_getbindtoken (Transact-SQL)

[!INCLUDE SQL Server]

Returns a unique identifier for the transaction. This unique identifier is a string used to bind sessions using sp_bindsession.

Important

[!INCLUDE ssNoteDepFutureAvoid] Use Multiple Active Results Sets (MARS) or distributed transactions instead. For more information, see Using Multiple Active Result Sets (MARS) in SQL Server Native Client.

:::image type="icon" source="../../includes/media/topic-link-icon.svg" border="false"::: Transact-SQL syntax conventions

Syntax

sp_getbindtoken [ @out_token = ] 'out_token' OUTPUT
[ ; ]

Arguments

[!INCLUDE extended-stored-procedures]

[ @out_token = ] 'out_token'

The token to use to bind sessions. @out_token is varchar(255), with no default.

Return code values

None.

Result set

None.

Remarks

sp_getbindtoken returns a valid token only when the stored procedure is executed inside an active transaction. Otherwise, the [!INCLUDE ssDE] returns an error message. For example:

-- Declare a variable to hold the bind token.
-- No active transaction.
DECLARE @bind_token varchar(255);

-- Trying to get the bind token returns an error 3921.
EXECUTE sp_getbindtoken @bind_token OUTPUT;

[!INCLUDE ssresult-md]

Server: Msg 3921, Level 16, State 1, Procedure sp_getbindtoken, Line 4
Cannot get a transaction token if there is no transaction active.
Reissue the statement after a transaction has been started.

When sp_getbindtoken is used to enlist a distributed transaction connection inside an open transaction, [!INCLUDE ssNoVersion] returns the same token. For example:

USE AdventureWorks2022;
GO

DECLARE @bind_token VARCHAR(255);
BEGIN TRANSACTION;
EXECUTE sp_getbindtoken @bind_token OUTPUT;
SELECT @bind_token AS Token1;
BEGIN DISTRIBUTED TRANSACTION;
EXECUTE sp_getbindtoken @bind_token OUTPUT;
SELECT @bind_token AS Token2;
--COMMIT TRANSACTION;
--COMMIT TRANSACTION;

Both SELECT statements return the same token:

Token1
------
PKb'gN5<9aGEedk_16>8U=5---/5G=--

Token2
------
PKb'gN5<9aGEedk_16>8U=5---/5G=--

The bind token can be used with sp_bindsession to bind new sessions to the same transaction. The bind token is only valid locally inside each instance of the [!INCLUDE ssDE] and can't be shared across multiple instances.

To obtain and pass a bind token, you must run sp_getbindtoken before executing sp_bindsession for sharing the same lock space. If you obtain a bind token, sp_bindsession runs correctly.

Note

We recommend that you use the srv_getbindtoken Open Data Services application programming interface (API) to obtain a bind token to be used from an extended stored procedure.

Permissions

Requires membership in the public role.

Examples

The following example obtains a bind token and displays the bind token name.

DECLARE @bind_token VARCHAR(255);
BEGIN TRANSACTION;
EXECUTE sp_getbindtoken @bind_token OUTPUT;
SELECT @bind_token AS Token;
--COMMIT TRANSACTION;

[!INCLUDE ssResult]

Token
-----
\0]---5^PJK51bP<1F<-7U-]ANZ

Related content