Chapter 7 The CFITSIO Iterator Function
The fits_iterate_data function in CFITSIO provides a unique method of
executing an arbitrary user-supplied `work' function that operates on
rows of data in FITS tables or on pixels in FITS images. Rather than
explicitly reading and writing the FITS images or columns of data, one
instead calls the CFITSIO iterator routine, passing to it the name of
the user's work function that is to be executed along with a list of
all the table columns or image arrays that are to be passed to the work
function. The CFITSIO iterator function then does all the work of
allocating memory for the arrays, reading the input data from the FITS
file, passing them to the work function, and then writing any output
data back to the FITS file after the work function exits. Because
it is often more efficient to process only a subset of the total table
rows at one time, the iterator function can determine the optimum
amount of data to pass in each iteration and repeatly call the work
function until the entire table been processed.
For many applications this single CFITSIO iterator function can
effectively replace all the other CFITSIO routines for reading or
writing data in FITS images or tables. Using the iterator has several
important advantages over the traditional method of reading and writing
FITS data files:
-
It cleanly separates the data I/O from the routine that operates on
the data. This leads to a more modular and `object oriented'
programming style.
- It simplifies the application program by eliminating the need to allocate
memory for the data arrays and eliminates most of the calls to the CFITSIO
routines that explicitly read and write the data.
- It ensures that the data are processed as efficiently as possible.
This is especially important when processing tabular data since
the iterator function will calculate the most efficient number
of rows in the table to be passed at one time to the user's work
function on each iteration.
- Makes it possible for larger projects to develop a library of work
functions that all have a uniform calling sequence and are all
independent of the details of the FITS file format.
There are basically 2 steps in using the CFITSIO iterator function.
The first step is to design the work function itself which must have a
prescribed set of input parameters. One of these parameters is a
structure containing pointers to the arrays of data; the work function
can perform any desired operations on these arrays and does not need to
worry about how the input data were read from the file or how the
output data get written back to the file.
The second step is to design the driver routine that opens all the
necessary FITS files and initializes the input parameters to the
iterator function. The driver program calls the CFITSIO iterator
function which then reads the data and passes it to the user's work
function.
Further details on using the iterator function can be found in the
companion CFITSIO User's Guide, and in the iter_a.f, iter_b.f and
iter_c.f example programs.