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 will contain 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 will follow 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.