1. Using cedarrpcgen
Invoking cedarrpcgen
cedarrpcgen is a C program that must be run from a Unix command shell. To run the stub generator, use the command
/project/cedar10.1/bin/cedarrpcgen module.x
where module.x is the name of the file containing the interface specification. This command will generate up to five files (where ``module'' is replaced by the actual name supplied):
module.mesa -- A Cedar interface for this module.
moduleClientImpl.mesa -- Client stubs that export the interface and make RPC calls using the SunRPC or SunRPCStream package.
moduleServerImpl.mesa -- Server stubs that import the interface and incoming RPC requests into calls on the interface.
moduleGetPut.mesa -- An interface for marshalling and unmarshalling the types in module.mesa.
moduleGetPutImpl.mesa -- Its implementation.
If no options are specified, then cedarrpcgen will produce stubs for Cedar10.0. Options can be used to produce either UDP or TCP stubs for PCedar2.0:
-PCedar -- Produce PCedar2.0 stubs that use SunRPC to produce UDP-based RPC calls.
-PCedarStream -- Produce PCedar2.0 stubs that use SunRPCStream to produce TCP-based RPC calls.
Two additional options are available that provide "creature comforts" in the generated Cedar stubs. It is envisioned that users will normally invoke these options; they are not the default for the sake of backwards compatibility.
-p -- Strip module name prefixes from symbol names. For example, if the type definition foo�r exists in the RPC interface file foo.x then this option will cause the Cedar stubs to use the name foo.bar instead of foo.foobar. This option also provides a slightly modified version of naming for union types that produces more readable Cedar code.
-e -- Expand procedure input arguments. SunRPC .x files allow specification of only a single input argument to a procedure. This option will expand any procedure input variable that is a record type into a list of arguments comprised of the fields of the record definition in the emitted Cedar stubs (both the client and the server stubs).
Note: For PCedar2.0 you can either produce UDP-based stubs or TCP-based stubs, but not both. I could have made the TCP-based stubs be emitted under different file names - so that one could produce both sets of stubs - but have not made that extension because PCedar2.0 will soon be obsolete and current PCedar2.0 clients need one or the other, but not both.
Input files
The input language is Sun's RPC language. For a detailed description, see ``rpcgen Programming Guide'', in the Network Programming manual.
Require files
To run the resulting code in Cedar, you will need require files to ensure that the proper packages are running. For the client, the file should look like this:
-- moduleClient.require
-- Copyright Ó 1990 by Xerox Corporation. All rights reserved.
-- Generic require file for cedarrpcgen clients.
-- SunRPC and SunRPCAuth
require PCedar SunRPCRuntime SunRPCRuntime
-- SunPMapClient
require PCedar SunPMap SunPMapClient
-- The client stub.
run moduleGetPutImpl
run moduleClientImpl
For the server, it should read:
-- moduleServer.require
-- Copyright Ó 1990 by Xerox Corporation. All rights reserved.
-- Generic require file for cedarrpcgen servers.
-- SunPMapLocal
require PCedar SunPMap SunPMapLocal
-- SunRPC
require PCedar SunRPCRuntime SunRPCRuntime
-- The server stub
run moduleGetPutImpl
run YourServerImplementation
run moduleServerImpl
DF files
Your package-PCR.df should contain the following lines to get the .mob files needed to compile the stubs:
Imports [PCedar2.0]<Top>SunRPCRuntime-PCR.df Of ~=
Using [SunRPC.mob, SunRPCAuth.mob]
Imports [PCedar2.0]<Top>RuntimeSupport-PCR.df Of ~=
Using [Basics.mob]
Imports [PCedar2.0]<Top>SunPMap-PCR.df Of ~=
Using [SunPMap.mob, SunPMapLocal.mob]
Imports [PCedar2.0]<Top>Communication-PCR.df Of ~=
Using [Arpa.mob]
Imports [PCedar2.0]<Top>SunPMap-PCR.df Of ~=
Using [SunPMapClient.mob]
Run-time considerations
cedarrpcgen produces an "interface object" for each program defined in module.x. Interface objects contain a procedure variable for each procedure defined in the corresponding SunRPC program. Interface objects are imported into a client program using the procedure ImportFooN, where Foo is the name of the program and N is the version number of the program. Interface objects are exported by server programs using the procedure ExportFooN.
The best way to get a feeling for how to use the stubs produced by cedarrpcgen is to look at the example program in the cedarrpcgen directory. The fortytwo program in this directory is an example that is currently compiled for use with UDP (the ImportFoo and ExportFoo routines to use with TCP are shown as comments). The program uses three different .x files: fortytwo.x, fourtwo.x, and fortyone.x. fortytwo.x includes the other two. The client program is named fortytwoClient and the server program is named fortytwoServer. See their respective config files for more information about their composition.
Note: The fortytwo program also illustrates a problem with SunRPC* in PCedar2.0; namely that XR�positField for real and double real numbers doesn't seem to work. If you run either fortytwoClient or fortytwoServer against some other server or client, respectively, then you will see them get part of the way through execution and then generate an exception signal. This problem is supposedly fixed in Cedar10.1.
2. Generated code
This section describes how the various types allowed in Sun's RPC language are translated into Cedar code.
Simple types
The simple data types in C translate as follows
bool BOOLEAN
char BYTE
u𡤌har BYTE
short INT16
u←short CARD16
int INT32
u←int CARD32
long INT32
u←long CARD32
Note that char arrays may not do what you expect, as they transmit a 32-bit word for each character. Instead, try string or opaque.
Structures
Structures are translated component by component.
Unions
Unions are translated into REFs to variant records, with the first field being the tag type declared in the RPC file, and the actual Cedar tag being an anonymous enumeration. The case arms specified in the RPC description are used in a SELECT statement to marshall and unmarshall the correct variant. Warning: The value of the user-defined tag field must match the Cedar tag or the marshalling routines will get an exception trying to NARROW a REF.
When unions are transmitted, an allocation is done on the receiving side to hold the incoming value.
Fixed-length Arrays
Fixed-length arrays are translated into packed arrays of the corresponding type.
Variable-length arrays
Variable-length arrays are translated into REFs to SEQUENCES with a max length of "size". When a variable-length array is transmitted, a new sequence is allocated on the receiving side.
Pointers
Pointers are translated into REFs. The data pointed to by the pointer is transmitted, and an allocation is done on the receiving side to hold the incoming data. If the transmitted pointer is NIL, then the receiver winds up with a NIL pointer. Pointers can thus be used to transmit recursive data structures, such as linked lists, but the stack frame is used for each pointer when marshalling or unmarshalling.
Strings
All strings are converted to ROPEs, regardless of max length.
Opaque
Opaque data declared as a fixed-length array is converted to a packed array of BYTE. Opaque data declared as a variable-length array is translated to a REF TEXT, regardless of max length.
3. An Example
The directory containing the source code for cedarrpcgen also contains an example client-server set of programs that employ cedarrpcgen. The SunRPC interface files for this example are:
fortytwo.x
fourtwo.x
fortyone.x
The client program that uses the RPC interface defined by these files is:
fortytwoClientMain.mesa
while the server program that implements the interface is:
fortytwoServerMain.mesa
To recompile and run this example do the steps listed below. You will obtain two programs: fortytwoClient and fortytwoServer. (You will also get cedarrpcgen recompiled if the local version in your directory is out-of-date.)
Note: These two programs currently expect to be running on the same host (I haven't yet added a command-line parameter to the client to allow specification of a host for the server).
From a Unix command shell issue the commands
cedarrpcgen -p -e fortytwo.x
cedarrpcgen -p -e fourtwo.x
cedarrpcgen -p -e fortyone.x
From a Cedar commandtool issue the command
makedo -df CedarRPCGen
From a Cedar commandtool issue the commands (assuming an -ux working directory)
pma /cedar/cedarrpcgen -ux:$(pwd)
fortytwoServer
From another Cedar commandtool issue the commands
pma /cedar/cedarrpcgen -ux:$(pwd)
fortytwoClient
Note: In PCedar you end up in the Cirio debugger because PCedar doesn't correctly implement the floating point case for RPC.