FXPAR
Name
FXPAR()
Purpose
Obtain the value of a parameter in a FITS header.
Explanation
The first 8 chacters of each element of HDR are searched for a match to
NAME. If the keyword is one of those allowed to take multiple values
("HISTORY", "COMMENT", or " " (blank)), then the value is taken
as the next 72 characters. Otherwise, it is assumed that the next
character is "=", and the value (and optional comment) is then parsed
from the last 71 characters. An error occurs if there is no parameter
with the given name.
If the value is too long for one line, it may be continued on to the
the next input card, using the CONTINUE Long String Keyword convention.
For more info, http://fits.gsfc.nasa.gov/registry/continue_keyword.html
Complex numbers are recognized as two numbers separated by one or more
space characters.
If a numeric value has no decimal point (or E or D) it is returned as
type LONG. If it contains more than 8 numerals, or contains the
character 'D', then it is returned as type DOUBLE. Otherwise it is
returned as type FLOAT. If an integer is too large to be stored as
type LONG, then it is returned as DOUBLE.
Calling Sequence
Result = FXPAR( HDR, NAME [, ABORT, COUNT=, COMMENT=, /NOCONTINUE ] )
Result = FXPAR(HEADER,'DATE') ;Finds the value of DATE
Result = FXPAR(HEADER,'NAXIS*') ;Returns array dimensions as
;vector
Required Inputs
HDR = FITS header string array (e.g. as returned by FXREAD). Each
element should have a length of 80 characters
NAME = String name of the parameter to return. If NAME is of the
form 'keyword*' then an array is returned containing values
of keywordN where N is an integer. The value of keywordN
will be placed in RESULT(N-1). The data type of RESULT will
be the type of the first valid match of keywordN
found, unless DATATYPE is given.
Optional Input
ABORT = String specifying that FXPAR should do a RETALL if a
parameter is not found. ABORT should contain a string to be
printed if the keyword parameter is not found. If not
supplied, FXPAR will return with a negative !err if a keyword
is not found.
DATATYPE = A scalar value, indicating the type of vector
data. All keywords will be cast to this type.
Default: based on first keyword.
Example: DATATYPE=0.0D (cast data to double precision)
START = A best-guess starting position of the sought-after
keyword in the header. If specified, then FXPAR
first searches for scalar keywords in the header in
the index range bounded by START-PRECHECK and
START+POSTCHECK. This can speed up keyword searches
in large headers. If the keyword is not found, then
FXPAR searches the entire header.
If not specified then the entire header is searched.
Searches of the form 'keyword*' also search the
entire header and ignore START.
Upon return START is changed to be the position of
the newly found keyword. Thus the best way to
search for a series of keywords is to search for
them in the order they appear in the header like
this:
START = 0L
P1 = FXPAR('P1', START=START)
P2 = FXPAR('P2', START=START)
PRECHECK = If START is specified, then PRECHECK is the number
of keywords preceding START to be searched.
Default: 5
POSTCHECK = If START is specified, then POSTCHECK is the number
of keywords after START to be searched.
Default: 20
Output
The returned value of the function is the value(s) associated with the
requested keyword in the header array.
If the parameter is complex, double precision, floating point, long or
string, then the result is of that type. Apostrophes are stripped from
strings. If the parameter is logical, 1 is returned for T, and 0 is
returned for F.
If NAME was of form 'keyword*' then a vector of values are returned.
Optional Input Keywords
/NOCONTINUE = If set, then continuation lines will not be read, even
if present in the header
Optional Output Keyword
COUNT = Optional keyword to return a value equal to the number of
parameters found by FXPAR.
COMMENTS= Array of comments associated with the returned values.
Procedure Calls
GETTOK(), VALID_NUM
Side Effects
The system variable !err is set to -1 if parameter not found, 0 for a
scalar value returned. If a vector is returned it is set to the number
of keyword matches found.
If a keyword occurs more than once in a header, a warning is given,
and the first occurence is used. However, if the keyword is "HISTORY",
"COMMENT", or " " (blank), then multiple values are returned.
Notes
The functions SXPAR() and FXPAR() are nearly identical, although
FXPAR() has slightly more sophisticated parsing. There is no
particular reason for having two nearly identical procedures, but
both are too widely used to drop either one.
Revision History
Version 1, William Thompson, GSFC, 12 April 1993.
Adapted from SXPAR
Version 2, William Thompson, GSFC, 14 October 1994
Modified to use VALID_NUM instead of STRNUMBER. Inserted
additional call to VALID_NUM to trap cases where character
strings did not contain quotation marks.
Version 3, William Thompson, GSFC, 22 December 1994
Fixed bug with blank keywords, following suggestion by Wayne
Landsman.
Version 4, Mons Morrison, LMSAL, 9-Jan-98
Made non-trailing ' for string tag just be a warning (not
a fatal error). It was needed because "sxaddpar" had an
error which did not write tags properly for long strings
(over 68 characters)
Version 5, Wayne Landsman GSFC, 29 May 1998
Fixed potential problem with overflow of LONG values
Version 6, Craig Markwardt, GSFC, 28 Jan 1998,
Added CONTINUE parsing
Version 7, Craig Markwardt, GSFC, 18 Nov 1999,
Added START, PRE/POSTCHECK keywords for better
performance
Version 8, Craig Markwardt, GSFC, 08 Oct 2003,
Added DATATYPE keyword to cast vector keywords type
Version 9, Paul Hick, 22 Oct 2003, Corrected bug (NHEADER-1)
Version 10, W. Landsman, GSFC 2 May 2012
Keywords of form "name_0" cound confuse vector extractions