VMS Help DCE_RPC, Application Routines, rpc_ns_binding_lookup_begin  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 NAME

   rpc_ns_binding_lookup_begin - Creates a lookup context for an
                                 interface and an object in the name
                                 service database

   Used by client applications.

 SYNOPSIS

   #include <dce/rpc.h>

   void rpc_ns_binding_lookup_begin( unsigned32 entry_name_syntax,
                                     unsigned_char_t *entry_name,
                                     rpc_if_handle_t if_handle,
                                     uuid_t *object_uuid,
                                     unsigned32 binding_max_count,
                                     rpc_ns_handle_t *lookup_context,
                                     unsigned32 *status );

 PARAMETERS

   Input

   entry_name_syntax
       An integer value that specifies the syntax of the entry_name
       parameter.  To use the syntax specified in the
       RPC_DEFAULT_ENTRY_SYNTAX logical name, provide the value
       rpc_c_ns_syntax_default.

   entry_name
       Specifies the entry name at which the search for compatible binding
       handles begins.  This can be either the global or cell-relative
       name.  To use the entry name found in the RPC_DEFAULT_ENTRY logical
       name, supply NULL or a null string (\0) for this parameter.  When
       this entry name is used, the RPC runtime automatically uses the
       default name syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX
       logical name.

   if_handle
       A stub-generated data structure specifying the interface to look
       up.  If the interface specification has not been exported or is
       of no concern to the caller, specify NULL for this parameter.
       In this case the bindings returned are only guaranteed to be of
       a compatible and supported protocol sequence and contain the
       specified object UUID.  The desired interface might not be
       supported by the contacted server.

   object_uuid
       Specifies an optional object UUID.

       If you specify NULL or a nil UUID for this parameter, the returned
       binding handles contain one of the object UUIDs exported by the
       compatible server.  If the server did not export any object UUIDs,
       the returned compatible binding handles contain a nil object UUID.

       For a non-nil UUID, compatible binding handles are returned from
       an entry only if the server has exported the specified object UUID.
       Each returned binding handle contains the specified non-nil object
       UUID.

   binding_max_count
       Sets the maximum number of bindings to return in the
       binding_vector parameter of rpc_ns_binding_lookup_next().
       Specify rpc_c_binding_max_count_default to use the default count.

   Output

   lookup_context
       Returns the name service handle for use with the
       rpc_ns_binding_lookup_next() and rpc_ns_binding_lookup_done()
       routines.

   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_incomplete_name
                      Incomplete name.

       rpc_s_invalid_name_syntax
                      Invalid name syntax.

       rpc_s_invalid_object
                      Invalid object.

       rpc_s_no_env_setup
                      Environment variable not set up.

       rpc_s_unsupported_name_syntax
                      Unsupported name syntax.

 DESCRIPTION

   The rpc_ns_binding_lookup_begin() routine creates a lookup context for
   locating compatible server binding handles for servers.  These servers
   offer the specified interface and object UUID in the respective
   if_handle and object_uuid parameters.

   Before calling rpc_ns_binding_lookup_next(), the client application
   must first create a lookup context by calling
   rpc_ns_binding_lookup_begin().  The parameters to this routine
   control the operation of rpc_ns_binding_lookup_next().

   When finished locating binding handles, the client application calls
   the rpc_ns_binding_lookup_done() routine to delete the lookup context.

   Permissions Required

   No permissions are required.

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: rpc_ns_binding_lookup_done
              rpc_ns_binding_lookup_next
              rpc_ns_mgmt_handle_set_exp_age