FITSIO Home
Next: Define or Redefine the
Up: Advanced Interface Subroutines
Previous: FITS File Open and
  Contents
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, ASCII_TBL, BINARY_TBL, or ANY_HDU 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 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)
- 8
- 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)
- 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.
FTITAB(unit,rowlen,nrows,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.
FTIBIN(unit,nrows,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.
FTRSIM(unit,bitpix,naxis,naxes,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' is
true (not 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
true, then the entire input file will be copied. On return, the current
HDU in the input file will be unchanged, and the last HDU will be the
current HDU in the output file.
int fits_copy_file / ffcpfl
(fitsfile *infptr, fitsfile *outfptr, int previous, int current,
int following, > int *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)
FITSIO Home
Next: Define or Redefine the
Up: Advanced Interface Subroutines
Previous: FITS File Open and
  Contents