Getting started with the BABARDatabase
Version Information
Original:
Draft: 8th June 1998
This document is still under development. If you have any questions or comments, please address them to David Quarrie (DRQuarrie@LBL.Gov).
This document describes how to get started using the BABAR database. It is designed as a beginners guide and so
is not complete, but should serve to get the vast majority of non-experts started. Much of the information contained here is abstracted from other more detailed documents so these should be referred as the first source of additional information. This
introduction also serves to introduce the concepts.
The references marked with [*] are not directly accessible via the Web. Please contact the people referred to on the Objectivity
Installation page directly for instructions how to access the documentation.
Return to Table of Contents.
The following concepts should be understood by all database users and developers:
- Persistent or persistent-capable Object. A persistent-capable object is one that inherits from BdbPersObj. A persistent object is an instance of a persistent-capable object that has been created using the overloaded
new operator with a placement hint, or the BdbNew(T) database macro. The BABAR coding rules disallow the creation of a transient instance of a persistent-capable object.
- Schema. This is a description of the class types that are defined. BABAR uses C++
classes which are defined in Data Definition Language (DDL) Files, having a .ddl suffix. Each class so defined is allocated a unique Schema ID (SCID). Named Schema allow sets of
classes to be assigned within a well defined range of schema IDs such that distributed development may take place.
- Pages. A page is the unit of transfer between a file server and the client application. It may be in the range of 4096 to 65536 bytes in size, and is determined by the database
designers.
- Database ordatabase file. Each persistent object is created in an Objectivity database. Currently each database corresponds to a Unix file, although this
one-to-one mapping is expected to be removed in a future release of Objectivity. Each database is associated with a particular file server (see later) and is identified both by its file system location and by a unique Database ID
(DBID).
- Federated Database or Federation. This is a set of related database files and objects that can be accessed by a single application. Each federation consists of
possibly multiple databases distributed across multiple file servers, together with the schema definitions. Each federation is identified by a Federated Database ID (FDID).
- Lock Server. This is a process running on a designated computer that manages concurrent access to the databases. No data passes through the lock server, but it ensures that data within
the federation is consistent and prevents simultaneous updates from multiple clients.
- File Server. Two sorts of file systems are supported by the BABAR database. The
first is local file systems, attached directly to the computer upon which the client application resides. The second is remote file systems, attached to remote computers. Such file systems are accessed via the Advanced Multi-threaded Server (AMS) by a
network protocol. AMS is a daemon that has to be installed on the file server machine by a system administrator. NFS or AFS file systems are not supported apart from the Boot File (see later).
- Boot File and Federated Database File. The Federated Database File contains the schema definitions and database catalog for a Federation. By
BABAR convention it is called BaBar.FDDB and is located on the Catalog Server. The Boot File is a file that describes the federated
database configuration, the location and file server of the Federated Database File, the Federated Database ID, lock server node and other parameters describing the federation. In principle the Boot File is the only file that must be directly visible to
the client applications and is used to bootstrap the applications. By BABAR convention the boot file is called BaBar and should reside on a file system that
is visible to all desired client computers. Unlike the other database files it may reside on a NFS or AFS file system.
- Persistent Object References. One persistent object may reference another persistent object. Such references may span databases if the two objects reside within different
databases.
- Clustering or placement. Objects may be created close together in the federation, based on their predicted access patterns. Thus, if two objects are typically accessed together,
clustering them in the same database will minimize tape-mounts in the mass store, and placing them on the same page will improve access by pre-fetching the second one when the first one is accessed, minimizing I/O traffic.
- Production, Reference andDeveloper Federations. Several different federations are created and maintained by BABAR.The Reference Federation is created by the software release system and contains no databases, only schema definitions. The
Production Federation is identical to the Reference Federation except that it also contains the production catalog of databases & persistent objects. Each developer may create their own Developer Federation by
importing schema from the Reference Federation and then adding their own schema and data.
Return to Table of Contents.
The following set of operations must be performed when wishing to use the BABAR database. They are described in
more detail in the following sections.
Return to Table of Contents.
Before the BABAR database can be used, the Objectivity Object Database Management System (ODBMS) must be installed at your site. Your BABAR computing site contact person should already have performed this, so
contact them for details on the location of the installation. Site Administrators should refer to the "Administrator's Guide to the BABAR Database" document.
Before a BABAR collaborator is allowed access to this software, they must read a license agreement form, sign it and return it to Charlotte Hee at SLAC.
Details of the installation and access procedures are given at the Objectivity Installation page at the following URL:
/BFROOT/www/Computing/Offline/Databases/Docs/objyInstal.html
Return to Table of Contents.
In order to access the BABAR database, the correct set of environment variables and search paths needs to be setup.
Environment variables that are necessary at software release build time are:
- BFARCH. The required setting of this is dependent on the base release that's being used. For releases 6.3.1 and later, the required setting is one of:
AIX4
OSF1V4
SunOS5
For earlier releases it should be set to one of:
AIX4-native-Objy
OSF1V4-native-Objy
SunOS5-native-Objy
In order to use Objectivity, several environment variables need to be setup. This is performed automatically for SLAC accounts using the recommended HEPiX login environment and so little explicit customization is
necessary in the login scripts (.login and .cshrc). One customization that might be necessary is to modify the default value of the BFARCH environment variable if that is not
one of the appropriate values above. This can be done by setting the BFARCH environment variable by hand and using the srtpath command to setup the development environment:
setenv BFARCH AIX4
srtpath 6.7.2 $BFARCH
Use of the HEPiX environment at SLAC is described in the document "BABAR Login Scripts".
For sites other than SLAC, the login environment is likely to be different. Check with your local BABAR
software administrator. The following C Shell code fragment is an example of setting the required environment variables for a particular location of the Objectivity distribution (in this case /usr/object) and machine architecture
(IBM AIX).
setenv OBJY_DIR /usr/object/ibmrs6000
setenv PATH "${PATH}:${OBJY_DIR}/bin"
if ( "$?MANPATH" == 0 ) then
setenv MANPATH "${OBJY_DIR}/man"
else
setenv MANPATH "${MANPATH}:${OBJY_DIR}/man"
endif
if ( "$?XUSERFILESEARCHPATH" == 0 ) then
setenv XUSERFILESEARCHPATH "${OBJY_DIR}/etc/app-defaults/%N"
else
setenv XUSERFILESEARCHPATH "${XUSERFILESEARCHPATH}:${OBJY_DIR}/etc/app-defaults/%N"
endif
if ( "$?XBMLANGPATH" == 0 ) then
setenv XBMLANGPATH "${OBJY_DIR}/etc/bitmaps/%N/%B"
else
setenv XBMLANGPATH "${XBMLANGPATH}:${OBJY_DIR}/etc/bitmaps/%N/%B"
endif
Return to Table of Contents.
The GetFDID command may be used to determine the base of range of federated database IDs that have been allocated to each developer. Five such ids have been assigned to each developer and
should be used for all their development. This avoids any potential interference between developers.
The GetFDID command can only be run at SLAC, but the range of federated database IDs should be used for any BABARsoftware development, even at remote sites such as IN2P3.
Syntax:
> GetFDID -h
usage: GetFDID [options] [<user>]
Prints out the range of five Objectivity Federated Database ID numbers
assigned to <user> (defaults to current user) for use in development.
Options are from among:
-h Prints this message.
-s Prints only the first number of the range.
> GetFDID
The five FDID numbers assigned to quarrie are 16855 - 16859.
> GetFDID -s becla
26200
Return to Table of Contents.
Consult with your local database system administrator for a suitable location and file server machine for your test federation. Multiple such test federations may be created, but they must be totally distinct,
having different locations, even if they share the same boot file server.
Several sites provide default locations; consult your local database administrator for information about this. As examples, the default locations for SLAC and LBNL are described in the "Working with BABAR Database Makefiles" document. These
default locations should be adequate for most developers, unless they wish to work with several test releases simultaneously. A possible strategy for this latter case is also described in the "Working with BABARDatabase Makefiles".
The following restrictions and limitations apply:
- The Boot File should be located on a file system that is accessible from all desired client computers. Ideally it should have the same location when viewed from such computers, and may reside on an AFS or NFS file
system.
- The Federated Database File should be located on either a local file system (if development is restricted to the single computer), or on an AMS-served remote file system if development is going to take place
from multiple machines. In the latter place the file system must also be directly visible from all computers where test releases (see next section) are to be built. This is a temporary restriction that will be removed in a
future release of the BABAR database software. A suitable configuration is to NFS-mount the remote file system on all client machines, as well as running the
AMS server.
The Section "Run-time Environment Variables" describes the environment variables that must be set at run-time.
Return to Table of Contents.
This is described in detail in the "Working with BABARDatabase Makefiles" document so only a brief description will be given here.
- Ensure that the BFARCH and BFSITE environment variables are setup correctly.
- Create a test release based on an existing BABAR database software release using the
newrel SoftRelTools tool. The following uses release 5.3.2 for demonstrative purposes only.
> cd <dir>
> newrel -t 6.7.2 rel672
> cd rel672
- Create a.bbobjy file in the test release directory. Depending on the desired boot file server and location and any site-specific defaults that might have been setup by your local system
adminstrator, this file will need an entry corresponding to the FD_NUMBER (Federated Database ID). It might also require entries specifying the boot file server and location etc. Note that the FD_NUMBER must be supplied and should be one
of the range reserved for you. Use the GetFDID command (at SLAC) to determine what that range is.
A minimal .bbobjy file consists of a single line defining the FD_NUMBER (do not use the number below, it's just for illustrative purposes):
FD_NUMBER = 12345
- Check that a sensible configuration has been setup using the gmake database.config command:
> gmake database.config
- Add packages to your test release in the normal manner using the addpkg command.
- Optionally import the federated database from the production release using the gmake database.import
command. This will be initially empty apart from the schema definitions and a minimal initialization as described in the Section "Loading the database". These actions will also be performed automatically if a plain gmake is
initiated instead of gmake.database.import.
> gmake database.import
- For Release 5.6.1 you need to load the database manually after it's been imported. This is automatic for later releases.
- Do your normal development.
Return to Table of Contents.
The only necessary run-time environment variable is OO_FD_BOOT, which should be set to the location of the Boot File. At SLAC and at some other sites, the setboot
command has been created to enable this to be done easily:
> cd rel672
> setboot
OO_FD_BOOT set to /nfs/objyserv1/u3/ec/stage/objy/quarrie/BaBar
This command is valid in the context of a test release directory or immediate subdirectory therof (including workdir/) after a database has been imported.
If setboot is not defined at your site, it can be specified in your own login environment as:
alias setboot "source $BFDIST/releases/newest/SoftRelTools/SRTsetboot.csh"
A final alternative is to set the OO_FD_BOOT environment variable explicitly. The appropriate location can be determined using the gmake database.config command and setting the environment variable to the BOOT_FILE location. The following locations are for
illustrative purposes only and should not be used.
> gmake database.config
config:
Boot file (BOOT_FILE) /nfs/objyserv1/u3/ec/stage/objy/quarrie/BaBar
FDDB (FDB_DIR/FDB_NAME) /nfs/objyserv1/u3/ec/stage/objy/quarrie/BaBar.FDDB
AMS Server (AMS_HOST) objyserv1.slac.stanford.edu
Lock Server (LOCK_HOST) objyserv1.slac.stanford.edu
FDDB ID (FD_NUMBER) 1301
Page Size (PAGE_SIZE) 8192
Import Directory /afs/slac.stanford.edu/g/babar/dist/releases/5.4.1/database/export
Import boot file BaBarRef
Import FDDB BaBarRef.FDDB
Export FID 5799
> setenv OO_FD_BOOT /nfs/objyserv1/u3/ec/stage/objy/quarrie/BaBar
However, using the setboot command is the preferred method of setting this environment variable.
If multiple test releases are in use simultaneously, take great care that this environment variable corresponds to the particular test release that is currently in use.
Return to Table of Contents.
Even when attempting to read event data from BBSIM generated .xdr files, it is necessary that some initial configuration information be loaded into the database. This database initialization is performed
automatically when the database is imported into your test release, but can also be performed manually using the gmake database.load
command.
This action is not necessary for releases later than 5.6.1 since the database is loaded automatically by the gmake
database.import command. However, it is possible to inhibit this automatic loading (via gmake database.import BYPASS_LOAD=yes) and this command allows it to be performed later.
> gmake database.load
Return to Table of Contents.
Several utilities are provided by which you may examine the contents of your databases. We intend to augment those provided by Objectivity with BABAR-specific ones. These utilities are described in the Objectivity documentation which is available online if you have signed the Objectivity license agreement. Unfortunately the licensing agreement does not allow us
to provide direct links to this documentation from here.
Perhaps one of the most useful utilities is ootoolmgr, which allows both the data and schema of a federation to be viewed. This is an X application, so the
DISPLAY environment variable must be set correctly as do the XUSERFILESSEARCHPATH and XBMLANGPATH environment variables described in the Section "Creating the necessary environment" above.
[This section incomplete.]
Return to Table of Contents.
Great care should be taken before deleting a federation. In particular, do not use the Objectivity oodeletefd utility. Use the gmake database.deleteboot to perform the operation:
> cd <TestRelease>
> gmake database.deleteboot DEFINE_BOOTFILE_RULES=yes
Note that this command is protected by the DEFINE_BOOTFILE_RULES=yes flag. This is another level of protection to ensure that you really mean to do what you are attempting to
do.
Return to Table of Contents.
The BdbConverters package contains both a database input module (BdbEventInput) and output module (BdbEventOutput). These provide a
mechanism whereby a database may be loaded with simulated events from bbsim .xdr files (next Section) or may input events that already exist in the database, perform processing on them and save the processed information to the
database.
Both modules have string parameters "collectionName" that allow the input or output event collection name to be specified at run-time. In releases prior to 6.7.0, overriding the default
must be performed during the initialization phase of the job and before any events are processed and only a single collection may be specified. In subsequent releases, the collection name may be specified at any time and a subsequent "events
begin" command will utilize the currrent collection name. Multiple collection names are therefore supported.
> module talk BdbEventInput
BdbEventInput> collectionName set newName
BdbEventInput> exit
> events begin
The database output module also supports the concept of a master collection to which several output collections generated by different jobs may be attached. This master collection may be
used as an input collection for later jobs in order to iterate over all the events from the different output collections.
> module talk BdbEventOutput
BdbEventInput> masterName set aMasterName
BdbEventInput> exit
> events begin
Note that only a single output collection may be attached with a master collection for any one job. This is the last output collection that is specified in the job. This restriction may be removed in a future
release.
Return to Table of Contents.
The BdbConverters package builds two applications, BdbIOApp and bdbLoader. The former is an example of an generic application that can
execute against both events in the database or simulated events in bbsim .xdr files. The latter, bdbLoader, is an example of a stand-alone database loader that is preconfigured to load the database with the contents of an .xdr
file. A Tcl file, BdbConverters/bdbLoader.tcl, controls the application, loading the database from the default bbsim.xdr file, but it could easily be extended to load the database from multiple bbsim
files.
The bdbLoader application is designed to be executed from the workdir, and so requires that this package is present and configured in your test
release:
> cd <ReleaseDir>
> addpkg workdir
> gmake workdir.setup
The following assumes that you're running the version of bdbLoader from the underlying base release, but an alternative would be to add the BdbConverters package
to your test release.
> cd workdir
> bdbLoader $BFDIST/releases/$BFCURRENT/BdbConverters/bdbLoader.tcl
or
> addpkg BdbLoader
> cd workdir
> bdbLoader ../BdbConverters/bdbLoader.tcl
It is possible that the bdbLoader application may not be functional for a particular release and hardware platform. We need to come up with a URL that users can refer to to determine which combinations
should work.
This application & Tcl file have moved between the BdbModules & BdbConverters packages over time. The above refers to the BdbConverters package. Look in the BdbModules package if the files
aren't found in the BdbConverters package.
Return to Table of Contents.
[This section missing.]
Return to Table of Contents.
It is possible to run jobs that access events from someone else's federation. The following steps must be taken:
- Set the OO_FD_BOOT environment variable to the appropriate value that references their federation. This can be done using the setboot command in the context of
their test release directory, or by setting the OO_FD_BOOT environment variable directly.
- Collection names must be fully qualified when referencing them. Fully qualified collection names are prefixed with /users/<username>/ before the unqualified name.
Thus if I run a job in my federation under account quarrie that creates an output collection called QuarrieEvents, someone else running under their account name
but with my federation will have to use the following commands in order to access those events:
> module talk BdbEventInput
BdbEventInput> collectionName set /users/quarrie/QuarrieEvents
BdbEventInput> exit
> events begin
Return to Table of Contents.
[This section missing.]
Return to Table of Contents.
[This section missing.]
Return to Table of Contents.
[This section missing.]
Return to Table of Contents.
There may be occasions when your application "hangs" unexpectedly. One occasion when this is possible is following an interactive session with the debugger. This is typically due to a transaction not being
committed and hence a transaction lock being retained. The status of any outstanding transaction locks may be determined through use of the gmake
database.status command:
> gmake database.status
status:
Boot file (BOOT_FILE) /nfs/objyserv1/u3/ec/stage/objy/quarrie/BaBar
[display of transaction locks omitted]
This will identify any outstanding transactions, together with the machine name and process ID from which they were initiated. In order to cleanup from any outstanding transactions, log onto the indicated machine
and use the gmake database.cleanup command:
> gmake database.cleanup
cleanup:
Boot file (BOOT_FILE) /nfs/objyserv1/u3/ec/stage/objy/quarrie/6.4.1/BaBar
cleanup: Attempting to cleanup locks etc...
[display of cleanup attempt omitted]
This will attempt to cleanup outstanding transactions that were initiated from this machine. Repeat this procedure from each machine if necessary.
Consult with your local database administrator if you are still unable to cleanup successfully. As a last resort, change to using another one of your 5 reserved FDDB ID numbers (Section "Assign a
Federated Database ID") until the cleanup has been performed. However, this should be treated as an extreme case and every effort should be made to cleanup beforehand. If you resort to this, please inform your database administrator so that they can
attempt to recover the lost FDDB ID.
Return to Table of Contents.
[This section missing.]
Return to Table of Contents.
DB Home | BaBar Home | Computing | Online | Reconstruction |
Simulation | Search
 DRQuarrie@LBL.Gov
|
