Documentation Home
MySQL Internals Manual


14.7.2.1 NULL-Bitmap

The binary protocol sends NULL values as bits inside a bitmap instead of a full byte as the ProtocolText::ResultsetRow does. If many NULL values are sent, it is more efficient than the old way.

Caution

For the Binary Protocol Resultset Row the num-fields and the field-pos need to add a offset of 2. For COM_STMT_EXECUTE this offset is 0.

The NULL-bitmap needs enough space to store a possible NULL bit for each column that is sent. Its space is calculated with:

NULL-bitmap-bytes = (num-fields + 7 + offset) / 8

resulting in:

num-fields+offset

NULL-bitmap-bytes

0

0

1

1

[...]

[...]

8

1

9

2

[...]

[...]

To store a NULL bit in the bitmap, you need to calculate the bitmap-byte (starting with 0) and the bitpos (starting with 0) in that byte from the field-index (starting with 0):

NULL-bitmap-byte = ((field-pos + offset) / 8)
NULL-bitmap-bit  = ((field-pos + offset) % 8)

Example:

Resultset Row, 9 fields, 9th field is a NULL (9th field -> field-index == 8, offset == 2)

nulls -> [00] [00]

byte_pos = (10 / 8) = 1
bit_pos  = (10 % 8) = 2

nulls[byte_pos] |= 1 << bit_pos
nulls[1] |= 1 << 2;

nulls -> [00] [04]

User Comments
User comments in this section are, as the name implies, provided by MySQL users. The MySQL documentation team is not responsible for, nor do they endorse, any of the information provided here.
Sign Up Login You must be logged in to post a comment.