|
|
|
|
|
SynopsisRetrieve information about a keyword from an input file Syntaxdmkeypar infile keyword [exist] [value] [rval] [ival] [sval] [bval] [datatype] [unit] [comment] [echo] [mode] DescriptionSearches 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 IntegersThis tool does not work on keywords of the datatype UInt4 (unsigned integers). The parameter interface assumes that all integers are signed. Example 1dmkeypar 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 2dmkeypar "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 3dmkeypar "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
Detailed Parameter DescriptionsParameter=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. BugsSee the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs. |
 |
The Chandra X-Ray
Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA. Email: cxcweb@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2004. All rights reserved. |
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}