5.7.4 Read and Write Column Data Routines

The following routines write or read data values in the current ASCII or binary table extension. If a write operation extends beyond the current size of the table, then the number of rows in the table will automatically be increased and the NAXIS2 keyword value will be updated. Attempts to read beyond the end of the table will result in an error.

Automatic data type conversion is performed for numerical data types (only) if the data type of the column (defined by the TFORMn keyword) differs from the data type of the array in the calling routine. ASCII and binary tables support the following data type values: TSTRING, TBYTE, TSBYTE, TSHORT, TUSHORT, TINT, TUINT, TLONG, TLONGLONG, TULONG, TULONGLONG, TFLOAT, or TDOUBLE. Binary tables also support TLOGICAL (internally mapped to the `char' data type), TCOMPLEX, and TDBLCOMPLEX.

Note that it is *not* necessary to insert rows in a table before writing data to those rows (indeed, it would be inefficient to do so). Instead, one may simply write data to any row of the table, whether that row of data already exists or not.

Individual bits in a binary table 'X' or 'B' column may be read/written to/from a *char array by specifying the TBIT datatype. The *char array will be interpreted as an array of logical TRUE (1) or FALSE (0) values that correspond to the value of each bit in the FITS 'X' or 'B' column. Alternatively, the values in a binary table 'X' column may be read/written 8 bits at a time to/from an array of 8-bit integers by specifying the TBYTE datatype.

Note that within the context of these routines, the TSTRING data type corresponds to a C 'char**' data type, i.e., a pointer to an array of pointers to an array of characters. This is different from the keyword reading and writing routines where TSTRING corresponds to a C 'char*' data type, i.e., a single pointer to an array of characters. When reading strings from a table, the char arrays obviously must have been allocated long enough to hold the whole FITS table string. See section 4.5 (“Dealing with Character Strings”) for more information.

For complex and double complex data types, nelements is the number of numerical pairs; the number of floats or doubles stored by array must be 2*nelements.

For the logical data (TLOGICAL), the C storage type is a char single-byte character. A FITS value of `T'rue reads as 1 and `F' reads as 0; other non-FITS characters are preserved untranslated.

Numerical data values are automatically scaled by the TSCALn and TZEROn keyword values (if they exist).

In the case of binary tables with vector elements, the firstelem parameter defines the starting element (beginning with 1, not 0) within the cell (a cell is defined as the intersection of a row and a column and may contain a single value or a vector of values). The firstelem parameter is ignored when dealing with ASCII tables. Similarly, in the case of binary tables the 'nelements' parameter specifies the total number of vector values to be read or written (continuing on subsequent rows if required) and not the number of table cells.

1

Write elements into an ASCII or binary table column.

The first routine simply writes the array of values to the FITS file (doing data type conversion if necessary) whereas the second routine will substitute the appropriate FITS null value for all elements which are equal to the input value of nulval (note that this parameter gives the address of nulval, not the null value itself). For integer columns the FITS null value is defined by the TNULLn keyword (an error is returned if the keyword doesn't exist). For floating point columns the special IEEE NaN (Not-a-Number) value will be written into the FITS file. If a null pointer is entered for nulval, then the null value is ignored and this routine behaves the same as the first routine. The third routine simply writes undefined pixel values to the column. The fourth routine fills every column in the table with null values, in the specified rows (ignoring any columns that do not have a defined null value).

The fits_write_cols() variant writes multiple columns in a single pass, which may be significantly faster for large data files. The “chunk” size is determined automatically based upon CFITSIO's buffer sizes. Only whole rows can be written, of any type except TBIT or TSTRING. For this variant, datatype, colnum, array and nulval are arrays of the equivalent single-column parameter (i.e. datatype[i] is the data type of column i).

  int fits_write_col / ffpcl
      (fitsfile *fptr, int datatype, int colnum, LONGLONG firstrow,
       LONGLONG firstelem, LONGLONG nelements, DTYPE *array, > int *status)

  int fits_write_colnull / ffpcn
      (fitsfile *fptr, int datatype, int colnum, LONGLONG firstrow,
      LONGLONG firstelem, LONGLONG nelements, DTYPE *array, DTYPE *nulval,
      > int *status)

   int fits_write_col_null / ffpclu
       (fitsfile *fptr, int colnum, LONGLONG firstrow, LONGLONG firstelem,
        LONGLONG nelements, > int *status)

   int fits_write_nullrows / ffprwu
       (fitsfile *fptr, LONGLONG firstrow, LONGLONG nelements, > int *status)

  int fits_write_cols / ffpcln
      (fitsfile *fptr, int ncols, int *datatype, int *colnum, LONGLONG firstrow, 
       LONGLONG nrows, DTYPE **array, DTYPE **nulval, int *status)

2

Read elements from an ASCII or binary table column. The data type parameter specifies the data type of the `nulval' and `array' pointers. The caller is required to allocate the storage of array before calling. Undefined array elements will be returned with a value = *nullval, (note that this parameter gives the address of the null value, not the null value itself) unless nulval = 0 or *nulval = 0, in which case no checking for undefined pixels will be performed. The second routine is similar except that any undefined pixels will have the corresponding nullarray element set equal to TRUE (= 1).

Reading data as TSTRING values is different than for other data types as described above.

Any column, regardless of it's intrinsic data type, may be read as a string. It should be noted however that reading a numeric column as a string is 10 - 100 times slower than reading the same column as a number due to the large overhead in constructing the formatted strings. The display format of the returned strings will be determined by the TDISPn keyword, if it exists, otherwise by the data type of the column. The length of the returned strings (not including the null terminating character) can be determined with the fits_get_col_display_width routine. The following TDISPn display formats are currently supported:

    Iw.m   Integer
    Ow.m   Octal integer
    Zw.m   Hexadecimal integer
    Fw.d   Fixed floating point
    Ew.d   Exponential floating point
    Dw.d   Exponential floating point
    Gw.d   General; uses Fw.d if significance not lost, else Ew.d

where w is the width in characters of the displayed values, m is the minimum number of digits displayed, and d is the number of digits to the right of the decimal. The .m field is optional.

The fits_read_cols() variant read multiple columns in a single pass, which may be significantly faster for large data files. The “chunk” size is determined automatically based upon CFITSIO's buffer sizes. Only whole rows can be read, of any type except TBIT or TSTRING. For this variant, datatype, colnum, array and nulval are arrays of the equivalent single-column parameter (i.e. datatype[i] is the data type of column i).

  int fits_read_col / ffgcv
      (fitsfile *fptr, int datatype, int colnum, LONGLONG firstrow, LONGLONG firstelem,
       LONGLONG nelements, DTYPE *nulval, DTYPE *array, int *anynul, int *status)

  int fits_read_colnull / ffgcf
      (fitsfile *fptr, int datatype, int colnum, LONGLONG firstrow, LONGLONG firstelem,
      LONGLONG nelements, DTYPE *array, char *nullarray, int *anynul, int *status)

  int fits_read_cols / ffgcvn
      (fitsfile *fptr, int ncols, int *datatype, int *colnum, LONGLONG firstrow, 
       LONGLONG nrows, DTYPE **nulval, DTYPE **array, int **anynul, int *status)