The BdbIntervalUtil Reference Manual

December 12, 2000

Igor Gaponenko (gapon@slac.stanford.edu)

 

Table of contents

1. Introduction

1.1 General notes on the syntax

1.2 Transaction management

1.3 Authorization

1.4 Completion of the commands

1.5 The version of this document

2. The commands description

2.1 General information

2.1.1 help

2.1.2 detectors

2.1.3 containers

2.2 Genealogy browsing

2.2.1 genealogy

2.2.2 toplist

2.2.3 baselinelist

2.2.4 revisionlist

2.3 Managing containers

2.3.1 delete

2.3.2 deletemany

2.3.3 copy

2.3.4 checkpoint

2.3.5 merge

2.3.6 verifymerge

2.3.7 merge2

2.3.8 verifymerge2

2.3.9 split

2.3.10 compare

2.3.11 purge

2.3.12 verify

2.3.13 profile

2.3.14 nanocorrection

2.4 Browsing and managing symbolic links

2.4.1 createlink

2.4.2 removelink

2.4.3 showlink

2.4.4 locklink

2.4.5 unlocklink

2.5 Operations involving conditions objects

2.5.1 classes

2.5.2 composites

2.5.3 validate

2.6 Browsing and managing the revisions

2.6.1 registry

2.6.2 revision

2.6.3 dependencylist

2.6.4 dependencytree

2.6.5 produce

2.6.6 revise2d

2.6.7 revise2d_update

2.6.8 reviseoids

2.6.9 reviseoids_update

2.6.10 revisetop

2.6.11 revisetop_update

2.6.12 revisetopmany

2.6.13 revisetopmany_update

2.6.14 createrevision

2.6.15 deleterevision

2.7 Browsing and managing the history

2.7.1 createhistory

2.7.2 removehistory

2.7.3 comment

2.7.4 history

2.8 Other operations

2.8.1 fetchnstore

2.8.2 removeinterval

3. Appendix

3.1 How to specify the day and time

3.2 How to specify the time zone

3.3 The formats of genealogy dump

3.4 The list of origins

3.5 The History Records

3.6 The configuration file format

3.6.1 v1

3.6.2 v2

3.6.3 v3

3.7 The definition of correctness for intervals in the context of revisions

1. Introduction

This document is a reference guide for the BdbIntervalUtil. The utility provides a broad spectrum of browsing and management commands related to the contents of Conditions database.

Due to "referential" nature of this document its scope is only limited to a short description of each command without going deep into details. This will be covered by another document.

Each command is documented with:

The commands are grouped into groups according to their functionality.

1.1 General notes on the syntax

The Utility is able to execute just one command at a time. It's not possible to read commands from a file.

The general syntax recognized by the utility is:

BdbIntervalUtil <command> [<parameters>]

The command is an atomic action to be executed by the utility. Each command has a list of parameters specific to this command.

1.2 Transaction management

The transaction management policy for those commands meant to modify the contents of the Conditions/DB is as follows:

  1. An update-mode transaction is unconditionally aborted if any kind of problems is encountered during the command's execution or even at the preparation stage (like command parsing stage).
  2. For the composite commands (the ones involving starts or commits of multiple transactions to complete specified mission) the previously stated rule (1) applies only to a transaction where a problem occurs. Should this occur the command's execution is immediately aborted as well. This actually means that the composite commands may be "semi-completed".

By default (unless it's stated explicitly) commands are executed within a single transaction. Multiple transaction mode is typically used when multiple interval containers are involved into an operation, or if this is required by the performance consideration.

See the description of each command for an indication if this command is the composite one.

1.3 Authorization

The current authorization policy for the Conditions/DB requires that each detector of the Conditions/DB be mapped onto a separate authorization group. Therefore only members of a group as well as all so called "System Managers" of the Conditions domain are allowed to modify conditions of the corresponding detector.

A practical consequence of the mentioned above rule is that a user must be registered as a member of the group in order to modify the conditions of the detector/group.

In addition, some of the operations involving conditions from multiple detectors require a user to be either a System Manager of the Conditions domain or be a member of every single group affected by the operation.

The list of all registered users in the Conditions domain of a federation can be obtained with the following command:

BdbAuthCmd lsusers Conditions

A list of known authorization groups (for the Conditions domain) can be obtained with:

BdbAuthCmd lsgroups Conditions

Here is how to get a list of members of a particular group (emc in this example):

BdbAuthCmd lsmembers Conditions emc

See "BaBar Database Authorization API and Authorization Management Utility" for other details, especially on how to create new groups and register new group members.

1.4 Completion of the commands

Upon a command completion the following values are returned to a shell:

0 - success

1 - error

The detailed information about the error is printed onto a standard output stream. The meaning of the error status for the complex commands (the ones whose execution involves multiple transactions) depends on a command. In some cases the command's execution may be considered as semi-successful.

1.5 The version of this document

The description of the utility and other related software components presented in this document are valid for the following ranges of BABAR software releases:

·        From release 9.6.0

·        Up to (including) 9.9.2

The partial compatibility with previous and past releases is also available. See the self-descriptive help command of this utility for a list of commands supported in a specific version.

This document will be updated as new releases are issued.

2. The commands description

2.1 General information

2.1.1 help

DESCRIPTION:

This command will print onto the standard output stream the information on this utility in a form of a simple list of lines. The content of the output is a non-structural subset of information presented in the current document.

SYNTAX:

BdbIntervalUtil help

PARAMETERS:

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil help
DESCRIPTION:
 
  This Utility provides a broad spectrum of various browsing
  and management commands which relate to the contents of Conditions database.
 
  IMPORTANT: The transaction management policy for those commands which are
             meant to modify the contents of the Conditions/DB is as follows:
 
             1. An update-mode transaction is unconditionally aborted if any kind of
                problems is encountered during the command's execution or even at
                the preparation stage (like command parsing stage).
...

2.1.2 detectors

DESCRIPTION:

Print names of sub-detectors groups in the Conditions database. This command (in its current implementation) will make and parse a dump of the existing con_xxx_Link databases using the oodumpcatalog utility.

Make sure that the mentioned above utility is in your current path. Note also, that for some federations with many databases this may take a while. Just be patient.

SYNTAX:

BdbIntervalUtil detectors

PARAMETERS:

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil detectors
emc
dch
ifr
...

2.1.3 containers

DESCRIPTION:

Print names of conditions for specified detector group. Additional options are controlling how much information to show about found containers. It's also possible to specify exactly where the conditions have to be searched.

SYNTAX:

BdbIntervalUtil containers <detector>
                [-all] [-long]
                [ { ALL | NEWLINK | NEWINDEX [<origin>] | OLDINDEX } ]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

Optional

-all

This optional parameter forces the command to include conditions with special names starting with underscore symbol '_'. These names are reserved for the internal use by the Conditions/DB implementation. They are not normally shown if this optional parameter is not explicitly specified.

-long

This optional parameter forces the command to print basic characteristics of each of the found condition. This includes the following:

If the persistent bookkeeping is on for this condition then [HISTORY] will appear in the output. This keyword will never seen for the old style databases.

The so called origin of a condition is shown with [ORIGIN:xxxx] where xxxx is the origin name. This keyword will never seen for the old style databases.

Some conditions can be declared as read-only at a given federation. If this is a case then [READONLY] will appear for this conditions. This kind of protection can be set by a special command of BdbIntervalUtil. See commands locklink and unlocklink for details.

See examples below.

Mutually exclusive

ALL

To find and print both old containers in old interval database (OLDINDEX) and new container links in link database (NEWLINK).

NEWLINK

To find and print containers found in con_<detector>_Link link database.

NEWINDEX [<origin>]

To find and print containers found in an index interval database con_<detector>_Index_<origin> for specified origin. If no origin is specified then the local one is used.

OLDINDEX

To find and print only those containers found in the legacy con_<detector>_Index interval database.

AUTHORIZATION:

EXAMPLES:

% BdbIntervalUtil containers emc
AAA
EmcFooClassP
BBB
 
% BdbIntervalUtil containers emc -all -long
[HISTORY][ORIGIN:default]  AAA
[HISTORY][ORIGIN:default]  EmcFooClassP
[HISTORY][ORIGIN:default]  _CHECKPOINT_3151268353_EmcFooClassP
...

2.2 Genealogy browsing

2.2.1 genealogy

DESCRIPTION:

Print the information about persistent intervals for specified condition. The output is available in various formats. The validity range can also be optionally narrowed from either or both sides of the validity timeline.

SYNTAX:

BdbIntervalUtil genealogy <detector> <container>
                [-format <number>]
                [-begin_validity <time> [-begin_validity_tzone <zone>]]
                [-end_validity   <time> [-end_validity_tzone   <zone>]]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

Optional

-format <number>

This parameter controls the output format of the dump. More information on the known format numbers and how they would affect the output of the dump is available at: “The formats of genealogy dumps”.

-begin_validity <time>

This parameter is meant to specify the left limit for the genealogy dump in the validity time. By default the dump begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the left validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_validity <time>

This parameter is meant to specify the right limit for the genealogy dump in the validity time. By default the dump ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the right validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil genealogy emc EmcFooClassP
*  -Infinity-:2997907200  FirstInterval  [9219-6-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-6-3-18] -> [9217-3-1-25]  Rev.0
1.0  2997907200:2997907210  V1  [9219-6-3-55] -> [9217-3-1-28]  Rev.*
2  2997907210:2997907220  V0  [9219-6-3-41] -> [9217-3-1-26]  Rev.0
2.0  2997907210:2997907220  V1  [9219-6-3-60] -> [9217-3-1-28]  Rev.*
*  2997907220:+Infinity+  LastInterval  [9219-6-3-48] -> [9217-3-1-28]  Rev.0
...

2.2.2 toplist

DESCRIPTION:

Print the information about persistent intervals for specified condition. The output is available in various formats. The validity range can also be optionally narrowed from either or both sides of the validity timeline.

This command prints a subset of the genealogy information corresponding to the TOPMOST  layer of intervals only. The red intervals on a picture below are those ones printed by the command:

SYNTAX:

BdbIntervalUtil toplist <detector> <container>
                [-format <number>]
                [-begin_validity <time> [-begin_validity_tzone <zone>]]
                [-end_validity   <time> [-end_validity_tzone   <zone>]]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

Optional

-format <number>

This parameter controls the output format of the dump. More information on the known format numbers and how they would affect the output of the dump is available at: “The formats of genealogy dumps”.

-begin_validity <time>

This parameter is meant to specify the left limit for the genealogy dump in the validity time. By default the dump begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the left validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_validity <time>

This parameter is meant to specify the right limit for the genealogy dump in the validity time. By default the dump ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the right validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil toplist emc EmcFooClassP
*  -Infinity-:2997907200  FirstInterval  [9219-6-3-17] -> [0-0-0-0]  Rev.0
*  2997907200:2997907210  V1  [9219-6-3-55] -> [9217-3-1-28]  Rev.*
*  2997907210:2997907220  V1  [9219-6-3-60] -> [9217-3-1-28]  Rev.*
*  2997907220:+Infinity+  LastInterval  [9219-6-3-48] -> [9217-3-1-28]  Rev.0
...

2.2.3 baselinelist

DESCRIPTION:

Print the information about persistent intervals for specified condition. The output is available in various formats. The validity range can also be optionally narrowed from either or both sides of the validity timeline.

This command prints a subset of the genealogy information corresponding to the BASELINE layer of intervals only. The red intervals on a picture below are those ones printed by the command:

SYNTAX:

BdbIntervalUtil baselinelist <detector> <container>
                [-format <number>]
                [-begin_validity <time> [-begin_validity_tzone <zone>]]
                [-end_validity   <time> [-end_validity_tzone   <zone>]]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

Optional

-format <number>

This parameter controls the output format of the dump. More information on the known format numbers and how they would affect the output of the dump is available at: “The formats of genealogy dumps”.

-begin_validity <time>

This parameter is meant to specify the left limit for the genealogy dump in the validity time. By default the dump begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the left validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_validity <time>

This parameter is meant to specify the right limit for the genealogy dump in the validity time. By default the dump ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the right validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil baselinelist emc EmcFooClassP
*  -Infinity-:2997907200  FirstInterval  [9219-6-3-17] -> [0-0-0-0]  Rev.0
*  2997907200:2997907210  V0  [9219-6-3-18] -> [9217-3-1-25]  Rev.0
*  2997907210:2997907220  V0  [9219-6-3-41] -> [9217-3-1-26]  Rev.0
*  2997907220:+Infinity+  LastInterval  [9219-6-3-48] -> [9217-3-1-28]  Rev.0
...

2.2.4 revisionlist

DESCRIPTION:

Print the information about persistent intervals for specified condition. The output is available in various formats. The validity range can also be optionally narrowed from either or both sides of the validity timeline.

This command prints a subset of the genealogy information for intervals belonging to the specified revision either directly or indirectly. The red intervals on a picture below are those ones printed by the command:

SYNTAX:

BdbIntervalUtil revisionlist <detector> <container> <revision_id>
                [-format <number>]
                [-begin_validity <time> [-begin_validity_tzone <zone>]]
                [-end_validity   <time> [-end_validity_tzone   <zone>]]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

<revision_id>

The revision number of intervals to be displayed. This is a 32-bit unsigned integer number. Decimal format is expected.

Optional

-format <number>

This parameter controls the output format of the dump. More information on the known format numbers and how they would affect the output of the dump is available at: “The formats of genealogy dumps”.

-begin_validity <time>

This parameter is meant to specify the left limit for the genealogy dump in the validity time. By default the dump begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the left validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_validity <time>

This parameter is meant to specify the right limit for the genealogy dump in the validity time. By default the dump ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the right validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil genealogy emc EmcFooClassP
*  -Infinity-:2997907200  FirstInterval  [9219-6-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-6-3-18] -> [9217-3-1-25]  Rev.0
1.0  2997907200:2997907210  V1  [9219-6-3-55] -> [9217-3-1-28]  Rev.1
1.0.0  2997907200:2997907210  V2  [9219-6-3-83] -> [9217-3-1-29]  Rev.*
2  2997907210:2997907220  V0  [9219-6-3-41] -> [9217-3-1-26]  Rev.0
2.0  2997907210:2997907220  V1  [9219-6-3-60] -> [9217-3-1-28]  Rev.1
2.0.0  2997907210:2997907220  V2  [9219-6-3-85] -> [9217-3-1-29]  Rev.*
*  2997907220:+Infinity+  LastInterval  [9219-6-3-48] -> [9217-3-1-29]  Rev.0
...
% BdbIntervalUtil revisionlist emc EmcFooClassP 0
*  -Infinity-:2997907200  FirstInterval  [9219-6-3-17] -> [0-0-0-0]  Rev.0
*  2997907200:2997907210  V0  [9219-6-3-18] -> [9217-3-1-25]  Rev.0
*  2997907210:2997907220  V0  [9219-6-3-41] -> [9217-3-1-26]  Rev.0
*  2997907220:+Infinity+  LastInterval  [9219-6-3-48] -> [9217-3-1-29]  Rev.0
...
% BdbIntervalUtil revisionlist emc EmcFooClassP 1
*  -Infinity-:2997907200  FirstInterval  [9219-6-3-17] -> [0-0-0-0]  Rev.0
*  2997907200:2997907210  V1  [9219-6-3-55] -> [9217-3-1-28]  Rev.1
*  2997907210:2997907220  V1  [9219-6-3-60] -> [9217-3-1-28]  Rev.1
*  2997907220:+Infinity+  LastInterval  [9219-6-3-48] -> [9217-3-1-29]  Rev.0
...

2.3 Managing containers

2.3.1 delete

DESCRIPTION:

Delete specified interval container and all the objects pointed through intervals of the container if required by optional argument.

By default this operation will delete both the container link from con_xxx_Link databases and the interval container from con_xxx_Index_<origin> database. This kind of behavior can be changed by setting an optional parameter to avoid deleting the symbolic link.

Note that containers which are declared as read-only (see containers command) can not be deleted in this way. This has to be fixed by the unlocklink command before doing this operation.

SYNTAX:

BdbIntervalUtil delete <detector> <container> [-objects] [-nolink]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

This is the condition name to be affected by the operation.

Optional

-objects

If this optional parameter is specified then all the condition objects following from persistent intervals will be deleted as well.

-nolink

If this optional parameter is set then the symbolic link container will not be deleted. One important consequence of this is that when the operation is finished the link will point to non-existing interval container.

AUTHORIZATION:

A user must be a member of a detector group where the deleted container is located.

EXAMPLE:

% BdbIntervalUtil containers emc -all -long
[HISTORY][ORIGIN:default]  AAA
[HISTORY][ORIGIN:default]  EmcFooClassP
[HISTORY][ORIGIN:default]  _CHECKPOINT_3151268353_EmcFooClassP
...
% BdbIntervalUtil deletemany emc AAA
...

2.3.2 deletemany

DESCRIPTION:

Delete many interval containers at a detector whose names match a simple regular expression. For each eligible container the command behaves exactly as a single container deletion command.

Names of deleted containers can optionally be reported to the Standard output stream if the verbose mode is chosen.

If at least one read-only container is met in the list of the eligible one then all the operation fails. See more details on that subject from the single container deletion command's description.

The special containers (starting with underscore prefix) will also be deleted if they match the specified regular expression.

SYNTAX:

BdbIntervalUtil deletemany <detector> <regexpr> [-objects] [-nolink] [-verbose]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<regexpr>

A simple expression for the container names to be selected for the deletion. See the description of RWCRegexp class, which is used in the current implementation of the command, for the complete description and limitation of the syntax.

Here are simple expressions: "*", "*Class", "My*Class".

Optional

-objects

If this optional parameter is specified then all the condition objects following from persistent intervals will be deleted as well.

-nolink

If this optional parameter is set then the symbolic link container will not be deleted. One important consequence of this is that when the operation is finished the link will point to non-existing interval container.

-verbose

Forces the command to print the names of deleted containers.

 

AUTHORIZATION:

A user must be a member of a detector group where the deleted containers are located.

EXAMPLE:

% BdbIntervalUtil containers emc -all -long
[HISTORY][ORIGIN:default]  AAA
[HISTORY][ORIGIN:default]  EmcFooClassP
[HISTORY][ORIGIN:default]  _CHECKPOINT_3151268353_EmcFooClassP
...
% BdbIntervalUtil deletemany emc "*" -verbose
DELETE: emc AAA
DELETE: emc EmcFooClassP
DELETE: emc _CHECKPOINT_3151268353_EmcFooClassP
...
% BdbIntervalUtil containers emc -all -long
...

2.3.3 copy

DESCRIPTION:

Make a copy of an interval container and optionally all the condition objects being registered through the original container. The output interval container may be located either in the same detector or in the other one. The new container is always created in an interval database corresponding to the local origin of a federation where this operation is being performed.

As an option, only a part of the whole genealogy from the input container can be copied into the output one. Possible options include: copy baseline intervals only, copy topmost intervals only and copy a specific revision slice only. By default all the intervals information is copied.

IMPORTANT: The history records are not copied during this operation. A special record is placed into the history of the output container to indicate that this container is created as a copy of the other one.

The condition objects are copied only if required by the corresponding switch. If this is the case then by default the output condition objects are created in object databases of the output detector as it’s suggested by the regular clustering hint. As an option these objects can also be created in a separate container (whose name must be explicitly specified by a user) located in the same interval database where the copy of an interval container is placed. In this case a user should follow some naming convention for these (data) containers, for example by using the following prefix in front of these names "_DATA_<time>_" followed by the interval container name. See examples below.

IMPORTANT: In the current implementation of the code so called composite objects are copied just partially.

SYNTAX:

BdbIntervalUtil copy <from_detector> <from_container>
                     <to_detector>   <to_container>
                     [-l<level> [<revision_id>]]
                     [-objects  [-local <container>] [-warnings]]

PARAMETERS:

mandatory

<from_detector>

The detector name where the input condition is located.

<from_container>

The input condition name.

<to_detector>

The output detector where a copy of the input container will be placed. This can be the same detector as the input one.

<to_container>

The output condition/container name. If the output detector is the same as the input one then this name must be

optional

-l<level>

This parameter specifies the genealogy copy level. It allows to force the command to copy a subset of intervals into the output container. The following values for his parameter are allowed:

-ld  all the genealogy information is copied. This is the default behavior of the command.

-lb  baseline intervals are copied only.

-lt   topmost intervals are copied only.

-lr   intervals that belong (either directly or indirectly) to the specified (through the next parameter) revision are copied only.

optional

<revision_id>

This normally optional parameter is required if the previous parameter requires that a revised slice of intervals has to be copied.

-objects

This parameter forces the command to make a deep copy of the persistent condition objects registered via the intervals. By default the new objects are placed into object databases of the output detector as it’s defined by the clustering policy of the Conditions/DB.

optional

-local <container>

This parameter allows to override the default clustering policy and to store the output objects into a separate container in the output interval database alongside with the newly created copy of interval container.

It’s advised to follow some policy when copying condition objects using this combination of parameters. So for example the container name for this (data) container should start from the underscore (‘_’) to indicate that this is going to be a special container.

-warning

This tells the command to issue a warning every time the virtual table for the copied persistent condition object is not loaded.

AUTHORIZATION:

A user must be a member of a to_detector group where the output containers are placed.

EXAMPLE:

% BdbIntervalUtil containers emc -long
[HISTORY][ORIGIN:default]  EmcFooClassP
...
% BdbIntervalUtil copy emc EmcFooClassP emc AAA
...
% BdbIntervalUtil containers emc -long
[HISTORY][ORIGIN:default]  EmcFooClassP
[HISTORY][ORIGIN:default]  AAA
...
% BdbIntervalUtil containers tmp –long
...
% BdbIntervalUtil copy emc EmcFooClassP tmp EmcFooClassP –objects –local _DATA_EmcFooClassP
...
% BdbIntervalUtil containers tmp –all
EmcFooClassP
_DATA_EmcFooClassP
...

2.3.4 checkpoint

DESCRIPTION:

Create a checkpoint of an interval container. The checkpoint is a copy of specified interval container into another one having a special normally invisible name. The basic idea of this operation is to take a snapshot of the genealogy information for a specified condition at a given time. Since the snapshots have unique names (bound to a time when this operation is performed) then there may be as many snapshots of a particular condition as it's required.

This operation does not involve the condition objects themselves, but it does create a new name in the link database for a new condition. This name is build from the original condition name preceded by a prefix "_CHECKPOINT_<time>_". The <time> in this prefix is represented as the number of seconds since January 1, 1901.

No matter what's the origin of an original condition the new interval container is created in an interval database corresponding to the local origin of a federation where this command is being executed.

The checkpoints can be seen when running the containers command with on optional switch -all.

Since checkpoints are much like the regular containers then they can be deleted in the same way as the regular ones using delete or deletemany commands. It's very important however to remember that all intervals at a checkpoint have references to the same condition objects as the intervals from the original container do. So avoid deleting the checkpoints using -objects switch of the deletion commands. Otherwise the original interval container (as well as any other remaining checkpoints of this condition) will have so called dangling references to non-existing condition objects. The same rule should be followed when deleting the original condition with -objects switch. In that case all checkpoints must be deleted as well.

SYNTAX:

BdbIntervalUtil checkpoint <detector> <container>

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

This is the condition name to be affected by the operation.

AUTHORIZATION:

A user must be a member of a detector group where the deleted containers are located.

EXAMPLE:

% BdbIntervalUtil containers emc -all -long
[HISTORY][ORIGIN:default]  EmcFooClassP
...
% BdbIntervalUtil checkpoint emc EmcFooClassP
...
% BdbIntervalUtil containers emc -all -long
[HISTORY][ORIGIN:default]  EmcFooClassP
[HISTORY][ORIGIN:default]  _CHECKPOINT_3151268353_EmcFooClassP
...
% BdbIntervalUtil delete emc _CHECKPOINT_3151268353_EmcFooClassP
... 

2.3.5 merge

2.3.6 verifymerge

2.3.7 merge2

2.3.8 verifymerge2

2.3.9 split

DESCRIPTION:

Split a timeline of a condition at a given point of validity time. This operation will make a vertical genealogy “cut” at this point. The condition objects themselves are not affected by this operation. The output of the “fetch” operations will also be the same as before. The only purpose of this operation is to change the internal structure of intervals.

Here is an example of what is happening to the genealogy:

        

SYNTAX:

BdbIntervalUtil split <detector> <container>
                      -split_time <time> [-split_time_tzone <zone>]

PARAMETERS:

mandatory

<detector>

The detector name where the input condition is located.

<container>

The condition name where the operation is done.

-split_time <time>

This is the point of time where the genealogy split is done. See format of the time at: “How to specify day and time”.

optional

-split_time_tzone <zone>

This optional parameter is meant to specify the time zone for the time above. See format of this parameter at: ”How to specify the time zone”.

AUTHORIZATION:

A user must be a member of a detector group where the splitten container is located.

EXAMPLE:

% BdbIntervalUtil containers emc -all -long
[HISTORY][ORIGIN:default]  EmcFooClassP
...
% BdbIntervalUtil checkpoint emc EmcFooClassP
...
% BdbIntervalUtil containers emc -all -long
[HISTORY][ORIGIN:default]  EmcFooClassP
[HISTORY][ORIGIN:default]  _CHECKPOINT_3151268353_EmcFooClassP
...
% BdbIntervalUtil delete emc _CHECKPOINT_3151268353_EmcFooClassP
...

2.3.10 compare

DESCRIPTION:

Compare two interval containers. Various comparison strategies can be applied.

NOTE: This command has not been implemented yet.

SYNTAX:

BdbIntervalUtil compare <from_detector> <from_container>
                        <to_detector>   <to_container>
                        [-strategy { STRUCTURAL | EXACT }]
                        [-include { ALL | [LINK][:INTERVALS][:REVISIONS][:HISTORY] }] [-verbose]

PARAMETERS:

Mandatory

<from_detector>

The detector name where the first compared condition is located.

<from_container>

The first compared condition name.

<to_detector>

The detector name where the second compared condition is located.

<to_container>

The second compared condition name.

Optional

-strategy

Mutually exclusive options

STRUCTURAL

The structure of a network of persistent objects is only compared.

EXACT

Two containers must be completely equivalent.

-include

Mutually exclusive options

ALL

All persistent structures of an interval container are involved into the comparison.

[LINK] [:INTERVALS] [:REVISIONS] [:HISTORY]

Any combination of the specified sources of information is only considered.

-verbose

Print more information as the comparison process goes on.

EXAMPLE:

...

2.3.11 purge

DESCRIPTION:

Purge so called staircases in the genealogy of the specified condition. The staircases when they are present often decline the performance of the Conditions/DB code. The validity range of the operation can be optionally narrowed from either or both sides of the validity timeline.

IMPORTANT: This operation does not preserve the OID-s of the original interval objects, even when no intervals are physically purged in the affected area of the validity time.

This command will excess extra intervals in a vertical stack of versions between the topmost ones and the baseline ones. Some types of intervals in between, depending on their meaning, can also be excluded from purging. It’s also possible to specify how many layers from the top to keep from purging. See the description of parameters for more details on this subject.

Here is the basic idea on how the operation will work:

SYNTAX:

BdbIntervalUtil purge <detector> <container>
                [-begin_validity <time> [-begin_validity_tzone <zone>]]
                [-end_validity   <time> [-end_validity_tzone   <zone>]]
                { [-dont_keep_revised_intervals] | [-max_under_revision <number>] }
                [-max_top2keep <number>]
                [-force]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

Optional

-begin_validity <time>

This parameter is meant to specify the left limit for the validity time of intervals affected by the operation. By the operation begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the left validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_validity <time>

This parameter is meant to specify the right limit for the validity time of intervals affected by the operation. By default the operation ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the right validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

Mutually exclusive

-dont_keep_revised_intervals

If this option is set then the operation will not keep explicitly revised intervals from removal. In other words these intervals are treated as the unassigned ones. The exception of this rule is a set of baseline intervals, which are never removed.

-max_under_revision <number>

This parameter is meant to specify how many layers to keep under an explicitly revised interval (the revised interval itself does not count). So if this number is equal to 0 then the command will purge any unassigned intervals beneath the revised one, unless these intervals have to be kept from purging for some other reason (see the next parameter).

This is the default option. The default number of interval layers frozen in this ways is 1.

-max_to_keep <number>

The maximum number of intervals from the top to keep from purging. The baseline intervals are not count here. So if this number is equal to 0 then the resulting container will keep the baseline intervals only, unless there is another reason to keep the eligible intervals from removal. If this number is equal to 1 then the resulting container may have the baseline and the topmost intervals only.

The default number of intervals frozen in this way is 2.

-force

If this option is set then a user will not be asked for the confirmation before to proceed with the operation’s execution.

AUTHORIZATION:

A user must be a member of a detector group where the deleted container is located.

EXAMPLE:

% BdbIntervalUtil genealogy emc EmcFooClassP
*  -Infinity-:2997907200  FirstInterval  [9219-6-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-6-3-18] -> [9217-3-1-25]  Rev.0
1.0  2997907200:2997907210  V1  [9219-6-3-55] -> [9217-3-1-28]  Rev.*
2  2997907210:2997907220  V0  [9219-6-3-41] -> [9217-3-1-26]  Rev.0
2.0  2997907210:2997907220  V1  [9219-6-3-60] -> [9217-3-1-28]  Rev.*
*  2997907220:+Infinity+  LastInterval  [9219-6-3-48] -> [9217-3-1-28]  Rev.0
...

2.3.12 verify

DESCRIPTION:

Verify if specified interval container has consistent internal structure. The following types of tests are executed by the command:

1.      Contingency of BASELINE intervals.

2.      Contingency of TOPMOST intervals

3.      Contingency of vertical versioning trees. The correct alignment of intervals in trees is also checked.

4.      Consistency of the Objectivity index and the versioning trees.

The term of “contingency” in the tests 1 and 2 above means that each next (in the validity time interval) must begin exactly where the previous one ends. The “contingency” of a vertical tree (test number 3) means that intervals on each vertical layer of the tree must be “contingent” and they must cover the validity period of the intermediate parent interval.

The last test (number 4) is the most complicated one – it checks if all intervals of a container are registered in the index. The index is used as a fast way to locate intervals containing specified validity time.

In the end, when these tests are over, and the “verbose” (see the description of parameters) mode is set then the command reports one of the following conclusions:

“The structure is CORRECT”
“The structure is NOT CORRECT”

The status value returned to the shell also reflects the results of the operation: 0 – in case of correct structure, and 1 – otherwise (including errors during the command’s execution).

The scope of this operation in the validity time can also be optionally narrowed. See the description of parameters on how to do this.

IMPORTANT: This test does not check if the links to condition objects are correct. This is done by another command: validate.

SYNTAX:

BdbIntervalUtil verify <detector> <container>
                [-begin_validity <time> [-begin_validity_tzone <zone>]]
                [-end_validity   <time> [-end_validity_tzone   <zone>]]
                [-verbose]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

Optional

-begin_validity <time>

This parameter is meant to specify the left limit for the validity time of intervals affected by the operation. By the operation begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the left validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_validity <time>

This parameter is meant to specify the right limit for the validity time of intervals affected by the operation. By default the operation ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the right validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-verbose

Forces the command to print the names of deleted containers.

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil verify emc EmcFooClassP -verbose
BEGIN
  DETECTOR:  emc
  CONTAINER: EmcFooClassP
  1:Verifying contingency of BASELINE intervals...
  2:Verifying contingency of TOPMOST intervals...
  3:Verifying contingency of vertical versioning trees...
  4:Verifying consistency of the Objectivity index and the versioning tree...
  CONCLUSION: "The structure is CORRECT."
END.
...

2.3.13 profile

DESCRIPTION:

Measure the interval container profile. This operation collects some statistics about an interval container. This includes:

·         Total number of intervals.

·         Number of baseline intervals.

·         Number of topmost intervals.

·         Number of revised intervals (the ones explicitly connected to a revision).

·         Number of intervals having a reference to a null condition object.

·         The maximum numbers for:

o   Width of baseline intervals (the number of topmost intervals above a baseline one).

o   Number of vertical layers.

o   Number of intermediate versions.

·         Similar histograms for:

o   The width of baseline intervals.

o   The number of vertical layers.

o   The number of immediate versions.

The scope of this operation in the validity time can be optionally narrowed. See the description of parameters on how to do this. In this case the total numbers, maximum numbers and histograms are only related to the subset of data.

SYNTAX:

BdbIntervalUtil profile <detector> <container>
                [-begin_validity <time> [-begin_validity_tzone <zone>]]
                [-end_validity   <time> [-end_validity_tzone   <zone>]]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

Optional

-begin_validity <time>

This parameter is meant to specify the left limit for the validity time of intervals included into the operation. By the operation begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the left validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_validity <time>

This parameter is meant to specify the right limit for the validity time of intervals included into the operation. By default the operation ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the right validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil profile pep PepBoostCal_BhabhaP4
 
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
= = =  C O N T A I N E R  P R O F I L E  R E P O R T  = = =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 
  PARAMETERS:
 
    Detector:  pep
    Container: PepBoostCal_BhabhaP4
    Begin Validity Time: -Infinity
    End   Validity Time: +Infinity
 
  TOTALS:
 
    Intervals:          211
    BASELINE Intervals: 208
    TOPMOST Intervals:  208
    Revised Intervals:  211
    NULL References:    8
 
  MAXIMUMS:
 
    Maximum Width (TOPMOST intervals per BASELINE one): 1
    Maximum Layers (height of sub-trees):               2
    Maximum Versions (intermediate versions only):      1
 
  HISTOGRAMS:
 
    "WIDTH"
 
      [0,0) -> 0
      [1,1) -> 208
 
    "LAYERS"
 
      [0,0) -> 0
      [1,1) -> 205
      [2,2) -> 3
 
    "VERSIONS"
 
      [0,0) -> 208
      [1,1) -> 3
 
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
...

2.3.14 nanocorrection

DESCRIPTION:

This command fixes begin and end times of persistent intervals of specified condition by zeroing nanoseconds field at these times.

The reason to have this procedure is a mismatch between the specification and the implementation of the Conditions/DB code. According to the specification the resolution of time is 1 second. However due to current implementation of the code it’s possible to store nanoseconds as well. This may cause some troubles when managing interval containers.

The command may also be run in a "verify" only mode, if an optional switch is specified. In this case the command will just locate and report intervals having non-empty nanosecond fields at validity limits.

The scope of this operation in the validity time can also be optionally narrowed. See the description of parameters on how to do this.

If the "verbose" mode is chosen then a list of OID-s of found/fixed intervals will also be reported.

SYNTAX:

BdbIntervalUtil nanocorrection <detector> <container>
                [-begin_validity <time> [-begin_validity_tzone <zone>]]
                [-end_validity   <time> [-end_validity_tzone   <zone>]]
                [-verify_only]
                [-verbose]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

Optional

-begin_validity <time>

This parameter is meant to specify the left limit for the validity time of intervals affected by the operation. By the operation begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the left validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_validity <time>

This parameter is meant to specify the right limit for the validity time of intervals affected by the operation. By default the operation ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

This optional parameter is bound to the right validity time limit. It’s meant to override the default time zone for the validity time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-verify_only

Do not fix the found intervals. Just report them.

-verbose

Forces the command to print the OID-s of found/fixed containers.

AUTHORIZATION:

A user must be a member of a detector group where the corrected container is located.

EXAMPLE:

% BdbIntervalUtil nanocorrection pep PepBoostCal_BhabhaP4 -verify_only -verbose
 
##########################
##### nanocorrection #####
##########################
 
    Detector:   pep
    Container:  PepBoostCal_BhabhaP4
 
    Begin Validity Time: -Infinity
    End   Validity Time: +Infinity
 
The following intervals were found:
 
[1591-19-3-157]
[1591-19-3-131]
[1591-19-3-156]
[1591-19-3-155]
[1591-19-3-154]
[1591-19-3-153]
[1591-19-3-152]
[1591-19-3-151]
[1591-19-3-150]
[1591-19-3-149]
 
Total of 10 intervals were found.
...

2.4 Browsing and managing symbolic links

2.4.1 createlink

DESCRIPTION:

The primary goal of this command is to create a new condition name in a name space of a particular detector and to associate this name with an instance of the either existing or yet to be created interval container. Typically this action is being done automatically when a user’s code is storing the very first record for a non-existing condition. But in some (management of multiple federations) cases it’s still required to create the links explicitly.

Technically each detector has a special link database (con_<detector>_Link, where the <detector> is a detector’s TLA (Three Letter Acronym)) providing a name space for conditions of this detector. Each condition is represented as a named container in the link database. Each such container has a kind of symbolic link to an interval container in an interval/index database con_<detector>_Index_<origin>, which is another kind of databases in the Conditions/DB.

A link has three parameters:

·         The origin name:

o     The origin is meant to specify a federation where a condition was created. The complete description of this concept will be presented in the other document.

·         The target detector name:

o     In most cases this is the same name as the one where a new link is created. But in some specific cases it can be different. The origin and the detector names are meant to “calculate” an interval database where con_<detector>_Index_<origin> the target interval container should be located.

·         The target interval container name:

o   This is a container where all the genealogy, history and revision information is kept.

The target detector and the target container names are optional, if they are not specified then they are set to the detector where the link is being created and the link name.

It’s also not required for a target interval container to exist when a new link is being created, unless an optional “verify” switch is specified. Should this be the case the link is only created when the interval container does exist.

See other link related commands for more information.

Here is a concept of the link in a graphical form:

SYNTAX:

BdbIntervalUtil createlink <detector> <container>
                           <origin>   [<real_detector> <real_container>
                           [-verify]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group in a name space. If the specified detector does not exist then it will be automatically created (which means that the corresponding link database con_<detector>_Link will be created).

<container>

The new condition name. This name should not exist before the operation.

<origin>

This is the origin (a key identifying a federation) where an instance of the condition was created and is updated. See a list of currently known origins at: The list of origins.

Optional

<real_detector>

This second key together with the origin is meant to identify an interval (index) database name where the corresponding instance of an interval container is located. If this parameter is omitted then the link’s detector name is used.

<real_container>

This is a target interval container name in an index database. If this parameter is omitted then the link’s name is used.

-verify

Forces the command to verify if the target interval container exists before to create the link. If it does not exist then the link is not created.

AUTHORIZATION:

A user must be at least a group manager of a detector group where the new link is created. This privilege is higher then just a “group member”.

EXAMPLE:

% BdbIntervalUtil conditions pep -long
[HISTORY][ORIGIN:repro-core]  PepBeamSpotCal_Bhabha
[HISTORY][ORIGIN:repro-core]  PepBeamSpotCal_Hadronic
...
% BdbIntervalUtil createlink pep NewCondition opr-core
...
% BdbIntervalUtil showlink pep NewCondition
LINK Detector: pep
LINK Container: NewCondition
 
    -> Origin:    opr-core
    -> Detector:  pep
    -> Container: NewCondition
...
% BdbIntervalUtil conditions pep -long
[ORIGIN:opr-core]  NewCondition
[HISTORY][ORIGIN:repro-core]  PepBeamSpotCal_Bhabha
[HISTORY][ORIGIN:repro-core]  PepBeamSpotCal_Hadronic
...

2.4.2 removelink

DESCRIPTION:

This command will remove existing link.

Technically when a link is being deleted then a container with the same name is deleted from the link database con_<detector>_Link corresponding to the <detector>.

IMPORTANT: The link is deleted even if a container it’s pointing at is not enabled for writing. See the locklink and unlocklink commands for details.

By default this operation does not affect a "real" container the link is pointing at. This container can be deleted if an optional switch is specified. If this is the case then the target interval container pointed by the link is also removed from the target interval database con_<target_detector>_Index_<origin>. See what’s on the other side of the link (use: showlink) before to choose this option. Also even if the target interval container is deleted the objects being pointed through its intervals are never deleted. See the delete command for details. In general using the container deletion command is more preferable.

IMPORTANT: Since it’s allowed to have more then one link pointing onto the same instance of an interval container then it’s very important to make sure that no other links are using the same instance before to delete the link with target interval container.

SYNTAX:

BdbIntervalUtil removelink <detector> <container>
                           [-propagate]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group in a name space.

<container>

The condition name.

Optional

-propagate

Forces the command to propagate along the link and to delete an interval container targeted by the link. This container must exist before the operation. Otherwise the operation will fail.

AUTHORIZATION:

A user must be at least a group manager of a detector group where the new link is deleted. This privilege is higher then just a “group member”.

EXAMPLE:

% BdbIntervalUtil conditions pep -long
[ORIGIN:opr-core]  NewCondition
[HISTORY][ORIGIN:repro-core]  PepBeamSpotCal_Bhabha
[HISTORY][ORIGIN:repro-core]  PepBeamSpotCal_Hadronic
...
% BdbIntervalUtil removelink pep NewCondition
...
% BdbIntervalUtil conditions pep -long
[HISTORY][ORIGIN:repro-core]  PepBeamSpotCal_Bhabha
[HISTORY][ORIGIN:repro-core]  PepBeamSpotCal_Hadronic
...

2.4.3 showlink

DESCRIPTION:

Display the information about specified link.

NOTE: This command does not reflect the status of an interval container the link is pointed at.

SYNTAX:

BdbIntervalUtil showlink <detector> <container>

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group in a name space.

<container>

The condition name.

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil conditions pep -long
[ORIGIN:opr-core]  NewCondition
[HISTORY][ORIGIN:repro-core]  PepBeamSpotCal_Bhabha
[HISTORY][ORIGIN:repro-core]  PepBeamSpotCal_Hadronic
...
% BdbIntervalUtil showlink pep NewCondition
LINK Detector: pep
LINK Container: NewCondition
 
    -> Origin:    opr-core
    -> Detector:  pep
    -> Container: NewCondition
...

2.4.4 locklink

DESCRIPTION:

This command enforces a READ-ONLY mode for an interval container referenced via specified container link. If the container is locked then its contents can’t be modified by anyone, including those ones who are formally authorized to do so. The basic goal of the command is to protect the container from accidental modification.

The opposite command for the locklink is the unlocklink command.

NOTE: Don’t be confused with the use of the lock term. Its use is to indicate that this container is disabled for the modifications. Also this lock has nothing in common with Objectivity’s lock.

SYNTAX:

BdbIntervalUtil locklink <detector> <container>

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group in a name space.

<container>

The condition name.

AUTHORIZATION:

A user must be at least a group manager of a detector group where the new link is deleted. This privilege is higher then just a “group member”.

EXAMPLE:

% BdbIntervalUtil conditions pep -long
[ORIGIN:opr-core]  NewCondition
...
% BdbIntervalUtil locklink pep NewCondition
...
% BdbIntervalUtil conditions pep -long
[READONLY][ORIGIN:opr-core]  NewCondition
...

2.4.5 unlocklink

DESCRIPTION:

This command removes an existing READ-ONLY mode for an interval container referenced via specified container link. This is the opposite command for the locklink command. See this command for the other details.

SYNTAX:

BdbIntervalUtil unlocklink <detector> <container>

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group in a name space.

<container>

The condition name.

AUTHORIZATION:

A user must be at least a group manager of a detector group where the new link is deleted. This privilege is higher then just a “group member”.

EXAMPLE:

% BdbIntervalUtil conditions pep -long
[READONLY][ORIGIN:opr-core]  NewCondition
...
% BdbIntervalUtil unlocklink pep NewCondition
...
% BdbIntervalUtil conditions pep -long
[ORIGIN:opr-core]  NewCondition
...

2.5 Operations involving conditions objects

2.5.1 classes

DESCRIPTION:

This command will browse all persistent interval in either a single interval container or all interval containers of specified detector and find out the names of persistent classes of condition objects referenced through these intervals. In addition, if the “long” mode is chosen, the number of uses for each found class is also printed.

SYNTAX:

BdbIntervalUtil classes <detector> [<container>] [-long]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

Optional

<container>

The condition name is optional. If it’s not specified then all containers of the specified detector are studied.

-long

Forces the command to print usage statistics for each found class. This means the number of objects for each found class.

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil classes emc -long
CalBankT<CalMSNChan>.EmcBhabhaType[0]
    96 : CalBankT<CalMSNChan >
CalBankT<CalMSNChan>.EmcBhabhaType[1]
    96 : CalBankT<CalMSNChan >
CalBankT<CalMSNChan>.EmcBhabhaType[2]
    96 : CalBankT<CalMSNChan >
CalBankT<CalMSNChan>.EmcBhabhaType[3]
    96 : CalBankT<CalMSNChan >
CalBankT<CalMSNChan>.EmcBhabhaType[4]
    96 : CalBankT<CalMSNChan >
CalBankT<CalMSNChan>.EmcBhabhaType[5]
    96 : CalBankT<CalMSNChan >
CalBankT<CalMSNChan>.EmcBhabhaType[6]
    96 : CalBankT<CalMSNChan >
CalBankT<CalMSNChan>.EmcBhabhaType[7]
    96 : CalBankT<CalMSNChan >
CalBankT<CalMSNChan>.EmcBhabhaType[8]
    96 : CalBankT<CalMSNChan >
CalBankT<CalMSNChan>.EmcBhabhaType[9]
    96 : CalBankT<CalMSNChan >
CalBankT<CalStatusChan>.EmcStatusType[0]
    595 : CalBankT<CalStatusChan >
CalBankT<CalStatusChan>.EmcStatusType[1]
    504 : CalBankT<CalStatusChan >
CalBankT<CalStatusChan>.EmcStatusType[2]
    1767 : CalBankT<CalStatusChan >
...

2.5.2 composites

DESCRIPTION:

Print names of the composite persistent classes. The composite classes are those ones consisting from more then one persistent class. Typically objects of these classes form a tree or a graph, and they are registered in the Conditions/DB through one of its nodes. The objects of this kind are hard to manage (making deep copy is impossible without the help of a class developer).

This command requires a text file with the output of ooschemadump command on its input. It uses this file to check if the found persistent class name is the composite one.

If the “long” mode is chosen, the number of uses for each found class is also printed.

SYNTAX:

BdbIntervalUtil composites <detector> <schema_file> [-long]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<schema_file>

The text file produced by running the ooschemadump command.

Optional

-long

Forces the command to print usage statistics for each found class. This means the number of objects for each found class.

AUTHORIZATION:

EXAMPLE:

% ooschemadump –outfile schema.dmp –notitle -quiet
...
% BdbIntervalUtil composites emc schema.dmp -long
CalBankT<CalMSNChan >
CalBankT<CalStatusChan >
EmcMinIType
EmcBhabhaType
EmcSrcType
EmcSrcCalBank
EmcElecCalType
EmcPedType
EmcStatusType
EmcGlobalAlignP
EmcHwSystem                                            // this is a composite class because it
    -> private ooVArray(ooRef(EmcHwCrate)) _crateList  // has an array of child objects.
EmcUnifDataP
EmcCalibDictionary                                     // this class is also the composite one
    -> private ooRef(ooMap) _myCalibMap                // because it has a map of child objects.
EmcAlgBank
EmcDigiAlgBank
EmcEnergyScaleType
CalBankT<EmcEnergyScaleChan >
CalBankT<EmcMinIChan >
CalBankT<EmcElecCalPChan >
CalBankT<EmcPedPChan >
EmcGLayoutP_001
EmcLPTypeP
EmcSrcCalType
CalBankT<EmcSrcPChan_001 >
EmcNonLinearityDataP
...

2.5.3 validate

DESCRIPTION:

Check if all the persistent references going from intervals to condition objects are valid. This test in fact checks if there are no dangling references in the Conditions/DB. These references may appear in case of either malfunctioning AMS server or mismanagement of the database. A typical scenario in the later case would be if one of object databases (the ones contained the condition objects themselves) were missing in a federation.

If the “long” mode is chosen then the complete information about a location of the found problem is printed onto the Standard output stream. See examples below to see how potential problems could look like.

The result of the test is also reported to the shell as a return status of the utility. As usually 0 indicates a success.

IMPORTANT: This test does not check the correctness of an interval container. This should be done using another command: verify. The correctness of the internal structure of conditions objects (especially if they are so called composite objects) is also not checked. Only the presence of these objects is checked.

Red color on the picture below indicates what is actually being validated by this command.

SYNTAX:

BdbIntervalUtil validate <detector> <container> [-long]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

Optional

-long

Forces the command to print detailed information about found problems.

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil genealogy emc EmcFooClassP
*  -Infinity-:2997907200  FirstInterval  [9219-6-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-6-3-18] -> [9217-3-1-25]  Rev.0
1.0  2997907200:2997907210  V1  [9219-6-3-55] -> [9217-3-1-28]  Rev.1
1.0.0  2997907200:2997907210  V2  [9219-6-3-83] -> [9217-3-1-29]  Rev.*
2  2997907210:2997907220  V0  [9219-6-3-41] -> [9217-3-1-26]  Rev.0
2.0  2997907210:2997907220  V1  [9219-6-3-60] -> [9217-3-1-28]  Rev.1
2.0.0  2997907210:2997907220  V2  [9219-6-3-85] -> [9217-3-1-29]  Rev.*
*  2997907220:+Infinity+  LastInterval  [9219-6-3-48] -> [9217-3-1-29]  Rev.0
...
% BdbIntervalUtil validate emc EmcFooClassP -long
 
#######################################
#######################################
##### The list of invalid objects #####
#######################################
 
EmcFooClassP
 
    Interval ID: 9219-6-3-83
        Begin time: 2997907200  12/31/95 16:00:00 (local time) 0 ns
        End time:   2997907210  12/31/95 16:00:10 (local time) 0 ns
            Object ID: 9217-3-1-29
            DB Name:   con_emc_emc002401
 
    Interval ID: 9219-6-3-85
        Begin time: 2997907210  12/31/95 16:00:10 (local time) 0 ns
        End time:   2997907220  12/31/95 16:00:20 (local time) 0 ns
            Object ID: 9217-3-1-29
            DB Name:   con_emc_emc002401
 
    Interval ID: 9219-6-3-48
        Begin time: 2997907220  12/31/95 16:00:20 (local time) 0 ns
        End time:   4294967295  +Infinity
            Object ID: 9217-3-1-29
            DB Name:   con_emc_emc002401
 
 
Total of 3 invalid objects were found.
...

2.6 Browsing and managing the revisions

2.6.1 registry

DESCRIPTION:

This very simple command produces a list of revision numbers registered (there is a special persistent data structure called registry) in the scope of specified condition. The output generated by the command will contain at least one number 0.

A revision is represented as a 32-bit unsigned integer number. Number 0 corresponds to the baseline revision. The baseline revision is a very first revision created automatically when a condition is created. All other revisions are deriving (directly or indirectly) from this one. See the dependencylist and dependencytree commands for more information on that subject.

SYNTAX:

BdbIntervalUtil registry <detector> <container>

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group.

<container>

The condition name.

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil containers emc
[HISTORY][ORIGIN:default]  EmcFooClassP
...
% BdbIntervalUtil registry emc EmcFooClassP
...
0
1
2
...

2.6.2 revision

DESCRIPTION:

Print detailed information about specified revision, including:

Revision ID

the specified revision number. This must be the one passed as a parameter. The reason why this number is printed is that a new generation of the BdbIntervalUtil might be able to accept symbolic names fro the revision rather than just plain numbers.

Creation Time

This is the date and time when the revision was created.

Site

This is a place from where the revision was created. This value is taken from BFSITE environment variable of a process that created the revision. If no such variable were in the environment then unknown will be used.

Description

This is an optional comment on the revision.

Base revision ID

This is a revision the specified one is based on. This field is always empty for the baseline revision.

Dependent revisions ID

A list of space separated revisions based upon the specified one.

SYNTAX:

BdbIntervalUtil revision <detector> <container> <revision_id>

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

<revision_id>

The revision number. Must be a 32-bit unsigned integer number.

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil registry emc EmcFooClassP
0
1
2
...
% BdbIntervalUtil revision emc EmcFooClassP 0
   Revision ID:            0
   Creation Time:          11/15/00 09:50:50 (local time) 0 ns
   Site:                   slac
   Description:            -- baseline revision --
   Base revision ID:       
   Dependent revisions ID: 1 2
...

2.6.3 dependencylist

DESCRIPTION:

Print the revision the specified one is based on and those ones based upon the specified revision. By default this operation is executed for every single revision found in the registry of specified container (see the registry command). The operation can be optionally narrowed to a particular revision.

SYNTAX:

BdbIntervalUtil dependencylist <detector> <container> [<revision_id>]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

Optional

<revision_id>

The revision number. Must be a 32-bit unsigned integer number.

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil registry emc EmcFooClassP
0
1
2
% BdbIntervalUtil revision emc EmcFooClassP 0
   Revision ID:            0
   Creation Time:          11/15/00 09:50:50 (local time) 0 ns
   Site:                   slac
   Description:            -- baseline revision --
   Base revision ID:       
   Dependent revisions ID: 1 2
...
% BdbIntervalUtil dependencylist emc EmcFooClassP
* <- 0 <- 1 2 
0 <- 1 <- *
0 <- 2 <- *
...

2.6.4 dependencytree

DESCRIPTION:

Print the dependency between all the revisions found in the registry of specified container (see the registry command).

SYNTAX:

BdbIntervalUtil dependencytree <detector> <container> [-long]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

Optional

-long

Forces the command to display more information on each found revision. Use the revision command to get all information on a revision.

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil dependencytree emc EmcFooClassP
0
+ - 1
    + - 3
        + - 5
+ - 2
    + - 4
...
% BdbIntervalUtil dependencytree emc EmcFooClassP -long
0  slac  11/15/00 09:50:50 (local time) 0 ns  -- baseline revision --
+ - 1  slac  11/15/00 14:14:50 (local time) 0 ns  
    + - 3  slac  12/08/00 14:05:40 (local time) 0 ns  This is a test revision.
        + - 5  slac  12/08/00 14:06:18 (local time) 0 ns  Another level of dependency. And so on.
+ - 2  slac  12/08/00 13:43:49 (local time) 0 ns  
    + - 4  slac  12/08/00 14:06:05 (local time) 0 ns  Another level of dependency
...

2.6.5 produce

DESCRIPTION:

This command will generate the configuration file for the Conditions/DB of a federation based on the most recent revision numbers known in this database. Every single condition of each found detector group is analyzed. The results are placed into the output file as one line per each condition plus one line per detector plus one line for all conditions and all detectors. The latter two items are added to specify the default configuration in case if new containers/detectors will be added in the future.

See the details on the formats of the configuration file at: The configuration file format.

KNOWN PROBLEMS: This command has an outdated implementation in the current version of the code. The first problem with this implementation is that it will generate the V1 of the configuration that is difficult to read. The second problem is that a list of detectors is taken from the Authorization/DB. This list does not necessarily match the actual list of detectors in the Conditions/DB.

SYNTAX:

BdbIntervalUtil produce <config_file>

PARAMETERS:

Mandatory

<config_file>

The configuration file name where the command output will be written.

AUTHORIZATION:

EXAMPLE:

% BdbIntervalUtil produce output.cfg
...
% cat output.cfg
V1
* * 1 0
emc * 1 0
emc EmcFooClassP 0 7
...

2.6.6 revise2d

DESCRIPTION:

This command creates a new revision made of unassigned intervals found in a 2-d space of the validity and version timelines of the specified interval container. The found intervals are associated with the new revision. The vertical (version time) ambiguity if two or more intervals are found in the same stack is resolved with a special strategy parameter.

If no restrictions in either or both dimensions are given then the whole timeline(s) is searched.

See a graphical example below to get an idea how this command works. This picture is different from typical drawings because intervals stack is stretched in the vertical (version time) dimension in order to illustrate when the corresponding intervals were created. There are 4 layers of intervals on the picture: the blue layer includes baseline intervals only, plus three extra layers on the top of it. Let’s assume that each of these 3 layers corresponds to a consistent set of constants associated with some activity that was meant to reconsider original constants in the baseline. Now we want to create a new revision made of intervals in between begin_validity and end_validity validity time limits done in between begin_version and end_version version time (the actual time when these constants were loaded into the database). The operation will select four intervals. Each two of them will cover the same period of the validity time, but be inserted at different times. The strategy keyword will resolve this kind of ambiguity.

SYNTAX:

BdbIntervalUtil revise2d <detector> <container> <base_revision_id> <strategy_key>
                [-description <description>]
                [-begin_validity <time> [-begin_validity_tzone <zone>]]
                [-end_validity   <time> [-end_validity_tzone   <zone>]]
                [-begin_version  <time> [-begin_version_tzone  <zone>]]
                [-end_version    <time> [-end_version_tzone    <zone>]]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

<base_revision_id>

This will be the base revision for the new revision. Must be specified as a 32-bit unsigned decimal number.

<strategy_key>

Mutually exclusive options

EARLIEST

This key resolves possible ambiguity when two or more unassigned intervals are found in a vertical stack in favor of the oldest (in the version time) intervals.

RECENT

Provides an opposite criteria.

Optional

-description <description>

This is an optional comment for the new revision. It does not affect the functioning of the new revision in any way. It just servers as an additional way to specify why a new revision is being created.

-begin_validity <time>

This parameter is meant to specify the left limit for the operation in the validity time. By default the search for intervals begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-begin_validity_tzone <zone>

This optional parameter is bound to the begin time limit. It’s meant to override the default time zone for the begin time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_validity <time>

This parameter is meant to specify the right limit for the operation in the validity time. By default the search for intervals ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-end_validity_tzone <zone>

This optional parameter is bound to the end time limit. It’s meant to override the default time zone for the end time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-begin_version <time>

This parameter is meant to specify the lower limit for the operation in the version time. By default the search for intervals begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-begin_version_tzone <zone>

This optional parameter is bound to the begin time limit. It’s meant to override the default time zone for the begin time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_version <time>

This parameter is meant to specify the uper limit for the operation in the version time. By default the search for intervals ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-end_version_tzone <zone>

This optional parameter is bound to the end time limit. It’s meant to override the default time zone for the end time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

AUTHORIZATION:

A user must be a member of a detector group where the container is located.

EXAMPLE:

% BdbIntervalUtil genealogy emc EmcFooClassP
*  -Infinity-:2997907200  FirstInterval  [9219-8-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-8-3-18] -> [9217-3-1-30]  Rev.0
1.0  2997907200:2997907210  V1  [9219-8-3-49] -> [9217-3-1-32]  Rev.*
2  2997907210:2997907220  V0  [9219-8-3-42] -> [9217-3-1-32]  Rev.0
2.0  2997907210:2997907220  V1  [9219-8-3-71] -> [9217-3-1-33]  Rev.*
*  2997907220:+Infinity+  LastInterval  [9219-8-3-69] -> [0-0-0-0]  Rev.0
...
% BdbIntervalUtil revise2d emc EmcFooClassP 0 RECENT
Path I: Total of 2 intervals were found.
Path II: A new revision 1 has been created.
...
% BdbIntervalUtil genealogy emc EmcFooClassP
*  -Infinity-:2997907200  FirstInterval  [9219-8-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-8-3-18] -> [9217-3-1-30]  Rev.0
1.0  2997907200:2997907210  V1  [9219-8-3-49] -> [9217-3-1-32]  Rev.1
2  2997907210:2997907220  V0  [9219-8-3-42] -> [9217-3-1-32]  Rev.0
2.0  2997907210:2997907220  V1  [9219-8-3-71] -> [9217-3-1-33]  Rev.1
*  2997907220:+Infinity+  LastInterval  [9219-8-3-69] -> [0-0-0-0]  Rev.0
...

2.6.7 revise2d_update

DESCRIPTION:

This command provides the same basic functionality as the revise2d does with the only exception – the intervals are upended to already existing revision. See this command for the details.

SYNTAX:

BdbIntervalUtil revise2d_update <detector> <container> <revision_id> <strategy_key>
                [-begin_validity <time> [-begin_validity_tzone <zone>]]
                [-end_validity   <time> [-end_validity_tzone   <zone>]]
                [-begin_version  <time> [-begin_version_tzone  <zone>]]
                [-end_version    <time> [-end_version_tzone    <zone>]]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

<revision_id>

This will be an existing revision number. Must be specified as a 32-bit unsigned decimal number.

<strategy_key>

This key is used to resolve an ambiguity when two or more unassigned intervals are found in a vertical stack. Currently the key may have two values:

EARLIEST - provides that the most old (in the version time) interval is chosen;

RECENT – means the opposite criteria.

Optional

-begin_validity <time>

This parameter is meant to specify the left limit for the operation in the validity time. By default the search for intervals begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-begin_validity_tzone <zone>

This optional parameter is bound to the begin time limit. It’s meant to override the default time zone for the begin time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_validity <time>

This parameter is meant to specify the right limit for the operation in the validity time. By default the search for intervals ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-end_validity_tzone <zone>

This optional parameter is bound to the end time limit. It’s meant to override the default time zone for the end time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-begin_version <time>

This parameter is meant to specify the lower limit for the operation in the version time. By default the search for intervals begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-begin_version_tzone <zone>

This optional parameter is bound to the begin time limit. It’s meant to override the default time zone for the begin time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_version <time>

This parameter is meant to specify the uper limit for the operation in the version time. By default the search for intervals ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-end_version_tzone <zone>

This optional parameter is bound to the end time limit. It’s meant to override the default time zone for the end time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

AUTHORIZATION:

A user must be a member of a detector group where the container is located.

EXAMPLE:

% BdbIntervalUtil genealogy emc EmcFooClassP
*  -Infinity-:2997907200  FirstInterval  [9219-8-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-8-3-18] -> [9217-3-1-30]  Rev.0
1.0  2997907200:2997907210  V1  [9219-8-3-49] -> [9217-3-1-32]  Rev.1
2  2997907210:2997907220  V0  [9219-8-3-42] -> [9217-3-1-32]  Rev.0
2.0  2997907210:2997907220  V1  [9219-8-3-71] -> [9217-3-1-33]  Rev.*
*  2997907220:+Infinity+  LastInterval  [9219-8-3-69] -> [0-0-0-0]  Rev.0
...
% BdbIntervalUtil revise2d_update emc EmcFooClassP 1 RECENT
Path I: Total of 1 intervals were found.
Path II: The revision 1 has been updated.
...
% BdbIntervalUtil genealogy emc EmcFooClassP
*  -Infinity-:2997907200  FirstInterval  [9219-8-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-8-3-18] -> [9217-3-1-30]  Rev.0
1.0  2997907200:2997907210  V1  [9219-8-3-49] -> [9217-3-1-32]  Rev.1
2  2997907210:2997907220  V0  [9219-8-3-42] -> [9217-3-1-32]  Rev.0
2.0  2997907210:2997907220  V1  [9219-8-3-71] -> [9217-3-1-33]  Rev.1
*  2997907220:+Infinity+  LastInterval  [9219-8-3-69] -> [0-0-0-0]  Rev.0
...

2.6.8 reviseoids

DESCRIPTION:

This command creates a new revision made of intervals whose object identifiers (OID-s) are read from the specified plain text. These intervals are first checked for the correctness (see more details on this test at: The definition of correctness for intervals in the context of revisions). If the previous test does not find any problems then a new revision based on the specified base one is created. The verified intervals are associated with the new revision.

The syntax of the input file passed to the command is very simple – it must contain the OID-s separated by delimiters. The following symbols are recognized as delimiters: SPACE, TAB, EOL and EOF.

The OID has the following format:

D-C-P-S

Where:

D - is the database number (16-bit unsigned decimal integer)

C - is the container number (16-bit unsigned decimal integer)

P - is the page number (16-bit unsigned decimal integer)

S - is the slot number (16-bit unsigned decimal integer)

Here is an example of the file contents:

9012-2-4-2
9012-2-4-3
9012-2-5-4
9012-2-1-56
9012-2-5-5
...

SYNTAX:

BdbIntervalUtil reviseoids <detector> <container> <base_revision_id> <oids_file>
                [-description <description>]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

<base_revision_id>

This will be the base revision for the new revision. Must be specified as a 32-bit unsigned decimal number.

<oids_file>

The plain text file with OID-s.

Optional

-description <description>

This is an optional comment for the new revision. It does not affect the functioning of the new revision in any way. It just servers as an additional way to specify why a new revision is being created.

AUTHORIZATION:

A user must be a member of a detector group where the container is located.

EXAMPLE:

% BdbIntervalUtil genealogy emc AAA
*  -Infinity-:2997907200  FirstInterval  [9219-8-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-8-3-18] -> [9217-3-1-30]  Rev.0
1.0  2997907200:2997907210  V1  [9219-8-3-49] -> [9217-3-1-32]  Rev.*
*  2997907210:+Infinity+  LastInterval  [9219-8-3-42] -> [9217-3-1-32]  Rev.0
...
% cat > oids.txt
9219-8-3-49
^D
...
% BdbIntervalUtil reviseoids emc EmcFooClassP 0 oids.txt
Path I: Total of 1 intervals were loaded.
Path II: A new revision 1 has been created.
...
% BdbIntervalUtil genealogy emc AAA
*  -Infinity-:2997907200  FirstInterval  [9219-8-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-8-3-18] -> [9217-3-1-30]  Rev.0
1.0  2997907200:2997907210  V1  [9219-8-3-49] -> [9217-3-1-32]  Rev.1
*  2997907210:+Infinity+  LastInterval  [9219-8-3-42] -> [9217-3-1-32]  Rev.0
...

2.6.9 reviseoids_update

DESCRIPTION:

This command provides the same basic functionality as the reviseoids does with the only exception – the intervals are upended to already existing revision. See this command for the details.

SYNTAX:

BdbIntervalUtil reviseoids_update <detector> <container> <revision_id> <oids_file>

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

<revision_id>

This is an existing revision number (32-bit unsigned decimal number).

<oids_file>

The plain text file with OID-s.

AUTHORIZATION:

A user must be a member of a detector group where the container is located.

EXAMPLE:

% BdbIntervalUtil genealogy emc AAA
*  -Infinity-:2997907200  FirstInterval  [9219-8-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-8-3-18] -> [9217-3-1-30]  Rev.0
1.0  2997907200:2997907210  V1  [9219-8-3-49] -> [9217-3-1-32]  Rev.1
2  2997907210:2997907220  V0  [9219-8-3-42] -> [9217-3-1-32]  Rev.0
2.0  2997907210:2997907220  V1  [9219-8-3-71] -> [9217-3-1-33]  Rev.*
*  2997907220:+Infinity+  LastInterval  [9219-8-3-69] -> [0-0-0-0]  Rev.0...
% cat > oids.txt
9219-8-3-71
^D
...
% BdbIntervalUtil reviseoids emc EmcFooClassP 1 oids.txt
Path I: Total of 1 intervals were loaded.
Path II: The revision 1 has been updated.
...
% BdbIntervalUtil genealogy emc AAA
*  -Infinity-:2997907200  FirstInterval  [9219-8-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-8-3-18] -> [9217-3-1-30]  Rev.0
1.0  2997907200:2997907210  V1  [9219-8-3-49] -> [9217-3-1-32]  Rev.1
2  2997907210:2997907220  V0  [9219-8-3-42] -> [9217-3-1-32]  Rev.0
2.0  2997907210:2997907220  V1  [9219-8-3-71] -> [9217-3-1-33]  Rev.1
*  2997907220:+Infinity+  LastInterval  [9219-8-3-69] -> [0-0-0-0]  Rev.0
...

2.6.10 revisetop

DESCRIPTION:

This command creates a new revision made of unassigned topmost intervals found in specified interval container. The found intervals are associated with the new revision.

The operation scope can be optionally narrowed in the validity time. By default the whole timeline of the container is searched.

SYNTAX:

BdbIntervalUtil revisetop <detector> <container> <base_revision_id>
                [-description <description>]
                [-begin_validity <time> [-begin_validity_tzone <zone>]]
                [-end_validity   <time> [-end_validity_tzone   <zone>]]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

<base_revision_id>

This will be the base revision for the new revision. Must be specified as a 32-bit unsigned decimal number.

Optional

-description <description>

This is an optional comment for the new revision. It does not affect the functioning of the new revision in any way. It just servers as an additional way to specify why a new revision is being created.

-begin_validity <time>

This parameter is meant to specify the left limit for the operation in the validity time. By default the search for intervals begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-begin_validity_tzone <zone>

This optional parameter is bound to the begin time limit. It’s meant to override the default time zone for the begin time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_validity <time>

This parameter is meant to specify the right limit for the operation in the validity time. By default the search for intervals ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-end_validity_tzone <zone>

This optional parameter is bound to the end time limit. It’s meant to override the default time zone for the end time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

AUTHORIZATION:

A user must be a member of a detector group where the container is located.

EXAMPLE:

% BdbIntervalUtil genealogy emc EmcFooClassP
*  -Infinity-:2997907200  FirstInterval  [9219-8-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-8-3-18] -> [9217-3-1-30]  Rev.0
1.0  2997907200:2997907210  V1  [9219-8-3-49] -> [9217-3-1-32]  Rev.*
2  2997907210:2997907220  V0  [9219-8-3-42] -> [9217-3-1-32]  Rev.0
2.0  2997907210:2997907220  V1  [9219-8-3-71] -> [9217-3-1-33]  Rev.*
*  2997907220:+Infinity+  LastInterval  [9219-8-3-69] -> [0-0-0-0]  Rev.0
...
% BdbIntervalUtil revisetop emc EmcFooClassP 0
Path I: Total of 2 TOPMOST intervals were found.
Path II: A new revision 1 has been created.
...
% BdbIntervalUtil genealogy emc EmcFooClassP
*  -Infinity-:2997907200  FirstInterval  [9219-8-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-8-3-18] -> [9217-3-1-30]  Rev.0
1.0  2997907200:2997907210  V1  [9219-8-3-49] -> [9217-3-1-32]  Rev.1
2  2997907210:2997907220  V0  [9219-8-3-42] -> [9217-3-1-32]  Rev.0
2.0  2997907210:2997907220  V1  [9219-8-3-71] -> [9217-3-1-33]  Rev.1
*  2997907220:+Infinity+  LastInterval  [9219-8-3-69] -> [0-0-0-0]  Rev.0
...

2.6.11 revisetop_update

DESCRIPTION:

This command provides the same basic functionality as the revisetop does with the only exception – the intervals are upended to already existing revision. See this command for the details.

SYNTAX:

BdbIntervalUtil revisetop_update <detector> <container> <revision_id>
                [-begin_validity <time> [-begin_validity_tzone <zone>]]
                [-end_validity   <time> [-end_validity_tzone   <zone>]]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

<revision_id>

This is an existing revision number (32-bit unsigned decimal number).

Optional

-begin_validity <time>

This parameter is meant to specify the left limit for the operation in the validity time. By default the search for intervals begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-begin_validity_tzone <zone>

This optional parameter is bound to the begin time limit. It’s meant to override the default time zone for the begin time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_validity <time>

This parameter is meant to specify the right limit for the operation in the validity time. By default the search for intervals ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-end_validity_tzone <zone>

This optional parameter is bound to the end time limit. It’s meant to override the default time zone for the end time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

AUTHORIZATION:

A user must be a member of a detector group where the container is located.

EXAMPLE:

% BdbIntervalUtil genealogy emc EmcFooClassP
*  -Infinity-:2997907200  FirstInterval  [9219-8-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-8-3-18] -> [9217-3-1-30]  Rev.0
1.0  2997907200:2997907210  V1  [9219-8-3-49] -> [9217-3-1-32]  Rev.*
2  2997907210:2997907220  V0  [9219-8-3-42] -> [9217-3-1-32]  Rev.0
2.0  2997907210:2997907220  V1  [9219-8-3-71] -> [9217-3-1-33]  Rev.*
3  2997907220:2997907230  V0  [9219-8-3-69] -> [0-0-0-0]  Rev.0
3.0  2997907220:2997907230  V1  [9219-8-3-112] -> [9217-3-1-34]  Rev.*
*  2997907230:+Infinity+  LastInterval  [9219-8-3-110] -> [0-0-0-0]  Rev.0
...
% BdbIntervalUtil revisetop_update emc EmcFooClassP 1 –begin_validity 2997907220
Path I: Total of 1 TOPMOST intervals were found.
Path II: The revision 2 has been updated.
...
% BdbIntervalUtil genealogy emc EmcFooClassP
*  -Infinity-:2997907200  FirstInterval  [9219-8-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-8-3-18] -> [9217-3-1-30]  Rev.0
1.0  2997907200:2997907210  V1  [9219-8-3-49] -> [9217-3-1-32]  Rev.1
2  2997907210:2997907220  V0  [9219-8-3-42] -> [9217-3-1-32]  Rev.0
2.0  2997907210:2997907220  V1  [9219-8-3-71] -> [9217-3-1-33]  Rev.1
3  2997907220:2997907230  V0  [9219-8-3-69] -> [0-0-0-0]  Rev.0
3.0  2997907220:2997907230  V1  [9219-8-3-112] -> [9217-3-1-34]  Rev.1
*  2997907230:+Infinity+  LastInterval  [9219-8-3-110] -> [0-0-0-0]  Rev.0...

2.6.12 revisetopmany

DESCRIPTION:

This command behaves much like as the revisetop does for a single container but it’s able to process multiple interval containers. In addition it produces the updated configuration file with newly created revision numbers.

There are two complementary ways to specify containers to be processed:

·         via an explicit list of detectors/containers to be included into the operation;

·         or by specifying those detectors/containers which have to be excluded from the operation.

The following conditions are always excluded from the processing, no matter what type of selection above is chosen:

·         any "old" style interval containers that do not have symbolic links;

·         any non locally created interval containers (those ones having the origin which is different from the local origin of a federation where the procedure is being run.

Also the new revisions are not created at containers that do not have un-assigned (not belonging to any particular revision) intervals                 on the top.

On its input the command requires to specify the location of the most recent configuration file in order to calculate the base revision ID-s for new revisions.

On its output the command produces an updated configuration file at the specified location.

IMPORTANT: This is multi-transaction command. Each container (even those ones where new revisions are not created) is processed within its own transaction. See specific notes on this type of transaction management at: Transactions management.

NOTE: Since this type of operation may bring a lot of persistent objects into the process cache (managed by Objectivity's client code) then it would be wise to increase the default maximum for the cache size using the following method:

setenv OO_CACHE_MAX 4096

Do not forget to unset this environment variable when the operation is finished. Otherwise this may affect the performance of other application you may run afterwards.

SYNTAX:

BdbIntervalUtil revisetopmany <input_config> <output_config>
                { -include | -exclude } <list>
                [-description <description>]
                [-begin_validity <time> [-begin_validity_tzone <zone>]]
                [-end_validity   <time> [-end_validity_tzone   <zone>]]
                [-verbose]

PARAMETERS:

Mandatory

<input_config>

This is the input configuration file. The file must have valid contents because it’s used as a source of base revisions for the newly created ones.

<output_config>

This output file will be created in the end.

Mutually exclusive

-include <list>

A list of detectors/conditions to be included into processing. The list is specified either as a plain text file or as read from the Standard input, if ‘-‘ was passed instead of the file name.

-exclude <list>

A list of detectors/containers to be excluded from the processing. . The list is specified either as a plain text file or as read from the Standard input, if ‘-‘ was passed instead of the file name.

Optional

-description <description>

This is an optional comment for the new revision. It does not affect the functioning of the new revisions in any way. It just servers as an additional way to specify why new revisions are being created.

NOTE: All new revisions created by the command get the same description.

-begin_validity <time>

This parameter is meant to specify the left limit for the operation in the validity time. By default the search for intervals begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-begin_validity_tzone <zone>

This optional parameter is bound to the begin time limit. It’s meant to override the default time zone for the begin time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_validity <time>

This parameter is meant to specify the right limit for the operation in the validity time. By default the search for intervals ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-end_validity_tzone <zone>

This optional parameter is bound to the end time limit. It’s meant to override the default time zone for the end time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-verbose

Forces the command to print the containers name as they are processed. This option is strongly recommended.

AUTHORIZATION:

A user must be a member of every single detector group where the processed containers are located. It’s better to be a System Manager of the Conditions domain.

EXAMPLE:

...

2.6.13 revisetopmany_update

DESCRIPTION:

This command provides the same basic functionality as the revisetopmany does with the only exception – the intervals are upended to already existing revisions. Please, see this command first.

SYNTAX:

BdbIntervalUtil revisetopmany_update <input_config> <output_config>
                { -include | -exclude } <list>
                [-begin_validity <time> [-begin_validity_tzone <zone>]]
                [-end_validity   <time> [-end_validity_tzone   <zone>]]
                [-verbose]

PARAMETERS:

Mandatory

<input_config>

This is the input configuration file. The file must have valid contents because it’s used as a source of base revisions for the newly created ones.

<output_config>

This output file will be created in the end.

Mutually exclusive

-include <list>

A list of detectors/conditions to be included into processing. The list is specified either as a plain text file or as read from the Standard input, if ‘-‘ was passed instead of the file name.

-exclude <list>

A list of detectors/containers to be excluded from the processing. . The list is specified either as a plain text file or as read from the Standard input, if ‘-‘ was passed instead of the file name.

Optional

-begin_validity <time>

This parameter is meant to specify the left limit for the operation in the validity time. By default the search for intervals begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-begin_validity_tzone <zone>

This optional parameter is bound to the begin time limit. It’s meant to override the default time zone for the begin time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_validity <time>

This parameter is meant to specify the right limit for the operation in the validity time. By default the search for intervals ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

Optional

-end_validity_tzone <zone>

This optional parameter is bound to the end time limit. It’s meant to override the default time zone for the end time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-verbose

Forces the command to print the containers name as they are processed. This option is strongly recommended.

AUTHORIZATION:

A user must be a member of every single detector group where the processed containers are located. It’s better to be a System Manager of the Conditions domain.

EXAMPLE:

...

2.6.14 createrevision

DESCRIPTION:

Create a new revision based upon the specified one. An optional comment string can also be passed to the command to indicate a purpose the new revision is being created.

The new revision number will be printed onto the standard output. This number may not be just an increment of the specified base one since there may be other revisions with higher numbers in this container.

NOTE: This command does not connect any existing intervals to the newly created revision. What is does – it just creates the infrastructure for the new revision. This revision can later be updated by connecting new intervals to it. See the following commands for details: revise2d_update, reviseoids_update, revisetop_update and revisetopmany_update.

SYNTAX:

BdbIntervalUtil createrevision <detector> <container> <base_revision_id>
                [-description <description>]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

<base_revision_id>

This will be the base revision for the new revision.

Optional

-description <description>

This is an optional comment for the new revision. It does not affect the functioning of the new revision in any way. It just servers as an additional way to specify why a new revision is being created.

AUTHORIZATION:

A user must be a member of a detector group where the container is located.

EXAMPLE:

% BdbIntervalUtil dependencytree emc EmcFooClassP
0
+ - 1
    + - 3
        + - 5
+ - 2
    + - 4
...
% BdbIntervalUtil createrevision emc EmcFooClassP 4 –description “Just a test.”
A new revision 6 has been created.
...
% BdbIntervalUtil dependencytree emc EmcFooClassP
0
+ - 1
    + - 3
        + - 5
+ - 2
    + - 4
        + - 6
...

2.6.15 deleterevision

DESCRIPTION:

Delete an existing revision from the registry of the specified container. All the intervals explicitly associated with this revision will be disconnected from the revision and therefore they become unassigned ones.

A revision can only be deleted if there are no revisions based upon it. See the revision and other related commands to get more information on that subject.

In order to protect a revision against an accidental deletion an operator is asked to confirm the operation when the command is run with default set of parameters. This kind of behavior can intentionally be avoided by specifying an optional force switch.

IMPORTANT: Be careful with this command because you may loose important information and make the connected intervals eligible for deletion during the staircases purging operation (See the purge command for details.

SYNTAX:

BdbIntervalUtil deleterevision <detector> <container> <revision_id>
                [-force]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

<revision_id>

This is a revision targeted by the operation.

Optional

-force

This switch if omitted provides additional protection against the accidental deletion of a revision. If the switch is specified then the revision is deleted without any other additional questions, if there are no other restrictions for this of course.

AUTHORIZATION:

A user must be a member of a detector group where the container is located.

EXAMPLE:

% BdbIntervalUtil dependencytree emc EmcFooClassP
0
+ - 1
    + - 3
        + - 5
+ - 2
    + - 4
...
% BdbIntervalUtil deleterevision emc EmcFooClassP 2 –force
    The revision can't be deleted since it's being used as base revision
    by other revisions. Removing this revision would make the internal
    structure of the container inconsistent.
...
% BdbIntervalUtil deleterevision emc EmcFooClassP 4
 
##########################
##### deleterevision #####
##########################
 
    You are about to modify the database contents using
    the folowing parameters:
 
        Detector:   emc
        Container:  EmcFooClassP
 
        Revision ID: 3
        -> Found Revision Object: 9219-6-3-101
           -> Creation Time:    12/08/00 14:05:40 (local time) 0 ns
              Site:             slac
              Description:      This is a test revision
              Base revision ID: 1
 
    The found revision object will be deleted and all connected intervals
    dettached from this revision.
 
    NOTE: this operation can only be done if you posses desired privileges
          and if this revision is not a base revision for any other revisions
          in this container.
 
    Enter 'y' to confirm the operation: y
...

2.7 Browsing and managing the history

2.7.1 createhistory

DESCRIPTION:

This command is meant to turn on the use of the persistent History (logbook) for an interval container. The History is made of History records. Records represent actions modifying the contents of the interval container. The scope of the History is an interval container where the History is kept persistently. By default when a container is being created the History is created as well. A list of operations for which the History records are created (if this feature is turned on) can be found at: The History Records.

By default when the History is being created a copy of a target interval container is made. This copy has the same container name prefixed by _HISTORY_ in order to make this container invisible. This may appear as an unexpected delay in the command’s execution time for complex (having many intervals) container. To avoid nasty side effect there is an optional flag allowing to get rid of making backup. See command syntax for the details.

IMPORTANT: In general the presence of the History in a container may affect the performance of some operations dealing with the container since at least one persistent History record is created in the container in a course of these operations. This may not only increase the execution time of these operations but also means bigger (in a the persistent space) interval containers.

SYNTAX:

BdbIntervalUtil createhistory <detector> <container> [-nobackup]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

Optional

-nobackup

Tells the command not to create a backup of an interval container where the history is being created.

AUTHORIZATION:

A user must be a member of a detector group where the container is located.

EXAMPLE:

% BdbIntervalUtil containers emc -all -long
[ORIGIN:default]  EmcFooClassP
...
% BdbIntervalUtil createhistory emc EmcFooClassP
...
% BdbIntervalUtil containers emc -all -long
[HISTORY][ORIGIN:default]  EmcFooClassP
[HISTORY][ORIGIN:default]  _HISTORY_EmcFooClassP
...

2.7.2 removehistory

DESCRIPTION:

This command turns off the use of the persistent History (logbook) for an interval container. All existing History records are deleted. The backup interval container prefixed by _HISTORY_ if the one exists is deleted as well.

This command is the opposite one to the createhistory command.

SYNTAX:

BdbIntervalUtil removehistory <detector> <container>

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

AUTHORIZATION:

A user must be a member of a detector group where the container is located.

EXAMPLE:

% BdbIntervalUtil containers emc -all –long
[HISTORY][ORIGIN:default]  EmcFooClassP
[HISTORY][ORIGIN:default]  _HISTORY_EmcFooClassP
...
% BdbIntervalUtil removehistory emc EmcFooClassP
...
% BdbIntervalUtil containers emc -all -long
[ORIGIN:default]  EmcFooClassP
...

2.7.3 comment

DESCRIPTION:

The goal of this command is to place an arbitrary comment string into the History of an interval container. A new record of this type will appear in list along with other existing records. There are no special requirements on what has to be kept in this string. The new record is followed by the usual timestamp and the information of by whom and where the comment is made.

The operation requires the History to be turned on for the corresponding container

NOTE: A complete list of records can bee found at: The list of History Records.

SYNTAX:

BdbIntervalUtil comment <detector> <container> <comment>

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

<container>

The condition name.

<comment>

The comment string to be stored in the History.

AUTHORIZATION:

A user must be a member of a detector group where the container is located.

EXAMPLE:

% BdbIntervalUtil containers emc
{HISTORY][ORIGIN:default]  EmcFooClassP
...
% BdbIntervalUtil comment emc EmcFooClassP “This is just a test comment.”
...
% BdbIntervalUtil history emc EmcFooClassP
...

2.7.4 history

DESCRIPTION:

This command makes reports from the History of the specified interval container.

A simple filter based on the insertion time and/or types of the operations (History records) can optionally be applied. By default all the records stored in the History are reported in the ascending order.

SYNTAX:

BdbIntervalUtil history <detector> <container>
                [-operation <operation>]
                [-begin_time <time> [-begin_time_tzone <zone>]]
                [-end_time   <time> [-end_time_tzone   <zone>]]

PARAMETERS:

Mandatory

<detector>

This mandatory parameter narrows search to a specific detector group. Make sure that specified detector exists.

 

<container>

The condition name.

 

Optional

-operation <operation>

This parameter serves as a simple filter of a type of operations selected by the filter. By default all the operations are selected. See the values of possible operations at: The History Records.

 

-begin_time <time>

This parameter is meant to specify the staring time of the report. Only records past the specified insertion time will be chosen. By default the report begins from the logical minus infinity. See more information on how to specify the time at: “How to specify day and time”.

 

Optional

-begin_time_zone <zone>

This optional parameter is bound to the begin time limit. It’s meant to override the default time zone for the begin time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.

-end_time <time>

This parameter is meant to specify the ending time of the report. Only records before the specified insertion time will be chosen. By default the report ends at the logical plus infinity. See more information on how to specify the time at: “How to specify day and time”.

 

Optional

-end_time_zone <zone>

This optional parameter is bound to the end time limit. It’s meant to override the default time zone for the end time, which is “local” in the current implementation of the utility. See format of this parameter at: ”How to specify the time zone”.


AUTHORIZATION
:

EXAMPLE:

% BdbIntervalUtil history emc EmcFooClassP –operation COMMENT
 
########## Record #7 ##########
 
OPERATION: COMMENT
TIME: 12/07/00 18:59:39 (local time) 0 ns
SITE: slac
HOST: flora06
USER: gapon
CODE: $Id: BdbIntervalUtil.cc,v 1.38 2000/09/22 21:41:20 gapon Exp $
    COMMENT: This is just a test string.
 
Total of 1 of 8 were found.
...

2.8 Other operations

2.8.1 fetchnstore

2.8.2 removeinterval

3. Appendix

3.1 How to specify the day and time

Many commands supported by the utility require the day and time to be passed as parameters of these commands. Although the syntax of each command may vary from one command to the other one (in some cases the time may be required as a positional parameter, in the other cases the actual time can be preceded by a keyword), the syntax of the time itself remains the same.

Generally there are tree ways to specify the time:

·        In two extreme cases the time is specified as either of the two predefined keywords:

o       –Infinity (logical minus infinity)

o       +Infinity (logical plus infinity)

·        As a number of seconds since 00:00:00 of January 1, 1901;

·        In the human-readable format.

The parser of the BdbIntervalUtil will automatically determine the chosen format using the “best try” strategy.

When the time is entered as a pure number of seconds then 32-bit unsigned integer in a decimal format is expected on the input. Here are a few examples:

1234567890
4000000000
0
1

Two numbers 0 and 4294967296 are corresponding to the mentioned above extreme cases of -Infinity and +Infinity. The number must contain only digits in a range of ‘0’ to ‘9’. No “plus” or “minus” signs or any formulas are allowed. Otherwise the command parser will try another interpretation. The time can be taken into double quotes.

In those cases when the time is entered either as a pure number of seconds or as one of the mentioned above extreme keywords then any subsequent specifications of the time zone (see the next section) are simply ignored. No warning will be issued if the time zone is passed, although the command parser will still parse the time zone parameter(s). See more details on this subject from the subsequent section.

When the time has to be specified in the “human-readable” format then the following formats are allowed:

"20Jun1999 10:00:01"
"06/20/1999 10:00:01"

It’s very important to enclose a time parameter into double quotes to tell the command parser to treat this time as a single token. By default the “local” time zone is used to translate the time specified in this way unless the time zone is set explicitly to the other value. See the next section for the details.

3.2 How to specify the time zone

Only two options are allowed when specifying the time zone:

·        “local”

·        “UTC”

Any other values will be treated as syntax errors.

3.3 The formats of genealogy dumps

The format is a decimal number used by the genealogy dump commands to produce various forms (including the number of details) of the output. The following formats are available in the present implementation of the utility:

·        0 (default)

·        1

·        2

·        3

·        4

·        5

Here are examples illustrating the effect of each format when a full dump of genealogy is done.

Format 0:

BdbIntervalUtil genealogy emc EmcFooClassP –format 0
*  -Infinity-:2997907200  FirstInterval  [9219-6-3-17] -> [0-0-0-0]  Rev.0
1  2997907200:2997907210  V0  [9219-6-3-18] -> [9217-3-1-25]  Rev.0
1.0  2997907200:2997907210  V1  [9219-6-3-55] -> [9217-3-1-28]  Rev.*
2  2997907210:2997907220  V0  [9219-6-3-41] -> [9217-3-1-26]  Rev.0
2.0  2997907210:2997907220  V1  [9219-6-3-60] -> [9217-3-1-28]  Rev.*
*  2997907220:+Infinity+  LastInterval  [9219-6-3-48] -> [9217-3-1-28]  Rev.0
^  ^          ^           ^             ^                ^              ^
|  |          |           |             |                |              |
|  |          |           |             |                |              +----- The revision number (if any).
|  |          |           |             |                |
|  |          |           |             |                +----- The condition object OID.
|  |          |           |             +---------------------- The interval object OID.
|  |          |           |
|  |          |           +----- The interval object name. The meaning of this name depends on a scope.
|  |          |                  For “FirstInterval” and “LastInterval” it’s an interval container where
|  |          |                  the interval is physically located. For the names like “Vxxx” it’s
|  |          |                  a genealogy cluster of intervals growing from a baseline one.
|  |          |                  The ‘*’ means that interval does not have a name in any scope.
|  |          |
|  |          +------ The end time of the interval.
|  +----------------- The begin time of the interva.l
|
+----- The relative position of the interval at the current genealogy cluster. The cluster
       is growing from a baseline interval. The ‘*’ is the indication that there is just one (this one)
       interval in the cluster. ‘n’ means a baseline interval. ‘n.m’ means an immediate version of
       the basline interval.

Format 1:

BdbIntervalUtil genealogy emc EmcFooClassP -format 1
-Infinity-:2997907200  FirstInterval  [9219-6-3-17] -> [0-0-0-0]  Rev.0
2997907200:2997907210  V0  [9219-6-3-18] -> [9217-3-1-25]  Rev.0
2997907200:2997907210  V1  [9219-6-3-55] -> [9217-3-1-28]  Rev.*
2997907210:2997907220  V0  [9219-6-3-41] -> [9217-3-1-26]  Rev.0
2997907210:2997907220  V1  [9219-6-3-60] -> [9217-3-1-28]  Rev.*
2997907220:+Infinity+  LastInterval  [9219-6-3-48] -> [9217-3-1-28]  Rev.0
^          ^           ^             ^                ^              ^
|          |           |             |                |              |
|          |           |             |                |              +----- The revision number (if any).
|          |           |             |                |
|          |           |             |                +----- The condition object OID.
|          |           |             +---------------------- The interval object OID.
|          |           |
|          |           +----- The interval object name. The meaning of this name depends on a scope.
|          |                  For “FirstInterval” and “LastInterval” it’s an interval container where
|          |                  the interval is physically located. For the names like “Vxxx” it’s
|          |                  a genealogy cluster of intervals growing from a baseline one.
|          |                  The ‘*’ means that interval does not have a name in any scope.
|          |
|          +------ The end time of the interval.
+----------------- The begin time of the interval.

Format 2:

BdbIntervalUtil genealogy emc EmcFooClassP -format 2
-Infinity-:2997907200  [9219-6-3-17] -> [0-0-0-0]  FirstInterval *  Rev.0
2997907200:2997907210  [9219-6-3-18] -> [9217-3-1-25]  V0 1  Rev.0
2997907200:2997907210  [9219-6-3-55] -> [9217-3-1-28]  V1 1.0  Rev.*
2997907210:2997907220  [9219-6-3-41] -> [9217-3-1-26]  V0 2  Rev.0
2997907210:2997907220  [9219-6-3-60] -> [9217-3-1-28]  V1 2.0  Rev.*
2997907220:+Infinity+  [9219-6-3-48] -> [9217-3-1-28]  LastInterval *  Rev.0
^          ^           ^                ^              ^            ^  ^
|          |           |                |              |            |  |
|          |           |                |              |            |  +----- The revision number (if any).
|          |           |                |              |            |
|          |           |                |              |            +----- The relative position of the interval at the current
|          |           |                |              |                   genealogy cluster. The cluster is growing from
|          |           |                |              |                   a baseline interval. The ‘*’ is the indication that
|          |           |                |              |                   there is just one (this one) interval in the cluster.
|          |           |                |              |                   ‘n’ means a baseline interval. ‘n.m’ means an immediate
|          |           |                |              |                   version of the basline interval.
|          |           |                |              |
|          |           |                |              +----- The interval object name. The meaning of this name depends on a scope.
|          |           |                |                     For “FirstInterval” and “LastInterval” it’s an interval container where
|          |           |                |                     the interval is physically located. For the names like “Vxxx” it’s
|          |           |                |                     a genealogy cluster of intervals growing from a baseline one.
|          |           |                |                     The ‘*’ means that interval does not have a name in any scope.
|          |           |                |
|          |           |                +----- The condition object OID.
|          |           +---------------------- The interval object OID.
|          |
|          +------ The end time of the interval.
+----------------- The begin time of the interval.

Format 3:

BdbIntervalUtil genealogy emc EmcFooClassP -format 3
*  -Infinity-:2997907200  FirstInterval  [9219-6-3-17] at [11/15/00 09:50:50 (local time) 0 ns]  Rev.0
1  2997907200:2997907210  V0  [9219-6-3-18] at [11/15/00 09:50:50 (local time) 0 ns]  Rev.0
1.0  2997907200:2997907210  V1  [9219-6-3-55] at [11/15/00 09:51:03 (local time) 0 ns]  Rev.*
2  2997907210:2997907220  V0  [9219-6-3-41] at [11/15/00 09:50:50 (local time) 0 ns]  Rev.0
2.0  2997907210:2997907220  V1  [9219-6-3-60] at [11/15/00 09:51:03 (local time) 0 ns]  Rev.*
*  2997907220:+Infinity+  LastInterval  [9219-6-3-48] at [11/15/00 09:51:03 (local time) 0 ns]  Rev.0
^  ^          ^           ^             ^                ^                                      ^
|  |          |           |             |                |                                      |
|  |          |           |             |                |                                      +----- The revision number (if any).
|  |          |           |             |                |
|  |          |           |             |                +----- This is so called “version time” – the time when
|  |          |           |             |                       the corresponding condition object was created.
|  |          |           |             |
|  |          |           |             +---------------------- The interval object OID.
|  |          |           |
|  |          |           +----- The interval object name. The meaning of this name depends on a scope.
|  |          |                  For “FirstInterval” and “LastInterval” it’s an interval container where
|  |          |                  the interval is physically located. For the names like “Vxxx” it’s
|  |          |                  a genealogy cluster of intervals growing from a baseline one.
|  |          |                  The ‘*’ means that interval does not have a name in any scope.
|  |          |
|  |          +------ The end time of the interval.
|  +----------------- The begin time of the interval.
|
+----- The relative position of the interval at the current genealogy cluster. The cluster
       is growing from a baseline interval. The ‘*’ is the indication that there is just one (this one)
       interval in the cluster. ‘n’ means a baseline interval. ‘n.m’ means an immediate version of
       the basline interval.
 

Format 4:

BdbIntervalUtil genealogy emc EmcFooClassP -format 4
1 0 -Infinity- 2997907200 3151763450 FirstInterval 9219-6-3-17 0-0-0-0 0 0
0 0 2997907200 2997907210 3151763450 V0 9219-6-3-18 9217-3-1-25 0 0
1 1 2997907200 2997907210 3151763463 V1 9219-6-3-55 9217-3-1-28 0 *
0 0 2997907210 2997907220 3151763450 V0 9219-6-3-41 9217-3-1-26 0 0
1 1 2997907210 2997907220 3151763463 V1 9219-6-3-60 9217-3-1-28 0 *
1 0 2997907220 +Infinity+ 3151763463 LastInterval 9219-6-3-48 9217-3-1-28 0 0
^ ^ ^          ^          ^          ^            ^           ^           ^ ^
| | |          |          |          |            |           |           | |
| | |          |          |          |            |           |           | +----- The revision number or ‘*’ if
| | |          |          |          |            |           |           |        this interval does not belong
| | |          |          |          |            |           |           |        to any specific revision.
| | |          |          |          |            |           |           |
| | |          |          |          |            |           |           +----- The tag number. This is an obsolete
| | |          |          |          |            |           |                  feature of the current design.
| | |          |          |          |            |           |
| | |          |          |          |            |           +----- The condition object OID.
| | |          |          |          |            +----------------- The interval object OID.
| | |          |          |          |
| | |          |          |          +----- The interval object name. The meaning of this name depends on a scope.
| | |          |          |                 For “FirstInterval” and “LastInterval” it’s an interval container where
| | |          |          |                 the interval is physically located. For the names like “Vxxx” it’s
| | |          |          |                 a genealogy cluster of intervals growing from a baseline one.
| | |          |          |                 The ‘*’ means that interval does not have a name in any scope.
| | |          |          |
| | |          |          +----- This is so called “version time” – the time when the corresponding condition object
| | |          |                 was created. This time is specified as a number of seconds passed since
| | |          |                 00:00:00 Jan 1, 1901 (UTC).
| | |          |
| | |          +------ The end time of the interval.
| | +----------------- The begin time of the interval.
| |
| +----- This is a layer number where the interval is located. This number is equal to 0 for all
|        the baseline intervals, is equal to ‘1’ for their immediate versions, etc.
|
+----- This is a binary flag indicating whether this interval is the topmost one (if ‘1’) or not (‘0’).

Format 5:

BdbIntervalUtil genealogy emc EmcFooClassP -format 5
1 0 -Infinity-  31Dec1995  15Nov2000 FirstInterval 9219-6-3-17 0-0-0-0 0 0
0 0  31Dec1995  31Dec1995  15Nov2000 V0 9219-6-3-18 9217-3-1-25 0 0
1 1  31Dec1995  31Dec1995  15Nov2000 V1 9219-6-3-55 9217-3-1-28 0 *
0 0  31Dec1995  31Dec1995  15Nov2000 V0 9219-6-3-41 9217-3-1-26 0 0
1 1  31Dec1995  31Dec1995  15Nov2000 V1 9219-6-3-60 9217-3-1-28 0 *
1 0  31Dec1995 +Infinity+  15Nov2000 LastInterval 9219-6-3-48 9217-3-1-28 0 0
^ ^  ^         ^           ^         ^            ^           ^           ^ ^
| |  |         |           |         |            |           |           | |
| |  |         |           |         |            |           |           | +----- The revision number or ‘*’ if
| |  |         |           |         |            |           |           |        this interval does not belong
| |  |         |           |         |            |           |           |        to any specific revision.
| |  |         |           |         |            |           |           |
| |  |         |           |         |            |           |           +----- The tag number. This is an obsolete
| |  |         |           |         |            |           |                  feature of the current design.
| |  |         |           |         |            |           |
| |  |         |           |         |            |           +----- The condition object OID.
| |  |         |           |         |            +----------------- The interval object OID.
| |  |         |           |         |
| |  |         |           |         +----- The interval object name. The meaning of this name depends on a scope.
| |  |         |           |                For “FirstInterval” and “LastInterval” it’s an interval container where
| |  |         |           |                the interval is physically located. For the names like “Vxxx” it’s
| |  |         |           |                a genealogy cluster of intervals growing from a baseline one.
| |  |         |           |                The ‘*’ means that interval does not have a name in any scope.
| |  |         |           |
| |  |         |           +----- This is so called “version date” – the date when the corresponding condition object
| |  |         |                  was created. This date is specified in the “UTC” time zone.
| |  |         |
| |  |         +------ The end date of the interval. The date is specified in the “UTC” time zone.
| |  +----------------- The begin date of the interval. The date is specified in the “UTC” time zone.
| |
| +----- This is a layer number where the interval is located. This number is equal to 0 for all
|        the baseline intervals, is equal to ‘1’ for their immediate versions, etc.
|
+----- This is a binary flag indicating whether this interval is the topmost one (if ‘1’) or not (‘0’).

 

3.4 The list of origins

In the current implementation of the BaBar Database Software origins are mapped onto the so called “DBID ranges”, which specify the lists of Objectivity database identifiers available for storing various types of data (conditions, events, etc.). Each type of data can only be created in its own set of databases. Furthermore the data of the same type created in different (types of) federations may also go into different sets of databases. The latter is very important when these data from various are merged into a single one, or when they (data) are exchanged between these federations.

The origins are identified by names. The following names are used to store conditions in the current version (see The version of this document to get more ideas on this) of the BABAR Database software:

·        core

o       These databases can only be created in the IR2 federation.

o       The following identifiers are available for this range: 16-511.

·        opr-core

o       These databases can only be created in the OPR (Online Prompt Reconstruction) federation.

o       The following identifiers are available for this range: 512-1023.

·        anal-core

o       These databases can only be created in the Physics Analysis federation.

o       The following identifiers are available for this range: 1024-1535.

·        repro-core

o       These databases can only be created in the REPRO (Reprocessing) federation.

o       The following identifiers are available for this range: 1536-2047.

·        default

o       This name is reserved for the users’ test federations.

o       The following identifiers are available for this range: 9216-10239.

A complete list of database ID ranges (origins) can be obtained with the following command:

testDbIdRange

When a new condition is being created the Conditions/Db code always knows what’s the local origin name of a federation.

3.5 The History records

3.6 The configuration file format

A configuration file is a plain text file. The file content is case sensitive.

The very first line of this file always defines the version of the file:

V1

The following versions are known to the current implementation of the Conditions/DB code:

V1
V2
V3

The code supporting a later version is able to recognize the previous formats. The opposite is not true.

The rest of the configuration file contains definitions specific to particular conditions. Given a specific version of the file all these lines have the same syntax. Typically each line is meant to provide definitions for a particular condition. But it’s also possible (within the same syntax) to provide a definition for either of the following:

·        All conditions of all detectors (the system scope definition)

·        All conditions of a particular detector (a detector scope definition)

The following rules are followed when the file is loaded by the Conditions/DB code:

·        If no system scope definition is given then a default system scope definition is assumed.

o       NOTE: The meaning of the default depends on the version of the file.

·         Similarly, if no explicit detector definition is given then the previously established (either explicit or default one) system scope definition is used.

·        The detector scope definition if present overrides the system scope definition (either the default one or an explicit one if the later is available) for the corresponding detector.

·        A particular condition definition overrides both the system and detector scope definitions for a particular condition.

It’s also possible to have multiple definitions for the same system, detector or condition scopes throughout a single file. Should this be a case then the following rules are followed:

·        The system scope definition overrides the previous system scope definition only. The previous definitions for particular detectors and conditions do not change.

·        Similarly, the detector scope definition overrides the previous detector scope definition only. The previous definitions for particular conditions of this detector do not change.

·        The most recent definition for a particular condition always overrides the previous one.

Typically these definitions should come first as in the following example:

<version>
<system scope definition>
<detector scope default for ”emc” detector>
<individual definitions for “emc” conditions”>
...
<detector scope default for ”dch” detector>
<individual definitions for “dch” conditions”>
...

A minimal content of the file must be of two lines:

<version>
<any definition>

The following subsections describe the syntax of the configuration file for each of the mentioned above versions.

3.6.1 v1

All (except the very first one) lines have the following general format:

<detector> <condition> {0|1} <number>

Where:

<detector>  ß The detector name. Must be exactly 3 symbols in length.
               All symbols are in low case.
 
<container> ß The container name.
 
{0|1}       ß These are mutually exclusive options 0 or 1.
 
                 ‘1’ - topmost conditions are used.
                 ‘0’ – a revision is used. The revision number is expected as the next parameter.
 
<number>   ß The revision number (identifier).
              This parameter always present even if not used.

The wildcard character ‘*’ can be used instead of either or both the detector and container names. If this is the case then the following lines are treated as:

*   * ß The system scope default.
xxx * ß The detector “xxx” scope default.
* yyy ß Illegal syntax!!!

The system scope default is:

·        Use topmost intervals for all containers of all detectors

Here is an example configuration file:

V1
*   *            1 0
emc *            1 0
emc EmcFooClassP 0 3
svt *            1 0
svt SvtDetectorG 0 2

3.6.2 v2

All (except the very first one) lines have the following general format:

<detector> <condition> {0|1|<TOPMOST>|<REVISION>} <number> <user_area>

Where:

<detector>  ß The detector name. Must be exactly 3 symbols in length.
               All symbols are in low case.
 
<container> ß The container name.
 
{0|1|<TOPMOST>|<REVISION>}
 
            ß These are mutually exclusive options 0 or 1.
 
                 ‘1’ or <TOPMOST>  - topmost conditions are used.
                 ‘0’ or <REVISION> – a revision is used.
                                     The revision number is expected as the next parameter.
 
<number>   ß The revision number (identifier).
              This parameter always present even if not used.
 
<user_area>
 
           ß This parameter indicates if a condition is located in the so called “User Area”.
              The following values are expected:
 
                 <SYSTEM>   - The “User Area” is not used. The container is in a global space.
                 <USER>     – The container is in the “User Area” of the current user.
                 <username> - The container is in the are of a specified user.
                              This can be a user which is different from the current one.

The wildcard character ‘*’ can be used instead of either or both the detector and container names. If this is the case then the following lines are treated as:

*   * ß The system scope default.
xxx * ß The detector “xxx” scope default.
* yyy ß Illegal syntax!!!

The system scope default is:

·        Use topmost intervals for all containers of all detectors

·        Do not use “User Area” for any condition from any detector

Here is an example configuration file:

V2
*   *            <TOPMOST>  0 <SYSTEM>
emc *            <TOPMOST>  0 <USER>
emc EmcFooClassP <REVISION> 3 <SYSTEM>
svt *            <TOPMOST>  0 <SYSTEM>
svt SvtDetectorA <REVISION> 2 <USER>

3.6.3 v3

The only difference in the syntax of this version the version “V2” is two additional fields in the end of each line:

<detector> <condition> {0|1|<TOPMOST>|<REVISION>} <number> <user_area> <revise_after_store> <revision>

Where:

<revise_after_store>
 
           ß This parameter indicates if new (non-baseline) intervals are automatically revised or not.
              The following values are expected:
 
                 <>                   - Do not revise new intervals.
                 <REVISE_AFTER_STORE> – Do it.
                                        An existing revision identifier is expected in the next parameter.
 
<revision> ß The revision number (identifier) used to revise new intervals.

See the details on the first 5 fields at the previous section.

3.7 The definition of correctness for intervals in the context of revisions

Here we are assuming that a list of intervals is picked up for a new or updated revision.

These intervals (all together) are considered correct if:

·        They (all intervals in this list) do not overlap with each other in the validity time.

·        They are not the baseline ones.

·        They do not leave revision holes in a sub-tree of the genealogy where they are found. See a picture below.

 This example illustrates the meaning of a revision hole in the genealogy.

What else?