DBManager Users Guide

A Simple Example Program

//*************************************************
//File:SomeTableDriver.cc
//An example program which reads/writes SomeTable
//This program uses generated files where identified.
//Making these will be discussed below.


//DataKey.hh defines the (calib_run,version) key.
#include "CalibDB/DataKey.hh"

//SomeTable.Defs.hh has a Data Container and Manager definition --  generated code
#include "CalibDBTables/gen/SomeTable.Defs.hh

//SomeTable.hh has  the Data Object Definition
#include "CalibDBTables/gen/SomeTable.hh

int main(int argc, char* argv[])
{
  char *database_id ="MSQL";
  int  run=1,version=1 ;

  cout << " readDB Program starting ..." << endl;

  // Create a DB manager and a container for table="SomeTable"
  // @see SomeTable.Defs.hh
  SomeTableContainer_ptr gcont;  
  SomeTable_mgr iom(database_id,"SomeTable");

  if(iom.isValid()==false)
    {
      cerr << "ERROR: SomeTable_mgr initialisation failure " << endl;
      return -1;
    }

  // Create a DataKey for run, version
  DataKey qk(run,version);

  //read back from DB
  if(iom.get(qk, gcont)!=Result::success)
    {
      cerr << "ERROR: Failed to retrieve calibration for Run = " << run << endl;
      // Summary
      cout << "read from DB "<< gcont->size()<< " Rows of data " << endl;
    }
  else
    {

     SomeTableContainer::iterator pi;      cout << "SomeTable Contents : Run = " << run << " # Rows = " << gcont->size() << endl;
      for(pi=gcont->begin();pi!=gcont->end();++pi)
        dump(cerr, *pi);
    }


  return 0;
}

Generating, Compiling, and Running C++ and SQL

1. Setup for Generating:

   (Courtesy Mark Lancaster and Paolo Califigura)

   The main point of all this code generation gymnastic is to make your life easier when you want to add a new table to the database. Let's suppose you want to play with a new test table. You can create a new component for it (a component is a related group of tables, typically a subdetector) or may be add it to the existing TESTcomp

           import emitter.Attrib;
           import emitter.Component;
   
           /**
            *  This is an entry of the CDF calibration dictionary.
            *  Test-Table
            * @author Mark Lancaster
            */
           public class TESTcomp extends Component{  
             public Attrib TestTable;
             public Attrib myTable; //  your new attribute table
   
         }
   
   

   Here is your myTable.java (that you have to put in CaliDBTables/dictionary/Tables/)

           import emitter.Attrib;
           import emitter.DBString;  //only if you need a DBString
   
           import java.io.Serializable;
   
           /** @author Joe User                                               */
           /** @version 1.0                                                   */
   
           /** This is a bogus people address table                           */
   
           public class myTable  extends Attrib implements Serializable
           {
           /** your Fermi ID                                                  */
               long   userID;
           /** your name                                                      */
              String name;
           /** your mail stop                                                 */
               static public DBString mailSt = new DBString(8);
           }
   

   A few notes here:

   • comments of the form /** something */ are processed by javadoc and produce the html doc in CalibDBTables/doc

   • A java native String is mapped into a MSQL text type (of initial length set to 10). text is a type of variable lenght strings like std::string, but it is slow, can not be used as index and has some more limitations

   • DBString(8) gets mapped into a MSQL char(8) (fixed length string). This is the string type to be used whenever possible. Notice the odd syntax and the "import emitter.DBString". This is the only solution we could think of, in order to specify the length (8) of the string. The "static public" qualifiers are necessary for the code generation and have nothing to do with the scope of "mailSt" in the generated code

2. Generate the Tables and Header Files

   • This example is on cdfsga, in a CalibDBTables directory created by addpkg -h

   • cd to CalibDBTables/dictionary. The makefile codegen.make lives there.

   • setenv TOPDICT TESTcomp.java (from the above example). Make sure your myTable.java is in the dictionary/Tables subdirectory

   • Run codegen.make file thusly:

     • gmake -f codegen.make codegen for c++ code
     • gmake -f codegen.make doscripts for sql

   • You now have source code and table definitions in ../../include/CalibDBTables/gen/

3. Run the Table Data Definition Language

   In ../../include/CalibDBTables/gen/ you have 2 scripts, build_msql_tables for msql and build_osql_tables for oracle. If you have the database know how and permissions (i.e. you have create table priveleges on the target database), run these scripts. In most cases you will need the assistance of the dba to do this.

4. Compile the Source Code

   A driver program, similar to SomeTableDriver.cc above, must be written to use your generated classes.

   Put the generated source code along with your driver program in the proper directories for an SRT build, modify the appropriate makefiles, and compile. (gmake followed by gmake tbin)

5. Running the Compiled Program

   Copy (and modify as needed) iomap_msql.txt or iomap_osql.txt into $PWD/iomap.txt . Iomap.txt is a file that tells DBManager about which database to use.

   Run the compiled program (it will probably be in the SRT bin dir).