Off-line database

The off-line database is stored in a Perl DBM database, a simple database management facility that allows the user to store information to disk files in key-value pairs. A very nice discussion of this type of database and how to use it in a Perl context can be found in [Perl, pages 170-172]. This database provides a record of the ``cooking'' process by storing such information as the executables that were run and the location of the output files from these executables. It also records information about the quality of the ``cooking'' by parsing the output of the monitoring programs and storing this information in the database. All of the variables that are stored in this database, along with their definitions, can be found in Tables 1 - 13 of this paper.

Several utilities have been written to make use of this database, all of which MUST be run on Linux machines. These scripts can be found under CVS management in the directory scripts/cooking_scripts. The first and simplest utility is lookatrun which takes as an argument the database file name. lookatrun then simply dumps out the contents of that file in no particular order under the format:

variable has a value of value

While lookatrun simply lists the key-value pairs in a data file, the getdb script can produce a table of database quantities for a given set of keys indexed by run number. The usage for getdb is shown below.

usage: getdb -K<key1> -K<Key2> <dbfile1, dbfile2> 
		-K<key> set key
		-h 		Print this Help
		-F<###> fraction of events * number
		-S<###> Scale by intergrated_PS_scalers * <###> 

The output of getdb is a table with the run number and file extention listed in the first two columns and the values of the various input database keys listed in the remaining columns. The following is a sample execution of this script and the results which could be redirected into an ASCII file:

ifarml2> getdb -Krms_s1_sl1  -Krms_s1_sl2 -Krms_s1_sl3 -Krms_s1_sl4 -Krms_s1_sl5 
-Krms_s1_sl6 /work/clas/production/g1/pass1/database/clas*.db
		11205 0 		0.065 		0.075 		0.126 		0.123 		0.174 		0.158
		11206 1 		0.065 		0.074 		0.126 		0.123 		0.175 		0.160
		11462 0 		0.061 		0.070 		0.115 		0.113 		0.175 		0.165
		11462 1 		0.061 		0.070 		0.114 		0.113 		0.177 		0.165
		11462 2 		0.061 		0.070 		0.115 		0.115 		0.174 		0.167 
etc...

Another script which is used to examine the contents of the off-line database is plot_strip_chart.pl. The usage for this script is

Usage:plot_strip_chart.pl [-h][-R<#>][-r<#>][-f<file>][-d<dbdir>]
(-b<beam.t>)[-t<torus_current>][-nf][-ne][-A][-S] ARGS
		-h 		Print this help message.
		-R<run#> Maximum run number to include in plot.
		-r<run#> Minimum run number to include in plot.
		-f<file> Base file name for output.
		 -d<dbdir> Path to database directory.
		-b<beam.t> Plot only runs with this beam energy in MeV.
		-t<torus> Plot only runs with this torus current.
		-nf 		Normalize results to Faraday cup.
		-ne 		Normalize results to # of events written.
		-A 		Average over all of the file extensions.
		-S 		Plot variables on same page.
		ARGS 		List of variables to plot on same graph. 

The arguments used for this script are the variable names found in Tables 1 - 13 of this paper. plot_strip_chart then produces three files. The first is a text file very similar to the output of getdb. The first column of this text file contains the run numbers found in the database and the other columns contain the values for the chosen variables. However, where getdb prints out the values for each file extension, plot_strip_chart.pl sums the information from each file extension over the entire run number. The options -A, -nf, and -ne allow the user to either average the value by the number of file extensions, normalize the sum to the Faraday Cup information or for photon running, normalize the sum by the total number of events written out by a1c. The second output file created by plot_strip_chart.pl has the extension .gnu. This .gnu file contains a series of commands that will be used by gnuplot to histogram the chosen variables versus run number. plot_strip_chart.pl then uses gnuplot to create a postscript file containing a graphical representation of the information found in the .txt file. Examples of output from this script can be found in Figs. 5 and 8.