HDU-Level Operations  

When a FITS file is first opened or created, the internal buffers in FITSIO automatically point to the first HDU in the file. The following routines may be used to move to another HDU in the file. Note that the HDU numbering convention used in FITSIO denotes the primary array as the first HDU, the first extension in a FITS file is the second HDU, and so on.

1

Move to a specified (absolute) HDU in the FITS file (nhdu = 1 for the FITS primary array)

        FTMAHD(unit,nhdu, > hdutype,status)

2

Move to a new (existing) HDU forward or backwards relative to the CHDU

        FTMRHD(unit,nmove, > hdutype,status)

3

Get the number of the current HDU in the FITS file (primary array = 1)

        FTGHDN(unit, > nhdu)

4

Create (append) a new empty HDU following the last extension that has been previously accessed by the program. This will overwrite any extensions in an existing FITS file if the program has not already moved to that (or a later) extension using the FTMAHD or FTMRHD routines. For example, if an existing FITS file contains a primary array and 5 extensions and a program (1) opens the FITS file, (2) moves to extension 4, (3) moves back to the primary array, and (4) then calls FTCRHD, then the new extension will be written following the 4th extension, overwriting the existing 5th extension.

        FTCRHD(unit, > status)

5

Insert a new IMAGE extension immediately following the CHDU. Any following extensions will be shifted down to make room for the new extension. If there are no other following extensions then the new image extension will simply be appended to the end of the file. The new extension will become the CHDU.

        FTIIMG(unit,bitpix,naxis,naxes, > status)

6

Insert a new ASCII TABLE extension immediately following the CHDU. Any following extensions will be shifted down to make room for the new extension. If there are no other following extensions then the new table extension will simply be appended to the end of the file. The new extension will become the CHDU.

        FTITAB(unit,rowlen,nrows,tfields,ttype,tbcol,tform,tunit,extname, >
               status)

7

Insert a new binary table extension immediately following the CHDU. Any following extensions will be shifted down to make room for the new extension. If there are no other following extensions then the new bintable extension will simply be appended to the end of the file. The new extension will become the CHDU.

        FTIBIN(unit,nrows,tfields,ttype,tform,tunit,extname,varidat > status)

8

Resize an image by modifing the size, dimensions, and/or datatype of the current primary array or image extension. If the new image, as specified by the input arguments, is larger than the current existing image in the FITS file then zero fill data will be inserted at the end of the current image and any following extensions will be moved further back in the file. Similarly, if the new image is smaller than the current image then any following extensions will be shifted up towards the beginning of the FITS file and the image data will be truncated to the new size. This routine rewrites the BITPIX, NAXIS, and NAXISn keywords with the appropriate values for new image.

        FTRSIM(unit,bitpix,naxis,naxes,status)

9

Delete the CHDU in the FITS file. Any following HDUs will be shifted forward in the file, to fill in the gap created by the deleted HDU. This routine will only delete extensions; the primary array (the first HDU in the file) cannot be deleted. Note that Fortran (unfortunately) does not have the facility to decrease the size of an existing file, therefore the physical size of the FITS file will not change and the end of the file will be padded out with zeros to fill in the space left after the CHDU is deleted. If there are more extensions in the file following the one that is deleted, then the the CHDU will be defined to point to the following extension. If there are no following extensions then the CHDU will be redefined to point to the previous extension (or the primary array if there was only one extension in the file). The output HDUTYPE parameter indicates the type of the new CHDU after the previous CHDU has been deleted.

        FTDHDU(unit, > hdutype,status)

10

Copy the entire CHDU from the FITS file associated with IUNIT to the CHDU of the FITS file associated with OUNIT. The output HDU must be empty and not already contain any keywords. Space will be reserved for MOREKEYS additional keywords in the output header if there is not already enough space.

        FTCOPY(iunit,ounit,morekeys, > status)

11

Copy just the data from the CHDU associated with IUNIT to the CHDU associated with OUNIT. This will overwrite any data previously in the OUNIT CHDU. This low level routine is used by FTCOPY, but it may also be useful in certain application programs which want to copy the data from one FITS file to another but also want to modify the header keywords in the process. all the required header keywords must be written to the OUNIT CHDU before calling this routine

        FTCPDT(iunit,ounit, > status)