9.6.4 Read Column Data Routines

Two types of routines are provided to get the column data which differ in the way undefined pixels are handled. The first set of routines (ffgcv) simply return an array of data elements in which undefined pixels are set equal to a value specified by the user in the 'nullval' parameter. If nullval = 0, then no checks for undefined pixels will be performed, thus increasing the speed of the program. The second set of routines (ffgcf) returns the data element array and in addition a logical array of flags which defines whether the corresponding data pixel is undefined. See Appendix B for the definition of the parameters used in these routines.

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

1

Read elements from an ASCII or binary table column (in the CDU). These routines return the values of the table column array elements. The caller is required to allocate the storage array before calling. Undefined array elements will be returned with a value = nulval, unless nulval = 0 (or = ' ' for ffgcvs) in which case no checking for undefined values will be performed. The anynul parameter is set to true if any of the returned elements are undefined.

For the _log (logical) variant, the C storage type is a char single-byte character. A FITS value of `T'rue reads as 1 and `F' reads as 0; other non-FITS characters are preserved untranslated.

For the _str (string) variant the number of elements is the number of strings, and the caller must allocate storage for both the array of pointers array and the character array data itself (use fits_get_col_display_width or fits_get_coltype to determine the number of characters). See section 4.5 (“Dealing with Character Strings”) for more information. Also, when the _byt variant is used to read a column stored in the file as string data (TFORMn = 'nA'), the subroutine will read the character bytes (instead of attempting to perform a numerical conversion as other integer variants would do), with no attempt at null termination.

For the _cmp and _dblcmp (complex and double complex) variants, nelements is the number of numerical pairs; the number of floats or doubles that must be pre-allocated is 2*nelements.

  int fits_read_col_str / ffgcvs
      (fitsfile *fptr, int colnum, LONGLONG firstrow, LONGLONG firstelem,
       LONGLONG nelements, char *nulstr, > char **array, int *anynul,
       int *status)

  int fits_read_col_[log,byt,sht,usht,int,uint,lng,ulng, lnglng, ulnglng, flt, dbl, cmp, dblcmp] /
      ffgcv[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 nulval, > DTYPE *array, int *anynul,
       int *status)

2

Read elements and null flags from an ASCII or binary table column (in the CHDU). These routines return the values of the table column array elements. Any undefined array elements will have the corresponding nullarray element set equal to TRUE. The anynul parameter is set to true if any of the returned elements are undefined.

  int fits_read_colnull_str / ffgcfs
      (fitsfile *fptr, int colnum, LONGLONG firstrow, LONGLONG firstelem,
       LONGLONG nelements, > char **array, char *nullarray, int *anynul,
       int *status)

  int fits_read_colnull_[log,byt,sht,usht,int,uint,lng,ulng,lnglng,ulnglng,flt,dbl,cmp,dblcmp] /
      ffgcf[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,
       char *nullarray, int *anynul, int *status)

3

Read an arbitrary data subsection from an N-dimensional array in a binary table vector column. Undefined pixels in the array will be set equal to the value of 'nulval', unless nulval=0 in which case no testing for undefined pixels will be performed. The first and last rows in the table to be read are specified by fpixel(naxis+1) and lpixel(naxis+1), and hence are treated as the next higher dimension of the FITS N-dimensional array. The INC parameter specifies the sampling interval in each dimension between the data elements that will be returned.

  int fits_read_subset_[byt, sht, usht, int, uint, lng, ulng, lnglng, ulnglng, flt, dbl] /
      ffgsv[b,i,ui,k,uk,j,uj,jj,ull,e,d]
      (fitsfile *fptr, int colnum, int naxis, long *naxes, long *fpixel,
       long *lpixel, long *inc, DTYPE nulval, > DTYPE *array, int *anynul,
       int *status)

4

Read an arbitrary data subsection from an N-dimensional array in a binary table vector column. Any Undefined pixels in the array will have the corresponding 'nullarray' element set equal to TRUE. The first and last rows in the table to be read are specified by fpixel(naxis+1) and lpixel(naxis+1), and hence are treated as the next higher dimension of the FITS N-dimensional array. The INC parameter specifies the sampling interval in each dimension between the data elements that will be returned.

  int fits_read_subsetnull_[byt, sht, usht, int, uint, lng, ulng, lnglng, ulnglng, flt, dbl] /
      ffgsf[b,i,ui,k,uk,j,uj,jj,ujj,e,d]
      (fitsfile *fptr, int colnum, int naxis, long *naxes,
       long *fpixel, long *lpixel, long *inc, > DTYPE *array,
       char *nullarray, int *anynul, int *status)

5

Read bit values from a 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 read. If larray is true then the corresponding bit was set to 1, otherwise the bit was 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 value of 128. Note that in the case of 'X' columns, CFITSIO can read all 8 bits of each byte whether they are formally valid or not. Thus if the column is defined as '4X', and one calls ffgcx with firstbit=1 and nbits=8, then all 8 bits will be read from the first byte (as opposed to reading the first 4 bits from the first row and then the first 4 bits from the next row), even though the last 4 bits of each byte are formally not defined. It should also be noted that it is more efficient to read 'X' columns an entire byte at a time, instead of bit by bit. Any of the CFITSIO routines that read columns (e.g. fits_read_col_byt) may be used for this purpose. These routines will interpret 'X' columns as though they were 'B' columns (e.g., '8X' is equivalent to '1B', and '16X' is equivalent to '2B').

  int fits_read_col_bit / ffgcx
      (fitsfile *fptr, int colnum, LONGLONG firstrow, LONGLONG firstbit,
       LONGLONG nbits, > char *larray, int *status)

6

Read any consecutive set of bits from an 'X' or 'B' column and interpret them as an unsigned n-bit integer. nbits must be less than 16 or 32 in ffgcxui and ffgcxuk, respectively. If nrows is greater than 1, then the same set of bits will be read from each row, starting with firstrow. The bits are numbered with 1 = the most significant bit of the first element of the column.

  int fits_read_col_bit_[usht, uint] / ffgcx[ui,uk]
      (fitsfile *fptr, int colnum, LONGLONG firstrow, LONGLONG, nrows,
       long firstbit, long nbits, > DTYPE *array, int *status)

7

Return the descriptor for a variable length column in a binary table. The descriptor consists of 2 integer parameters: the number of elements in the array and the starting offset relative to the start of the heap. The first pair of routine returns a single descriptor whereas the second pair of routine returns the descriptors for a range of rows in the table. The only difference between the 2 routines in each pair is that one returns the parameters as 'long' integers, whereas the other returns the values as 64-bit 'LONGLONG' integers.

  int fits_read_descript / ffgdes
      (fitsfile *fptr, int colnum, LONGLONG rownum, > long *repeat,
           long *offset, int *status)

  int fits_read_descriptll / ffgdesll
      (fitsfile *fptr, int colnum, LONGLONG rownum, > LONGLONG *repeat,
           LONGLONG *offset, int *status)

  int fits_read_descripts / ffgdess
      (fitsfile *fptr, int colnum, LONGLONG firstrow, LONGLONG nrows
       > long *repeat, long *offset, int *status)

  int fits_read_descriptsll / ffgdessll
      (fitsfile *fptr, int colnum, LONGLONG firstrow, LONGLONG nrows
       > LONGLONG *repeat, LONGLONG *offset, int *status)