Chapter 6 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.
6.1 FITS File Open and Close Subroutines:
- 1
- Open an existing FITS file with readonly or readwrite access. The
FTDKOPN routine simply opens the specified file without trying to
interpret the filename using the extended filename syntax. FTDOPN opens
the file and
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)
FTDKOPN(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.
The FTDKINIT routine simply creates the specified
file without trying to interpret the filename using the extended
filename syntax.
FTINIT(unit,filename,blocksize, > status)
FTDKINIT(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. If the input template file name
is blank, then this routine behaves the same as FTINIT.
The currently supported format of the ASCII template file is described
under the fits_parse_template routine (in the general Utilities
section), but this may change slightly later releases of
CFITSIO.
FTTPLT(unit, filename, tplfilename, > status)
- 6
- Flush internal buffers of data to the output FITS file
previously opened with ftopen or ftinit. The routine usually
never needs to be called, but doing so will ensure that
if the program subsequently aborts, then the FITS file will
have at least been closed properly.
FTFLUS(unit, > status)
- 7
- Close a FITS file previously opened with ftopen or ftinit
FTCLOS(unit, > status)
- 8
- Close and DELETE a FITS file previously opened with ftopen or ftinit.
This routine may be useful in cases where a FITS file is created, but
an error occurs which prevents the complete file from being written.
FTDELT(unit, > status)
- 9
- Get the value of an unused I/O unit number which may then be used
as input to FTOPEN or FTINIT. This routine searches for the first
unused unit number in the range from with 99 down to 50. This
routine just keeps an internal list of the allocated unit numbers
and does not physically check that the Fortran unit is available (to be
compatible with the SPP version of FITSIO). Thus users must not
independently allocate any unit numbers in the range 50 - 99
if this routine is also to be used in the same program. This
routine is provided for convenience only, and it is not required
that the unit numbers used by FITSIO be allocated by this routine.
FTGIOU( > iounit, status)
- 10
- Free (deallocate) an I/O unit number which was previously allocated
with FTGIOU. All previously allocated unit numbers may be
deallocated at once by calling FTFIOU with iounit = -1.
FTFIOU(iounit, > status)
- 11
- Return the Fortran unit number that corresponds to the C fitsfile
pointer value, or vice versa. These 2 C routines may be useful in
mixed language programs where both C and Fortran subroutines need
to access the same file. For example, if a FITS file is opened
with unit 12 by a Fortran subroutine, then a C routine within the
same program could get the fitfile pointer value to access the same file
by calling ’fptr = CUnit2FITS(12)’. These routines return a value
of zero if an error occurs.
int CFITS2Unit(fitsfile *ptr);
fitsfile* CUnit2FITS(int unit);
- 11
- Parse the input filename and return the HDU number that would be
moved to if the file were opened with FTNOPN. The returned HDU
number begins with 1 for the primary array, so for example, if the
input filename = ‘myfile.fits[2]’ then hdunum = 3 will be returned.
FITSIO does not open the file to check if the extension actually exists
if an extension number is specified. If an extension *name* is included
in the file name specification (e.g. ‘myfile.fits[EVENTS]’ then this
routine will have to open the FITS file and look for the position of
the named extension, then close file again. This is not possible if
the file is being read from the stdin stream, and an error will be
returned in this case. If the filename does not specify an explicit
extension (e.g. ’myfile.fits’) then hdunum = -99 will be returned,
which is functionally equivalent to hdunum = 1. This routine is mainly
used for backward compatibility in the ftools software package and is
not recommended for general use. It is generally better and more
efficient to first open the FITS file with FTNOPN, then use FTGHDN to
determine which HDU in the file has been opened, rather than calling
FTEXTN followed by a call to FTNOPN.
FTEXTN(filename, > nhdu, status)
- 12
- Return the name of the opened FITS file.
FTFLNM(unit, > filename, status)
- 13
- Return the I/O mode of the open FITS file (READONLY = 0, READWRITE = 1).
FTFLMD(unit, > iomode, status)
- 14
- Return the file type of the opened FITS file (e.g. ’file://’, ’ftp://’,
etc.).
FTURLT(unit, > urltype, status)
- 15
- Parse the input filename or URL into its component parts: the file
type (file://, ftp://, http://, etc), the base input file name, the
name of the output file that the input file is to be copied to prior
to opening, the HDU or extension specification, the filtering
specifier, the binning specifier, and the column specifier. Blank
strings will be returned for any components that are not present
in the input file name.
FTIURL(filename, > filetype, infile, outfile, extspec, filter,
binspec, colspec, status)
- 16
- Parse the input file name and return the root file name. The root
name includes the file type if specified, (e.g. ’ftp://’ or ’http://’)
and the full path name, to the extent that it is specified in the input
filename. It does not include the HDU name or number, or any filtering
specifications.
FTRTNM(filename, > rootname, status)
- 16
- Test if the input file or a compressed version of the file (with
a .gz, .Z, .z, or .zip extension) exists on disk. The returned value of
the ’exists’ parameter will have 1 of the 4 following values:
2: the file does not exist, but a compressed version does exist
1: the disk file does exist
0: neither the file nor a compressed version of the file exist
-1: the input file name is not a disk file (could be a ftp, http,
smem, or mem file, or a file piped in on the STDIN stream)
FTEXIST(filename, > exists, status);
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)
6.3 Define or Redefine the structure of the CHDU
It should rarely be necessary to call the subroutines in this section.
FITSIO internally calls these routines whenever necessary, so any calls
to these routines by application programs will likely be redundant.
- 1
- This routine forces FITSIO to scan the current header keywords that
define the structure of the HDU (such as the NAXISn, PCOUNT and GCOUNT
keywords) so that it can initialize the internal buffers that describe
the HDU structure. This routine may be used instead of the more
complicated calls to ftpdef, ftadef or ftbdef. This routine is
also very useful for reinitializing the structure of an HDU,
if the number of rows in a table, as specified by the NAXIS2 keyword,
has been modified from its initial value.
FTRDEF(unit, > status) (DEPRECATED)
- 2
- Define the structure of the primary array or IMAGE extension. When
writing GROUPed FITS files that by convention set the NAXIS1 keyword
equal to 0, ftpdef must be called with naxes(1) = 1, NOT 0, otherwise
FITSIO will report an error status=308 when trying to write data
to a group. Note: it is usually simpler to call FTRDEF rather
than this routine.
FTPDEF(unit,bitpix,naxis,naxes,pcount,gcount, > status) (DEPRECATED)
- 3
- Define the structure of an ASCII table (TABLE) extension. Note: it
is usually simpler to call FTRDEF rather than this routine.
FTADEF(unit,rowlen,tfields,tbcol,tform,nrows > status) (DEPRECATED)
- 4
- Define the structure of a binary table (BINTABLE) extension. Note: it
is usually simpler to call FTRDEF rather than this routine.
FTBDEF(unit,tfields,tform,varidat,nrows > status) (DEPRECATED)
- 5
- Define the size of the Current Data Unit, overriding the length
of the data unit as previously defined by ftpdef, ftadef, or ftbdef.
This is useful if one does not know the total size of the data unit until
after the data have been written. The size (in bytes) of an ASCII or
Binary table is given by NAXIS1 * NAXIS2. (Note that to determine the
value of NAXIS1 it is often more convenient to read the value of the
NAXIS1 keyword from the output file, rather than computing the row
length directly from all the TFORM keyword values). Note: it
is usually simpler to call FTRDEF rather than this routine.
FTDDEF(unit,bytlen, > status) (DEPRECATED)
- 6
- Define the zero indexed byte offset of the ’heap’ measured from
the start of the binary table data. By default the heap is assumed
to start immediately following the regular table data, i.e., at
location NAXIS1 x NAXIS2. This routine is only relevant for
binary tables which contain variable length array columns (with
TFORMn = ’Pt’). This subroutine also automatically writes
the value of theap to a keyword in the extension header. This
subroutine must be called after the required keywords have been
written (with ftphbn) and after the table structure has been defined
(with ftbdef) but before any data is written to the table.
FTPTHP(unit,theap, > status)
6.4 FITS Header I/O Subroutines
6.4.1 Header Space and Position Routines
- 1
- Reserve space in the CHU for MOREKEYS more header keywords.
This subroutine may be called to reserve space for keywords which are
to be written at a later time, after the data unit or subsequent
extensions have been written to the FITS file. If this subroutine is
not explicitly called, then the initial size of the FITS header will be
limited to the space available at the time that the first data is written
to the associated data unit. FITSIO has the ability to dynamically
add more space to the header if needed, however it is more efficient
to preallocate the required space if the size is known in advance.
FTHDEF(unit,morekeys, > status)
- 2
- Return the number of existing keywords in the CHU (NOT including the
END keyword which is not considered a real keyword) and the remaining
space available to write additional keywords in the CHU. (returns
KEYSADD = -1 if the header has not yet been closed).
Note that FITSIO will attempt to dynamically add space for more
keywords if required when appending new keywords to a header.
FTGHSP(iunit, > keysexist,keysadd,status)
- 3
- Return the number of keywords in the header and the current position
in the header. This returns the number of the keyword record that
will be read next (or one greater than the position of the last keyword
that was read or written). A value of 1 is returned if the pointer is
positioned at the beginning of the header.
FTGHPS(iunit, > keysexist,key_no,status)
6.4.2 Read or Write Standard Header Routines
These subroutines provide a simple method of reading or writing most of
the keyword values that are normally required in a FITS files. These
subroutines are provided for convenience only and are not required to
be used. If preferred, users may call the lower-level subroutines
described in the previous section to individually read or write the
required keywords. Note that in most cases, the required keywords such
as NAXIS, TFIELD, TTYPEn, etc, which define the structure of the HDU
must be written to the header before any data can be written to the
image or table.
- 1
- Put the primary header or IMAGE extension keywords into the CHU.
There are 2 available routines: The simpler FTPHPS routine is
equivalent to calling ftphpr with the default values of SIMPLE = true,
pcount = 0, gcount = 1, and EXTEND = true. PCOUNT, GCOUNT and EXTEND
keywords are not required in the primary header and are only written if
pcount is not equal to zero, gcount is not equal to zero or one, and if
extend is TRUE, respectively. When writing to an IMAGE extension, the
SIMPLE and EXTEND parameters are ignored.
FTPHPS(unit,bitpix,naxis,naxes, > status)
FTPHPR(unit,simple,bitpix,naxis,naxes,pcount,gcount,extend, > status)
- 2
- Get primary header or IMAGE extension keywords from the CHU. When
reading from an IMAGE extension the SIMPLE and EXTEND parameters are
ignored.
FTGHPR(unit,maxdim, > simple,bitpix,naxis,naxes,pcount,gcount,extend,
status)
- 3
- Put the ASCII table header keywords into the CHU. The optional
TUNITn and EXTNAME keywords are written only if the input string
values are not blank.
FTPHTB(unit,rowlen,nrows,tfields,ttype,tbcol,tform,tunit,extname, >
status)
- 4
- Get the ASCII table header keywords from the CHU
FTGHTB(unit,maxdim, > rowlen,nrows,tfields,ttype,tbcol,tform,tunit,
extname,status)
- 5
- Put the binary table header keywords into the CHU. The optional
TUNITn and EXTNAME keywords are written only if the input string
values are not blank. The pcount parameter, which specifies the
size of the variable length array heap, should initially = 0;
FITSIO will automatically update the PCOUNT keyword value if any
variable length array data is written to the heap. The TFORM keyword
value for variable length vector columns should have the form ’Pt(len)’
or ’1Pt(len)’ where ‘t’ is the data type code letter (A,I,J,E,D, etc.)
and ‘len’ is an integer specifying the maximum length of the vectors
in that column (len must be greater than or equal to the longest
vector in the column). If ‘len’ is not specified when the table is
created (e.g., the input TFORMn value is just ’1Pt’) then FITSIO will
scan the column when the table is first closed and will append the
maximum length to the TFORM keyword value. Note that if the table
is subsequently modified to increase the maximum length of the vectors
then the modifying program is responsible for also updating the TFORM
keyword value.
FTPHBN(unit,nrows,tfields,ttype,tform,tunit,extname,varidat, > status)
- 6
- Get the binary table header keywords from the CHU
FTGHBN(unit,maxdim, > nrows,tfields,ttype,tform,tunit,extname,varidat,
status)
6.4.3 Write Keyword Subroutines
- 1
- Put (append) an 80-character record into the CHU.
FTPREC(unit,card, > status)
- 2
- Put (append) a COMMENT keyword into the CHU. Multiple COMMENT keywords
will be written if the input comment string is longer than 72 characters.
FTPCOM(unit,comment, > status)
- 3
- Put (append) a HISTORY keyword into the CHU. Multiple HISTORY keywords
will be written if the input history string is longer than 72 characters.
FTPHIS(unit,history, > status)
- 4
- Put (append) the DATE keyword into the CHU. The keyword value will contain
the current system date as a character string in ’dd/mm/yy’ format. If
a DATE keyword already exists in the header, then this subroutine will
simply update the keyword value in-place with the current date.
FTPDAT(unit, > status)
- 5
- Put (append) a new keyword of the appropriate datatype into the CHU.
Note that FTPKYS will only write string values up to 68 characters in
length; longer strings will be truncated. The FTPKLS routine can be
used to write longer strings, using a non-standard FITS convention.
The E and D versions of this routine have the added feature that
if the ’decimals’ parameter is negative, then the ’G’ display
format rather then the ’E’ format will be used when constructing
the keyword value, taking the absolute value of ’decimals’ for the
precision. This will suppress trailing zeros, and will use a
fixed format rather than an exponential format,
depending on the magnitude of the value.
FTPKY[JKLS](unit,keyword,keyval,comment, > status)
FTPKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
- 6
- Put (append) a string valued keyword into the CHU which may be longer
than 68 characters in length. This uses the Long String Keyword
convention that is described in the "Usage Guidelines and Suggestions"
section of this document. Since this uses a non-standard FITS
convention to encode the long keyword string, programs which use
this routine should also call the FTPLSW routine to add some COMMENT
keywords to warn users of the FITS file that this convention is
being used. FTPLSW also writes a keyword called LONGSTRN to record
the version of the longstring convention that has been used, in case
a new convention is adopted at some point in the future. If the
LONGSTRN keyword is already present in the header, then FTPLSW will
simply return and will not write duplicate keywords.
FTPKLS(unit,keyword,keyval,comment, > status)
FTPLSW(unit, > status)
- 7
- Put (append) a new keyword with an undefined, or null, value into the CHU.
The value string of the keyword is left blank in this case.
FTPKYU(unit,keyword,comment, > status)
- 8
- Put (append) a numbered sequence of keywords into the CHU. One may
append the same comment to every keyword (and eliminate the need
to have an array of identical comment strings, one for each keyword) by
including the ampersand character as the last non-blank character in the
(first) COMMENTS string parameter. This same string
will then be used for the comment field in all the keywords. (Note
that the SPP version of these routines only supports a single comment
string).
FTPKN[JKLS](unit,keyroot,startno,no_keys,keyvals,comments, > status)
FTPKN[EDFG](unit,keyroot,startno,no_keys,keyvals,decimals,comments, >
status)
- 9
- Copy an indexed keyword from one HDU to another, modifying
the index number of the keyword name in the process. For example,
this routine could read the TLMIN3 keyword from the input HDU
(by giving keyroot = "TLMIN" and innum = 3) and write it to the
output HDU with the keyword name TLMIN4 (by setting outnum = 4).
If the input keyword does not exist, then this routine simply
returns without indicating an error.
FTCPKY(inunit, outunit, innum, outnum, keyroot, > status)
- 10
- Put (append) a ’triple precision’ keyword into the CHU in F28.16 format.
The floating point keyword value is constructed by concatenating the
input integer value with the input double precision fraction value
(which must have a value between 0.0 and 1.0). The FTGKYT routine should
be used to read this keyword value, because the other keyword reading
subroutines will not preserve the full precision of the value.
FTPKYT(unit,keyword,intval,dblval,comment, > status)
- 11
- Write keywords to the CHDU that are defined in an ASCII template file.
The format of the template file is described under the ftgthd
routine below.
FTPKTP(unit, filename, > status)
- 12
- Append the physical units string to an existing keyword. This
routine uses a local convention, shown in the following example,
in which the keyword units are enclosed in square brackets in the
beginning of the keyword comment field.
VELOCITY= 12.3 / [km/s] orbital speed
FTPUNT(unit,keyword,units, > status)
6.4.4 Insert Keyword Subroutines
- 1
- Insert a new keyword record into the CHU at the specified position
(i.e., immediately preceding the (keyno)th keyword in the header.)
This ’insert record’ subroutine is somewhat less efficient
then the ’append record’ subroutine (FTPREC) described above because
the remaining keywords in the header have to be shifted down one slot.
FTIREC(unit,key_no,card, > status)
- 2
- Insert a new keyword into the CHU. The new keyword is inserted
immediately following the last keyword that has been read from the header.
The FTIKLS subroutine works the same as the FTIKYS subroutine, except
it also supports long string values greater than 68 characters in length.
These ’insert keyword’ subroutines are somewhat less efficient then
the ’append keyword’ subroutines described above because the remaining
keywords in the header have to be shifted down one slot.
FTIKEY(unit, card, > status)
FTIKY[JKLS](unit,keyword,keyval,comment, > status)
FTIKLS(unit,keyword,keyval,comment, > status)
FTIKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
- 3
- Insert a new keyword with an undefined, or null, value into the CHU.
The value string of the keyword is left blank in this case.
FTIKYU(unit,keyword,comment, > status)
6.4.5 Read Keyword Subroutines
These routines return the value of the specified keyword(s). Wild card
characters (*, ?, or #) may be used when specifying the name of the keyword
to be read: a ’?’ will match any single character at that position in the
keyword name and a ’*’ will match any length (including zero) string of
characters. The ’#’ character will match any consecutive string of
decimal digits (0 - 9). Note that when a wild card is used in the input
keyword name, the routine will only search for a match from the current
header position to the end of the header. It will not resume the search
from the top of the header back to the original header position as is done
when no wildcards are included in the keyword name. If the desired
keyword string is 8-characters long (the maximum length of a keyword
name) then a ’*’ may be appended as the ninth character of the input
name to force the keyword search to stop at the end of the header
(e.g., ’COMMENT *’ will search for the next COMMENT keyword). The
ffgrec routine may be used to set the starting position when doing
wild card searches.
- 1
- Get the nth 80-character header record from the CHU. The first keyword
in the header is at 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)
- 2
- Get the name, value (as a string), and comment of the nth keyword in CHU.
This routine also checks that the returned keyword name (KEYWORD) contains
only legal ASCII characters. Call FTGREC and FTPSVC to bypass this error
check.
FTGKYN(unit,key_no, > keyword,value,comment,status)
- 3
- Get the 80-character header record for the named keyword
FTGCRD(unit,keyword, > card,status)
- 4
- Get the next keyword whose name matches one of the strings in
’inclist’ but does not match any of the strings in ’exclist’.
The strings in inclist and exclist may contain wild card characters
(*, ?, and #) as described at the beginning of this section.
This routine searches from the current header position to the
end of the header, only, and does not continue the search from
the top of the header back to the original position. The current
header position may be reset with the ftgrec routine. Note
that nexc may be set = 0 if there are no keywords to be excluded.
This routine returns status = 202 if a matching
keyword is not found.
FTGNXK(unit,inclist,ninc,exclist,nexc, > card,status)
- 5
- Get the literal keyword value as a character string. Regardless
of the datatype of the keyword, this routine simply returns the
string of characters in the value field of the keyword along with
the comment field.
FTGKEY(unit,keyword, > value,comment,status)
- 6
- Get a keyword value (with the appropriate datatype) and comment from
the CHU
FTGKY[EDJKLS](unit,keyword, > keyval,comment,status)
- 7
- Read a string-valued keyword and return the string length, the value string,
and/or the comment field. The first routine, FTGKSL, simply
returns the length of the character string value of the specified keyword.
The second routine, FTGSKY, also returns up to maxchar characters
of the keyword value string, starting with the firstchar character,
and the keyword comment string.
The length argument returns the total length of the keyword value string
regardless of how much of the string is actually returned (which
depends on the value of the firstchar and maxchar arguments). These
routines support string keywords that use the CONTINUE convention to
continue long string values over multiple FITS header records. Normally,
string-valued keywords have a maximum length of 68 characters, however,
CONTINUE’d string keywords may be arbitrarily long.
FTGKSL(unit,keyword, > length,status)
FTGSKY(unit,keyword,firstchar,maxchar,> keyval,length,comment,status)
- 8
- Get a sequence of numbered keyword values. These
routines do not support wild card characters in the root name.
FTGKN[EDJKLS](unit,keyroot,startno,max_keys, > keyvals,nfound,status)
- 9
- Get the value of a floating point keyword, returning the integer and
fractional parts of the value in separate subroutine arguments.
This subroutine may be used to read any keyword but is especially
useful for reading the ’triple precision’ keywords written by FTPKYT.
FTGKYT(unit,keyword, > intval,dblval,comment,status)
- 10
- Get the physical units string in an existing keyword. This
routine uses a local convention, shown in the following example,
in which the keyword units are
enclosed in square brackets in the beginning of the keyword comment
field. A blank string is returned if no units are defined
for the keyword.
VELOCITY= 12.3 / [km/s] orbital speed
FTGUNT(unit,keyword, > units,status)
6.4.6 Modify Keyword Subroutines
Wild card characters, as described in the Read Keyword section, above,
may be used when specifying the name of the keyword to be modified.
- 1
- Modify (overwrite) the nth 80-character header record in the CHU
FTMREC(unit,key_no,card, > status)
- 2
- Modify (overwrite) the 80-character header record for the named keyword
in the CHU. This can be used to overwrite the name of the keyword as
well as its value and comment fields.
FTMCRD(unit,keyword,card, > status)
- 3
- Modify (overwrite) the name of an existing keyword in the CHU
preserving the current value and comment fields.
FTMNAM(unit,oldkey,keyword, > status)
- 4
- Modify (overwrite) the comment field of an existing keyword in the CHU
FTMCOM(unit,keyword,comment, > status)
- 5
- Modify the value and comment fields of an existing keyword in the CHU.
The FTMKLS subroutine works the same as the FTMKYS subroutine, except
it also supports long string values greater than 68 characters in length.
Optionally, one may modify only the value field and leave the comment
field unchanged by setting the input COMMENT parameter equal to
the ampersand character (&).
The E and D versions of this routine have the added feature that
if the ’decimals’ parameter is negative, then the ’G’ display
format rather then the ’E’ format will be used when constructing
the keyword value, taking the absolute value of ’decimals’ for the
precision. This will suppress trailing zeros, and will use a
fixed format rather than an exponential format,
depending on the magnitude of the value.
FTMKY[JKLS](unit,keyword,keyval,comment, > status)
FTMKLS(unit,keyword,keyval,comment, > status)
FTMKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
- 6
- Modify the value of an existing keyword to be undefined, or null.
The value string of the keyword is set to blank.
Optionally, one may leave the comment field unchanged by setting the
input COMMENT parameter equal to the ampersand character (&).
FTMKYU(unit,keyword,comment, > status)
6.4.7 Update Keyword Subroutines
- 1
- Update an 80-character record in the CHU. If the specified keyword
already exists then that header record will be replaced with
the input CARD string. If it does not exist then the new record will
be added to the header.
The FTUKLS subroutine works the same as the FTUKYS subroutine, except
it also supports long string values greater than 68 characters in length.
FTUCRD(unit,keyword,card, > status)
- 2
- Update the value and comment fields of a keyword in the CHU.
The specified keyword is modified if it already exists (by calling
FTMKYx) otherwise a new keyword is created by calling FTPKYx.
The E and D versions of this routine have the added feature that
if the ’decimals’ parameter is negative, then the ’G’ display
format rather then the ’E’ format will be used when constructing
the keyword value, taking the absolute value of ’decimals’ for the
precision. This will suppress trailing zeros, and will use a
fixed format rather than an exponential format,
depending on the magnitude of the value.
FTUKY[JKLS](unit,keyword,keyval,comment, > status)
FTUKLS(unit,keyword,keyval,comment, > status)
FTUKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
- 3
- Update the value of an existing keyword to be undefined, or null,
or insert a new undefined-value keyword if it doesn’t already exist.
The value string of the keyword is left blank in this case.
FTUKYU(unit,keyword,comment, > status)
6.4.8 Delete Keyword Subroutines
- 1
- Delete an existing keyword record. The space previously occupied by
the keyword is reclaimed by moving all the following header records up
one row in the header. The first routine deletes a keyword at a
specified position in the header (the first keyword is at position 1),
whereas the second routine deletes a specifically named keyword.
Wild card characters, as described in the Read Keyword section, above,
may be used when specifying the name of the keyword to be deleted
(be careful!).
FTDREC(unit,key_no, > status)
FTDKEY(unit,keyword, > status)
6.5 Data Scaling and Undefined Pixel Parameters
These subroutines define or modify the internal parameters used by
FITSIO to either scale the data or to represent undefined pixels.
Generally FITSIO will scale the data according to the values of the BSCALE
and BZERO (or TSCALn and TZEROn) keywords, however these subroutines
may be used to override the keyword values. This may be useful when
one wants to read or write the raw unscaled values in the FITS file.
Similarly, FITSIO generally uses the value of the BLANK or TNULLn
keyword to signify an undefined pixel, but these routines may be used
to override this value. These subroutines do not create or modify the
corresponding header keyword values.
- 1
- Reset the scaling factors in the primary array or image extension; does
not change the BSCALE and BZERO keyword values and only affects the
automatic scaling performed when the data elements are written/read
to/from the FITS file. When reading from a FITS file the returned
data value = (the value given in the FITS array) * BSCALE + BZERO.
The inverse formula is used when writing data values to the FITS
file. (NOTE: BSCALE and BZERO must be declared as Double Precision
variables).
FTPSCL(unit,bscale,bzero, > status)
- 2
- Reset the scaling parameters for a table column; does not change
the TSCALn or TZEROn keyword values and only affects the automatic
scaling performed when the data elements are written/read to/from
the FITS file. When reading from a FITS file the returned data
value = (the value given in the FITS array) * TSCAL + TZERO. The
inverse formula is used when writing data values to the FITS file.
(NOTE: TSCAL and TZERO must be declared as Double Precision
variables).
FTTSCL(unit,colnum,tscal,tzero, > status)
- 3
- Define the integer value to be used to signify undefined pixels in the
primary array or image extension. This is only used if BITPIX = 8, 16,
32. or 64 This does not create or change the value of the BLANK keyword in
the header. FTPNULLL is identical to FTPNUL except that the blank
value is a 64-bit integer instead of a 32-bit integer.
FTPNUL(unit,blank, > status)
FTPNULLL(unit,blankll, > status)
- 4
- Define the string to be used to signify undefined pixels in
a column in an ASCII table. This does not create or change the value
of the TNULLn keyword.
FTSNUL(unit,colnum,snull > status)
- 5
- Define the value to be used to signify undefined pixels in
an integer column in a binary table (where TFORMn = ’B’, ’I’, ’J’, or ’K’).
This does not create or change the value of the TNULLn keyword.
FTTNULLL is identical to FTTNUL except that the tnull
value is a 64-bit integer instead of a 32-bit integer.
FTTNUL(unit,colnum,tnull > status)
FTTNULLL(unit,colnum,tnullll > status)
6.6 FITS Primary Array or IMAGE Extension I/O Subroutines
These subroutines put or get data values in the primary data array
(i.e., the first HDU in the FITS file) or an IMAGE extension. The
data array is represented as a single one-dimensional array of
pixels regardless of the actual dimensionality of the array, and the
FPIXEL parameter gives the position within this 1-D array of the first
pixel to read or write. Automatic data type conversion is performed
for numeric data (except for complex data types) if the data type of
the primary array (defined by the BITPIX keyword) differs from the data
type of the array in the calling subroutine. The data values are also
scaled by the BSCALE and BZERO header values as they are being written
or read from the FITS array. The ftpscl subroutine MUST be
called to define the scaling parameters when writing data to the FITS
array or to override the default scaling value given in the header when
reading the FITS array.
Two sets of subroutines are provided to read the data array which
differ in the way undefined pixels are handled. The first set of
routines (FTGPVx) simply return an array of data elements in which
undefined pixels are set equal to a value specified by the user in the
’nullval’ parameter. An additional feature of these subroutines is
that if the user sets nullval = 0, then no checks for undefined pixels
will be performed, thus increasing the speed of the program. The
second set of routines (FTGPFx) returns the data element array and, in
addition, a logical array which defines whether the corresponding data
pixel is undefined. The latter set of subroutines may be more
convenient to use in some circumstances, however, it requires an
additional array of logical values which can be unwieldy when working
with large data arrays. Also for programmer convenience, sets of
subroutines to directly read or write 2 and 3 dimensional arrays have
been provided, as well as a set of subroutines to read or write any
contiguous rectangular subset of pixels within the n-dimensional array.
- 1
- Get the data type of the image (= BITPIX value). Possible returned
values are: 8, 16, 32, 64, -32, or -64 corresponding to unsigned byte,
signed 2-byte integer, signed 4-byte integer, signed 8-byte integer,
real, and double.
The second subroutine is similar to FTGIDT, except that if the image
pixel values are scaled, with non-default values for the BZERO and
BSCALE keywords, then this routine will return the ’equivalent’
data type that is needed to store the scaled values. For example,
if BITPIX = 16 and BSCALE = 0.1 then the equivalent data type is
floating point, and -32 will be returned. There are 2 special cases:
if the image contains unsigned 2-byte integer values, with BITPIX =
16, BSCALE = 1, and BZERO = 32768, then this routine will return
a non-standard value of 20 for the bitpix value. Similarly if the
image contains unsigned 4-byte integers, then bitpix will
be returned with a value of 40.
FTGIDT(unit, > bitpix,status)
FTGIET(unit, > bitpix,status)
- 2
- Get the dimension (number of axes = NAXIS) of the image
FTGIDM(unit, > naxis,status)
- 3
- Get the size of all the dimensions of the image. The FTGISZLL
routine returns an array of 64-bit integers instead of 32-bit integers.
FTGISZ(unit, maxdim, > naxes,status)
FTGISZLL(unit, maxdim, > naxesll,status)
- 4
- Get the parameters that define the type and size of the image. This
routine simply combines calls to the above 3 routines. The FTGIPRLL
routine returns an array of 64-bit integers instead of 32-bit integers.
FTGIPR(unit, maxdim, > bitpix, naxis, naxes, int *status)
FTGIPRLL(unit, maxdim, > bitpix, naxis, naxesll, int *status)
- 5
- Put elements into the data array. The FTPPR[]LL routines
accept 64-bit integers for fpixel and nelements.
FTPPR[BIJKED](unit,group,fpixel,nelements,values, > status)
FTPPR[BIJKED]LL(unit,group,fpixelll,nelementsll,values, > status)
- 6
- Put elements into the data array, substituting the appropriate FITS null
value for all elements which are equal to the value of NULLVAL. For
integer FITS arrays, the null value defined by the previous call to FTPNUL
will be substituted; for floating point FITS arrays (BITPIX = -32
or -64) then the special IEEE NaN (Not-a-Number) value will be
substituted. The FTPPN[]LL routines accept 64-bit integers for
fpixel and nelements.
FTPPN[BIJKED](unit,group,fpixel,nelements,values,nullval > status)
FTPPN[BIJKED]LL(unit,group,fpixelll,nelementsll,values,nullval > status)
- 7
- Set data array elements as undefined. FTPPRULL accepts 64-bit integers
for fpixel and nelements.
FTPPRU(unit,group,fpixel,nelements, > status)
FTPPRULL(unit,group,fpixelll,nelementsll, > status)
- 8
- Get elements from the data array. Undefined array elements will be
returned with a value = nullval, unless nullval = 0 in which case no
checks for undefined pixels will be performed. FTGPV[]LL accepts
64-bit integers for fpixel and nelements.
FTGPV[BIJKED](unit,group,fpixel,nelements,nullval, > values,anyf,status)
FTGPV[BIJKED]LL(unit,group,fpixelll,nelementsll,nullval, > values,anyf,status)
- 9
- Get elements and nullflags from data array.
Any undefined array elements will have the corresponding flagvals element
set equal to .TRUE.
FTGPF[BIJKED](unit,group,fpixel,nelements, > values,flagvals,anyf,status)
- 10
- Put values into group parameters
FTPGP[BIJKED](unit,group,fparm,nparm,values, > status)
- 11
- Get values from group parameters
FTGGP[BIJKED](unit,group,fparm,nparm, > values,status)
The following 4 subroutines transfer FITS images with 2 or 3 dimensions
to or from a data array which has been declared in the calling program.
The dimensionality of the FITS image is passed by the naxis1, naxis2,
and naxis3 parameters and the declared dimensions of the program array
are passed in the dim1 and dim2 parameters. Note that the program array
does not have to have the same dimensions as the FITS array, but must
be at least as big. For example if a FITS image with NAXIS1 = NAXIS2 = 400
is read into a program array which is dimensioned as 512 x 512 pixels,
then the image will just fill the lower left corner of the array
with pixels in the range 1 - 400 in the X an Y directions. This has
the effect of taking a contiguous set of pixel value in the FITS array
and writing them to a non-contiguous array in program memory
(i.e., there are now some blank pixels around the edge of the image
in the program array).
- 11
- Put 2-D image into the data array
FTP2D[BIJKED](unit,group,dim1,naxis1,naxis2,image, > status)
- 12
- Put 3-D cube into the data array
FTP3D[BIJKED](unit,group,dim1,dim2,naxis1,naxis2,naxis3,cube, > status)
- 13
- Get 2-D image from the data array. Undefined
pixels in the array will be set equal to the value of ’nullval’,
unless nullval=0 in which case no testing for undefined pixels will
be performed.
FTG2D[BIJKED](unit,group,nullval,dim1,naxis1,naxis2, > image,anyf,status)
- 14
- Get 3-D cube from the data array. Undefined
pixels in the array will be set equal to the value of ’nullval’,
unless nullval=0 in which case no testing for undefined pixels will
be performed.
FTG3D[BIJKED](unit,group,nullval,dim1,dim2,naxis1,naxis2,naxis3, >
cube,anyf,status)
The following subroutines transfer a rectangular subset of the pixels
in a FITS N-dimensional image to or from an array which has been
declared in the calling program. The fpixels and lpixels parameters
are integer arrays which specify the starting and ending pixels in each
dimension of the FITS image that are to be read or written. (Note that
these are the starting and ending pixels in the FITS image, not in the
declared array). The array parameter is treated simply as a large
one-dimensional array of the appropriate datatype containing the pixel
values; The pixel values in the FITS array are read/written from/to
this program array in strict sequence without any gaps; it is up to
the calling routine to correctly interpret the dimensionality of this
array. The two families of FITS reading routines (FTGSVx and FTGSFx
subroutines) also have an ’incs’ parameter which defines the
data sampling interval in each dimension of the FITS array. For
example, if incs(1)=2 and incs(2)=3 when reading a 2-dimensional
FITS image, then only every other pixel in the first dimension
and every 3rd pixel in the second dimension will be returned in
the ’array’ parameter. [Note: the FTGSSx family of routines which
were present in previous versions of FITSIO have been superseded
by the more general FTGSVx family of routines.]
- 15
- Put an arbitrary data subsection into the data array.
FTPSS[BIJKED](unit,group,naxis,naxes,fpixels,lpixels,array, > status)
- 16
- Get an arbitrary data subsection from the data array. Undefined
pixels in the array will be set equal to the value of ’nullval’,
unless nullval=0 in which case no testing for undefined pixels will
be performed.
FTGSV[BIJKED](unit,group,naxis,naxes,fpixels,lpixels,incs,nullval, >
array,anyf,status)
- 17
- Get an arbitrary data subsection from the data array. Any Undefined
pixels in the array will have the corresponding ’flagvals’
element set equal to .TRUE.
FTGSF[BIJKED](unit,group,naxis,naxes,fpixels,lpixels,incs, >
array,flagvals,anyf,status)
6.7 FITS ASCII and Binary Table Data I/O Subroutines
6.7.1 Column Information Subroutines
- 1
- Get the number of rows or columns in the current FITS table.
The number of rows is given by the NAXIS2 keyword and the
number of columns is given by the TFIELDS keyword in the header
of the table. The FTGNRWLL routine is identical to FTGNRW except
that the number of rows is returned as a 64-bit integer rather
than a 32-bit integer.
FTGNRW(unit, > nrows, status)
FTGNRWLL(unit, > nrowsll, status)
FTGNCL(unit, > ncols, status)
- 2
- Get the table column number (and name) of the column whose name
matches an input template name. The table column names are defined by
the TTYPEn keywords in the FITS header. If a column does not have a
TTYPEn keyword, then these routines assume that the name consists of
all blank characters. These 2 subroutines perform the same function
except that FTGCNO only returns the number of the matching column whereas
FTGCNN also returns the name of the column. If CASESEN = .true. then
the column name match will be case-sensitive.
The input column name template (COLTEMPLATE) is (1) either the exact
name of the column to be searched for, or (2) it may contain wild cards
characters (*, ?, or #), or (3) it may contain the number of the desired
column (where the number is expressed as ASCII digits). The first 2 wild
cards behave similarly to UNIX filename matching: the ’*’ character matches
any sequence of characters (including zero characters) and the ’?’
character matches any single character. The # wildcard will match
any consecutive string of decimal digits (0-9). As an example, the template
strings ’AB?DE’, ’AB*E’, and ’AB*CDE’ will all match the string
’ABCDE’. If more than one column name in the table matches the
template string, then the first match is returned and the status value
will be set to 237 as a warning that a unique match was not found. To
find the other cases that match the template, simply call the
subroutine again leaving the input status value equal to 237 and the
next matching name will then be returned. Repeat this process until a
status = 219 (column name not found) is returned. If these subroutines
fail to match the template to any of the columns in the table, they
lastly check if the template can be interpreted as a simple positive
integer (e.g., ’7’, or ’512’) and if so, they return that column
number. If no matches are found then a status = 219 error is
returned.
Note that the FITS Standard recommends that only letters, digits, and
the underscore character be used in column names (with no embedded
spaces in the name). Trailing blank characters are not significant.
FTGCNO(unit,casesen,coltemplate, > colnum,status)
FTGCNN(unit,casesen,coltemplate, > colname,colnum,status)
- 3
- Get the datatype of a column in an ASCII or binary table. This
routine returns an integer code value corresponding to the datatype
of the column. (See the FTBNFM and FTASFM subroutines in the Utilities
section of this document for a list of the code values). The vector
repeat count (which is alway 1 for ASCII table columns) is also returned.
If the specified column has an ASCII character datatype (code = 16) then
the width of a unit string in the column is also returned. Note that
this routine supports the local convention for specifying arrays of
strings within a binary table character column, using the syntax
TFORM = ’rAw’ where ’r’ is the total number of characters (= the width
of the column) and ’w’ is the width of a unit string within the column.
Thus if the column has TFORM = ’60A12’ then this routine will return
datacode = 16, repeat = 60, and width = 12. (The TDIMn
keyword may also be used to specify the unit string length; The pair
of keywords TFORMn = ’60A’ and TDIMn = ’(12,5)’ would have the
same effect as TFORMn = ’60A12’).
The second routine, FTEQTY is similar except that in
the case of scaled integer columns it returns the ’equivalent’ data
type that is needed to store the scaled values, and not necessarily
the physical data type of the unscaled values as stored in the FITS
table. For example if a ’1I’ column in a binary table has TSCALn =
1 and TZEROn = 32768, then this column effectively contains unsigned
short integer values, and thus the returned value of typecode will
be the code for an unsigned short integer, not a signed short integer.
Similarly, if a column has TTYPEn = ’1I’
and TSCALn = 0.12, then the returned typecode
will be the code for a ’real’ column.
FTGTCL(unit,colnum, > datacode,repeat,width,status)
FTEQTY(unit,colnum, > datacode,repeat,width,status)
- 4
- Return the display width of a column. This is the length
of the string that will be returned
when reading the column as a formatted string. The display width is
determined by the TDISPn keyword, if present, otherwise by the data
type of the column.
FTGCDW(unit, colnum, > dispwidth, status)
- 5
- Get information about an existing ASCII table column. (NOTE: TSCAL and
TZERO must be declared as Double Precision variables). All the
returned parameters are scalar quantities.
FTGACL(unit,colnum, >
ttype,tbcol,tunit,tform,tscal,tzero,snull,tdisp,status)
- 6
- Get information about an existing binary table column. (NOTE: TSCAL and
TZERO must be declared as Double Precision variables). DATATYPE is a
character string which returns the datatype of the column as defined
by the TFORMn keyword (e.g., ’I’, ’J’,’E’, ’D’, etc.). In the case
of an ASCII character column, DATATYPE will have a value of the
form ’An’ where ’n’ is an integer expressing the width of the field
in characters. For example, if TFORM = ’160A8’ then FTGBCL will return
DATATYPE=’A8’ and REPEAT=20. All the returned parameters are scalar
quantities.
FTGBCL(unit,colnum, >
ttype,tunit,datatype,repeat,tscal,tzero,tnull,tdisp,status)
- 7
- Put (append) a TDIMn keyword whose value has the form ’(l,m,n...)’
where l, m, n... are the dimensions of a multidimensional array
column in a binary table.
FTPTDM(unit,colnum,naxis,naxes, > status)
- 8
- Return the number of and size of the dimensions of a table column.
Normally this information is given by the TDIMn keyword, but if
this keyword is not present then this routine returns NAXIS = 1
and NAXES(1) equal to the repeat count in the TFORM keyword.
FTGTDM(unit,colnum,maxdim, > naxis,naxes,status)
- 9
- Decode the input TDIMn keyword string (e.g. ’(100,200)’) and return the
number of and size of the dimensions of a binary table column. If the input
tdimstr character string is null, then this routine returns naxis = 1
and naxes[0] equal to the repeat count in the TFORM keyword. This routine
is called by FTGTDM.
FTDTDM(unit,tdimstr,colnum,maxdim, > naxis,naxes, status)
- 10
- Return the optimal number of rows to read or write at one time for
maximum I/O efficiency. Refer to the “Optimizing Code” section
in Chapter 5 for more discussion on how to use this routine.
FTGRSZ(unit, > nrows,status)
6.7.2 Low-Level Table Access Subroutines
The following subroutines provide low-level access to the data in ASCII
or binary tables and are mainly useful as an efficient way to copy all
or part of a table from one location to another. These routines simply
read or write the specified number of consecutive bytes in an ASCII or
binary table, without regard for column boundaries or the row length in
the table. The first two subroutines read or write consecutive bytes
in a table to or from a character string variable, while the last two
subroutines read or write consecutive bytes to or from a variable
declared as a numeric data type (e.g., INTEGER, INTEGER*2, REAL, DOUBLE
PRECISION). These routines do not perform any machine dependent data
conversion or byte swapping, except that conversion to/from ASCII
format is performed by the FTGTBS and FTPTBS routines on machines which
do not use ASCII character codes in the internal data representations
(e.g., on IBM mainframe computers).
- 1
- Read a consecutive string of characters from an ASCII table
into a character variable (spanning columns and multiple rows if necessary)
This routine should not be used with binary tables because of
complications related to passing string variables between C and Fortran.
FTGTBS(unit,frow,startchar,nchars, > string,status)
- 2
- Write a consecutive string of characters to an ASCII table
from a character variable (spanning columns and multiple rows if necessary)
This routine should not be used with binary tables because of
complications related to passing string variables between C and Fortran.
FTPTBS(unit,frow,startchar,nchars,string, > status)
- 3
- Read a consecutive array of bytes from an ASCII or binary table
into a numeric variable (spanning columns and multiple rows if necessary).
The array parameter may be declared as any numerical datatype as long
as the array is at least ’nchars’ bytes long, e.g., if nchars = 17,
then declare the array as INTEGER*4 ARRAY(5).
FTGTBB(unit,frow,startchar,nchars, > array,status)
- 4
- Write a consecutive array of bytes to an ASCII or binary table
from a numeric variable (spanning columns and multiple rows if necessary)
The array parameter may be declared as any numerical datatype as long
as the array is at least ’nchars’ bytes long, e.g., if nchars = 17,
then declare the array as INTEGER*4 ARRAY(5).
FTPTBB(unit,frow,startchar,nchars,array, > status)
6.7.3 Edit Rows or Columns
- 1
- Insert blank rows into an existing ASCII or binary table (in the CDU).
All the rows FOLLOWING row FROW are shifted down by NROWS rows. If
FROW or FROWLL equals 0 then the blank rows are inserted at the beginning of the
table. These routines modify the NAXIS2 keyword to reflect the new
number of rows in the table. Note that it is *not* necessary to insert rows in a table before
writing data to those rows (indeed, it would be inefficient to do so).
Instead, one may simply write data to any row of the table, whether that
row of data already exists or not.
FTIROW(unit,frow,nrows, > status)
FTIROWLL(unit,frowll,nrowsll, > status)
- 2
- Delete rows from an existing ASCII or binary table (in the CDU).
The NROWS (or NROWSLL) is the number of rows are deleted, starting
with row FROW (or FROWLL), and
any remaining rows in the table are shifted up to fill in the space.
These routines modify the NAXIS2 keyword to reflect the new number
of rows in the table.
FTDROW(unit,frow,nrows, > status)
FTDROWLL(unit,frowll,nrowsll, > status)
- 3
- Delete a list of rows from an ASCII or binary table (in the CDU).
In the first routine, ’rowrange’ is a character string listing the
rows or row ranges to delete (e.g., ’2-4, 5, 8-9’). In the second
routine, ’rowlist’ is an integer array of row numbers to be deleted
from the table. nrows is the number of row numbers in the list.
The first row in the table is 1 not 0. The list of row numbers
must be sorted in ascending order.
FTDRRG(unit,rowrange, > status)
FTDRWS(unit,rowlist,nrows, > status)
- 4
- Insert a blank column (or columns) into an existing ASCII or binary
table (in the CDU). COLNUM specifies the column number that the (first)
new column should occupy in the table. NCOLS specifies how many
columns are to be inserted. Any existing columns from this position and
higher are moved over to allow room for the new column(s).
The index number on all the following keywords will be incremented
if necessary to reflect the new position of the column(s) in the table:
TBCOLn, TFORMn, TTYPEn, TUNITn, TNULLn, TSCALn, TZEROn, TDISPn, TDIMn,
TLMINn, TLMAXn, TDMINn, TDMAXn, TCTYPn, TCRPXn, TCRVLn, TCDLTn, TCROTn,
and TCUNIn.
FTICOL(unit,colnum,ttype,tform, > status)
FTICLS(unit,colnum,ncols,ttype,tform, > status)
- 5
- Modify the vector length of a binary table column (e.g.,
change a column from TFORMn = ’1E’ to ’20E’). The vector
length may be increased or decreased from the current value.
FTMVEC(unit,colnum,newveclen, > status)
- 6
- Delete a column from an existing ASCII or binary table (in the CDU).
The index number of all the keywords listed above (for FTICOL) will be
decremented if necessary to reflect the new position of the column(s) in
the table. Those index keywords that refer to the deleted column will
also be deleted. Note that the physical size of the FITS file will
not be reduced by this operation, and the empty FITS blocks if any
at the end of the file will be padded with zeros.
FTDCOL(unit,colnum, > status)
- 7
- Copy a column from one HDU to another (or to the same HDU). If
createcol = TRUE, then a new column will be inserted in the output
table, at position ‘outcolumn’, otherwise the existing output column will
be overwritten (in which case it must have a compatible datatype).
Note that the first column in a table is at colnum = 1.
FTCPCL(inunit,outunit,incolnum,outcolnum,createcol, > status);
6.7.4 Read and Write Column Data Routines
These subroutines put or get data values in the current ASCII or Binary table
extension. Automatic data type conversion is performed for numerical data
types (B,I,J,E,D) if the data type of the column (defined by the TFORM keyword)
differs from the data type of the calling subroutine. The data values are also
scaled by the TSCALn and TZEROn header values as they are being written to
or read from the FITS array. The fttscl subroutine MUST be used to define the
scaling parameters when writing data to the table or to override the default
scaling values given in the header when reading from the table.
Note that it is *not* necessary to insert rows in a table before
writing data to those rows (indeed, it would be inefficient to do so).
Instead, one may simply write data to any row of the table, whether that
row of data already exists or not.
In the case of binary tables with vector elements, the ’felem’
parameter defines the starting pixel within the element vector. This
parameter is ignored with ASCII tables. Similarly, in the case of
binary tables the ’nelements’ parameter specifies the total number of
vector values read or written (continuing on subsequent rows if
required) and not the number of table elements. Two sets of
subroutines are provided to get the column data which differ in the way
undefined pixels are handled. The first set of routines (FTGCV)
simply return an array of data elements in which undefined pixels are
set equal to a value specified by the user in the ’nullval’ parameter.
An additional feature of these subroutines is that if the user sets
nullval = 0, then no checks for undefined pixels will be performed,
thus increasing the speed of the program. The second set of routines
(FTGCF) returns the data element array and in addition a logical array
of flags which defines whether the corresponding data pixel is 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.
- 1
- Put elements into an ASCII or binary table column (in the CDU).
(The SPP FSPCLS routine has an additional integer argument after
the VALUES character string which specifies the size of the 1st
dimension of this 2-D CHAR array).
The alternate version of these routines, whose names end in ’LL’
after the datatype character, support large tables with more then
2*31 rows. When calling these routines, the frow and felem parameters
*must* be 64-bit integer*8 variables, instead of normal 4-byte integers.
FTPCL[SLBIJKEDCM](unit,colnum,frow,felem,nelements,values, > status)
FTPCL[LBIJKEDCM]LL(unit,colnum,frow,felem,nelements,values, > status)
- 2
- Put elements into an ASCII or binary table column (in the CDU)
substituting the appropriate FITS null value for any elements that
are equal to NULLVAL. For ASCII TABLE extensions, the
null value defined by the previous call to FTSNUL will be substituted;
For integer FITS columns, in a binary table the null value
defined by the previous call to FTTNUL will be substituted;
For floating point FITS columns a special IEEE NaN (Not-a-Number)
value will be substituted.
The alternate version of these routines, whose names end in ’LL’
after the datatype character, support large tables with more then
2*31 rows. When calling these routines, the frow and felem parameters
*must* be 64-bit integer*8 variables, instead of normal 4-byte integers.
FTPCN[SBIJKED](unit,colnum,frow,felem,nelements,values,nullval > status)
FTPCN[SBIJKED]LL(unit,colnum,(I*8) frow,(I*8) felem,nelements,values,
nullval > status)
- 3
- Put bit values into a binary byte (’B’) or bit (’X’) table column (in the
CDU). LRAY is an array of logical values corresponding to the sequence of
bits to be written. If LRAY is true then the corresponding bit is
set to 1, otherwise the bit is set to 0. Note that in the case of
’X’ columns, FITSIO will write to all 8 bits of each byte whether
they are formally valid or not. Thus if the column is defined as
’4X’, and one calls FTPCLX with fbit=1 and nbit=8, then all 8 bits
will be written into the first byte (as opposed to writing the
first 4 bits into the first row and then the next 4 bits into the
next row), even though the last 4 bits of each byte are formally
not defined.
FTPCLX(unit,colnum,frow,fbit,nbit,lray, > status)
- 4
- Set table elements in a column as undefined
FTPCLU(unit,colnum,frow,felem,nelements, > status)
- 5
- Get elements from an ASCII or binary table column (in the CDU). These
routines return the values of the table column array elements. 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. (Note: the ftgcl routine simple gets an array
of logical data values without any checks for undefined values; use
the ftgcfl routine to check for undefined logical elements).
(The SPP FSGCVS routine has an additional integer argument after
the VALUES character string which specifies the size of the 1st
dimension of this 2-D CHAR array).
The alternate version of these routines, whose names end in ’LL’
after the datatype character, support large tables with more then
2*31 rows. When calling these routines, the frow and felem parameters
*must* be 64-bit integer*8 variables, instead of normal 4-byte integers.
FTGCL(unit,colnum,frow,felem,nelements, > values,status)
FTGCV[SBIJKEDCM](unit,colnum,frow,felem,nelements,nullval, >
values,anyf,status)
FTGCV[BIJKEDCM]LL(unit,colnum,(I*8) frow, (I*8) felem, nelements,
nullval, > values,anyf,status)
- 6
- Get elements and null flags from an ASCII or binary table column (in the
CHDU). These routines return the values of the table column array elements.
Any undefined array elements will have the corresponding flagvals element
set equal to .TRUE. The ANYF parameter is set to true if any of the
returned elements are undefined.
(The SPP FSGCFS routine has an additional integer argument after
the VALUES character string which specifies the size of the 1st
dimension of this 2-D CHAR array).
The alternate version of these routines, whose names end in ’LL’
after the datatype character, support large tables with more then
2*31 rows. When calling these routines, the frow and felem parameters
*must* be 64-bit integer*8 variables, instead of normal 4-byte integers.
FTGCF[SLBIJKEDCM](unit,colnum,frow,felem,nelements, >
values,flagvals,anyf,status)
FTGCF[BIJKED]LL(unit,colnum, (I*8) frow, (I*8) felem,nelements, >
values,flagvals,anyf,status)
- 7
- Get an arbitrary data subsection from an N-dimensional array
in a binary table vector column. Undefined pixels
in the array will be set equal to the value of ’nullval’,
unless nullval=0 in which case no testing for undefined pixels will
be performed. The first and last rows in the table to be read
are specified by fpixels(naxis+1) and lpixels(naxis+1), and hence
are treated as the next higher dimension of the FITS N-dimensional
array. The INCS parameter specifies the sampling interval in
each dimension between the data elements that will be returned.
FTGSV[BIJKED](unit,colnum,naxis,naxes,fpixels,lpixels,incs,nullval, >
array,anyf,status)
- 8
- Get an arbitrary data subsection from an N-dimensional array
in a binary table vector column. Any Undefined
pixels in the array will have the corresponding ’flagvals’
element set equal to .TRUE. The first and last rows in the table
to be read are specified by fpixels(naxis+1) and lpixels(naxis+1),
and hence are treated as the next higher dimension of the FITS
N-dimensional array. The INCS parameter specifies the sampling
interval in each dimension between the data elements that will be
returned.
FTGSF[BIJKED](unit,colnum,naxis,naxes,fpixels,lpixels,incs, >
array,flagvals,anyf,status)
- 9
- Get bit values from a byte (’B’) or bit (‘X‘) table column (in the
CDU). LRAY is an array of logical values corresponding to the
sequence of bits to be read. If LRAY is true then the
corresponding bit was set to 1, otherwise the bit was set to 0.
Note that in the case of ’X’ columns, FITSIO will read all 8 bits
of each byte whether they are formally valid or not. Thus if the
column is defined as ’4X’, and one calls FTGCX with fbit=1 and
nbit=8, then all 8 bits will be read from the first byte (as
opposed to reading the first 4 bits from the first row and then the
first 4 bits from the next row), even though the last 4 bits of
each byte are formally not defined.
FTGCX(unit,colnum,frow,fbit,nbit, > lray,status)
- 10
- Read any consecutive set of bits from an ’X’ or ’B’ column and
interpret them as an unsigned n-bit integer. NBIT must be less than
or equal to 16 when calling FTGCXI, and less than or equal to 32 when
calling FTGCXJ; there is no limit on the value of NBIT for FTGCXD, but
the returned double precision value only has 48 bits of precision on
most 32-bit word machines. The NBITS bits are interpreted as an
unsigned integer unless NBITS = 16 (in FTGCXI) or 32 (in FTGCXJ) in which
case the string of bits are interpreted as 16-bit or 32-bit 2’s
complement signed integers. If NROWS is greater than 1 then the
same set of bits will be read from sequential rows in the table
starting with row FROW. Note that the numbering convention
used here for the FBIT parameter adopts 1 for the first element of the
vector of bits; this is the Most Significant Bit of the integer value.
FTGCX[IJD](unit,colnum,frow,nrows,fbit,nbit, > array,status)
- 11
- Get the descriptor for a variable length column in a binary table.
The descriptor consists of 2 integer parameters: the number of elements
in the array and the starting offset relative to the start of the heap.
The first routine returns a single descriptor whereas the second routine
returns the descriptors for a range of rows in the table.
FTGDES(unit,colnum,rownum, > nelements,offset,status)
FTGDESLL(unit,colnum,rownum, > nelementsll,offsetll,status)
FTGDESS(unit,colnum,firstrow,nrows > nelements,offset, status)
FTGDESSLL(unit,colnum,firstrow,nrows > nelementsll,offsetll, status)
- 12
- Write the descriptor for a variable length column in a binary table.
These subroutines can be used in conjunction with FTGDES to enable
2 or more arrays to point to the same storage location to save
storage space if the arrays are identical.
FTPDES(unit,colnum,rownum,nelements,offset, > status)
FTPDESLL(unit,colnum,rownum,nelementsll,offsetll, > status)
6.8 Row Selection and Calculator Routines
These routines all parse and evaluate an input string containing a user
defined arithmetic expression. The first 3 routines select rows in a
FITS table, based on whether the expression evaluates to true (not
equal to zero) or false (zero). The other routines evaluate the
expression and calculate a value for each row of the table. The
allowed expression syntax is described in the row filter section in the
earlier ‘Extended File Name Syntax’ chapter of this document. The
expression may also be written to a text file, and the name of the
file, prepended with a ’@’ character may be supplied for the ’expr’
parameter (e.g. ’@filename.txt’). The expression in the file can
be arbitrarily complex and extend over multiple lines of the file.
Lines that begin with 2 slash characters (’//’) will be ignored and
may be used to add comments to the file.
- 1
- Evaluate a boolean expression over the indicated rows, returning an
array of flags indicating which rows evaluated to TRUE/FALSE
FTFROW(unit,expr,firstrow, nrows, > n_good_rows, row_status, status)
- 2
- Find the first row which satisfies the input boolean expression
FTFFRW(unit, expr, > rownum, status)
- 3
- Evaluate an expression on all rows of a table. If the input and output
files are not the same, copy the TRUE rows to the output file; if the output
table is not empty, then this routine will append the new
selected rows after the existing rows. If the
files are the same, delete the FALSE rows (preserve the TRUE rows).
FTSROW(inunit, outunit, expr, > status)
- 4
- Calculate an expression for the indicated rows of a table, returning
the results, cast as datatype (TSHORT, TDOUBLE, etc), in array. If
nulval==NULL, UNDEFs will be zeroed out. For vector results, the number
of elements returned may be less than nelements if nelements is not an
even multiple of the result dimension. Call FTTEXP to obtain
the dimensions of the results.
FTCROW(unit,datatype,expr,firstrow,nelements,nulval, >
array,anynul,status)
- 5
- Evaluate an expression and write the result either to a column (if
the expression is a function of other columns in the table) or to a
keyword (if the expression evaluates to a constant and is not a
function of other columns in the table). In the former case, the
parName parameter is the name of the column (which may or may not already
exist) into which to write the results, and parInfo contains an
optional TFORM keyword value if a new column is being created. If a
TFORM value is not specified then a default format will be used,
depending on the expression. If the expression evaluates to a constant,
then the result will be written to the keyword name given by the
parName parameter, and the parInfo parameter may be used to supply an
optional comment for the keyword. If the keyword does not already
exist, then the name of the keyword must be preceded with a ’#’ character,
otherwise the result will be written to a column with that name.
FTCALC(inunit, expr, outunit, parName, parInfo, > status)
- 6
- This calculator routine is similar to the previous routine, except
that the expression is only evaluated over the specified
row ranges. nranges specifies the number of row ranges, and firstrow
and lastrow give the starting and ending row number of each range.
FTCALC_RNG(inunit, expr, outunit, parName, parInfo,
nranges, firstrow, lastrow, > status)
- 7
- Evaluate the given expression and return dimension and type information
on the result. The returned dimensions correspond to a single row entry
of the requested expression, and are equivalent to the result of fits_read_tdim().
Note that strings are considered to be one element regardless of string length.
If maxdim == 0, then naxes is optional.
FTTEXP(unit, expr, maxdim > datatype, nelem, naxis, naxes, status)
6.9 Celestial Coordinate System Subroutines
The FITS community has adopted a set of keyword conventions that define
the transformations needed to convert between pixel locations in an
image and the corresponding celestial coordinates on the sky, or more
generally, that define world coordinates that are to be associated with
any pixel location in an n-dimensional FITS array. CFITSIO is distributed
with a couple of self-contained World Coordinate System (WCS) routines,
however, these routines DO NOT support all the latest WCS conventions,
so it is STRONGLY RECOMMENDED that software developers use a more robust
external WCS library. Several recommended libraries are:
WCSLIB - supported by Mark Calabretta
WCSTools - supported by Doug Mink
AST library - developed by the U.K. Starlink project
More information about the WCS keyword conventions and links to all of
these WCS libraries can be found on the FITS Support Office web site at
http://fits.gsfc.nasa.gov under the WCS link.
The functions provided in these external WCS libraries will need access to
the WCS information contained in the FITS file headers. One convenient
way to pass this information to the external library is to use FITSIO
to copy the header keywords into one long character string, and then
pass this string to an interface routine in the external library that
will extract the necessary WCS information (e.g., see the astFitsChan
and astPutCards routines in the Starlink AST library).
The following FITSIO routines DO NOT support the more recent WCS conventions
that have been approved as part of the FITS standard. Consequently,
the following routines ARE NOW DEPRECATED. It is STRONGLY RECOMMENDED
that software developers not use these routines, and instead use an
external WCS library, as described above.
These routines are included mainly for backward compatibility with
existing software. They support the following standard map
projections: -SIN, -TAN, -ARC, -NCP, -GLS, -MER, and -AIT (these are the
legal values for the coordtype parameter). These routines are based
on similar functions in Classic AIPS. All the angular quantities are
given in units of degrees.
- 1
- Get the values of all the standard FITS celestial coordinate system
keywords from the header of a FITS image (i.e., the primary array or
an image extension). These values may then be passed to the subroutines
that perform the coordinate transformations. If any or all of the WCS
keywords are not present, then default values will be returned. If
the first coordinate axis is the declination-like coordinate, then
this routine will swap them so that the longitudinal-like coordinate
is returned as the first axis.
If the file uses the newer ’CDj_i’ WCS transformation matrix
keywords instead of old style ’CDELTn’ and ’CROTA2’ keywords, then
this routine will calculate and return the values of the equivalent
old-style keywords. Note that the conversion from the new-style
keywords to the old-style values is sometimes only an
approximation, so if the approximation is larger than an internally
defined threshold level, then CFITSIO will still return the
approximate WCS keyword values, but will also return with status =
506, to warn the calling program that approximations have been
made. It is then up to the calling program to decide whether the
approximations are sufficiently accurate for the particular
application, or whether more precise WCS transformations must be
performed using new-style WCS keywords directly.
FTGICS(unit, > xrval,yrval,xrpix,yrpix,xinc,yinc,rot,coordtype,status)
- 2
- Get the values of all the standard FITS celestial coordinate system
keywords from the header of a FITS table where the X and Y (or RA and
DEC coordinates are stored in 2 separate columns of the table.
These values may then be passed to the subroutines that perform the
coordinate transformations.
FTGTCS(unit,xcol,ycol, >
xrval,yrval,xrpix,yrpix,xinc,yinc,rot,coordtype,status)
- 3
- Calculate the celestial coordinate corresponding to the input
X and Y pixel location in the image.
FTWLDP(xpix,ypix,xrval,yrval,xrpix,yrpix,xinc,yinc,rot,
coordtype, > xpos,ypos,status)
- 4
- Calculate the X and Y pixel location corresponding to the input
celestial coordinate in the image.
FTXYPX(xpos,ypos,xrval,yrval,xrpix,yrpix,xinc,yinc,rot,
coordtype, > xpix,ypix,status)
6.10 File Checksum Subroutines
The following routines either compute or validate the checksums for the
CHDU. The DATASUM keyword is used to store the numerical value of the
32-bit, 1’s complement checksum for the data unit alone. If there is
no data unit then the value is set to zero. The numerical value is
stored as an ASCII string of digits, enclosed in quotes, because the
value may be too large to represent as a 32-bit signed integer. The
CHECKSUM keyword is used to store the ASCII encoded COMPLEMENT of the
checksum for the entire HDU. Storing the complement, rather than the
actual checksum, forces the checksum for the whole HDU to equal zero.
If the file has been modified since the checksums were computed, then
the HDU checksum will usually not equal zero. These checksum keyword
conventions are based on a paper by Rob Seaman published in the
proceedings of the ADASS IV conference in Baltimore in November 1994
and a later revision in June 1995.
- 1
- Compute and write the DATASUM and CHECKSUM keyword values for the CHDU
into the current header. The DATASUM value is the 32-bit checksum
for the data unit, expressed as a decimal integer enclosed in single
quotes. The CHECKSUM keyword value is a 16-character string which
is the ASCII-encoded value for the complement of the checksum for
the whole HDU. If these keywords already exist, their values
will be updated only if necessary (i.e., if the file has been modified
since the original keyword values were computed).
FTPCKS(unit, > status)
- 2
- Update the CHECKSUM keyword value in the CHDU, assuming that the
DATASUM keyword exists and already has the correct value. This routine
calculates the new checksum for the current header unit, adds it to the
data unit checksum, encodes the value into an ASCII string, and writes
the string to the CHECKSUM keyword.
FTUCKS(unit, > status)
- 3
- Verify the CHDU by computing the checksums and comparing
them with the keywords. The data unit is verified correctly
if the computed checksum equals the value of the DATASUM
keyword. The checksum for the entire HDU (header plus data unit) is
correct if it equals zero. The output DATAOK and HDUOK parameters
in this subroutine are integers which will have a value = 1
if the data or HDU is verified correctly, a value = 0
if the DATASUM or CHECKSUM keyword is not present, or value = -1
if the computed checksum is not correct.
FTVCKS(unit, > dataok,hduok,status)
- 4
- Compute and return the checksum values for the CHDU (as
double precision variables) without creating or modifying the
CHECKSUM and DATASUM keywords. This routine is used internally by
FTVCKS, but may be useful in other situations as well.
FTGCKS(unit, > datasum,hdusum,status)
- 5
- Encode a checksum value (stored in a double precision variable)
into a 16-character string. If COMPLEMENT = .true. then the 32-bit
sum value will be complemented before encoding.
FTESUM(sum,complement, > checksum)
- 6
- Decode a 16 character checksum string into a double precision value.
If COMPLEMENT = .true. then the 32-bit sum value will be complemented
after decoding.
FTDSUM(checksum,complement, > sum)
6.11 Date and Time Utility Routines
The following routines help to construct or parse the FITS date/time
strings. Starting in the year 2000, the FITS DATE keyword values (and
the values of other ‘DATE-’ keywords) must have the form ’YYYY-MM-DD’
(date only) or ’YYYY-MM-DDThh:mm:ss.ddd...’ (date and time) where the
number of decimal places in the seconds value is optional. These times
are in UTC. The older ’dd/mm/yy’ date format may not be used for dates
after 01 January 2000.
- 1
- Get the current system date. The returned year has 4 digits
(1999, 2000, etc.)
FTGSDT( > day, month, year, status )
- 2
- Get the current system date and time string (’YYYY-MM-DDThh:mm:ss’).
The time will be in UTC/GMT if available, as indicated by a returned timeref
value = 0. If the returned value of timeref = 1 then this indicates that
it was not possible to convert the local time to UTC, and thus the local
time was returned.
FTGSTM(> datestr, timeref, status)
- 3
- Construct a date string from the input date values. If the year
is between 1900 and 1998, inclusive, then the returned date string will
have the old FITS format (’dd/mm/yy’), otherwise the date string will
have the new FITS format (’YYYY-MM-DD’). Use FTTM2S instead
to always return a date string using the new FITS format.
FTDT2S( year, month, day, > datestr, status)
- 4
- Construct a new-format date + time string (’YYYY-MM-DDThh:mm:ss.ddd...’).
If the year, month, and day values all = 0 then only the time is encoded
with format ’hh:mm:ss.ddd...’. The decimals parameter specifies how many
decimal places of fractional seconds to include in the string. If ‘decimals’
is negative, then only the date will be return (’YYYY-MM-DD’).
FTTM2S( year, month, day, hour, minute, second, decimals,
> datestr, status)
- 5
- Return the date as read from the input string, where the string may be
in either the old (’dd/mm/yy’) or new (’YYYY-MM-DDThh:mm:ss’ or
’YYYY-MM-DD’) FITS format.
FTS2DT(datestr, > year, month, day, status)
- 6
- Return the date and time as read from the input string, where the
string may be in either the old or new FITS format. The returned hours,
minutes, and seconds values will be set to zero if the input string
does not include the time (’dd/mm/yy’ or ’YYYY-MM-DD’) . Similarly,
the returned year, month, and date values will be set to zero if the
date is not included in the input string (’hh:mm:ss.ddd...’).
FTS2TM(datestr, > year, month, day, hour, minute, second, status)
6.12 General Utility Subroutines
The following utility subroutines may be useful for certain applications:
- 1
- Return the starting byte address of the CHDU and the next HDU.
FTGHAD(iunit, > curaddr, nextaddr)
- 2
- Convert a character string to uppercase (operates in place).
FTUPCH(string)
- 3
- Compare the input template string against the reference string
to see if they match. The template string may contain wildcard
characters: ’*’ will match any sequence of characters (including
zero characters) and ’?’ will match any single character in the
reference string. The ’#’ character will match any consecutive string
of decimal digits (0 - 9). If CASESN = .true. then the match will be
case sensitive. The returned MATCH parameter will be .true. if
the 2 strings match, and EXACT will be .true. if the match is
exact (i.e., if no wildcard characters were used in the match).
Both strings must be 68 characters or less in length.
FTCMPS(str_template, string, casesen, > match, exact)
- 4
- Test that the keyword name contains only legal characters: A-Z,0-9,
hyphen, and underscore.
FTTKEY(keyword, > status)
- 5
- Test that the keyword record contains only legal printable ASCII
characters
FTTREC(card, > status)
- 6
- Test whether the current header contains any NULL (ASCII 0) characters.
These characters are illegal in the header, but they will go undetected
by most of the CFITSIO keyword header routines, because the null is
interpreted as the normal end-of-string terminator. This routine returns
the position of the first null character in the header, or zero if there
are no nulls. For example a returned value of 110 would indicate that
the first NULL is located in the 30th character of the second keyword
in the header (recall that each header record is 80 characters long).
Note that this is one of the few FITSIO routines in which the returned
value is not necessarily equal to the status value).
FTNCHK(unit, > status)
- 7
- Parse a header keyword record and return the name of the keyword
and the length of the name.
The keyword name normally occupies the first 8 characters of the
record, except under the HIERARCH convention where the name can
be up to 70 characters in length.
FTGKNM(card, > keyname, keylength, staThe '\#' character will match any consecutive string
of decimal digits (0 - 9). tus)
- 8
- Parse a header keyword record.
This subroutine parses the input header record to return the value (as
a character string) and comment strings. If the keyword has no
value (columns 9-10 not equal to ’= ’), then the value string is returned
blank and the comment string is set equal to column 9 - 80 of the
input string.
FTPSVC(card, > value,comment,status)
- 9
- Construct a properly formated 80-character header keyword record from the
input keyword name, keyword value, and keyword comment strings.
Hierarchical keyword names (e.g., "ESO TELE CAM") are supported.
The value string may contain an integer, floating point, logical, or
quoted character string (e.g., "12", "15.7", "T",
or "’NGC 1313’").
FTMKKY(keyname, value, comment, > card, status)
- 10
- Construct a sequence keyword name (ROOT + nnn).
This subroutine appends the sequence number to the root string to create
a keyword name (e.g., ’NAXIS’ + 2 = ’NAXIS2’)
FTKEYN(keyroot,seq_no, > keyword,status)
- 11
- Construct a sequence keyword name (n + ROOT).
This subroutine concatenates the sequence number to the front of the
root string to create a keyword name (e.g., 1 + ’CTYP’ = ’1CTYP’)
FTNKEY(seq_no,keyroot, > keyword,status)
- 12
- Determine the datatype of a keyword value string.
This subroutine parses the keyword value string (usually columns 11-30
of the header record) to determine its datatype.
FTDTYP(value, > dtype,status)
- 13
- Return the class of input header record. The record is classified
into one of the following categories (the class values are
defined in fitsio.h). Note that this is one of the few FITSIO
routines that does not return a status value.
Class Value Keywords
TYP_STRUC_KEY 10 SIMPLE, BITPIX, NAXIS, NAXISn, EXTEND, BLOCKED,
GROUPS, PCOUNT, GCOUNT, END
XTENSION, TFIELDS, TTYPEn, TBCOLn, TFORMn, THEAP,
and the first 4 COMMENT keywords in the primary array
that define the FITS format.
TYP_CMPRS_KEY 20 The keywords used in the compressed image or table
format, including ZIMAGE, ZCMPTYPE, ZNAMEn, ZVALn,
ZTILEn, ZBITPIX, ZNAXISn, ZSCALE, ZZERO, ZBLANK
TYP_SCAL_KEY 30 BSCALE, BZERO, TSCALn, TZEROn
TYP_NULL_KEY 40 BLANK, TNULLn
TYP_DIM_KEY 50 TDIMn
TYP_RANG_KEY 60 TLMINn, TLMAXn, TDMINn, TDMAXn, DATAMIN, DATAMAX
TYP_UNIT_KEY 70 BUNIT, TUNITn
TYP_DISP_KEY 80 TDISPn
TYP_HDUID_KEY 90 EXTNAME, EXTVER, EXTLEVEL, HDUNAME, HDUVER, HDULEVEL
TYP_CKSUM_KEY 100 CHECKSUM, DATASUM
TYP_WCS_KEY 110 CTYPEn, CUNITn, CRVALn, CRPIXn, CROTAn, CDELTn
CDj_is, PVj_ms, LONPOLEs, LATPOLEs
TCTYPn, TCTYns, TCUNIn, TCUNns, TCRVLn, TCRVns, TCRPXn,
TCRPks, TCDn_k, TCn_ks, TPVn_m, TPn_ms, TCDLTn, TCROTn
jCTYPn, jCTYns, jCUNIn, jCUNns, jCRVLn, jCRVns, iCRPXn,
iCRPns, jiCDn, jiCDns, jPVn_m, jPn_ms, jCDLTn, jCROTn
(i,j,m,n are integers, s is any letter)
TYP_REFSYS_KEY 120 EQUINOXs, EPOCH, MJD-OBSs, RADECSYS, RADESYSs
TYP_COMM_KEY 130 COMMENT, HISTORY, (blank keyword)
TYP_CONT_KEY 140 CONTINUE
TYP_USER_KEY 150 all other keywords
class = FTGKCL (char *card)
- 14
- Parse the ’TFORM’ binary table column format string.
This subroutine parses the input TFORM character string and returns the
integer datatype code, the repeat count of the field, and, in the case
of character string fields, the length of the unit string. The following
datatype codes are returned (the negative of the value is returned
if the column contains variable-length arrays):
Datatype DATACODE value
bit, X 1
byte, B 11
logical, L 14
ASCII character, A 16
short integer, I 21
integer, J 41
real, E 42
double precision, D 82
complex 83
double complex 163
FTBNFM(tform, > datacode,repeat,width,status)
- 15
- Parse the ’TFORM’ keyword value that defines the column format in
an ASCII table. This routine parses the input TFORM character
string and returns the datatype code, the width of the column,
and (if it is a floating point column) the number of decimal places
to the right of the decimal point. The returned datatype codes are
the same as for the binary table, listed above, with the following
additional rules: integer columns that are between 1 and 4 characters
wide are defined to be short integers (code = 21). Wider integer
columns are defined to be regular integers (code = 41). Similarly,
Fixed decimal point columns (with TFORM = ’Fw.d’) are defined to
be single precision reals (code = 42) if w is between 1 and 7 characters
wide, inclusive. Wider ’F’ columns will return a double precision
data code (= 82). ’Ew.d’ format columns will have datacode = 42,
and ’Dw.d’ format columns will have datacode = 82.
FTASFM(tform, > datacode,width,decimals,status)
- 16
- Calculate the starting column positions and total ASCII table width
based on the input array of ASCII table TFORM values. The SPACE input
parameter defines how many blank spaces to leave between each column
(it is recommended to have one space between columns for better human
readability).
FTGABC(tfields,tform,space, > rowlen,tbcol,status)
- 17
- Parse a template string and return a formatted 80-character string
suitable for appending to (or deleting from) a FITS header file.
This subroutine is useful for parsing lines from an ASCII template file
and reformatting them into legal FITS header records. The formatted
string may then be passed to the FTPREC, FTMCRD, or FTDKEY subroutines
to append or modify a FITS header record.
FTGTHD(template, > card,hdtype,status)
The input TEMPLATE character string generally should contain 3 tokens:
(1) the KEYNAME, (2) the VALUE, and (3) the COMMENT string. The
TEMPLATE string must adhere to the following format:
- -
- The KEYNAME token must begin in columns 1-8 and be a maximum of 8
characters long. If the first 8 characters of the template line are
blank then the remainder of the line is considered to be a FITS comment
(with a blank keyword name). A legal FITS keyword name may only
contain the characters A-Z, 0-9, and ’-’ (minus sign) and
underscore. This subroutine will automatically convert any lowercase
characters to uppercase in the output string. If KEYNAME = ’COMMENT’
or ’HISTORY’ then the remainder of the line is considered to be a FITS
COMMENT or HISTORY record, respectively.
- -
- The VALUE token must be separated from the KEYNAME token by one or more
spaces and/or an ’=’ character. The datatype of the VALUE token
(numeric, logical, or character string) is automatically determined
and the output CARD string is formatted accordingly. The value
token may be forced to be interpreted as a string (e.g. if it is a
string of numeric digits) by enclosing it in single quotes.
If the value token is a character string that contains 1 or more
embedded blank space characters or slash (’/’) characters then the
entire character string must be enclosed in single quotes.
- -
- The COMMENT token is optional, but if present must be separated from
the VALUE token by a blank space or a ’/’ character.
- -
- One exception to the above rules is that if the first non-blank
character in the template string is a minus sign (’-’) followed
by a single token, or a single token followed by an equal sign,
then it is interpreted as the name of a keyword which is to be
deleted from the FITS header.
- -
- The second exception is that if the template string starts with
a minus sign and is followed by 2 tokens then the second token
is interpreted as the new name for the keyword specified by
first token. In this case the old keyword name (first token)
is returned in characters 1-8 of the returned CARD string, and
the new keyword name (the second token) is returned in characters
41-48 of the returned CARD string. These old and new names
may then be passed to the FTMNAM subroutine which will change
the keyword name.
The HDTYPE output parameter indicates how the returned CARD string
should be interpreted:
hdtype interpretation
------ -------------------------------------------------
-2 Modify the name of the keyword given in CARD(1:8)
to the new name given in CARD(41:48)
-1 CARD(1:8) contains the name of a keyword to be deleted
from the FITS header.
0 append the CARD string to the FITS header if the
keyword does not already exist, otherwise update
the value/comment if the keyword is already present
in the header.
1 simply append this keyword to the FITS header (CARD
is either a HISTORY or COMMENT keyword).
2 This is a FITS END record; it should not be written
to the FITS header because FITSIO automatically
appends the END record when the header is closed.
EXAMPLES: The following lines illustrate valid input template strings:
INTVAL 7 This is an integer keyword
RVAL 34.6 / This is a floating point keyword
EVAL=-12.45E-03 This is a floating point keyword in exponential notation
lval F This is a boolean keyword
This is a comment keyword with a blank keyword name
SVAL1 = 'Hello world' / this is a string keyword
SVAL2 '123.5' this is also a string keyword
sval3 123+ / this is also a string keyword with the value '123+ '
# the following template line deletes the DATE keyword
- DATE
# the following template line modifies the NAME keyword to OBJECT
- NAME OBJECT
- 18
- Parse the input string containing a list of rows or row ranges, and
return integer arrays containing the first and last row in each
range. For example, if rowlist = "3-5, 6, 8-9" then it will
return numranges = 3, rangemin = 3, 6, 8 and rangemax = 5, 6, 9.
At most, ’maxranges’ number of ranges will be returned. ’maxrows’
is the maximum number of rows in the table; any rows or ranges
larger than this will be ignored. The rows must be specified in
increasing order, and the ranges must not overlap. A minus sign
may be use to specify all the rows to the upper or lower bound, so
"50-" means all the rows from 50 to the end of the table, and "-"
means all the rows in the table, from 1 - maxrows.
FTRWRG(rowlist, maxrows, maxranges, >
numranges, rangemin, rangemax, status)