next up previous contents Back To Software Index
Next: Read Column Data Up: FITS ASCII and Previous: Insert or Delete

Write Column Data Routines

The following routines put or get data values in the current ASCII or Binary table extension. Automatic data type conversion is performed for numerical data types (B,I,J,E,D) if the data type of the column (defined by the TFORM keyword) differs from the data type of the calling routine. The data values are also scaled by the TSCALn and TZEROn header values as they are being written to or read from the FITS array. The fftscl routine MUST be used to define the scaling parameters when writing data to the table or to override the default scaling values given in the header when reading from the table.

In the case of binary tables with vector elements, the 'felem' parameter defines the starting pixel within the element vector. This parameter is ignored with ASCII tables. Similarly, in the case of binary tables the 'nelements' parameter specifies the total number of vector values read or written (continuing on subsequent rows if required) and not the number of table elements.

1
Put elements into an ASCII or binary table column (in the CDU). The `datatype' parameter specifies the datatype of the `array' of values and can have one of the following symbolic constant values: TSTRING, TBYTE, TSHORT, TUSHORT, TINT, TLONG, TULONG, TFLOAT, or TDOUBLE. Binary tables also support the following additional datatypes: TLOGICAL, TCOMPLEX, and TDBLCOMPLEX.

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

2
Put elements into an ASCII or binary table column (in the CDU). The datatype of the array is implied by the suffix of the routine name.

  int fits_write_col_str / ffpcls
      (fitsfile *fptr, int colnum, long firstrow, long firstelem,
       long nelements, char **array, > int *status)

  int fits_write_col_[log, byt, sht, usht, lng, ulng, int, flt, dbl, cmp, dblcmp] /
      ffpcl[l,b,i,ui,j,uj,k,e,d,c,m]
      (fitsfile *fptr, int colnum, long firstrow,
           long firstelem, long nelements, DTYPE *array, > int *status)

3
Put elements into an ASCII or binary table column (in the CDU) substituting the appropriate FITS null value for any elements that are equal to NULLVAL. This family of routines must NOT be used to write to variable length array columns. For ASCII TABLE extensions, the null value defined by the previous call to ffsnul will be substituted; For integer FITS columns, in a binary table the null value defined by the previous call to fftnul will be substituted; For floating point FITS columns a special IEEE NaN (Not-a-Number) value will be substituted.

  int fits_write_colnul_[byt, sht, usht, lng, ulng, int, flt, dbl] /
      ffpcn[b,i,ui,j,uj,k,e,d]
      (fitsfile *fptr, int colnum, long firstrow, long firstelem,
       long nelements, DTYPE *array, DTYPE nulval, > int *status)

4
Put bit values into a binary byte ('B') or bit ('X') table column (in the CDU). Larray is an array of logical values corresponding to the sequence of bits to be written. If larray is true then the corresponding bit is set to 1, otherwise the bit is set to 0. Note that in the case of 'X' columns, CFITSIO can write to all 8 bits of each byte whether they are formally valid or not. Thus if the column is defined as '4X', and one calls ffpclx with firstbit=1 and nbits=8, then all 8 bits will be written into the first byte (as opposed to writing the first 4 bits into the first row and then the next 4 bits into the next row), even though the last 4 bits of each byte are formally not defined.

  int fits_write_col_bit / ffpclx
      (fitsfile *fptr, int colnum, long firstrow, long firstbit,
       long nbits, char *larray, > int *status)

5
Set table elements in a column as undefined

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

6
Put the descriptor for a variable length column in a binary table. This routine can be used in conjunction with FFGDES to enable 2 or more arrays to point to the same storage location to save storage space if the arrays are identical.

    int fits_write_descript / ffpdes
        (fitsfile *fptr, int colnum, long rownum, long repeat,
         long offset, > int *status)

7
Define the zero indexed byte offset of the 'heap' measured from the start of the binary table data. By default the heap is assumed to start immediately following the regular table data, i.e., at location NAXIS1 x NAXIS2. This routine is only relevant for binary tables which contain variable length array columns (with TFORMn = 'Pt'). This routine also automatically writes the value of theap to a keyword in the extension header. This routine must be called after the required keywords have been written (with ffphbn) and after the table structure has been defined (with ffbdef) but before any data is written to the table.

  int fits_write_theap / ffpthp
      (fitsfile *fptr, long theap, > int *status)



next up previous contents Back To Software Index
Next: Read Column Data Up: FITS ASCII and Previous: Insert or Delete