Export (0) Print
Expand All

2.2.7.8 ENVCHANGE

Token Stream Name:

ENVCHANGE

Token Stream Function:

A notification of an environment change (for example, database, language, and so on).

Token Stream Comments:

  • The token value is 0xE3.

  • Includes old and new environment values.

  • Type 4 (Packet size) is sent in response to a LOGIN7 message. The server MAY send a value different from the packet size requested by the client. That value MUST be greater than or equal to 512 and smaller than or equal to 32767. Both the client and the server MUST start using this value for packet size with the message following the login response message.

  • Type 13 (Database Mirroring) is sent in response to a LOGIN7 message whenever connection is requested to a database that it is being served as primary in real-time log shipping. The ENVCHANGE stream reflects the name of the partner node of the database that is being log shipped.

  • Type 15 (Promote Transaction) is sent in response to transaction manager requests with requests of type 6 (TM_PROMOTE_XACT).

  • Type 16 (Transaction Manager Address) is sent in response to transaction manager requests with requests of type 0 (TM_GET_DTC_ADDRESS).

  • Type 20 (Routing) is sent in response to a LOGIN7 message when the server wants to route the client to an alternate server. The ENVCHANGE stream returns routing information for the alternate server. If the server decides to send the Routing ENVCHANGE token, the Routing ENVCHANGE token MUST be sent after the LOGINACK token in the login response.

Token Stream-Specific Rules:

TokenType        =   BYTE
Length           =   USHORT

Type             =   BYTE

EnvValueData     =   Type
                     NewValue
                     [OldValue]

Token Stream Definition:

ENVCHANGE        =   TokenType
                     Length
                     EnvValueData

Token Stream Parameter Details

Parameter

Description

TokenType

ENVCHANGE_TOKEN

Length

The total length of the ENVCHANGE data stream (EnvValueData).

Type

The type of environment change:

Note Types 8 to 19 were introduced in TDS 7.2. Type 20 was introduced in TDS 7.4.

  • 1: Database

  • 2: Language

  • 3: Character set

  • 4: Packet size

  • 5: Unicode data sorting local id

  • 6: Unicode data sorting comparison flags

  • 7: SQL Collation

  • 8: Begin Transaction (described in [MSDN-BEGIN])

  • 9: Commit Transaction (described in [MSDN-COMMIT])

  • 10: Rollback Transaction

  • 11: Enlist DTC Transaction

  • 12: Defect Transaction

  • 13: Real Time Log Shipping

  • 15: Promote Transaction

  • 16: Transaction Manager Address<15>

  • 17: Transaction ended

  • 18: RESETCONNECTION/RESETCONNECTIONSKIPTRAN Completion Acknowledgement

  • 19: Sends back name of user instance started per login request

  • 20: Sends routing information to client

Type

Old Value

New Value

1: Database

OLDVALUE = B_VARCHAR

NEWVALUE = B_VARCHAR

2: Language

OLDVALUE = B_VARCHAR

NEWVALUE = B_VARCHAR

3: Character Set

OLDVALUE = B_VARCHAR

NEWVALUE = B_VARCHAR

4: Packet Size

OLDVALUE = B_VARCHAR

NEWVALUE = B_VARCHAR

5: Unicode data sorting local id

OLDVALUE = %x00

NEWVALUE = B_VARCHAR

6: Unicode data sorting comparison flags

OLDVALUE = %x00

NEWVALUE = B_VARCHAR

7: SQL Collation

OLDVALUE = B_VARBYTE

NEWVALUE = B_VARBYTE

8: Begin Transaction

OLDVALUE = %x00

NEWVALUE = B_VARBYTE

9: Commit Transaction

OLDVALUE = B_VARBYTE

NEWVALUE = "0x00"

10: Rollback Transaction

OLDVALUE = B_VARBYTE

NEWVALUE = %x00

11: Enlist DTC Transaction

OLDVALUE = B_VARBYTE

NEWVALUE = %x00

12: Defect Transaction

OLDVALUE = %x00

NEWVALUE = B_VARBYTE

13: Database Mirroring Partner

OLDVALUE = %x00

PARTNER_NODE = B_VARCHAR

NEWVALUE = PARTNER_NODE

15: Promote Transaction

OLDVALUE = %x00

DTC_TOKEN = L_VARBYTE;

NEWVALUE = DTC_TOKEN

16: Transaction Manager Address (not used)

OLDVALUE = %x00

XACT_MANAGER_ADDRESS = B_VARBYTE

NEWVALUE = XACT_MANAGER_ADDRESS

17: Transaction Ended

OLDVALUE = B_VARBYTE

NEWVALUE = %x00

18: Reset Completion Acknowledgement

OLDVALUE = %x00

NEWVALUE = %x00

19: Sends back info of user instance for logins (login7) requesting so.

OLDVALUE = %x00

NEWVALUE = B_VARCHAR

20: Routing

OLDVALUE = %x00 %x00

Protocol = BYTE

ProtocolProperty = USHORT

AlternateServer = US_VARCHAR

Protocol MUST be 0, specifying TCP-IP protocol. ProtocolProperty represents the TCP-IP port when Protocol is 0. A ProtocolProperty value of zero is not allowed when Protocol is TCP-IP.

RoutingDataValue = Protocol

ProtocolProperty

AlternateServer

RoutingDataValueLength = USHORT

RoutingDataValueLength is the total length, in bytes, of the following fields: Protocol, ProtocolProperty, and AlternateServer.

RoutingData = RoutingDataValueLength

[RoutingDataValue]

NEWVALUE = RoutingData

Notes

  • For types 1, 2, 3, 4, 5, 6, 13, and 19, the payload is a Unicode string; the LENGTH will always reflect the number of bytes.

  • ENVCHANGE types 3, 5, and 6 are only sent back to clients running TDS 7.0 or earlier.

  • For Types 8, 9, 10, 11, 12 the ENVCHANGE event is returned only if the transaction lifetime is controlled by the user for example explicit transaction commands, including transactions started by SET IMPLICIT_TRANSACTIONS ON.

  • For transactions started/committed under auto commit, no stream is generated.

  • For operations that change only the value of @@trancount, no ENVCHANGE stream is generated.

  • The payload of NEWVALUE for ENVCHANGE types 8, 11, and 17 and the payload of OLDVALUE for ENVCHANGE types 9, 10, and 12 is a ULONGLONG.

  • ENVCHANGE type 11 is sent by the server to confirm that it has joined a distributed transaction as requested through a TM_PROPAGATE_XACT request from the client.

  • ENVCHANGE type 12 is only sent when a batch defects from either a DTC or bound session transaction.

  • LENGTH for ENVCHANGE type 15 is sent as 0x01 indicating only the length of the type token. Client drivers are responsible for reading the additional payload if type is 15.

  • ENVCHANGE type 17 is sent when a batch is used that specified a descriptor for a transaction that has ended. This is only sent in the bound session case. For information about using bound sessions, see [MSDN-BOUND].

  • ENVCHANGE type 18 always produces empty (0x00) old and new values. It simply acknowledges completion of execution of a RESETCONNECTION/RESETCONNECTIONSKIPTRAN request.

  • ENVCHANGE type 19 is sent after LOGIN and after /RESETCONNECTION/RESETCONNECTIONSKIPTRAN when a client has requested use of user instances. It is sent prior to the LOGINACK token.

  • ENVCHANGE type 20 MAY be sent back to a client running TDS 7.4 or later whether or not the fReadOnlyIntent bit is set in the preceding LOGIN7 record. Type 20 MAY be sent to a TDS client running TDS 7.1 to 7.3 but only when the fReadOnlyIntent bit is set in the preceding LOGIN7 record.

 
Show:
© 2014 Microsoft