NAME

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() 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