2.2.6.9 Transaction Manager Request

Article
04/10/2023

Stream Name:

 TransMgrReq

Stream Function:

Query and control operations pertaining to the lifecycle and state of local and distributed transaction objects. Note that distributed transaction operations are coordinated through a Distributed Transaction Coordinator (DTC) implemented to the DTC Interface Specification. For more information about DTC, see [MSDN-DTC].

Stream Comments:

Packet header type 0x0E.
A sample Transaction Manager Request message is given in section 4.13.

Stream-Specific Rules:

 RequestType      =   USHORT

Stream Definition:

 TransMgrReq      =   ALL_Headers
                      RequestType
                      [RequestPayload]

RequestPayload details are as specified in the following table.

Stream Parameter Details

Parameter	Description
RequestType	The types of transaction manager operations that are requested by the client are specified as follows. If an unknown Type is specified, the message receiver SHOULD disconnect the connection. 0 = TM_GET_DTC_ADDRESS. Returns DTC network address as a result set with a single-column, single-row binary value. 1 = TM_PROPAGATE_XACT. Imports DTC transaction into the server and returns a local transaction descriptor as a varbinary result set. 5 = TM_BEGIN_XACT. Begins a transaction and returns the descriptor in an ENVCHANGE type 8. 6 = TM_PROMOTE_XACT. Converts an active local transaction into a distributed transaction and returns an opaque buffer in an ENVCHANGE type 15. 7 = TM_COMMIT_XACT. Commits a transaction. Depending on the payload of the request, it can additionally request that another local transaction be started. 8 = TM_ROLLBACK_XACT. Rolls back a transaction. Depending on the payload of the request, it can indicate that after the rollback, a local transaction is to be started. 9 = TM_SAVE_XACT. Sets a savepoint within the active transaction. This request MUST specify a nonempty name for the savepoint. Request types 5 through 9 were introduced in TDS 7.2.
RequestPayload	For RequestType TM_GET_DTC_ADDRESS: The RequestPayload SHOULD be a zero-length US_VARBYTE. RequestPayload = US_VARBYTE For RequestType TM_PROPAGATE_XACT: Data contains an opaque buffer used by the server to enlist in a DTC transaction (for more information, see [MSDN-ITrans]). RequestPayload = US_VARBYTE For RequestType TM_BEGIN_XACT: ISOLATION_LEVEL = BYTE BEGIN_XACT_NAME = B_VARBYTE RequestPayload = ISOLATION_LEVEL BEGIN_XACT_NAME This request begins a new transaction, or increments trancount if already in a transaction. If BEGIN_XACT_NAME is nonempty, a transaction is started with the specified name. See the definition for isolation level at the end of this table. For RequestType TM_PROMOTE_XACT – No payload. This message promotes the transaction of the current request (specified in the Transaction Descriptor header, section 2.2.5.3.2). The current transaction MUST be part of the specified header. Note that TM_PROMOTE_XACT is supported only for transactions initiated via TM_BEGIN_XACT, or via piggy back operation on TM_COMMIT/TM_ROLLBACK. An error is returned if TM_PROMOTE_XACT is invoked for a TSQL initiated transaction. For RequestType TM_COMMIT_XACT: fBeginXact = BIT XACT_FLAGS = fBeginXact 7FRESERVEDBIT ISOLATION_LEVEL = BYTE XACT_NAME = B_VARBYTE BEGIN_XACT_NAME = B_VARBYTE RequestPayload = XACT_NAME XACT_FLAGS [ISOLATION_LEVEL BEGIN_XACT_NAME] Without additional flags specified, this command is semantically equivalent to issuing a TSQL COMMIT statement. The flags in XACT_FLAGS are represented in least significant bit order. If fBeginXact is 1, then a new local transaction is started after the commit operation is done. If fBeginXact is 1, then ISOLATION_LEVEL can specify the isolation level to use to start the new transaction, according to the definition at the end of this table. If fBeginXact is 0, then ISOLATION_LEVEL SHOULD NOT be present. Specifying ISOLATION_LEVEL allows the isolation level to remain in effect for the session, once the transaction ends. If fBeginXact is 0, BEGIN_XACT_NAME SHOULD NOT be present. If fBeginXact is 1, BEGIN_XACT_NAME can be nonempty. If fBeginXact is 1, a new transaction MUST be started. If BEGIN_XACT_NAME is nonempty, the new transaction MUST be given the specified name. See the definition for isolation level at the end of this table. For RequestType TM_ROLLBACK_XACT: fBeginXact = BIT XACT_FLAGS = fBeginXact 7FRESERVEDBIT ISOLATION_LEVEL = BYTE XACT_NAME = B_VARBYTE BEGIN_XACT_NAME = B_VARBYTE RequestPayload = XACT_NAME XACT_FLAGS [ISOLATION_LEVEL BEGIN_XACT_NAME] The flags in XACT_FLAGS are represented in least significant bit order. If XACT_NAME is nonempty, this request rolls back the named transaction. This implies that if XACT_NAME specifies a savepoint name, the rollback only goes back until the specified savepoint. Without additional flags specified, this command is semantically equivalent to issuing a TSQL ROLLBACK statement under the current transaction. If fBeginXact is 1, then a new local transaction is started after the commit operation is done. If fBeginXact is 1, then ISOLATION_LEVEL can specify the isolation level to use to start the new transaction, according to the definition at the end of this table. If fBeginXact is 0, then ISOLATION_LEVEL SHOULD NOT be present. Specifying ISOLATION_LEVEL allows the isolation level to remain in effect for the session, once the transaction ends. If fBeginXact is 0, BEGIN_XACT_NAME SHOULD NOT be present. If fBeginXact is 1, BEGIN_XACT_NAME can be nonempty. If fBeginXact is 1, a new transaction MUST be started. If BEGIN_XACT_NAME is nonempty, the new transaction MUST be given the specified name. If fBeginXact is 1, and the ROLLBACK only rolled back to a savepoint, the Begin_Xact operation is ignored and trancount remains unchanged. See the definition for isolation level at the end of this table. For RequestType TM_SAVE_XACT: XACT_SAVEPOINT_NAME = B_VARBYTE RequestPayload = XACT_SAVEPOINT_NAME A nonempty name MUST be specified as part of this request. Otherwise, an error is raised.

Parameter

Description

RequestType

The types of transaction manager operations that are requested by the client are specified as follows. If an unknown Type is specified, the message receiver SHOULD disconnect the connection.

0 = TM_GET_DTC_ADDRESS. Returns DTC network address as a result set with a single-column, single-row binary value.
1 = TM_PROPAGATE_XACT. Imports DTC transaction into the server and returns a local transaction descriptor as a varbinary result set.
5 = TM_BEGIN_XACT. Begins a transaction and returns the descriptor in an ENVCHANGE type 8.
6 = TM_PROMOTE_XACT. Converts an active local transaction into a distributed transaction and returns an opaque buffer in an ENVCHANGE type 15.
7 = TM_COMMIT_XACT. Commits a transaction. Depending on the payload of the request, it can additionally request that another local transaction be started.
8 = TM_ROLLBACK_XACT. Rolls back a transaction. Depending on the payload of the request, it can indicate that after the rollback, a local transaction is to be started.
9 = TM_SAVE_XACT. Sets a savepoint within the active transaction. This request MUST specify a nonempty name for the savepoint.

Request types 5 through 9 were introduced in TDS 7.2.

RequestPayload

For RequestType TM_GET_DTC_ADDRESS: The RequestPayload SHOULD be a zero-length US_VARBYTE.
```
 RequestPayload     =   US_VARBYTE
```
For RequestType TM_PROPAGATE_XACT: Data contains an opaque buffer used by the server to enlist in a DTC transaction (for more information, see [MSDN-ITrans]).
```
 RequestPayload     =   US_VARBYTE
```
For RequestType TM_BEGIN_XACT:
```
 ISOLATION_LEVEL    =   BYTE
 BEGIN_XACT_NAME    =   B_VARBYTE
  
 RequestPayload     =   ISOLATION_LEVEL 
                        BEGIN_XACT_NAME
```
This request begins a new transaction, or increments trancount if already in a transaction. If BEGIN_XACT_NAME is nonempty, a transaction is started with the specified name. See the definition for isolation level at the end of this table.
For RequestType TM_PROMOTE_XACT – No payload.

This message promotes the transaction of the current request (specified in the Transaction Descriptor header, section 2.2.5.3.2). The current transaction MUST be part of the specified header.

Note that TM_PROMOTE_XACT is supported only for transactions initiated via TM_BEGIN_XACT, or via piggy back operation on TM_COMMIT/TM_ROLLBACK. An error is returned if TM_PROMOTE_XACT is invoked for a TSQL initiated transaction.
For RequestType TM_COMMIT_XACT:
```
 fBeginXact         =   BIT
  
 XACT_FLAGS         =   fBeginXact
                        7FRESERVEDBIT
  
 ISOLATION_LEVEL    =   BYTE
  
 XACT_NAME          =   B_VARBYTE
 BEGIN_XACT_NAME    =   B_VARBYTE
  
 RequestPayload     =   XACT_NAME
                        XACT_FLAGS
                        [ISOLATION_LEVEL
                        BEGIN_XACT_NAME]
```
Without additional flags specified, this command is semantically equivalent to issuing a TSQL COMMIT statement.

The flags in XACT_FLAGS are represented in least significant bit order.

If fBeginXact is 1, then a new local transaction is started after the commit operation is done.

If fBeginXact is 1, then ISOLATION_LEVEL can specify the isolation level to use to start the new transaction, according to the definition at the end of this table. If fBeginXact is 0, then ISOLATION_LEVEL SHOULD NOT be present.

Specifying ISOLATION_LEVEL allows the isolation level to remain in effect for the session, once the transaction ends.

If fBeginXact is 0, BEGIN_XACT_NAME SHOULD NOT be present. If fBeginXact is 1, BEGIN_XACT_NAME can be nonempty.

If fBeginXact is 1, a new transaction MUST be started. If BEGIN_XACT_NAME is nonempty, the new transaction MUST be given the specified name.

See the definition for isolation level at the end of this table.
For RequestType TM_ROLLBACK_XACT:
```
 fBeginXact         =   BIT
  
 XACT_FLAGS         =   fBeginXact
                        7FRESERVEDBIT
  
 ISOLATION_LEVEL    =   BYTE
  
 XACT_NAME          =   B_VARBYTE
 BEGIN_XACT_NAME    =   B_VARBYTE
  
 RequestPayload     =   XACT_NAME
                        XACT_FLAGS
                        [ISOLATION_LEVEL
                        BEGIN_XACT_NAME]
```
The flags in XACT_FLAGS are represented in least significant bit order.

If XACT_NAME is nonempty, this request rolls back the named transaction. This implies that if XACT_NAME specifies a savepoint name, the rollback only goes back until the specified savepoint.

Without additional flags specified, this command is semantically equivalent to issuing a TSQL ROLLBACK statement under the current transaction.

If fBeginXact is 1, then a new local transaction is started after the commit operation is done.

If fBeginXact is 1, then ISOLATION_LEVEL can specify the isolation level to use to start the new transaction, according to the definition at the end of this table. If fBeginXact is 0, then ISOLATION_LEVEL SHOULD NOT be present.

Specifying ISOLATION_LEVEL allows the isolation level to remain in effect for the session, once the transaction ends.

If fBeginXact is 0, BEGIN_XACT_NAME SHOULD NOT be present. If fBeginXact is 1, BEGIN_XACT_NAME can be nonempty.

If fBeginXact is 1, a new transaction MUST be started. If BEGIN_XACT_NAME is nonempty, the new transaction MUST be given the specified name.

If fBeginXact is 1, and the ROLLBACK only rolled back to a savepoint, the Begin_Xact operation is ignored and trancount remains unchanged.

See the definition for isolation level at the end of this table.
For RequestType TM_SAVE_XACT:
```
 XACT_SAVEPOINT_NAME   =   B_VARBYTE
  
 RequestPayload        =   XACT_SAVEPOINT_NAME
```
A nonempty name MUST be specified as part of this request. Otherwise, an error is raised.

ISOLATION_LEVEL MUST have one of the following values.

Value	Description
0x00	No isolation level change requested. Use current.
0x01	Read Uncommitted.
0x02	Read Committed.
0x03	Repeatable Read.
0x04	Serializable.
0x05	Snapshot.

2.2.6.9 Transaction Manager Request

Additional resources