=======================================================================
README for REXX Socket API sample:   "RPC program generator utility"
=======================================================================

   Contents:

      1.)   Abstract
      2.)   Description
      3.)   Requirements
      4.)   Installation instructions
      5.)   Usage
      6.)   RPC configuration file
      7.)   Samples
      8.)   Limitations
      9.)   Getting Help

=======================================================================
1.) Abstract
=======================================================================

   This is a simple RPC (Remote Procedure Calling) program generator
   utility for REXX.

=======================================================================
2.) Description
=======================================================================

   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 remotely executable function is as easy as putting
         the function name into the RPC configuration file!

   :-)   You don't even have to code one single line of Socket code
         to generate a socket application.

   :-)   The utility is easily extensible to your own needs.

   :-(   Supports only workstation API at the moment.

=======================================================================
3.) Requirements
=======================================================================

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

   Machines that shall run a socket application must be ready to use
   the TCP/IP protocol stack.

   To test a socket application on only one machine you even need not
   have a network adapter installed - just use the special loopback IP
   address 127.0.0.1.

=======================================================================
4.)   Installation instructions
=======================================================================

   1.) Unzip the *.ZIP file on a workstation.

   2.) You should find following files:

         Readme.txt
         rxRPCgen.rex
         _c.rex
         _s.rex

         samples/strsrv/strsrv.rex
         samples/strsrv/strsrv.rpc
         samples/strsrv/strsrv_c.rex
         samples/strsrv/strsrv_s.rex

         samples/hello/hello.rex
         samples/hello/hello.rpc
         samples/hello/hello_c.rex
         samples/hello/hello_s.rex

=======================================================================
5.) 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 program
      - set the names of the output REXX programs
      - set defaults for the server's IP address and port number.
      - declare the remote functions' names
      - declare and initialize server side global variables

   The build is started using:

      rexx rxRPCgen <rpc_config_file>

=======================================================================
6.) 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 generated programs are started without
      explicitly naming a server IP address and port.

   -  Each line following "remoteFunctions:" is taken as declaration
      of a remote function - just give the names of the functions.

   -  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.

=======================================================================
7.) 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 out messages.
   Now you are ready to start the distributed application!
   First start the server:

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

   Optionally you may specify the server's IP-address and its port of
   service - if not given the defaults from the RPC configuration file
   are used.
   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 - if not given the defaults from the RPC configuration file
   are used.

=======================================================================
8.) Limitations
=======================================================================

   -  does only work with Workstation REXX Socket API.

=======================================================================
9.) 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!
