NAME
   dce_db_fetch_by_name - 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

   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
              dce_db_fetch_by_uuid
              dce_db_free
              dce_db_open