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 calling routine. ASCII and binary tables support the following datatype values: TSTRING, TBYTE, TSHORT, TUSHORT, TINT, TUINT, TLONG, TLONGLONG, TULONG, TFLOAT, or TDOUBLE. Binary tables also support TLOGICAL (internally mapped to the `char' datatype), TCOMPLEX, and TDBLCOMPLEX.

Note that within the context of these routines, the TSTRING datatype corresponds to a C 'char**' datatype, 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*' datatype, 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.

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 'felem' 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 felem 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 datatype 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 second routine must not be used to write to variable length array columns. The third routine simply writes undefined pixel values to the column.      

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

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

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

2

Read elements from an ASCII or binary table column. The datatype parameter specifies the datatype of the `nulval' and `array' pointers; 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.

Any column, regardless of it's intrinsic datatype, 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 datatype 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.    

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

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