|
|
|
|
|
SynopsisEdit datamodel file headers Syntaxdmhedit infile filelist operation key value [datatype] [unit] [comment] [verbose] DescriptionEdits the header of a file in place, modifying the original file. There are two ways to use dmhedit: specifying parameters on the command line to change one keyword or with an ASCII edit list file to modify several keywords at once. The syntax for each method is illustrated in the EXAMPLES. The Data Model does not support writing to gzip'ed files, even if the CIAO installation was configured with gzip support. General write support for gzip'ed files will not be added anytime in the near future, so users should gunzip their files first if it is necessary to modify them. Format for the edit list file:The edit list file can contain two kinds of lines, control lines and edit lines. The control lines, which must begin with a pound sign (#), specify what to do with the edit lines that follow it. The valid control lines are:
Anything other line beginning with a pound sign is treated as a comment. Note that there may not be any blank lines in the edit list file or the tool will complain; also, there may not be a space between the pound sign and the command in the control lines. A control line applies to all following commands until a new control line is encountered. Each edit line has the format KEYNAME = value / [unit] comment The entries must be space delimited, tabs are not allowed. The unit and comment may be omitted; if both are omitted, the slash following the value should be omitted as well. If the value is a string value, it should be included in single quotes. String values that contain slashes:Any string value that contains a forward slash ("/") must be enclosed in single quotes within double quotes when setting the parameter, i.e. value="'/this/is/a/string/'". Adding comment keywords:The tool can also add comments to the header (i.e. COMMENT and HISTORY keywords). In this case, only the "key" and "value" parameters are used, with the latter containing the comment text. Since comments do not have unique key names, it is not possible to delete existing ones. Users should be aware that dmhedit can also set structural FITS keywords which are normally hidden by the Data Model. However, this is not recommended and can easily corrupt files. Example 1dmhedit in.fits filelist=none operation=add key=LIVETIME value=123.3 datatype=indef This is an example of using dmhedit to update a single keyword. The default block of the input file is modified to update the keyword LIVETIME with value 123.3 using the existing datatype. Example 2dmhedit in.fits none add NEWTIME "123.3 / [s] New time" datatype=double Single key mode is again used to add the keyword NEWTIME with double value 123.3, units of seconds, and the comment "New time". This example shows how the value, unit, and comment may all be included in the "value" parameter. Example 3dmhedit in.fits none add LIVETIME 'some string value' datatype=string The existing keyword LIVETIME (which has a double datatype) is updated with a string value. Example 4dmhedit in.fits none operation="add after OBJECT" key=AGNCLASS value='Type 2 Seyfert' datatype=string A new keyword, AGNCLASS, is added after the OBJECT key. Example 5dmhedit in.fits none operation="move after DEC_NOM" key=RA_NOM The order of RA_NOM and DEC_NOM is switched via the "move after KEYNAME" operation. Since RA_NOM is an existing keyword, it is not necessary to supply a value, datatype, etc. Example 6dmhedit in.fits none add GAINFILE "'/path/name/gain.fits'" unit='' comment='Gain file' This shows the correct syntax when working with a string with forward slashes in it (in this case, a directory path). Example 7dmhedit in.fits edit.list dmhedit is used in edit list mode to make multiple changes with one command. The file "edit.list" might look like: #add LIVETIME = 142.3 / [s] Live time INSTRUME = 'HRC-S' #delete PHAMAX #add GAUSS.POWER = -1.8 / Power law index Parameters
Detailed Parameter DescriptionsParameter=infile (file required filetype=input stacks=yes)Input dataset Input FITS file, or stack of files (see "ahelp stack" for more information), with an optional FITS extension in brackets, e.g. "filename.fits[GTI2]". The same header edits are applied to all files in the stack. The file cannot be gzipped, even if the CIAO installation was configured with gzip support. Parameter=filelist (file required stacks=no)An ASCII edit list file A file containing control and edit lines, see the full explanation in the DESCRIPTION. If set to "none" or empty, dmhedit uses the " operation", "key", and "value" parameter. If a filelist is given and the other parameters are specified, the filelist takes precedence. Parameter=operation (string required)Add/change or delete the key Specifies what operation should be performed on the given keyword. Valid options are "add" and "delete". Use the "add" operation to update an existing key. Parameter=key (string required)Keyword to change Name of the new keyword to add or an existing keyword to edit or delete. The syntax value="value / [unit] comment" may be used to provide the value, unit, and comment at the same time (e.g. value="45.89 / [ks] New time"). Parameter=value (string required)Value of the keyword that is being modified Remember that string values which contain forwarded slashes must be enclosed in single quotes within double quotes when setting the parameter, i.e. value="'/this/is/a/string/'". Parameter=datatype (string default=indef)Datatype of the keyword value The datatype of the value when the "add" operation is being used. Possibilities are "string", "double", "float", "long", "short", "ulong", "ushort", "boolean", or "indef". If "datatype=indef" and the keyword exists, the datatype will be set to that of the existing keyword. If "datatype" is set to anything else or a new key is being added, the tool will attempt to write the keyword using the specified datatype. Any value can be written as a string, while only type-specific numeric values can be written using the numeric datatypes. If the value is a number and contains a decimal point, it will be written as a double; otherwise, numbers are written as short integers. If the value is not a number, it will be written as a string. Allowed values to update a boolean keyword are "T", "F", "TRUE", and "FALSE", all case-insensitive. Parameter=unit (string)Unit of the value If there is a unit associated with the keyword value, it is input via this parameter. Parameter=verbose (integer default=0 min=0 max=5)Verbose level Reports the input filenames and the key to be changed, as well as any warnings. 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}