The following utility routines may be useful for certain applications:
1
Convert a character string to uppercase (operates in place).
void fits_uppercase / ffupch (char *string)
2
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. If casesen = CASESEN = TRUE then the match will be
case sensitive, otherwise the case of the letters will be ignored
if casesen = CASEINSEN = FALSE. 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.
void fits_compare_str / ffcmps
(char *templt, char *string, int casesen, > int *match, int *exact)
3
Test that the keyword name contains only legal characters: A-Z,0-9,
hyphen, and underscore.
int fits_test_keyword / fftkey (char *keyname, > int *status)
4
Test that the keyword record contains only legal printable ASCII characters
int fits_test_record / fftrec (char *card, > int *status)
5
Parse a header keyword record, returning the value (as
a literal character string) and comment strings. If the keyword has no
value (columns 9-10 not equal to '= '), then a null value string is
returned and the comment string is set equal to column 9 - 80 of the
input string.
int fits_parse_value / ffpsvc
(char *card, > char *value, char *comment, int *status)
6
Construct an array indexed keyword name (ROOT + nnn).
This routine appends the sequence number to the root string to create
a keyword name (e.g., 'NAXIS' + 2 = 'NAXIS2')
int fits_make_keyn / ffkeyn
(char *keyroot, int value, > char *keyname, int *status)
7
Construct a sequence keyword name (n + ROOT).
This routine concatenates the sequence number to the front of the
root string to create a keyword name (e.g., 1 + 'CTYP' = '1CTYP')
int fits_make_nkey / ffnkey
(int value, char *keyroot, > char *keyname, int *status)
8
Determine the datatype of a keyword value string. This routine
parses the keyword value string to determine its datatype.
Returns 'C', 'L', 'I', 'F' or 'X', for character string, logical,
integer, floating point, or complex, respectively.
int fits_get_keytype / ffdtyp
(char *value, > char *dtype, int *status)
9
Parse the 'TFORM' binary table column format string.
This routine 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. See Chapter
9 for the allowed values for the returned typecode parameter. A
null pointer may be given for any output parameters that are not needed.
int fits_binary_tform / ffbnfm
(char *tform, > int *typecode, long *repeat, long *width,
int *status)
10
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, with the following
additional rules: integer columns that are between 1 and 4 characters
wide are defined to be short integers (code = TSHORT). Wider integer
columns are defined to be regular integers (code = TLONG). Similarly,
Fixed decimal point columns (with TFORM = 'Fw.d') are defined to
be single precision reals (code = TFLOAT) if w is between 1 and 7 characters
wide, inclusive. Wider 'F' columns will return a double precision
data code (= TDOUBLE). 'Ew.d' format columns will have datacode = TFLOAT,
and 'Dw.d' format columns will have datacode = TDOUBLE. A null
pointer may be given for any output parameters that are not needed.
int fits_ascii_tform / ffasfm
(char *tform, > int *typecode, long *width, int *decimals,
int *status)
11
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).
int fits_get_tbcol / ffgabc
(int tfields, char **tform, int space, > long *rowlen,
long *tbcol, int *status)
12
Parse a template header record and return a formatted 80-character string
suitable for appending to (or deleting from) a FITS header file.
This routine 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 fits_write_record, ffmcrd, or
fits_delete_key routines
to append or modify a FITS header record.
int fits_parse_template / ffgthd
(char *templt, > char *card, int *keytype, int *status)
The input templt 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. A legal FITS keyword name may only
contain the characters A-Z, 0-9, and '-' (minus sign) and
underscore. This routine will automatically convert any lowercase
characters to uppercase in the output string. 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).
-
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.
-
The COMMENT token is optional, but if present must be separated from
the VALUE token by at least one blank space and a '/' character.
-
One exception to the above rules is that if the first non-blank
character in the first 8 characters of 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 (without an equals sign between
them) 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 ffmnam routine which will change
the keyword name.
The keytype output parameter indicates how the returned CARD string
should be interpreted:
keytype interpretation
------- -------------------------------------------------
-2 Rename the keyword with name = the first 8 characters of CARD
to the new name given in characters 41 - 48 of CARD.
-1 delete the keyword with this name from the FITS header.
0 append the CARD string to the FITS header if the
keyword does not already exist, otherwise update
the keyword value and/or comment field if is already exists.
1 This is a HISTORY or COMMENT keyword; append it to the header
2 END record; do not explicitly write it to the FITS file.
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
13
Check that the Header fill bytes (if any) are all blank. These are the bytes
that may follow END keyword and before the beginning of data unit, or the end of
the HDU if there is no data unit.
int ffchfl(fitsfile *fptr, > int *status)
14
Check that the Data fill bytes (if any) are all zero (for IMAGE or BINARY Table HDU)
or all blanks (for ASCII table HDU). These file bytes may be
located after the last valid data byte in the HDU and before the physcal end of the HDU.
FITSIO Home