trar - an ASCII Archiving Tool for EPICS Process Variables

Copyright (C) , TRIUMF 1999, 2000, ...

Updated:  30-Nov-2014


This document was developed from source code comments in the file trar.c. In case of discrepancies, comments in the source code of trar.c are deemed to be closer to reality   than any information in this document.




Request File Format:



Archive File Format:

Data are archived in "samples". Each sample consists of:
  1. a sample header line of the form:

    [sample] <date> <time> <long time>

    <date> is yyyymmdd
    <time> is hhmmss
    <long time> as returned by the C time function.

  2. one line per PV in the format:
Archiver revisions before 1.14:
  <pv name> <pv value> <pv min> <pv max> <monitor count>
Archiver revisions after 1.14:
  <pv name> <pv value> <pv min> <pv max> <monitor count> <min timestamp> <max timestamp>

The timestamps are in the format  HHMMSS.mmm, where mmm is milliseconds. Timestamp is the time when a monitor was received by the archiver, NOT the EPICS timestamp.


Information File:

In addition to the archive file, trar writes an information file:

<archive directory><yyyymmdd>.info.

The information file contains a list of all archive groups, tags and archive files, as well as start time and process ID info. A copy of the information file is written to <archive directory>



trar terminates if it receives a SIGTSTP or a SIGTERM signal. Termination time info is written to the archive file and the information file. The file is deleted.

Archive Retrieval:

A Perl/Tk script displays the information about the current archiving configuration form the information file.

A Perl/Tk script allows retrieval of up to eight process variables from the archive files and plots them using Gnuplot.

A Perl/CGI script allows retrieval of up to eight process variables from the archive files from a web browser and plots them using Gnuplot.

Both retrieval scripts use a compiled retrieval tool for more efficient extraction of data from the ASCII archives.

Split Archive Files at TRIUMF:

At TRIUMF, the archive files are post-processed in order to speed up archive retrieval. The result of post-processing is a set of "split archive files" where each file contains the archived data of one PV.

The split archive files for a given day are stored in the sub-directory <yyyymmdd>-split    of the <archive directory>.

The split archive file contains the archive data for the PV with one line per archive time ordered by archive time in ascending order. Line format:
<date> <time> <long time> <pv value> <pv min> <pv max> <monitor count> <min timestamp> <max timestamp>

Split Archive File Names:

Split archive file names come in two flavours:

  1.  <yyyymmdd-<PV name>.txt,    e.g. 20051130-IMS:Q3:RDVOL.txt. 
    This is the original file name format, which has the disadvantage that the file name is illegal on Windows systems.
  2. <yyyymmdd-<PV name modified>.txt,    e.g. 20051130-IMS-Q3-RDVOL.txt.
    i.e. the colons in the PV name are replaced by a dash. This format is written by newer versions of the post-processing script.
Any archive retrieval tool should be able to handle both file name formats.