4.1.2 DB Framework API V0,5

void open(char *name,
          opal_list_t *properties,
          orcm_db_callback_fn_t cbfunc,
          void *cbdata);

Synopsis:

Open a database for access (read, write, etc.). The request can contain a user-specified name for this database that has nothing to do with the backend database (it is solely for use as a debug tool to help identify the database. The request can also optionally provide a list of properties (as an opal_list_t). This is where one might specify the name of the backend database, a URI for contacting it, the name of a particular table for request, etc. Thus, it is important to note that the returned "handle" is associated solely with the defined request (i.e. if the properties specify a database and table, then the handle will be specific to that combination).

NOTE: one special property allows you to specify the name(s) of the component(s) you want considered for this handle (i.e. the equivalent of specifying the MCA parameter "db=list") by using the reserved property name "components". The components will be queried in the order specified. The "^" character is also supported, with the remaining components considered in priority order.

Just like the standard POSIX file open, the call will return a unique handle that must be provided with any subsequent call to store or fetch data.

void close(int dbhandle,
           orcm_db_callback_fn_t cbfunc,
           void *cbdata);

Synopsis:

Close the specified database handle. This may or may not invoke termination of a connection to a remote database or release of memory storage, depending on the precise implementation of the active database components. A -1 handle indicates that ALL open database handles are to be closed.

void store(int dbhandle,
           const char *primary_key,
           opal_list_t *kvs,
           orcm_db_callback_fn_t cbfunc,
           void *cbdata);

Synopsis:

Store one or more data elements against a primary key. The values are passed as a key-value list in the kvs parameter. The semantics of the primary key and list of values will depend on the data that needs to be stored.

At the moment the API store function is designed to handle storing data collected by the sensor framework components. In this case, the primary key is a name for the group of data being passed (to classify the data and avoid naming conflicts with other data items collected by other sensors) and the list of values shall contain: the time stamp, the hostname and the values. For the values, sensors may optionally provide the data units in the key field using the following format: :. Note that this means the colon (":") is a reserved character.

void commit(int dbhandle,
            orcm_db_callback_fn_t cbfunc,
            void *cbdata);

Synopsis:

Commit data to the database. The action depends on the implementation within each active component.

void fetch(int dbhandle,
           const char *primary_key,
           const char *key,
           opal_list_t *kvs,
           orcm_db_callback_fn_t cbfunc,
           void *cbdata);

Synopsis:

Retrieve data for the given primary key associated with the specified key. Wildcards are supported here as well. The caller is responsible for releasing the returned list of opal_value_t objects.

void remove(int dbhandle,
            const char *primary_key,
            const char *key,
            orcm_db_callback_fn_t cbfunc,
            void *cbdata);

Synopsis:

Delete the data for the given primary key that is associated with the specified key. If a NULL key is provided, all data for the given primary key will be deleted.