70

SECTION 7. STANDARD EXTENSIONS

PCOUNT gives the total number of bytes from the end of the main data table to the end of

the heap and in this example has a value of 2040 + 2880 + 120 = 5040. This is expressed

in the table header as:

NAXIS1

=

168 / Width of table row in bytes

NAXIS2

=

5 / Number of rows in table

PCOUNT

=

5040 / Random parameter count

...

THEAP

=

2880 / Byte offset of heap area

The values of TSCALn and TZEROn for variable-length array column entries are to be

applied to the values in the data array in the heap area, not the values of the array

descriptor. These keywords can be used to scale data values in either static or variable-

length arrays.

7.3.6

Variable-Length Array Guidelines

While the above description is sufficient to define the required features of the variable-

length array implementation, some hints regarding usage of the variable-length array

facility might also be useful.

Programs that read binary tables should take care to not assume more about the

physical layout of the table than is required by the specification. For example, there are

no requirements on the alignment of data within the heap. If efficient runtime access

is a concern one might want to design the table so that data arrays are aligned to the

size of an array element. In another case one might want to minimize storage and forgo

any efforts at alignment (by careful design it is often possible to achieve both goals).

Variable-length array data may be stored in the heap in any order, i.e., the data for row

N +1 are not necessarily stored at a larger offset than that for row N . There may be

gaps in the heap where no data are stored. Pointer aliasing is permitted, i.e., the array

descriptors for two or more arrays may point to the same storage location (this could

be used to save storage if two or more arrays are identical).

Byte arrays are a special case because they can be used to store a `typeless' data

sequence. Since FITS is a machine-independent storage format, some form of machine-

specific data conversion (byte swapping, floating-point format conversion) is implied

when accessing stored data with types such as integer and floating, but byte arrays are

copied to and from external storage without any form of conversion.

An important feature of variable-length arrays is that it is possible that the stored

array length may be zero. This makes it possible to have a column of the table for

which, typically, no data are present in each stored row. When data are present the

stored array can be as large as necessary. This can be useful when storing complex

objects as rows in a table.

FITS Standard