6.2 The Iterator Driver Function

The iterator driver function must open the necessary FITS files and position them to the correct HDU. It must also initialize the following parameters in the iteratorCol structure (defined above) for each column or image before calling the CFITSIO iterator function. Several `constructor' routines are provided in CFITSIO for this purpose.

• *fptr - The fitsfile pointer to the table or image.
• colnum - the number of the column in the table. This value is ignored in the case of images. If colnum equals 0, then the column name will be used to identify the column to be passed to the work function.

• colname - the name (TTYPEn keyword) of the column. This is only required if colnum = 0 and is ignored for images.
• datatype - The desired data type of the array to be passed to the work function. For numerical data the data type does not need to be the same as the actual data type in the FITS file, in which case CFITSIO will do the conversion. Allowed values are: TSTRING, TLOGICAL, TBYTE, TSBYTE, TSHORT, TUSHORT, TINT, TLONG, TULONG, TFLOAT, TDOUBLE. If the input value of data type equals 0, then the existing data type of the column or image will be used without any conversion.

• iotype - defines whether the data array is to be input to the work function (i.e, read from the FITS file), or output from the work function (i.e., written to the FITS file) or both. Allowed values are InputCol, OutputCol, or InputOutputCol. Variable-length array columns are supported as InputCol or InputOutputCol types, but may not be used for an OutputCol type.

After the driver routine has initialized all these parameters, it can then call the CFITSIO iterator function:

  int fits_iterate_data(int narrays, iteratorCol *data, long offset,
      long nPerLoop, int (*workFn)( ), void *userPointer, int *status);

• narrays - the number of columns or images that are to be passed to the work function.

• *data - pointer to array of structures containing information about each column or image.

• offset - if positive, this number of rows at the beginning of the table (or pixels in the image) will be skipped and will not be passed to the work function.

• nPerLoop - specifies the number of table rows (or number of image pixels) that are to be passed to the work function on each iteration. If nPerLoop = 0 then CFITSIO will calculate the optimum number for greatest efficiency. If nPerLoop is negative, then all the rows or pixels will be passed at one time, and the work function will only be called once. If any variable length arrays are being processed, then the nPerLoop value is ignored, and the iterator will always process one row of the table at a time.

• *workFn - the name (actually the address) of the work function that is to be called by fits_iterate_data.

• *userPointer - this is a user supplied pointer that can be used to pass ancillary information from the driver routine to the work function. It may point to a single number, an array, or to a structure containing an arbitrary set of parameters.

• *status - The CFITSIO error status. Should = 0 on input; a non-zero output value indicates an error.

When fits_iterate_data is called it first allocates memory to hold all the requested columns of data or image pixel arrays. It then reads the input data from the FITS tables or images into the arrays then passes the structure with pointers to these data arrays to the work function. After the work function returns, the iterator function writes any output columns of data or images back to the FITS files. It then repeats this process for any remaining sets of rows or image pixels until it has processed the entire table or image or until the work function returns a non-zero status value. The iterator then frees the memory that it initially allocated and returns control to the driver routine that called it.