2.2.7.9 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.
|
|
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 always reflects 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, and 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 can be sent back to a client running TDS 7.4 or later regardless of whether the fReadOnlyIntent bit is set in the preceding LOGIN7 record. If a client is running TDS 7.1 to 7.3, type 20 can be sent only if the fReadOnlyIntent bit is set in the preceding LOGIN7 record.