7.3. BINARY TABLE EXTENSION

69

indicates that field 8 of the table is a variable-length array of type byte, with a maximum

stored array length not to exceed 1800 array elements (bytes in this case).

The data for the variable-length arrays in a table are not stored in the main data

table; they are stored in a supplemental data area, the heap, following the main data

table. What is stored in the main data table field is an array descriptor. This consists

of two 32-bit signed integer values in the case of `P' array descriptors, or two 64-bit

signed integer values in the case of `Q' array descriptors: the number of elements (array

length) of the stored array, followed by the zero-indexed byte offset of the first element

of the array, measured from the start of the heap area. The meaning of a negative

value for either of these integers is not defined by this standard. Storage for the array

is contiguous. The array descriptor for field N as it would appear embedded in a table

row is illustrated symbolically below:

. . . [field N ­1] [(nelem,offset)] [field N +1] . . .

If the stored array length is zero there is no array data, and the offset value is

undefined (it should be set to zero). The storage referenced by an array descriptor must

lie entirely within the heap area; negative offsets are not permitted.

A binary table containing variable-length arrays consists of three principal segments,

as follows:

[table header] [main data table] (optional gap) [heap area]

The table header consists of one or more 2880-byte header blocks with the last block

indicated by the keyword END somewhere in the block. The main data table begins with

the first data block following the last header block and is NAXIS1 × NAXIS2 bytes in

length. The zero indexed byte offset to the start of the heap, measured from the start of

the main data table, may be given by the THEAP keyword in the header. If this keyword

is missing then the heap begins with the byte immediately following main data table

(i.e., the default value of THEAP is NAXIS1 × NAXIS2). This default value is the minimum

allowed value for the THEAP keyword, because any smaller value would imply that the

heap and the main data table overlap. If the THEAP keyword has a value larger than

this default value, then there is a gap between the end of the main data table and the

start of the heap. The total length in bytes of the supplemental data area following the

main data table (gap plus heap) is given by the PCOUNT keyword in the table header.

For example, suppose a table contains 5 rows which are each 168 bytes long, with

a heap area 3000 bytes long, beginning at an offset of 2880, thereby aligning the main

data table and heap areas on data block boundaries (this alignment is not necessarily

recommended but is useful for this example). The data portion of the table consists of

3 2880-byte data blocks: the first block contains the 840 bytes from the 5 rows of the

main data table followed by 2040 fill bytes; the heap completely fills the second block;

the third block contains the remaining 120 bytes of the heap followed by 2760 fill bytes.

FITS Standard