FXPAR()

       Obtain the value of a parameter in a FITS header.

       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 OGIP CONTINUE convention.  For more info,
       http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.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.

       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

       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.

       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

       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.

       /NOCONTINUE = If set, then continuation lines will not be read, even
                 if present in the header

       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.

       GETTOK(), VALID_NUM

       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.

       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.

       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)

[Home Page] [Software, Documentation] [IDL Documentation] [Quick Reference] [Feedback]