2.2.7.4 COLMETADATA

  • 项目

Token Stream Name: 

 COLMETADATA

Token Stream Function:

Describes the result set for interpretation of following ROW data streams.

Token Stream Comments:

  • The token value is 0x81.

  • This token is used to tell the client the data type and length of the column data. It describes the format of the data found in a ROW data stream.

  • All COLMETADATA data streams are grouped together.

Token Stream-Specific Rules: 

 TokenType        =   BYTE
 Count            =   USHORT
  
 UserType         =   USHORT/ULONG; (Changed to ULONG in TDS 7.2)
  
 fNullable        =   BIT
 fCaseSen         =   BIT
 usUpdateable     =   2BIT        ; 0 = ReadOnly
                                  ; 1 = Read/Write
                                  ; 2 = Unused
 fIdentity        =   BIT
 fComputed        =   BIT         ; (introduced in TDS 7.2)
 usReservedODBC   =   2BIT        ; (only exists in TDS 7.3.A and below)
 fSparseColumnSet =   BIT         ; (introduced in TDS 7.3.B)
 fEncrypted       =   BIT         ; (introduced in TDS 7.4)
 usReserved3      =   BIT         ; (introduced in TDS 7.4)
 fFixedLenCLRType =   BIT         ; (introduced in TDS 7.2)
 usReserved       =   4BIT
 fHidden          =   BIT         ; (introduced in TDS 7.2)
 fKey             =   BIT         ; (introduced in TDS 7.2)
 fNullableUnknown =   BIT         ; (introduced in TDS 7.2)
  
 Flags            =  fNullable
                     fCaseSen
                     usUpdateable
                     fIdentity
                     (FRESERVEDBIT / fComputed)
                     usReservedODBC
                     (FRESERVEDBIT / fFixedLenCLRType)
                     (usReserved   / (FRESERVEDBIT fSparseColumnSet fEncrypted usReserved3))
                                  ; (introduced in TDS 7.4)
                     (FRESERVEDBIT / fHidden)
                     (FRESERVEDBIT / fKey)
                     (FRESERVEDBIT / fNullableUnknown)
  
 NumParts        =   BYTE         ; (introduced in TDS 7.2)
 PartName        =   US_VARCHAR   ; (introduced in TDS 7.2)
  
 TableName       =   NumParts
                     1*PartName
  
 ColName         =   B_VARCHAR
  
 BaseTypeInfo    =   TYPE_INFO            ; (BaseTypeInfo introduced in TDS 7.4)
  
 EncryptionAlgo  =   BYTE                 ; (EncryptionAlgo introduced in TDS 7.4)
  
 AlgoName        =   B_VARCHAR            ; (introduced in TDS 7.4)
  
 EncryptionAlgoType = BYTE                ; (introduced in TDS 7.4)
  
 NormVersion     =   BYTE                 ; (introduced in TDS 7.4)
  
 Ordinal         =   USHORT               ; (introduced in TDS 7.4)
  
 CryptoMetaData  =   Ordinal              ; (CryptoMetaData introduced in TDS 7.4)
                     UserType
                     BaseTypeInfo
                     EncryptionAlgo
                     [AlgoName]
                     EncryptionAlgoType
                     NormVersion
  
 EkValueCount    =   USHORT               ; (introduced in TDS 7.4)
  
 CekTable        =   EkValueCount         ; (introduced in TDS 7.4)
                     *EK_INFO             ; (introduced in TDS 7.4)
  
 ColumnData      =   UserType
                     Flags
                     TYPE_INFO
                     [TableName]
                     [CryptoMetaData]
                     ColName
  
 NoMetaData      =   %xFF %xFF

The TableName element is specified only if a text, ntext, or image column is included in the result set.

Token Stream Definition: 

 COLMETADATA      =   TokenType
                      Count
                      [CekTable]
                      NoMetaData / (1*ColumnData)

Token Stream Parameter Details:

Parameter

Description

TokenType

COLMETADATA_TOKEN

Count

The count of columns (number of aggregate operators) in the token stream. In the event that the client requested no metadata to be returned (see section 2.2.6.6 for information about the OptionFlags parameter in the RPCRequest token), the value of Count will be 0xFFFF. This has the same effect on Count as a zero value (for example, no ColumnData is sent).

UserType

The user type ID of the data type of the column. Depending on the TDS version that is used, valid values are 0x0000 or 0x00000000, with the exceptions of data type timestamp (0x0050 or 0x00000050) and alias types (greater than 0x00FF or 0x000000FF).

Flags

The size of the Flags parameter is always fixed at 16 bits regardless of the TDS version. Each of the 16 bits of the Flags parameter is interpreted based on the TDS version negotiated during login. Bit flags, in least significant bit order:

  • fNullable is a bit flag. Its value is 1 if the column is nullable.

  • fCaseSen is a bit flag. Set to 1 for string columns with binary collation and always for the XML data type. Set to 0 otherwise.

  • usUpdateable is a 2-bit field. Its value is 0 if column is read-only, 1 if column is read/write and 2 if updateable is unknown.

  • fIdentity is a bit flag. Its value is 1 if the column is an identity column.

  • fComputed is a bit flag. Its value is 1 if the column is a COMPUTED column.

  • usReservedODBC is a 2-bit field that is used by ODS gateways supporting the ODBC ODS gateway driver.

  • fFixedLenCLRType is a bit flag. Its value is 1 if the column is a fixed-length common language runtime user-defined type (CLR UDT).

  • fSparseColumnSet, introduced in TDS version 7.3.B, is a bit flag. Its value is 1 if the column is the special XML column for the sparse column set. For information about using column sets, see [MSDN-ColSets].

  • fEncrypted is a bit flag. Its value is 1 if the column is encrypted transparently and has to be decrypted to view the plaintext value. This flag is valid when the column encryption feature is negotiated between client and server and is turned on.

  • fHidden is a bit flag. Its value is 1 if the column is part of a hidden primary key created to support a T-SQL SELECT statement containing FOR BROWSE.<40>

  • fKey is a bit flag. Its value is 1 if the column is part of a primary key for the row and the T-SQL SELECT statement contains FOR BROWSE.

  • fNullableUnknown is a bit flag. Its value is 1 if it is unknown whether the column might be nullable.

TableName

The fully qualified base table name for this column. It contains the table name length and table name. This exists only for text, ntext, and image columns. It specifies how many parts will be returned and then repeats PartName once for each NumParts.

ColName

The column name. It contains the column name length and column name.

BaseTypeInfo

The TYPEINFO for the plaintext data.

EkValueCount

The size of CekTable. It represents the number of entries in CekTable.

CekTable

A table of various encryption keys that are used to secure the plaintext data. It contains one row for each encryption key. Each row can have multiple encryption key values, and each value represents the cipher text of the same encryption key that is secured by using a different master key. The size of this table is determined by EkValueCount. This table MUST be sent when COLUMNENCRYPTION is negotiated by client and server and is turned on.

EncryptionAlgo

This byte describes the encryption algorithm that is used.

For a custom encryption algorithm, the EncryptionAlgo value MUST be set to 0 and the actual encryption algorithm MUST be inferred from the AlgoName. For all other values, AlgoName MUST NOT be sent.

If EncryptionAlgo is set to 1, the algorithm that is used is AEAD_AES_256_CBC_HMAC_SHA512, as described in [IETF-AuthEncr] section 5.4.

If EncryptionAlgo is set to 2, the algorithm that is used is AEAD_AES_256_CBC_HMAC_SHA256.

Other values are reserved for future use.

AlgoName

Reserved for future use.

Algorithm name literal that is used for encrypting the plaintext value. This is an optional field and MUST be sent when EncryptionAlgo = 0. For all other values of EncryptionAlgo, this field MUST NOT be sent.

EncryptionAlgoType

A field that describes the encryption algorithm type. Available values are defined as follows:

1 = Deterministic encryption.

2 = Randomized encryption.

NormVersion

The normalization version to which plaintext data MUST be normalized. Version numbering starts at 0x01.

Ordinal

Where the encryption key information is located in CekTable. Ordinal starts at 0.

CryptoMetaData

This describes the encryption metadata for a column. It contains the ordinal, the UserType, the TYPE_INFO (BaseTypeInfo) for the plaintext value, the encryption algorithm that is used, the algorithm name literal, the encryption algorithm type, and the normalization version.

NoMetaData

This notifies client that no metadata will follow the COLMETADATA token. When fNoMetaData is set to 1, client notifies server that it has already cached the metadata from a previous RPC Request (section 2.2.6.6), and server sends no metadata.<41>