D0 GROUP LEVEL3
ONLINE LESSONS

Episode VII
D0om

by Gustaaf Brooijmans

This is an episode with little work. It tells you about d0om and persistency, something you're going to run into sooner or later.

This episode is meant as a minimal introduction to d0om - please read the d0om user guide (found in $BFDIST/packages/d0om/...) for more information.

To start off, what is d0om? d0om is an interface to i/o packages a bit like HepTuple is an interface to histogramming packages. This means that you can write your code now using d0om, and change your i/o package later (or anytime) without significant changes in your code.

As far as developing level 3 tools goes, we will not use d0om in that code. However, a lot of code might be inspired from or tested with offline reconstruction code, such that it is useful to have some knowledge about d0om.

Before addressing the technicalities, I think it's good to say a few words about how d0om works: d0om will store objects in association with their names, not simply in order (like, for example, ZEBRA). This means you can write out data with one version of your program and read it with another without major problems - objects which no longer exist will be ignored and new ones will be set to 0 (zero) when the data is read in. Therefore, to avoid recreating a new object with a different meaning but the same name, it is adviseable to comment out objects which are no longer desired rather than delete them from the code.

Note that d0om already supports multiple i/o packages: DSPACK and an MSQL-readable database format are the most important.

The objects d0om can write out are called "persistent". For objects to be persistent, they have to be members of a persistent class and be of persistent types. A class is made persistent by inheriting from d0_Object (defined in #include "d0om/d0_Object.hpp") - or another persistent class - and it has to have the macro D0_OBJECT_SETUP(myclass); as one of its members. Objects in a persistent class are by default persistent if they are of one of the allowed types (see below), and transient if not.

The main allowed data types are:

• the standard and d0om atomic types (int, d0_Int, double, d0_double, etc.)
• standard and d0om container classes (list, d0_List, vector, etc.) Note that classes stored in d0om containers should implement the default constructor, copy constructor, destructor and any method required by the container (like < for example).
• The standard and d0om string class - usually it is necessary to include d0_util/d0_String.hpp before most other include statements to fix problems with string implementations (even if only standard strings are used).
• C++ bare pointers and d0om reference classes (d0_Ref<T>) (note that they have to point to persistent objects). The d0om reference class provides more functionality than a pointer and is recommended.

If a type is by default persistent but you don't want it to be written out, you can make it transient in two ways: the first is to mark it transient by declaring it with
# pragma transient member-name
Note that this should probably be hidden from anything but cint by enclosing it in an #ifdef __CINT__ block (see below). Example:

class test : public d0_Object
{
int a;
int b;

#ifdef __CINT__
# pragma transient a
#endif
}
// but this can be declared outside the class declaration
#ifdef __CINT__
# pragma transient test::b 
#endif

Another way to make an object transient is by including a comment starting with //! on the same line:

int b; //! b is transient.

Ok - so my class is persistent - now what? I'll only describe the use of d0om with ctest here, and I'm not going to talk about actual writing to file - see d0om user guide, p. 32 for that. (It would get a bit long and it's not really appropriate here).

With ctest: update your package to use d0om (ctnewpkg -ud). This will create a file D0OM_COMPONENTS in your src directory. In this file, list the filenames of those files containing classes you want to make persistent (as usual, without suffixes).

For an example, see package ctexample_d0om (in $BFDIST/releases/$BFCURRENT/ctexample_d0om).

Now when you've done all that, and run gmake xxx.test, you will see something like:

Compiling D0OM linkage doomtest_lnk
a - /d0chb/home/room1/gusbroo/l3test/l3main/tmp/IRIX6-KCC//l3res/doomtest_lnk.o

This is a "linkage" file, compiled from doomtest_lnk.cc which has been produced by the cint interpreter to prepare persistent objects for writing. This file will be included when linking the program to make the objects persistent. If there's anything in your .hpp file that you don't want cint to see, enclose it in:

#ifndef __CINT__ // (that's a double underscore)
  // This will not be persistent
#endif

Ok, I think this is most of it. Feel free to send me any questions or comments you might have.