Previous Next Chapter

The Command Interface

The ARexx command interface is a public message port. ARexx compatible applications must have this message port. ARexx programs issue commands by placing the command string in a message packet and sending the packet to the host's message port. The program suspends operation while the host processes the commands and resumes when the message packet returns.

The Host Address

ARexx maintains two implicit host addresses, a current and a previous value, as part of the program's storage environment. These values can be changed at any time using the ADDRESS instruction (or its synonym, SHELL). The current host address can be inspected with the ADDRESS() built-in function. The default host address string is REXX, but this can be overridden when a program is invoked. Most host applications will supply the name of their public port when they invoke a macro program, so that the macro can automatically issue commands back to the host.

One special host address is recognized. The string COMMAND indicates that the macro should be issued directly to AmigaDOS. All other host addresses are assumed to refer to a public message port. An attempts to send a command to a nonexistent message port will generate the syntax error "Host environment not found".

Program 9 shows the interaction between ARexx and the AmigaDOS editor, ED. The program sees if ED is running, determines the name of the message port, and sets up some stem variables.

Program 9. ED-status.rexx

/*Prints status of ED. ED must be running before this program is started. ED ports are named `Ed', `Ed_1', `Ed_2', and so on.*/
DEFAULT_ED = "Ed "/*This name is case sensitive*/
/*Procedure to follow if ED isn't running, or if only a second (or later) instance of ED is running.*/
DO WHILE ~ SHOW (`p',DEFAULT_ED) /*Look for port*/
SAY "Cannot find port named" DEFAULT_ED
SAY "Available ports:"
SAY SHOW (`P') `0a'X
SAY "Enter different name for port, or QUIT to quit "/*Let user choose port if we can't find it*/
DEFAULT_ED = READLN(stdout)IF STRIP(UPPER(DEFAULT_ED)) = `QUIT' then exit 10 /*Let user quit*/
END
SAY "Using ED port" DEFAULT_ED
/*Now that port is found, have ARexx address it.*/
ADDRESS VALUE DEFAULT_ED
/* Set up some useful stem variables*/
STEM.0 = 15 /*Number of ED ARexx variables*/
STEM.1 = `LEFT' /*Left margin (SL)*/
STEM.2 = `RIGHT' /*Right margin (SR)*/
STEM.3 = `TABSTOP' /*Tab stop setting (ST)*/
STEM.4 = `LMAX' /*Max visible line on screen*/
STEM.5 = `WIDTH' /*Width of screen in chars*/
STEM.6 = `X' /*Physical X pos. on screen-from 1*/
STEM.7 = `Y' /*Physical Y pos. on screen-from 1*/
STEM.8 = `BASE' /*Window base*/
/*Base is 0 unless screen is shifted right)*/
STEM.9 = `EXTEND' /*Extended margin value (EX)*/
STEM.10 = `FORCECASE' /*Case sensitivity flag*/
STEM.11 = `LINE' /*Current line number*/
STEM.12 = `FILENAME' /*File being edited*/
STEM.13 = `CURRENT' /*Text of current line*/
STEM.14 = `LASTCMD' /*Last extended command*/
STEM.15 = `SEARCH' /*Last search string*/
/*Ask ED to put values into stem variable `STEM.'*/
`RV' `/STEM/' /*RV is an ED command used to send into from ED to ARexx*/
/*STEM.1 is LEFT, and STEM.LEFT now holds a value from ED. Here is a way to print that information.*/

DO i = 1 to STEM.0
ED_VAR = STEM.1
SAY STEM.1 "=" STEM.ED_VAR /*Print ED variable/value*/
END

Creating a Macro

ARexx can be used to write programs for any host application that includes a compatible command interface. Some application programs are designed with an embedded macro language and may include many pre-defined macro commands.

Check your macro program for "shortcut" commands. Some programs may include powerful functions that were implemented specifically for use in macro programs.

The interpretation of the received commands depends entirely on the host application. In the simplest case, the command strings will correspond exactly to commands that could be entered directly by a user. For example, positional control (up/down) commands for a text editor would probably have identical interpretations. Other commands may be valid only when issued from a macro program. A command to simulate a menu operation would probably not be entered by the user. In Program 10, the ARexx program is called by ED to transpose two characters.

Program 10. Transpose.rexx

/*Given string `123', if cursor is on 3, macro converts string to `213'.*/
HOST = ADDRESS() /*Find out which ED called us*/
ADDRESS VALUE HOST /*. . . and talk to it.*/
`rv' `/CURR/' /*Have ED put info in stem CURR*/
/*We'll need two pieces of informations:*/
currpos = CURR.X /*Position of cursor on line*/
currling = CURR.CURRENT /*Contents of current line*/
IF (currpos >2) /*Must work on current line*/
THEN currpos = currpos - 1
ELSE DO /*Report error and exit*/
`sm /Cursor must be at pos. 2 or more to the right/'
EXIT 10
END

/*Need to reverse the CURRPOSth and CURRPOSth-1 chars and replace the current line with the new one.*/
DROP CURR. /*STEM variable CURR is no longer needed; save some memory*/
`d' /*Tell ED to delete current line*/
currlin = swapch (currpos,currlin) /*Swap 2 chars*/
`i /'| |currlin| |'/ /*Insert modified line*/
DO i = 1 to currpos /*Place cursor back at start*/
`cr' /*ED's `cursor right' command*/
END
EXIT /*All done*/
/*Function to swap two characters*/
swapch: procedure
PARSE ARG cpos,clin
chl = substr (clin, cpos, 1) /*Get character*/
clin = delstr (clin, cpos, 1) /*Delete it from string*/
clin = insert (chl,clin,cpos-2,1) /*Insert to create transposition*/
RETURN clin /*Return modified string*/

To execute this example from ED, press ESC then enter:

RX "transpose.rexx"

You can also assign this string to a function key.

Return Codes

After it finishes processing a command, the host replies with a return code to indicate the status of the command. The documentation for the host application should describe the possible return codes for each command. These codes can be used to determine whether the operation performed by the command was successful.

This return code is placed in the ARexx special variable RC so that it can be examined by the macro. A value of zero means that the command was successful. A return of a positive integer indicates an error condition. The higher the integer, the more severe the error. The return code allows the macro program to determine whether the command succeeded and to take action if it failed.

Command Shells

Although ARexx was designed to work most effectively with programs that support its specific command interface, it can be used with any command shell program that uses standard I/O mechanisms to obtain its input stream. One way to use ARexx is to create an actual command file on the Ram Disk, then pass it directly to the Shell. Program 11 opens a new Shell to run a standard EXECUTE script.

Program 11. Shell.rexx

/*Launch a new Shell*/
ADDRESS command
conwindow = "CON:0/0/640/100/NewOne/Close"
/*Create a command file*/
CALL OPEN out, "ram:temp",write
CALL WRITELN out, `echo "This is a test"'
CALL CLOSE out
/*Open the new Shell window*/
`newshell' conwindow "ram:temp"
EXIT

Top Previous Next Chapter