Name

dce_db_iter_next - During iteration, returns the next key from a backing store

Synopsis

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

Parameters

Input

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

Output

keyA pointer to the string or UUID 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() 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 one of the dce_db_fetch() routines to retrieve the actual data. 

The iteration functions scan sequentially through a backing store, in no particular order.  The dce_db_iter_start() routine initialized the process, a dce_db_iter_next() routine retrieves successive keys, for which the data can be retrieved with dce_db_fetch(), and the dce_db_iter_done() routine finishes the process.  The iteration can also use the dce_db_iter_next_by_name() and dce_db_iter_next_by_uuid() routines; the fetching can use the dce_db_fetch_by_name() and dce_db_fetch_by_uuid() routines. 

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(3dce), dce_db_fetch_by_name(3dce), dce_db_fetch_by_uuid(3dce), dce_db_iter_done(3dce), dce_db_iter_next_by_name(3dce), dce_db_iter_next_by_uuid(3dce), dce_db_iter_start(3dce).