@DATABASE "ARx_Intro.ag"
@VER 1.0b
@INDEX ARx_Index/MAIN
@Node MAIN "ARexxGuide | Introduction |"
@TOC ARexxGuide.guide/MAIN
@PREV ARexxGuide.guide/MAIN
   @{FG HIGHLIGHT}AN AMIGAGUIDE® TO ARexx@{FG TEXT}                 Edition: 1.0b
   by Robin Evans

   Preface
      @{" Acknowledgements   " link ACKN}   @{" References         " link REF}   @{" About the author   " link AUTHOR}
      @{" Distribution       " link DIST}

   About this guide
      @{" Navigating hints   " link NAVG}

   Intro to ARexx
      @{" Hello World!       " link HIWRLD}   @{" Why ARexx?         " link WHYREXX}
      @{" Getting it started " link STARTUP}   @{" Writing programs   " link WRITING}
      @{" Running a script   " link RUNAREXX}



                      Copyright © 1993, Robin Evans.

    This guide is @{" shareware " link ArexxGuide.guide/REG}. If you find it useful, please register.
@REM 1.0b: Fixed some typos

@EndNode
@Node ACKN "ARexxGuide | ACKNOWLEDGEMENTS (1 of 1)"
@Next MAIN
@Prev MAIN
I thank the many people who have written ARexx scripts over the years and
released them publicly so that all of us could study and learn, to the
folks on GEnie for asking challenging questions about ARexx and providing
insightful answers, to Richard Stockton and Gramma's BBS -- not only one of the
best sources of information on ARexx, but also one of the most incredible
applications of the language -- and to those who provide fascinating
discussions on Usenet's comp.lang.rexx of the many flavors of REXX.

The development of this guide was aided greatly by Ed Patterson who had
the patience to look through rough and early versions and provided
invaluable suggestions. Thanks to Ron Adam for suggesting the
header/footer method used to identify nodes. Thanks to Larry Shanahan for
extensive link-testing and for raising several Multiview-compatibility
issues.

A special thanks to Dean Adams for not only registering, but sending
extensive errata reports after doing so.

Trademarks:

   Amiga, AmigaGuide, AmigaDOS, AmigaOS, Amiga Workbench, and Intuition
   are trademarks of Commodore-Amiga, Inc.

   ARexx and WShell are a trademarks of Wishful Thinking, Inc.

   GEnie is a trademark of General Electric Information Services, Inc.

Next, Prev, & Contents: Introduction contents

@EndNode
@Node REF "ARexxGuide | REFERENCES (1 of 1)"
@Next MAIN
@Prev MAIN
@REM Hawes, William S.Cowlishaw, M.FZamara, ChrisSullivan, NickGoldberg, GabrielSmith, Phillip H. IIIWienstein, Marvin
ARexx User's Reference Manual, The REXX Language for the Amiga
   by William S. Hawes
   Wishful Thinking Development, 1987 (with disk-based updates)

The REXX Language, A Practical Approach to Programming
   by M.F. Cowlishaw
      Prentice-Hall, First edition: 1985

Using ARexx on the Amiga
   by Chris Zamara & Nick Sullivan
      Abacus, 1992


The REXX Handbook
   edited by Gabriel Goldberg & Philip H. Smith III
      McGraw-Hill, 1992

Extending ARexx (and other articles)
   by Marvin Weinstein
      AmigaWorld Tech Journal, 1991-1992

Next, Prev, & Contents: Introduction contents

@EndNode

@Node AUTHOR "ARexxGuide | Author (1 of 1 [fortunately] )"
@NEXT MAIN
@PREV MAIN

      No, the only perfect solution would have been the sixteen
      pockets, symmetrically disposed, each one with its stone. Then
      I would have needed neither to number nor to think, but
      merely, as I sucked a given stone, to move on the fifteen
      others, each to the next pocket, a delicate business
      admittedly, but within my power, and to call always on the
      same pocket when I felt like a suck.

                     --- Samuel Beckett, Molloy

Mr. (as in Robin Hood, in case you were wondering) Evans has, in his
checkered past, sprayed asbestos onto the ceilings of mobile homes and
designed databases for lawyers (two activities that seem somehow related).
Between those periods, he edited a biweekly community newspaper in Seattle
and typeset enough headlines and stories on a CompuGraphic EditWriter 7500
to realize that computers could be nifty things after all.

He was a serious enough philosophy major in college (a time when he
thought that computers just might be evil) that he can still give a
passable definition of "epistomology" or "ontology."

He moved up from a C-64 to his first Amiga (a 500) in 1988 and bought
ARexx shortly thereafter. When he discovered what could be done with ARexx
by itself and ARexx with TxEd, he was hooked.

Evans writes occasional articles on ARexx for ViewPort, GEnie's monthly
online Amiga magazine. He teaches a class in REXX/ARexx at CALC, the
online college available on GEnie.

Next, Prev & Contents: INTRODUCTION

@EndNode
@Node DIST "ARexxGuide | Distribution restrictions (1 of 1)"
@NEXT MAIN
@PREV MAIN
The files in this archive are copyright 1993, Robin Evans and may be
distributed only in the original form and only under the conditions
outlined below.

The archive may be distributed in its original form on any non-commercial
media, on local and national computer networks, on Aminet distribution
channels (including the Walnut Creek CD-ROM), and on the Fish Disks.

Distribution of the copyrighted material in this archive is prohibited if
the contents of the original archive are in any way altered.

Rights are reserved for other forms of distribution of this archive or of
its contents individually, including distribution with commercial products
or distribution of printed versions of any copyrighted file contained in
the archive. Contact the author for further information.

               Robin Evans                   22 Oct 1993

                  on GEnie:
                     R.EVANS6   on GEnie

                  from Internet:
                     robin@halcyon.com
                     r.evans6@genie.geis.com

                  by phone:
                     (206) 682-7077


@EndNode

@Node HIWRLD "ARexxGuide | Introduction (1 of 5) | THE FIRST PROGRAM"
@Prev MAIN
It has become a @{" mantra " link ArexxGuide.guide/GLOSSARY 53} -- two simple words that have been repeated so
often in so many programming languages that they seem to have become an
incantation. It is the First Program, the Foundation.

Let us not delay. Here it is:

      /**/
      SAY 'Hello, world.'

That is an ARexx program, total and complete. The first line ( a
@{" comment " link ARx_Elements.ag/COMMENT}) is vital, but doesn't do anything. The second line, though --
that will cause ARexx to output to the current shell the words of the
mantra.

In the jargon of ARexx, the second line is an @{" instruction " link ARx_Elements3.ag/INSTRUCTION}; @{" SAY " link ARx_Instr3.ag/SAY} is a
@{" keyword " link ArexxGuide.guide/GLOSSARY 41}; the quoted words form a @{" string " link ARx_Elements2.ag/STRINGEXPR}. The jargon is useful and the
reader who has been pressing buttons has discovered that it is both used
extensively and explained at length elsewhere in this guide, but the
jargon used to define the language is not the heart of ARexx. The program
is. That mantra -- or, rather, the means used to produce the mantra -- is
the heart of the language.

Let us repeat it for good luck:

      /**/
     @{" DO 5  " link ARx_Instr.ag/DO}
         SAY 'Hello, world.'
      END

There we have a @{" control structure " link ArexxGuide.guide/GLOSSARY 10} that produces an iterative @{" loop " link ArexxGuide.guide/GLOSSARY 50}.
What is important, though, is what it does: it repeats 5 times an
instruction that is written out only once. ARexx offers a wealth of such
control structures.

This guide seeks to explain the elements of the language, not because the
jargon used to describe such things has any importance in its own right,
but because through understanding how the language works the programmer
will be better able to use the language to do just what she wants.

Next: WHY AREXX | Prev: Introduction | Contents: Introduction

@EndNode

@Node WHYREXX "ARexxGuide | Introduction (2 of 5) | WHY AREXX?"
Why spend time learning a programming language like ARexx? For one thing,
it's easy. REXX -- the language from which ARexx was born -- was designed
to be easily accessible to non-programmers while still providing the power
and structure expected by the seasoned programmer.

ARexx on the Amiga can make the machine more powerful and more
personalized, not just through its own resources as a programming
language, but also through its facilities that can be used to control
other programs.

Most commercial productivity programs for the Amiga use ARexx to add
features to the program. The heavyweight image-processing tools make
extensive use of ARexx as do the two major desktop publishing programs.
Most word processors available use ARexx as their macro language.

ARexx does more than just replace the often-bizarre syntax of macro
languages. It also allows different programs to communicate with one
another. For instance, a bitmap picture in Professional Page can be sent
to ADPro for manipulation and reinserted in Pro Page by simply choosing
the name of an ARexx script in PPage. The PPage script then sends the
necessary commands to ADPro to load the image, and could even be made to
begin an automatic processing operation in ADPro. (Similar tasks could be
performed with ImageMaster or ImageFX as well as with version 3.0 of
Pagestream.)

ARexx itself doesn't know anything about anim files or iff files since the
language was developed over a decade ago on an IBM mainframe that didn't
have such wonderful things. It can, nonetheless, be used to control the
creation of an animation in a program that does know about iff and anims.

Many PD and shareware programs provide ARexx support as well. EdPlayer,
for example, is a wonderful MED/MOD player. It works fine without ARexx,
but becomes more powerful when combined with ARexx. A list of chosen mods
can be saved for later playback, but only through ARexx. An ARexx script
available in some electronic file libraries will randomly choose mod files
in a specified directory and play them using EdPlayer.

From the time ARexx was introduced, text editors have led the way as
innovative ARexx implementations. With the help of ARexx and a terminal
program that also communicates via the language, a text editor like
TurboText or CED can become a complete text engine, serving as a
customized front-end for any communications service.

Next: GETTING STARTED | Prev: Hi world | Contents: Introduction @endnode

@EndNode
@Node STARTUP " ARexxGuide | Introduction (3 of 5) | GETTING STARTED"
By themselves, ARexx scripts are merely collections of text that are
meaningless to the Amiga. Some computer languages sift through the text
written by the programmer (called 'source code') and translate it into a
form understandable by the computer just once. The source code is
'compiled' once by a program that reads the text and outputs an executable
program. (A compiler is available for ARexx, but is not covered in this
guide.)

ARexx, on the other hand, translates a script's source code each time it
is executed. The script is interpreted by another program, one that
understands the meaning of ARexx @{" tokens " link ARx_Elements.ag/TOKEN}, @{" expressions " link ARx_Elements2.ag/EXPRESSION}, and @{" clauses " link ARx_Elements3.ag/CLAUSE}
and is able to translate them into the computer language understood by the
Amiga.

That @{" interpreter " link ArexxGuide.guide/GLOSSARY 27} program is @{" RexxMast " link ARx_Cmd.ag/REXXMAST}. It is located in the sys:System
drawer on standard Workbench disks (for versions 2.0+ of the OS). The
interpreter must be running before ARexx scripts can be run.

@{FG HIGHLIGHT}STORING AREXX FILES:@{FG TEXT}    ARexx looks for files specified by the @{" RX " link ARx_Cmd.ag/RX}
                        command in a directory called { REXX: }. Each user
should decide where on the system ARexx files will be stored and then add
to the user-startup the following line:

   assign REXX: <script location>

In its manuals, Commodore recommends assigning REXX: to the S: directory,
which is where standard DOS scripts are located, but that could become
confusing to those who use ARexx frequently. The REXX: directory can
easily be filled with dozens of files. Many application programs (this
guide among them) now include large collections of scripts (sometimes with
unique file extensions) to be added to the REXX: directory. That can
quickly become overwhelming if they are mixed up with the files in S:.

It strikes this writer as more useful to devote a new directory to REXX:
and leave S: for DOS scripts. The following might, therefore, be a useful
assign statement:

   assign REXX: sys:rexx

Next: WRITING | Prev: Why ARexx | Contents: Introduction

@EndNode

@Node WRITING " ARexxGuide | Introduction (4 of 5) | WHERE TO WRITE PROGRAMS"
ARexx does not supply an 'environment' in which scripts must be written.
Any text editor will do. The script must begin with a @{" comment " link ARx_Elements.ag/COMMENT}, and must
follow the basic rules that are the subject of this guide. That's it.

You don't need to learn how to work the menus and requesters in a new
program, since ARexx itself has none of those. Just start your trusted
editor and type. It is even possible to use a word processor to write
scripts, but care must be taken in such an environment. First of all, the
script will have to be saved as ASCII text since most word processors add
formatting codes to documents -- codes that would be confusing to ARexx.

Another danger of word processors is their treatment of text lines. Text
editors usually allow a line to be as long as necessary -- extending past
the edge of the window if necessary. Word-processors, in contrast, wrap
lines to fit within a defined column width. The problem in programming is
that a line is significant. A long line of code can be divided into
several lines in ARexx, but each line must end with a special code (the
@{" comma continuation character " link ARx_Elements.ag/COMMA}) to indicate that condition.

Once the script is written, it can be saved under nearly any name. The
standard convention, though, is to save ARexx scripts that are meant to be
executed from the shell with a filename extension of '.rexx'. ARexx will
run such a script using the @{" RX " link ARx_Cmd.ag/RX} command even if its name is entered
without the extension.

ARexx scripts meant to be called as macros from an application program are
usually given unique extensions determined by the developer of the
application.

Next: RUNNING PROGRAMS | Prev: Startup | Contents: Introduction

@EndNode

@Node RUNAREXX " ARexxGuide | Introduction (5 of 5) | RUNNING YOUR PROGRAMS"
The ARexx distribution -- both the commercial version and that included
with the operating system -- includes a utility program called @{" RX " link ARx_Cmd.ag/RX} that
has one task in life: to launch ARexx scripts from the Amiga shell or from
an icon in much the way that the command EXECUTE launches DOS scripts.

One of the example scripts that was installed in the rexx: directory by
this guide's installation script is called 'ARx_Cmpr.rexx' To run that
script, the following command can be typed in the shell:

   RX arx_cmpr

If the script is located in the rexx: directory, ARexx will find it
there, even if rexx: is not included in the system's command search path.
Because the file extension '.rexx' is the ARexx standard, it need not be
included.

For frequently-used ARexx scripts, an entry in the alias list of the
User-Startup file can be helpful. If the script is saved as
'rexx:DoAlottaStuff.rexx', then the following will make it more easily
accessible from the shell:

   alias DoStuff "rx DoAlottaStuff []"

Once the alias is entered in the startup file, the shorter name can be
used to launch the script.

Another, somewhat more complex way to start an ARexx script, is to treat
it like a DOS script file. The DOS PROTECT command can be used to set what
is called the 'script bit' for a file. When that bit is set, AmigaDOS
recognizes the file as something that may be executed. If the file begins
with an ARexx comment line, then AmigaDOS will launch it as an ARexx
script.

This is the command to set the script bit:

   PROTECT rexx:arx_cmpr.rexx +s

Once that bit is set, the rexx: directory must be added to the command
search path with a line similar to the following (which should, ideally,
be included in the file 's:user-startup'):

   PATH rexx: add

With those two tasks accomplished, the script 'arx_cmpr.rexx' can be
started by entering is full name (including the extension) on the shell.
The need to include the extension along with the file name means that
this method doesn't save typing over using the RX command. A quick fix,
which is possible for some files, is to store them in the rexx: directory
without an extension.

That won't work in all cases, however. The arx_cmpr file is one of those
cases. It is called by its full name from within this guide as an
external function, so the extension is significant.

Next: WHAT TO WRITE | Prev: WRITING | Contents: Introduction

@EndNode

@Node WHATWRITE " ARexxGuide | Introduction (6 of 5) | WHAT TO WRITE"
@NEXT MAIN
It is beyond the scope of this guide to tell the user what to write. Once
one has learned how to write scripts in ARexx, the 'what?' question will
answer itself. Most people who have mastered ARexx find that there are too
many ideas about what to write and not enough time to write.

The information presented in this guide is meant to help users master the
intricacies of ARexx, but it may be overwhelming to a new user. One
approach that might be helpful is to look first at the @{" Tutorial " link ArexxGuide.guide/TUTOR} section.
Even if the script presented there are not useful, it can be helpful to
see instructions, assignments, and functions used in context.

It is also useful to study ARexx scripts written by others. Many scripts
are now available on networks and public-domain disks.

Next: Introduction | Prev: RUNNING PROGRAMS | Contents: Introduction

@EndNode

@Node NAVG " ARexxGuide | Introduction ( of ) | Navigation"
@NEXT MAIN
@PREV MAIN
The three most important keys in this guide are the -Browse Forward- key,
the -Contents- key, and the mouse button or return key that chooses link
points.

     -- @{FG HIGHLIGHT}Press -Help- for general information about AmigaGuide keys@{FG TEXT} --

The browse keys let you move from one node to the next. The contents key
will bring you back to the closest in a nested series of Contents pages.
Some of those pages feature an overall explanation of the subject; some of
the contents pages consist of little more than links to other nodes in the
document.

Pressing the Contents key repeatedly will bring you back to the main
contents page of the document 'ARexxGuide.guide'

Nodes are attached to one another in this guide in a way that makes some
of them invisible when using only the Browse keys.

         1. Node name 1
          | a. subnode
          | b. subnode
          |  | b1. sub-subnode
          |  +-b2. sub-subnode
          +-c. subnode
         2. Node name 2
          | a. subnode
          | b. subnode
          | c. subnode
          | d. subnode
          +-e. subnode
         3. Node name 3

Nodes listed in the same column are directly accessible with the browse
keys. Pressing -Browse Forward- from node 1 will move you to node 2 and
from there to node 3.

One must press a link button to get from node 1 to node 1a, but once in
node 1a the -Browse Forward- key will move you to node 1b and through the
other subnodes of that level.

The lines extending from node 1c back up to 1 indicate that the contents
page for all of the subnodes of 1 is node 1 itself. Pressing -Browse
Forward- from node 1c. will also move you back to node 1.

@{FG HIGHLIGHT}A NOTE ABOUT LINK-SURFING:@{FG TEXT} Using a hypertext document is more like
                             reading a newspaper than it is like reading a
book. Just as it's possible to get lost in a newspaper when one has
flipped back the section covers to follow a story's "jump" to the inside
pages, so too, it's easy to get lost when following the links in a
hypertext document.

The best thing to do with a newspaper is to fold back the sections to
their front pages, rearranging the paper in its original form. So too,
it's often best to move back to the beginning when jumping through links
in a hypertext document. The -Contents- key allows you to rearrange each
section so that its front page is on the front.

Some versions of AmigaGuide include a 'Bookmark' feature in the
'Navigation' menu. Setting the bookmark will let you quickly jump back to
your starting point after investigating a few of the links.

A new window can be opened for any link by shift-selecting the link point.
Links identified as "NOTE:" on the link button and those identified only
with a " * " will always open a new window.

Any open window (including the main one) can be closed immediately by
pressing the Esc key.


@EndNode