Chapter 9 Advanced Interface Subroutines
This chapter defines all the available subroutines in the FITSIO user
interface. For completeness, the basic subroutines described in the
previous chapter are also repeated here. A right arrow symbol is used
here to separate the input parameters from the output parameters in the
definition of each subroutine. This symbol is not actually part of the
calling sequence. An alphabetical list and definition of all the
parameters is given at the end of this section.
9.1 FITS File Open and Close Subroutines:
-
1
- Open an existing FITS file with readonly or readwrite access. FTDOPN
also moves to the first HDU containing significant data, if no specific
HDU is specified as part of the filename. FTTOPN and FTIOPN are similar
except that they will move to the first table HDU or image HDU, respectively,
if a HDU name or number is not specified as part of the filename.
FTOPEN(unit,filename,rwmode, > blocksize,status)
FTDOPN(unit,filename,rwmode, > status)
FTTOPN(unit,filename,rwmode, > status)
FTIOPN(unit,filename,rwmode, > status)
-
2
- Open an existing FITS file with readonly or readwrite access
and move to a following extension, if one was specified as
part of the filename. (e.g., 'filename.fits+2' or
'filename.fits[2]' will move to the 3rd HDU in the file).
Note that this routine differs from FTOPEN in that it does not
have the redundant blocksize argument.
FTNOPN(unit,filename,rwmode, > status)
-
3
- Reopen a FITS file that was previously opened with
FTOPEN, FTNOPN, or FTINIT. The newunit number
may then be treated as a separate file, and one may
simultaneously read or write to 2 (or more) different extensions in
the same file. The FTOPEN and FTNOPN routines (above) automatically
detects cases where a previously opened file is being opened again,
and then internally call FTREOPEN, so programs should rarely
need to explicitly call this routine.
FTREOPEN(unit, > newunit, status)
-
4
- Open and initialize a new empty FITS file
FTINIT(unit,filename,blocksize, > status)
-
5
- Create a new FITS file, using a template file to define its
initial size and structure. The template may be another FITS HDU
or an ASCII template file.y array (i.e.,t key_no = 1; if key_no = 0 then this subroutine
simple moves the internal pointer to the beginning of the header
so that subsequent keyword operations will start at the top of
the header; it also returns a blank card value in this case.
FTGREC(unit,key_no, > card,status)
-
4
- Get a keyword value (with the appropriate datatype) and comment from
the CHU
FTGKY[EDJLS](unit,keyword, > keyval,comment,status)
-
5
- Delete an existing keyword record.
FTDKEY(unit,keyword, > status)
8.4 Data I/O Routines
The following routines read or write data values in the current HDU of
the FITS file. Automatic datatype conversion
will be attempted for numerical datatypes if the specified datatype is
different from the actual datatype of the FITS array or table column.
-
1
- Write elements into the primary data array or image extension.
FTPPR[BIJED](unit,group,fpixel,nelements,values, > status)
-
2
- Read elements from the primary data array or image extension.
Undefined array elements will be
returned with a value = nullval, unless nullval = 0 in which case no
checks for undefined pixels will be performed. The anyf parameter is
set to true (= .true.) if any of the returned
elements were undefined.
FTGPV[BIJED](unit,group,fpixel,nelements,nullval, > values,anyf,status)
-
3
- Write elements into an ASCII or binary table column. The `felem'
parameter applies only to vector columns in binary tables and is
ignored when writing to ASCII tables.
FTPCL[SLBIJEDCM](unit,colnum,frow,felem,nelements,values, > status)
-
4
- Read elements from an ASCII or binary table column. Undefined
array elements will be returned with a value = nullval, unless nullval = 0
(or = ' ' for ftgcvs) in which case no checking for undefined values will
be performed. The ANYF parameter is set to true if any of the returned
elements are undefined.
Any column, regardless of it's intrinsic datatype, may be read as a
string. It should be noted however that reading a numeric column
as a string is 10 - 100 times slower than reading the same column
as a number due to the large overhead in constructing the formatted
strings. The display format of the returned strings will be
determined by the TDISPn keyword, if it exists, otherwise by the
datatype of the column. The length of the returned strings can be
determined with the ftgcdw routine. The following TDISPn display
formats are currently supported:
Iw.m Integer
Ow.m Octal integer
Zw.m Hexadecimal integer
Fw.d Fixed floating point
Ew.d Exponential floating point
Dw.d Exponential floating point
Gw.d General; uses Fw.d if significance not lost, else Ew.d
where w is the width in characters of the displayed values, m is the minimum
number of digits displayed, and d is the number of digits to the right of the
decimal. The .m field is optional.
FTGCV[SBIJEDCM](unit,colnum,frow,felem,nelements,nullval, >
values,anyf,status)
-
5
- Get the table column number and full name of the column whose name
matches the input template string. See the `Advanced Interface Routines'
chapter for a full description of this routine.
FTGCNN(unit,casesen,coltemplate, > colname,colnum,status)