NAME

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

handle

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

Output

key

A pointer to the string or UUID that is the key to the item in the backing store.

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

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