NAME

   dced_initialize_cursor - Sets a cursor to the start of a cached
                            list of data entries for a dced service

 SYNOPSIS

   #include <dce/dced.h>

   void dced_initialize_cursor( dced_binding_handle_t  dced_bh,
                                dced_cursor_t          *cursor,
                                error_status_t         *status );

 PARAMETERS

   Input

   dced_bh
       Specifies the dced binding handle for a dced service on a
       specific host.

   Output

   cursor
       Returns the cursor used to traverse the list of data entries,
       one at a time.  The cursor is an opaque data structure that is
       used to keep track of the entries between invocations of the
       dced_entry_get_next() routine.

   status
       Returns the status code from this routine.  This status code
       indicates whether the routine completed successfully or, if not,
       why not.  The possible status codes are:

            error_status_ok
            db_s_bad_index_type
            db_s_iter_not_allowed
            db_s_key_not_found
            dced_s_bad_binding
            dced_s_no_memory
            dced_s_no_support
            sec_acl_invalid_permission

 DESCRIPTION

   The dced_initialize_cursor() routine sets a cursor at the start of
   a DCE host service's list of data entries. The cursor is then used
   in subsequent calls to dced_entry_get_next() to obtain individual
   data entries.  When the application is finished traversing the
   entry list, it should call dced_release_cursor() to free the
   resources allocated for the cursor.

   The valid services for this routine that have entry lists include
   hostdata, srvrconf, srvrexec, and keytab.

   If a service's entry list is small, it may be more efficient to
   obtain the entire list using the dced_list_get() routine rather
   than using cursor routines.  This is because dced_list_get()
   guarantees the list is obtained with one remote procedure call.
   However, your application is scalable if you use the cursor
   routines because if an entry list is very large, it may be more
   efficient (or even necessary) to obtain the list in chunks with
   more than one remote procedure call.

   Prior to calling the dced_initialize_cursor() routine, the
   application must have established a valid dced binding handle
   by calling either the dced_binding_create() or
   dced_binding_from_rpc_binding() routine.

 RELATED INFORMATION

   Routines:   dced_entry_get_next
               dced_release_cursor
               dced_list_get
               dced_binding_create
               dced_binding_from_rpc_binding

   Books: OSF DCE Application Development Guide.