idlastro / FITS I/O: SXPAR

[Source code]

NAME
SXPAR
PURPOSE
Obtain the value of a parameter in a FITS header
CALLING SEQUENCE
result = SXPAR( Hdr, Name, [ Abort, COUNT=, COMMENT =, /NoCONTINUE, 
                                  DUP=,   /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
DUP =  When the FITS keyword exists more than once in a header, set 
          DUP to a positive integer to specify which value is to be 
          read.   For example, set DUP = 2 to read the value of the 
          second appearance of a keyword in the header.    If DUP is not
          supplied, then by default, SXPAR() reads the *last* appearance and
          issues a warning.
MISSING = By default, this routine returns 0 when keyword values are
          not found.  This can be overridden by using the MISSING
          keyword, e.g. MISSING=-1.
/NAN    = If set, then return Not-a-Number (!values.f_nan) for missing
          values.  Ignored if keyword MISSING is present.
/NOCONTINUE = If set, then continuation lines will not be read, even
          if present in the header
/NULL   = If set, then return !NULL (undefined) for missing values.
          Ignored if MISSING or /NAN is present, or if earlier than IDL
          version 8.0.  If multiple values would be returned, then
          MISSING= or /NAN should be used instead of /NULL, making sure
          that the datatype is consistent with the non-missing values,
          e.g. MISSING='' for strings, MISSING=-1 for integers, or
          MISSING=-1.0 or /NAN for floating point.  /NAN should not be
          used if the datatype would otherwise be integer.
/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
IFOUND - Array of found keyword indicies when Name is of the form keyword*
       For example, one searches for 'TUNIT*' and the FITS header contains
       TUNIT1, TUNIT2, TUNIT4, and TUNIT6 then IFOUND woud be returned as
       [1,2,4,6].    Set to zero if Name is not of the form keyword*.
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 !ERR 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, and the DUP keyword is not supplied, then a warning is given, 
and the *last* occurrence 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 has a decimal point, and contains more than 8 numerals, or 
contains the character 'D', 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 LONG64.
If the value is too long for one line, it may be continued on to the
the next input card, using the 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.
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 functions, but
both are too widely used to drop either one.
PROCEDURES CALLED
cgErrorMsg(), 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
W. Landsman Apr 2014  Don't convert Long64 numbers to double
W. Landsman Nov 2014  Use cgErrorMsg rather than On_error,2
W. Landsman Dec 2014  Return Logical as IDL Boolean in IDL 8.4 or later
W. Landsman May 2015  Added IFound output keyword
J. Slavin Aug 2015 Allow for 72 character par values (fixed from 71)
W. Landsman Sep 2015  Added Missing, /NULL and /NaN keywords
W. Landsman Oct 2017   Added DUP keyword,  Needed to support distortion
                 table lookup parameters
W. Landsman Jan 2018 Return ULONG64 integer if LONG64 will overflow