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.

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.

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.

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.

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.

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.