Export (0) Print
Expand All
Expand Minimize
This topic has not yet been rated - Rate this topic

sp_getbindtoken (Transact-SQL)

Windows Server 2003

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

Dd883744.note(en-us,MSDN.10).gifImportant:
This feature will be removed in a future version of Microsoft SQL Server. Avoid using this feature in new development work, and plan to modify applications that currently use this feature. Use Multiple Active Results Sets (MARS) or distributed transactions instead. For more information, see Using Multiple Active Result Sets (MARS) or Distributed Transactions (Database Engine).

Topic link icon Transact-SQL Syntax Conventions


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

Is the token to use to bind sessions. return_value is varchar(255) with no default.

In SQL Server 2000 and later, sp_getbindtoken will return a valid token only when the stored procedure is executed inside an active transaction. Otherwise, the Database Engine will return 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;
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.
Dd883744.note(en-us,MSDN.10).gifNote:
In SQL Server 7.0, sp_getbindtoken returns a valid token even if the stored procedure is executed outside an active transaction. The previous example works in SQL Server 7.0, but not in SQL Server 2000 or later.

When sp_getbindtoken is used to enlist a distributed transaction connection inside an open transaction, SQL Server 2000 or later returns the same token. For example:

USE AdventureWorks;
GO
DECLARE @bind_token varchar(255);

BEGIN TRAN;

EXECUTE sp_getbindtoken @bind_token OUTPUT;
SELECT @bind_token AS Token;

BEGIN DISTRIBUTED TRAN;

EXECUTE sp_getbindtoken @bind_token OUTPUT;
SELECT @bind_token AS Token;

Both SELECT statements return the same token:

Token
-----
PKb'gN5<9aGEedk_16>8U=5---/5G=--
(1 row(s_) affected)

Token
-----
PKb'gN5<9aGEedk_16>8U=5---/5G=--
(1 row(s_) affected)

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 Database Engine and cannot 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.

Dd883744.note(en-us,MSDN.10).gifNote:
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.

Requires membership in the public role.

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

DECLARE @bind_token varchar(255);
BEGIN TRAN;
EXECUTE sp_getbindtoken @bind_token OUTPUT;
SELECT @bind_token AS Token;

Here is the result set.

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

Reference

sp_bindsession (Transact-SQL)
System Stored Procedures (Transact-SQL)

Other Resources

Using Bound Sessions
srv_getbindtoken (Extended Stored Procedure API)

Help and Information

Getting SQL Server 2005 Assistance
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.