9.6.3 Write Column Data Routines

This subsection describes specialized routines for writing data to FITS tables. Please see section 9.6.4 (“Read Column Data Routines”) for more information about how values are stored in C.

1

Write elements into an ASCII or binary table column (in the CDU). The data type of the array is implied by the suffix of the routine name.

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

  int fits_write_col_[log,byt,sht,usht,int,uint,lng,ulng,lnglng,ulnglng,flt,dbl,cmp,dblcmp] /
      ffpcl[l,b,i,ui,k,uk,j,uj,jj,ujj,e,d,c,m]
      (fitsfile *fptr, int colnum, LONGLONG firstrow,
           LONGLONG firstelem, LONGLONG 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.

  int fits_write_colnull_[log, byt, sht, usht, int, uint, lng, ulng, lnglng, ulnglng, flt, dbl] /
      ffpcn[l,b,i,ui,k,uk,j,uj,jj,ujj,e,d]
      (fitsfile *fptr, int colnum, LONGLONG firstrow, LONGLONG firstelem,
       LONGLONG nelements, DTYPE *array, DTYPE nulval, > int *status)

3

Write string elements into a binary table column (in the CDU) substituting the FITS null value for any elements that are equal to the nulstr string.

  int fits_write_colnull_str / ffpcns
      (fitsfile *fptr, int colnum, LONGLONG firstrow, LONGLONG firstelem,
       LONGLONG nelements, char **array, char *nulstr, > int *status)

4

Write bit values into a binary byte ('B') or bit ('X') table column (in the CDU). Larray is an array of characters corresponding to the sequence of bits to be written. If an element of larray is true (not equal to zero) then the corresponding bit in the FITS table is set to 1, otherwise the bit is set to 0. The 'X' column in a FITS table is always padded out to a multiple of 8 bits where the bit array starts with the most significant bit of the byte and works down towards the 1's bit. For example, a '4X' array, with the first bit = 1 and the remaining 3 bits = 0 is equivalent to the 8-bit unsigned byte decimal value of 128 ('1000 0000B'). 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 and should all be set = 0. It should also be noted that it is more efficient to write 'X' columns an entire byte at a time, instead of bit by bit. Any of the CFITSIO routines that write to columns (e.g. fits_write_col_byt) may be used for this purpose. These routines will interpret 'X' columns as though they were 'B' columns (e.g., '1X' through '8X' is equivalent to '1B', and '9X' through '16X' is equivalent to '2B').

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

5

Write 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, LONGLONG rownum, LONGLONG repeat,
         LONGLONG offset, > int *status)