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)
FITSIO Home