.help fmodcomm Jun95 ftools.futils
.ih
NAME
fmodcomm --  Operates upon an input FITS file by modifying the text of
commentary keywords in the header of the primary array or an extension.
.ih
USAGE
fmodcomm infile[ext#] template newtext
.ih
DESCRIPTION
This task modifies the text in any of the three commentary keywords
(COMMENT, HISTORY, or <blank>) in the header of the input FITS file.  A
unique substring (plus its keyword type) specifies the particular line
to be modified. If two or more lines are identical, then a match to the
first line can be forced by setting the "firstmatch" parameter.  New
text provided by the user replaces the original text. If the new text
is too long to fit on a single line, additional lines of the same
keyword type are inserted. New text (up to 99 lines) can be read in
from a file via the @filename convention.

.ih 
PARAMETERS 
.le
.ls infile [string] 
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.

.le 
.ls template [string]
Text which is matched against all header records of the specified
keyword type to identify the line to be modified.

.le 
.ls newtext [string]
The text which is put in place of the *entire* header line matched by
template and keytype. If longer than 70 characters (up to 350), extra
header records of the same keyword type are inserted as necessary.  If
@filename is given instead, up to 99 lines of text will be read from 
filename and replace the template line.

.le 
.ls (keytype="COMMENT") [string] 
Specifies which of the three commentary keywords should be acted upon
[COMMENT, HISTORY, or <blank>].  Only the first letter is required, case 
insensitive.

.le 
.ls (firstmatch = no) [boolean]
If identical header lines exist, then action can be forced by setting
this to yes;  the first matching line will then be acted upon.

.le
.le
.ih
EXAMPLES
1. Modify the myfile.fits file which contains the following record
   in the primary array header to correct the date to 1995:

   COMMENT   Data derived from AJ 109, 1697 (1994)

.nf

   ft> fmodcomm myfile.fits+0 "AJ" "Data derived from AJ 109, 1697 (1995)"

  This will find a COMMENT line in the primary array header containing
  the substring "AJ" and replace that line with "Data derived....(1995)"

2. Modify the myfile.fits file which contains the following records in 
   the first extension so as to sandwich additional text between them:

   HISTORY   Input PHA spectrum file = SCRABK.PHA
   HISTORY   TASK: FEXTRACT on FILENAME: crabk.fits

   ft> fmodcomm myfile.fits+1 "PHA spec" @tmp keytype=HISTORY

   where the file named tmp contains:

   Input PHA spectrum file = SCRABK.PHA
   This is an extra line of text
   So is this one
   And finally this one

   yields:

   HISTORY   Input PHA spectrum file = SCRABK.PHA
   HISTORY   This is an extra line of text
   HISTORY   So is this one
   HISTORY   And finally this one
   HISTORY   TASK: FEXTRACT on FILENAME: crabk.fits

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