Previous
section.
CDE 1.1:
Remote Procedure Call
Copyright © 1997 The Open Group
RPC Service Definition
This chapter specifies the basic operations performed
by a Remote Procedure Call (RPC). These operations, which represent the
interaction between the service user and the service provider, are specified
as service primitives.
The service users are represented in the client stub and
client application code and in the server stub, server manager routines
and server application code, which provide the appropriate parameter values
and process the results.
The service provider is represented in the RPC run-time
system and is specified in the protocol machines, which generate and receive
the events driven by the service primitives.
Call Representation Data Structure
The call
representation data structure is an input parameter to all service
primitives described here. Some information is dynamically generated during
the sequence of common service operations that comprise an RPC.
The call representation data structure contains all of
the control information about an individual RPC. This includes location
and interface information. An interface specification and an operation
number define the interface information. Dynamic information includes the
transfer syntax in which the RPC arguments are marshalled, and cancel state
information.
An RPC protocol machine may have specific information
particular to an RPC. To facilitate this, the call representation data
structure is composed of a common part and a protocol-specific part. A
call handle is provided to the RPC stubs as an opaque pointer to
the the call representation data structure.
Service Primitives
The tables in this chapter, which specify the parameters
that are present in each service primitive, use the following notation,
as described in the ISO TR 8509 standard:
- M
- The parameter is mandatory. It will always be present
in the service primitive.
- U
- The parameter is a user option. It need not be provided
by the user in the particular instance of the service primitive.
- C
- The parameter is conditional. It will always be present
in that indication-type primitive if it was present in the corresponding
request-type primitive.
- (=)
- When the parameter is present in a particular instance
of that indication-type primitive, it takes the same value it had in the
corresponding request-type primitive.
Invoke
The Invoke service primitive is used to invoke
an RPC. The Invoke service primitive is service user-initiated.
Invoke
Parameters lists the parameters of the Invoke service
primitive.
Parameter Name |
Request |
Indication |
Call_Handle |
M |
M |
Call_Args |
U |
C(=) |
Call_Status |
- |
M |
Table:
Invoke Parameters
The permitted parameter values are as follows:
- Call_Handle
- The call handle that uniquely identifies this RPC.
- Call_Args
- The marshalled call arguments according to the parameters
specified in the interface operation (IDL), if any.
- Call_Status
- A value indicating the status of the operation. For a
summary of possible condition values that this operation can return, refer
to Reject
Status Codes and Parameters .
The events and triggering conditions generated by this
service primitive are:
- START_CALL, TRANSMIT_REQ
The client user issues an RPC and generates the event START_CALL.
The conditional flag TRANSMIT_REQ indicates that there is data in the send
queue (request-type primitive).
- RECEIVE_PDU[REQUEST_PDU]
The server provider generates the event RECEIVE_PDU (conditionally
REQUEST_PDU) upon receiving a REQUEST PDU (indication-type primitive).
- RCV_LAST_IN_FRAG
The server provider promotes the requested operation (including
input data, if any) to the server user (server stub and manager routine)
for execution.
Result
The Result service primitive is used to return
the output and input/output parameters at the end of a normal execution
of the invoked RPC. The Result service primitive is server-user
(server manager routine) initiated.
Result
Parameters lists the parameters of the Result service
primitive.
Parameter Name |
Response |
Confirmation |
Call_Handle |
M |
M |
Result_Args |
U |
C(=) |
Call_Status |
- |
M |
Table:
Result Parameters
The permitted parameter values are as follows:
- Call_Handle
- The call handle that uniquely identifies this RPC.
- Result_Args
- The marshalled output and input/output arguments according
to the parameters specified in the interface operation (IDL), if any.
- Call_Status
- A value indicating the status of the operation. For a
summary of possible condition values that this operation can return, refer
to Reject
Status Codes and Parameters .
The events and triggering conditions generated by the
Result service primitive are as follows:
- PROC_RESPONSE, TRANSMIT_RESP
The server user processed this RPC request and generates
the event PROC_RESPONSE. The conditional flag TRANSMIT_RESP indicates data
in the send queue (response-type primitive).
- RECEIVE_PDU[RESPONSE_PDU]
The client provider generates the event RECEIVE_PDU (conditionally
RESPONSE_PDU) upon receiving a response PDU (confirmation-type primitive).
Cancel
The Cancel service primitive is used to cancel
an outstanding RPC. This operation forwards a client cancel request to
the server application thread. If the server application thread does not
return within a caller-specified time, the RPC will fail. Most of this
processing is specific to the associated protocol machines.
Cancel
Parameters lists the parameters of the Cancel service
primitive.
Parameter Name |
Request |
Indication |
Call_Handle |
M |
M |
Table:
Cancel Parameters
The permitted parameter value is as follows:
- Call_Handle
- The call handle that uniquely identifies this RPC. The
cancel-related data values and flags are modified appropriately.
The events and actions generated by the Cancel service
primitive are:
- CLIENT_CANCEL
- The client user has issued a request to terminate a call
in progress. The event CLIENT_CANCEL is generated.
- RCV_CAN_PDU
- The server provider receives a cancel PDU and
generates the event RCV_CAN_PDU (RECEIVE_PDU, conditionally CANCEL_PDU).
- CANCEL_NOTIFY_APP
The server provider notifies the server user about a pending
cancel request.
Error
The Error service primitive may be used by the
server manager routine to indicate an error in response to a previous Invoke
indication. The Error service primitive is server-user (server manager
routine) initiated.
Error Parameters
lists the parameters of the Error service primitive.
Parameter Name |
Response |
Confirmation |
Call_Handle |
M |
M |
Call_Error_Value |
M |
M(=) |
Table:
Error Parameters
The permitted parameter values are:
- Call_Handle
- The call handle that uniquely identifies this RPC.
- Call_Error_Value
- The marshalled error information.
The events generated by the Error service primitive
are as follows:
- PROCESSING_FAULT
The server user detected a fault during execution of the
requested operation and raises the event PROCESSING_FAULT.
- RCV_FAULT
- The client provider generates the event RCV_FAULT upon
receiving a fault PDU with fault status code.
Reject
The Reject service primitive indicates that there
is a problem with the underlying communications or the RPC protocol machines.
The reject reason (parameter, Call_Reject_Reason) can indicate the state
of a particular RPC and therefore may be evaluated to determine whether
the call has already been executed at the server. The Reject service
primitive is typically server provider-initiated. Some reject reasons such
as Op_Range_Error are detected at the server user and are server user-initiated.
Reject
Parameters lists the parameters of the Reject service
primitive.
Parameter Name |
Response |
Confirmation |
Call_Handle |
M |
M |
Call_Reject_Reason |
M |
M(=) |
Table:
Reject Parameters
The permitted parameter values are:
- Call_Handle
- The call handle that uniquely identifies this RPC.
- Call_Reject_Reason
- The marshalled reject information. For a summary of which
reject status codes are reported, refer to Reject
Status Codes .
The events generated by the Reject service primitive are
as follows:
- PROCESSING_FDNE
The server provider or server user rejects the execution
of the requested operation (FaultDidNotExecute) and raises the event PROCESSING_FDNE.
- RCV_FAULT
- The client provider generates the event RCV_FAULT upon
receiving either a reject PDU or a fault PDU with a reject
status code.
Please note that the html version of this specification
may contain formatting aberrations. The definitive version is available
as an electronic publication on CD-ROM from The Open Group.