PreviousNext

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)

dce_db_fetch_by_uuid(3dce)

dce_db_free(3dce)

dce_db_open(3dce)