Edit datamodel file headers
dmhedit infile filelist operation key value [datatype] [unit] [comment] [verbose]
Edits 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 gzipped files.
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:
- "#add" : add a new keyword at the end of the block header
- "#delete" : remove an existing keyword
- "#del" : same as "#delete"
- "#add after KEYNAME" : add a new keyword after an existing one
Other lines beginning with a pound sign are treated as a comment. There can be no blank lines in the edit list file or the tool will complain. There can 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.
dmhedit 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.
dmhedit 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.
dmhedit 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.
dmhedit 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.
dmhedit 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).
dmhedit 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
In this example since the keyword 'GAUSS.POWER' is longer than 8 character and contains special characters, the period, it is written using a pair of DSVAL and DSTYPE keywords.
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input stacks=yes)
Input file, or stack of files (see "ahelp stack" for more information), with an optional extension in brackets, e.g. "filename.fits[GTI2]". The same header edits are applied to all files in the stack.
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.
Parameter=value (string required)
Value of the keyword that is being modified
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/'".
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=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 long 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.
Unit of the value
If there is a unit associated with the keyword value, it is input via this parameter.
A description of the keyword or other related comment.
Parameter=verbose (integer default=0 min=0 max=5)
Reports the input filenames and the key to be changed, as well as any warnings.
Changes in CIAO 4.11
Improved error checking when attempting to modify read-only files. This includes file-system level write permissions, attempting to modify compressed files, attempting to modify non-standard files (eg pipes like STDIN and URLs using http:// or ftp://).
- Quotes removed from string values
When trying to edit or add a keyword, dmhedit will remove quotation marks, ", from string values.