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_bhSpecifies the dced binding handle for a dced service on a specific host. 

Output

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

statusReturns 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 that the list is obtained with one remote procedure call.  However, your application is scalable if you use the cursor routines.  This is because when 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

Functions: dced_binding_create(3dce), dced_binding_from_rpc_binding(3dce), dced_entry_get_next(3dce), dced_list_get(3dce), dced_release_cursor(3dce). 

Books: OSF DCE Application Development Guide.