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