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


Functions

INT db_open_database (const char *xdatabase_name, INT database_size, HNDLE *hDB, const 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, const char *key_name, DWORD type)
INT db_create_link (HNDLE hDB, HNDLE hKey, const char *link_name, const 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, const char *key_name, HNDLE *subhKey)
INT db_set_value (HNDLE hDB, HNDLE hKeyRoot, const char *key_name, const void *data, INT data_size, INT num_values, DWORD type)
INT db_set_value_index (HNDLE hDB, HNDLE hKeyRoot, const char *key_name, const void *data, INT data_size, INT idx, DWORD type, BOOL trunc)
INT db_get_value (HNDLE hDB, HNDLE hKeyRoot, const char *key_name, void *data, INT *buf_size, DWORD type, BOOL create)
INT db_enum_key (HNDLE hDB, HNDLE hKey, INT idx, HNDLE *subkey_handle)
INT db_get_key (HNDLE hDB, HNDLE hKey, KEY *key)
INT db_get_link (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_link_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 idx, DWORD type)
INT db_set_data (HNDLE hDB, HNDLE hKey, const void *data, INT buf_size, INT num_values, DWORD type)
INT db_set_data_index (HNDLE hDB, HNDLE hKey, const void *data, INT data_size, INT idx, DWORD type)
INT db_load (HNDLE hDB, HNDLE hKeyRoot, const 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, const char *buffer)
INT db_paste_xml (HNDLE hDB, HNDLE hKeyRoot, const char *buffer)
INT db_copy_xml (HNDLE hDB, HNDLE hKey, char *buffer, INT *buffer_size)
INT db_save (HNDLE hDB, HNDLE hKey, const char *filename, BOOL bRemote)
INT db_save_xml (HNDLE hDB, HNDLE hKey, const char *filename)
INT db_save_struct (HNDLE hDB, HNDLE hKey, const char *file_name, const char *struct_name, BOOL append)
INT db_sprintf (char *string, const void *data, INT data_size, INT idx, 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, const char *orig_key_name, const char *init_str)
INT db_check_record (HNDLE hDB, HNDLE hKey, const char *keyname, const 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 s)
INT db_send_changed_records ()


Function Documentation

INT db_check_record ( HNDLE  hDB,
HNDLE  hKey,
const char *  keyname,
const 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 7904 of file odb.c.

Referenced by al_check(), 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 8393 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 1128 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 8356 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:

Definition at line 5413 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 6135 of file odb.c.

INT db_create_key ( HNDLE  hDB,
HNDLE  hKey,
const 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 1552 of file odb.c.

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

INT db_create_link ( HNDLE  hDB,
HNDLE  hKey,
const char *  link_name,
const 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 1792 of file odb.c.

INT db_create_record ( HNDLE  hDB,
HNDLE  hKey,
const char *  orig_key_name,
const 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 7734 of file odb.c.

Referenced by al_check(), al_trigger_alarm(), analyzer_init(), cm_set_client_info(), db_check_record(), main(), 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 1992 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 1822 of file odb.c.

Referenced by cm_delete_client_info(), and db_delete_key().

INT db_enum_key ( HNDLE  hDB,
HNDLE  hKey,
INT  idx,
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.
idx 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 3311 of file odb.c.

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

INT db_find_key ( HNDLE  hDB,
HNDLE  hKey,
const 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 2025 of file odb.c.

Referenced by al_check(), al_reset_alarm(), 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_data(), db_get_key(), db_get_value(), db_paste(), db_paste_xml(), db_set_data(), db_set_data_index(), db_set_value(), db_set_value_index(), load_fragment(), logger_root(), main(), 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 4167 of file odb.c.

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

INT db_get_data_index ( HNDLE  hDB,
HNDLE  hKey,
void *  data,
INT buf_size,
INT  idx,
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.
idx 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 4515 of file odb.c.

Referenced by cm_transition(), and db_get_data().

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 3650 of file odb.c.

Referenced by al_check(), al_reset_alarm(), cm_check_client(), cm_register_transition(), cm_shutdown(), cm_transition(), db_check_record(), db_get_data(), db_get_record(), db_get_record_size(), db_open_record(), db_paste(), db_save_struct(), 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 3853 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 3795 of file odb.c.

INT db_get_link ( HNDLE  hDB,
HNDLE  hKey,
KEY key 
)

Same as db_get_key, but it does not follow a link to an array index

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 3731 of file odb.c.

Referenced by db_copy(), and db_save_xml_key().

INT db_get_link_data ( HNDLE  hDB,
HNDLE  hKey,
void *  data,
INT buf_size,
DWORD  type 
)

Same as db_get_data, but do not follow a link to an array index

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 4289 of file odb.c.

Referenced by db_copy(), and db_save_xml_key().

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 7223 of file odb.c.

Referenced by al_check(), al_reset_alarm(), 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 7137 of file odb.c.

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

INT db_get_value ( HNDLE  hDB,
HNDLE  hKeyRoot,
const 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 3152 of file odb.c.

Referenced by al_check(), al_trigger_alarm(), ana_end_of_run(), bm_open_buffer(), 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(), main(), register_equipment(), and tr_start().

INT db_load ( HNDLE  hDB,
HNDLE  hKeyRoot,
const 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 5328 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 1408 of file odb.c.

Referenced by cm_check_client(), 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_link(), db_get_link_data(), 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 ( const char *  xdatabase_name,
INT  database_size,
HNDLE *  hDB,
const 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 815 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.

Definition at line 8222 of file odb.c.

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

INT db_paste ( HNDLE  hDB,
HNDLE  hKeyRoot,
const 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 5680 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 5959 of file odb.c.

Referenced by db_paste_xml().

INT db_paste_xml ( HNDLE  hDB,
HNDLE  hKeyRoot,
const 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 6096 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 1491 of file odb.c.

INT db_save ( HNDLE  hDB,
HNDLE  hKey,
const 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 6312 of file odb.c.

INT db_save_struct ( HNDLE  hDB,
HNDLE  hKey,
const char *  file_name,
const 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 6567 of file odb.c.

INT db_save_xml ( HNDLE  hDB,
HNDLE  hKey,
const 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 6514 of file odb.c.

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

Definition at line 6411 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.

//-------- 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 8636 of file odb.c.

Referenced by scan_fragment().

INT db_set_data ( HNDLE  hDB,
HNDLE  hKey,
const 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 4642 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,
const void *  data,
INT  data_size,
INT  idx,
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 
idx 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 4891 of file odb.c.

Referenced by cm_register_transition(), db_paste_node(), db_set_data(), and db_set_value_index().

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 7327 of file odb.c.

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

INT db_set_value ( HNDLE  hDB,
HNDLE  hKeyRoot,
const char *  key_name,
const 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 2978 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_set_value_index ( HNDLE  hDB,
HNDLE  hKeyRoot,
const char *  key_name,
const void *  data,
INT  data_size,
INT  idx,
DWORD  type,
BOOL  trunc 
)

Set single value of an array.

The function sets a single value of an ODB key which is an array. 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_index(hDB, 0, "/Equipment/Trigger/Settings/Level1",
                          &level1, sizeof(level1), 15, TID_INT, FALSE);
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).
index Array index of value.
type Type of key, one of TID_xxx (see Midas Data Types)
truncate Truncate array to current index if TRUE
Returns:
<same as db_set_data_index>

Definition at line 3107 of file odb.c.

INT db_sprintf ( char *  string,
const void *  data,
INT  data_size,
INT  idx,
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.
idx Index for array data.
type Type of key, one of TID_xxx (see Midas Data Types).
Returns:
DB_SUCCESS

Definition at line 6741 of file odb.c.

Referenced by db_copy(), db_save_xml_key(), and hs_dump().

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 1462 of file odb.c.

Referenced by cm_check_client(), 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_link(), db_get_link_data(), 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  s 
)

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.
s optional server socket
Returns:
DB_SUCCESS, DB_INVALID_HANDLE

Definition at line 8428 of file odb.c.

BOOL equal_ustring ( char *  str1,
char *  str2 
)

Definition at line 1522 of file odb.c.

Referenced by al_check(), 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().

const char* extract_key ( const char *  key_list,
char *  key_name,
int  key_name_length 
)

Definition at line 1508 of file odb.c.

Referenced by db_create_key(), and db_find_key().

void xml_encode ( char *  src,
int  size 
)

Definition at line 6368 of file odb.c.


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