FMODCOMM (Jun95)              ftools.futils             FMODCOMM (Jun95)



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.
    
    
USAGE
    fmodcomm infile[ext#] template newtext
    
    
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.
    
    
    
PARAMETERS 
    
    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.
        
    
    template [string]
        Text  which  is  matched  against  all  header  records  of  the 
        specified keyword type to identify the line to be modified.
        
    
    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.
        
    
    (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.
        
    
    (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.
        
    
    
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)
    
    
       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
    
    
    
BUGS
    
    
SEE ALSO
    fthedit.  fv,  the interactive FITS file editor, can also be used to
    modify commentary keywords.