Name

dce_db_iter_next_by_name - During iteration, returns the next key from a backing store indexed by string

Synopsis

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

Parameters

Input

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

Output

keyThe string that is the key to the item in the backing store. 

statusA pointer to the completion status.  On successful completion, the routine returns error_status_ok.  Otherwise, it returns an error. 

Description

The dce_db_iter_next_by_name() routine retrieves the next key from the backing store that is identified by the handle parameter.  An iterator established by the dce_db_iter_start() routine maintains the identity of the current key.  Use the dce_db_fetch_by_name() routine to retrieve the actual data. 

This iteration routine is the same as dce_db_iter_next(), except that it only works with backing stores indexed by name, and returns an error if the backing store index is the wrong type. 

The iteration routine returns a pointer to a private space associated with the handle.  Each call to the iteration routine reuses the space, instead of using allocated space. 

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_no_more
All the keys in the backing store have been accessed; there are no more iterations remaining to be done.

error_status_ok
The call was successful.

Related Information

Functions: dce_db_fetch_by_uuid(3dce), dce_db_iter_done(3dce), dce_db_iter_next(3dce), dce_db_iter_next_by_uuid(3dce), dce_db_iter_start(3dce).