=======================================================================
                        README for RxRPCgen:
            the Remote Procedure Call Generator utility:
=======================================================================

Table of Contents

   1.)   Introduction
   2.)   Requirements
   3.)   Installation
   4.)   Usage
   5.)   RPC configuration file
   6.)   Samples
   7.)   Pitfalls and limitations
   8.)   Getting Help

=======================================================================
1.) Introduction
=======================================================================

   ok - there is a Socket API for REXX - so far so good,  but you want
   more comfort in creating distibuted applications?
   Maybe you find it nasty to do all the nitty socket stuff (creating,
   configuring, accepting, closing, ...) every time again...here come
   the solution:

   The utility RxRPCgen takes 1 REXX program and 1 configuration file
   as input and generates 2 REXX programs that can be executed as
   distributed application - 1 program acts as server and the other as
   client.

   :-)   creating a remote executable function is as easy as stating
         its name in the configuration file!

   :-)   you don't even have to code one single line of Socket code.

   :-(   supports only workstation API at the moment.

=======================================================================
2.) Requirements
=======================================================================

   This software is designed for the following platforms:
      - AIX
      - Linux
      - Linux for S/390
      - Win32
      - OS/2

   Your machine must be ready to use the TCP/IP protocol stack.

=======================================================================
3.) Usage
=======================================================================

   You need 2 input files for creating a distributed application
   using RxRPCgen:

   - a REXX program that will be divided into 2 pieces, namely the
     server and the client of the distributed application.

   - a RPC configuration file that configures the build process:
      - set the name of the input REXX proram
      - set the names of the output REXX prorams
      - set defaults for the server's IP address and port number.
      - declare the remote function's names
      - declare and initialize server side global variables

   The build is started using:

      rexx RxRPCgen <rpc_config_file>

=======================================================================
4.) RPC configuration file
=======================================================================

   A configuration file schematically looks like this:

      rexxFileName        = <input_file>
      clientFileName      = <client_output_file>
      serverFileName      = <server_output_file>
      defaultServerAddr   = <ip_address>
      defaultServerPort   = <tcp/udp_port_number>

      remoteFunctions:
      <func_1>
      <func_2>
      ....

      serverGlobalVars:
      <var_1> [= <init_value_1>]
      <var_2> [= <init_value_2>]
      ...

   -  The "defaultServerAddr" and "defaultServerPort" parameters serve
      as default values when the client program is started without
      explicitly naming a server IP address.

   - Each line following "remoteFunctions:" is taken as declaration
     of a remote function.

   - Under "serverGlobalVars:" you may declare variables that will
     become global variables in the server program. Optionally you
     may initialize them to some value - initialization will happen
     once at server startup.

=======================================================================
5.) Samples
=======================================================================

   There are 2 samples provided:

   1.) hello   - a hello message with increasing numbers
   2.) strsrv  - some string services

   To start generating client and server code change into the
   directory where the RPC configuration file and the input REXX
   program are located (furtheron it is assumed that you unpacked
   the zip to the path "C:\RxRPCgen").

   So let's take a try and build the "Hello world" sample:

      c:
      cd c:\RxRPCgen\samples\hello
      rexx ..\..\RxRPCgen hello.rpc

   While processing the generator prints messages.
   Now you are ready to start the distributed application!
   First start the server:

      rexx hello_s [<port>]

   Optionally you may specify the port of service.
   The server prints its address and port of service at startup.
   Now open another shell window and start a client:

      rexx hello_c [<IP-address> <port>]

   Optionally you may specify the server's IP-address and its port of
   service.

=======================================================================
7.) Pitfalls and limitations
=======================================================================

   -  does only work with Workstation API

=======================================================================
8.) Getting Help
=======================================================================

   Visit our REXX family webpages at:

      http://www.ibm.com/software/ad/rexx/

   If you experience difficulties in using this package you can get
   help by writing an e-mail to:

      rexxhelp@vnet.ibm.com

   Also any suggestions for improvement or bug-reports are welcome.
   HAVE FUN WITH REXX!
