NAME

   dced_binding_create - Establishes a dced binding to one of the
                         host services of a remote (or the local) dced.

 SYNOPSIS

   #include <dce/dced.h>

   void dced_binding_create( dced_string_t          service,
                             unsigned32             binding_flags,
                             dced_binding_handle_t  *dced_bh,
                             error_status_t         *status );

 PARAMETERS

   Input

   service
       A character string that specifies a host daemon service name
       and an optional remote host. A service name is specified with
       one of the following: hostdata, srvrconf, srvrexec, secval, or
       keytab.  The format of a complete service and host specification
       is one of the following:

       service_name
                 A service at the local host.  Pre-existing defined
                 values include:

                      dced_c_service_hostdata
                      dced_c_service_srvrconf
                      dced_c_service_srvrexec
                      dced_c_service_secval
                      dced_c_service_keytab

       service_name@hosts/host_name
                 A service at a host anywhere in the local namespace.

       /.:/hosts/host_name/config/service_name
                 A complete specification for service_name@host, where
                 the host is anywhere in the local namespace.

       /.../cell/hosts/host_name/config/service_name
                 A service at a host anywhere in the global namespace.

   binding_flags
       Currently, the only valid flag value is
       dced_c_binding_syntax_default.

   Output

   dced_bh
       Returns a dced binding handle which is a pointer to an opaque
       data structure containing information about an RPC binding, the
       host, the host service, and a local cache.

   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
            dce_cf_e_no_mem
            dced_s_invalid_arg
            dced_s_no_memory
            dced_s_unknown_service
            rpc_s_entry_not_found
            rpc_s_incomplete_name
            rpc_s_invalid_object
            rpc_s_name_service_unavailable
            rpc_s_no_memory
            rpc_s_no_more_bindings
            rpc_s_no_ns_permission

 DESCRIPTION

   The dced on each DCE host maintains the host services and provides
   a remote interface to them.  The host services include the
   following:

     +  Endpoint Mapper

     +  Host Data Management (hostdata)

     +  Server Management: Including Server Configuration (srvrconf)
        and Server Execution (srvrexec)

     +  Security Validation (secval)

     +  Key Table Management (keytab)

   The dced_binding_create() routine establishes a dced binding to a
   dced service and it (or dced_binding_from_rpc_binding()) must be the
   first dced API routine called before an application can access one
   of the host services with other dced API routines.  When an
   application is finished with the service, it should call the
   dced_binding_free() routine to free resources.  To establish a dced
   binding to your local host's dced, you can use the service name by
   itself, and do not need to specify a host.

   To access the endpoint map directly, use rpc_mgmt_ep_elt_inq_begin()
   and associated routines.

 EXAMPLES

   This example establishes a dced binding to the server configuration
   service on the host patrick.

        dced_binding_handle_t dced_bh;
        error_status_t        status;

        dced_binding_create("srvrconf@hosts/patrick",
                            dced_c_binding_syntax_default,
                            &dced_bh,
                            &status);
         .
         . /* Other routines including dced API routines. */
         .
        dced_binding_free(dced_bh, &status);

 RELATED INFORMATION

   Routines:   dced_binding_free
               dced_binding_from_rpc_binding

   Books: OSF DCE Application Development Guide.