next up previous contents Back To Software Index
Next: Celestial Coordinate System Up: FITS ASCII and Previous: Write Column Data

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. An additional feature of these routines is that if the user sets 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.

1
Get elements from an ASCII or binary table column (in the CDU). The `datatype' parameter specifies the datatype of the parameters pointed to by the `nulval' and `array' pointers; it 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. Undefined array elements will be returned with a value = *nullval, (note that this parameter gives the address of the null value, not the null value itself) unless nulval = 0 or *nulval = 0, in which case no checks for undefined pixels will be performed.

  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)

2
Get 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. (Note: the ffgcl routine simple gets an array of logical data values without any checks for undefined values; use the ffgcfl routine to check for undefined logical elements).

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

  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_[byt, sht, usht, lng, ulng, int, flt, dbl, cmp, dblcmp] /
      ffgcv[b,i,ui,j,uj,k,e,d,c,m]
      (fitsfile *fptr, int colnum, long firstrow, long firstelem,
       long nelements, DTYPE nulval, > DTYPE *array, int *anynul,
       int *status)

3
Get 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 / ffgcfl
      (fitsfile *fptr, int colnum, long firstrow, long firstelem,
       long nelements, > char *array, char *nularray, int *anynul,
       int *status)

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

4
Get 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 fpixels(naxis+1) and lpixels(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, lng, ulng, int, flt, dbl] /
      ffgsv[b,i,ui,j,uj,k,e,d]
      (fitsfile *fptr, int colnum, int naxis, long *naxes, long *fpixels,
       long *lpixels, long *inc, DTYPE nulval, > DTYPE *array, int *anynul,
       int *status)

5
Get 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 fpixels(naxis+1) and lpixels(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, lng, ulng, int, flt, dbl] /
      ffgsf[b,i,ui,j,uj,k,e,d]
      (fitsfile *fptr, int colnum, int naxis, long *naxes,
       long *fpixels, long *lpixels, long *inc, > DTYPE *array,
       char *nularray, int *anynul, int *status)

6
Get 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.

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

7
Get 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.

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



next up previous contents Back To Software Index
Next: Celestial Coordinate System Up: FITS ASCII and Previous: Write Column Data