     =========================================================
     Geant4 - an Object-Oriented Toolkit for Simulation in HEP
     =========================================================

                            ExampleR05
                            ----------

31-Oct-2000 Bill Seligman (seligman@nevis.columbia.edu)

The intent of this example is to show how one might use the
RecorderBase class with ROOT to create persistent I/O from Geant4.

This example is based on two previous examples:

-- $G4INSTALL/examples/novice/N02 as found in Geant 4.2.0.  If the
   name of a file or routine contains "N02", then it is unchanged from
   that example.

-- exampleR04 from the Nevis LAr software effort
   <http://www.nevis.columbia.edu/~atlas/lar/>.

If you run "exampleR05 exampleN02.in", the file exampleR05.root will
contain four ROOT Trees with events from each run.  Each event record
contains a collection of hits found in the example tracker for that
event.

The sample ROOT macro can be executed by the command "root exampleR05.C".  
The example does a lot, and you'll want to read exampleR05.C to see
how it does it.  Briefly, the macro:

-- loads the Event and Hit classes defined for
this example from a shared library (type ".class ExR05RootEvent" and
".class ExR05RootHit" to check this);

-- reads a Tree from file exampleR05.root;

-- demonstrates the difference between reading an entire event versus
just a single branch;

-- histograms the z-distribution of hit energies for a single run;

-- generates HTML documentation for our new classes.


If you want to work from this example to use ROOT as the persistency
mechanism for your application, here's the general procedure:

-- Design the ROOT classes that will contain the G4 information you
wish to store.  These classes must only use ROOT data types; no
templates, no STL, no G4 classes.  ExR05RootEvent and ExR05RootHit are
the two ROOT classes in example R05.

-- Edit the GNUmakefile for the ROOT compilation of your new classes.
Note that you will be editing the execution of a "rootcint" command
that will create a ROOT dictionary for your classes; both the source
and the header (a ".h" file) will be placed in the ./src directory.
Also note the creation of a shared library near the end of the
GNUmakefile; the dictionary's object file must be part of the library.

-- Create "conversion classes" that inherit from your classes.  These
should take a G4 class and convert it to the ROOT version.  In this
example, these classes are ExR05PersistentRootEvent and
ExR05PersistentRootHit.

-- Use a class inherited from RecorderBase (or code three of your own
user action classes) to open a ROOT file, and create a ROOT Tree with
branch(es) for the ROOT classes.  Write your classes by "filling" the
Tree.  In this example, all of the persistency aspects are isolated
from the rest of G4 in class ExR05RootPersistency.

-- The ROOT file can be read by the "root" program, or you can call
the ROOT functions from a program of your own.  An example of the
former is shown in exampleR05.C.
