Last modified: December 2022

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

dmhistory

Context: Tools::Header

Synopsis

Extracts the tool history from the file header

Syntax

dmhistory  infile tool [outfile] [expand] [action] [clobber] [verbose]

Description

'dmhistory' extracts the processing history stored in a data file's HISTORY keywords. It is possible to extract individual commands by tool name or to retrieve the entire file history (multiple tools) in one batch.

The HISTORY keywords are a part of the COMMENTS header section of a data file and contain a listing of all the commands (tools plus their input parameters) which were used to process the file. To view the actual history, type: dmlist file.fits opt=comments.


Examples

Example 1

dmhistory file.fits dmhedit

Will extract the history records from 'file.fits' and print to STDOUT all dmhedit commands that were used.

Example 2

dmhistory file.fits acis_format_events expand=yes

Will extract the history records from 'file.fits' and print to STDOUT any acis_format_events commands that were used. Will also expand the stacks in the output:

acis_format_events infile="filename.fits[time=51517057.4305350:51522856.8805350]" ....

Otherwise, the output would be abbreviated as such:

acis_format_events infile="@filename.fits" ....

Example 3

unix% punlearn dmcopy
unix% dmhistory file.fits dmcopy action=pset
unix% plist dmcopy

This will grab the 'dmcopy' history record from the file file.fits and use it to set the parameters in dmcopy.par. If multiple dmcopy commands were run, the last instance of dmcopy is reflected in the .par file.

Example 4

dmhistory file.fits my_own_script action=put

Read the parameters from the 'my_own_script.par' parameter file and add it to the history of 'file.fits'. 'my_own_script.par' will be searched for in the usual parameter searching order.


Parameters

name type ftype def min max reqd
infile file input       yes
tool string         yes
outfile file output stdout      
expand boolean   yes      
action string   get      
clobber boolean   no      
verbose integer   0 0 5  

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The input file name (image or table)

Parameter=tool (string required)

The name of the tool whose history you wish to extract.

All the history for the specified tool will be extracted. For example, if dmhedit was run several times, you will extract all the dmhedit commands. You can specify 'all' to extract the history for all CIAO tools recorded in the file.

dmhistory will exit with an error if no history records can be found specified tool.

Parameter=outfile (file filetype=output default=stdout)

The output file name

The default will print one command per line to stdout. Optionally, a file name can be supplied. "none" or "" will direct the output to stdout as well.

Parameter=expand (boolean default=yes)

Expand stacks

This parameter controls whether or not the stack name or the list of files in the stack are included in the output string. For example, if 'file.lis' contained 'one' and 'two', setting expand=no will show '@file.lis' while expand=yes will show 'file.lis[one,two]'.

Parameter=action (string default=get)

What to do with the history: get, put, or pset

Defines what action dmhistory should take with the history information.

action="get": the command line string for 'tool' will be created and sent to the 'outfile' (default is stdout, i.e. the screen).

action="pset": instead of printing the value to 'outfile', the reconstructed command is "pset" (see "ahelp tools pset"), setting the parameter file for the 'tool' task. Note: If there are multiple instances of that tool in the history, then there will be multiple psets and the most recent instance will be the final version in the parameter file.

action="put": the parameter file for the given tool is written to the data file, instead of a command being read from the history. The infile must have read and write permission for the user. This feature is especially useful in shell-scripts that use a pseudo parameter interface (e.g. wavdetect and tgdetect) to store their parameters in the history. In "put" mode, 'all' is not a valid tool name unless the user is trying to add a command stored in 'all.par'. Also, the outfile and clobber parameters are not used in this mode.

Parameter=clobber (boolean default=no)

Remove output if it exists?

Used to specify whether or not to overwrite existing file that has the same name as the specified output file (only DM dataset will be clobbered).

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

Verbose can be from 0 to 5, generating different amounts of output.


Bugs

action=pset with long command lines may crash.  (14 Sep 2012)

If one uses the action=pset option and the command line is very long (> ~4096 characters), the tool may crash. This may be the case if the file is the result of combining many observations.

Caveats

action=pset with multiple instances of tool  (14 Sep 2012)

Each instance of a tool in the history is acted on when action=pset.

unix% dmhistory evt.fits acis_process_events action=pset

Each instance of acis_process_events in the above example will be pset; the last instance will be the final parameter settings.

As the parameter of any tool may have changed, this may lead to warning messages about parameter mis-matches and may miss or skip new parameter.

See Also

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