geant4/examples/extended/persistency/PersistentEx01/README

$Id: README,v 1.8 2001/06/19 15:03:58 morita Exp $
-------------------------------------------------------------------

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

                       Example PersistentEx01
                       ----------------------

This example program demonstrates how users can use object database 
with Geant4 Persistency Manager with HepODBMS and Objectivity/DB.
Ask your local system manager for the availability of these
products on your system.

Users of this example are assumed to have the knowledge of
HepODBMS and Objectivity/DB.  Refer to the corresponding
documents and examples for detail usage and setups.
It is also recommended to read the Geant4 User's Guide:
"Object persistency" (in Chapter 3) and "Object-oriented database"
(in Appendix).

============
Introduction
============
PersistentEx01 demonstrates how to store event, run and geometry
objects into databases.  Only some skelton associations and basic data
members are stored in this release.

Event:
  Event ID and the informaion of the primary vertecies and particles
  are stored.  Hits are transient in this example, and therefore
  they are not stored.  See example PersistentEx02 to create
  persistent hits, 

Run:
  Run ID and number of events are stored in this release.

Geometry:
  Basic geometry types and volume informations are stored.  
  Note that the association to materials is not supported in
  this release.  Material names are stored instead.

There are two types of database transactions in the Geant4
persistency.  Non-sustained transaction, which is used in this
example as a default, stores Geant4 persistent objects
at the end of each event as an atomic database transaction.

If user wants to create his/her own persitent objects in
the user event action class or in any other user classes,
he/she should explicitly use StartTransaction() and
Commit()/Abort() of the G4PersistentManager.  See
PersistentEx02 for an example of the sustained transaction.

=====
Setup
=====
In addition to the standard Geant4 setup, additional setup for
LHC++, HepODBMS and Objectivity/DB are required.
Here are the required variables:

   G4USE_HEPODBMS      <"1" for compiling Geant4 persistent libraries>

   HEP_ODBMS_DIR       <root directory for HepODBMS>
   HEP_ODBMS_INCLUDES  <include file directory for HepODBMS>

   OBJY_VERS           <Objectivity version>
   OBJY_DIR            <root directory for Objectivity/DB>

   OS                  <"Solaris", "Linux", "HP-UX" etc used by HepODBMS>

   PATH                <add "${OBJY_DIR}/bin" and "${OBJY_DIR}/doc">
   MANPATH             <add "${OBJY_DIR}/man">
   LD_LIBRARY_PATH     <add "${OBJY_DIR}/lib">

Following variables are optional (used by HepODBMS GNUmakefiles):

   LHCXXTOP            <root directory for LHC++>
   PLATF               <LHC++ architecture type on CERN AFS>

____________________________________________________________________________

For CERN AFS users, an example setup script "g4odbms_setup.csh" and
"g4odbms_setup.sh" is provided in this directory.

For csh users, copy "g4odbms_setup.csh" to your local directory, edit 
the version numbers of HepODBMS and Objectivity if needed, and put a line 
such as

   source g4odbms_setup.csh

in your .cshrc file.

For zsh and alike, copy "g4odbms_setup.sh" to your local directory, 
edit the version numbers, then put a line such as

   . g4odbms_setup.sh

in your .zshrc etc...
____________________________________________________________________________


=======================
Objectivity Lock Server
=======================
Make sure that your system is running Objectivity/DB lock
server.  Ask your local system administrator for the location of
the lock server.

If you own your machine, or if you know you are the only user of
Objectivity/DB on your system, you may start your own lock server by:

  oocheckls -notitle `hostname` || oolockserver -notitle -noauto

See the note below for more detail about the lock server.

======================================
Installing Geant4 persistent libraries
======================================
Persistency in Geant4 is designed to be as an optional sub category.
If the installation of Geant4 has been made without the variable
G4USE_HEPODBMS defined, you must re-install it from the
source directory.

  cd ${G4INSTALL}/source
  setenv G4USE_HEPODBMS 1
  gmake 

This will generate persistent granular libraries such as
libG4pmanegement.a, libG4phits.a, etc, in the Geant4 library directory.
This process will also produce schema files in ${G4INSTALL}/schema.

Make sure that you have set up proper combination of HepODBMS and 
Objectivity/DB versions before you build the persistency libraries.
Users of this installation must use the same versions of schema
for building their applications.

=========================================
Your boot file and federeated database ID
=========================================
Geant4 provids a base boot file which contains database schema 
information of Geant4, HepODBMS and Objectivity/DB persistent
classes.  When you compile your application with your own 
persistent classes, you must copy the Geant4 schema boot file
to your local area and process your schema files into
your boot file.  In this example, schema of the example files
are stored into G4EXAMPLE_BOOT, which is located at
${G4WORKDIR}/exampleSchema/${G4SYSTEM} by default.

When you run your application and populate the database,
copy the schema into runtime federated database G4EXAMPLE_FD.
This is located at ${G4WORKDIR}/exampleFD/${G4SYSTEM} by default.

To run the runtime federate database concorrently on the same
lock server, each copy of the boot file must have a unique 
Federated Database ID (FDID).  Ask your local system manager for
the unique FDID on your system, then assign it to

  setenv G4EXAMPLE_FDID  <your federeated database ID>

for example.
___________________________________________________________________________
Note: On CERN AFS, contact your group system administrator to obtain access
      to your group lock server.  Generally it is recommended to stay away
      from the production lock server when you are building your own
      application.  Use development lock server or use your own
      to avoid unintentional locks being left on the production lock 
      server.

      To start your own lock server, type

         oocheckls -notitle `hostname` || oolockserver -notitle -noauto

      Check the lock server with

         ps -ef | grep ools
         ....
         <user>  60156      1   0 06:36:40 pts/15  0:00 ools -OO_NO_AUTOREC
         ....

      To kill the lock server,

         ookillls
      or
         kill -9 <pid_of_ools>

      You must have AFS ACL access to HepODBMS and Objectivity/DB
      directories.

      At CERN, the FDID allocation table is given in this URL:

      http://wwwinfo.cern.ch/asd/rd45/white-papers/9804/FDIDAllocation.html
___________________________________________________________________________

=========================
PersistentEx01 executable
=========================
PersistentEx01 executable can be made by simply typing "gmake" in this
directory.  Use PersistentEx01run csh-script for a simple test.

example:
   gmake                # creates PersistentEx01 executable
   PersistentEx01run    # run PersistentEx01

=================
Persistent output
=================
When PersistentEx01 is run correctly, following database files will be
created in your federated database directory $G4EXAMPLE_FD_DIR.

Events.PersistentEx01.DB       Geometry.PersistentEx01.DB  
PersistentEx01                 PersistentEx01.FDDB         
Runs.PersistentEx01.DB         System.PersistentEx01.DB

To browse the database contents, use tools such as "oodump" or "ootoolmgr".

  oodump -notitle -db Events   $G4EXAMPLE_FD
  oodump -notitle -db Geometry $G4EXAMPLE_FD
  oodump -notitle -db Runs     $G4EXAMPLE_FD

  setenv DISPLAY <your_x_terminal>:0.0
  ootoolmgr -notitle $G4EXAMPLE_FD

Make sure to quit the ootoolmgr when you finish browsing.
Otherwise the transaction lock will remain in the lock server 
and the further updates to the database will be blocked.

==========================
readDB, createTag, readTag
==========================
Simple HepODBMS example applications are provided in this directory.
These examples demonstrate how to access the stored Geant4 event objects.
See the corresponding README for more detail.

==========================
Changing the database name
==========================
To work on different set of federated database, change the
definition of OO_FD_BOOT variable defined in PersistentEx01run.
Use $HEP_ODBMS_DIR/etc/getdb to create a new federeated database.

To change the database name within the federation, and to
change the verbose level of G4PersistencyManager, following
runtime commands are supported.

  /db/verbose   * Set the verbose level of G4PersistencyManager.
  /db/run       * Set the name of Run Database.
  /db/event     * Set the name of Event Database.
  /db/geometry  * Set the name of Geometry Database.

Here is the example of changing database names in the macro
file PersistentEx01.in.

     # -------------------------
     #
     #  PersistentEx01.in
     #
      .....
     /db/run NewRuns
     /db/event NewEvents
     /db/geometry NewGeometry
      .....
     # -------------------------

--