AmiTCP/IP RPC Notes
*******************

This chapter describes the AmiTCP/IP version of the Sun RPC 4.0.

Note: Read this chapter carefully and then do the ``Hello World!'' test with the provided demonstration protocols in demo directory.  Once you get these compiled and running you know that your setup is complete.

About the Port to AmiTCP/IP and Amiga
=====================================

Nonsupported Features
---------------------

Following features are not supported/modified in this version:

Secure RPC
     This is not yet supported. I might decide to support it, if it is requested. This means that none of the DES authentication functions are included in the library.

Broadcast RPC
     The current support for Broadcast RPC is limited in sense that the portmap blocks while serving the broadcasted RPC. This means that the portmap services are not available during that time, which may prevent some RPC servers from functioning correctly.

getrpcent()
     Didn't include this, since AmiTCP/IP doesn't provide the *ent() functions in general. I might re-enable this if there is any demand for it.

svcfd_create()
     This is not included, since the library uses AmiTCP/IP socket descriptors. This might be added if there ever becomes a good, portable solution to the file vs. socket descriptor problem.

About the Floating Point Format
-------------------------------

The library supports only IEEE format floating point values (xdr_float() and xdr_double()). The FFP format must not be used. Consult your compiler documentation about choosing the floating point format (SAS/C uses IEEE by default).

What Was Done to the Original SUNRPC 4.0 While Porting
------------------------------------------------------

 1. Added ANSI C prototypes to all function and function pointer prototypes

 2. ANSIfied the includes if possible (sys/errno.h -> errno.h, for example).

 3. Removed dependency on select() retaining the value of the timeout timeval.

 4. Changed read() and write() calls to recv() and send(), respectively. This prevents the usage of the real file descriptors (see the svcfd_create() in Nonsupported Features).

 5. Added sys/param.h as the first include file for every .c file for concistency.

 6. Added XDRFUN definition to rpc/types.h. It is used in definition of every xdr-function.

 7. Changed close()s and ioctl()s on sockets to CloseSocket() and IoctlSocket() if AMITCP is defined.

 8. Changed getpid()s to FindTask(NULL) if AMIGA is defined.

 9. Changed socket calls no to be retried after the EINTR error return.

rpcgen Notes
============

The rpcgen included in this distibution is ported from the TIRPC (Transport Independent RPC) rpcgen from Linux by Carsten Heyl <ch@irb.informatik.uni-dortmund.de>. This version of rpcgen can produce K&R/ANSI-C/C++ compatible output.  It also can generate inetd compatible daemons, but this feature is not yet supported. Refer to the manual page of the rpcgen for its usage.

The rpcgen needs a C preprocessor to handle the macros and comments. One suitable C preprocessor (cpp) is included in the distribution. It is based on an old DECUS cpp port by Fred Fish. Carsten added a -P option to suppress #line directives, which the cpp left on the output.

See rpcgen Manual Page.

portmap and rpcinfo
===================

portmap is the RPC program to internet port mapper, see Port Mapper Program Protocol. The portmap must be started before any RPC services, and it is best to include line ``run portmap'' to your AmiTCP:bin/startnet script. See portmap Manual Page.

The rpcinfo can be used to view portmap bindings on any host. See the manual page for the usage. See rpcinfo Manual Page.

Using the Library
=================

Supported Compilers
-------------------

The distribution contains precompiled library for the SAS/C 6.x, since it's the compiler I use. The library is highly portable though, and you should have no problems compiling it with DICE, GCC etc.

The only compiler dependent part I made there is the definition XDRFUN (in rpc/types.h), which is defined as __regargs for SAS/C and as nothing for others.

The makefiles are written for the SAS smake, but since it doesn't have any fancy features, they should be quite portable as well.

Compiling the library
---------------------

The library code assumes that the bsdsocket.library is opened by the caller, and the library base is in global variable named SocketBase. Also the global errno variable must be set with the AmiTCP/IP SocketBaseTagList() function (These are standard AmiTCP/IP practices and are provided by the net.lib autoinitialization routine, so normally these are no concern.).

The Smakefile of the library can compile eight different versions of the library, but only the rpcr.lib version is compiled by default, see Choosing the Library to Use. This library is installed to the AmiTCP:netlib directory by default.

Choosing the Library to Use
---------------------------

Eight different versions of the library are provided. The library is compiled either with or without the debugging information, with near or far data, and with register or stack arguments. Use the following table to select the right library:

     |   Arguments   |     Data      | Debugging |
     | Stack | Reg.  | Near  |  Far  | No  | Yes | Library name
     +-------+-------+-------+-------+-----+-----+--------------
     |   x   |       |   x   |       |  x  |     | rpc.lib
     |       |   x   |   x   |       |  x  |     | rpcr.lib
     |   x   |       |       |   x   |  x  |     | rpcnb.lib
     |       |   x   |       |   x   |  x  |     | rpcnbr.lib
     |   x   |       |   x   |       |     |  x  | grpc.lib
     |       |   x   |   x   |       |     |  x  | grpcr.lib
     |   x   |       |       |   x   |     |  x  | grpcnb.lib
     |       |   x   |       |   x   |     |  x  | grpcnbr.lib

The use of registerized arguments and near data is highly recommended, since these options provide smaller and faster executables.

To compile the desired version of the library, issue smake <Library name> or smake all to compile all the versions. The makefile can only install the default version to the netlib:, you must move the other libraries yourself.

The reason why the library is not compiled with SAS/C ARGS=BOTH is that there are some problems SAS/C not enforcing the function pointers prototyped as taking stack arguments actually being assigned with the proper (stack) entry point of a function, if there are both stack and register versions of the function available (as is the case with the ARGS=BOTH libraries).

Second reason is that if you want to use stack arguments, an ARGS=STACK library is faster than the BOTH equivalent.

The dedugging info is compiled with SAS/C FullFlush option.