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

   Output

   list
       Returns a list of data entries for the service.

   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
            dced_s_bad_binding
            dced_s_no_memory
            dced_s_no_support
            sec_acl_invalid_permission

 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
   file name 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 it
   guarantees 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() set of 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 );

 RELATED INFORMATION

   Routines:   dced_list_release
               dced_initialize_cursor
               dced_binding_create
               dced_binding_from_rpc_binding

   Books: OSF DCE Application Development Guide.