OSF DCE Application Development Guide--Introduction and Style Guide

RPC Parameters
IDL also provides two execution semantic attributes of somewhat more limited use:
broadcast and maybe. Broadcast semantics may be used with connectionless transports
when there are multiple servers on the local network that can handle a call. The client
broadcasts the call request to all servers, and completes the call with one of them.
Maybe semantics provides a calling style that may be used when a call has no [out] or
[in, out] parameters. The call is attempted once, and no response is returned. Both
broadcast and maybe semantics implictly require that the operation be idempotent.
6.2 Parameter Semantics
RPC calls and the RPC API specify directional attributes for their parameters, even
though such attributes are not formally supported by C. As a general rule, an [in]
parameter is one that must be passed with a meaningful value and an [out] parameter is
one whose value will be changed by the call. An [in,out] parameter is therefore one
which must have a meaningful value on input and which may be changed on output.
The following table summarizes parameter semantics:
TABLE 6-1. Parameter Semantics
_____________________________________________________
Semantics Meaningful value input Changed on output
_____________________________________________________
_____________________________________________________
[in] yes no
[out] no yes
[in,out] yes yes
_____________________________________________________
An [out] or( [in,out]) parameter is one whose value is changed by the call, so it must be
passed by reference, that is, as a pointer to the datum of interest. RPCs and the RPC
APIs therefore always specify output parameters as pointers. The address passed must
always point to valid storage. For example, the ubiquitous status parameter may be
declared in the IDL as follows:
[out] error_status_t *status
The application code then needs to declare a variable such as the following, and pass it
as &st to each RPC:
error_status_t st;
When a call allocates storage for an output parameter, it is declared as a pointer to a
pointer. For example:
rpc_binding_vector_t **binding_vector
The application follows the same rule as in the status case, declaring a variable such as
the following, and then passing this as &binding_vec:
rpc_binding_vector_t *binding_vec
124246 Tandem Computers Incorporated 6−3