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

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 pixel 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.  

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

2

Write elements into an ASCII or binary table column, substituting the appropriate FITS null value for any elements that are equal to the nulval parameter (note that this parameter gives the address of the null value, not the null value itself). For all ASCII table columns and for integer columns in binary tables, the null value to be used in the FITS file is defined by the TNULLn keyword and an error is returned if the TNULLn keyword doesn't exist. For floating point columns in binary tables the special IEEE NaN (Not-a-Number) value will be written into the FITS column. If a null pointer is entered for nulval, then the null value is ignored and this routine behaves the same as fits_write_col. This routine must not be used to write to variable length array columns.  

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

3

Set elements in a table column as undefined. For all ASCII table columns and for integer columns in binary tables, the null value to be used in the FITS file is defined by the TNULLn keyword and an error is returned if the TNULLn keyword doesn't exist. For floating point columns in binary tables the special IEEE NaN (Not-a-Number) value will be written into the FITS column.  

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

4

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.  

  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)