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