Name

dced_list_get - Returns the list of data entries maintained by a dced service on a specific host

Synopsis

#include <dce/dced.h> void dced_list_get(
dced_binding_handle_t dced_bh,
dced_entry_list_t ∗list,
error_status_t ∗status);

Parameters

Input

dced_bhSpecifies the dced binding handle for a dced service on a specific host. 

Output

listReturns a list of data entries for the service. 

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

Description

The dced_list_get() routine obtains all the data entries for a dced service on a specific host.  The list of data entries obtained is not the actual data.  Each entry contains a UUID, name, description, and storage tag that describes where the data is located (for example, a filename or memory location).  Call the dced_list_release() routine when your application is finished with the entry list to release resources allocated with dced_list_get() routine. 

If a service’s entry list is small, it may be efficient to obtain the entire list using the dced_list_get() routine, because this guarantees that the list is obtained with one remote procedure call.  However, to make your application scalable, use the dced_initialize_cursor(), dced_entry_get_next(), and dced_release_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 this 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.  The list of entries for the service is obtained with the dced_list_get() routine and each entry’s name and description are displayed. 

dced_binding_from_rpc_binding(service_type, rpc_bh, &dced_bh, &status);
dced_list_get(dced_bh, &entries, &status);
for(i=0; i<entries.count; i++)
    display(&entries);  /∗ application specific ∗/
dced_list_release(dced_bh, &entries, &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_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_initialize_cursor(3dce), dced_list_release(3dce). 

Books: OSF DCE Application Development Guide.