Writing the definition file

See also: The RPC Compiler accepts a formal description of the procedures which are called remotely, and their parameters. It produces as output the necessary software to exchange data between your local application and the remote one. The input language is called RPCL. The RPCL syntax is a similar to the ADA language; the reader is referred to the formal definition for details.

(@@picture omitted)

The definition file defines the interface between two software modules. An example input file is

PACKAGE myfacility IS TYPE myarray IS ARRAY(1..20) OF RPC_LONG; PROCEDURE doit( xxx: IN RPC_SHORT; yyy: OUT myarray); END myfacility; The package in this example contains a procedure to set the state of, say, a remote valve. The procedure takes three input parameters from the caller: two integers (func, index) and a real. It does not alter the value of these. It has one output parameter which happens to be the last one, a 32 bit status value (stat). The procedure does not use the initial value of stat, but a new value is returned to the caller.

(In the examples, the reserved words are given in upper case for clarity, although in an input file upper and lower case are treated the same.)

In general, the input file is composed of two parts: type declarations and procedure/function declarations.

In a type declaration complicated types may, if necessary, be defined in terms of simpler types.

In the second part of the file, the remote procedures and functions are defined by giving, for each one, its name, the number and type of parameters, their direction and, for a function, the type of value returned. This is very similar to the declaration of a external procedure in other high level languages.

See:

This list of declarations is automatically generated by the RPC Compiler, as the .ext file using the TYPES compiler option .

PRAGMAs

A PRAGMA is a statement in an RPC definition file which instructs the compiler how to implement something, without fundamentally changing the definition of the interface. A PRAGMA consists of the word PRAGMA followed by the name of the pragma, followed by (in brackets) the name of things to which it applies, and any other parameters.

PRAGMA TIMEOUT

Syntax: PRAGMA TIMEOUT ( <procedure_name> , <value> ); This specifies the absolute maximum time which the procedure could possibly be expected to take, including any network delays. The RPC system will check this time (when the underlying transport service allows it) and if it expires will create and error. This will halt the program unless a user Error Handler (q.v.) or a Call Status parameter (q.v.) is used.

If this pragma is not used, the default will be no timeout, or the value specified with the TIMEOUT compiler option, if that has been given.

The procedure (or function) name given must already have been declared.

The value is given in units of 10ms as a decimal integer value.

PRAGMA CONCURRENT

Syntax: PRAGMA CONCURRENT ( <procedure_name> , { <procedure_name> }* ); the {braces}* indicating more than one (previously declared) procedure name may be given.

This specifies that, once started, the procedure should continue execution concurrently with the client. The fact that the client continues processing after the procesdure call does not, in this case, signify that the procedure is complete: only, that it has started. The flow of control for a normal call and for a concurrent call. The procedure ( not function) name given must already have been declared. It may not have any return (OUT or INOUT) parameters.

This method provides concurrency between the caller and the called routine. There are other methods of achieving concurrency, for example which allow a separate server task to run concurrently with the client processes, and be interrupted to service a remote call. These are described under "varieties of server".

See also PRAGMA CAST below.

PRAGMA CAST

Syntax: PRAGMA CAST ( <procedure_name> , { <procedure_name> }* ); the {braces}* indicating more than one (previously declared) procedure name may be given.

This specifies that no return message should be sent at all. The call message is sent and return is immediately made to the caller.

Over a reliable stream oriented medium (TCP, DECnet, ISO TP4, CHI etc.), this allows information to be streamed between a client producing it and a server receiving it. This may significantly increase the efficiency in some applications.

Over a non-reliable medium (raw ethernet, UDP etc.), this option supresses the protocol which ensures reliable transmission of the data.There is no acknowledgement made at all. This can speed up execution by a factor of two or more.

Pragma CAST also allows broadcast and multicast calls to be made where the transport protocol supports it, for example over raw ethernet.

Client Server | |------- call message -----> | | | | | - (There is no reply) | V execution continues The flow of control for a cast. The procedure ( not function) name given must already have been declared. It may not have any return (OUT or INOUT) parameters.

PRAGMA CALL_STATUS

Syntax: PRAGMA CALL_STATUS ( <procedure_name> , <parameter_name> ); This informs the compiler that the parameter indicated is a status parameter for the return of any bad call status. In this case, if any error (network failure, timeout, etc.,) occurs during the call, a VMS&hyphen.style error code will be put into this parameter and all the other OUT parameters (and return value of a function) will be undefined. In this case the RPC system will not take the normal error action (calling user error handlers or aborting the program with an error message).

The procedure (or function) name given must already have been declared.

The parameter name must be the identifier of one of the parameters of that procedure. The parameter must be OUT or INOUT, and of type RPC_LONG.

PRAGMA EXTERNAL_MARSHALLING

Syntax: PRAGMA EXTERNAL_MARSHALLING ( <type_id> ); The type_id must refer to a previously defined type.

This tells the compiler that external procedures PCK_ and UPK_ will be used to marshal and unmarshal (respectively) the given type. Marshalling is the process of taking data from the user space and putting it into a message in the correct format for transmission.

This pragma will allow types whose data type is a function of circumstance (unions, private conventions, etc) to be transferred as RPC parameters. It also allows the RPC system to send any related data which may be required, such as to send over parts of a FORTRAN common block. Also, side effects may be put into user marshalling routines, such as parameter value checking, rebinding of the client depending on a particular parameter value, etc.

The type must already be declared, and it is this declaration which will decide how much memory is allocated to receive a variable of this type in the server.

The marshaling routines must be provided by the user, or may be distributed with a library for certain special types. Their format is as follows:

-- Marshalling for type <type_id> PROCEDURE PCK_<type_id> ( rpc_p_buf: IN rpc_buffer_pointer; -- by reference variable: IN <type_id>); -- by reference -- Unmarshalling for type <type_id> PROCEDURE UPK_<type_id> ( rpc_p_buf: IN rpc_buffer_pointer; -- by reference variable: OUT <type_id>); -- by reference The writer of these routines is recommended to build them in terms of the basic routines such as PCK_INTEGER etc which are defined in the include files RPCSTUB.H (Pascal), rpcheader.h (for C). (Under VMS, these files are under the RPC_INC directory).