9.6.1 General Column Routines

1

Get information about an existing ASCII or binary table column. A null pointer may be given for any of the output parameters that are not needed. DATATYPE is a character string which returns the data type of the column as defined by the TFORMn keyword (e.g., 'I', 'J','E', 'D', etc.). In the case of an ASCII character column, typecode will have a value of the form 'An' where 'n' is an integer expressing the width of the field in characters. For example, if TFORM = '160A8' then ffgbcl will return typechar='A8' and repeat=20. All the returned parameters are scalar quantities.

  int fits_get_acolparms / ffgacl
    (fitsfile *fptr, int colnum, > char *ttype, long *tbcol,
     char *tunit, char *tform, double *scale, double *zero,
     char *nulstr, char *tdisp, int *status)

  int fits_get_bcolparms / ffgbcl
      (fitsfile *fptr, int colnum, > char *ttype, char *tunit,
       char *typechar, long *repeat, double *scale, double *zero,
       long *nulval, char *tdisp, int  *status)

  int fits_get_bcolparmsll / ffgbclll
      (fitsfile *fptr, int colnum, > char *ttype, char *tunit,
       char *typechar, LONGLONG *repeat, double *scale, double *zero,
       LONGLONG *nulval, char *tdisp, int  *status)

2

Return optimal number of rows to read or write at one time for maximum I/O efficiency. Refer to the “Optimizing Code” section in Chapter 5 for more discussion on how to use this routine.

  int fits_get_rowsize / ffgrsz
      (fitsfile *fptr, long *nrows, *status)

3

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) but before any data is written to the table.

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

4

Test the contents of the binary table variable array heap, returning the size of the heap, the number of unused bytes that are not currently pointed to by any of the descriptors, and the number of bytes which are pointed to by multiple descriptors. It also returns valid = FALSE if any of the descriptors point to invalid addresses out of range of the heap.

  int fits_test_heap / fftheap
      (fitsfile *fptr, > LONGLONG *heapsize, LONGLONG *unused, LONGLONG *overlap,
       int *validheap, int *status)

5

Re-pack the vectors in the binary table variable array heap to recover any unused space. Normally, when a vector in a variable length array column is rewritten the previously written array remains in the heap as wasted unused space. This routine will repack the arrays that are still in use, thus eliminating any bytes in the heap that are no longer in use. Note that if several vectors point to the same bytes in the heap, then this routine will make duplicate copies of the bytes for each vector, which will actually expand the size of the heap.

  int fits_compress_heap / ffcmph
      (fitsfile *fptr, > int *status)