idlastro / FITS Binary Table Extensions I/O: FXHMODIFY

[Source code]

NAME
FXHMODIFY
PURPOSE
Modify a FITS header in a file on disk.
Explanation
Opens a FITS file, and adds or modifies a parameter in the FITS header.
Can be used for either the main header, or for an extension header. 
The modification is performed directly on the disk file.
Use
FXHMODIFY, FILENAME, NAME, VALUE, COMMENT
Inputs
FILENAME = String containing the name of the file to be read.
NAME    = Name of parameter, scalar string  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.
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
None.
Opt. Outputs
None.
Keywords
EXTENSION = Either the number of the FITS extension, starting with the
            first extension after the primary data unit being one; or a
            character string containing the value of EXTNAME to search
            for.  If not passed, then the primary FITS header is
            modified.           
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.
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.  If no errors are
          encountered, then a null string is returned.  In order to
          use this feature, ERRMSG must be defined first, e.g.
                ERRMSG = ''
                FXHMODIFY, ERRMSG=ERRMSG, ...
                IF ERRMSG NE '' THEN ...
NEW_HEADER = If defined and passed, then ignore NAME, VALUE,
             and COMMENT. Instead replace the old file header
             with the strarr given.
Calls
FXHREAD, FXPAR, FXADDPAR, BLKSHIFT
Restrictions
This routine can not be used to modify any of the keywords that control
the structure of the FITS file, e.g. BITPIX, NAXIS, PCOUNT, etc.  Doing
so could corrupt the readability of the FITS file.
Example
Modify the name 'OBJECT' keyword in the primary FITS header of a FITS 
file 'spec98.ccd' to contain the value 'test domeflat'
IDL> fxhmodify, 'spec98.ccd', 'OBJECT', 'test domeflat'
Side effects
If adding a record to the FITS header would increase the
number of 2880 byte records stored on disk, then the file is
enlarged before modification, unless the NOGROW keyword is passed.
Category
Data Handling, I/O, FITS, Generic.
Prev. Hist.
None.
Written
William Thompson, GSFC, 3 March 1994.
Modified
Version 1, William Thompson, GSFC, 3 March 1994.
Version 2, William Thompson, GSFC, 31 May 1994
        Added ERRMSG keyword.
Version 3, William Thompson, GSFC, 23 June 1994
        Modified so that ERRMSG is not touched if not defined.
Version 3.1 Wayne Landsman GSFC   17 March 2006
        Fix problem in BLKSHIFT call if primary header  extended
Version 3.2 W. Landsman 14 November 204 
        Allow for need for 64bit number of bytes
Version 4, William Thompson, GSFC, 22-Dec-2014
        Modified test for keyword EXTEND to only issue warning.
Version 5, Mats Löfdahl, ISP, 11-Oct-2017  
on     :
Version 5, 11-Oct-2017