Previous: Error Status Values
Up: Basic FITSIO Conventions
Previous Page: Error Status Values
Next Page: Usage Guidelines and Suggestions

Variable-Length Array Facility in Binary Tables

The FITSIO package supports reading and writing data to variable length fields of a binary table which have TFORM = 'rPt' where r is an optional repeat count and t is the datatype code (e.g., L, X, I, E, etc.). The same subroutines which read and write data in an ordinary fixed length binary table extension (FTPCLx, FTGCVx, FTGCFx) are also used for variable length fields, however, the subroutine parameters take on a slightly different interpretation.

When writing to a variable length field, the entire array of values for a given row of the table must be written with a single call to FTPCLx. The total length of the array is calculated from (NELEM+FELEM-1). One cannot append more elements to an existing field at a later time because any attempt to append more elements will simply overwrite all the data which was previously written. Note also that the new data will be written to a new area of the 'heap' and the heap space used by the previous write cannot be reclaimed. For this reason it is advised that each row of a variable length field only be written once. An exception to this general rule occurs when setting elements of an array as undefined. One must first write a dummy value into the array with FTPCLx, and then call FTPCLU to flag the desired elements as undefined. The rows of a table may be written in any order. It is also possible to start writing the table without knowing the final total size of the heap (as specified by the PCOUNT header keyword). One can simple use a dummy value for PCOUNT initially, and then update the value after the table has been completely written (it is also necessary to update the total length of the data area with the FTDDEF subroutine). Note, however, it is not possible to increase the total number of rows in the table over what was initially declared in the FTBDEF subroutine because the heap starts immediately after the last row, unless one has used the FTPTHP subroutine to leave a gap between the end of the fixed length table and the heap (see below).

When reading from a variable length array field one can only read as many elements as exist in that row of the table; reading does not automatically continue with the next row of the table as occurs when reading an ordinary fixed length table field. Attempts to read more than this will return an error. One can determine the length of each row of the field with the FTGDES subroutine.

When reading or writing to an ASCII character field (e.g., TFORM = 'PA') only a single character string is read or written. The number of characters in the string is specified with the NELEM parameter (the FELEM parameter is ignored).

The FTPDES subroutine is useful in situations where multiple rows of a variable length column have the identical array of values. One can simply write the array once for the first row, and then use FTPDES to write the same descriptor values into the other rows; all the rows will then point to the same storage location thus saving disk space.

By default the heap starts immediately following the end of the fixed length table, (i.e., at byte location = NAXIS1 x NAXIS2). If desired, the starting location of the heap can be changed by using the FTPTHP subroutine. FTPTHP must be called after the table structure is defined (with FTBDEF) and after the required header keywords have been written, but before any data are written to the table. This subroutine also automatically writes the THEAP keyword to the binary table extension header.