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

   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
              dce_db_fetch_by_name
              dce_db_fetch_by_uuid
              dce_db_iter_done
              dce_db_iter_next_by_name
              dce_db_iter_next_by_uuid
              dce_db_iter_start