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 can be 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: add RexxMast to the WBStartup Prefs window or edit the S:User-Startup file.

To place RexxMast in the WBStartup Prefs list:

1. Open the Prefs drawer.
2. Open the WBStartup prefs.
3. Click the "Add" button.
4. Select SYS:System/RexxMast in the requester that pops up
5. Click on "Save"
6. Reboot your Amiga.

The command to start RexxMast should already be in the S:Startup-Sequence file. If the command has been removed from S:Startup-Sequence, we suggest that you add it to the S:User-Startup file. To edit the S:User-Startup file:

1. Open a text editor like Notepad.
2. Open the S:User-Startup file.
3. Enter SYS:System/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.

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/ARexx 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. The "Rx" may be in any case, for example, "RX", "rx" and "Rx" will all work the same.

As long as your program 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:C/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

Using ARexx Interactively

You can use ARexx interactively with a short ARexx program. Open a Shell window and enter the following line:

rx "do forever;parse pull input;interpret input;end"

As a result cursor moves at the beginning of the next line and program waits for you to enter an ARexx command. You can type any command and it will be executed once you press Enter. To leave the interactive command mode, type exit and press Enter.

The interactive command mode can be used for testing and controlling programs which have ARexx ports. As an example you can command Workbench to open its "About..." requester as follows.

In the Shell window start the interactive command mode:

rx "do forever;parse pull input;interpret input;end"

Tell ARexx to send messages to Workbench's ARexx port (WORKBENCH):

address workbench

Ask Workbench to display its "About..." requester by sending the following message:

menu window root invoke workbench.about

To leave the interactive mode, enter

exit

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 Notepad 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) /* matched 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.

Square.rexx

This example introduces the concept of a function, a group of statements executed by mentioning the function name in a suitable context. Functions allow you to build large complex programs from smaller modules. Functions also permit the same code for similar operations in a different program.

Functions are specified in an expression as a name followed by an open parenthesis. (There is no space between the name and the parenthesis.) One or more expressions, called arguments, may follow the parenthesis. The last argument must be followed by a closing parenthesis. These arguments pass information to the function for processing.

Program 5. Square.rexx

/* Defining and calling a function. */
 
DO i = 1 TO 5
   SAY i square( i ) /* Call the "square" function */
END
 
EXIT
 
square: /* Function name */
   ARG x /* Get the argument */
RETURN x**2 /*Square it and return*/

Starting with DO and ending with END , a loop is set up with an index variable "i", that will increment by 1. The loop will iterate (repeat) five times. The loop contains an expression that calls the function "square" when the expression is evaluated. The function's result is displayed using the SAY instruction.

The function "square", defined by the ARG and RETURN instructions, calculates the squared values. ARG retrieves the value of the argument string "i" and RETURN passes the function's result back to the SAY instruction.

Once the function is called by the loop, the program looks for the function name "square", retrieves the argument "i", performs a calculation, and returns to the line within the DO/END loop. The EXIT instruction ends the program after the final loop.

Results.rexx

The TRACE instruction activates ARexx's error checking feature.

Program 6. Results.rexx

/* Demonstrate "results" tracing */
TRACE results
 
sum = 0 ; sumsq = 0;
DO i = 1 TO 5
   sum = sum + 1
   sumsq = sumsq + i**2
END
 
SAY 'sum=' sum 'sumsq=' sumsq

The console displays the executed source lines, each pass through the DO/END loop, and the expression's final results. Removing the TRACE instruction, would display only the final result: sum = 15 sumsq = 55 .

Grades.rexx

This program calculates the final grade for a given student based on four essay grades and a class participation grade. The average of Essay 1 and Essay 2 is worth 30%, the average of Essay 3 and Essay 4 is worth 45%, and participation is worth 25% of the final grade.

Once a final grade is displayed, an option to continue with another calculation is presented. The response is "PULLed" and if it does not equal "Q" (quit), the loop continues. If the response equals "Q" , the program quits the loop and exits.

Program 7. Grades.rexx

/* Grading program */
SAY "Hallo, I will calculate your grades for you."
 
Response = 0
DO while response ~ = "Q" /* Loop while response isn't Q */
   SAY "Please enter all grades for the student."
   SAY "Essay 1:"
   PULL es1
 
   SAY "Essay 2:"
   PULL es2
 
   SAY "Essay 3:"
   PULL es3
 
   SAY "Essay 4:"
   PULL es4
 
   SAY "Participation:"
   PULL p
 
   Final = ( ( ( es1 + es2 ) / 2 * .3 ) + ( ( es3 + es4 ) / 2 * .45 ) + ( p * .25 ) )
   SAY "Your final grade for this student is " Final
 
   SAY "Would you like to continue? (Q for quit.)"
   PULL response
END
 
EXIT