=======================================================================
                        README for RxMake:
           the makefile utility for the REXX/370 compiler
=======================================================================

   contents:

         1)    Introduction
         2)    Requirements
         3)    Installation
         4)    Usage
         5)    Makefile
         6)    Samples
         7)    Pitfalls and limitations
         8)    Getting Help

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

   Haven't you always hated the complex way of compiling REXX programs
   to OBJECT format and linking them with stubs by using CHANGE cards
   in the linker steps?
   And anyway, haven't you always hated coding JCL jobs?

   ...well it doesn't have to be that difficult, here comes the
   solution:

   RxMake is a makefile utility for the REXX/370 compiler.
   You write the REXX program and a makfile and RxMake cares for:

   - creating the JCL job to compile and link the application and
   - submitting the generated job or
   - opening the ISPF editor with the generated job.

   The main highlights are:

   :-)   No more nasty JCL job hacking or Online panel clicking is
         necessary for compiling and linking REXX programs into load
         modules.

   :-)   It's the fastest and easiest way to build load modules from
         your REXX applications on OS/390.

   :-)   The makefiles are REXX programs, so you don't have to learn
         some cryptic syntax and you have absolute freedom in choosing
         the way the Makefile script is gathering the required
         parameters (-> fetch them from a database if you like...).

   :-)   Support for C/C++ main programs.
         -> RxMake will compile the C program and link it with the
            external REXX functions.
         -> Calling the external REXX functions from a C/C++ program
            seems as if it were a 'normal' function call.
         -> The CRStub extension stubs are required to exploit this
            functionality, they can be downloaded from our web pages.

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

   This software is designed for the following platforms:

      - OS/390

      -  AIX              \
      -  Linux             \
      -  Linux for S/390    >  these systems can generate the JCL job,
      -  Win32             /   but not submit it to JES.
      -  OS/2             /

   You need to have the following products installed:

      -  REXX/370 compiler & library for OS/390.

   If you want to bind C/C++ applications with external compiled REXX
   functions you also need:

      -  C/370 compiler for OS/390
      -  C->REXX extension stubs for REXX/370

=======================================================================
3)    Installation
=======================================================================

   1. After downloading the RxMake.zip package unpack the ZIP file on
      a workstation (AIX, Linux, Win32). It contains:

      -  Assembler sources:
         -  eagstc.asm     -> non recursive C/C++ -> REXX stub
         -  eagstcr.asm    ->     recursive C/C++ -> REXX stub
         -  eagstefp.asm   -> original EFPL  REXX -> REXX stub
         -  evalfree.asm   -> module to free allocated EVALBLOCKS

      -  JCL job to build the load module versions of the EAGSTC
         and EAGSTCR stubs.

      -  Samples in the subdirectory '.../samples'.

      -  Documentation - this Readme file and the samples.


=======================================================================
4)    Usage
=======================================================================

   EXEC RXMAKE <makefile_name> [SUB|EDIT]

   -  makefile_name must be given in apostrophes and include the first
      level qualifier of the data set name.
   -  'SUB'  - submits the generated job to JES.
   -  'EDIT' - opens ISPF editor loaded with the generated job.

=======================================================================
5.)   Makefile
=======================================================================

   As stated before, a RxMake makefile is a REXX program.
   It is read line by line, each one concatenated to the previous one.
   The complete program-string is then handed over to the INTERPRET
   instruction. Therefore nearly every valid REXX program that sets the
   required attributes works.
   I say 'NEARLY' because this simple concatenation doesn't take care
   of line continuations with commas and omitted end-of-statement
   semicolons, so the following 2 restrictions apply:

   - be careful NOT to forget the semicolon after each statement.

   - do NOT continue a statement on the next line with a comma ending
     the previous line - just simply write on.

   The attributes that must (+) or may (-) be set are described in the
   following sections.

   main routine attributes:
   ------------------------

      + mainRoutine.ExecDSN   =  Name of the data set (if PDS including
                                 member name) where the REXX source
                                 code can be found.

      + mainRoutine.Language  =  Language of the main program. Values:
                                 - 'REXX' and
                                 - 'C'

      + mainRoutine.Stub      =  Stub to be used for main program.
                                 There are currently 5 stubs available:
                                 CPPL     -  invoked as TSO command
                                             processor or from REXX
                                             with ADDRESS TSO.
                                 EFPL     -  invoked as REXX function
                                             or via REXX CALL stmt.
                                 CPPLEFPL -  upper both.
                                 CALLCMD  -  called via TSO CALL cmd.
                                 MVS      -  called from batch job with
                                             EXEC PGM=...
                                 NONE     -  specify this if the main
                                             routine is a C program.

      - mainRoutine.CompOpt   =  you may specify additional REXX/370
                                 compiler options. Already in effect
                                 are:
                                 NOCEXEC - do not build CEXEC.
                                 OBJECT  - do build an object module.
                                 [DLINK] - used if there are ext.
                                           references in the module.

                                 (keep in mind that some options have
                                  great impact on runtime performance,
                                  such as: TRACE, TESTHALT, ...)

      - mainRoutine.PreLinkOpt=  you may specify C/370 prelinker
                                 options. They will only be used if the
                                 main program is coded in C. Already in
                                 effect is:
                                 MAP

      - mainRoutine.LinkOpt   =  you may specify additional linkage
                                 editor options. Already in effect are:
                                 LIST, MAP, RENT, AMODE=31, RMODE=ANY

   external function attributes:
   -----------------------------

      + extFunc.0             =  x, the number of external functions.

      + extFunc.x.ExecDSN     =  name of the data set (if PDS including
                                 member name) where the REXX source
                                 code can be found.

      + extFunc.x.Recursive   =  tell RxMakMod if the external REXX
                                 functions is recursive (i.e. it calls
                                 itself). Valid values are '0' and '1'.

      - extFunc.x.CompOpt     =  you may specify additional REXX/370
                                 compiler options. Already in effect
                                 are:
                                 NOCEXEC, OBJECT, [DLINK]

      - extFunc.x.LinkOpt     =  you may specify additional linkage
                                 editor options. Already in effect are:
                                 LIST, MAP, RENT, AMODE=31, RMODE=ANY

   data set attributes:
   --------------------

      + dsn.RexxPrefix        =  this is where in your installation the
                                 REXX/370 files can be found. The given
                                 string should end with a period, since
                                 it is suffixed with 'SEAGLMD' to find
                                 the stubs and with 'SFANLMD' to find
                                 the compiler's 'REXXCOMP' module.

      + dsn.C370Prefix        =  this is where in your installation the
                                 C/370 files can be found. The given
                                 string should end with a period, since
                                 it is suffixed with 'SCBC3CMP' to find
                                 the compiler's 'CBC320PP' module.

      - dsn.CPrelink          =  the name of a PO data set, where the
                                 pre-linked load modules shall be
                                 retained - if none is specified they
                                 are thrown away at job ending. This
                                 will only be used if the main program
                                 is written in C/C++.

      - dsn.CHeaderFiles      =  the name of a PO data set, where the
                                 C/370 compiler shall search for your
                                 private header files.

      - dsn.Stubs             =  the name of a PO data set, where the
                                 stub modules can be found - if none is
                                 given the dsn.rexxPrefix'SEAGLMD' data
                                 set will be used instead.

      - dsn.Listings          =  the name of a PO data set, where the
                                 compiler listings shall be retained -
                                 if none is specified they are written
                                 to the jobs printer output (SYSOUT=*).

      - dsn.Objects           =  the name of a PO data set, where the
                                 compiled objects shall be retained -
                                 if none is specified they are thrown
                                 away at job ending.

      - dsn.LoadMods          =  the name of a PO data set, where the
                                 intermediate load modules shall be
                                 retained - if none is specified they
                                 are thrown away at job ending.

      + dsn.FinalMod          =  the name of a PO data set, where the
                                 final load module shall be written to.
                                 If you specify a member name this name
                                 will be used, else the name of the
                                 main routine is used as member name.

   JCL batch job attributes:
   -------------------------

      + job.OutputDSN         =  name of data set (if PDS including
                                 member name) to write the generated
                                 job into.

      + job.User              =  your user ID.

      + job.Name              =  the name for the JOB card.
                                 Your user ID will be used as prefix.
                                 The resulting string will be cut to
                                 8 characters.

      - job.AccountNumber     =  accounting number, if necessary.

      - job.AccountingInfo    =  accounting information, if necessary.

      - job.ProgrammersName   =  programmer's name.

      + job.Class             =  JES class for job input.

      + job.MsgClass          =  JES class for job output.

      - job.Notify            =  user ID to notify on job end, abend...

      - job.Password          =  password to protect job against
                                 alteration.

      - job.Priority          =  the priority that JES shall give the
                                 job.

      - job.Region            =  space demand for job execution.

=======================================================================
6)    Samples
=======================================================================

   There are 2 REXX-only samples   in .../samples/rexx_only
         and 7 C-REXX samples      in .../samples/c_rexx.

   In the sayab makefile the descriptions for all the attributes are
   included as comments.

   C-REXX samples:
   ---------------

      | C/370 main| REXX func | EAGSTC  | EAGSTCR |   JCL   |  MAKE   |
   ---|-----------|-----------|---------|---------|---------|---------|
    1 |  CREXX1   |  noParm   |    X    |         |  make1  |  samp1  |
   ---|-----------|-----------|---------|---------|---------|---------|
    2 |  CREXX2   |  longRet  |    X    |         |  make2  |  samp2  |
   ---|-----------|-----------|---------|---------|---------|---------|
    3 |  CREXX3   |  sayn     |         |    X    |  make3  |  samp3  |
   ---|-----------|-----------|---------|---------|---------|---------|
    4 |  CREXX4   |  longRet  |    X    |         |  make4  |  samp4  |
      |           |  sayn     |         |    X    |         |         |
   ---|-----------|-----------|---------|---------|---------|---------|
    5 |  CREXX56  |  arbArgs  |    X    |         |  make5  |  samp5  |
   ---|-----------|-----------|---------|---------|---------|---------|
    6 |  CREXX56  |  arbArgs  |         |    X    |  make6  |  samp6  |
   ---|-----------|-----------|---------|---------|---------|---------|
    7 |  CREXX7   |  reverse  |    X    |         |  make7  |  samp7  |
   ---|-----------|-----------|---------|---------|---------|---------|

   REXX-only samples:
   ------------------

      | REXX main | REXX func |   JCL    |  MAKE    |
   ---|-----------|-----------|----------|----------|
    1 |  repworld |   sayn    | repworld | repworld |
   ---|-----------|-----------|----------|----------|
    2 |  repw2    |  csayn    |  repw2   |  repw2   |
      |           |   sayn    |          |          |
   ---|-----------|-----------|----------|----------|
    3 |  sayab    |   saya    |  sayab   |  sayab   |
      |           |   sayb    |          |          |
   ---|-----------|-----------|----------|----------|

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

   -  As makefile nearly every valid REXX program that sets the required
      attributes is thinkable, BUT:
      -  line continuations with commas or
      -  omitting the end-of-statement semicolon
      will lead to error situations.

   -  The names of modules must not differ only in their eighth
      character, ie. their first 7 characters must definitely be matched
      by only one single CSECT's name in the final load module.

   -  The optional parameters EDIT and SUB are only available under
      TSO/E.

   -  Temporary data sets for copying recursive external REXX functions
      are allocated with RECFM=FB and LRECL=80. Should your input
      data set for REXX sources have other characteristics you'll
      have to edit either the generated JCL jobs or adapt the RxMake
      utility for your needs.

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

   The documentation used for developing this stubs was:

      -  IBM Compiler and Library for SAA REXX/370 - User's Guide and
         Reference                                 (SH19-8160)
      -  OS/390 V2R9.0 TSO/E REXX User's Guide     (SC28-1974)
      -  OS/390 V2R10.0 TSO/E REXX Reference       (SC28-1975)

   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!
