source: pvrrd/doc/source/usage.rst @ 624

.. $Id: usage.rst 624 2011-08-21 20:15:37Z jemian $

Adding EPICS Process Variables
------------------------------------------------------------------

The EPICS Process Variables to be logged are
entered in the ``pvlist.xml`` file.  Follow the
pattern for the other entries in that file.
Here is an example::
 
  <EPICS_PV pv="S:SRcurrentAI" units="mA" min="-0.1" max="310" scale="lin">
    APS storage ring current, mA
  </EPICS_PV>
  <EPICS_PV pv="33bmPLC:alarm:cg1:vac" 
      units="Torr" min="1e-5" max="2000" scale="log">
    33BM DCM convectron gauge vacuum
  </EPICS_PV>

Updating EPICS PVs into RRD databases
------------------------------------------------------------------

:note: TODO: APS server now has the necessary parts.  Revise the docs.

RRD needs some more parts (database and graphing scripts) 
to be built before plots will be available on the WWW.
Documentation on how those parts are 
created has not yet been written.  Until then,
examine :mod:`rrdCreate` and :mod:`cgiCreate`
for hints.

Generating plots of logged data
------------------------------------------------------------------

The APS XOR WWW server is configured for RRDTOOL support 
to generate the plots on demand from their associated RRD databases.
The plots will only be generated on demand from a
web browser request, and then only 
as needed by the time-granularity of the plot.
Thus, the plots will not be re-generated unless necessary.

Until the XOR WWW server had rrdcgi capability, the plots and HTML pages
were generated by calling rrdcgi directly from a command-line job.
The Python program ``htmlCreate.py`` generated
all HTML pages and related plots from the set of CGI scripts.
It was run from a UNIX cron job.  This is no longer used.

RRDtool support was added to the WWW server in July 2010.
The WWW server needs to identify the CGI files by suffix.
Appending ``.cgi`` to all the CGI files will allow the files
to be properly identified and rendered.  (tested and works)

The plots directory needs to be writable by the WWW server 
user (nobody) and have the group sticky bit set

Configuration of the infrastructure
------------------------------------------------------------------

:note: under construction

It is necessary to understand UNIX command shell scripts,
EPICS PV communications, php,
Python, rrdtool, and WWW servers to configure the 
infrastructure of this support.

crontab configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A cron job is used to keep the software running.
This avoids an unprivileged user from needing root access to modify
the OS startup configuration.  This file will need to be edited
for the proper path to the installed directory::

          #     field          allowed values
          #     -----          --------------
          #     minute         0-59
          #     hour           0-23
          #     day of month   1-31
          #     month          1-12 (or names, see below)
          #     day of week    0-7 (0 or 7 is Sun, or use names)
 
  # make sure that EPICS --> RRD monitor tool is running, check every 5 minutes
  # solaris cron does not support */5 notation from linux cron
    10,5,10,15,20,25,30,35,40,45,50,55 * * * * /home/joule/WEB33/www/rrd/checkup-epics2rrd.csh 2>&1 /dev/null

assets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These are the assets as configured for one particular installation::

   cgi/                      (ignored by SVN)
   data/                     (ignored by SVN)
   html/                     (no longer needed)
   other/
   plots/                    (ignored by SVN)
   checkup-epics2rrd.csh
   cgiCreate.py
   epics2rrd.csh
   epics2rrd.log
   epics2rrd.pid
   epics2rrd.py
   htmlCreate.py            (no longer needed)
   index.php
   Makefile
   makeTagHTML.py
   documentation.html
   rrdCreate.py
   xmlSupport.py
   properties.xml
   pvlist.xml

   leo% svn pg svn:ignore .
   xref.txt
   plots
   cgi
   html
   data
   *.log
   *.pyc