NAME

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

handle

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

key

A UUID 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_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

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