Standards for ARexx

In order for your program to work with ARexx, it must have an ARexx interface: a software structure that allows your application to send and receive messages [to and] from ARexx.

If your application supports scripts, it should do so via ARexx. Even if your program doesn't use macros, you are urged to add an ARexx interface.

Having said that, the purpose of the rest of this chapter is simple: to give a listing of standard ARexx commands so the same commands do the same thing from program to program.

The fast-growing popularity of ARexx combined with its flexibility create, unfortunately, the likelihood of command name and function conflicts. It's frustrating to the user when the OPEN command works differently in his paint program than in his typesetting program.

Your program should support at least a minimal subset of ARexx commands. It increases the power of your program, and as a powerful and seamless standard, it's good for the platform as a whole. Applications that don't support ARexx decrease the overall power and lure of the Amiga. Average users who decide to learn ARexx will almost certainly experience frustration when they run into the brick wall of the program that doesn't support ARexx.

Once you learn how, incorporating ARexx support into your application requires about as much programming effort as supporting menus - without having to deal with the graphics. This chapter discusses which ARexx commands to support and the style in which they should be supported. For more details on the ARexx language itself refer to the Release 2 Users Manual Using the System Software.

General Description and Guidelines

ARexx is an interpreted programming language. As in BASIC, ARexx scripts can be written with any text editor and run without having to use a compiler. If an error occurs, ARexx outputs error messages indicating which line or lines are in error so the user can make changes and try again.

ARexx is unique in that an ARexx script can contain commands that are specific to ARexx as well as commands that are specific to an application. ARexx provides commands typical of most programming languages (variable manipulation, arithmetic, conditional loops, string manipulation, etc.).

Follow these general guidelines when creating your ARexx commands.

Your application should provide, through ARexx, a subset, or even a superset, of the commands available through the GUI. This refers to menu or action gadget commands such as New, Save, Save As... and Quit.

By combining ARexx commands and application-specific commands, the user can create simple or complex scripts to automate common tasks, create new functions, and integrate application software.

For the sake of consistency, your application's ARexx commands should be similar in syntax to the AmigaDOS commands. They take the form:

COMMAND [<argument1>, <argument2>...]

where COMMAND is a keyword that your application recognizes followed by a list of arguments. In many cases the arguments will be optional and your application should be set to take some default action.

As a general rule, your command set should:

Errors

ARexx scripts can be written by the everyday user or the professional programmer. Scripts must be able to handle error conditions and take some kind of action when an error occurs (ie. notify the user, prompt the user, terminate, etc.). Therefore, it is important that your application return error codes when a command cannot be performed.

The standard convention in ARexx is for application-specific commands to return error codes of zero (0) for no error, five (5) for warnings such as "Aborted by user", ten (10) for errors such as "<file> wrong type", and twenty (20) for failures such as "Couldn't open the clipboard".

Return codes are placed in ARexx's special variable called "RC" which can be checked for an manipulated in an ARexx script. For example, the user might try to save a file using the "SAVEAS" command. If the file could not be saved for any reason, it would be appropriate to return an error code of ten (10) so that the script could be terminated early, or some other action could be taken.

You may choose to support a more comprehensive set of error codes. This is acceptable but your application should still return zero (0) for no error and use return codes of less than ten (10) for warnings.

Returning Data

Some commands may return information back to ARexx. For example, a text editor or word processor might have a command that returns the string of text under the cursor. The string of text would be placed in a special ARexx variable called RESULT; the user, however, should be allowed to override this with a VAR or STEM switch in the command.

VAR = return the value.

STEM = place the value in the specified variable.

In order for result strings to be returned to ARexx, the script must use ARexx's OPTIONS RESULTS command. This command tells the application that it is OK to return result strings. Data placed in RESULT can then be copied and manipulated within an ARexx script.

Here's an example: a text editor supports a command called GETLINE that returns the line of text under the cursor. The following is a sample ARexx script that uses the GETLINE command to get the line of text under the cursor and place it in a variable called "line". Note that comments are surrounded by pairs of "/*" and "*/".

/* Example ARexx script */

OPTIONS RESULTS

'GETLINE'   /* Command telling the application to
               return the line of text under the
               cursor. */

line=RESULT /* Set the variable called "line" equal
               to ARexx's special variable called
               "RESULT". */
			

If the VAR (simple variable) or STEM (complex variable) switches are used, information should be placed into the named variable. For instance:

MYCOMMAND STEM comresult

This would place the return result in the variable named comresult. The VAR and STEM switches make it easier for applications from different vendors to operate on the same data under ARexx.

Text strings that contain records with spaces should be returned with quotes around the record. A space should separate multiple records. For example, if you were trying to return the following list of records:

Letter to John Doe
Notes on Standards
Addresses of the Stars

the information would be returned as:

"Letter to John Doe" "Notes on Standards"
"Addresses of the Stars"

When the command returns multiple records, it should allow the user to specify a stem variable to place the contents in. For example, a command that would return the names of the loaded documents in a text editor would normally return information in the RESULT field, but if the user chooses to place the information in a stem variable, he could specify:

GETATTRS DOCUMENTS STEM DocList.

which would return:

DocList.count = 3
DocList.0 = Letter to John Doe
DocList.1 = Notes on Standards
DocList.2 = Addresses of the Stars

In the above example, DocList.count contains the number of records in the array. Also note that the elements do not contain quotes around the information.

ARexx Port Naming

Part of the job of supporting ARexx is adding an ARexx port to your application - this is a software structure through which ARexx communicates with your program. Each ARexx port must have a unique name and must be in upper-case. In ARexx, a port name is derived from:

<basename>.<slot #>

In the above line, <basename> is the same name your application's executable uses (see Chapter 2), and <slot #> is the next available ARexx port slot for that application.

This ARexx port name should be displayed in the window brought up by the About menu item (along with the version of your application, etc.). The user should also have the ability to rename the port. Being able to specify the ARexx port name in the project icon's Tool Types field, or from the command line by using the PORTNAME keyword, is a good thing.

Unique port names should be given to each project started within your application and for each instance of your application. For example, a fictional word processing package named GonzoWord with a basename of GWord should have an ARexx port of GWORD.1 when thefirst document is opened. A second document running concurrently should be given the port name of GWORD.2. If the user opened the GonzoWord program again without choosing QUIT in the first instance, that third document should have a port name of GWORD.3.

Command Shell

Your application should allow the user to open a console window or command shell within your application's environment. There are two possible ways of handling this: you can provide a window that looks like a basic Shell window or one that looks like Workbench's Execute Command window.

Workbench's Execute Command window
Fig. 9.1: Workbench's Execute Command window.

Commands entered into this window would allow direct control of your application.

As with any other type of window, your application should allow to user to snapshot the placement and size of the command shell.

Fig. 9.2: A sample ARexx command shell.