SXPAR
Name
SXPAR
Purpose
Obtain the value of a parameter in a FITS header
Calling Sequence
result = SXPAR( Hdr, Name, [ Abort, COUNT=, COMMENT =, /NoCONTINUE,
/SILENT ])
Inputs
Hdr = FITS header array, (e.g. as returned by READFITS)
string array, 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 a positive (non-zero) 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.
Optional Inputs
ABORT - string specifying that SXPAR 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, SXPAR will return quietly with COUNT = 0
(and !ERR = -1) if a keyword is not found.
Optional Input Keywords
/NOCONTINUE = If set, then continuation lines will not be read, even
if present in the header
/SILENT - Set this keyword to suppress warning messages about duplicate
keywords in the FITS header.
Optional Output Keywords
COUNT - Optional keyword to return a value equal to the number of
parameters found by SXPAR, integer scalar
COMMENT - Array of comments associated with the returned values
Outputs
Function value = value of parameter in header.
If parameter is double precision, floating, long or string,
the result is of that type. Apostrophes are stripped
from strings. If the parameter is logical, 1b is
returned for T, and 0b is returned for F.
If Name was of form 'keyword*' then a vector of values
are returned.
Side Effects
!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. The use of !ERR is deprecated, and
instead the COUNT keyword is preferred
If a keyword (except HISTORY or COMMENT) occurs more than once in a
header, a warning is given, and the *last* occurence is used.
Examples
Given a FITS header, h, return the values of all the NAXISi values
into a vector. Then place the history records into a string vector.
IDL> naxisi = sxpar( h ,'NAXIS*') ; Extract NAXISi value
IDL> history = sxpar( h, 'HISTORY' ) ; Extract HISTORY records
Procedure
The first 8 chacters of each element of Hdr are searched for a
match to Name. The value from the last 20 characters is returned.
An error occurs if there is no parameter with the given name.
If a numeric value has no decimal point it is returned as type
LONG. If it contains more than 8 numerals, or contains the
characters 'D' or 'E', then it is returned as type DOUBLE. Otherwise
it is returned as type FLOAT. Very large integer values, outside
the range of valid LONG, are returned as DOUBLE.
If the value is too long for one line, it may be continued on to the
the next input card, using the OGIP CONTINUE convention. For more info,
see 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.
Notes
The functions SXPAR() and FXPAR() are nearly identical, although
FXPAR() has slightly more sophisticated parsing, and additional keywords
to specify positions in the header to search (for speed), and to force
the output to a specified data type.. There is no
particular reason for having two nearly identical procedures, but
both are too widely used to drop either one.
Procedures Called
GETTOK(), VALID_NUM()
Modification History
DMS, May, 1983, STPAR Written.
D. Lindler Jan 90 added ABORT input parameter
J. Isensee Jul,90 added COUNT keyword
W. Thompson, Feb. 1992, added support for FITS complex values.
W. Thompson, May 1992, corrected problem with HISTORY/COMMENT/blank
keywords, and complex value error correction.
W. Landsman, November 1994, fix case where NAME is an empty string
W. Landsman, March 1995, Added COMMENT keyword, ability to read
values longer than 20 character
W. Landsman, July 1995, Removed /NOZERO from MAKE_ARRAY call
T. Beck May 1998, Return logical as type BYTE
W. Landsman May 1998, Make sure integer values are within range of LONG
W. Landsman Feb 1998, Recognize CONTINUE convention
W. Landsman Oct 1999, Recognize numbers such as 1E-10 as floating point
W. Landsman Jan 2000, Only accept integer N values when name = keywordN
W. Landsman Dec 2001, Optional /SILENT keyword to suppress warnings
W. Landsman/D. Finkbeiner Mar 2002 Make sure extracted vectors
of mixed data type are returned with the highest type.
W.Landsman Aug 2008 Use vector form of VALID_NUM()
W. Landsman Jul 2009 Eliminate internal recursive call
W. Landsman Apr 2012 Require vector numbers be greater than 0