| ## 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) ##