idlastro / FITS I/O: SXADDPAR

[Source code]

NAME
SXADDPAR
PURPOSE
Add or modify a parameter in a FITS header array.
CALLING SEQUENCE
SXADDPAR, Header, Name, Value, [ Comment,  Location, /SaveComment, 
                        BEFORE =, AFTER = , FORMAT= , /PDU
                        /SAVECOMMENT, Missing=, /Null
INPUTS
Header = String array containing FITS header.    The
        length of each element must be 80 characters.    If not 
        defined, then SXADDPAR 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 'COMMENT'
        or 'HISTORY' or a blank string then the value will be added to 
        the record without replacement.  For these cases, 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.
OPTIONAL INPUT PARAMETERS
Comment = String field.  The '/' is added by this routine.  Added 
        starting in position 31.    If not supplied, or set equal to 
        '', or /SAVECOMMENT is set, then the previous comment field is 
        retained (when found) 
Location = Keyword string name.  The parameter will be placed before the
        location of this keyword.    This parameter is identical to
        the BEFORE keyword and is kept only for consistency with
        earlier versions of SXADDPAR.
OPTIONAL INPUT KEYWORD PARAMETERS
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 default is
        'G19.12' for double precision, and 'G14.7' for floating point.
/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.
/PDU    = specifies keyword is to be added to the primary data unit
        header. If it already exists, it's current value is updated in
        the current position and it is not moved.
/SAVECOMMENT = if set, then any existing comment is retained, i.e. the
        COMMENT parameter only has effect if the keyword did not 
        previously exist in the header.
OUTPUTS
Header = updated FITS header array.
EXAMPLE
Add a keyword 'TELESCOP' with the value 'KPNO-4m' and comment 'Name
of Telescope' to an existing FITS header h.
IDL> sxaddpar, h, 'TELESCOPE','KPNO-4m','Name of Telescope'
NOTES
The functions SXADDPAR() and FXADDPAR() are nearly identical, with the
major difference being that FXADDPAR forces required FITS keywords
BITPIX, NAXISi, EXTEND, PCOUNT, GCOUNT to appear in the required order
in the header, and FXADDPAR supports the OGIP LongString convention.   
There is no particular reason for having two nearly identical 
procedures, but both are too widely used to drop either one.
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
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.
RESTRICTIONS
Warning -- Parameters and names are not checked
        against valid FITS parameter names, values and types.
MODIFICATION HISTORY
DMS, RSI, July, 1983.
D. Lindler Oct. 86  Added longer string value capability
Added Format keyword, J. Isensee, July, 1990
Added keywords BEFORE and AFTER. K. Venkatakrishna, May '92
Pad string values to at least 8 characters   W. Landsman  April 94
Aug 95: added /PDU option and changed routine to update last occurrence
        of an existing keyword (the one SXPAR reads) instead of the
        first occurrence.
Comment for string data can start after column 32 W. Landsman June 97
Make sure closing quote supplied with string value  W. Landsman  June 98
Increase precision of default formatting of double precision floating
        point values.   C. Gehman, JPL  September 1998
Mar 2000, D. Lindler, Modified to use capital E instead of lower case
        e for exponential formats.
Apr 2000, Make user-supplied format upper-case  W. Landsman 
Oct 2001, Treat COMMENT or blank string like HISTORY keyword W. Landsman
Jan 2002, Allow BEFORE, AFTER to apply to COMMENT keywords W. Landsman
June 2003, Added SAVECOMMENT keyword    W. Landsman
Jan 2004, If END is missing, then add it at the end W. Landsman
May 2005 Fix SAVECOMMENT error with non-string values W. Landsman
Oct 2005 Jan 2004 change made SXADDPAR fail for empty strings W.L.
May 2011 Fix problem with slashes in string values W.L. 
Aug 2013 Only use keyword_set for binary keywords W. L. 
Sep 2015 Added NULL and MISSING keywords W.L.
Sep 2016 Allow writing of byte or Boolean variables  W.L.