Odbxx

A C++11 object-oriented interface to the ODB (online database) was introduced in May 2020. You can think of it like a "magic" map/dictionary that automatically sends changes you make to the ODB, and receives updates that others have made.

The header for this odbxx interface is at odbxx.h and example usage in odbxx_test.cxx.

You can find more details about the ODB on the ODB Access and Use page, which includes links to the command-line, javascript, python, and non-object C++ interfaces.

Basic usage

The simplest usage is like:

// Grab a bit of the ODB
midas::odb exp("/Experiment");

// Simple read
std::cout << "The current transition timeout is " << exp["Transition timeout"] << std::endl;

// Make a change. The new value is automatically sent to the ODB.
// Most C++ operators are supported (++, += etc), or you can do a simple
// re-assignment like `exp["Transition timeout"] = 12345;`.
exp["Transition timeout"] += 100;

// Read the new value
std::cout << "The transition timeout is now " << exp["Transition timeout"] << std::endl;

You can automatically cast to regular data types (int, double) etc if you want a copy of the value to work with:

int curr_timeout = exp["Transition timeout"];

Automatic refreshing

You may temporarily disable the automatic updating to/from the ODB using odb::set_auto_refresh_write(false) and odb::set_auto_refresh_read(false).

If auto-refresh is enabled (the default), your new values are sent to the ODB as soon as you touch the value in the midas::odb object. The ODB is queried for new values whenever you access the value. In the above example, the ODB is queried 4 times (during construction of exp, and each time exp["Transition timeout"] is mentioned), and written to 1 time (when exp["Transition timeout"] is assigned to).

See the #Callback functions section below for details on how to have a function called when a value changes.

Arrays/vectors

ODB arrays are represented by std vectors.

You can access/edit individual elements using []:

odb["Example"][1] = 1.2;

You can completely re-assign content using a std::vector or std::array:

std::vector<float> vec = std::vector<float>(10);
odb["Example"] = vec;

You can resize arrays using odb::resize(). If the existing array is longer, it will be truncated; if shorter it will be extended with default values (0 or an empty string).

odb["Example"].resize(5); // Now is 5 elements long

Note that arithmetic operators are supported for arrays, and will apply the operation to ALL ELEMENTS IN THE ARRAY:

// Create the vector
std::vector<float> vec = std::vector<float>(2);
vec[0] = 3;
vec[1] = 5;

// Assign in ODB
odb["Example"] = vec;

// Multiply ALL elements by 2
odb["Example"] *= 2;

// odb["Example"] now contains {6, 10}.

You can directly iterate over arrays/vectors:

// Iterating using standard begin/end.
for (auto it = o["Int Array"].begin(); it != o["Int Array"].end(); it++) {
   int val = *it;
   std::cout << val << std::endl;
}

// Iterating using C++11 range-based for loop.
for (int val : o["Int Array"]) {
   std::cout << val << std::endl;
}

Strings

Strings in the ODB are returned as std::string (unlike the midas.h db_get_value() family of functions, where strings are returned as char*). You may have vectors of strings.

Creating new bits of the ODB

You can automatically create bits of the ODB by passing a struct to the midas::odb constructor, then calling odb::connect(), like:

// Define the ODB structure
midas::odb new_bit = {
   {"Int32 Key", 42},
   {"Bool Key", true},
   {"Subdir", {
      {"Float key", 1.2f},     // floats must be explicitly specified
   }},
   {"Int Array", {1, 2, 3}},
   {"Double Array", {1.2, 2.3, 3.4}},
   {"String Array", {"Hello1", "Hello2", "Hello3"}},
   {"Large Array", std::array<int, 10>{} },   // array with explicit size
   {"Large String", std::string(63, '\0') },  // string with explicit size
};

// Then sync the structure. Any keys that don't exist will be created; any
// that already exist will keep their existing values...
o.connect("/Test/Settings");

// ... unless you make the `write_defaults` argument true, in which case the
// existing values will be ignored, and overwritten with what you specified above.
o.connect("/Test/Settings", true);

If you want to add new keys to existing ODB subdirectories, you can also just use the [] operator:

midas::odb existing_key("/MyExistingKey");
existing_key["MyNewSubKey"] = 1.23;

You can also create new keys by providing a default value when reading a value. If the key doesn't already exist, the default value will be used.

midas::odb existing_key("/MyExistingKey");
double val = existing_key["MyNewSubKey"](1.23);

Iterating over subkeys

You can iterate over subkeys using normal iterator functions.

// Iterating using standard begin/end.
midas::odb exp("/Experiment");

for (auto it = exp.begin(); it != exp.end(); it++) {
   midas::odb& subkey = *it;
   std::cout << subkey.get_name() << " = " << subkey << std::endl;
}

// Iterating using C++11 range-based for loop.
for (midas::odb& subkey : exp) {
   std::cout << subkey.get_name() << " = " << subkey << std::endl;
}

You can check whether a subkey exists using odb::is_subkey().

Deleting bits of the ODB

You can use odb::delete_key() to remove part of the ODB:

midas::odb existing_bit("/Some/ODB/Path");
existing_bit.delete_key();

Callback functions

You may also set up callback functions that are called whenever a value changes, using the odb::watch() function. Note that you must call cm_yield() (from midas.h) periodically for this to work - deep down it is cm_yield() itself that calls your callback function.

The callback functions can either be a "normal" function or a C++ lambda. In either case, it should accept one argument - a midas::odb object (passed by reference) that contains the new state.

// Example with a lambda:
midas::odb to_watch("/Experiment");
to_watch.watch([](midas::odb &arg) {
   std::cout << "Value of key \"" + arg.get_full_path() + "\" changed to " << arg << std::endl;
});

// Example with a "normal" function:
void my_function(midas::odb &arg) {
   std::cout << "Value of key \"" + arg.get_full_path() + "\" changed to " << arg << std::endl;
}

midas::odb to_watch("/Experiment");
to_watch.watch(my_function);

Example code

A full working example exploring most of the features can be found in odbxx/odbxx_test.cxx. The test executable will be compiled as build/odbxx/odbxx_test (it is not installed in the `bin` directory).