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.
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)
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.dwhere 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)