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 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.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. 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 ANYF parameter is set to true if any of the returned elements are undefined.  

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

  int fits_read_col_[log,byt,sht,usht,int,uint,lng,ulng, lnglng, flt, dbl, cmp, dblcmp] /
      ffgcv[l,b,i,ui,k,uk,j,uj,jj,e,d,c,m]
      (fitsfile *fptr, int colnum, long firstrow, long firstelem,
       long 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 nularray 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, long firstrow, long firstelem,
       long nelements, > char **array, char *nularray, int *anynul,
       int *status)

  int fits_read_colnull_[log,byt,sht,usht,int,uint,lng,ulng,lnglng,flt,dbl,cmp,dblcmp] /
      ffgcf[l,b,i,ui,k,uk,j,uj,jj,e,d,c,m]
      (fitsfile *fptr, int colnum, long firstrow,
       long firstelem, long nelements, > DTYPE *array,
       char *nularray, 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, flt, dbl] /
      ffgsv[b,i,ui,k,uk,j,uj,jj,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 'nularray' 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, flt, dbl] /
      ffgsf[b,i,ui,k,uk,j,uj,jj,e,d]
      (fitsfile *fptr, int colnum, int naxis, long *naxes,
       long *fpixel, long *lpixel, long *inc, > DTYPE *array,
       char *nularray, 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. 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, long firstrow, long firstbit,
       long 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, long firstrow, long, 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 routine returns a single descriptor whereas the second routine returns the descriptors for a range of rows in the table.  

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

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