6.2 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

Move to the (first) HDU which has the specified extension type and EXTNAME (or HDUNAME) and EXTVER keyword values. The hdutype parameter may have a value of IMAGE_HDU (0), ASCII_TBL (1), BINARY_TBL (2), or ANY_HDU (-1) where ANY_HDU means that only the extname and extver values will be used to locate the correct extension. If the input value of extver is 0 then the EXTVER keyword is ignored and the first HDU with a matching EXTNAME (or HDUNAME) keyword will be found. If no matching HDU is found in the file then the current HDU will remain unchanged and a status = BAD_HDU_NUM (301) will be returned.

        FTMNHD(unit, hdutype, extname, extver, > status)

4

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

        FTGHDN(unit, > nhdu)

5

Return the type of the current HDU in the FITS file. The possible values for hdutype are IMAGE_HDU (0), ASCII_TBL (1), or BINARY_TBL (2).

        FTGHDT(unit, > hdutype, status)

6

Return the total number of HDUs in the FITS file. The CHDU remains unchanged.

        FTTHDU(unit, > hdunum, status)

7

Create (append) a new empty HDU at the end of the FITS file. This new HDU becomes the Current HDU, but it is completely empty and contains no header keywords or data. It is recommended that FTIIMG, FTITAB or FTIBIN be used instead of this routine.

        FTCRHD(unit, > status)

8

Create a primary array (if none already exists), or insert a new IMAGE extension immediately following the CHDU, or insert a new Primary Array at the beginning of the file. Any following extensions in the file will be shifted down to make room for the new extension. If the CHDU is the last HDU in the file then the new image extension will simply be appended to the end of the file. One can force a new primary array to be inserted at the beginning of the FITS file by setting status = -9 prior to calling the routine. In this case the existing primary array will be converted to an IMAGE extension. The new extension (or primary array) will become the CHDU. The FTIIMGLL routine is identical to the FTIIMG routine except that the 4th parameter (the length of each axis) is an array of 64-bit integers rather than an array of 32-bit integers.

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

9

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. The FTITABLL routine is identical to the FTITAB routine except that the 2nd and 3rd parameters (that give the size of the table) are 64-bit integers rather than 32-bit integers.

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

10

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. The FTIBINLL routine is identical to the FTIBIN routine except that the 2nd parameter (that gives the length of the table) is a 64-bit integer rather than a 32-bit integer.

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

11

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. The FTRSIMLL routine is identical to the FTRSIM routine except that the 4th parameter (the length of each axis) is an array of 64-bit integers rather than an array of 32-bit integers.

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

12

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. In the case of deleting the primary array (the first HDU in the file) then the current primary array will be replace by a null primary array containing the minimum set of required keywords and no data. If there are more extensions in the file following the one that is deleted, then the the CHDU will be redefined to point to the following extension. If there are no following extensions then the CHDU will be redefined to point to the previous HDU. The output HDUTYPE parameter indicates the type of the new CHDU after the previous CHDU has been deleted.

        FTDHDU(unit, > hdutype,status)

13

Copy all or part of the input FITS file and append it to the end of the output FITS file. If 'previous' (an integer parameter) is not equal to 0, then any HDUs preceding the current HDU in the input file will be copied to the output file. Similarly, 'current' and 'following' determine whether the current HDU, and/or any following HDUs in the input file will be copied to the output file. If all 3 parameters are not equal to zero, then the entire input file will be copied. On return, the current HDU in the input file will be unchanged, and the last copied HDU will be the current HDU in the output file.

        FTCPFL(iunit, ounit, previous, current, following, > status)

14

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)

15

Copy the header (and not the data) from the CHDU associated with inunit to the CHDU associated with outunit. If the current output HDU is not completely empty, then the CHDU will be closed and a new HDU will be appended to the output file. This routine will automatically transform the necessary keywords when copying a primary array to and image extension, or an image extension to a primary array. An empty output data unit will be created (all values = 0).

        FTCPHD(inunit, outunit, > status)

16

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)