Midas ODB Functions (db_xxx)
[The odb.c]


Functions

INT db_open_database (char *database_name, INT database_size, HNDLE *hDB, char *client_name)
INT db_close_database (HNDLE hDB)
INT db_lock_database (HNDLE hDB)
INT db_unlock_database (HNDLE hDB)
INT db_protect_database (HNDLE hDB)
INT db_create_key (HNDLE hDB, HNDLE hKey, char *key_name, DWORD type)
INT db_create_link (HNDLE hDB, HNDLE hKey, char *link_name, char *destination)
INT db_delete_key1 (HNDLE hDB, HNDLE hKey, INT level, BOOL follow_links)
INT db_delete_key (HNDLE hDB, HNDLE hKey, BOOL follow_links)
INT db_find_key (HNDLE hDB, HNDLE hKey, char *key_name, HNDLE *subhKey)
INT db_set_value (HNDLE hDB, HNDLE hKeyRoot, char *key_name, void *data, INT data_size, INT num_values, DWORD type)
INT db_get_value (HNDLE hDB, HNDLE hKeyRoot, char *key_name, void *data, INT *buf_size, DWORD type, BOOL create)
INT db_enum_key (HNDLE hDB, HNDLE hKey, INT index, HNDLE *subkey_handle)
INT db_get_key (HNDLE hDB, HNDLE hKey, KEY *key)
INT db_get_key_time (HNDLE hDB, HNDLE hKey, DWORD *delta)
INT db_get_key_info (HNDLE hDB, HNDLE hKey, char *name, INT name_size, INT *type, INT *num_values, INT *item_size)
INT db_get_data (HNDLE hDB, HNDLE hKey, void *data, INT *buf_size, DWORD type)
INT db_get_data_index (HNDLE hDB, HNDLE hKey, void *data, INT *buf_size, INT index, DWORD type)
INT db_set_data (HNDLE hDB, HNDLE hKey, void *data, INT buf_size, INT num_values, DWORD type)
INT db_set_data_index (HNDLE hDB, HNDLE hKey, void *data, INT data_size, INT index, DWORD type)
INT db_load (HNDLE hDB, HNDLE hKeyRoot, char *filename, BOOL bRemote)
INT db_copy (HNDLE hDB, HNDLE hKey, char *buffer, INT *buffer_size, char *path)
INT db_paste (HNDLE hDB, HNDLE hKeyRoot, char *buffer)
INT db_paste_xml (HNDLE hDB, HNDLE hKeyRoot, char *buffer)
INT db_copy_xml (HNDLE hDB, HNDLE hKey, char *buffer, INT *buffer_size)
INT db_save (HNDLE hDB, HNDLE hKey, char *filename, BOOL bRemote)
INT db_save_xml (HNDLE hDB, HNDLE hKey, char *filename)
INT db_save_struct (HNDLE hDB, HNDLE hKey, char *file_name, char *struct_name, BOOL append)
INT db_sprintf (char *string, void *data, INT data_size, INT index, DWORD type)
INT db_get_record_size (HNDLE hDB, HNDLE hKey, INT align, INT *buf_size)
INT db_get_record (HNDLE hDB, HNDLE hKey, void *data, INT *buf_size, INT align)
INT db_set_record (HNDLE hDB, HNDLE hKey, void *data, INT buf_size, INT align)
INT db_create_record (HNDLE hDB, HNDLE hKey, char *orig_key_name, char *init_str)
INT db_check_record (HNDLE hDB, HNDLE hKey, char *keyname, char *rec_str, BOOL correct)
INT db_open_record (HNDLE hDB, HNDLE hKey, void *ptr, INT rec_size, WORD access_mode, void(*dispatcher)(INT, INT, void *), void *info)
INT db_close_record (HNDLE hDB, HNDLE hKey)
INT db_close_all_records ()
INT db_update_record (INT hDB, INT hKey, int socket)
INT db_send_changed_records ()


Function Documentation

INT db_check_record HNDLE  hDB,
HNDLE  hKey,
char *  keyname,
char *  rec_str,
BOOL  correct
 

This function ensures that a certain ODB subtree matches a given C structure, by comparing the init_str with the current ODB structure. If the record does not exist at all, it is created with the default values in init_str. If it does exist but does not match the variables in init_str, the function returns an error if correct=FALSE or calls db_create_record() if correct=TRUE.

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
keyname Name of key to search, can contain directories.
rec_str ASCII representation of ODB record in the format
correct If TRUE, correct ODB record if necessary
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_NO_KEY, DB_STRUCT_MISMATCH

Definition at line 7441 of file odb.c.

Referenced by al_trigger_alarm(), cm_connect_experiment1(), and register_equipment().

INT db_close_all_records  ) 
 

Release local memory for open records. This routines is called by db_close_all_databases() and cm_disconnect_experiment()

Returns:
DB_SUCCESS, DB_INVALID_HANDLE

Definition at line 7921 of file odb.c.

Referenced by cm_disconnect_experiment().

INT db_close_database HNDLE  hDB  ) 
 

Close a database

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, RPC_NET_ERROR

Definition at line 1033 of file odb.c.

INT db_close_record HNDLE  hDB,
HNDLE  hKey
 

Close a record previously opend with db_open_record.

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
Returns:
DB_SUCCESS, DB_INVALID_HANDLE

Definition at line 7884 of file odb.c.

INT db_copy HNDLE  hDB,
HNDLE  hKey,
char *  buffer,
INT *  buffer_size,
char *  path
 

Copy an ODB subtree in ASCII format to a buffer

This function converts the binary ODB contents to an ASCII. The function db_paste() can be used to convert the ASCII representation back to binary ODB contents. The functions db_load() and db_save() internally use db_copy() and db_paste(). This function converts the binary ODB contents to an ASCII representation of the form:

  • For single value:
    [ODB path]
     key name = type : value
    
  • For strings:
    key name = STRING : [size] string contents
    
  • For arrayes (type can be BYTE, SBYTE, CHAR, WORD, SHORT, DWORD, INT, BOOL, FLOAT, DOUBLE, STRING or LINK):
    key name = type[size] :
     [0] value0
     [1] value1
     [2] value2
     ...
    
    Parameters:
    hDB ODB handle obtained via cm_get_experiment_database().
    hKey Handle for key where search starts, zero for root.
    buffer ASCII buffer which receives ODB contents.
    buffer_size Size of buffer, returns remaining space in buffer.
    path Internal use only, must be empty ("").
    Returns:
    DB_SUCCESS, DB_TRUNCATED, DB_NO_MEMORY

Definition at line 4998 of file odb.c.

Referenced by db_create_record(), and db_save().

INT db_copy_xml HNDLE  hDB,
HNDLE  hKey,
char *  buffer,
INT *  buffer_size
 

Copy an ODB subtree in XML format to a buffer

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
buffer ASCII buffer which receives ODB contents.
buffer_size Size of buffer, returns remaining space in buffer.
Returns:
DB_SUCCESS, DB_TRUNCATED, DB_NO_MEMORY

Definition at line 5705 of file odb.c.

INT db_create_key HNDLE  hDB,
HNDLE  hKey,
char *  key_name,
DWORD  type
 

Create a new key in a database

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Key handle to start with, 0 for root
key_name Name of key in the form "/key/key/key"
type Type of key, one of TID_xxx (see Midas Data Types)
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_INVALID_PARAM, DB_FULL, DB_KEY_EXIST, DB_NO_ACCESS

Definition at line 1453 of file odb.c.

Referenced by db_create_record(), db_get_value(), db_paste(), db_paste_node(), db_set_value(), and register_equipment().

INT db_create_link HNDLE  hDB,
HNDLE  hKey,
char *  link_name,
char *  destination
 

Create a link to a key or set the destination of and existing link.

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Key handle to start with, 0 for root
link_name Name of key in the form "/key/key/key"
destination Destination of link in the form "/key/key/key"
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_FULL, DB_KEY_EXIST, DB_NO_ACCESS

Definition at line 1692 of file odb.c.

INT db_create_record HNDLE  hDB,
HNDLE  hKey,
char *  orig_key_name,
char *  init_str
 

Create a record. If a part of the record exists alreay, merge it with the init_str (use values from the init_str only when they are not in the existing record).

This functions creates a ODB sub-tree according to an ASCII representation of that tree. See db_copy() for a description. It can be used to create a sub-tree which exactly matches a C structure. The sub-tree can then later mapped to the C structure ("hot-link") via the function db_open_record().

If a sub-tree exists already which exactly matches the ASCII representation, it is not modified. If part of the tree exists, it is merged with the ASCII representation where the ODB values have priority, only values not present in the ODB are created with the default values of the ASCII representation. It is therefore recommended that before creating an ODB hot-link the function db_create_record() is called to insure that the ODB tree and the C structure contain exactly the same values in the same order.

Following example creates a record under /Equipment/Trigger/Settings, opens a hot-link between that record and a local C structure trigger_settings and registers a callback function trigger_update() which gets called each time the record is changed.

struct {
  INT level1;
  INT level2;
} trigger_settings;
char *trigger_settings_str =
"[Settings]\n\
level1 = INT : 0\n\
level2 = INT : 0";
void trigger_update(INT hDB, INT hkey, void *info)
{
  printf("New levels: %d %d\n",
    trigger_settings.level1,
    trigger_settings.level2);
}
main()
{
  HNDLE hDB, hkey;
  char[128] info;
  ...
  cm_get_experiment_database(&hDB, NULL);
  db_create_record(hDB, 0, "/Equipment/Trigger", trigger_settings_str);
  db_find_key(hDB, 0,"/Equipment/Trigger/Settings", &hkey);
  db_open_record(hDB, hkey, &trigger_settings,
    sizeof(trigger_settings), MODE_READ, trigger_update, info);
  ...
}
Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
orig_key_name Name of key to search, can contain directories.
init_str Initialization string in the format of the db_copy/db_save functions.
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_FULL, DB_NO_ACCESS, DB_OPEN_RECORD

Definition at line 7271 of file odb.c.

Referenced by al_trigger_alarm(), analyzer_init(), cm_set_client_info(), db_check_record(), register_equipment(), and tr_start().

INT db_delete_key HNDLE  hDB,
HNDLE  hKey,
BOOL  follow_links
 

Delete a subtree in a database starting from a key (including this key).

...
    status = db_find_link(hDB, 0, str, &hkey);
    if (status != DB_SUCCESS)
    {
      cm_msg(MINFO,"my_delete"," "Cannot find key %s", str);
      return;
    }

    status = db_delete_key(hDB, hkey, FALSE);
    if (status != DB_SUCCESS)
    {
      cm_msg(MERROR,"my_delete"," "Cannot delete key %s", str);
      return;
    }
  ...
Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey for key where search starts, zero for root.
follow_links Follow links when TRUE.
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_NO_ACCESS, DB_OPEN_RECORD

Definition at line 1892 of file odb.c.

Referenced by cm_deregister_transition(), cm_set_client_info(), and db_create_record().

INT db_delete_key1 HNDLE  hDB,
HNDLE  hKey,
INT  level,
BOOL  follow_links
 

Delete a subtree, using level information (only called internally by db_delete_key())

For internal use only.

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Key handle to start with, 0 for root
level Recursion level, must be zero when
follow_links Follow links when TRUE called from a user routine
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_OPEN_RECORD

Definition at line 1722 of file odb.c.

Referenced by cm_delete_client_info(), and db_delete_key().

INT db_enum_key HNDLE  hDB,
HNDLE  hKey,
INT  index,
HNDLE *  subkey_handle
 

Enumerate subkeys from a key, follow links.

hkey must correspond to a valid ODB directory. The index is usually incremented in a loop until the last key is reached. Information about the sub-keys can be obtained with db_get_key(). If a returned key is of type TID_KEY, it contains itself sub-keys. To scan a whole ODB sub-tree, the function db_scan_tree() can be used.

INT   i;
HNDLE hkey, hsubkey;
KEY   key;
  db_find_key(hdb, 0, "/Runinfo", &hkey);
  for (i=0 ; ; i++)
  {
   db_enum_key(hdb, hkey, i, &hsubkey);
   if (!hSubkey)
    break; // end of list reached
   // print key name
   db_get_key(hdb, hkey, &key);
   printf("%s\n", key.name);
  }
Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
index Subkey index, sould be initially 0, then incremented in each call until subhKey becomes zero and the function returns DB_NO_MORE_SUBKEYS
subkey_handle Handle of subkey which can be used in db_get_key() and db_get_data()
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_NO_MORE_SUBKEYS

Definition at line 3156 of file odb.c.

Referenced by cm_connect_client(), cm_exist(), cm_set_client_info(), cm_shutdown(), cm_transition(), db_save_xml_key(), load_fragment(), logger_root(), and update_odb().

INT db_find_key HNDLE  hDB,
HNDLE  hKey,
char *  key_name,
HNDLE *  subhKey
 

Returns key handle for a key with a specific name.

Keys can be accessed by their name including the directory or by a handle. A key handle is an internal offset to the shared memory where the ODB lives and allows a much faster access to a key than via its name.

The function db_find_key() must be used to convert a key name to a handle. Most other database functions use this key handle in various operations.

HNDLE hkey, hsubkey;
// use full name, start from root
db_find_key(hDB, 0, "/Runinfo/Run number", &hkey);
// start from subdirectory
db_find_key(hDB, 0, "/Runinfo", &hkey);
db_find_key(hdb, hkey, "Run number", &hsubkey);
Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
key_name Name of key to search, can contain directories.
subhKey Returned handle of key, zero if key cannot be found.
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_NO_ACCESS, DB_NO_KEY

Definition at line 1925 of file odb.c.

Referenced by al_trigger_alarm(), analyzer_init(), cm_connect_client(), cm_deregister_transition(), cm_exist(), cm_get_client_info(), cm_msg_log(), cm_msg_log1(), cm_msg_retrieve(), cm_register_deferred_transition(), cm_register_transition(), cm_set_client_info(), cm_shutdown(), cm_transition(), db_check_record(), db_create_link(), db_create_record(), db_delete_key1(), db_enum_key(), db_get_value(), db_paste(), db_paste_xml(), db_set_value(), load_fragment(), logger_root(), register_equipment(), tr_start(), and update_odb().

INT db_get_data HNDLE  hDB,
HNDLE  hKey,
void *  data,
INT *  buf_size,
DWORD  type
 

Get key data from a handle

The function returns single values or whole arrays which are contained in an ODB key. Since the data buffer is of type void, no type checking can be performed by the compiler. Therefore the type has to be explicitly supplied, which is checked against the type stored in the ODB.

  HNLDE hkey;
  INT   run_number, size;
  // get key handle for run number
  db_find_key(hDB, 0, "/Runinfo/Run number", &hkey);
  // return run number
  size = sizeof(run_number);
  db_get_data(hDB, hkey, &run_number, &size,TID_INT);
Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
data Pointer to the return data.
buf_size Size of data buffer.
type Type of key, one of TID_xxx (see Midas Data Types).
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_TRUNCATED, DB_TYPE_MISMATCH

Definition at line 3925 of file odb.c.

Referenced by cm_connect_client(), cm_get_client_info(), cm_set_client_info(), db_copy(), db_get_record(), db_save_xml_key(), and tr_start().

INT db_get_data_index HNDLE  hDB,
HNDLE  hKey,
void *  data,
INT *  buf_size,
INT  index,
DWORD  type
 

returns a single value of keys containing arrays of values.

The function returns a single value of keys containing arrays of values.

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
data Size of data buffer.
buf_size Return size of the record.
index Index of array [0..n-1].
type Type of key, one of TID_xxx (see Midas Data Types).
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_TRUNCATED, DB_OUT_OF_RANGE

Definition at line 4151 of file odb.c.

Referenced by cm_transition().

INT db_get_key HNDLE  hDB,
HNDLE  hKey,
KEY key
 

Get key structure from a handle.

KEY structure has following format:

typedef struct {
  DWORD         type;                 // TID_xxx type
  INT           num_values;           // number of values
  char          name[NAME_LENGTH];    // name of variable
  INT           data;                 // Address of variable (offset)
  INT           total_size;           // Total size of data block
  INT           item_size;            // Size of single data item
  WORD          access_mode;          // Access mode
  WORD          notify_count;         // Notify counter
  INT           next_key;             // Address of next key
  INT           parent_keylist;       // keylist to which this key belongs
  INT           last_written;         // Time of last write action
} KEY;
Most of these values are used for internal purposes, the values which are of public interest are type, num_values, and name. For keys which contain a single value, num_values equals to one and total_size equals to item_size. For keys which contain an array of strings (TID_STRING), item_size equals to the length of one string.
KEY   key;
HNDLE hkey;
db_find_key(hDB, 0, "/Runinfo/Run number", &hkey);
db_get_key(hDB, hkey, &key);
printf("The run number is of type %s\n", rpc_tid_name(key.type));
Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
key Pointer to KEY stucture.
Returns:
DB_SUCCESS, DB_INVALID_HANDLE

Definition at line 3488 of file odb.c.

Referenced by cm_check_client(), cm_register_transition(), cm_shutdown(), cm_transition(), db_check_record(), db_copy(), db_get_record(), db_get_record_size(), db_open_record(), db_paste(), db_save_struct(), db_save_xml_key(), db_set_record(), load_fragment(), tr_start(), and update_odb().

INT db_get_key_info HNDLE  hDB,
HNDLE  hKey,
char *  name,
INT  name_size,
INT *  type,
INT *  num_values,
INT *  item_size
 

Get key info (separate values instead of structure)

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle of key to operate on
name Key name
name_size Size of the give name (done with sizeof())
type Key type (see Midas Data Types).
num_values Number of values in key.
item_size Size of individual key value (used for strings)
Returns:
DB_SUCCESS, DB_INVALID_HANDLE

Definition at line 3610 of file odb.c.

INT db_get_key_time HNDLE  hDB,
HNDLE  hKey,
DWORD *  delta
 

Get time when key was last modified

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle of key to operate on
delta Seconds since last update
Returns:
DB_SUCCESS, DB_INVALID_HANDLE

Definition at line 3552 of file odb.c.

INT db_get_record HNDLE  hDB,
HNDLE  hKey,
void *  data,
INT *  buf_size,
INT  align
 

Copy a set of keys to local memory.

An ODB sub-tree can be mapped to a C structure automatically via a hot-link using the function db_open_record() or manually with this function. Problems might occur if the ODB sub-tree contains values which don't match the C structure. Although the structure size is checked against the sub-tree size, no checking can be done if the type and order of the values in the structure are the same than those in the ODB sub-tree. Therefore it is recommended to use the function db_create_record() before db_get_record() is used which ensures that both are equivalent.

struct {
  INT level1;
  INT level2;
} trigger_settings;
char *trigger_settings_str =
"[Settings]\n\
level1 = INT : 0\n\
level2 = INT : 0";

main()
{
  HNDLE hDB, hkey;
  INT   size;
  ...
  cm_get_experiment_database(&hDB, NULL);
  db_create_record(hDB, 0, "/Equipment/Trigger", trigger_settings_str);
  db_find_key(hDB, 0, "/Equipment/Trigger/Settings", &hkey);
  size = sizeof(trigger_settings);
  db_get_record(hDB, hkey, &trigger_settings, &size, 0);
  ...
}
Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
data Pointer to the retrieved data.
buf_size Size of data structure, must be obtained via sizeof(RECORD-NAME).
align Byte alignment calculated by the stub and passed to the rpc side to align data according to local machine. Must be zero when called from user level.
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_STRUCT_SIZE_MISMATCH

Definition at line 6775 of file odb.c.

Referenced by al_trigger_alarm(), cm_transition(), db_open_record(), db_update_record(), register_equipment(), and tr_start().

INT db_get_record_size HNDLE  hDB,
HNDLE  hKey,
INT  align,
INT *  buf_size
 

Calculates the size of a record.

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
align Byte alignment calculated by the stub and passed to the rpc side to align data according to local machine. Must be zero when called from user level
buf_size Size of record structure
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_TYPE_MISMATCH, DB_STRUCT_SIZE_MISMATCH, DB_NO_KEY

Definition at line 6689 of file odb.c.

Referenced by db_get_record(), db_open_record(), and db_set_record().

INT db_get_value HNDLE  hDB,
HNDLE  hKeyRoot,
char *  key_name,
void *  data,
INT *  buf_size,
DWORD  type,
BOOL  create
 

Get value of a single key.

The function returns single values or whole arrays which are contained in an ODB key. Since the data buffer is of type void, no type checking can be performed by the compiler. Therefore the type has to be explicitly supplied, which is checked against the type stored in the ODB. key_name can contain the full path of a key (like: "/Equipment/Trigger/Settings/Level1") while hkey is zero which refers to the root, or hkey can refer to a sub-directory (like: /Equipment/Trigger) and key_name is interpreted relative to that directory like "Settings/Level1".

INT level1, size;
  size = sizeof(level1);
  db_get_value(hDB, 0, "/Equipment/Trigger/Settings/Level1",
                                   &level1, &size, TID_INT, 0);
Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKeyRoot Handle for key where search starts, zero for root.
key_name Name of key to search, can contain directories.
data Address of data.
buf_size Maximum buffer size on input, number of written bytes on return.
type Type of key, one of TID_xxx (see Midas Data Types)
create If TRUE, create key if not existing
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_NO_ACCESS, DB_TYPE_MISMATCH, DB_TRUNCATED, DB_NO_KEY

Definition at line 2997 of file odb.c.

Referenced by al_trigger_alarm(), ana_end_of_run(), cm_check_client(), cm_connect_experiment1(), cm_exist(), cm_msg_log(), cm_msg_log1(), cm_msg_retrieve(), cm_register_deferred_transition(), cm_set_client_info(), cm_shutdown(), cm_transition(), el_submit(), load_fragment(), logger_root(), register_equipment(), scheduler(), and tr_start().

INT db_load HNDLE  hDB,
HNDLE  hKeyRoot,
char *  filename,
BOOL  bRemote
 

Load a branch of a database from an .ODB file.

This function is used by the ODBEdit command load. For a description of the ASCII format, see db_copy(). Data can be loaded relative to the root of the ODB (hkey equal zero) or relative to a certain key.

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKeyRoot Handle for key where search starts, zero for root.
filename Filename of .ODB file.
bRemote If TRUE, the file is loaded by the server process on the back-end, if FALSE, it is loaded from the current process
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_FILE_ERROR

Definition at line 4913 of file odb.c.

INT db_lock_database HNDLE  hDB  ) 
 

Lock a database for exclusive access via system mutex calls.

Parameters:
hDB Handle to the database to lock
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_TIMEOUT

Definition at line 1313 of file odb.c.

Referenced by cm_check_client(), cm_cleanup(), cm_delete_client_info(), cm_get_watchdog_info(), cm_set_client_info(), cm_set_watchdog_params(), db_close_database(), db_create_key(), db_create_record(), db_delete_key1(), db_enum_key(), db_find_key(), db_get_data(), db_get_data_index(), db_get_key(), db_get_key_info(), db_get_key_time(), db_get_record(), db_get_record_size(), db_get_value(), db_open_database(), db_set_data(), db_set_data_index(), db_set_record(), and db_set_value().

INT db_open_database char *  database_name,
INT  database_size,
HNDLE *  hDB,
char *  client_name
 

Open an online database

Parameters:
database_name Database name.
database_size Initial size of database if not existing
client_name Name of this application
hDB ODB handle obtained via cm_get_experiment_database().
Returns:
DB_SUCCESS, DB_CREATED, DB_INVALID_NAME, DB_NO_MEMORY, DB_MEMSIZE_MISMATCH, DB_NO_MUTEX, DB_INVALID_PARAM, RPC_NET_ERROR

Definition at line 720 of file odb.c.

Referenced by cm_connect_experiment1().

INT db_open_record HNDLE  hDB,
HNDLE  hKey,
void *  ptr,
INT  rec_size,
WORD  access_mode,
void(*)(INT, INT, void *)  dispatcher,
void *  info
 

Open a record. Create a local copy and maintain an automatic update.

This function opens a hot-link between an ODB sub-tree and a local structure. The sub-tree is copied to the structure automatically every time it is modified by someone else. Additionally, a callback function can be declared which is called after the structure has been updated. The callback function receives the database handle and the key handle as parameters.

Problems might occur if the ODB sub-tree contains values which don't match the C structure. Although the structure size is checked against the sub-tree size, no checking can be done if the type and order of the values in the structure are the same than those in the ODB sub-tree. Therefore it is recommended to use the function db_create_record() before db_open_record() is used which ensures that both are equivalent.

The access mode might either be MODE_READ or MODE_WRITE. In read mode, the ODB sub-tree is automatically copied to the local structure when modified by other clients. In write mode, the local structure is copied to the ODB sub-tree if it has been modified locally. This update has to be manually scheduled by calling db_send_changed_records() periodically in the main loop. The system keeps a copy of the local structure to determine if its contents has been changed.

If MODE_ALLOC is or'ed with the access mode, the memory for the structure is allocated internally. The structure pointer must contain a pointer to a pointer to the structure. The internal memory is released when db_close_record() is called.

  • To open a record in write mode.
    struct {
      INT level1;
      INT level2;
    } trigger_settings;
    char *trigger_settings_str =
    "[Settings]\n\
    level1 = INT : 0\n\
    level2 = INT : 0";
    main()
    {
      HNDLE hDB, hkey, i=0;
      ...
      cm_get_experiment_database(&hDB, NULL);
      db_create_record(hDB, 0, "/Equipment/Trigger", trigger_settings_str);
      db_find_key(hDB, 0,"/Equipment/Trigger/Settings", &hkey);
      db_open_record(hDB, hkey, &trigger_settings, sizeof(trigger_settings)
                      , MODE_WRITE, NULL);
      do
      {
        trigger_settings.level1 = i++;
        db_send_changed_records()
        status = cm_yield(1000);
      } while (status != RPC_SHUTDOWN && status != SS_ABORT);
      ...
    }
    
    Parameters:
    hDB ODB handle obtained via cm_get_experiment_database().
    hKey Handle for key where search starts, zero for root.
    ptr If access_mode includes MODE_ALLOC: Address of pointer which points to the record data after the call if access_mode includes not MODE_ALLOC: Address of record if ptr==NULL, only the dispatcher is called.
    rec_size Record size in bytes
    access_mode Mode for opening record, either MODE_READ or MODE_WRITE. May be or'ed with MODE_ALLOC to let db_open_record allocate the memory for the record.
    (*dispatcher) Function which gets called when record is updated.The argument list composed of: HNDLE hDB, HNDLE hKey, void *info
    info Additional info passed to the dispatcher.
    Returns:
    DB_SUCCESS, DB_INVALID_HANDLE, DB_NO_MEMORY, DB_NO_ACCESS, DB_STRUCT_SIZE_MISMATCH

Definition at line 7750 of file odb.c.

Referenced by analyzer_init(), cm_register_deferred_transition(), and register_equipment().

INT db_paste HNDLE  hDB,
HNDLE  hKeyRoot,
char *  buffer
 

Copy an ODB subtree in ASCII format from a buffer

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKeyRoot Handle for key where search starts, zero for root.
buffer NULL-terminated buffer
Returns:
DB_SUCCESS, DB_TRUNCATED, DB_NO_MEMORY

Definition at line 5253 of file odb.c.

Referenced by db_create_record(), and db_load().

int db_paste_node HNDLE  hDB,
HNDLE  hKeyRoot,
PMXML_NODE  node
 

Definition at line 5531 of file odb.c.

Referenced by db_paste_xml().

INT db_paste_xml HNDLE  hDB,
HNDLE  hKeyRoot,
char *  buffer
 

Paste an ODB subtree in XML format from a buffer

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKeyRoot Handle for key where search starts, zero for root.
buffer NULL-terminated buffer
Returns:
DB_SUCCESS, DB_INVALID_PARAM, DB_NO_MEMORY, DB_TYPE_MISMATCH

Definition at line 5666 of file odb.c.

Referenced by db_load().

INT db_protect_database HNDLE  hDB  ) 
 

Protect a database for read/write access outside of the db_xxx functions

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
Returns:
DB_SUCCESS, DB_INVALID_HANDLE

Definition at line 1396 of file odb.c.

INT db_save HNDLE  hDB,
HNDLE  hKey,
char *  filename,
BOOL  bRemote
 

Save a branch of a database to an .ODB file

This function is used by the ODBEdit command save. For a description of the ASCII format, see db_copy(). Data of the whole ODB can be saved (hkey equal zero) or only a sub-tree.

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
filename Filename of .ODB file.
bRemote Flag for saving database on remote server.
Returns:
DB_SUCCESS, DB_FILE_ERROR

Definition at line 5882 of file odb.c.

INT db_save_struct HNDLE  hDB,
HNDLE  hKey,
char *  file_name,
char *  struct_name,
BOOL  append
 

Save a branch of a database to a C structure .H file

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
file_name Filename of .ODB file.
struct_name Name of structure. If struct_name == NULL, the name of the key is used.
append If TRUE, append to end of existing file
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_FILE_ERROR

Definition at line 6137 of file odb.c.

INT db_save_xml HNDLE  hDB,
HNDLE  hKey,
char *  filename
 

Save a branch of a database to an .xml file

This function is used by the ODBEdit command save to write the contents of the ODB into a XML file. Data of the whole ODB can be saved (hkey equal zero) or only a sub-tree.

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
filename Filename of .XML file.
Returns:
DB_SUCCESS, DB_FILE_ERROR

Definition at line 6084 of file odb.c.

INT db_save_xml_key HNDLE  hDB,
HNDLE  hKey,
INT  level,
MXML_WRITER *  writer
 

Definition at line 5981 of file odb.c.

Referenced by db_copy_xml(), and db_save_xml().

INT db_send_changed_records  ) 
 

Send all records to the ODB which were changed locally since the last call to this function.

This function is valid if used in conjunction with db_open_record() under the condition the record is open as MODE_WRITE access code.

  • Full example dbchange.c which can be compiled as follow
    gcc -DOS_LINUX -I/midas/include -o dbchange dbchange.c
    /midas/linux/lib/libmidas.a -lutil}
    
    \begin{verbatim}
    //------- dbchange.c
    #include "midas.h"
    #include "msystem.h"
    

//-------- BOF dbchange.c
typedef struct {
    INT    my_number;
    float   my_rate;
} MY_STATISTICS;

MY_STATISTICS myrec;

#define MY_STATISTICS(_name) char *_name[] = {\
"My Number = INT : 0",\
"My Rate = FLOAT : 0",\
"",\
NULL }

HNDLE hDB, hKey;

// Main
int main(unsigned int argc,char **argv)
{
  char      host_name[HOST_NAME_LENGTH];
  char      expt_name[HOST_NAME_LENGTH];
  INT       lastnumber, status, msg;
  BOOL      debug=FALSE;
  char      i, ch;
  DWORD     update_time, mainlast_time;
  MY_STATISTICS (my_stat);

  // set default
  host_name[0] = 0;
  expt_name[0] = 0;

  // get default
  cm_get_environment(host_name, sizeof(host_name), expt_name, sizeof(expt_name));

  // get parameters
  for (i=1 ; i<argc ; i++)
  {
    if (argv[i][0] == '-' && argv[i][1] == 'd')
      debug = TRUE;
    else if (argv[i][0] == '-')
    {
      if (i+1 >= argc || argv[i+1][0] == '-')
        goto usage;
      if (strncmp(argv[i],"-e",2) == 0)
        strcpy(expt_name, argv[++i]);
      else if (strncmp(argv[i],"-h",2)==0)
        strcpy(host_name, argv[++i]);
    }
    else
    {
   usage:
      printf("usage: dbchange [-h <Hostname>] [-e <Experiment>]\n");
      return 0;
    }
  }

  // connect to experiment
  status = cm_connect_experiment(host_name, expt_name, "dbchange", 0);
  if (status != CM_SUCCESS)
    return 1;

  // Connect to DB
  cm_get_experiment_database(&hDB, &hKey);

  // Create a default structure in ODB
  db_create_record(hDB, 0, "My statistics", strcomb(my_stat));

  // Retrieve key for that strucutre in ODB
  if (db_find_key(hDB, 0, "My statistics", &hKey) != DB_SUCCESS)
  {
    cm_msg(MERROR, "mychange", "cannot find My statistics");
    goto error;
  }

  // Hot link this structure in Write mode
  status = db_open_record(hDB, hKey, &myrec
                          , sizeof(MY_STATISTICS), MODE_WRITE, NULL, NULL);
  if (status != DB_SUCCESS)
  {
    cm_msg(MERROR, "mychange", "cannot open My statistics record");
    goto error;
  }

  // initialize ss_getchar()
  ss_getchar(0);

  // Main loop
  do
  {
    // Update local structure
    if ((ss_millitime() - update_time) > 100)
    {
      myrec.my_number += 1;
      if (myrec.my_number - lastnumber) {
        myrec.my_rate = 1000.f * (float) (myrec.my_number - lastnumber)
          / (float) (ss_millitime() - update_time);
      }
      update_time = ss_millitime();
      lastnumber = myrec.my_number;
    }

    // Publish local structure to ODB (db_send_changed_record)
    if ((ss_millitime() - mainlast_time) > 5000)
    {
      db_send_changed_records();                   // <------- Call
      mainlast_time = ss_millitime();
    }

    // Check for keyboard interaction
    ch = 0;
    while (ss_kbhit())
    {
      ch = ss_getchar(0);
      if (ch == -1)
        ch = getchar();
      if ((char) ch == '!')
        break;
    }
    msg = cm_yield(20);
  } while (msg != RPC_SHUTDOWN && msg != SS_ABORT && ch != '!');

 error:
  cm_disconnect_experiment();
  return 1;
}
//-------- EOF dbchange.c
Returns:
DB_SUCCESS

Definition at line 8164 of file odb.c.

Referenced by scan_fragment(), scheduler(), and tr_stop().

INT db_set_data HNDLE  hDB,
HNDLE  hKey,
void *  data,
INT  buf_size,
INT  num_values,
DWORD  type
 

Set key data from a handle. Adjust number of values if previous data has different size.

HNLDE hkey;
 INT   run_number;
 // get key handle for run number
 db_find_key(hDB, 0, "/Runinfo/Run number", &hkey);
 // set run number
 db_set_data(hDB, hkey, &run_number, sizeof(run_number),TID_INT);
Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
data Buffer from which data gets copied to.
buf_size Size of data buffer.
num_values Number of data values (for arrays).
type Type of key, one of TID_xxx (see Midas Data Types).
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_TRUNCATED

Definition at line 4278 of file odb.c.

Referenced by db_paste(), db_paste_node(), db_set_record(), and update_odb().

INT db_set_data_index HNDLE  hDB,
HNDLE  hKey,
void *  data,
INT  data_size,
INT  index,
DWORD  type
 

Set key data for a key which contains an array of values.

This function sets individual values of a key containing an array. If the index is larger than the array size, the array is extended and the intermediate values are set to zero.

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
data Pointer to single value of data.
data_size 
index Size of single data element.
type Type of key, one of TID_xxx (see Midas Data Types).
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_NO_ACCESS, DB_TYPE_MISMATCH

Definition at line 4502 of file odb.c.

Referenced by cm_register_transition(), and db_paste_node().

INT db_set_record HNDLE  hDB,
HNDLE  hKey,
void *  data,
INT  buf_size,
INT  align
 

Copy a set of keys from local memory to the database.

An ODB sub-tree can be mapped to a C structure automatically via a hot-link using the function db_open_record() or manually with this function. Problems might occur if the ODB sub-tree contains values which don't match the C structure. Although the structure size is checked against the sub-tree size, no checking can be done if the type and order of the values in the structure are the same than those in the ODB sub-tree. Therefore it is recommended to use the function db_create_record() before using this function.

...
  memset(&lazyst,0,size);
  if (db_find_key(hDB, pLch->hKey, "Statistics",&hKeyst) == DB_SUCCESS)
    status = db_set_record(hDB, hKeyst, &lazyst, size, 0);
  else
    cm_msg(MERROR,"task","record %s/statistics not found", pLch->name)
...
Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
data Pointer where data is stored.
buf_size Size of data structure, must be obtained via sizeof(RECORD-NAME).
align Byte alignment calculated by the stub and passed to the rpc side to align data according to local machine. Must be zero when called from user level.
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_TYPE_MISMATCH, DB_STRUCT_SIZE_MISMATCH

Definition at line 6879 of file odb.c.

Referenced by al_trigger_alarm(), db_open_record(), db_send_changed_records(), register_equipment(), and update_odb().

INT db_set_value HNDLE  hDB,
HNDLE  hKeyRoot,
char *  key_name,
void *  data,
INT  data_size,
INT  num_values,
DWORD  type
 

Set value of a single key.

The function sets a single value or a whole array to a ODB key. Since the data buffer is of type void, no type checking can be performed by the compiler. Therefore the type has to be explicitly supplied, which is checked against the type stored in the ODB. key_name can contain the full path of a key (like: "/Equipment/Trigger/Settings/Level1") while hkey is zero which refers to the root, or hkey can refer to a sub-directory (like /Equipment/Trigger) and key_name is interpreted relative to that directory like "Settings/Level1".

INT level1;
  db_set_value(hDB, 0, "/Equipment/Trigger/Settings/Level1",
                          &level1, sizeof(level1), 1, TID_INT);
Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKeyRoot Handle for key where search starts, zero for root.
key_name Name of key to search, can contain directories.
data Address of data.
data_size Size of data (in bytes).
num_values Number of data elements.
type Type of key, one of TID_xxx (see Midas Data Types)
Returns:
DB_SUCCESS, DB_INVALID_HANDLE, DB_NO_ACCESS, DB_TYPE_MISMATCH

Definition at line 2864 of file odb.c.

Referenced by al_trigger_alarm(), cm_connect_experiment1(), cm_delete_client_info(), cm_register_deferred_transition(), cm_register_transition(), cm_set_client_info(), cm_set_transition_sequence(), cm_set_watchdog_params(), cm_transition(), db_create_link(), db_get_value(), register_equipment(), tr_start(), and update_odb().

INT db_sprintf char *  string,
void *  data,
INT  data_size,
INT  index,
DWORD  type
 

Convert a database value to a string according to its type.

This function is a convenient way to convert a binary ODB value into a string depending on its type if is not known at compile time. If it is known, the normal sprintf() function can be used.

...
  for (j=0 ; j<key.num_values ; j++)
  {
    db_sprintf(pbuf, pdata, key.item_size, j, key.type);
    strcat(pbuf, "\n");
  }
  ...
Parameters:
string output ASCII string of data.
data Value data.
data_size Size of single data element.
index Index for array data.
type Type of key, one of TID_xxx (see Midas Data Types).
Returns:
DB_SUCCESS

Definition at line 6311 of file odb.c.

Referenced by db_copy(), and db_save_xml_key().

INT db_unlock_database HNDLE  hDB  ) 
 

Unlock a database via system mutex calls.

Parameters:
hDB Handle to the database to unlock
Returns:
DB_SUCCESS, DB_INVALID_HANDLE

Definition at line 1367 of file odb.c.

Referenced by cm_check_client(), cm_cleanup(), cm_delete_client_info(), cm_get_watchdog_info(), cm_set_client_info(), cm_set_watchdog_params(), db_close_database(), db_create_key(), db_create_record(), db_delete_key1(), db_enum_key(), db_find_key(), db_get_data(), db_get_data_index(), db_get_key(), db_get_key_info(), db_get_key_time(), db_get_record(), db_get_record_size(), db_get_value(), db_open_database(), db_set_data(), db_set_data_index(), db_set_record(), and db_set_value().

INT db_update_record INT  hDB,
INT  hKey,
int  socket
 

If called locally, update a record (hDB/hKey) and copy its new contents to the local copy of it.

If called from a server, send a network notification to the client.

Parameters:
hDB ODB handle obtained via cm_get_experiment_database().
hKey Handle for key where search starts, zero for root.
socket optional server socket
Returns:
DB_SUCCESS, DB_INVALID_HANDLE

Definition at line 7956 of file odb.c.

BOOL equal_ustring char *  str1,
char *  str2
 

Definition at line 1425 of file odb.c.

Referenced by bm_open_buffer(), cm_connect_client(), cm_connect_experiment1(), cm_exist(), cm_get_watchdog_info(), cm_list_experiments(), cm_set_client_info(), cm_shutdown(), db_check_record(), db_create_key(), db_find_key(), db_open_database(), db_paste(), db_paste_node(), logger_root(), and register_equipment().

char* extract_key char *  key_list,
char *  key_name
 

Definition at line 1413 of file odb.c.

Referenced by db_create_key(), and db_find_key().

void xml_encode char *  src,
int  size
 

Definition at line 5938 of file odb.c.


Midas DOC Version 1.9.5 ---- PSI Stefan Ritt ----
Contributions: Pierre-Andre Amaudruz - Sergio Ballestrero - Suzannah Daviel - Doxygen - Peter Green - Qing Gu - Greg Hackman - Gertjan Hofman - Paul Knowles - Rudi Meier - Glenn Moloney - Dave Morris - John M O'Donnell - Konstantin Olchanski - Renee Poutissou - Tamsen Schurman - Andreas Suter - Jan M.Wouters - Piotr Adam Zolnierczuk