idlastro / FITS Binary Table Extensions I/O: FXADDPAR

[Source code]

NAME
FXADDPAR
Purpose
Add or modify a parameter in a FITS header array.
Explanation
This version of FXADDPAR will write string values longer than 68 
characters using the FITS continuation convention described at 
http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.html
Use
FXADDPAR, HEADER, NAME, VALUE, COMMENT
Inputs
HEADER  = String array containing FITS header.  The maximum string
          length must be equal to 80.  If not defined, then FXADDPAR
          will create an empty FITS header array.
NAME    = Name of parameter.  If NAME is already in the header the
          value and possibly comment fields are modified. Otherwise a
          new record is added to the header.  If NAME is equal to
          either "COMMENT" or "HISTORY" then the value will be added to
          the record without replacement.  In this case the comment
          parameter is ignored.
VALUE   = Value for parameter.  The value expression must be of the
          correct type, e.g. integer, floating or string.
          String values of 'T' or 'F' are considered logical
          values unless the /NOLOGICAL keyword is set.  If the value is
          a string and is "long" (more than 69 characters), then it 
          may be continued over more than one line using the OGIP 
          CONTINUE standard.
Opt. Inputs
COMMENT = String field.  The '/' is added by this routine.  Added
          starting in position 31.  If not supplied, or set equal to ''
          (the null string), then any previous comment field in the
          header for that keyword is retained (when found).
Outputs
HEADER  = Updated header array.
Opt. Outputs
None.
Keywords
BEFORE  = Keyword string name.  The parameter will be placed before the
          location of this keyword.  For example, if BEFORE='HISTORY'
          then the parameter will be placed before the first history
          location.  This applies only when adding a new keyword;
          keywords already in the header are kept in the same position.
AFTER   = Same as BEFORE, but the parameter will be placed after the
          location of this keyword.  This keyword takes precedence over
          BEFORE.
FORMAT  = Specifies FORTRAN-like format for parameter, e.g. "F7.3".  A
          scalar string should be used.  For complex numbers the format
          should be defined so that it can be applied separately to the
          real and imaginary parts.  If not supplied, then the IDL
          default formatting is used, except that double precision is
          given a format of G19.12.
/NOCONTINUE = By default, FXADDPAR will break strings longer than 68 
         characters into multiple lines using the continuation
         convention.    If this keyword is set, then the line will
         instead be truncated to 68 characters.    This was the default
         behaviour of FXADDPAR prior to December 1999.  
NOLOGICAL = If set, then the values 'T' and 'F' are not interpreted as
         logical values, and are simply added without interpretation.
/NULL   = If set, then keywords with values which are undefined, or
          which have non-finite values (such as NaN, Not-a-Number) are
          stored in the header without a value, such as
                MYKEYWD =                      /My comment
MISSING = A value which signals that data with this value should be
          considered missing.  For example, the statement
                FXADDPAR, HEADER, 'MYKEYWD', -999, MISSING=-999
          would result in the valueless line described above for the
          /NULL keyword.  Setting MISSING to a value implies /NULL.
          Cannot be used with string or complex values.
 ERRMSG   = If defined and passed, then any error messages will be
            returned to the user in this parameter rather than
            depending on the MESSAGE routine in IDL, e.g.
                 ERRMSG = ''
                 FXADDPAR, ERRMSG=ERRMSG, ...
                 IF ERRMSG NE '' THEN ...
Calls
DETABIFY(), FXPAR(), FXPARPOS()
Common
None.
Restrictions
Warning -- Parameters and names are not checked against valid FITS
parameter names, values and types.
The required FITS keywords SIMPLE (or XTENSION), BITPIX, NAXIS, NAXIS1,
NAXIS2, etc., must be entered in order.  The actual values of these
keywords are not checked for legality and consistency, however.
Side effects
All HISTORY records are inserted in order at the end of the header.
All COMMENT records are also inserted in order at the end of the
header, but before the HISTORY records.  The BEFORE and AFTER keywords
can override this.
All records with no keyword (blank) are inserted in order at the end of
the header, but before the COMMENT and HISTORY records.  The BEFORE and
AFTER keywords can override this.
All other records are inserted before any of the HISTORY, COMMENT, or
"blank" records.  The BEFORE and AFTER keywords can override this.
String values longer than 68 characters will be split into multiple
lines using the OGIP CONTINUE convention, unless the /NOCONTINUE keyword
is set.    For a description of the CONTINUE convention see    
http://fits.gsfc.nasa.gov/registry/continue_keyword.html
Category
Data Handling, I/O, FITS, Generic.
Prev. Hist.
William Thompson, Jan 1992, from SXADDPAR by D. Lindler and J. Isensee.
Differences include:
        * LOCATION parameter replaced with keywords BEFORE and AFTER.
        * Support for COMMENT and "blank" FITS keywords.
        * Better support for standard FITS formatting of string and
          complex values.
        * Built-in knowledge of the proper position of required
          keywords in FITS (although not necessarily SDAS/Geis) primary
          headers, and in TABLE and BINTABLE extension headers.
William Thompson, May 1992, fixed bug when extending length of header,
and new record is COMMENT, HISTORY, or blank.
Written
William Thompson, GSFC, January 1992.
Modified
Version 1, William Thompson, GSFC, 12 April 1993.
        Incorporated into CDS library.
Version 2, William Thompson, GSFC, 5 September 1997
        Fixed bug replacing strings that contain "/" character--it
        interpreted the following characters as a comment.
Version 3, Craig Markwardt, GSFC,  December 1997
        Allow long values to extend over multiple lines
 Version 4, D. Lindler, March 2000, modified to use capital E instead
         of a lower case e for exponential format.
Version 4.1 W. Landsman April 2000, make user-supplied format uppercase
Version 4.2 W. Landsman July 2002, positioning of EXTEND keyword
Version 5, 23-April-2007, William Thompson, GSFC
Version 6, 02-Aug-2007, WTT, bug fix for OGIP long lines
Version 6.1, 10-Feb-2009, W. Landsman, increase default format precision
Version 6.2  30-Sep-2009, W. Landsman, added /NOLOGICAL keyword
Version 7, 13-Aug-2015, William Thompson, allow null values
        Add keywords /NULL, MISSING.  Catch non-finite values (e.g. NaN)
Version 7.1, 22-Sep-2015, W. Thompson, No slash if null & no comment
Version
Version 7.1, 22-Sep-2015