AmigaOS Manual: ARexx Getting Started

This chapter shows you how to:

• Start ARexx
• Save Programs
• Store Programs
• Use sample programs

Starting ARexx

To start using ARexx, you activate the RexxMast program. The RexxMast program is started automatically or manually. Each time ARexx is started or stopped, a text message appears.

To Start ARexx Automatically

There are two methods to start ARexx automatically: placing the RexxMast icon in the WBStartup drawer or editing the S:User-Startup file.

To place RexxMast in the WBStartup drawer:

1. Open the System drawer.
2. Drag the RexxMast icon over the WBStartup drawer.
3. Reboot your Amiga.

To edit the S:User-Startup file:

1. Open a text editor.
2. Open the S:User-Startup file.
3. Enter REXXMAST >NIL:
4. Save the file.
5. Reboot your Amiga.

To Start ARexx Manually

There are two ways to start RexxMast manually: double-click on the RexxMast icon in Workbench or start it from the Shell. Floppy-based system users can save disk space by starting ARexx only when necessary.

To start RexxMast from Workbench:

1. Open the System Drawer.
2. Double-click on the RexxMast icon.

To start RexxMast from the Shell:

1. Open a Shell.
2. Type REXXMAST >NIL: and press Enter.

About ARexx Programs

ARexx programs are usually stored in the REXX: directory (which is generally assigned to the SYS:S directory). Although programs can be stored in any directory, storing them in REXX: has several advantages:

• You can run the program without having to type the complete path.
• All of your ARexx programs will be in the same place.
• Most applications search for ARexx programs in REXX:.

Just as you can store an ARexx program anywhere, you can also name it anything you choose. However, adopting a simple naming convention will make program management much easier. Programs run from the Shell should have a .rexx extension to distinguish them from files run from other applications.

Running ARexx Programs

The RX command is used to run an ARexx program. If a complete path is included with the program name, only that directory is searched for the program. If no path is included, the current directory and REXX: are checked.

As long as your programs is stored in the REXX: directory, you do not need to include the .rexx extension when specifying your program name. In other words, typing:

RX Program.rexx

is the same as:

RX Program

A short program can be entered directly at the command line by enclosing the program line in double-quotes. For example, the following program will send five files named myfile.1 through myfile.5 to the printer.

RX "DO i=1 to 5;
ADDRESS command `copy myfile.' | | i `prt:'; END"

When an application is ARexx-compatible, you can run ARexx programs from within the application by choosing a menu item or by specifying command options. Refer to the application's documentation for more information.

ARexx programs can be run from the Workbench by creating a tool or project icon for the program. You must specify the RX command as the Default Tool for the icon. In the icon's Information window, enter:

Default Tool: SYS:Rexxc/RX

When the icon is opened, RX starts RexxMast (if it is not already running). It executes the file associated with the icon as an ARexx program.

ARexx accepts two Tool Types: Console, to specify a window, and CMD, to specify a command string. You enter these Tool Types in the project icon's Information window as:

Console=CON:0/0/640/200/Example/Close
CMD=rexxprogram

Program Examples

The following examples illustrate how to use ARexx to display text strings on your screen, to perform calculations, and to activate the error checking feature.

Programs can be entered into any text editor, such as ED or MEmacs, or a word processor. Save your program as an ASCII file if you use a word processor. ARexx supports the extended ASCII character set (Å, Æ, ß). These extended characters are recognized as ordinary printing characters and will be mapped from lowercase to uppercase.

The examples also illustrate the use of some basic ARexx syntax requirements such as:

• Comment lines
• Spacing rules
• Case-sensitivity
• Use of single and double quotes

Each ARexx program consists of a comment line that describes the program and an instruction that displays text on the console. ARexx programs must always begin with a comment line. The initial (slash asterisk) /* balanced with an ending (asterisk slash) */ tells the RexxMast interpreter that it has found an ARexx program. Without the /* and the *\, RexxMast will not view the file as an ARexx program. Once it begins executing the program, ARexx ignores any additional comment lines within the file. However, comment lines are extremely useful when reading the program. They can help organize and make sense of a program.

Amiga.rexx

This program shows how to use SAY in a set of instructions to display text strings on the screen. Instructions are language statements that denote a certain action to be performed. Each statement always begins with a symbol. In the following example, the symbol is SAY. (Symbols are always translated to uppercase letters when the program is run.) Following SAY is an example of a string. A string is a series of characters surrounded by single quotes (`) or double quotes (").

Program 1. Amiga.rexx

/*A simple program*/
SAY `Amiga. The Computer For the Creative Mind.'

Enter the above program, and save it as REXX:Amiga.rexx . To run the program, open a Shell window and type:

RX Amiga

Although the full path and program name is Rexx:Amiga.rexx, you do not need to type the REXX: directory name or the .rexx extension if the program has been saved in the REXX: directory.

You should see the following text in your Shell window:

Amiga. The Computer for the Creative Mind.

Age.rexx

This program displays a prompt for input and then reads entered information.

Program 2. Age.rexx

/*Calculate age in days*/
SAY `Please enter your age:'
PULL age
SAY `You are about' age*365 `days old.'

Save this program as REXX:Age.rexx and run it with the command:

RX age

This program begins with a comment line that describes what the program will do. All ARexx programs begin with a comment. The SAY instruction displays a request for input on the console.

The PULL instruction reads a line of input from the user, which in this case is the user's age. PULL takes the input, converts it to uppercase letters, and stores it in a variable. Variables are symbols which may be assigned a value. Choose descriptive variable names. This example uses the variable name "age" to hold the entered number.

The final line multiplies the variable "age" by 365 and issues the SAY instruction to display the result. The "age" variable did not have to be declared as a number because its value was checked when it was used in the expression. This is an example of typeless data. To see what would happen if age was not a number, try running the program again with a non-numeric entry for the age. The resulting error message shows the line number and type of error that occurred.

Calc.rexx

This program introduces the DO instruction, which repeats the execution of program statements. It also illustrates the exponentiation operator ( ** ). Enter this program and save it as REXX:Calc.rexx. To run the program, use the " RX calc " command.

Program 3. Calc.rexx

/*Calculate some squares and cubes.*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
SAY i i**2 i**3 /*Perform calculations*/
END /*End of loop*/
SAY `All done.'

The DO instruction repeatedly executes the statements between the DO and END instructions. The variable " i " is the index variable for the loop and is incremented by 1 for each iteration (repetition). The number following the symbol TO is the limit for the DO instruction and could have been a variable or a full expression rather than just the constant 10.

Generally, ARexx programs use single spacing between alphanumeric characters. In Program 3, however, spacing is closed up between the exponentiation characters ( ** ) and the variables ( i , and 2, i and 3).

The statements within the loop have been indented. This is not required by the language, but it makes the program more readable, because you can easily visualize where the loop starts and stops.

Even.rexx

The IF instruction allows statements to be conditionally executed. In this example, the numbers from 1 to 10 are classified as odd or even by dividing them by 2 and then checking the remainder. The // arithmetic operator calculates the remainder after a division operation.

Program 4. Even.rexx

/*Even or odd?*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
IF 1 // 2 = 0 THEN type = `even'
ELSE type = `odd'
SAY i `is' type
END /*End loop*/

The IF line states that if the remainder of the division of the variable " i " by 2 equals 0, then set the variable " type " to even. If the remainder is not 0, the program will skip over the THEN branch and execute the ELSE branch, setting variable " type " to odd.