>  Docs Center  >  Libraries  >  ASTROLIB  >  SXPAR

SXPAR

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


      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



© 2019 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us