Welcome to version 0.05d of the Regina Rexx interpreter. 

But first, the copyright and copying conditions. The code is
'copylefted', which means that it is copyrighted, but that you are
allowed to use, copy, modify, redistribute and sell the code, under
the conditions listed in the "GNU Public License". See the file
COPYING for more information.

The source has been built and tested on several platforms. Generally,
'all' you need a Standard C compiler (i.e. ANSI C), a 'lex' program
and a 'yacc' program. In addition, your machine should be POSIX
compliant. The latest version of Regina is stored on the anonymous ftp
site flipper.pvv.unit.no (129.241.36.200), in the '/pub/regina'
directory. 

To build the interpreter:

1) Edit the Makefiles (in particular the one in the 'src' subdirectory,
   and uncomment a suitable definition of the macros CC and CEXTRA.
   You may want to make a new one if none of the existing ones fit
   your exact needs.

2) Run the command   make

3) The Makefile does not install targets. There is a make-target
   'install', which installs programs. Check the settings of macros in
   the makefile before running make for target 'install'.

4) You might want to run the documentation through the LaTeX
   textformatter.  If you don't have the 'block' and 'a4' style
   options for tex (these are not standard LaTeX options), just
   edit them out, letting the first line become:

      \documentstyle{article}

If you want to compile it for VMS, you need a lex and a yacc program.
You can get the GNU versions of these tools, or you can run the lex
and yacc on another machine, and copy the results of these programs
from that machine. 

I have built it on the following platforms:

   - gcc, lex and yacc on a Uniline 88
   - gcc, lex and yacc on Sun 3
   - c89 (unbundled), lex and yacc on Decstation 5000, under Ultrix 4.2
   - cc, lex and yacc on Irix Indigo and Onyx, under IRIX 4 and 5
   - acc (unbundled), lex and yacc on Sun Sparc, under Sunos 4.2
   - cc, lex and yacc on Decstation 3100, under OSF/1
   - c89, lex and yacc on HP 9000, under HP/UX 8.05
   - cc, lex and yacc on IBM RS6000 under AIX
   - cc, lex and yacc on Cray under UNICOS
   - cc, lex and yacc on Linux 0.99
   - cc on a VAX/VMS, getting yacc and lex output from a Sun. 
   - cc, lex and yacc on a DEC alpha running OSF/1

Read the file README.VMS to get more information about how to build
Regina on a computer running VMS, and what functionality is present in
the VMS version of Regina. In addition to VMS and Unix, this version
of Regina has also been successfully built for OS/2 and MS-DOS, using
the EMX development environment under OS/2. However, Regina does not
yet have any specific support for these systems.

If you are unable to get Regina to work on your computer, because you
don't have one or several of the programs needed to build it, you can
try to build the GNU tools on your computer. Regina will compile with
these tools (and using them is a good idea anyway). You can get them
by anonymous ftp from prep.ai.mit.edu, ugle.unit.no and several other
places. 

The areas where it is not POSIX compliant are:

   - It uses "struct timeval" and gettimeofday().  You can control
     this through the HAS_TIMEVAL option in config.h.  Comment it out
     if your machine does not eat the code.  Consequences: The
     interpreter will have a time granularity of 1 second.

   - It uses ftruncate().  If you do not have that, comment out the
     HAS_FTRUNCATE option on config.h.  Consequences: When writing to
     the middle of a file with lineout(), the file will not be
     truncated after the line written.

   - It uses putenv() to set an environment variable. While POSIX do
     have the getenv() call, it does not have a way of setting
     environment variables. Fortunately, most machines have a way of
     doing this, but you might have to link in an extra library or
     something. If you can't find a putenv() on your machine, you can
     undefine the HAS_PUTENV macro in config.h.  Consequences: Trying
     to set en environment variable will cause a syntax error

The interpreter has bugs and missing feature. I consider this release
of Regina a beta release, and I will continue to do so, until:

   - Regina is a full implementation of Rexx as described in the book:
     "The Rexx Language", by Mike Cowlishaw;

   - the most important extensions from CMS have been implemented;

   - a full implementation of the Rexx SAA API, as documented for
     OS/2, has been implemented;

   - all important extensions suggested by the ANSI Rexx committee 
     have been implemented; 
  
   - an extensive test suite which test most parts of the features
     listed above have been implemented, and Regina is able to run it
     without problems; and

   - the documentation for Regina has been completed.

(... or when I finish my studies, whatever comes first :-)

If you find bugs or incompatibilities, please send me e-mail
describing the bug. It is important that your bugreport contains:

   - Description of what equipment you used, i.e. hardware
     platform, operating system, compiler version, compiler
     options used, version of Regina etc.

   - A description of the buggy behavior (and the behavior that
     you expected to see).

   - Preferably a program that demonstrates the behavior.  The
     program should be as small as possible, preferably not more
     than 10 lines or so.

   - If you have already fixed the bug, please append a context
     diff of the changes you made to the source.

Please make sure that the bug is really a bug in the interpreter, not
just a bug in your program. And also make sure that you've got the
latest release of Regina. If possible, run your program on other REXX
interpreters to see how they behave, and check with a REXX manual if
you have access to one. Bugreports are welcome, as well as other types
of comments. You can send bugreports directly to my email address,
listed below.

There are four subdirectories.

   - The first is 'trip' which is the start of a "triptest" for a REXX
     interpreter, which is supposed to test most REXX interpreter
     features.  If enough tests are gathered in this triptest, any
     REXX interpreter that manages to run it would be fairly REXX
     compatible. Such a trip test is not a perfect way of ensuring
     compatibility, but it is far better than none. 

   - The next subdirectory is the 'demo', which contains some small
     demo programs for REXX, mainly demonstrations of special
     programming features in REXX. Also included are some common test
     programs and routines distributed on the net. Note that the
     programs in this directory are not covered by the GPL.

   - The src directory, containing the source code for Regina.

   - The 'doc' subdirectory, containing the documentation for Regina.
     Unfortunately, this documentation is not complete, nor it is
     completely correct at the moment, since I want to finish the
     coding before continuing the work in the doc.

What's new in 0.05d? Well, there are lots of bug fixes. Some features
which was previously missing have been implemented. Basically, it is
numerous small changes, and two major changes:

   - The code have been speeded up quite a bit. 

   - Large parts of the Rexx SAA API (as present in OS/2) have been
     implemented. 

   - The CMS specific built-in functions justify(), index() and find()
     is supported. 

Some of the things the interpreter does not have:

   - The documentation is far from finished. It has lower priority 
     for the moment, until I have finished the interpreter itself.

   - For the (external) commands, there is not a consistent shell in
     the background to which commands are sent.  Instead either there
     is a shell that is started up each time (ADDRESS SYSTEM), or the
     command is run directly (ADDRESS PATH and COMMAND).  This will
     be fixed ...

   - I still need to test a lot of functionality that has been
     implemented and are supposed to work. 

   - Lots of other things ...

There is a mailing list for announcements of new versions of Regina.
If you want to be on that list, send a request to be put on the list
to the address: <rexx-request@pvv.unit.no>

Anders Christensen                     e-mail: anders@solan.unit.no
Norwegian Institute for Technology
University of Trondheim, Norway
