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