VMS Help DCE, dce_intro, dced_intro, Generic Entry Routines, dced_entry_get_next  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 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

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

   Output

   entry
       Returns a pointer to an entry.

   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_no_more_entries

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

      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); /* app. specific */
      }
      dced_release_cursor( &cursor, &status );
      dced_binding_free( dced_bh, &status );

 RELATED INFORMATION

   Routines:   dced_initialize_cursor
               dced_release_cursor
               dced_binding_create
               dced_binding_from_rpc_binding

   Books: OSF DCE Application Development Guide.