SXPAR

      Obtain the value of a parameter in a FITS header

      result = SXPAR( Hdr, Name, [ Abort, COUNT=, COMMENT =, /NoCONTINUE  ])

      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 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.

       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.

       /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.

       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

       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.

       !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.

       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

       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,
       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.

       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.

       GETTOK(), VALID_NUM()

       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
       Converted to IDL V5.0, May 1998
       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.

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