.help fmodhead Jul92 ftools.futils
.ih
NAME
fmodhead --  Modifies an input FITS file by adding, modifying, or deleting 
keywords in the header of the primary array or an extension.
.ih
USAGE
fmodhead infile[ext#] tmpfil
.ih
DESCRIPTION
This  task modifies the header of the input FITS file based on 
instructions given in an input ASCII template file.   The template
file can specify any combination of a) new keywords to be added to the
header, b) new values or comment strings for existing keywords in the
header, or c) names of keywords to be deleted from the header.

.ih 
PARAMETERS 
.le
.ls infile [FITS file name] 
The name (including
extension number in square brackets or after a +) of the input FITS
file which is to be modified.  The user must have write privilege to
this file. If no extension is specified, extension number 1 (not the
primary extension) is the default.

.le 
.ls tmpfil [file name]
The name  of  the  ASCII  template file 
which specifies the keywords that are to be added, modified, or
deleted in the FITS header.
Each line of the template file defines one header keyword operation
except that blank lines or lines beginning with # are ignored.
Each template file line should generally  contain three parts, or tokens:
(1) the KEYNAME, (2) the VALUE, and (3) the COMMENT string.
If a keyword with the specified KEYNAME already exists in the FITS header
then the value and comment strings will be  updated with the new values
specified in the template file.  If the keyword does not already exist, or
if the KEYNAME = COMMENT or HISTORY
then a new keyword is appended to the FITS header.

The template file must adhere to the following format rules:

.ls
The KEYNAME token must begin in columns 1-8 of the line and be a
maximum  of 8 characters long.  If the first 8 characters of the  line
are blank then the remainder of the line is considered to be a FITS
comment (with a blank keyword name).  A legal FITS keyword name may
only contain the characters A-Z, 0-9, and '-' (minus sign) and '_'
(underscore).  This task will automatically convert any lowercase
characters to uppercase in the output file.  If KEYNAME = 'COMMENT' or
'HISTORY' then the remainder of the line is considered to be a FITS
COMMENT or HISTORY record, respectively.

If the keyword name token is proceeded by a minus sign (-) and there is
no VALUE token, then it is
interpreted to be the name of a keyword to be deleted from
the FITS header.  Note that FITSIO does not support the deletion of
blank FITS blocks from FITS headers.

The VALUE token must be separated from the KEYNAME token by one or
more
spaces and/or an '=' character.  The datatype of the VALUE
token (numeric, logical, or character string) is implicitly
determined by the format in the template file 
and  the output FITS header record is formatted
accordingly.  Logical keyword values are represented by T or F (not enclosed
in quote characters).  The value token may be forced to be interpreted
as a string (e.g., if it is a string of numeric digits) by
enclosing it in single quotes.  If the KEYWORD token is proceed by a minus
sign (-) and a value token is specified, the original keyword name is
changed to VALUE, while the keyword value and comment are unchanged.

The COMMENT token is optional, but if present must be separated from
the VALUE token by at least one blank space.  A leading '/'
character may be used to mark the beginning of the comment
field, otherwise the comment field begins with the first
non-blank character following the value token.
.le
.le
.ih
EXAMPLES
1. Modify the myfile.fits file using a template file call htemp.dat.

.nf

     ft> fmodhead myfile.fits htemp.dat

     where the template file contains the following lines of text:

     EXPOSURE 300.0 / Value of exposure changed
     - BACKFILE 
     # Ignore this line - this is a comment in the template file
     Comment This header was modified with the fmodhead task

  This will add (or modify the value if it already exists) the EXPOSURE
  keyword, will delete the BACKFILE keyword, and append a new COMMENT
  keyword.

.fi
.ih
BUGS
.ih
SEE ALSO
fthedit, ftcreate, ftlist. fv, the interactive FITS file
editor, can also be used to modify header keywords.
.endhelp
