5/20/92

This is code for a Modula-3 implementation of Sun RPC, written by Marvin
Theimer and me.  After unpacking, you should have three subdirectories:

	m3rpc       -- Modula-3 and C code for the library.
	m3rpcgen    -- A stub compiler.
	rpcexamples -- Several example/test programs.

To build it, try doing a make in the top-level directory.  The makefile
uses the $(MAKE) macro, which in Sun's make at least, invokes make again
with all the switches it was invoked with.  If it doesn't work, then run
make in each subdir in the order m3rpcgen, m3rpc, rpcexamples.  The only
warnings should be from code generated by the stub compiler.

There's a man page for m3rpcgen, but the rest is documented in the
interfaces to the extent that it's documented at all.


Making a program
================

To make a program, create a .x file that describes your RPC interface.
This should be written in Sun's RPC Language.  Files that work with rpcgen
should work with m3rpcgen.  Then run the file through m3rpcgen:

    % m3rpcgen Foo.x

You will get files named Foo.i3 (an interface for clients and servers for
this RPC service), Foo_c.m3 (client stubs), Foo_s.m3 (server stubs), and
possibly Foo_x.i3 and Foo_x.m3 (for "XDR", marshalling and unmarshalling
routines).  Compile these up and link them into your program along with the
code that calls the stubs and the runtime.  Link against libm3rpc.a.


The stubs and the library interface
===================================

The stub compiler is based on Sun's rpcgen and accepts Sun's RPC Language
(.x files).  It produces stubs that declare an object for each
program/version defined in the interface.  Thus, if Foo.x had something
like

    program FOO {
	version OLD_VERS {
	    resultType P(int) = 1;
	} = 23;
	version CURR_VERS {
	    resultType P(float) = 1;
	    int Q(paramType) = 2;
	} = 24;
    } = 234324234;

then Foo.i3 file would declare two objects, OLD_VERS with a P method, and
CURR_VERS with P and Q methods.  A client should do something like

    VAR
      b: RPCSun.BindingInfo;
      o: Foo.CURR_VERSClient;
    b := RPCSun.CreateBindingInfo(hostAddr, Foo.FOO_prognum,
				  Foo.CURR_VERS_versnum, 0,
				  RPCSun.Protocol.UDP);
    o := Foo.ImportCURR_VERS(b);
    r := o.P(2.34);

Only one call at a time may be outstanding on a client connection (but you
can have multiple connections).  The stub generator enforces this by use of
a lock embedded in the client stub object.

Currently, each client uses a socket, even for UDP.  Thus, you need to
destroy the socket by writing

    o.GetClient().Destroy();

to reclaim the file descriptor before discarding o.

The server should subclass Foo.CURR_VERS to create an object that implements
the object's methods, then export it with code like

    VAR
      b: RPCSun.BindingInfo;
      o: NEW(MyCURR_VERS);
    b := RPCSun.Export(Foo.GetCURR_VERSServerProc(o), Foo.FOO_prognum,
		       Foo.CURR_VERS_versnum, RPCSun.Protocol.UDP);

The export gives the server an RPCSun.BindingInfo, which is an opaque
structure that represents the address of an RPC server.  To allocate a
transient program number, the constant RPCSun.TransientProgram can be
supplied as the second parameter to RPCSun.Export.

The server object's implementation should be prepared to handle concurrent
method invocations.  Currently, the RPC server code will only do this if
more than one connection exists to a TCP service.

There is no support for authentication at this time.

This package uses the ExceptionArg conventions for exception parameters, as
described in a message I sent to the mailing list a while back.  The file
ExceptionArg.i3 has a reasonably detailed explanation.


Keeping in touch
================

If you have any questions, bug reports, bug fixes, or enhancements, drop me
a note at nichols@parc.xerox.com.

	David Nichols
	Xerox PARC

================================================================
Changes for 1.3 (5/20/92):
- Added support for transient program numbers.
- Converted to version 2.06 of the compiler.
- Bug fixes to m3rpcgen.
- Added locking to generated stubs.
================================================================
