ARexx Scripting Language¶

ARexx is the Amiga's built-in scripting and inter-application communication language. It is a dialect of Rexx, included with AmigaOS since Workbench 2.0. Source: Amiga OS 3.1 ARexx manual (Italian edition) and locale.library ARexx host interface docs.

What ARexx is for¶

ARexx serves two purposes: 1. Scripting — write automation scripts (like shell scripts, but more powerful) 2. Inter-application communication — send commands between applications. A spreadsheet can control a word processor; a paint program can talk to a file converter.

ARexx acts as a central hub: applications register with the RexxMast interpreter, and scripts can route commands to any registered application.

RexxMast — the interpreter¶

The ARexx interpreter is RexxMast (in SYS:System/). It must be running for ARexx to work.

Auto-launch: drag RexxMast into WBStartup/, or add REXXMAST >NIL: to S:User-Startup.

Manual launch: REXXMAST >NIL: from a Shell.

RexxMast creates a public message port named "REXX". ARexx scripts are plain ASCII text files (typically .rexx extension) run via the rx command:

rx myscript.rexx

How application hosting works¶

An ARexx-aware application:

Creates a named message port (e.g., "MYAPP.1")
Waits for messages on that port
When an ARexx message arrives, processes the command string
Replies to the sender with a result code (0 = success, non-zero = error)

Scripts send commands to the application via the ADDRESS instruction:

ADDRESS 'MYAPP' 'Load myfile.doc'
ADDRESS 'MYAPP' 'SaveAs newfile.doc'

Language reference¶

Basic instructions¶

Instruction	Purpose
`SAY expr`	Print to console
`PULL var`	Read a line from input
`var = expr`	Assignment
`IF cond THEN ...`	Conditional
`DO i = 1 TO n ... END`	Counted loop
`DO WHILE cond ... END`	While loop
`DO UNTIL cond ... END`	Until loop
`SELECT WHEN ... OTHERWISE ... END`	Multi-branch
`CALL func args`	Call function/procedure
`RETURN value`	Return from call
`EXIT code`	Exit program
`SIGNAL label`	Goto (error handling)
`INTERPRET expr`	Execute string as code
`PROCEDURE`	Start local-variable scope
`ARG ...`	Parse command arguments

String parsing with PARSE¶

PARSE is ARexx's powerful string decomposition tool:

PARSE VAR string word1 word2 word3
PARSE PULL line                    /* parse input line */
PARSE ARG arg1 ',' arg2            /* parse comma-separated args */
PARSE SOURCE opsys caller name     /* how was this script called? */

Built-in functions¶

Function	Purpose
`LENGTH(s)`	String length
`SUBSTR(s, start, len)`	Substring
`POS(needle, haystack)`	Find position
`DATE()`	Current date
`TIME()`	Current time
`RANDOM(min, max)`	Random number
`DATATYPE(var)`	NUM or CHAR
`STRIP(s)`	Remove leading/trailing spaces
`COPIES(s, n)`	Repeat string n times
`WORD(s, n)`	Extract nth word
`WORDS(s)`	Count words
`X2C(hex)` / `C2X(char)`	Hex ↔ char conversion
`D2X(dec)` / `X2D(hex)`	Decimal ↔ hex

Error handling¶

SIGNAL ON ERROR
SIGNAL ON SYNTAX
SIGNAL ON HALT

/* ... main code ... */

ERROR:
  SAY 'Error' RC 'at line' SIGL
  SAY 'Condition:' CONDITION('C')
  EXIT RC

RC — return code from last command
SIGL — line number where the signal was raised
CONDITION('C') — the condition name that triggered the handler

Host commands¶

/* Send commands to a host application */
ADDRESS 'MYAPP' 'Open filename'
result = RC
IF result = 0 THEN SAY 'Success'
ELSE SAY 'Failed with code' result

The application processes the command string and returns a result code through the message reply. RC always holds the most recent result.

Procedures and local variables¶

myprocedure: PROCEDURE
  arg a, b
  sum = a + b
  RETURN sum

PROCEDURE creates a new variable scope — all variables are local. Without it, variables are global.

Multi-tasking¶

ARexx scripts can launch other scripts in parallel:

'rx background_task.rexx &'   /* asynchronous */
'rx foreground_task.rexx'     /* synchronous (waits) */

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search