THE PAN DATABASE
==================
PART I: THE BASICS
===================
The "pan" database is a collection of control parameters,
calibration parameters, cuts, etc which are read from an ASCII
file usually, but can also be read from a ROOT file or MYSQL.
The database is stored in ASCII files in the ./db directory of
the pan distribution. The files have names like "parity02_1454.db"
for run 1454, where "parity02" indicates the year 2002. These
ASCII files will be produced automatically by CODA for each run
and distributed to users. They can also be produced by a Perl
script which reads MYSQL and generates the ASCII files.
The format of the database is such that the first word in each
line is a "table" string, indicating a table in the MYSQL sense.
The columns of data that follow in that line are associated data
(data are strings, integers, or doubles) which belong to that table.
Look into one of the files and it will be fairly obvious. The rules
are given formally below.
Normally you would want to let "pan" read the ASCII database (db)
file corresponding to your run. If that db file is missing, you are
warned, and the default file "control.db" from $pwd is used instead.
One can also force "pan" to use control.db (see examples). Other
options exist, for over-riding this database at the command line,
for retrieving the database from a ROOT output or from MYSQL.
Putting stuff in database: You can use the Put() methods to put
ADC and Scaler calibration data, and cut intervals. The database
for that run is over-written (but only if you put something).
See the temporary example section in VaAnalysis.
PART II: LEARN BY EXAMPLE
==========================
Here are examples of how to use the database when running "pan":
1. The database is read from ./db/parity02_1454.db if
it exists, otherwise from ./control.db
./pan -r 1454
2. Force pan to read database read from ./control.db
./pan -r 1454 -D control.db
3. Database read from ./control.db, and over-ride the
tables 'lobeam' and 'windelay'.
All these are syntactically equivalent and correct:
./pan -r 1454 -D control.db -D lobeam 400 -D windelay 8
./pan -r 1454 -D control.db lobeam 400 windelay 8
./pan -D control.db lobeam 400 windelay 8 -r 1454
./pan -D control.db -r 1454 -D lobeam 400 windelay 8
but these examples are WRONG:
^^^^^
./pan control.db -D -r 1454 lobeam 400 windelay 8
./pan control.db -r 1454 lobeam 400 windelay 8 -D
4. Read the database from root file parity02_1389_BEAM.root.
Note: Any other '-D' command is ignored. You *CANNOT*
over-ride the database if you read from ROOT because
this is intended to recover exact conditions.
./pan -r 1454 -D -useroot parity02_1389_BEAM.root
./pan -r 1454 -D -useroot bob.root -D lobeam 1200
(in 2nd example, -D lobeam 1200 is ignored)
5. Read the database from MYSQL.
./pan -r 1454 -D -mysql
6. Read the database from MYSQL and over-ride a table 'lobeam'
./pan -r 1454 -D mysql -D lobeam 1400
PART III. RETREIVING DATA FROM MYSQL
====================================
(This part to be written.... Hello, Riad ?)
PART IV. DATABASE SPECIFICATION
=================================
Here are some detailed specs in case you have too much imagination
and something goes wrong. Most users can ignore this section.
The logic of command line over-ride of database does not allow
infinite combinations. Here is the expected behavior:
* If '-D control.db' we read from control.db. Other
'-D' command subsequently over-ride table(s).
* If '-D useroot filename' we read database from ROOT
file 'filename' and IGNORE all other commands. This is
because the purpose of reading from a ROOT file is to
reproduce exactly the analysis conditions that were used
to generate that ROOT file.
* If '-D mysql' we read database from MYSQL. Other '-D'
commands subsequently over-ride table(s).
* It is an error to specify both mysql and useroot. If
you try that, you'll get no data at all (ERROR).
* '-D table values' will over-write the table with those
values, provided the line has proper syntax. The syntax is
the same as a line in the database. IMPORTANT: The table
is dropped; therefore, you cannot add to a table, instead
you must add all lines of a table when you start one.
Normally this would be used for trivial tables like
'-D maxevents 500' or '-D lobeam 1200'. If the syntax is
wrong the error might not be caught, depending on what you
do wrong. Luckily the database is printed at the end-of-run
summary, so hopefully you will realize it then.
Whenever you Put() data, it together with the other data will be written
to ASCII and to MYSQL. To turn off MYSQL interaction requires an #ifdef
directive to be set. However, what is written to the ROOT file and log
output is always the data at startup, i.e. what was used for analysis.
The only data that can be Put() are DAC noise, pedestals, and cut
intervals. An important restriction is that you must Put ALL the
data because I clear all the other data from that table as soon as
you start Putting into that table. So, you must Put() all ADC channels
if you Put() one, and similarly you must Put() all cut intervals, if you
Put() one. Distinct tables (pedestals & cuts) don't interfere in this logic.
The Print() method should be called before any Put(). The Write() method
should be called after all Put()'s.
Required Content of Database
=============================
The following are required to be defined, else "pan" will complain.
1. tirdata in datamap table
2. a runtype
3. a pairtype
4. helicity delay 0 <= windelay <= 8.
5. a reasonable oversamp value (could be 1)
6. cuts named Low_beam, Beam_burp, and Oversample; for
pair-structured beam data, cut named Sequence
Rules about the Datamap
=======================
The datamap is one of the tables in the database
"pan" tries to provide clear error messages if you violate these rules.
1. Contents
ALL raw data and ONLY raw data must be listed in the datamap.
^^^ ^^^^
2. Syntax of the 'datamap' line in database:
The 'datamap' is the name of the table in the database.
The other quantities will be defined below.
There are three possible syntaxes illustrated by examples:
Example 1 (the "old" way, prior to Mar 20, 2003, which is still supported)
~~~~~~~~~
The following means find bpm4a in the location 73 thru 76 of event buffer.
datamap bpm bpm4a adc 5 0 73 bpm4axp bpm4axm bpm4ayp bpm4aym
Example 2
~~~~~~~~~~
The following means find bpm4a in ROC 21 at 14th location after adc header.
datamap bpm bpm4a adc 5 0 14 21 bpm4axp bpm4axm bpm4ayp bpm4aym
Example 3 -- This is the best way since it leads to fewer mistakes.
~~~~~~~~~
The first line means find bpm4a in adc5 starting at channel 0.
Then adc5 is located in the 14th word after header in roc 21
datamap bpm bpm4a adc 5 0 bpm4axp bpm4axm bpm4ayp bpm4aym
datamap adc adc5 adc 5 0 14 21 adc5_0 adc5_1 adc5_2 adc5_3
A common mistake here might be to have bpm4axp point to a channel
that is nowhere else defined, e.g. if the startchan field were 452.
Example 4 (ILLEGAL -- missing info. -- leads to error message)
~~~~~~~~~
Logically, bpms, bcms, lumis, and other detectors may be tied to adcs,
scalers, etc, but not vice versa, and you can't tie an adc 'to itself'.
datamap adc adc5 adc 5 0 adc5_0 adc5_1 adc5_2 adc5_3
Formal Structure of Datamap Line:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
table dev-type dev-name read-type devnum startchan [evbuff-offset] [crate-number] chan-names(keys)
Table = 'datamap'
3. Device type
The device type is used by the code to decide the generic type of
data being considered on this line. It is not a class.
4. Device name
A device is a name that people call the a device type within the
code. It is used to index the device. It is not an object.
5. Readout type
This indicates whether the readout is adc or scaler. If we wanted to
change the example above to a scaler, for example, we'd simply need to
change "adc" to "scaler" and also adjust the evbuff-offset and possibly
devnum and startchan as appropriate.
6. Device number
The index of the ADC or scaler must be unique and denotes a physical ADC
or scaler unit.
7. startchan
The 'startchan' is the first channel that is mapped for that line
in the datamap table of the database. If there is only one datamap
line for a given device-name, the startchan will usually be zero (1st
channel). However, if there are multiple lines for a given device-name,
then the startchan is the first channel pertaining to the first key
in the list. It is assumed that the subsequent channels range from
the start channel, incrementing by one for each key listed. The same
assumptions pertain to the evbuff-offset. If raw data from an ADC is
not part of a channel (e.g. csr or dac) its channel number MUST BE NEGATIVE
by convention. ^^^^^^^^^^^^^^^^
An example follows, where some antennas for bpm4a are distributed across
two different ADCs.
datamap bpm bpm4a adc 7 0 85 bpm4axp bpm4axm
datamap bpm bpm4a adc 9 2 99 bpm4ayp bpm4aym
And here is an example of data from one ADC. Note the negative channel
numbers for csr and dac.
datamap bpm bpm10 adc 6 0 79 bpm10xp bpm10xm bpm10yp bpm10ym
datamap adc adc3 adc 6 -9 83 csr dac
Note: Because of the convention of negative start-chan for csr,dac
these cannot be tied to a channel of an ADC, so one must use example 1
or 2, but not 3, in section 1 for the datamap line.
8. [evbuff-offset] -- optional field
If crate == 0 (or if there is a 'key' string in the crate field),
then the evbuff-offset is the absolute position of the index in
the event buffer for the data pertaining to the first key.
If crate != 0, then the evbuff-offset is the number which when added
to the index of the location of the header for that readout type.
These header indices are found automatically by "pan".
In either case, subsequent keys increment to index for where to
find the data.
9. [crate-number] -- optional field
The crate number (or ROC #). People who setup CODA should not make
a crate #0 (it is technically possible in CODA, but do not do it).
10. keys --
In the datamap, keys are unique labels of channels of raw data.
They are indexed in the code by indices in DevTypes.hh. See also
VaEvent::Decode() method.