NAME
dce_db_intro - Introduction to the DCE backing store interface
DESCRIPTION
The DCE backing store interface allows you to maintain typed data
between program invocations. For example, you might store application-
specific configuration data in a backing store, and then retrieve it
from the backing store when the application restarts. The backing
store routines can be used in servers, in clients or in standalone
programs that do not involve remote procedure calls (RPC). A program
can have more than one backing store open at the same time.
Sometimes the backing store is called a database. For instance, the
associated IDL file is dce/database.idl, and the name of the backing
store routines begin with dce_db_. The backing store is, however,
not a full-fledged database in the conventional sense, and it has no
support for SQL or for any other query system.
BACKING STORE DATA
The backing store interface provides for the tagged storage and
retrieval of typed data. The tag (or retrieval key) can be either
a UUID or a standard C string. For a specific backing store, the
data type must be specified at compile time, and is established
through the IDL Encoding Services. Each backing store can contain
only a single data type.
Each data item (also called a data object or data record) consists
of the data stored by a single call to a storage routine
(dce_db_store(), dce_db_store_by_name(), or dce_db_store_by_uuid()).
Optionally, data items can have headers. If a backing store has been
created to use headers, then every data item must have a header. For
a description of the data item header, see "Data Structures," below.
ENCODING AND DECODING IN THE BACKING STORE
When a Remote Procedure Call (RPC) sends data between a client and a
server, it serializes the user's data structures by using the IDL
Encoding Services (ES), described in the OSF DCE Application
Development Guide.
The backing store uses this same serialization scheme for encoding
and decoding, informally called "pickling," when storing data
structures to disk. The IDL compiler, idl, writes the routine that
encodes and decodes the data. This routine is passed to dce_db_open(),
remembered in the handle, and used by the store and fetch routines:
+ dce_db_fetch()
+ dce_db_fetch_by_name()
+ dce_db_fetch_by_uuid()
+ dce_db_header_fetch()
+ dce_db_store()
+ dce_db_store_by_name()
+ dce_db_store_by_uuid()
MEMORY ALLOCATION
When fetching data, the Encoding Services (ES) allocate memory for
the data structures that are returned. These services accept a
structure, and use rpc_sm_allocate() to provide additional memory
needed to hold the data.
The backing store library does not know what memory has been allocated,
and therefore cannot free it. For fetch calls that are made from a
server stub, this is not a problem, because the memory is freed
automatically when the server call terminates. For fetch calls that
are made from a non-server, the programmer is responsible for freeing
the memory.
Programs that call the fetch or store routines, such as dce_db_fetch(),
outside of a server operation (for instance, if a server does some
backing store initialization, or in a standalone program) must call
rpc_sm_enable_allocate() first.
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.
DATA TYPES AND STRUCTURES
dce_db_handle_t An opaque handle to a backing store. Use
dce_db_open() to acquire the handle.
dce_db_header_t The data structure that defines a standard
backing store header for data items. Use
dce_db_header_fetch() to retrieve it from a
backing store and dce_db_std_header_init() to
initialize it.
dce_db_convert_func_t
An opaque pointer to the data conversion
function to be used when storing or retrieving
data. This function is specified as an
argument to dce_db_open() at open time. It
converts between native format and on-disk
(serialized) format. It is generated from the
IDL file by the IDL compiler.
CAUTIONS
You can not use conformant arrays in objects stored to a backing
store. This is because the idl-generated code that encodes (pickles)
the structure has no way to predict or detect the size of the array.
When the object is fetched, there will likely be insufficient space
provided for the structure, and the array's data will destroy
whatever is in memory after the structure.
FILES
database.idl, database.h, db.h, and dbif.h
RELATED INFORMATION
BOOKS: OSF DCE Application Development Guide
1 – dce_db_close
NAME
dce_db_close - Closes an open backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_close( dce_db_handle_t *handle,
error_status_t *status );
PARAMETERS
Input
handle A handle identifying the backing store to be closed.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_close() routine closes a backing store that was opened
by dce_db_open(). It also frees the storage used by the handle,
and sets the handle's value to NULL.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_open
2 – dce_db_delete
NAME
dce_db_delete - Deletes an item from a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_delete( dce_db_handle_t handle,
void *key,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A pointer to a string or UUID that is the key to the
item in the backing store. The datatype of key must
match the key method that was selected in the flags
parameter to dce_db_open() when the backing store was
created.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error code.
DESCRIPTION
The dce_db_delete() routine deletes an item from the backing store
that is identified by the handle parameter, which was obtained from
dce_db_open(). It is a general deletion routine, interpreting the
key parameter according to the type of index with which the backing
store was created.
ERRORS
db_s_del_failed
The deletion did not occur. The global variable errno
may indicate further information about the error.
db_s_bad_index_type
The key's type is wrong, or the backing store is not by
name or by UUID.
db_s_iter_not_allowed
The function was called while an iteration, begun by
dce_db_iter_start(), was in progress. Deletion is not
allowed during iteration.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_delete_by_name
dce_db_delete_by_uuid
dce_db_open
3 – dce_db_delete_by_name
NAME
dce_db_delete_by_name - Deletes an item from a string-indexed
backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_delete_by_name( dce_db_handle_t handle,
char *key,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A NULL-terminated string that is the key to the item
in the backing store.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error code.
DESCRIPTION
The dce_db_delete_by_name() routine deletes an item from the
backing store that is identified by the handle parameter, which
was obtained from dce_db_open(). It is a specialized deletion
routine for backing stores that are indexed by name, as selected
by the db_c_index_by_name bit in the flags parameter to
dce_db_open() when the backing store was created.
ERRORS
db_s_del_failed
The deletion did not occur. The global variable errno
may indicate further information about the error.
db_s_bad_index_type
The backing store is not indexed by name.
db_s_iter_not_allowed
The function was called while an iteration, begun by
dce_db_iter_start(), was in progress. Deletion is not
allowed during iteration.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_delete
dce_db_delete_by_uuid
dce_db_open
4 – dce_db_delete_by_uuid
NAME
dce_db_delete_by_uuid - Deletes an item from a UUID-indexed
backing-store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_delete_by_uuid( dce_db_handle_t handle,
uuid_t *key,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing-store being used.
key A pointer to a UUID that is the key to the item in the
backing store.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error code.
DESCRIPTION
The dce_db_delete_by_uuid() routine deletes an item from the
backing-store that is identified by the handle parameter, which
was obtained from dce_db_open(). It is a specialized deletion
routine for backing stores that are indexed by UUID, as selected
by the db_c_index_by_uuid bit in the flags parameter to
dce_db_open() when the backing store was created.
ERRORS
db_s_del_failed
The deletion did not occur. The global variable errno
may indicate further information about the error.
db_s_bad_index_type
The backing-store is not indexed by UUID.
db_s_iter_not_allowed
The function was called while an iteration, begun by
dce_db_iter_start(), was in progress. Deletion is
not allowed during iteration.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_delete
dce_db_delete_by_name
dce_db_open
5 – dce_db_fetch
NAME
dce_db_fetch - Retrieves data from a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_fetch( dce_db_handle_t handle,
void *key,
void *data,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A string or UUID that is the key to the item in the
backing store. The datatype of key must match the key
method that was selected in the flags parameter to
dce_db_open() when the backing store was created.
Output
data A pointer to the returned data.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_fetch() routine retrieves data from the backing store
that is identified by the handle parameter, which was obtained
from dce_db_open(). It is a general retrieval routine,
interpreting the key parameter according to the type of index
with which the backing store was created.
The data parameter is shown as a pointer to an arbitrary data
type. In actual use it will be the address of the backing-store-
specific data type.
NOTES
After calling dce_db_fetch(), it may be necessary to free some
memory, if the call was made outside of an RPC, on the server
side. This is done by calling rpc_sm_client_free(). (Inside
an RPC the memory is allocated through rpc_sm_allocate(), and
is automatically freed.)
Programs that call dce_db_fetch() outside of a server operation
(for instance, if a server does some backing store initialization,
or in a standalone program) must call rpc_sm_enable_allocate()
first. Indeed, every thread that calls dce_db_fetch() must do
rpc_sm_allocate(), but in the server side of an RPC, this is
already done.
ERRORS
db_s_key_not_found
The specified key was not found in the backing store.
(This circumstance is not necessarily an error.)
db_s_bad_index_type
The key's type is wrong, or else the backing store is
not by name or by UUID.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch_by_name
dce_db_fetch_by_uuid
dce_db_free
dce_db_open
6 – dce_db_fetch_by_name
NAME
dce_db_fetch_by_name - Retrieves data from a string-indexed
backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_fetch_by_name( dce_db_handle_t handle,
char *key,
void *data,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A null-terminated string that is the key to the item
in the backing store.
Output
data A pointer to the returned data.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_fetch_by_name() routine retrieves data from the
string-indexed backing store that is identified by the handle
parameter, which was obtained from dce_db_open(). It is a
specialized retrieval routine for backing stores that are indexed
by string, as selected by the db_c_index_by_name bit in the flags
parameter to dce_db_open() when the backing store was created.
The data parameter is shown as a pointer to an arbitrary data type.
In actual use it will be the address of the backing-store-specific
data type.
NOTES
After calling dce_db_fetch_by_name(), it may be necessary to free
some memory, if the call was made outside of an RPC, on the server
side. This is done by calling rpc_sm_client_free(). (Inside an
RPC the memory is allocated through rpc_sm_allocate(), and is
automatically freed.)
Programs that call dce_db_fetch_by_name() outside of a server
operation (for instance, if a server does some backing store
initialization, or in a standalone program) must call
rpc_sm_enable_allocate() first. Indeed, every thread that calls
dce_db_fetch_by_name() must do rpc_sm_allocate(), but in the
server side of an RPC, this is already done.
EXAMPLES
This example shows the use of the user-defined data type as the
data parameter.
extern dce_db_handle_t db_h;
uuid_t key_uuid;
my_data_type_t my_data;
error_status_t status;
/* set key_uuid = xxx; */
dce_db_fetch_by_name(db_h, &key_uuid, &my_data, &status);
ERRORS
db_s_key_not_found
The specified key was not found in the backing store.
(This circumstance is not necessarily an error.)
db_s_bad_index_type
The backing store is not indexed by name.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch
dce_db_fetch_by_uuid
dce_db_free
dce_db_open
7 – dce_db_fetch_by_uuid
NAME
dce_db_fetch_by_uuid - Retrieves data from a UUID-indexed backing
store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_fetch_by_uuid( dce_db_handle_t handle,
uuid_t *key,
void *data,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A UUID that is the key to the item in the backing store.
Output
data A pointer to the returned data.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_fetch_by_uuid() routine retrieves data from the
UUID-indexed backing store that is identified by the handle
parameter, which was obtained from dce_db_open(). It is a
specialized retrieval routine for backing stores that are
indexed by UUID, as selected by the db_c_index_by_uuid bit in
the flags parameter to dce_db_open() when the backing store was
created.
The data parameter is shown as a pointer to an arbitrary data type.
In actual use it will be the address of the backing-store-specific
data type.
NOTES
After calling dce_db_fetch_by_uuid(), it may be necessary to free
some memory, if the call was made outside of an RPC, on the server
side. This is done by calling rpc_sm_client_free(). (Inside an
RPC the memory is allocated through rpc_sm_allocate(), and is
automatically freed.)
Programs that call dce_db_fetch_by_uuid() outside of a server
operation (for instance, if a server does some backing store
initialization, or in a standalone program) must call
rpc_sm_enable_allocate() first. Indeed, every thread that calls
dce_db_fetch_by_uuid() must do rpc_sm_allocate(), but in the
server side of an RPC, this is already done.
EXAMPLES
This example shows the use of the user-defined data type as the
data parameter.
extern dce_db_handle_t db_h;
uuid_t key_uuid;
my_data_type_t my_data;
error_status_t status;
/* set key_uuid = xxx; */
dce_db_fetch_by_uuid(db_h, &key_uuid, &my_data, &status);
ERRORS
db_s_key_not_found
The specified key was not found in the backing store.
(This circumstance is not necessarily an error.)
db_s_bad_index_type
The backing store is not indexed by UUID.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch
dce_db_fetch_by_name
dce_db_free
dce_db_open
8 – dce_db_free
NAME
dce_db_free - Releases the data supplied from a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_free( dce_db_handle_t handle,
void *data,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
data The data area to be released.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_free() routine is designed to free the data
area previously returned via a call to dce_db_fetch(),
dce_db_fetch_by_name(), or dce_db_fetch_by_uuid().
NOTES
In the current implementation, the dce_db_free() routine does not
perform any action. For servers that execute properly this is of
little consequence, because their allocated memory is automatically
cleaned up when a remote procedure call finishes. For completeness,
and for compatibility with future releases, the use of dce_db_free()
is recommended.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch
dce_db_fetch_by_name
dce_db_fetch_by_uuid
9 – dce_db_header_fetch
NAME
dce_db_header_fetch - Retrieves the header from a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_header_fetch( dce_db_handle_t handle,
void *key,
dce_db_header_t *hdr,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A string or UUID that is the backing store key.
Output
hdr A pointer to a caller-supplied header structure to be
filled in by the library.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_header_fetch() routine returns a pointer to a copy of the
header of the object in the backing store that is identified by the
handle parameter, which was obtained from dce_db_open(). The caller
must free the copy's storage. It was allocated (as with other fetch
routines) through rpc_ss_alloc(). The key parameter is interpreted
according to the type of index with which the backing store was
created.
The hdr parameter is shown as a pointer to an arbitrary data type.
In actual use it will be the address of the backing-store-specific
data type.
ERRORS
db_s_key_not_found
The key was not found in the backing store.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch
dce_db_std_header_init
10 – dce_db_inq_count
NAME
dce_db_inq_count - Returns the number of items in a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_inq_count( dce_db_handle_t handle,
unsigned32 *count,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
count A pointer to the number of items in the backing store.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_inq_count() routine returns the number of items in the
backing store that is identified by the handle parameter, which was
obtained from dce_db_open(). It performs identically on backing
stores that are indexed by UUID and those that are indexed by string.
The count of items can be helpful when iterating through a backing
store.
ERRORS
db_s_iter_not_allowed
The function was called while an iteration, begun by
dce_db_iter_start(), was in progress. Determining the
count is not allowed during iteration.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_iter_next
11 – dce_db_iter_done
NAME
dce_db_iter_done - Frees the state associated with iteration
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_iter_done( dce_db_handle_t handle,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
DESCRIPTION
The dce_db_iter_done() routine frees the state that permits
iteration. It should be called after an iteration through a
backing store is finished.
The iteration state is established by dce_db_iter_start().
The routines for performing iteration over the items are
dce_db_iter_next(), dce_db_iter_next_by_name(), and
dce_db_iter_next_by_uuid().
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_iter_next
dce_db_iter_next_by_name
dce_db_iter_next_by_uuid
dce_db_iter_start
12 – dce_db_iter_next
NAME
dce_db_iter_next - During iteration, returns the next key from
a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_iter_next( dce_db_handle_t handle,
void **key,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
key A pointer to the string or UUID that is the key to the
item in the backing store.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_iter_next() routine retrieves the next key from the
backing store that is identified by the handle parameter. An
iterator established by the dce_db_iter_start() routine maintains
the identity of the current key. Use one of the dce_db_fetch()
routines to retrieve the actual data.
The iteration functions scan sequentially through a backing store,
in no particular order. The dce_db_iter_start() routine initialized
the process, a dce_db_iter_next() routine retrieves successive keys,
for which the data can be retrieved with dce_db_fetch(), and the
dce_db_iter_done() routine finishes the process. The iteration can
also use the dce_db_iter_next_by_name() and dce_db_iter_next_by_uuid()
routines; the fetching can use the dce_db_fetch_by_name() and
dce_db_fetch_by_uuid() routines.
The iteration routine returns a pointer to a private space
associated with the handle. Each call to the iteration routine
reuses the space, instead of using allocated space.
ERRORS
db_s_no_more
All the keys in the backing store have been accessed;
there are no more iterations remaining to be done.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch
dce_db_fetch_by_name
dce_db_fetch_by_uuid
dce_db_iter_done
dce_db_iter_next_by_name
dce_db_iter_next_by_uuid
dce_db_iter_start
13 – dce_db_iter_next_by_name
NAME
dce_db_iter_next_by_name - During iteration, returns the next key
from a backing store indexed by string
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_iter_next_by_name( dce_db_handle_t handle,
char **key,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
key The string that is the key to the item in the backing store.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_iter_next_by_name() routine retrieves the next key
from the backing store that is identified by the handle parameter.
An iterator established by the dce_db_iter_start() routine maintains
the identity of the current key. Use the dce_db_fetch_by_name()
routine to retrieve the actual data.
This iteration routine is the same as dce_db_iter_next(), except
that it only works with backing stores indexed by name, and returns
an error if the backing store index is the wrong type.
The iteration routine returns a pointer to a private space
associated with the handle. Each call to the iteration routine
reuses the space, instead of using allocated space.
ERRORS
db_s_no_more
All the keys in the backing store have been accessed;
there are no more iterations remaining to be done.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch_by_uuid
dce_db_iter_done
dce_db_iter_next
dce_db_iter_next_by_uuid
dce_db_iter_start
14 – dce_db_iter_next_by_uuid
NAME
dce_db_iter_next_by_uuid - During iteration, returns the next key
from a backing store indexed by UUID
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_iter_next_by_uuid( dce_db_handle_t handle,
uuid_t **key,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
key The UUID that is the key to the item in the backing store.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_iter_next_by_uuid() routine retrieves the next key
from the backing store that is identified by the handle parameter.
An iterator established by the dce_db_iter_start() routine maintains
the identity of the current key. Use the dce_db_fetch_by_uuid()
routine to retrieve the actual data.
This iteration routine is the same as dce_db_iter_next(), except
that it only works with backing stores indexed by UUID, and returns
an error if the backing store index is the wrong type.
The iteration routine returns a pointer to a private space
associated with the handle. Each call to the iteration routine
reuses the space, instead of using allocated space.
ERRORS
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_iter_done
dce_db_iter_next
dce_db_iter_next_by_name
dce_db_iter_start
15 – dce_db_iter_start
NAME
dce_db_iter_start - Prepares a backing store for iteration
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_iter_start( dce_db_handle_t handle,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
DESCRIPTION
The dce_db_iter_start() routine prepares the backing store that is
identified by the handle parameter for iterative retrieval of all
its keys in succession.
A given handle can support only a single instance of iteration at
one time.
To avoid the possibility that another thread will write to the
backing store during an iteration, always use the dce_db_lock()
routine before calling dce_db_iter_start().
ERRORS
db_s_iter_not_allowed
The function was called while an iteration was already
in progress. The concept of nested iterations is not
supported.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_iter_done
dce_db_iter_next
dce_db_iter_next_by_name
dce_db_iter_next_by_uuid
dce_db_lock
dce_db_unlock
dce_db_open
16 – dce_db_lock
NAME
dce_db_lock - Applies an advisory lock on a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_lock( dce_db_handle_t handle,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_lock() routine acquires the lock associated with the
handle.
There is an advisory lock associated with each handle. The routines
for storing and deleting backing stores apply the lock before
updating a backing store. This routine provides a means to apply
the lock for other purposes, such as iteration.
Advisory locks allow cooperating threads to perform consistent
operations on backing stores, but do not guarantee consistency;
that is, threads may still access backing stores without using
advisory locks, possibly resulting in inconsistencies.
ERRORS
db_s_already_locked
An attempt was made to lock a backing store, but it
was already locked.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_delete
dce_db_delete_by_name
dce_db_delete_by_uuid
dce_db_store
dce_db_store_by_name
dce_db_store_by_uuid
dce_db_unlock
17 – dce_db_open
NAME
dce_db_open - Opens an existing backing store or creates a new one
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_open( const char *name,
const char *backend_type,
unsigned32 flags,
dce_db_convert_func_t convert,
dce_db_handle_t *handle,
error_status_t *status );
PARAMETERS
Input
name The filename of the backing store to be opened or created.
backend_type
Either of the strings, bsd4.4-hash or bsd4.4-btree, or
a null pointer, which defaults to hash. This parameter
specifies the backing store backend type for licensees
adding multiple backends.
flags The manner of opening, as specified by any of the
following bits:
db_c_index_by_name
The backing store is to be indexed by name.
Either this or db_c_index_by_uuid, but not
both, must be selected.
db_c_index_by_uuid
The backing store is to be indexed by UUID.
Either this or db_c_index_by_name, but not
both, must be selected.
db_c_std_header
The first field of each item (which is defined
as a union in dce_db_header_t) is the standard
backing store header, with the case
dce_db_header_std selected. The selection for
header cannot have both db_c_std_header and
db_c_acl_uuid_header. If neither header flag is
specified, no header is used.
db_c_acl_uuid_header
The first field of each item (the union) is an
ACL UUID, with the case dce_db_header_acl_uuid
selected. The selection for header cannot have
both db_c_std_header and db_c_acl_uuid_header.
If neither header flag is specified, no header
is used.
db_c_readonly
An existing backing store is to be opened in
read-only mode. Read/write is the default.
db_c_create
Creates an empty backing store if one of the
given name does not already exist. It is an
error to try to create an existing backing store.
convert The function, generated by the IDL compiler, that is
called to perform serialization.
Output
handle A pointer to a handle that identifies the backing
store being used.
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_open() routine opens the specified backing store. The
flags parameter must specify whether the backing store is to be
indexed by name or by UUID. If all of a server's objects have
entries in the CDS namespace, then it is probably best to use a
UUID index. If the server provides a junction or another name-based
lookup operation, then it is probably best to use a name index.
The IDL code in /usr/include/dce/database.idl defines the backing
store header (selected by the flags parameter) that is placed on
each item, the possible header types, and the form of the function
for serializing headers.
NOTES
Backing stores are also called databases. For instance, the
associated IDL header is dce/database.idl, and the name of the
backing store routines begin with dce_db_. Nevertheless, backing
stores are not databases in the conventional sense, and have no
support for SQL or for any other query system.
EXAMPLES
Standardized use of the backing store library is encouraged. The
following is the skeleton IDL interface for a server's backing store:
interface XXX_db
{
import "dce/database.idl";
typedef XXX_data_s_t {
dce_db_header_t header;
/* server-specific data */
} XXX_data_t;
void XXX_data_convert( [in] handle_t h,
[in, out] XXX_data_t *data,
[out] error_status_t *st );
}
This interface should be compiled with the following ACF:
interface XXX_db
{
[encode, decode] XXX_data_convert();
}
A typical call to dce_db_open(), using the preceding IDL example,
would be:
dce_db_open( "XXX_db", NULL,
db_c_std_header | db_c_index_by_uuid,
(dce_db_convert_func_t)XXX_data_convert,
&handle, &st );
ERRORS
db_s_bad_index_type
The index type in flags is specified neither by name nor
by UUID; or else it is specified as both.
db_s_bad_header_type
The header type in flags is specified as both standard
header and ACL header.
db_s_index_type_mismatch
An existing backing store was opened with the wrong index
type.
db_s_open_already_exists
The backing store file specified for creation already
exists.
db_s_no_name_specified
No filename is specified.
db_s_open_failed_eacces
The server does not have permission to open the backing
store file.
db_s_open_failed_enoent
The specified directory or backing store file was not found.
db_s_open_failed
The underlying database-open procedure failed. The global
variable errno may provide more specific information.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_close
18 – dce_db_std_header_init
NAME
dce_db_std_header_init - Initializes a standard backing store header
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_std_header_init( dce_db_handle_t handle,
dce_db_header_t *hdr,
uuid_t *uuid,
uuid_t *acl_uuid,
uuid_t *def_object_acl,
uuid_t *def_container_acl,
unsigned32 ref_count,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
hdr Pointer to the object header part of the users' structure.
uuid The UUID to be placed into the header. Can be NULL.
acl_uuid The UUID of the ACL protecting this object, to be placed
into the header. Can be NULL.
def_object_acl
The UUID of the default object ACL, to be placed into
the header. Can be NULL.
def_container_acl
The UUID of the default container ACL, to be placed into
the header. Can be NULL.
ref_count The reference count to be placed into the header.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_std_header_init() routine initializes the fields of the
standard header for a data object whose backing store is identified
by the handle parameter. The fields are only set in memory and
should be stored to the backing store by one of the store routines.
The handle was obtained from dce_db_open(), which must have been
called with the db_c_std_header flag.
ERRORS
db_s_bad_header_type
The header type is not dce_db_header_std.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_header_fetch
19 – dce_db_store
NAME
dce_db_store - Stores data into a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_store( dce_db_handle_t handle,
void *key,
void *data,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A string or UUID that is the backing store key. The
datatype of key must match the key method that was
selected in the flags parameter to dce_db_open() when
the backing store was created.
data A pointer to the data structure to be stored.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_store() routine stores the data structure pointed to by
data into the backing store. The conversion function that was
specified in the call to dce_db_open() serializes the structure so
that it can be written to disk.
If the key value is the same as a key already stored, the new data
replaces the previously stored data associated with that key.
NOTES
Because the dce_db_store() routine uses the encoding services,
and they in turn use rpc_sm_allocate(), all programs that call
dce_db_store() outside of a server operation (for instance, if a
server does some backing store initialization, or in a standalone
program) must call rpc_sm_enable_allocate() first. Indeed, every
thread that calls dce_db_store() must do rpc_sm_enable_allocate(),
but in the server side of an RPC, this is already done.
ERRORS
db_s_bad_index_type
The key's type is wrong, or else the backing store is not
by name or by UUID.
db_s_readonly
The backing store was opened with the db_c_readonly flag,
and cannot be written to.
db_s_store_failed
The data could not be stored into the backing store for
some reason. The global variable errno may contain more
information about the error.
db_s_iter_not_allowed
The function was called while an iteration, begun by
dce_db_iter_start(), was in progress. Storing is not
allowed during iteration.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_fetch
dce_db_open
dce_db_store_by_name
dce_db_store_by_uuid
20 – dce_db_store_by_name
NAME
dce_db_store_by_name - Stores data into a string-indexed backing
store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_store_by_name( dce_db_handle_t handle,
char *key,
void *data,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A null-terminated string that is the backing store key.
data A pointer to the data structure to be stored.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_store_by_name() routine stores the data structure pointed
to by data into the backing store. The conversion function that was
specified in the call to dce_db_open() serializes the structure so
that it can be written to disk.
This routine is specialized for storage into backing stores that
are indexed by string, as selected by the db_c_index_by_name bit
in the flags parameter to dce_db_open() when the backing store was
created.
If the key value is the same as a key already stored, the new data
replaces the previously stored data associated with that key.
NOTES
Because the dce_db_store_by_name() routine uses the encoding
services, and they in turn use rpc_sm_allocate(), all programs
that call dce_db_store_by_name() outside of a server operation
(for instance, if a server does some backing store initialization,
or in a standalone program) must call rpc_sm_enable_allocate()
first. Indeed, every thread that calls dce_db_store_by_name() must
do rpc_sm_enable_allocate(), but in the server side of an RPC, this
is already done.
ERRORS
db_s_bad_index_type
The backing store is not indexed by name.
db_s_readonly
The backing store was opened with the db_c_readonly flag,
and cannot be written to.
db_s_store_failed
The data could not be stored into the backing store for
some reason. The global variable errno may contain more
information about the error.
db_s_iter_not_allowed
The function was called while an iteration, begun by
dce_db_iter_start(), was in progress. Storing is not
allowed during iteration.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_open
dce_db_store
dce_db_store_by_uuid
21 – dce_db_store_by_uuid
NAME
dce_db_store_by_uuid - Stores data into a UUID-indexed backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_store_by_uuid( dce_db_handle_t handle,
uuid_t *key,
void *data,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
key A UUID that is the backing store key.
data A pointer to the data structure to be stored.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_store_by_uuid() routine stores the data structure pointed
to by data into the backing store. The conversion function that was
specified in the call to dce_db_open() serializes the structure so
that it can be written to disk.
This routine is specialized for storage into backing stores that are
indexed by UUID, as selected by the db_c_index_by_uuid bit in the
flags parameter to dce_db_open() when the backing store was created.
If the key value is the same as a key already stored, the new data
replaces the previously stored data associated with that key.
NOTES
Because the dce_db_store_by_uuid() routine uses the encoding services,
and they in turn use rpc_sm_allocate(), all programs that call
dce_db_store_by_uuid() outside of a server operation (for instance,
if a server does some backing store initialization, or in a standalone
program) must call rpc_sm_enable_allocate() first. Indeed, every
thread that calls dce_db_store_by_uuid() must do
rpc_sm_enable_allocate(), but in the server side of an RPC, this is
already done.
ERRORS
db_s_bad_index_type
The backing store is not indexed by UUID.
db_s_readonly
The backing store was opened with the db_c_readonly flag,
and cannot be written to.
db_s_store_failed
The data could not be stored into the backing store for
some reason. The global variable errno may contain more
information about the error.
db_s_iter_not_allowed
The function was called while an iteration, begun by
dce_db_iter_start(), was in progress. Storing is not
allowed during iteration.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_open
dce_db_store
dce_db_store_by_name
22 – dce_db_unlock
NAME
dce_db_unlock - Releases the backing store lock
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_unlock( dce_db_handle_t handle,
error_status_t *status );
PARAMETERS
Input
handle A handle, returned from dce_db_open(), that identifies
the backing store being used.
Output
status A pointer to the completion status. On successful
completion, the routine returns error_status_ok.
Otherwise, it returns an error.
DESCRIPTION
The dce_db_unlock() routine releases the lock associated with the
handle.
ERRORS
db_s_not_locked
An attempt was made to unlock a backing store, but it
was not locked.
error_status_ok
The call was successful.
RELATED INFORMATION
Functions: dce_db_lock