The Backing Store Routines
Many of the backing store routines appear in three versions: plain, by name, and by UUID. The plain version will work with backing stores that were created to be indexed either by name, or by UUID, while the restricted versions accept only the matching type. It is advantageous to use the restricted versions when they are appropriate, because they provide type checking by the compiler, as well as visual clarity of purpose.
The backing store routines are as follows, listed in alphabetical order:
dce_db_close( )
Frees the handle returned by dce_db_open( ). It closes any open files and releases all other resources associated with the backing store.
dce_db_delete( )
Deletes an item from a backing store that is indexed by name or by UUID. The key's type must match the flag that was used in dce_db_open( ).
dce_db_delete_by_name( )
Deletes an item only from a backing store that is indexed by name.
dce_db_delete_by_uuid( )
Deletes an item only from a backing store that is indexed by UUID.
dce_db_fetch( )
Retrieves data from a backing store that is indexed by name or by UUID. The key's type must match the flag that was used in dce_db_open( ).
dce_db_fetch_by_name( )
Retrieves data only from a backing store that is indexed by name.
dce_db_fetch_by_uuid( )
Retrieves data only from a backing store that is indexed by UUID.
dce_db_free( )
Releases the data supplied from a backing store.
dce_db_header_fetch( )
Retrieves a header from a backing store.
dce_db_inq_count( )
Returns the number of items in a backing store.
dce_db_iter_done( )
Terminates and iteration operation initiated by dce_db_iter_start( ). It should be called when iteration is done.
dce_db_iter_next( )
Returns the key for the next item from a backing store that is indexed by name or by UUID. The db_s_no_more return value indicates that there are
no more items.
dce_db_iter_next_by_name( )
Returns the key for the next item only from a backing store that is indexed by name. The db_s_no_more return value indicates that there are
no more items.
dce_db_iter_next_by_uuid( )
Returns the key for the next item only from a backing store that is indexed by UUID. The db_s_no_more return value indicates that there are
no more items.
dce_db_iter_start( )
Prepares for the start of iteration.
dce_db_lock( )
Locks a backing store. A lock is associated with an open backing store's handle. The storage routines, dce_db_store( ), dce_db_store_by_name(
), and dce_db_store_by_uuid( ), all acquire the lock before updating.
dce_db_open( )
Creates a new backing store or opens an existing one. The backing store is identified by a filename. Flags allow you to:
· Create a new backing store, or open an existing one.
· Create a new backing store indexed by name, or indexed by UUID.
· Open an existing backing store read/write, or read-only.
· Use the standard data item header, or not.
The routine returns a handle by which subsequent routines can reference the opened backing store.
dce_db_std_header_init( )
Initializes a standard backing store header retrieved by dce_db_header_fetch( ). It only places the values into the header, and does not
write into the backing store.
dce_db_store( )
Stores a data item into a backing store that is indexed by name or by UUID. The key's type must match the flag that was used in dce_db_open( ).
dce_db_store_by_name( )
Stores a data item only into a backing store that is indexed by name.
dce_db_store_by_uuid( )
Stores a data item only into a backing store that is indexed by UUID.
dce_db_unlock( )
Unlocks a backing store.