NAME

ftkeypar - Read a FITS header keyword and write its value to the parameter file.

USAGE

ftkeypar infile[ext] keyword

DESCRIPTION

This task reads a header keyword in the input file and writes the value and comment string of the keyword to the ftkeypar parameter file. The contents of the parameter file can be viewed by executing 'plist ftkeypar' after running the ftkeypar task. This task is mainly designed for use by data processing scripts, to provide a convenient way to retrieve the value of a header keyword.

If the keyword does not exist, then the 'exist' parameter will be set = NO. If the keyword does exist, then the value is written twice in the parameter file in slightly different forms. The 'value' parameter gives the literal string value of the keyword, exactly as it appears in the keyword record. The data type of the keyword ('string', 'integer', 'real', or 'boolean') is given by the 'datatype' parameter. The interpreted data value of the keyword is then given by the 'svalue', 'ivalue', 'rvalue' or 'bvalue' parameter, depending on the data type of the keyword. The keyword comment string, if any, is written to the 'comment' parameter.

PARAMETERS

infile [filename]
Input file name and optional extension name or number enclosed in square brackets of the HDU containing the keyword (e.g., 'file.fits[0]' or file.fits[events]'). If an explicit HDU is not specified, then the first 'interesting' HDU in the input file will be opened, i.e., the first non-null image HDU, or the first table extension table that is not a GTI (Good Time Interval) extension.

keyword [string]
Name of keyword to read. The COMMENT and HISTORY keywords are not allowed because they generally are repeated multiple times in the header.

(exist = NO) [boolean, output]
Does the keyword exist? Set to NO if the keyword could not be read.

(value = "") [string, output]
The value of the keyword, exactly as it appears in the keyword record.

(datatype = "") [string, output]
Data type of the keyword. Allowed values are 'string', 'real', 'integer', or 'boolean'.

(rvalue = 0.) [real, output]
Value of the keyword, if datatype = real.

(ivalue = "") [integer, output]
Value of the keyword, if datatype = integer.

(svalue = "") [string, output]
Value of the keyword, if datatype = string.

(bvalue = NO) [boolean, output]
Value of the keyword, if datatype = boolean.

(comment = "") [string, output]
The keyword comment field, exactly as it appears in the keyword record

(chatter = 1) [integer, 0 - 5]
Controls the amount of informative text written to standard output. Chatter = 3 or higher will cause the keyword name, value, and comment to be written to stdout. Setting chatter = 5 will also generate detailed diagnostic output.

EXAMPLES

Note that when commands are issued on the Unix command line, strings containing special characters such as '[' or ']' must be enclosed in single or double quotes.

1. Retrieve the value of the NAXIS keyword in the primary array. The NAXIS keyword has an integer data type, so the keyword value will be written to the 'ivalue' output parameter.

      ftkeypar 'image.fits[0]' NAXIS
2. Retrieve the value of the OBJECT keyword. In this case, a specific HDU name or number is not specified, so the keyword will be read from the first 'interesting' HDU in the file (i.e., the first image HDU with NAXIS > 0, or the first table HDU that is not a 'good time interval' extension). The OBJECT keyword has a string data type, so the keyword value will be written to the 'svalue' output parameter. Setting the chatter parameter to 3 or higher also causes the keyword name, value, and comment string to be written to the standard output stream.

      ftkeypar infile.fits OBJECT chatter=3

SEE ALSO

ftlist, fthedit

The design of this task is based on the fkeypar task in the ftools package and the CXC dmkeypar task.

LAST MODIFIED

October 2010