dce_db_fetch_by_name(3dce)
Retrieves data from a string-indexed backing store
Synopsis
#include <dce/dce.h>
#include <dce/dbif.h>
void dce_db_fetch_by_name(
dce_db_handle_t handle,
char *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 null-terminated string that is the key to the item in the backing store.
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_by_name( ) routine retrieves data from the string-indexed backing store that is identified by the handle parameter, which was
obtained from dce_db_open( ). It is a specialized retrieval routine for 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.
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_by_name( ), 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_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_fetch_by_name( ) must do rpc_sm_allocate( ), but in the server side of an RPC, this is already done.
Examples
This example shows the use of the user-defined data type as the data parameter.
extern dce_db_handle_t db_h;
uuid_t key_uuid;
my_data_type_t my_data;
error_status_t status;
/* set key_uuid = xxx; */
dce_db_fetch_by_name(db_h, &key_uuid, &my_data, &status);
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_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 backing store is not indexed by name.
error_status_ok
The call was successful.
Related Information
Functions: dce_db_fetch(3dce)