Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/dmmakepar.html
AHELP for CIAO 4.16

dmmakepar

Context: Tools::Header

Synopsis

Write header keywords to a parameter file

Syntax

dmmakepar input output [template] [case] [verbose] [clobber]

Description

Writes file header keywords and the corresponding data types, values, and comments to an output parameter file. The units, if present, are added in brackets to the end of the comment. An optional template may be used to filter, reorder, or rename the keywords in the output file.

If the value or comment has a double quote (") in it, dmmakepar replaces it with a single quote (') and prints a warning. This needs to happen for the file to be useable by other tools, such as dmreadpar.

Note that if you run this tool with a template file and verbose greater than zero, you may see the message 'template keyword "mode" does not exist in file.' The output of the tool is unaffected and this warning may be ignored.


Examples

Example 1

dmmakepar in.fits out.par case=lower

The header of in.fits looks like:

0034 INSTRUME             ACIS          String       Instrument
0035 DETNAM               ACIS-7        String       Detector
0036 GRATING              NONE          String       Grating

so out.par looks like this:

instrume,s,h,"ACIS",,,"Instrument"
detnam,s,h,"ACIS-7",,,"Detector"
grating,s,h,"NONE",,,"Grating"

Example 2

dmmakepar "fileone.fits,filetwo.fits,/some/path/filethree.fits"
"out_one.par,outdir/out_two.par,out_three.par"

This example uses the stack input feature to create three parameter files from three input files. The number of input and output files must be equal.


Parameters

name type ftype def min max reqd stacks
input file input       yes yes
output file output       yes yes
template file input         yes
case string   lower        
verbose integer   0 0 5    
clobber boolean   no        

Detailed Parameter Descriptions

Parameter=input (file required filetype=input stacks=yes)

Input file

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]". By default, the tool reads the header from the principal block (e.g. EVENTS, EVENTS_IMAGE), not the primary block.

Parameter=output (file required filetype=output stacks=yes)

Output parameter file or STDOUT

Name of the text file receiving parameter values, which must end in '.par'. When using a stack of input files, there must be an equal number of output filenames given.

Parameter=template (file filetype=input stacks=yes)

Template file

The template file is formatted as a CIAO parameter file and must end in '.par'. A stack of files may be used. If "NONE", all header keywords will be written to the output file. If a template file is given, only keywords which appear both in the file header and the template file will be written to the output file. If an empty or missing template file is specified, the tool will exit with an error and create an empty output file.

A short template file might look like:

CONTENT,s,h,"EVT1",,,"NEWNAME"
TELESCOP,s,h,"CHANDRA",,,""
INSTRUME,s,h,"ACIS",,,""
DETNAM,s,h,"ACIS-7",,,""
GRATING,s,h,"NONE",,,""
OBJECT,s,h,"0235+164",,,""

The first three fields are required, but only the first and last fields are used. The first field contains the keyword name and the last field contains an optional new name for the keyword in the output file. If the last field is "", the name of the keyword is the same in the output file as in the input file.

Parameter=case (string default=lower)

Output keyword case

Possibilities are "same", "upper", and "lower". If "same", the case of keywords in the input file will be preserved in output file. Otherwise, the case is forced to upper or lower.

Parameter=verbose (integer default=0 min=0 max=5)

Verbose level

Reports the input and output filenames, as well as any warnings.

Parameter=clobber (boolean default=no)

Overwrite existing output file

Specifies whether or not to overwrite an existing output file. If "no" and the output file exists, the tool exits with an error.


Bugs

There are no known bugs for this tool.

See Also

concept
parameter
tools::core
dmdiff
tools::header
dmhedit, dmhistory, dmkeypar, dmreadpar
tools::parameter
paccess, pdump, pget, pline, plist, pquery, pset, punlearn