NAME

fmodhead -- Modifies an input FITS file by adding, modifying, or deleting keywords in the header of the primary array or an extension.

USAGE

fmodhead infile[ext#] tmpfil

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.

PARAMETERS

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.

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:

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.

EXAMPLES

1. Modify the myfile.fits file using a template file call htemp.dat.

                  
                       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.

BUGS

SEE ALSO

fthedit, ftcreate, ftlist. fv, the interactive FITS file editor, can also be used to modify header keywords.

CATEGORY

Jul92 ftools.futils