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