Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  Libraries  >  ASTROLIB  >  FXPAR

FXPAR

FXPAR

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.

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

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


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

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



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