The programs in this directory demonstrate the RAW TCP and RAW UDP HRPC
protocols.  These protocols are designed to allow HRPC-capable clients/servers
to interact with ad-hoc-message-based insular servers/clients, providing the
advantages of HRPC (primarily, automatic stub generation, simple syntax, and
support for different transport protocols and data representations) without
changing the insular servers/clients.

These protocols are called "RAW" because they perform the simplest function
within the confines of the HRPC structure:  buffer allocation, socket
initialization, transmission, and data conversion.  In particular, they supply
no "RPC" protocol, i.e., message headers and processing associated with the
meanings of these headers.  The intention is that the HRPC-capable
client/server should marshal the needed message headers into/out of messages by
defining them explicitly in the Courier definition file, and then do any needed
processing at the client level.

Notes about the protocols:

	1. When using these protocols, there is no concept of procedure number,
	   as with the other HRPC protocols (and as is required by procedural
	   definitions in the Courier IDL description).  Instead, you just
	   define a single generic procedure (and give it any number you want
	   in the IDL description), which sends a message of the format
	   expected by the server, and receives back a message in the format
	   generated by the server.  Multiple server interfaces are achieved
	   through explicit field encoding (e.g., an OpCode field).
	2. They assume there is a single network standard data representation,
	   and that the application puts its port number into network standard
	   order (using, e.g., htons).
	3. The UDP protocol used here uses a simple timeout-and-retransmit
	   strategy.  The timeout period and number of retransmissions is
	   not application-level-settable.
	4. There is a conflict between the way C defines integers (32 bits)
	   and the way Courier defines them (16 bits).  The standard (non RAW)
	   OTW routines encode all numeric data as longs; the RAW integer
	   routine, however, encode INTEGERs as shorts, to allow one to
	   communicate with programs (like BIND) that use htons() and ntohs().
	5. ARRAYs don't include byte counts, as they do in Sun RPC.  This is
	   useful for ARRAY n OF UNSPECIFIED, to allow RAW clients to get a
	   number of unspec. data bytes, e.g., for a bit-packed field of a
	   message structure.
	6. Similarly, strings are null-terminated instead of byte-counted.
	   Also, strings are unaligned, since some programs (such as BIND) pack
	   them into messages this way.  If you want aligned strings with the
	   RAW HRPC protocols, you'll have to do it using a USERPROC.
	7. Note that the insular server/client can't just declare a message
	   structure as follows:
		struct {
			short IntPart;
			long LongPart;
			...
		} Msg;
	   because the C compiler will allocate 4 bytes for the short on a Vax,
	   but only 2 on a Sun (as demonstrated by the program AlignTest.c in
	   this directory); rather, you must declare a char * buffer, and then
	   marshal in the bytes, setting the alignment boundaries so that
	   shorts are allocated 2 bytes, and other numeric data (longs and
	   booleans) are allocated 4 bytes; if you do not do this, the
	   alignment of shorts won't be consistent across machine types.  This
	   is unfortunate, since such a definition is easier to manipulate than
	   a char * definition, and dbx(1) can print it out meaningfully too.
	   You can get around the problem by always using long data, but not
	   all insular applications (BIND in particular) do this.




To demonstrate these protocols, do the following:

	1. make
	2. vanillaServer 3011 &		(note: 3011 is currently set in the
					 name service for this test)
	3. vanillaClient -t 3011 [host]
	   (you will see that the server gets the client's message on a TCP
	   port, and the client gets the server's response).  Currently, borneo
	   and larry are the only hosts registered in the name service for
	   this test.
	4. vanillaClient -u 3011 [host]
	   (similar to 3 above, but using UDP)
	5. hrpcclient
	   (prompts you... try both TCP and UDP; try client and server on the
	   same and different hosts; try client and server on the same and
	   different host types).
