![[*]](file:/usr/share/latex2html/icons/crossref.png){kind=icon}
for a primer on the language.
Brett Viren
October 5, 2001
This document will give information on obtaining, building, running and configuring the End Of Spill Monitor. It is also available in postscript format
The End Of Spill MONitor (EOS-MON) reads events from the DD FIFO system (see DD documentation). It is limited to data from the SCALERs and the SSPs, more generally, any data in broadcast fifos with ctlw1 == RUN_K_RECORD_END_SPILL (14).
It can display this data, or arbitrary functions of this data in various formats. These current consist of:
The number of charts displayed is essentially unlimited and new charts can be created or removed on the fly. The functions of the data can be input during the running of the program, or can be entered into a file which can be loaded at start up time or in the middle of running.
The Guile Scheme programming language (see section 8.6) is
embedded in to EOS-MON to provide for configuration as well as
arbitrary functions of the data. Scheme is a vastly simplified
dialect of Lisp. Although at first glance it appears to be much
different than FORTRAN or C, it is fairly easy to learn to do simple
things with it. See section 6 for details on how it
is employed and section for a primer on the language.
The source code to EOS-MON is in the e787/e949 CVS repository (http://www.cvshome.org/). It can be retrieved by following the steps in this section.
To gain access to the CVS repository must be able to log in as online@bnlku9.phy.bnl.gov. When you invoke CVS, as shown below, you must supply a password. Alternatively, you can add the contents of your $HOME/.ssh/identity.pub file to the file online@bnlku9.phy.bnl.gov:.ssh/known_hosts.
To get the actual code follow these steps:
cd /path/to/some/working/directory/ cvs -d online@bnlku9.phy.bnl.gov:/disk1/online.cvsroot get EOSThis should produce a subdirectory called online/. It will hold the code for EOS-MON as well as DD and OTOOLS which are needed to allow EOS-MON to connect to the FIFO system.
Building the code is done in the context of the rest of the online. However, only DD and OTOOLS are needed. Furthermore, EOS-MON needs to be built with GCC/G++.
To build the code as online@bnlku9 do the following:
ssh -l online bnlku9 > bash bash> cd somedir/ bash> cvs -d online@bnlku9.phy.bnl.gov:/disk1/online.cvsroot get EOS bash> cd online/ bash> export ONLINE_MAIN=`pwd` bash> source setup.sh bash> export USE_GCC=yes bash> PATH=$PATH:/usr/freeware/bin bash> LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/PublicDomain/lib:/usr/freeware/lib bash> gmake EOS
Using bash instead of the default shell for the online@bnlku9 and sourcing the setup.sh script assures that no collision will occur with the rest of the built online code (which must be built with the IRIX system C/C++ compiler).
Shift members will usually start the program by clicking on the EOS-MON button in the toolbox. This will start it in the default configuration.
This runs a script called eos-mon in the online/eos-mon/ directory. This scripts sets up some environment variables, finds various needed map files, and then calls the eos-mon.exe executable.
Internally, eos-mon.exe loads a file eos-mon.scm which contains some Scheme code for setting up the environment used to load the FIFO event data. This file is not ``user serviceable'', but is necessary.
Running eos-mon.exe -h will give a short synopsis of what command line arguments it takes.
You can add new charts either by clicking on the ``Charts'' menu, or by clicking on the name of one of the available data values. You have a choice of adding just a bar chart, just a strip chart, or a combination of the two.
If you create a chart from the ``Charts'' menu it will start with an empty value. You must then type in either the name of a data value (scaler or ssp), or the body of a function in the provided entry. See section 6 for details on how to enter these things.
For each chart there are adjustable minimum and maximum limits. Either click on the arrows or type in a value to set them.
You can also set the color used for a chart by right clicking on the chart and using the color widget to select a color.
You can remove an existing chart from the display by right clicking on the chart and selecting ``Remove''.
All attributes of the current set of charts can be saved by selecting ``Dump GUI State'' from the ``File'' menu. You can later reload this saved file by selecting ``Load File'' from the ``File'' menu. Any Scheme file can be loaded in this manner. You can also configure things to cause files to be loaded at start up time. See section 7 for details.
Finally, there is an entry at the bottom of the window which allows typing in raw Scheme commands.
As mentioned above, each chart has an entry into which one can type either the name of the datum to plot or the body1 of a Scheme function. The brand of Scheme used is case sensitive and this must be kept in mind when entering values or function bodies.
An example of a simple value is:
Ck
And example of a simple function body, which returns the ratio of the ``Ck'' and ``CSec'' values is:
(/ Ck CSec)
You will note that the function (the division operator) comes before its arguments. This is the usual ``prefix'' notation of Scheme (and all Lisps).
After hitting <enter>, EOS-MON will form a Scheme function using your function body and process this function to make sure it will return a number.
More complicated function bodies can be built by nesting functions. For example one might want to form an average of two values:
(/ (+ B4U B4V) 2.0)
To allow customizations or other extensions, EOS-MON can load Scheme files at startup. This is accomplished by simply giving the file to the eos-mon script on the command line (or in the toolbox's .chestrc file).
(FIXME: In the future, there may also be a mechanism by which a .eos-mon file is loaded from the users home directory)
The Scheme files can be either written by hand, or dumped from EOS-MON as described above.
This section gives a very brief introduction to the Scheme programming language. It should be just enough for you do be productive in using it to do simple extensions to EOS-MON.
Scheme syntax is far different from most other programming languages. This is largely due to the fact that its syntax is so simple as to almost be non-existent and because it uses a ``prefix'' notation instead of the usual ``infix'' notation of C and FORTRAN.
The syntax can be described as containing functions, function arguments (values) and ``special forms'' (and, of course, parenthesis). A function invocation is a list, starting with an open paren, '(', followed by the function name and zero or more arguments and terminated with a close parent, ')'. All arguments are evaluated before being passed to the function. A ``special form'' is simply something that looks like a function, but doesn't necessarily evaluate its arguments. A Scheme macro is an example.
Here is an example of a function call in C, FORTRAN and Scheme:
x = f(y,z);
X = F(Y,Z)
(set! x (f y z))
Note that the scheme example has 2 functions: set! and f. Also note that the ``!'' in the built in Scheme function set! is valid syntax. The convention is that if a function modifies one of its arguments it has a ``!'' at the end of its name.
You can create a value in Scheme by using the define special form. For example,
(define x 42)
defines ``x'' to be the number ``42''. You can set this value to
something else either by using define or, as above, set!
such as in (set! x 69).
To create a Scheme function, one uses the lambda special form. For example,
(lambda (x) (* x x))
returns a function which takes one argument and returns its square.
Note, that the returned function is treated just like data. One could
use this function via:
((lambda (x) (* x x)) 5)
and ``25'' would result. It is tedious to define the function each
time we want to use it, so typically one defines a variable to hold
this function:
(define square (lambda (x) (* x x)))
After this, (square 5) also returns ``25''. Since this is
common syntax, Scheme provides some syntactical sugar to make it even
less tedious to define a function:
(define (square x) (* x x))
If such definitions are typed into the entry bar at the bottom of the EOS-MON window, the resulting function can be used in the entries associated with the charts.
Besides loading a Scheme file via the ``File'' menu, one can load one Scheme file from another using:
(load "/somepath/somefile.scm")
If a relative path is given, the environment variable
GUILE_LOAD_PATH is used to search for the file.
This section will walk through an example which creates a function that will return an average of the last N values it was given. This is actual code which is loaded into EOS-MON by default.
The idea of an average is to maintain a ring buffer of values. Each time the averager is called its argument is added to the ring buffer and an average of all the stored values is returned. The ring buffer code used will not be described in detail, but its interface is like:
In more detail, the averager is described. The description is interspersed with the code.
;; averager.scm - part of eos-mon.
;;
;; This creates an averager of some number of past numbers. Each time
;; this function is called with a value, the value is stored and an
;; average of all stored values is returned. The storage is a ring
;; buffer so once the capacity of the storage is exhausted, the oldest
;; value will be bumped.
;;
;; A few fixed sizes are defined as the aveN functions where N is
;; 2,5,10,25,100.
;;
;; bv@bnl.gov
;; Load the implementation of the ring buffer
(load "ring-buffer.scm")
;; First we define a function which returns an averager function of
;; the given size. It uses the recursive "clear" function to set all
;; initial values to zero. This also shows an example of lexical
;; scoping, namely that when the resulting averager function is
;; called, there is no mention of "size", yet, this is available to the
;; averager since it is in scope at its time of definition.
(define (make-running-averager size)
(letrec ((ring (make-ring size))
(clear (lambda (r s)
(if (zero? s)
r
(begin
(ring-add r 0)
(clear r (- s 1)))))))
(clear ring size)
(lambda (value)
(ring-add ring value)
(ring-average ring size))))
;; A simple utility function used inside the averager which returns
;; its average.
(define (ring-average ring size)
(letrec ((summer (lambda (r s)
(if (zero? s)
0
(+ (ring-get r s) (summer r (- s 1)))))))
(/ (summer ring size) size)))
;; Finally, some "canned" averagers of fixed sizes are defined.
(define ave2 (make-running-averager 2))
(define ave5 (make-running-averager 5))
(define ave10 (make-running-averager 10))
(define ave25 (make-running-averager 25))
(define ave100 (make-running-averager 100))
As stated above, Scheme is in the family of LISP languages. However,
while Common Lisp needs about 500 pages to specify the language,
Scheme is specified in about 50 and this specification is one of the
best places to learn Scheme. The specification is called Revised
Report on the Algorithmic Language Scheme (R5RS). Guile also has a
Fine Manual (although not yet complete) which includes a good
tutorial and reference. There are also some good tutorials on the
web, such as ``Learn Scheme in fixnum Days''. Below give a listing of
these and other resources.
http://www.schemers.org/Documents/Standards/R5RS/
http://www.swiss.ai.mit.edu/ftpdir/scheme-reports/r5rs-html/r5rs_toc.html
http://www.gnu.org/software/guile/docs/docs.html
http://www.cs.rice.edu/~dorai/t-y-scheme/t-y-scheme.html