idlastro / FITS Binary Table Extensions I/O: FXPAR

[Source code]

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.
If a keyword is in the header and has no value, then the default
missing value is returned as explained below.  This can be
distinguished from the case where the keyword is not found by the fact
that COUNT=0 in that case, while existing keywords without a value will
be returned with COUNT=1 or more.
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.
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
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
/NOCONTINUE = If set, then continuation lines will not be read, even
          if present in the header
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.
/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.
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.    This use of !ERR is deprecated.
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" could confuse vector extractions
Version 11 W. Landsman, GSFC 24 Apr 2014
        Don't convert LONG64 numbers to to double precision
Version 12, William Thompson, 13-Aug-2014
        Add keywords MISSING, /NAN, and /NULL
         Version 13, W. Landsman 25-Jan-2018
                         Return ULONG64 integer if LONG64 would overflow