Code Generation HOW-TO

This document covers code generation and read/write access to the CDF Calibration API. A seperate document covers Read Only access and is available here

The purpose of this code generation package is to make your life easier when you want to add a new table to the database, and access it through a C++ or Java API . Let's suppose you want add a new table, called 'TESTTABLE' for the sake of discussion. The steps to achieving this with the code generation package are:

1. Create a java representation of the table
2. Add this java object to a CodeGen dictionary
3. Set the appropriate environment variables
4. Generate the API access code
5. Compile the access code into a library
6. Use the library to access the database from user code

Step 1. Create a java representation of the table

We want to create a table in the database called TESTABLE. The java language description that the CodeGen package uses must inherit from emitter.Attrib . Here is a java language representation of how that table might look:

import emitter.Attrib;  
import emitter.DBString;
import java.io.Serializable;
/** @author Mark Lancaster                                                 */
/** @version 1.0                                                           */
/** Dummy Test table     */
public class TestTable  extends Attrib implements Serializable
{
    long   attr1;
    double attr2;
    float  attr3;
    static public DBString bla   = new DBString(32);
    static public DBString attr4 = new DBString(40);
}

Step 2. Add your representation to a CodeGen dictionary

First, some definitions. In this system, database tables and code objects are logically grouped into CodeGen dictionaries which may be composed of sub-dictionaries. A closely related term used to group actual physical detector parts and thier calibration data is components, which may be built out of sub-components.

You must decide whether it makes more sense to add your table to an existing dictionary/component, or to create a new one. From a practical standpoint, it is easier to add your table to an existing component than to create a new one, as the existing component/dictionary probably already worked with the code generation framework.

Structurally a dictionary is composed of sub-dictionaries and tables. Parts of the 'allcomps' dictionary, which represents all of the detector that is known to the API, is shown in the following figure:

We will add the TestTable.java file described above, to the TESTcomp.java dictionary. This results in TESTcomp.java looking like this:

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;

}

All of the existing dictionaries and table definitions currently live in the CalibDBTables SRT package. Your new table definition should probably be added somewhere into the allcomps dictionary hierarchy, which will involve checking out CalibDBTables, modifying some file in the dictionaries subdirectory, and doing a commit.

Step 3. Set the appropriate environment variables

• TOPDICT By default, the code generation step generates C++ templated access code for every table in the allcomps dictionary. This is a lot of code, and can take a while to compile. Your alternative is to set TOPDICT to one of the sub-dictionaries. In this case, TESTTABLE is part of the TESTcomp dictionary, so from a csh enviroment we would setenv TOPDICT TESTcomp .

• CDF_ORACLE_CLIENT_EXISTS By default, the code generation package generates access to msql and text databases. If you want to generate oracle access as well setenv CDF_ORACLE_CLIENT_EXISTS 1

Step 4. Generate the API access code

If you haven't sourced ~cdfsoft/cdf2.cshrc do so now.

gmake codegen

Step 5.Compile the access code into a library

gmake lib

Step 5a Run the generated SQL table description into the SQL server.

During 'gmake codegen', we generated 2 scripts, create_oracle_sql.sh and create_msql_sql.sh . These generate an entire Calibration API database schema. Msql definitions for individual tables were generated and deposited into CalibDBTables/CalibDBTables/gen, and can be run directly against the msql server.

For oracle, the process is a little more complicated. A good practice with Oracle table definitions is to place them into tablespaces, with associated indexes in separate tablespaces. The create_oracle_sql.sh script creates such definitions, and places them in CalibDBTables/CalibDBTables/gen with a '.tab_sql' suffix.

b0dau30:/data1/dbox/tst3% CalibDBTables/CalibDBTables/gen/create_oracle_sql.sh 
This script will delete tables in the ORACLE db 
Do you want to continue ? [y/n] : y
 
This script will create sql to create the calibration DB 
 
Enter d to use a default if that option is available 
 
Enter UserName of Table Owner [d = calib_dev]       --> newcalib
Enter TableSpace Name for Tables [d = calib_data]   --> USERDATA_01
Enter TableSpace Name for Indices [d = calib_index] --> USERINDEX_01
Enter Role Name for Write Access [d = calib_write]  --> public
Enter Role Name for Read Access [d = calib_read]    --> public
Enter Sequence start # (2:offline, 1:online)        --> 1
 
create public synonyms for everything ? [y/n] : n
SQL being created is called calib_oracle.sql 
b0dau30:/data1/dbox/tst3% 

To create an entirely new Calibration Database, for your own developmental purposes, you could do the following:
sqlplus usr/passwd@server < calib_oracle.sql

To add your table to an existing Oracle Database:
sqlplus usr/passwd@server < CalibDBTables/CalibDBTables/gen/TestTable.pcalib.osql.tab_sql

To add your table to an existing msql database:
msql mydatabase < CalibDBTables/CalibDBTables/gen/TestTable.pcalib.msql

Step 6.Use the library to access the database from user code

Check out the DBUtils SRT package, see fillDB.cc and readDB.cc in the examples subdirectory

gmake bin