DCE, dce_intro, dce_db_intro
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help DCE, dce_intro, dce_db_intro *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
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
Additional Information (explode) :
|
|
