<> <> <> <<>> cedarrpcgenDoc CEDAR 10.1 % cedarrpcgenDoc SunRPC stubs for Cedar Marvin Theimer Ó Copyright 1992 Xerox Corporation. All rights reserved. Abstract: cedarrpcgen is a modified version of Sun's RPCGen that accepts interface specifications in Sun's RPC language and emits stubs written in Cedar. The stubs allows C and Cedar programs to communicate via remote procedure call using Sun's RPC protocol. Created by: Marvin Theimer Maintained by: Marvin Theimer Keywords: RPC, Stub compiler, Sun RPC XEROX Xerox Corporation Palo Alto Research Center 3333 Coyote Hill Road Palo Alto, California 94304 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_bar 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]SunRPCRuntime-PCR.df Of ~= Using [SunRPC.mob, SunRPCAuth.mob] Imports [PCedar2.0]RuntimeSupport-PCR.df Of ~= Using [Basics.mob] Imports [PCedar2.0]SunPMap-PCR.df Of ~= Using [SunPMap.mob, SunPMapLocal.mob] Imports [PCedar2.0]Communication-PCR.df Of ~= Using [Arpa.mob] Imports [PCedar2.0]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_DepositField 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_char 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.