Canada's National Laboratory for Particle and Nuclear Physics
Laboratoire national canadien pour la recherche en physique nucléaire et en physique des particules

trar - an ASCII Archiving Tool for EPICS Process Variables

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

Disclaimer:

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.

Functionality:

• host-based archiver which was developed at TRIUMF
• archives to ASCII files
• an archiving session is configured by a request file which is read when trar is started.
• archiving is organised in archive groups
• supports arbitrary number of archive groups.
• archiving of a group may be conditional on the value of one PV
• each archive group is written to disk after a group-specific, fixed time-interval
• sets CA monitors on the requested PVs and accumulates current value, minimum, maximum, and monitor count during an archive interval.
• archive directory  is specified by the environment variable TRAR_ARCHIVE_DIRECTORY.
• by default, all groups are archived to one archive file (<archive_directory><yyyymmdd>.txt). A new default archive file is opened at mid-night, as well as an information file (<archive_directory><yyyymmdd>.info).
• any archive group may be archived to a specified file instead of the default file. In that case, multiple days are archived into one file
• by default, values are written to the archive file, using the %g format of the C language. This can be overridden on an archive group basis by the !precision directive (see below)
• a  PV prefix can be defined, which is used to update a heart-beat PV and PVs with information about connected and unconnected variables.

Limitations:

• reads all PVs as DBR_DOUBLE
• assumes only one value per PV (i.e. no waveform records etc.)
• in order to change the archive configuration, trar must be stopped and re-started with a new request file
• connections to PVs are only established at trar startup. Any non-connected PVs (e.g. because of an IOC is not running) will be reported, but no attempts at later connects are made.

Request File Format:

• comment lines start with %
• directives start with !
• empty lines are ignored
• one PV per line left aligned
• Directives:
  a) general directives
  - !include <request file>
  - !instance <PV prefix>
  b) directives for specifying an archive group
  - !group <interval> [<archive file>]
  - !name <group name>
  - !condition <pv> <op> <value>
  - !precision <significant digits>

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>
   
   where:
   <date> is yyyymmdd
   <time> is hhmmss
   <long time> as returned by the C time function.
   
   
2. one line per PV in the format:
   

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.info.

Miscellaneous:

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 trar.info is deleted.

Archive Retrieval:

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

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

A Perl/CGI script trarexweb.pl 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.