Loading/updating constants in the MASTER CDB

Igor A.Gaponenko

October 30, 2002

Document update history

Changes since October 18, 2002

Table of Contents

  1  Introduction

  2  Begin loading with this step

  3  Does my condition already exist in the MASTER CDB?

  4  Load new constants now

  5  Create new revision

  6  Update recent view to use new revisions

  7  Finish loading with this step

1  Introduction

This document provides detailed instruction on how conditions can be created/updated in the MASTER federation of the new CDB.

All the operations performed with the MASTER CDB must be done against the following BOOT file:

objyserv5::/objy/databases/production/conditions/master/BaBar.BOOT

The operations explained in this document require the following binary commands to be available in your current path:

CdbBrowser
CdbManager

Correct versions of these commands are available at 12.3.3 and any more recent production releases.

The rest of the documents describes steps which have to be done to load/update conditions. Please note one important difference of the new CDB from the old Condition/DB - in the new CDB new types of conditions (calibrations, alignments, etc.) must be created explicitly using a special command before trying to load any objects into these conditions. Otherwise CDB API would complain about non-existing conditions. The old Condition/DB created new conditions implicitly when the code was trying to write into non-existing condition of the database. If you think that your calibration does not exist yet in the CDB then check this and if it does not then create it using actions described in the corresponding step below.

Other important comments are about the scope of this document:

If you want to deal with OFFLINE constants then go to the following document: "Loading/updating constants in the IR2 CDB".

To simplify explanation we'll use the following condition name as an example. It will be used throughout the rest of the document. Just substitute this name with the one you're going to deal with in your specific use case. Here would be full path name of the sample condition:

"/det/condition"

Where "det" is supposed to be the actual detector name and "condition" is the condition name in the scope of the detector. CDB management commands described below require to specify the full path name (including detector name and condition name) exactly as it's shown above. When specifying condition names don't forget to use double quotes to hide special symbols (if any) like '>' from a UNIX shell.

Now follow step-by-step instructions below.

2  Begin loading with this step

Get permission to load new constants through the IR-2 Prod BABAR Hyper News forum.

Then constants can be loaded at any time except Monday, which is a day when MASTER CDB is synchronized with other federations of the distributed Condition/DB.

3  Does my condition already exist in the MASTER CDB?

As it was explained in the "Introduction" section above the condition type you're going to load/modify must exist in the federation. An easiest way to check is to run the following command:

CdbBrowser objects "/det/condition"

If the specified condition type is already known then you'll get a list of objects visible from this condition through the most recent "view" (persistent configuration). Here is an example output:

  --------------------------------------------- --------------------- --------------------
           VISIBLE VALIDITY INTERVAL                   STORED                OBJECT
  --------------------------------------------- --------------------- --------------------
         -Infinity      : 3131745000.0000000000                       - 
  3131745000.0000000000 : 3131762760.0382864000 3211231507.0077742000 #1537-68-3-2
  3131762760.0382864000 : 3131772053.0803690000 3211233188.0745296000 #1537-68-3-4
  ...
  3187324800.0000000000 :       +Infinity       3211742021.0981123000 #1537-68-10-21
  --------------------------------------------- --------------------- --------------------

If it does not then you'll see complains about "non-existing condition" meaning that you need to create new type of condition. Creating new condition requires proper authorization, which means that a user who is about to create new condition must be either a so called "System Manager" of the Condition/DB or a member of the "cdb" authorization group. the following commands could be used to check your authorization status:

BdbAuthCmd lsusers C | grep "(SYS)" | grep `whoami`
BdbAuthCdm lsmembers C "cdb" | grep `whoami`

If you can't find your account name by any of these commands then send a request to the BdbSOS HN group.

The actual condition creation sequence is as follows:

CdbManager create_condition        "/det/condition" "...put some condition description here..." REGULAR CLUSTER "regular"
CdbManager autoconfigure_condition "/det/condition" TOPMOST
CdbManager include_condition       "/Det/condition" "...put some condition description here..." "MASTER::condition"
CdbManager autoconfigure_condition "/Det/condition" TOPMOST

The first two commands will create new condition named "/det/condition" and give it user-specified description (you're free to provide any description in the double quotes above). The condition will be of the REGULAR  type and will be put into existing cluster of "regular" conditions. The second command will create default configuration entry for the newly created condition in the recent view. This default configuration will tell client application to use any recently loaded conditions. This will change a bit later (see the step following the one below explaining how to create new revision).

ATTENTION - READ THESE COMMENTS BEFORE TO EXECUTE COMMANDS ABOVE:

Now you'll also be able to se your condition in the list reported by any the following command:

CdbBrowser conditions /
CdbBrowser conditions /det
CdbBrowser conditions /Det

Now if you repeat repeat the first command of this subsection then you should not se any objects in this condition:

CdbBrowser objects "/det/condition"
 
  --------------------------------------------- --------------------- --------------------
           VISIBLE VALIDITY INTERVAL                   STORED                OBJECT
  --------------------------------------------- --------------------- --------------------
         -Infinity      :        +Infinity                            - 
  --------------------------------------------- --------------------- --------------------

The green color is used above to show the output of the command.

Now go to the next step.

4  Load new constants now

Before running your loader please set up the following environment variable:

setenv BDBDEBUG1 <some file name here or just "cout">

This will tell BDB and CDB API code to turn on its internal diagnostic mode and report more information about low level database operations. This information could be used by experts to analyze possible problems (if any). Send a copy of the output (or better a URL onto the file with it) into the mentioned above Hyper News group.

When you'll finish running your loader then don't forget to get rid of the above mentioned environment variable to avoid noise from CDB tools you'll be running next.

Now if you will try to see what new object you've just loaded by running:

CdbBrowser objects "/det/condition"

command then you may be surprising not seeing new objects unless you've just created this brand new condition type. The explanation is simple - new CDB does not automatically make your new objects visible in the recent view. To see new objects you'll need to take a couple of extra actions explained in the next step. The only exception is the case when you've just created the brand new type of condition and "auto-configure"-ed it for the "topmost" revisions. Then any new objects will be seen immediately.

5  Create new revision

Pick some meaningfull (to you) simple name for new revision. This name should not contain any special symbols like spaces. This name should not also exist in the list reported below:

CdbBrowser revisions "/det/condition" 0

(NOTE: the last '0' is mandatory parameter for this command). Let's suppose that you decided on the following name:

"update_for_Run1_reprocessing"

Create this revision now:

CdbManager create_revision "/det/condition" "update_for_Run1_reprocessing" "...put some meaningful revision description..." 0

(NOTE: the last '0' is again the mandatory parameter for this command). Put some meaningful to you revision description as the value of the corresponding parameter above. Now if you repeat the first command of this section then you'll see your new revision in the list. Note also that revisions also have identifiers which are actually values of the BdbTime corresponding to the real time when you run the revision creation command. This identifier has two fields: seconds and nanoseconds separated by '.' symbol.

6  Update recent view to use new revision

At this step we are going to refresh the recent view to use newly created revision for your condition. This step is required to make your new objects visible through this view. First of all check the current configuration of your condition with:

CdbBrowser config "/det/condition"
CdbBrowser config "/Det/condition"

Now run the "auto-configuration' tool to pick up the new revision created at the previous step and put into the configuration of this condition:

CdbManager autoconfigure_condition "/det/condition" NOW
CdbManager autoconfigure_condition "/Det/condition" NOW

If you repeat the following command:

CdbBrowser config "/det/condition"
CdbBrowser config "/Det/condition"

then you'll see that the "REVISION ID" has changed to use the newly created one (see previous step). This will let you to see newly loaded objects by running:

CdbBrowser objects "/det/condition"

If may also see which objects were added since previous revision. To perform this check you'll need to know the revision identifier reported by the "config" command before you ran the "autoconfigure_condition". For example if this identifier was

3210970345.0450832960

Then you do the following:

CdbBrowser objects "/det/condition" -since 3210970345.0450832960

You may also use natural format of time like "10/18/2002 10:00:01" to specify when to start looking for new objects.

7  Finish loading with this step

When you finish the steps described above then report it back to the same IR-2 Prod Hyper News forum. Report the loaded/updated condition names (their full path names), the names of newly created revision for each of these conditions, your explanations of these conditions and updates you've made, and also which clients (Prompt Reconstruction, Reprocessing, Simulation, Analysis, Online etc.) will need each of these conditions. This information will be used to propagate your updates down to appropriate federations.