Hall A Analyzer

h1. Podd 1.5 to 1.6 Database Conversion

In Analyzer 1.5 and earlier, many (but not all) detector classes employed fixed-format database files. These are problematic for a number of reasons: they are prone to errors, hard to extend, inefficient with time stamps, not readily transferable to non file-based database systems, etc. To address this problem, all modules (detectors, spectrometers, physics modules etc.) in Analyzer version 1.6 use the LoadDB database API. LoadDB expects database files in free-form key/value format.

To help users convert their existing databases to the new format, which could be a non-trivial and potentially very time-consuming task, we have written an automatic conversion tool called dbconvert. To build this tool, proceed as follows

* Ensure that the analyzer has been built properly

* Point the environment variable ANALYZER to the top-level installation directory. For example, if you have installed the distribution in ~/analyzer-1.6.0, do

<pre>

% export ANALYZER=~/analyzer-1.6.0

</pre>        

or for tcsh users (JLab CUE)

<pre>

% setenv ANALYZER ~/analyzer-1.6.0

</pre>        

* Now build dbconvert

<pre>

% cd $ANALYZER/utils

% make

% cd ..

</pre>

Once built, the tool allows you to convert an entire directory tree of database files to a new directory tree of free-format files. Before starting, make sure you have a backup of your old databases. Assuming the old databases are stored under $DB_DIR, back them up and write-protect them:

<pre>

% cp -av $DB_DIR DB_backup

% chmod -R -w DB_backup

</pre>

Now you can convert the files in $DB_DIR simply like this

<pre>

./utils/dbconvert $DB_DIR newDB

</pre>

where newDB is the name of the output directory. That directory will be created if it does not exist. Treat it like scratch space; the name can always be changed later. If the target directory does exists, all database files in it will be erased after asking for confirmation.

dbconvert has to make assumptions about what detector each database files belongs to. To do so, it uses a mapping from typical detector names to detector types. For example, databases with detector name "R.s1" are interpreted as belonging to THaScintillator or derived classes. You can inspect the full name mapping in the source code of dbconvert.cxx in function DefaultMap(). To change this map, you currently have to edit the source and recompile; we are planning to make the mapping user-configurable in a later version. This is important to know in case you are using custom names for some detectors in your experiment. dbconvert is unlikely to know about them. To have these files converted automatically, you will need to edit the list.

Of course, if you have written an entirely new custom detector with its own database format, dbconvert will not have a conversion function. In that case, no worries. In general, you do not need to convert databases for your own custom-written modules. Even with Analyzer 1.6, you can do whatever you want in the ReadDatabase functions of your own modules, and things will continue to work as before. Using the new database system is strongly encouraged, however, for all new development. Eventually, we might use different database backends, and your old-style code would not be able to take advantage of those new features.

*Caution:* dbconvert is still under development at this time (Feburary 2018). Bugs may cause incorrect conversions. Additional features may be added that improve the conversion results (formatting, version indicators, etc.) It goes without saying that you must keep backup copies of your original database files so you will be able to re-run the conversion at a later time. You should also use version control with your converted databases so you have a record of any edits you made. Do spot-checks of your converted databases for apparent errors and file a bug report if necessary.

Below is a summary of options currently understood by dbconvert:

<pre>

Usage: dbconvert [options] SRC_DIR DEST_DIR

 Convert Podd 1.5 and earlier database files under SRC_DIR to Podd 1.6 and 

 later format, written to DEST_DIR

Options:

 -h, --help                   show this help message

 -v, --verbose                increase verbosity

 -d, --debug                  print extensive debug info

 -p, --preserve-subdirs       preserve subdirectory structure

     --no-preserve-subdirs    don't preserve subdirectory structure (negates 

                                -p)

     --no-clean               don't erase all existing files from DEST_DIR if 

                                it exists

     --no-verify              don't ask for confirmation before deleting any 

                                files

 -s, --subdirs ARG            split output files into new set of sudirectories

                                given in ARG. ARG is a comma-separated list 

                                of directory names which must be in YYYYMMDD 

                                format. Overrides -p.

 -z, --input-timezone ARG     interpret all validity timestamps in the input 

                                that don't have a timezone indicator to be in 

                                timezone ARG. ARG may be the name of a 

                                system timezone file (e.g. 'US/Eastern'), 

                                which supports DST, or a fixed offset 

                                specified as [+|-]nnnn (e.g. +0100 for central

                                European standard time). The default is to use

                                the current timezone at run time.

     --output-timezone ARG    write all output timestamps relative to timezone

                                ARG, specified in the same way as 

                                --input-timezone. The default is to use the 

                                current timezone at run time.

</pre>

As mentioned before, additional features are expected to be added over the next several months as we test and improve the program.