View source for HOWTO record a selection of EPICS values to a file or ET system

This page describes how to use the ''epics2et'' tool for recording a selection of EPICS PVs (=process variables) to either a file or ET system. For general access to the complete EPICS archive, one should look at the [[https://halldweb.jlab.org/hdops/wiki/index.php/Slow_Controls_Shift#MYA_Archiver MYA tools]]. This tool was originally written to insert EPICS values into the CODA data stream. However, it has been expanded to include writing the events to either an EVIO or ASCII file. The latter is makes this a convenient tool for temporarily capturing a subset of EPICS values into a file with some specified periodicity in a form that os fairly easy to parse.

The long-form usage statement for the tool is:

<pre>
Usage:
   epics2et [options]

Periodically read EPICS values and insert them into an ET system or file.

By default, this will read the configuration file:
   $DAQ_HOME/config/monitoring/epics2et.conf
The file should have two entries per line. The first being
the EPICS PV (=process variable) name and the second the 
period in seconds in which to read out that variable. Events can be written to an ET system, EVIO file, or ASCII
formatted file. Any combination of these output formats can be
written simultaneously. Writing to an ET system can be used to insert
the events into a CODA-produced data file.

The ETsystem string is normally of the format:

ET:etfilename:station:host:port

for example:

ET:/tmp/et_sys_hdops:MON:gluonraid1:23914

This format is deliberately chosen to match that used by the
DAQ plugin and therefore, the online monitoring system. Note that
because this program (unlike monitoring programs) is a producer,
it will always attach to the GRAND CENTRAL station, thereby
ignoring the 'station' field. Also, if the port number is not given
then the default ET port number of 11111 is used. Finally, if the
source does not start with the string 'ET:', then the source is 
assumed to be an ET system file on the local file system.

At least one of the -et, -evio, or -ascii options must be given.

options:
  -h                 Print the short form Usage statement
  --help             Print the long form Usage statement
  -v                 turn on verbose mode
  -et    ETsystem    Write events to ET system with given name
  -evio  filename    Write events to EVIO file with given name
  -ascii filename    Write events to ASCII file with given name
                     (if filename exists, it will be appended to)
  -c     file.conf   Use this config file instead of default
  -NTHevio           Do NOT write out Network Transfer Header to EVIO file(see below)
  +NTHevio           Do write out Network Transfer Header to EVIO file(see below)
  -NTHet             Do NOT write out Network Transfer Header to ET event(see below)
  +NTHet             Do write out Network Transfer Header to ET event(see below)

The -NTHet and +NTHet options can be used to force the addition or not of a
CODA Network Transfer Header to the front of the event. This is needed
when writing events to the datastream via an ET system being read by 
a CODA Event Recorder process. Similarly, the -NTHevio and +NTHevio
options can turn this off and on for EVIO files. The default has this 
ON for event written to ET and OFF for events writtent to EVIO file.
</pre>

== Configuration File Format ==
The format of the input configuration file used to specify which EPICS variables to read an how often is as follows:

 name1  period1
 name2  period2
     ...

where:
* ''nameN'' is the name of an EPICS variable
* ''periodN'' is the approximate time in seconds between readings
* The "name" and "period" fields are separated by white space
* Lines starting with "#" are ignored
* Blank lines are ignored

A full example file is:

<pre>

# My Example file

HallD-PXI:Data:I_Shunt     2
HallD-PXI:Data:B_Field     5
IBCAD00CRCUR6              5
hd:radiator:motor.RBV    600
DAQ:availableRAID        600
</pre>

== Writing to an ASCII File ==

To write to an ASCII file, just run ''epics2et'' with a "--ascii filename" argument. This will start writing to the file, creating it if necessary, but appending to it if it already exists.

 > epics2et -c epics2et.conf -ascii tmp.txt

Because each "event" may read a different subset of variables due to their different periods, values are written out one per line with the name and value separated by one or more spaces. Events are separated by a line starting with "+++++++ New Event:". Each event also has a "timestamp" field with the time of the reading in seconds.

<pre>
+++++++ New Event: Wed Nov  5 21:28:35 2014
DAQ:availableRAID                  47.4399
HallD-PXI:Data:B_Field             1.04472
HallD-PXI:Data:I_Shunt             1000.39
IBCAD00CRCUR6                      100.5
hd:radiator:motor.RBV              135.944
timestamp                          1415240915
+++++++ New Event: Wed Nov  5 21:28:38 2014
HallD-PXI:Data:I_Shunt             1000.26
timestamp                          1415240918
+++++++ New Event: Wed Nov  5 21:28:41 2014
HallD-PXI:Data:B_Field             1.04472
HallD-PXI:Data:I_Shunt             1000.62
IBCAD00CRCUR6                      103.5
timestamp                          1415240921
+++++++ New Event: Wed Nov  5 21:28:44 2014
HallD-PXI:Data:I_Shunt             1000.42
timestamp                          1415240924
</pre>