/sys$common/syshlp/helplib.hlb DCE_RPC, Application Routines, rpc_binding_reset  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 NAME

   rpc_binding_reset - Resets a server binding handle

   Used by client or management applications.

 SYNOPSIS

   #include <dce/rpc.h>

   void rpc_binding_reset( rpc_binding_handle_t binding,
                           unsigned32 *status );

 PARAMETERS

   Input

   binding
       Specifies the server binding handle to reset.

   Output

   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 and their meanings
       are as follows:

       rpc_s_ok      Success.

       rpc_s_invalid_binding
                     Invalid binding handle.

       rpc_s_wrong_kind_of_binding
                     Wrong kind of binding for operation.

 DESCRIPTION

   The rpc_binding_reset() routine disassociates a server instance from
   the server binding handle specified in the binding parameter.  This
   routine removes the endpoint portion of the server address in the
   binding handle as well as any other server instance information in the
   binding handle.  The host portion of the server address remains
   unchanged.  The result is a partially bound server binding handle.
   This binding handle can rebind to another server instance on the
   previous host when it is later used to make a remote procedure call.
   The rpc_intro reference page contains an explanation of partially and
   fully bound binding handles.

   This routine does not affect any authentication information for the
   binding parameter.

   Suppose that a client can be serviced by any compatible server instance
   on the host specified in the binding handle.  Then, the client can call
   the rpc_binding_reset() routine before making a remote procedure call
   using the binding handle specified in binding.

   When the client makes the next remote procedure call using the reset
   server binding handle in binding, the client's RPC runtime uses a
   well-known endpoint from the client's interface specification, if any.
   Otherwise, the client's RPC runtime automatically communicates with
   the DCE Host Daemon (dced) on the specified remote host, to obtain the
   endpoint of a compatible server from the local endpoint map.  If a
   compatible server is located, the RPC runtime updates binding with a
   new endpoint.

   However, if a compatible server is not located, the client's remote
   procedure call fails.  If the failed call uses a connection protocol
   (ncacn), it receives the rpc_s_endpoint_not_found status code.  If
   the failed call uses a datagram protocol (ncadg), it receives the
   rpc_s_comm_failure status code.

   If a server application wants to be available to clients making a
   remote procedure call on a reset binding handle, it registers all
   binding handles by calling rpc_ep_register() or
   rpc_ep_register_no_replace().  If, however, the IDL-generated file
   contains endpoint address information, then the application does not
   have to call either of these two routines.

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: rpc_ep_register
              rpc_ep_register_no_replace