Name

dce_db_store_by_name - Stores data into a string-indexed backing store

Synopsis

#include <dce/dce.h>
#include <dce/dbif.h> void dce_db_store_by_name(
    dce_db_handle_t handle,
    char ∗key,
    void ∗data,
    error_status_t ∗status);

Parameters

Input

handleA handle, returned from dce_db_open(), that identifies the backing store being used. 

keyA null-terminated string that is the backing store key. 

dataA pointer to the data structure to be stored. 

Output

statusA pointer to the completion status.  On successful completion, the routine returns error_status_ok.  Otherwise, it returns an error. 

Description

The dce_db_store_by_name() 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. 

This routine is specialized for storage into backing stores that are indexed by string, as selected by the db_c_index_by_name bit in the flags parameter to dce_db_open() when the backing store was created. 

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_by_name() routine uses the encoding services, and they in turn use rpc_sm_allocate(), all programs that call dce_db_store_by_name() 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_by_name() must do rpc_sm_enable_allocate(), but in the server side of an RPC, this is already done. 

Errors

The following describes a partial list of errors that might be returned.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

db_s_bad_index_type
The backing store is not indexed by name.

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_open(3dce), dce_db_store(3dce), dce_db_store_by_uuid(3dce).