Name

dced_entry_get_next - Obtains one data entry from a list of entries of a dced service

Synopsis

#include <dce/dced.h> void dced_entry_get_next(
dced_cursor_t cursor,
dced_entry_t ∗∗entry,
error_status_t ∗status);

Parameters

Input/Output

cursorSpecifies the entry list’s cursor that points to an entry, and returns the cursor advanced to the next entry in the list. 

Output

entryReturns a pointer to an entry. 

statusReturns the status code from this routine.  This status code indicates whether the routine completed successfully or, if not, why not. 

Description

The dced_entry_get_next() routine obtains a pointer to a data entry, and advances the cursor to the next entry in the list.  This routine is commonly used in a loop to traverse a host service’s entry list.  The data is obtained in an undetermined order.  Prior to using this routine, the application must call dced_initialize_cursor() to obtain a list of entries and to establish the beginning of the cursor.  When the application is finished traversing the entry list, it should call dced_release_cursor() to release resources. 

A data entry does not contain the actual data, but it contains the name, identity, description,  and storage location of the data.  In the cases of hostdata and keytab services, the data for each entry is stored in a file.  In the cases of  srvrconf and srvrexec services, data is stored in memory.  The dced uses this two-level scheme so that it can manipulate different kinds of data in the same way. 

Prior to using the dced_entry_get_next() 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. 

Examples

In the following example, a dced binding is obtained from a service type and an existing rpc binding handle.  After establishing an entry list cursor, the dced_entry_get_next() routine obtains an entry, one at a time, and the name and description of each entry is displayed until the entry list is exausted. 

dced_binding_from_rpc_binding(service_type, rpc_bh, &dced_bh, &status);
dced_initialize_cursor(dced_bh, &cursor, &status);
for( ; ; ) { /∗ forever loop ∗/
   dced_entry_get_next(cursor, &entry, &status);
   if(status != error_status_ok) break;
   display(entry->name, entry->description); /∗ application specific ∗/
}
dced_release_cursor(&cursor, &status);
dced_binding_free( dced_bh, &status);

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

dced_s_no_more_entries

Related Information

Functions: dced_binding_create(3dce), dced_binding_from_rpc_binding(3dce), dced_initialize_cursor(3dce), dced_release_cursor(3dce). 

Books: OSF DCE Application Development Guide.