Robert Michaels, rom@jlab.org, Jefferson
Lab Hall A, updated Aug 2003
dataspy -- To print out raw diagnostic data, e.g. TDC or ADC data, from online.
dplot -- To plot a minimal set of raw diagnostic histograms from online data. dhist is a shell script which calls dplot with particular arguments.
Warning: These codes are being deprecated in Fall 2003. No longer supported.
This brief section assumes you are on shift, want to know a bit about dhist, and don't have time to read a lot.
While these codes run in many ways, lets be definite: Log onto adaqs3 as the "adaq" account. If dhist is not already running type "dhist". Now you will see a reminder of what directory to go to and that you should type "./dhist" there. Just do it.
There are TCL interfaces "dopte" and "dopth" for turning on/off the histograms which pop up with dhist. These interfaces also show an alarm status for the histograms by statistical comparison to a set of reference histograms. There is a push button for updating the reference histogram file -- if you are sure the current histograms can be used as a reference for what is "good".
Now if you crave more details, read on....
dataspy -D [ -f filename -S cpu -r -s -v -l -g -p -a1 -a2 -am ]
dplot -D [ -f filename -S cpu -u nupdate -w nwait -r nreset -e numevents -d ] where
D = R or L for Right arm or Left arm, respectively (note, the R-arm package was formerly called E-arm or Arm 1, and L-arm was called H-arm or Arm 2 by this software.)
Default source of data is the online ET system (network-distributed shared memory), but if "filename" is given, the CODA file "filename" (full-path-name) is analyzed instead.
-S (capital S) cpu is to pick cpu = adaqs2, adaqs3 (or now adaql2) as the server of online (ET) data. Specifying S overrides search for a local ET system, but specifying a CODA file overrides ANY other choice of input. If S is absent, code looks first for local ET system, and if one is not found to be running it looks for the default ET server on adaqs2. If you want the ET server on adaql2 you have to specify "-S adaql2".
-r (for dataspy) means print raw data in CODA format
-r (for dplot) means reset every nreset*nupdate events (the default is adequate).
-s, -v, -l, -g, -p -a1 -a2 -am (for dataspy) are respectively for printing scintillator, vdc, leadglass, gas Cerenkov, FPP, A1, A2, or Am aerogel diagnostic data.
The other arguments are self-explanatory -- if you type just the name of the executible (e.g. "dplot") it will printout the usage instructions. But the defaults for these optional arguments are probably ok and you need not bother.
dataspy and dplot share most of the same underlying software which grew from the OHAA analyzer of C. Howell, P. Ulmer, and R. Michaels. The dataspy and dplot codes have also had major contributions from N. Liyanage, M. Rvachev, L. Zhu, and the FPP group. This software makes plots of raw diagnostic information, such as wire maps, and can also print the information to the screen. A variety of options are available, which are passed as flags to the command, or by editing the "hist_opt" file.
dataspy grew out of dplot, but dataspy doesn't actually plot anything. Instead it prints out some raw data from detectors. In this sense it is similar to running dplot with the "-d" option, but dataspy grew a bit beyond dplot.
dplot uses the CERNLIB package HPLOT to plot continuously on the workstation screen with no human intervention. It works both OFFLINE -- on a CODA file -- or ONLINE -- getting CODA data from the ET system, which is a network distributed shared memory connection to data in real-time. When getting data online, it does so in a way that cannot cause deadtime. The default is to get the data from ET, but if you specify the argument "-f filename", the CODA file filename will be analyzed. dataplot.c is the main routine for the binary dplot. A new feature as of Aug 1998 is that if the ET system is not found on the local machine and the "-f filename" option is not used, then the software attempts to connect to a remote server of ET data. This server is running on the same machine as CODA, allows multiple connections, and the connection are via BSD sockets. dhist is a shell scripts which call dplot with a particular set of arguments.
The codes dataspy and dplot work on HP-UX and SunOS, running with both versions 1.4 and 2.0 of CODA. There is no restriction that one must run the online (ET) version on the same computer as CODA, because it can connect remotely.
There are about 20 pages of HPLOT plots. The plots pop up on the workstation screen and remains for a few seconds, in succession. Each page results in a postscript file with an obvious filename, for convenient printing. Also, all histograms appear in a histogram file which may be analyzed in PAW. The file "hist_opt" controls which histograms are to be printed. Simply change the number in the first column to a one or zero to plot or not-plot. The pages are described in comments in the hist_opt file. hist_opt is read every time the page plotting starts at page 1.
For dplot (dhist), one needs both the detmap.config file and the hist_opt file in the same directory from which you are running. If you just type "dhist" from anywhere, it will remind you where to go and what to do. The optional TCL/TK window started by "dopte" and "dopth" also allows to turn on/off the pages. These interfaces work by writing to the hist_opt files. The dopte(h) interfaces also have alarm status: If some histogram on one of the pages go "bad", the corresponding line on dopte(h) turns red. It turns red whether or not the user has selected that page for viewing. The "badness" is judged by a statistical comparison to a set of reference histograms. Beware, the comparison is rather sensitive; there could be false alarms (especially if running conditions change in a natural way). The intention of the red-alarm is to alert experimenters to problems like a chamber tripping off.
One may generate standard histograms from dopte(h); see the push button. Upon pushing this button, a dialog pops up to ask for the file name (full-path-name) of a file to analyze for generating the standard histograms. Make sure this file is for a run which was "normal", since this will now become your standard for statistical checks. After about 10 minutes, the new standard histograms are created in the appropriate directory. You have to restart dplot (dhist) in order to load in the new standard histograms.
Naturally, some experiments may want to tailor the online analysis to their particular needs, beyond trivial modifications of hist_opt. Below is a brief discussion of how to proceed. See also ~adaq/dplot/README, and please contact Bob Michaels before (or very soon after) you proceed to modify the code, to avoid miscommunication.
1. At any given time, there is a development version and a stable version. The development version is kept in ~adaq/dplot/dev, and the stable version in in ~adaq/dplot/stable. The /dev version may be modified by anyone with access to files owned by adaq (practically anyone), the /stable version is protected by the superuser.
2. Groups who want to modify the /dev version may work in /dev if they know what they are doing, or else copy it somewhere else and work for awhile until they know what they are doing. It would be best if only one or a few people worked on this software. Having such an unprotected /dev version may seem dangerous, but it has worked ok up till now, and the freedom is useful.
3. After we (mainly the group, but also me, Bob, to some extent) are sure the new executible is ok we put it in the front of the path, in ~/bin/$OSNAME. After I look over the code changes (I can do it fairly quickly with some script tools) and like what I see, I will copy the /dev version into /stable.
Finally, one question you might have: Can't we do the same stuff with ESPACE ? The answer is, basically yes. Experimenters have made ESPACE kumacs which plot raw diagnostic data for detector checkout. ESPACE runs on a data file as it is being written, and runs fairly fast, so it is practically the same utility. Of course, ESPACE can do much more also. Nevertheless, dataspy and dhist have their cult worshippers and occassionally have found problems ESPACE didn't, though not because it coudn't.
Maintained by Robert Michaels