dced_initialize_cursor(3dce)
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.
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 scaleable 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.
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.
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
Related Information
Routines: dced_entry_get_next(3dce)
dced_binding_from_rpc_binding(3dce)
Book: OSF DCE Application Development Guide - Core Components