NAME

   dced_object_read - Reads a data item of a dced service on a
                      specific host

 SYNOPSIS

   #include <dce/dced.h>

   void dced_object_read( dced_binding_handle_t  dced_bh,
                          uuid_t                 *entry_uuid,
                          void                   **data,
                          error_status_t         *status );

 PARAMETERS

   Input

   dced_bh
       Specifies the dced binding handle for a dced service on a
       specific host.

   entry_uuid
       Specifies the UUID of the dced service's data entry associated
       with the data item.

   Output

   data
       Returns the data read.  The data returned is one of the
       following structures, depending on the service:

                    Service    Data Type Returned
                    _____________________________
                    hostdata   sec_attr_t
                    srvrconf   server_t
                    srvrexec   server_t
                    keytab     dced_key_list_t

   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
            db_s_bad_index_type
            db_s_key_not_found
            dce_cf_e_file_open
            dce_cf_e_no_match
            dce_cf_e_no_mem
            dced_s_bad_binding
            dced_s_need_privacy
            dced_s_no_memory
            dced_s_no_support
            dced_s_not_found
            rpc_s_binding_has_no_auth
            rpc_s_invalid_binding
            rpc_s_wrong_kind_of_binding
            sec_acl_invalid_permission
            sec_key_mgmt_e_authn_invalid
            sec_key_mgmt_e_key_unavailable
            sec_key_mgmt_e_unauthorized
            uuid_s_bad_version

 DESCRIPTION

   The dced_object_read() routine reads the data for a specified entry
   of a dced service. When the application is done with the data, it
   should call the dced_objects_release() routine with a value of 1
   for the count parameter.

   The valid services for which you can read data include hostdata,
   srvrconf, srvrexec, and keytab.  These host services each have a
   list of data entries maintained by dced.  The entries do not contain
   the actual data but contain the data's identity and an indicator of
   the location of the data item.  The hostdata service also has the
   dced_hostdata_read() routine to read data, and the keytab service
   has a series of routines that traverse over the keys in a key table.
   (See the dced_keytab_initialize_cursor() routine.)  The secval and
   endpoint services do not have data items to read with this routine.

   Applications can also read the data for all entries of a service
   using one call to dced_objects_read_all().

   Prior to reading the actual data, an application commonly obtains
   the entries to read using the series of cursor routines that begin
   with dced_entry_initialize_cursor().

   Prior to calling the dced_object_read() 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

   The following example creates a dced binding to a dced service based
   on a service type and host in an rpc binding handle.  The example
   then obtains the service's entry list and reads the data associated
   with each entry.

        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++) {
           dced_object_read( dced_bh,
                             &entries.list[i].id,
                             &data,
                             &status );
           .
           .
           .
           dced_objects_release( dced_bh, 1, data, &status );
        }
         .
         .
         .

 RELATED INFORMATION

   Routines:   dced_objects_release
               dced_objects_read_all
               dced_hostdata_read
               dced_keytab_initialize_cursor
               dced_initialize_cursor
               dced_binding_create
               dced_binding_from_rpc_binding

   Books: OSF DCE Application Development Guide.