# Running the RPC Compiler

See also:

- A summary of all the command line options

The syntax to invoke the compiler is: Under VAX/VMS, or MSDOS:

            RPCC <source_file_name> [/option] [/option] ...
      or    RPC <source_file_name> [/option] [/option] ...

The first form produces stubs in Pascal, FORTRAN, PILS or C, which you then compile. The second form, only available under VMS, is used for Pascal, and also runs the stubs though the preprocessor and (for VMS/Pascal or CERNCROSS pascal) compiles them. The RPCC command generates the souces for the stubs. The RPC command under VMS performs all the functions in the dotted circle, for Pascal only). Under Bsd UNIX, Ultrix:

            rpcc <source_file_name> [-option] [-option] ...

The source file is the RPCL description file described in the previous section. This file name can have any extension except '.ext'. The compiler options are listed below. The RPCC lists, on the standard output device, the generated version number of the stub, (see the /VERSION option), and a list of errors, if any. If no error has been found, it produces three output files called, by default:

            cli<source_file_name>           (The client stub module)

            ser<source_file_name>           (The server stub module)

            <source_file_name>.ext          (A Pascal or C declaration file)

The '.ext' file contains a Pascal or C declaration of the procedures declared in RPCL. This is a declaration of external procedures See also the TYPES option, later in this chapter. that you can use to include in your client program if you are programming in Pascal or C.

Note that under VAX/VMS you must run a command file (@DISK$D1:[RPC]RPC on VXCERN, on other machines it is @[...]SETUP in the directory in which the RPC software has been installed) to gain access to RPC commands, while under UNIX BSD the 'rpcc' should be present in any directory of your PATH shell variable.

## Target environment options

The stub code produced by the RPCC may be in FORTRAN, C, or in Pascal with INCLUDE preprocessor statements. If the RPC command is used, the pascal will be put through the INCLUDE preprocessor automatically, and compiled to object format where a compiler exists on the machine. The code may be tailored for one of the following compilers:

- A C compiler.
- A FORTRAN77 compiler.
- A PILS compiler or interpreter
- Omegasoft Pascal (version 2) for the M6809.
- VAX/VMS PASCAL,
- CERN Cross Software Pascal 2.5 for the Motorola 68000 family,
- UNIX Berkeley (or Ultrix) Pascal compiler
- IBM PC Turbo Pascal
- A standard Pascal compiler without modular compilation,

In all but the last case, separately compilable modules are produced which can be simply linked to your application. In the last case, standard Pascal code is provided for those applications that require monolithic compilation. In such a case one must include (by hand using the editor, or using a preprocessor) the code generated by RPCC in the main program before compilation. The target environment is specified separately for client and server using the following options:

             c<environment> [ =<filename> ]

to specify the client (caller) environment, and the option

            s<environment> [ =<filename> ]

to specify the server (called) environment. The = clauses are optional, and allow the name of the output file to be specified explicitly, overriding the default This clause is not available for the RPC form, only for RPCC. The can be one of the following:

genericC
  A standard C compiler. The files produced refer to an include file, rpcheader.h, which is supplied with the release. Under VMS, compile the stubs using the
  $ CC/INCLUDE=RPC_INC/DEFINE=VAXVMS option to have access to this file and select the correct compilation option if using the pascal library..
FORTRAN
  A FORTRAN77 compiler. If structures are specified in the RPC definition file, the FORTRAN stubs will have structures in VAX/FORTRAN format.
PILS
  A PILS (Portable Interactive Language System) compiler or interpreter.
cerncross
  Cern Cross Pascal M680x0 compiler;
M6809
  Omegasoft M6809 Pascal Compiler;
vaxpascal
  VAX/VMS Pascal compiler. Strings are of type VARYING OF CHAR.
vaxvms
  VAX/VMS Pascal compiler (strings FORTRAN compatible). This options is included for back-compatibility but is not recommended.
unixbsd
  Berkley Unix (or Ultrix) Pascal Compiler;
pcturbo
  The Turbo Pascal system on the IBMyphen.PC
monolith
  A standard pascal compiler without modular compilation;

You should put at most one option for the client environment and one for the server environment. If you want to generate stub code for several environments, you must run the compiler several times giving different options each time. Example: The following command under UNIX generates pascal code for UNIX for the client side (into clifiler.rpc) and VAX/VMS for the server side (into the file mysstub.pas). It is supposed that input definition file is in 'filer.rpc'.

                   rpcc filer.rpc -cunixbsd -svaxvms=mysstub.pas

The following command under VAX/VMS generates object code for VAX/VMS for the client side (CLIFILER.OBJ) and M680X0 for the server side (SERFILER.CUF) . The input definition file is in FILER.RPC.

    		        $ RPC FILER.RPC  /CVAXVMS /SCERNCROSS

## Calling convention, BYVALUE

This section does not apply to PILS or FORTRAN stubs. In Pascal or C, stubs may be generated to respect either the FORTRAN, Pascal or C conventions. Intermediate possibilities exist, or example for C programs which are written to be FORTRAN callable.

The conventions used by the client stub should match those of the client program, and the conventions of the server stub must match those of the server routines. By running the compiler twice, it is possible to generate stubs of both types for the same package. These will be able to communicate with each other, so, for instance, a FORTRAN main program will be able to call subroutines written in C, and viceyphen.versa.

The two chief areas of difference are in the way strings are passed, and the way simple types are passed as IN parameters.

- For simple IN parameters, the deault is passing by address, for FORTRAN compatability (whatever language the stubs are generated in). The option allows them so be passed by immediate value. Not possible with SVAXVMS, CVAXVMS, SVAXPASCAL, CVAXPASCAL options. This is because under VAX/VMS, the Pascal is FORTRAN compatible, so a parameter is always passed by address, even if it is not "VAR". Therefore, VAX/Pascal stubs will not be compatible with C code. If C compatability is required, the stub should be generated using the genericC opions.
- The string passing is determined solely by the language option chosen. In C, the strings are null terminated, in Pascal they are passed by native Pascal string type (where available), by descriptor (VAXVMS option), or otherwise as two arguments, an array and a length. See the appendix on supported data types for details.

The following command under VAX/VMS generates C code for both stubs, which will be compatible with C client and server modules.

            $ RPCC FILER.RPC  /CGENERICC=CLIFILER.C /SGENERICC=SFILER.C /BYVALUE

To summarise the possible combinations,

Pascal
  Default, FORTRAN compatible. If the user program is in Pascal, all parameters must be passed "VAR".
Pascal, BYVALUE
  Pascal compatible, with IN parameters not passed with pascal "VAR".
GenericC
  This combination may be used to make stubs in C to be called from FORTRAN, where a pascal compiler is not avilable (OS9), but beware of the differences in string passing convention. All parameters must be passed by address (with an " in C).
GenericC, BYVALUE
  C compatible.

## Producing Type Declarations - TYPES

The option causes the user's type definitions to be included in the declaration (.ext) file . This is a convenient feature if the .ext file if to be used directly as a basis for the client or server program. If the user's types definitions already exist, or must be defined in terms of other types not in the RPC definition file, then this option will not be useful.

## Auto-Initialisation: NOAUTOINIT

This section applies in conjunction with VAXVMS, VAXPASCAL, PILS, PCTUBO or MACTURBO client and server options only. In these cases, normally, the client and server stubs are initialised Under VMS, the [INITIALIZE] attribute of a procedure is used to cause initialisation code to be put into the LIB$INITIALIZE PSECT so that the procedure will be called on image load. Under PILS or TurboPascal, each module contains a main section which is called initially before the main program. when a program is loaded, and make contact with each other automatically. Use of the NOAUTOINIT option suppresses this facility. In this case, the user is responsible for calling RPC_Open (on the client) and RPC_Attach (on the server) for each stub. See the section on initialisation procedures.

The initialisation makes the RPC system totally invisible to the user code, but you may wish to suppress it for portability, or for introducing your own special initialisation code. Example:

                     $ RPC FILER.RPC  /SVAXVMS /CVAXVMS /NOAUTOINIT

## CONCURRENT Execution option

The concurrent option modifies the code produced by the compiler, by making the PRAGMA CONCURRENT implicitly apply to all procedures which return no results, that is, procedures (not functions) which have no OUT or INOUT parameters. For these procedures, the server stub is made to reply immediately to the caller, before executing the called routine. See under "Pragmas". Example:

                     $ RPCC FILER.RPC  /SFORTRAN=S.FOR /CFORTRAN=C.FOR /CONCURRENT

Users of this facility should bear in mind, however, that the semantics of a concurrent remote call differ from those of a local call.

## LARGE parameter option

This option is not needed under version 3.0 onward , as multiple messages are used to send large parameters. The option to increase the buffer size is only kept for back-compatibility with version 2.

Under VMS, and using the RPC (not RPCC) command only, stubs may be generated with the parameter size extended to 8kB from 1.5kB. When this is done,

- When using the RPC command and Pascal stubs, the LARGE option must be specified. (Not required for C or FORTRAN stubs).
- The resulting stubs must be linked with the RPC_LARGE library rather than the RPC_LIB library. (These are logical names).
- Communication is not available over raw ethernet.

## Compiler error messages and error recovery

When the RPCC finds an error it prints on the standard output the line number in which the error occurred, then the offending input line with an arrow below the first character of the word that was wrong and finally, on the third line, the error meassage. Error messages are in English and should be quite selfyphen.explanatory so no other information is provided. In general the RPCC tries to recover from the error without aborting. If the error is not fatal, a semicolon forgotten for example, the compiler inserts or deletes a word (token) and continues to parse the input. If the error is not simple, a very malformed declaration for example, the compiler skips the input until a meaningful structure is found. Sometimes this attempt at recovery can produce misleading error messages, so be careful, and try to correct the very first error before going on. If any errors at all are encountered, no code generation is performed.