VMS Help DCE_RPC, API Runtime Intro, Frequently Used Routine Parameters  *Conan The Librarian (sorry for the slow response - running on an old VAX)

   A few parameters are common to many of the DCE RPC routines.
   These parameters are described fully here and again briefly
   on the specific routine reference pages.

1 - binding

   Used as an input or output parameter.

   Returns a binding handle for making remote procedure calls to a
   server.

   A client obtains a binding handle by calling one of the following
   routines:

          + rpc_binding_copy()

          + rpc_binding_from_string_binding()

          + rpc_ns_binding_import_next()

          + rpc_ns_binding_select()

   Creating a binding handle establishes a relationship between a
   client and a server.   However, the relationship does not involve
   any communications between the client and server.  The
   communications occur when a client makes a remote procedure call.

   As an input parameter to a remote procedure call, binding specifies
   a binding handle that refers to binding information.  The client's
   RPC runtime uses this binding information to make a remote procedure
   call to a server.  Server manager routines can extract client
   information from a client binding handle by using the following
   routines:

          + rpc_binding_inq_auth_client()

          + rpc_binding_inq_object()

          + rpc_binding_to_string_binding()

          + rpc_string_binding_parse()

2 - name

   Used as an input/output parameter.

   When used as an input parameter, the value of this  parameter
   depends on the syntax selected in the name_syntax parameter.  If
   it is allowed by the called routine, the value NULL specifies
   that the routine uses the name specified in the RPC_DEFAULT_ENTRY
   environment variable.  Specifying NULL also has the called routine
   use the name syntax that the environment variable
   RPC_DEFAULT_ENTRY_SYNTAX specifies.

   For a name_syntax value of rpc_c_ns_syntax_dce, use the DCE naming
   rules to specify parameter name.

   As an output parameter, returns an entry in the name service
   database in the form of a character string that includes a
   terminating null character.  The value of this parameter depends
   on the syntax selected in name_syntax.

   For a name_syntax value of rpc_c_ns_syntax_dce, name is returned
   using the DCE naming syntax.

   The DCE RPC runtime allocates memory for the returned string.  The
   application is responsible for calling the rpc_string_free() routine
   to deallocate the string.

   If an application does not want a returned name string, the
   application usually specifies NULL for this parameter.  The one
   exception is routine rpc_ns_entry_expand_name(); it always
   returns a name string.

3 - name_syntax

   Used as an input parameter, an integer value that specifies the
   syntax of an entry name.  When allowed by the called routine, a
   value of rpc_c_ns_syntax_default specifies that the routine uses
   the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX environment
   variable.  The following table lists the valid syntaxes that
   applications can use in DCE RPC for entries in the name service
   database.

                            Valid Name Syntaxes
              ________________________________________________
              Constant                  Value   Description
              ________________________________________________
              rpc_c_ns_syntax_default     0     Default syntax
              rpc_c_ns_syntax_dce         3     DCE

   The name_syntax parameter tells routines how to parse the entry
   name specified in an input name parameter or specifies the syntax
   to use when returning an entry name as an output name parameter.

   If the RPC_DEFAULT_ENTRY_SYNTAX environment variable is not
   defined, the RPC runtime uses the rpc_c_ns_syntax_dce name syntax.

4 - string

   Used as an input or output parameter.

   Returns a character string, which always includes the terminating
   null character \0.  The DCE RPC runtime allocates memory for the
   returned string.  The application calls the rpc_string_free()
   routine to deallocate the memory occupied by the string.

   If there is no data for the requested string, the routine returns
   the string \0.  For example, if the string binding passed to
   routine rpc_string_binding_parse() does not contain an object UUID,
   the routine returns \0 as the value of the object UUID string.  The
   application must call the rpc_string_free() routine to deallocate
   the memory occupied by this string.

   If an application does not require a returned output string, the
   application specifies NULL for this parameter.

5 - status

   Each routine in the RPC API returns a DCE status code indicating
   whether the routine completed successfully or, if not, why not.
   A return value of rpc_s_ok indicates success.  All other return
   values signify routine failure.  The status codes listed for each
   RPC runtime routine are the most likely, but not necessarily all,
   the status codes that the routine can return.

   The status code argument has a data type of unsigned32.

   To translate a DCE status code to a text message, call the routine
   dce_error_inq_text().

   Note that RPC exceptions are equivalent to RPC status codes.  To
   identify the status code that corresponds to a given exception,
   replace the _x_ string of the exception with the string _s_; for
   example, the exception rpc_x_already_listening is equivalent to
   the status code rpc_s_already_listening.

   For more information about the RPC status codes, see the OSF DCE
   Problem Determination Guide.

6 - uuid

   Used as an input or output parameter.

   When you need to specify a nil UUID to a uuid input parameter in
   any of the DCE RPC routines, you can supply the value NULL.