Previous: Creating a new FITS file
Up: Usage Guidelines and Suggestions
Next: Optimizing Code for Maximum I/O Processing Speed
Previous Page: Creating a new FITS file
Next Page: Optimizing Code for Maximum I/O Processing Speed

Advanced Usage

The FITSIO subroutines allow a great deal of flexibility in accessing FITS files; only some of the possibilities are briefly mentioned here. First, it is not necessary to read or write the information in the FITS file in the same order in which it is stored. One of the primary advantages of using the FITSIO interface is that it treats the FITS file as an 'object' and allows users to access various pieces of information in the file without regard to the internal FITS structure. One may, for example, read some data from one extension, then move back to read or write some other keywords from the primary header.

It is also not required to know the total size of a FITS data array or table before beginning to writing the data to the FITS file; one just has to write dummy values into the appropriate NAXISn keywords and then go back and modify the values later (with FTMKYJ) to match the actual size of the data array after it has been completely written. One must then also use the FTRDEF subroutine to reset the internal FITSIO parameters which define the actually size of the data unit. The following sequence of subroutine calls illustrates in more detail how to do this:

1

Write any required header keywords. Use any convenient dummy value for the keywords which define the size of the data, since these will be modified later with the correct values.

2

Write any additional desired optional keywords.

3

If desired, call FTHDEF to reserve space for any more keywords to be added at a later time. This is not required, but it is more efficient to reserve the space when the file is created rather than having to insert new empty blocks into the the header later on.

4

Define the structure of the FITS data with FTPDEF, FTBDEF, or FTADEF, whichever is appropriate. When writing a FITS image in which the final size of the highest dimension is unknown, then the corresponding value of the NAXES parameter must be initially set to a value larger than the expected final size of the image. If this is not done, then FITSIO will return an error status value = 308 when trying to write beyond the declared size of the image. Note that the total size (in bytes) of the data must not exceed the range of an Integer*4 variable, which is approximately 2 GBytes. When initializing a FITS table with an unknown number of rows, this initial size restriction does not apply and the NROWS parameter may be set = 0 or to any other arbitrary positive value.

5

Write the data, taking care to keep track of how much is actually written.

6

After the data have been written and the total size of the data is known, go back and modify the value of the required NAXISn keywords to reflect their true value.

7

Finally, call the FTRDEF subroutine to recalculate the new size of the extension, based on the modified NAXISn keywords. This is required so that FITSIO can calculate where the next extension in the FITS file should start.