Name

dce_db_fetch_by_uuid - Retrieves data from a UUID-indexed backing store

Synopsis

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

Parameters

Input

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

keyA UUID that is the key to the item in the backing store. 

Output

dataA pointer to the returned data. 

statusA 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_uuid() routine retrieves data from the UUID-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 UUID, as selected by the db_c_index_by_uuid 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_uuid(), 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_uuid() 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_uuid() 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_uuid(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 UUID.

error_status_ok
The call was successful.

Related Information

Functions: dce_db_fetch(3dce), dce_db_fetch_by_name(3dce), dce_db_free(3dce), dce_db_open(3dce).