/ ciao4.15 / ahelp / dmkeypar.html

Jump to: Description · Examples · Parameters · Changes in CIAO 4.15 · Bugs · See Also

AHELP for CIAO 4.15

dmkeypar

Synopsis

Retrieve information about a keyword from an input file

Syntax

dmkeypar infile keyword [exist] [value] [rval] [ival] [sval] [bval]
[datatype] [unit] [comment] [echo] [mode]

Description

Searches the file header for the requested keyword. If the keyword exists, dmkeypar returns the value, datatype, unit, and comment associated with it. By default, this information is stored in the parameter file and may be accessed with any of the parameter tools, such as plist and pget. If "echo=yes", the value alone is also printed to the screen.

dmkeypar will exit with an error message if the user specifies an unreadable file, a non-existent keyword, or COMMENT or HISTORY as the keyword. In each of these cases, the "exist" parameter is set to "no" and all other parameters are reset to the default values. COMMENT and HISTORY are special keywords that can occur multiple times in a file, so it is not possible for dmkeypar to know which one specifically is being requested.

It is also possible to use this tool to get the value from a column in the FITS file for a single row. In this case, the "keyword" parameter is the name of the column, and the row must be specified in the "infile" parameter with the "[#row nn]" DM syntax (where nn is the row number). If a vector column is specified, only the first value in the pair is returned; to avoid problems, use the specific component, e.g. "y" instead of "sky". This functionality is illustrated in the "Examples" section.

Unsigned Integers

This tool does not work on keywords of the datatype UInt4 (unsigned integers). The parameter interface assumes that all integers are signed.

Examples

Example 1

dmkeypar acis_evt2.fits mission

Retrieve the information for the keyword "mission" from the input file "acis_evt2.fits". Since the results are stored in the parameter file they can be accessed using the parameter tools. Here we use pget to list the value and comment for the keyword:

unix% pget dmkeypar value
AXAF
unix% pget dmkeypar comment
Mission

The full information can be listed using pline:

unix% pline dmkeypar
infile='acisf01703N002_short.fits' keyword='mission' echo='no' 
exist='yes' value='AXAF' rval='0' ival='0' sval='AXAF' bval='no'
datatype='string' unit='' comment='Mission' mode='ql'

Example 2

dmkeypar "acis_evt2.fits[3]" CCD_ID echo+

Retrieve the value of the keyword "CCD_ID" from the third block of the input file. This example uses the "echo=yes" option to print the results to the screen:

unix% dmkeypar "acis_evt2.fits[3]" CCD_ID echo=yes
7

Example 3

dmkeypar "indir/acisf01703N002_short.fits[#row=100]" EXPNO

dmkeypar is used to get the value from row 100 of the column EXPNO. The parameter file for dmkeypar can be examined - using pget and pline - to find the value:

unix% pget dmkeypar value
280
unix% pline dmkeypar
infile='indir/acisf01703N002_short.fits[#row=100]' keyword='EXPNO'
echo='no' exist='yes' value='280' rval='0' ival='280' sval=''
bval='no' datatype='integer' unit='' comment='' mode='ql'

Parameters

name	type	ftype	def	min	reqd
infile	file	input			yes
keyword	string				yes
echo	boolean		no		no
exist	boolean		no		no
value	string				no
rval	real				no
ival	integer				no
sval	string				no
bval	boolean		no		no
datatype	string		null	string\|real\|integer\|boolean\|null	no
unit	string				no
comment	string				no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input filename

Input FITS file with an optional extension in brackets, e.g. "filename.fits[GTI2]". By default, the tool reads the header from the principal block (e.g. EVENTS, EVENTS_IMAGE), not the primary block.

Parameter=keyword (string required)

Keyword to retrieve

COMMENT and HISTORY are invalid keywords, as explained in the DESCRIPTION. If using the tool to get information from a column and row, the column name is given in this parameter.

Parameter=echo (boolean not required default=no)

Echo value to screen?

Determines if the retrieved value is printed to the screen in addition to being stored in the parameter file.

Parameter=exist (boolean not required default=no)

Keyword existance

Set to "yes" if the keyword exists in the input file and "no" if it doesn't. Also set to "no" if the user attempts to search for a COMMENT or HISTORY keyword.

Parameter=value (string not required)

A pointer to the actual value of the keyword

This is a redirection pointer to the parameter in which the keyword value is stored, either rval, ival, sval, or bval.

Parameter=rval (real not required default=)

Keyword value -- real

If the value of the retrieved keyword is a real, it is stored in this parameter.

Parameter=ival (integer not required default=)

Keyword value -- integer

If the value of the retrieved keyword is an integer, it is stored in this parameter.

Parameter=sval (string not required)

Keyword value -- string

If the value of the retrieved keyword is a string, it is stored in this parameter.

Parameter=bval (boolean not required default=no)

Keyword value -- boolean

If the value of the retrieved keyword is a boolean, it is stored in this parameter.

Parameter=datatype (string not required default=null min=string|real|integer|boolean|null)

Keyword datatype

The datatype of the specified keyword. Possibilities are "string", "real", "integer", "boolean", or "null".

Parameter=unit (string not required)

Keyword unit

If the keyword has a unit associated with it (e.g. seconds, pixels), the information is stored in this parameter.

Parameter=comment (string not required)

Keyword comment

The comment associated with a keyword, if present.

Changes in CIAO 4.15

The tool name is now lowercase in any error or warning messages

Bugs

Caveats

Unsigned long integer values: Integers stored in parameter files are interpreted as signed 32-bit integers. Unsigned long integers which overflow the sign-bit are stored as negative values.