History Managment Routines

The HSI library is concerned with the creation and propogation of text history. ASTERIX applications typically write a record to output files containing the following information,

The creation date
The program which added the history record
The machine on which the program was executed
Optional text records detailing program parameters, and any other information required to repeat the operation

Representation of history in HDS

History in HDS is stored in a top-level component called HISTORY. History records are stored in a structure array component called RECORDS, which is extended in multiples of EXTEND_SIZE, the current record (ie. the last used) being denoted by CURRENT_RECORD. A trace of such a structure looks like,

HISTORY                {structure}
  CREATED          <_CHAR*18>     "dd-mmm-yy hh:mm:ss"
  EXTEND_SIZE      <_INTEGER>     10
  CURRENT_RECORD   <_INTEGER>     17
  UPDATE_MODE      <_CHAR*8>      "DISABLED"|"QUIET"|"NORMAL"|"VERBOSE"
  RECORDS[20]           {array of structures}

  Contents of RECORDS[1]
    DATE             <_CHAR*30>     "dd-mmm-yy hh:mm:ss"
    COMMAND          <_CHAR*30>     "XSORT Version 1.6-1           "
    TEXT[n]          <_CHAR*80>     ...

New history records use up the unused slots first, the array being extended on demand. The purpose of the UPDATE_MODE component is to allow history updating to take place at different levels on a file by file basis. The four options are self-descriptive and are, disabled, quiet, normal and verbose. ASTERIX implements all of these levels, but does not distinguish between normal and verbose. In quiet mode ASTERIX writes only the date, command and host name to the history record. In normal and verbose modes the text records are also written.

Representation of history in FITS

New history records written to FITS files by ASTERIX are written using HISTORY keywords thus,

HISTORY   ASTERIX: Created by COMMAND at DATE on HOST
HISTORY     text line 1
...
HISTORY     text line n

In addition the keywords DATE and CREATOR are written if the FITS file is being created ab initio, and the HSI_NEW routine is used. Where ASTERIX programs add history to FITS files not created originally by ASTERIX, all the existing HISTORY records are considered to comprise a first history record, with time stamp and command taken from the DATE and CREATOR keywords if defined.

History Managment Routines

Representation of history in HDS

Representation of history in FITS

Environment Control of History Creation

Extracting history

Examples

Creating history in a new file

Adding history to an existing file

Displaying history

Further Reading