New database tables, complete guide

How-To: request new DB tables

1. First of all, you need to define all required variables you want to store in database, and their compositions. This means, you will have one or more C++ structures, stored as one or more tables in STAR Offline database. Typically, this is stored in either Calibrations or Geometry db domains. Please describe briefly the following: a) how those variables are supposed to be used in offline code (3-5 lines is enough), b) how many entries would be stored in database (e.g. once per run, every 4 hours, once per day * 100 days, etc);
    

2. Second, you need an IDL file, describing your C/C++ structure(s). This IDL file will be automatically compiled/converted into C++ header and Fortran structure descriptor – so STAR Framework will support your data at all stages automatically. NOTE: comment line length should be less than 80 characters due to STIC limitation.

   EXAMPLE of IDL file:

   
   fooGain.idl :
   --------------------------------------------------------------------------------------------------------------
   /* fooGain.idl

   *

   * Table: fooGain

   *

   * description: // foo detector base gain

   *

   */

   struct fooGain {

   octet fooDetectorId; /* DetectorId, 1-32 */

   unsigned short fooChannel; /* Channel, 1-578*/

   float fooGain; /* Gain GeV/channel */

   };
   --------------------------------------------------------------------------------------------------------------
    

   Type comparison reference table :
    

IDL	C++
short, 16 bit signed integer	short
unsigned short, 16 bit unsigned integer	unsigned short
long, 32 bit signed integer	int
unsigned long, 32 bit unsigned integer	unsigned int
float, 32 bit IEEE float	float
double, 64 bit IEEE double	double
char, 8 bit ISO latin-1	char
octet, 8 bit byte (0x00 to 0xFF)	unsigned char

Generally, you should try to use types with smallest size, which fits your data. For example, if you expect your detector ids to go from 1 to 64, please use “octet” type, which is translated to “unsigned char” (0-255), not integer (0 - 65k).

 

3. There are two types of tables supported by STAR DB schema: non-indexed table and indexed table. If you are able to fit your data into one record, and you expect it to change completely (all members), than you need non-indexed table. If you know that you'll have, say, 16 rows corresponding to 16 subdetector ids, and only a few of those will change at a time, than you need indexed table. Please write down your index name, if needed (e.g. detectorID) and its range (e.g. 1-16) - if there's no index needed, just write "non-indexed".
    

4. Calculate average size of your structure, per record. You will need this to understand total disk space/memory requirements – for optimal performance on both database and C++ side, we want our tables to be as small as possible. Bloated tables are hard to retrieve from database, and might consume too much RAM on working node during BFC chain run.
   
   EXAMPLE :

   In a step 1 we created fooGain.idl file. Now, we need to convert it into header file, so we can check structure size. Let's do that (at any rcas node) :
   
   shell> mkdir TEST; cd TEST; # create temporary working directory
   shell> mkdir -p StDb/idl; # create required directory structure
   shell> cp fooGain.idl StDb/idl/; # copy .idl file to proper directory

   shell> cons; # compile .idl file
   
   After that, you should be able to include .sl44_gcc346/include/fooGain.h into your test program, so you can call sizeof(fooGain_st) to determine structure size, per entry. We need to write down this number too. Ultimately, you should multiply this size by expected number of entries from step 1 – generally, this should fit into 1 Gb limit (if not – it needs to be discussed in detail).
   

5. Decide on who is going to insert data into those tables, write down her/his rcf login (required to enable db “write” access permissions). Usually, subsystem coordinator is a best choice for this task.

6. Create Drupal page (could be your blog, or subsystem page) with the information from steps 1-5, and send a link to it to current database administrator or db-devel maillist. Please allow one day for table creation and propagation of committed .idl files to .dev version of STAR software. Done! If you need to know how to read or write your new tables, please read Frequently Asked Questions page, it has references to read/write db examples Frequently Asked Questions.
   

Time Stamps