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 is 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:
|
|
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 the number of parts that are 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 follows 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.<42> |