STAR  Computing Tutorials main page
How to Use StTpcDb 
Offline computing tutorial  Maintained by David Hardtke
What is StTpcDb?

StTpcDb is a utility that allows one to access the TPCdatabase information in a simpler way.  In addition,
it hides the underlying implementation details from the user.  All database information is served via a set
of abstract interfaces.  The interfaces will stay the same even if the offline infrastructure changes.  The
necessary modifcations are done behind the scenes, and the user need no longer worry that the next
release of the STAR offline software will break his/her code.

In addition to serving data directly from the database, StTpcDb is used to create derived quantities that are useful from an offline standpoint but that do not come directly from measurements.  One other function of StTpcDb is to replace the tpg geometry transformation packages that were previously used in the tpc reconstruction and simulation code.  StTpcDb wraps the necessary database information in fortran callable C-style functions.
 

How to use StTpcDb:

StTpcDb comes in two parts: StTpcDbMaker and StTpcDb.  StTpcDb is the utility that allows one to access the database.  StTpcDbMaker serves to initialize StTpcDb in bfc and contains the fortran callable C-Style functions.

Intializing StTpcDb:
StTpcDb is initized automatically with the standard chain.  The chain option is
"tpcDB", but this option is invoked whenever chain option "tpc" is invoked.  Optionally, one can create a simple chain with StTpcDb.  An example is shown in $STAR/StRoot/macros/test/tpcDbTest.C.  This simple macro creates a chain, adds an instance of St_db_Maker and an instance of StTpcDbMaker, and
performs the Init() and Make().  Note that St_db_Maker does the actually work (i.e. negotiation with
the mySQL database).  StTpcDb is a (purely optional) abstract layer on top of the datasets associated
with St_db_Maker.

StTpcDbMaker Functionality:
1) Create an instance of StTpcDb
2) implement C-Style fortran functions
3) return pointer to StTpcDb using function tpcDbInterface()

StTpcDb Functionality;
1) return abstract interfaces:
   public:
    StTpcPadPlaneI* PadPlaneGeometry();
    StTpcWirePlaneI* WirePlaneGeometry();
    StTpcDimensionsI* Dimensions();
    StTpcSlowControlSimI* SlowControlSim();
    StTpcElectronicsI* Electronics();
    StTpcGainI* Gain(int sector);
    StTpcT0I* T0(int sector);
    St_Table *getTpcTable(int i);
    //small pieces of data:
    float DriftVelocity();
    float triggerTimeOffset();
2) Create/manange real implementation of abstract interfaces.  Note that a table is generally not retrieved from the database until the corresponding abstarct interface is requested.
3) StTpcDb defines a global point (gStTpcDb) that points to the last instance of StTpcDb created (this of course is horrible object-oriented programming, but it sure makes life easy!)

Using StTpcDb from ROOT command line:
1) Start root4star
2) execute test macro:

root4star [0] .x tpcDbTest.C

3) check global pointer:

root4star [1] gStTpcDb
(class StTpcDb*)0x29bea78

4) use data:

root4star [2] gStTpcDb->PadPlaneGeometry()->numberOfPadsAtRow(13)
(int)182

5) you can see what interfaces are defined:

root4star [3] .class StTpcDb
===========================================================================
class StTpcDb
 size=0xec
 (tagnum=1369,voffset=-1,isabstract=0,parent=-1,gcomp=0,=~cd=0)
List of base class--------------------------------------------------------
List of member variable---------------------------------------------------
Defined in StTpcDb
0x1dcfea0  static const enum StTpcDb:: kCalibration
0x1dcfeb0  static const enum StTpcDb:: kGeometry
0x1dcfec0  static const enum StTpcDb:: kConditions
0x0        private: StMaker* mk
0x0        private: StTpcPadPlaneI* PadPlane //!
0x0        private: StTpcWirePlaneI* WirePlane //!
0x0        private: StTpcDimensionsI* dimensions //!
0x0        private: StTpcSlowControlSimI* slowControlSim //!
0x0        private: StTpcElectronicsI* electronics //!
0x0        private: StTpcGainI* gain[24] //!
0x0        private: StTpcT0I* t0[24] //!
0x0        private: St_DataSet* tpc[3] //!
0x0        private: St_tpcDriftVelocity* dvel //!
0x0        private: long G__virtualinfo
0x0        private: static TClass* fgIsA
(compiled)        0:0    0 protected: StTpcDb StTpcDb(void);
(compiled)        0:0    0 protected: void GetDataBase(StMaker* maker);
(compiled)        0:0    0 public: StTpcDb StTpcDb(St_DataSet* input);
(compiled)        0:0    0 public: StTpcDb StTpcDb(StMaker* makerDb);
(compiled)        0:0    0 public: StTpcPadPlaneI* PadPlaneGeometry(void);
(compiled)        0:0    0 public: StTpcWirePlaneI* WirePlaneGeometry(void);
(compiled)        0:0    0 public: StTpcDimensionsI* Dimensions(void);
(compiled)        0:0    0 public: StTpcSlowControlSimI* SlowControlSim(void);
(compiled)        0:0    0 public: StTpcElectronicsI* Electronics(void);
(compiled)        0:0    0 public: StTpcGainI* Gain(int sector);
(compiled)        0:0    0 public: StTpcT0I* T0(int sector);
(compiled)        0:0    0 public: St_Table* getTpcTable(int i);
(compiled)        0:0    0 public: float DriftVelocity(void);
(compiled)        0:0    0 public: static const char* DeclFileName(void);
(compiled)        0:0    0 public: static int DeclFileLine(void);
(compiled)        0:0    0 public: static const char* ImplFileName(void);
(compiled)        0:0    0 public: static int ImplFileLine(void);
(compiled)        0:0    0 public: static Version_t Class_Version(void);
(compiled)        0:0    0 public: static TClass* Class(void);
(compiled)        0:0    0 public: virtual TClass* IsA(void) const;
(compiled)        0:0    0 public: virtual void ShowMembers(TMemberInspector& insp,char* parent);
(compiled)        0:0    0 public: virtual void Streamer(TBuffer& b);
(compiled)        0:0    0 public: static void Dictionary(void);
(compiled)        0:0    0 public: StTpcDb StTpcDb(StTpcDb&);
(compiled)        0:0    0 public: virtual void ~StTpcDb(void);

6) You can then query the individual interfaces:

root4star [13] .class StTpcDimensionsI
===========================================================================
class StTpcDimensionsI
 size=0xc
 (tagnum=1359,voffset=-1,isabstract=17,parent=-1,gcomp=0,=~cd=0)
List of base class--------------------------------------------------------
0x0        public: TObject //Basic ROOT object
List of member variable---------------------------------------------------
Defined in StTpcDimensionsI
0x0        private: static TClass* fgIsA
List of member function---------------------------------------------------
filename       line:size busy function type and name  (in StTpcDimensionsI)
(compiled)        0:0    0 public: virtual int numberOfSectors(void) const=0;
(compiled)        0:0    0 public: virtual float ifcRadius(void) const=0;
(compiled)        0:0    0 public: virtual float ofcRadius(void) const=0;
(compiled)        0:0    0 public: virtual float tpcTotalLength(void) const=0;
(compiled)        0:0    0 public: virtual float wheelInnerRadius(void) const=0;
(compiled)        0:0    0 public: virtual float wheelOuterRadius(void) const=0;
(compiled)        0:0    0 public: virtual float wheelThickness(void) const=0;
(compiled)        0:0    0 public: virtual float senseGasOuterRadius(void) const=0;
(compiled)        0:0    0 public: virtual float tpeaThickness(void) const=0;
(compiled)        0:0    0 public: virtual float cathodeInnerRadius(void) const=0;
(compiled)        0:0    0 public: virtual float cathodeOuterRadius(void) const=0;
(compiled)        0:0    0 public: virtual float cathodeThickness(void) const=0;
(compiled)        0:0    0 public: virtual float innerEffectiveDriftDistance(void) const=0;
(compiled)        0:0    0 public: virtual float outerEffectiveDriftDistance(void) const=0;
(compiled)        0:0    0 public: virtual float gatingGridZ(void) const=0;
(compiled)        0:0    0 public: virtual float zInnerOffset(void) const=0;
(compiled)        0:0    0 public: virtual float zOuterOffset(void) const=0;
(compiled)        0:0    0 public: static const char* DeclFileName(void);
(compiled)        0:0    0 public: static int DeclFileLine(void);
(compiled)        0:0    0 public: static const char* ImplFileName(void);
(compiled)        0:0    0 public: static int ImplFileLine(void);
(compiled)        0:0    0 public: static Version_t Class_Version(void);
(compiled)        0:0    0 public: static TClass* Class(void);
(compiled)        0:0    0 public: virtual TClass* IsA(void) const;
(compiled)        0:0    0 public: virtual void ShowMembers(TMemberInspector& insp,char* parent);
(compiled)        0:0    0 public: virtual void Streamer(TBuffer& b);
(compiled)        0:0    0 public: static void Dictionary(void);
(compiled)        0:0    0 public: void ~StTpcDimensionsI(void);

The function names are intended to be self-explanatory (i.e. cathodeInnerRadius)

Using StTpcDb in your Maker:
1) #include "StTpcDb.h"
2) get pointer to StTpcDbMaker:
     option 1 (easy but uncouth way): Use global pointer gStTpcDb
    option 2 (hard but correct way): Use StRoot methods

TDataSet* MyDataSet = GetDataSet("tpcDb");
StTpcDbMaker* MakeItAMaker = (StTpcDbMaker*)MyDataSet;
StTpcDb* my_tpcdb = MakeItAMaker->tpcDbInterface();

Using some data in your old fortran programs:
We have defined a few functions that pass data to fortran programs.  If you need some other data, please
send an upgrade request.  So far, we have the following functions:
extern "C" {
numberOfPadsAtRow_(int *);
tpc_row_to_y_(float *,float *);
tpc_pad_to_x_(float *,float *,float *);
tpc_x_to_pad_(float *,float *,float *);
tpc_local_to_global_(int *,float *,float *);
tpc_global_to_local_(int *,float *,float *);
tpc_global_to_local_p_(int *,float *,float *);
tpc_time_to_z_(int *,int *,int *,int *,float *);
tpc_z_to_time_(float *,int *,int *,int *,int *);
tpc_drift_velocity_(float *);
tpc_drift_volume_length_(float *);
tpc_row_par_(int *,float *,float *,float *);
tpc_global_to_sector_(int*, float*);
tpc_sec24_to_sec12_(int*, int*);

As you can see, most of these are actually geometry tranformation routines that use another package
called StDbUtilities.

How to override the mySQL database
This has absolutely no connection to StTpcDb, but I will document it here since it is often requested:
In order to overide the database, you need to first write out the database tree using a function of  St_db_Maker.  This
is shown in $STAR/StRoot/macros/DbSave.C.  Essentially, you find the St_db_Maker that contains the values
you want to overwrite and you invoke the Save(const char* path) member function.  This writes out a tree structure
under a directory called StarDb.  You can descend that directory until you find the table that contains the data that you need.  You can then modify the value.   If you now run bfc (assuming you're in the directory above StarDb), the local copy
of your database will be used, including your modified values.

Warning The timestamp on the modified data must be valid in order for it to replace the mySQL data.
 
 
 

Last Update -- 02-May-2000 by David Hardtke (DHHardtke@lbl.gov)