2.2.9.1 EntityKey Structure

  • Article

The EntityKey structure specifies a collection of key column values corresponding to an instance of an entity. 

 EntityKey = flags [nullValueBits] *KeyValue


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

flags

nullValueBits (variable)

...

keyValues (variable)

...

flags (1 byte): A byte field that specifies the structure of the EntityKey. This field is a bitmask and is specified by the following bit fields.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

reserved

A

reserved (7 bits): The value MUST be zero.

A  (1 bit): IncludeNullValues - A bit that specifies that the next set of bytes contains a null value bitmask array (nullValueBits). IncludeNullValues is the most significant bit (MSB) of the flags field.

Value

Meaning

0

The null value bitmask array (nullValueBits) is not present, and the next set of bytes is the keyValues array.

1

The null value bitmask array (nullValueBits) is present.

nullValueBits (variable): An optional bit array that specifies for each key column whether the value of the key column is NULL. If a bit in this array is set to 1, the value of the corresponding key column is NULL, and the value of the key column is omitted from the key values array (keyValues). If a bit in this array is set to 0, then the value of the corresponding key column is included in the key values array (keyValues).

The nullValueBits bit array is not present if IncludeNullValues is set to 0. If the number of key columns is not a multiple of 8, padding is placed in the least significant bits (LSB) of the last byte. These padding bits are not used and can contain any value.

The size of the nullValueBits field, in bytes, is calculated using the following formula:

size of nullValueBits in bytes = 1+floor(n / 8), where n is the number of key columns for the entity.

The padding of this field, in bits, is calculated using the following formula:

padding = size of nullValueBits in bits – n, where n is the number of key columns for the entity.

The position of each bit in the array corresponds to the position of each key column in the key column collection, arranged as follows:

  • The most significant bit of the first byte corresponds to the first key column in the collection. The next most significant bit corresponds to the next key column in the collection. This pattern continues for each byte in the sequence.

  • Any padding is placed in the least significant bits of the last byte.

The following tables demonstrate this order.

Byte 0

0

1

2

3

4

5

6

7 (MSB)

Key 7

Key 6

Key 5

Key 4

Key 3

Key 2

Key 1

Key 0

Byte 1

8 (LSB)

9

10

11

12

13

14

15

Padding

Key 11

Key 10

Key 9

Key 8

keyValues (variable): An array of KeyValue structures that specifies the values of the key columns. If IncludeNullValues is set to 0, the number of values in this array MUST equal the total number of key columns. If IncludeNullValues is set to 1, the number of values in this array MUST equal the number of 0 values in the nullValueBits bit array, excluding any padding.