dmreadpar

Synopsis

Create header keywords from a parameter file

Syntax

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

Description

Reads parameters from a CIAO-style parameter file and writes them to a file header as keywords. The input filename must end in ".par".

An optional template file may be used to filter, reorder, or rename the keywords in the output file header

Examples

Example 1

dmreadpar in.par out.fits case=upper

The input file in.par looks like:

origin,s,h,"ASC",,,"Source of FITS file"
creator,s,h,"cxc - Version DS 8.0",,,"tool that created this output"
ascdsver,s,h,"8.1.2",,,"ASCDS version number"
revision,i,h,4,,,""

so out.fits has these header keywords:

0001 ORIGIN               ASC                            String
Source of FITS file 
0002 CREATOR              cxc - Version DS 8.0           String
tool that created this output 
0003 ASCDSVER             8.1.2                          String
ASCDS version number 
0004 REVISION             4                              Int4
Processing version of data

Example 2

dmreadpar input='input_one.par,indir/input_two.par, input_three.par'
output='fileone.fits, filetwo.fits,/some/path/filethree.fits'
template='' case='upper' verbose='0' clobber='no' mode='ql'

This example uses the stack input feature to add header keywords from three parameter files to three different output 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		upper
verbose	integer		0	0	5
clobber	boolean		no

Detailed Parameter Descriptions

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

Input parameter file

The input parameter file, or stack of files (see "ahelp stack" for more information), which must end in '.par'.

The format is the same as a CIAO parameter file. The first three fields are required, but only the first, second, fourth and seventh fields are used. The first field contains the keyword name, the second field contains the data type (b = boolean, i = integer, r = real, s = string), the fourth field contains the value (in double quotes if a string), and the seventh field contains an optional comment (also in double quotes).

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

Name of file receiving new header keywords

Name of the existing FITS file to receive the new header keywords, with an optional extension in brackets, e.g. "filename.fits[GTI2]". By default, the tool writes to the header from the principal block (e.g. EVENTS, EVENTS_IMAGE), not the primary block. 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.

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=upper)

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.

Note that the FITS convention defines all keywords to be upper case and no longer than 8 characters. On account of this design, keywords of this length will be written to the output in uppercase, regardless of this parameter.

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 keywords in output file

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

Changes in CIAO 4.15

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

Bugs

There are no known bugs for this tool.