2.2.7.15 NBCROW
Token Stream Name:
-
NBCROW
Token Stream Function:
NBCROW, introduced in TDS 7.3.B, is used to send a row as defined by the COLMETADATA token (section 2.2.7.4) to the client with null bitmap compression. Null bitmap compression is implemented by using a single bit to specify whether the column is null or not null and also by removing all null column values from the row. Removing the null column values (which can be up to 8 bytes per null instance) from the row provides the compression. The null bitmap contains one bit for each column defined in COLMETADATA. In the null bitmap, a bit value of 1 means that the column is null and therefore not present in the row, and a bit value of 0 means that the column is not null and is present in the row. The null bitmap is always rounded up to the nearest multiple of 8 bits, so there might be 1 to 7 leftover reserved bits at the end of the null bitmap in the last byte of the null bitmap. NBCROW is only used by TDS result set streams from server to client. NBCROW MUST NOT be used in BulkLoadBCP streams. NBCROW MUST NOT be used in TVP row streams.
Token Stream Comments
The token value is 0xD2/210.
Token Stream-Specific Rules:
-
TokenType = BYTE TextPointer = B_VARBYTE Timestamp = 8BYTE Data = TYPE_VARBYTE NullBitmap = <NullBitmapByteCount> BYTE ; see note on NullBitmapByteCount ColumnData = [TextPointer Timestamp] Data AllColumnData = *ColumnData
ColumnData is repeated once for each non-null column of data.
NullBitmapBitCount is equal to the number of columns in COLMETADATA.
NullBitmapByteCount is equal to the smallest number of bytes needed to hold 'NullBitmapBitCount' bits.
The server can decide to send either a NBCROW token or a ROW token. For example, the server might choose to send a ROW token if there is no byte savings if the result set has no nullable columns, or if a particular row in a result set has no null values. This implies that NBCROW and ROW tokens can be intermixed in the same result set.
When determining whether or not a specific column is null, consider all the columns from left to right ordered using a zero-based index from 0 to 65534 as they occur in the ColumnData section of the COLMETADATA token. The null bitmap indicates that a column is null using a zero bit at the following byte and bit layout:
-
Byte 1 Byte 2 Byte 3 ----------------------- ----------------------- ----------------------- 07 06 05 04 03 02 01 00 15 14 13 12 11 10 09 08 23 22 21 20 19 18 17 16
Hence the first byte contains flags for columns 0 through 7, with the least significant (or rightmost) bit within the byte indicating the zeroth column and the most significant (or leftmost) bit within the byte indicating the seventh column. For example, column index 8 would be in the second byte as the least significant bit. If the null bitmap bit is set, the column is null and no null token value for the column follows in the row. If the null bitmap bit is clear, the column is not null and the value for the column follows in the row.
Token Stream Definition:
-
NBCROW = TokenType NullBitmap AllColumnData
Token Stream Parameter Details
Parameter |
Description |
---|---|
TokenType |
NBCROW_TOKEN (0xD2) |
TextPointer |
The length of the text pointer and the text pointer for Data. |
Timestamp |
The time stamp of a text/image column. |
Data |
The actual data for the column. The TYPE_INFO information describing the data type of this data is given in the preceding COLMETADATA_TOKEN. |