$Id: README,v 1.7 1999/12/05 22:22:25 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 HEP_ODBMS_INCLUDES OBJY_VERS OBJY_DIR OS <"Solaris", "Linux", "HP-UX" etc used by HepODBMS> PATH MANPATH LD_LIBRARY_PATH Following variables are optional (used by HepODBMS GNUmakefiles): LHCXXTOP PLATF ____________________________________________________________________________ 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.csh" 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 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 .... 60156 1 0 06:36:40 pts/15 0:00 ools -OO_NO_AUTOREC .... To kill the lock server, ookillls or kill -9 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 :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 ..... # ------------------------- --