INTRODUCTION

Welcome to ARexx, an implementation of the REXX language for the Amiga
computer.  ARexx is a powerful programming took, but one which by
virtue of its clean syntax and sparse vocabulary is also easy to learn
and easy to use.

1 ORGANIZATION OF THIS DOCUMENT

This document will attempt to fill the roles of User's Manual, Language
Reference, and Programmer's Guide.  The chapters that follow have been
organized to provide a gently introduction to the language.

Chapter 1, What is ARexx?, gives an overview of the ARexx language and
its implementation of the Amiga.

Chapter 2, Getting Acquainted, tells how to install ARexx on your Amiga
and presents several example programs to illustrate the features of
the language.

Chapter 3, Elements of the Language, introduces the language structure
and syntax.

Chapter 4, Instructions, describes the action statements of ARexx.

Chapter 5, Commands, describes the program statements used to
communicate with external programs.

Chapter 6, Functions, explains how functions are called and documents
the Built- In Function library.

Chapter 7, Tracing and Interrupts, describes the source level debugging
features useful for developing and testing programs.

Chapter 8, Parsing and Templates, describes the instructions used to
extract words or fields from strings.

Chapter 9, The Resident Process, describes the capabilities of the
global communications and resources manager.

Chapter 10, Interfacing to ARexx, describes how to design and implement
an interface between ARexx and an external program.

Appendix A, Error Messages, lists the error messages issued by the
interpreter.

Appendix B, Limits and Compatibility, discusses the compatibility of
ARexx with the language standard.

Appendix C, The ARexx Systems Library, documents the functions of ARexx
systems library.

Appendix D, The Support Library, documents the library of Amiga specific
functions.

Appendix E, Distribution Files, lists the files on the distribution
disk.


				1

USING THIS MANUAL

If you are new to the REXX language, or perhaps to programming
itself, you should review chapters 1 through 4 and then play with ARexx
by running some of the sample programs given in chapter 2.  Further
examples are available in the :rexx directory of the distribution
disk.

If you are already familiar with REXX you may wish to skip directly to
chapter 5, which begins to present some of the system-dependent
features of this implementation.  A summary of the compatibility of
ARexx with the language definition is contained in Appendix B.

TYPOGRAPHIC CONVENTIONS

Describing a language is sometimes difficult because of the multiple
and changing contexts involved.  To help clarify the presentation
here, a simply typographic convention has been adopted throughout the
document.  All of the terms and words specific to the REXX language, as
well as the program examples and computer input and output, have been
set in typewriter font like this.  This should help to distinguish the
language keywords and examples from the surrounding text.

2 FUTURE DIRECTIONS

ARexx, like most software products, will probably envolve somewhat over
the next few years as new features are added, old bugs are removed, and
market imperatives become more apparant.  While the core language will
probably undergo few modifications, many capabilities will be added to
the function libraries supported by ARexx.  Your comments and
suggestions for improvements to ARexx are most welcome.

The author sincerely hopes that other software developers will
consider using ARexx with their products.  The advantages of having a
rich variety of software products sharing a common user interface and
a common procedural interface cannot be overstated.  This is the
underlying promise of the Amiga's multitasking capability, and that
which most sets it apart from other inexpensive computers.

Example Programs.  One of the best ways to learn a computer language
is to study examples written by more experienced programmers.  The
ARexx distribution disk includes a few example programs in the :rexx
directory, and more programs will be added in future releases.

If you have written REXX language program(for any computer)that you
think would be of interest to a more general audience, please send it
to the author for consideration.  Programs should be of interest
either in terms of their specific funtionality or as an example of
programming technique.  Each program submitted should include an
author credit and a few lines of commentary on its intended fuction.

				2

ARexx is a high-level language useful for prototyping, software
integration, and general programming tasks.  It is an implementation of
the REXX language described by M.F.  Cowlishaw in The REXX Language:A
Practical Approach to Programming(Prentice-Hall, 1985), and follow the
language definition closely.  ARexx is particularly well suited as a
command language.  Command programs,  sometimes called "scripts" or
"macros", are widely used to extend the predefined commands of an
operating system or to customize an applications program.

As a programming language, ARexx can be useful to a wide cross section
of users.  For the novice programmer, ARexx is an easy-to-learn yet
powerful language that serves as a good introduction to programming
techniques.  Its source-level debugging facilities will help take some
of the mystery out of how programs work(or don't work, as is more
frequently the case.)

For the more sophisticated user, ARexx provides the means to build
fully integrated software packages, combining different applications
programs into an environment tailored to their needs.  A common
command language among applications that support ARexx will bring
uniformity to procedural interfaces,  much as the Amiga's Intuition
provides uniformity in the graphical interface.

Finally, for the software developer, ARexx offers a straightforward way
to build fully programmable applications programs.  Developers can
concentrate their efforts on making the basic operations of their
programs fast and efficient, and let the end user add the frills and
custom features.

1-1 LANGUAGE FEATURES

Some of the important features of the language are:

TYPELESS DATA.  Data are treated as typeless character strings.
Variables do not have to be declared before being used, and all
operations dynamically check the validity of the operands.

COMMAND INTERFACE.  ARexx programs can issue commands to external
programs that provide a suitable command interface.  Any software
package that implements the command interface is then fully
programmable using ARexx, and can be extended and customized by the end
user.

TRACING AND DEBUGGING.  ARexx includes source-level debugging
facilities that allow the programmer to see the step-by-step actions
of a program as it runs,  thereby reducing the time required to develop
and test programs.  An internal interrupt system permits special
handling of errors that would otherwise cause the program to
terminate.

				3

INTERPRETED EXECUTION.  ARexx programs are run by an interpreter, so
separate compilation and linking steps are not required.  This makes
it especially useful for prototyping and as a learning tool.

FUNCTION LIBRARIES.  External function libraries can be used to extend
the capabilities of the language or as bridges to other programs.
Libraries also allow ARexx programs to be used as "test drivers" for
software development and testing.

AUTOMATIC RESOURCE MANAGEMENT.  Internal memory allocation related to
the creation and destruction of strings and other data structures is
handled automatically.

1-2 AREXX ON THE AMIGA

ARexx was designed to run on the Amiga, and makes use of many of the
features of its multitasking operating system.  ARexx programs run as
separate tasks and may communicate with each other or with external
programs.  The interpreter follows the design guidelines expected of
well-behaved programs in a multitasking environment:  specifcally, it
uses as little memory as possible and is careful to reutrn resources
to the operating system when they are no longer needed.  Memory
requirements were minimized by implementing the entire ARexx system as
a shared library, so that only one copy of the program code must be
loaded.

1-3 FURTHER INFORMATION

The aforementioned book by M.F.  Cowlishaw is highly recommended to
those interested in further information about REXX.  It presents an
interesting discussion of the design and development of the language.

				4