Running the RPC Compiler
See also:
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
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.
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.
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
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.
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.