NAME

ftcmpheap - compress the heap in variable-length columns of a FITS table extension.

USAGE

ftcmpheap infile[ext]

DESCRIPTION

This simple program functions as a wrapper to the CFITSIO library routine fits_compress_heap(), which re-packs vectors in a binary table variable array heap to recover any unused space.

From the CFITSIO manual:

All the data in a variable length field is written into an area called the heap which follows the main fixed-length FITS binary table. The size of the heap, in bytes, is specified by the PCOUNT keyword in the FITS header. When creating a new binary table, the initial value of PCOUNT should usually be set to zero. CFITSIO will recompute the size of the heap as the data is written and will automatically update the PCOUNT keyword value when the table is closed. When writing variable length data to a table, CFITSIO will automatically extend the size of the heap area if necessary, so that any following HDUs do not get overwritten.
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 [fits_compress_heap] 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.
ftcmpheap may be useful after performing operations on variable-length columns in a FITS binary table. For example, the ftcopy task could be used to delete variable-length columns from a table, but currently this leaves the PCOUNT keyword and file size unchanged (leading to warnings from e.g. ftverify). Running ftcmpheap on the affected extension frees up the unused space and fixes the PCOUNT keyword.

PARAMETERS

infile [filename]
Input file name and optional extension name or number, e.g. 'table.fits[3]', 'table.fits[events]', or 'table.fits+3'. Note that if the extension name or number is omitted, the first table HDU in the file will be used.

(chatter = 1) [integer, 0 - 5]
Controls the amount of informative text written to standard output. Setting chatter = 5 will produce detailed diagnostic output, otherwise this task does not normally write any output.

EXAMPLES

Note that when commands are issued on the Unix command line, strings containing special characters such as '[' or ']' must be enclosed in single or double quotes.

1. Compress the heap in the third extension (named "EVENTS") of a FITS binary table: 

      ftcmpheap table.fits+3
or 
      ftcmpheap 'table.fits[3]'
or 
      ftcmpheap 'table.fits[EVENTS]'
or, if there is only one table HDU in the file: 

      ftcmpheap table.fits

LAST MODIFIED

February 2021