Explaining Regina

AROS can use an AREXX-style communication concept, but it is important to understand the difference between classic ARexx ports, ARexx itself, and Regina REXX. 

What are ARexx ports? 

An ARexx port is a named communication point opened by a running program. 

A program that supports ARexx can create a port such as: 
MYPROGRAM
EDITOR
PLAYER 

A script can then send commands to that port. 

The target program receives the command, executes it, and may return a result. 

The idea is: 
REXX script↓sends command to named ARexx port↓
application receives command↓
application performs an action↓
script receives result or error 
This makes ARexx ports useful for automation. 

Typical use cases for ARexx ports 

ARexx ports are usually used to control applications from scripts. 

Typical examples:
tell a text editor to open a file
tell an image program to convert an image
tell a music player to load or play a module
tell a development tool to compile source code
automate repeated actions
connect several programs together

A beginner can think of an ARexx port as a remote-control socket for an application. 

How an application uses an ARexx port 

An application must explicitly support ARexx-style control. 

If it does, it usually does three things: 
1.  It opens a named message port. 
2. It waits for commands. 
3.It interprets command strings sent to that port. 

For example, an editor might understand commands like: 
OPEN RAM:test.txt
SAVE
QUIT 
A media player might understand: 
LOAD Work:Music/song.mod
PLAY
STOP 

The commands are not universal. Each program defines its own command set. 

ARexx versus Regina REXX 

ARexx ARexx is the Amiga scripting language based on REXX. It was deeply integrated into AmigaOS and especially known for application automation through message ports. 

Important characteristics: 
classic Amiga scripting language
designed for inter-application communication
can send commands to application ports
often used to automate Amiga programs
strongly connected to the AmigaOS environment

On classic Amiga systems, ARexx was one of the most powerful automation tools because many applications supported ARexx ports. 

Regina REXX 

Regina is a portable REXX interpreter. 

Important characteristics: 
available on many systems
focuses on the REXX language itself
good for general scripting
useful for strings, variables, loops, conditions, and file processing
not automatically the same as classic Amiga ARexx

Regina can run REXX scripts, but it does not automatically mean that every classic ARexx port feature is available exactly like on AmigaOS. On AROS, the available behavior depends on the installed Regina version, AROS components, and whether applications expose compatible ports. 

Main difference in simple words 

Short version: ARexx is the Amiga-style automation environment. Regina is a REXX interpreter that can be used to write and run REXX scripts, but it is not automatically identical to classic ARexx integration. 

Beginner example Hello world in Regina

/* hello.rexx */
say "Hello from Regina REXX!" 

Run it with Regina, for example: regina hello.rexx 
This prints: Hello from Regina REXX! 

Beginner example 2: Variables 

/* variables.rexx */
name = "AROS beginner"
system = "AROS OS" 
say "Hello" name
say "You are learning" system

Output: Hello AROS beginner
You are learning AROS OS 

Beginner example Asking for input 

/* input.rexx */
say "What is your name?"
pull name 
say "Hello," name
say "Welcome to REXX on AROS." 

pull reads a line from the user and stores it in the variable name. 

Beginner example: Conditions 

/* condition.rexx */
say "Enter a number:"
pull number 
if number > 10 then    
say "The number is greater than 10."
else    
say "The number is 10 or smaller." 

This example shows a simple if ... then ... else decision. 

Beginner example: Loop 

/* loop.rexx */
do i = 1 to 5    
say "This is line" i
end 

Output: 
This is line 1
This is line 2
This is line 3
This is line 4
This is line 5 

Beginner example 6: Working with strings 

/* strings.rexx */
text = "AROS Shell and Regina REXX" 
say "Original text:" text
say "Length:" length(text)
say "Uppercase:" translate(text)
say "First 4 characters:" substr(text, 1, 4)
say "Position of REXX:" pos("REXX", text) 

This teaches useful text-processing functions. 

Beginner example: Calling a system command 

Depending on the Regina setup, external commands can usually be called with address system. 

/* command.rexx */
say "Listing current directory:"
address system "dir" 

On AROS, the exact command may depend on the Shell environment and installed commands. 

Beginner example: A simple file list helper

/* filehelper.rexx */
say "This script shows the contents of RAM:"
address system "dir RAM:" 

This is useful for beginners because RAM: is a safe temporary location. 

Beginner example: Simulated ARexx-port idea 

Even if no real application port is used, the basic idea can be explained with a simulated command string: 

/* simulated_port_command.rexx */
portname = "TEXTEDITOR"
command = "OPEN RAM:test.txt" 
say "Target port:" portnamesay "Command to send:" command
say "If the application supported this port, it would receive and execute the command." 

Short summary 

ARexx ports are named communication channels used by applications to receive script commands. Classic ARexx was famous on Amiga systems because it allowed scripts to control many programs. Regina is a portable REXX interpreter and is useful for learning and running REXX scripts, but it is not automatically the same as the full classic ARexx environment. For beginners on AROS, Regina is a good way to learn variables, loops, conditions, strings, menus, and simple system-command scripting before moving on to application automation.I added a new beginner-friendly section with a generic Regina REXX template for sending a command to an AROS application port. 

A reminder that Regina can only send commands to ports that actually exist and are supported by the application. 

Generic Regina 

Template for Sending a Command to an AROS Application Port This example shows the general idea of how a Regina REXX script could send a command to an AROS application port. It is written as a template because the real port name and valid commands depend on the application. The target program must already be running and must provide a compatible ARexx-style port. 

/* send_to_port.rexx */
/* Generic Regina REXX template for sending a command to an AROS application port */

portname = "APPLICATIONPORT"
command = "ABOUT"

say "Target port:" portname
say "Command:" command
say "Sending command..."

address value portname command

if rc = 0 then do
    say "Command was sent successfully."
end
else do
    say "The command could not be completed."
    say "Return code:" rc
    say "Check whether the application is running, whether the port name is correct, and whether the command is supported."
end 

In this template, APPLICATIONPORT is only a placeholder. In a real script, it must be replaced with the exact port name opened by the target application. The command ABOUT is also only an example. Some applications may support commands such as OPEN, SAVE, PLAY, STOP, or QUIT, but the available commands are defined by the application itself. 

How to adapt the template 
1.       Start the AROS application that supports an ARexx-style port. 
2.       Find the application’s documented port name. 
3.       Replace APPLICATIONPORT with that port name. 
4.       Replace ABOUT with a real command supported by the application. 
5.       Run the script with Regina. 
6.       If the script returns an error, check whether the program is running and whether the command syntax is correct. 

A beginner should remember that Regina can run REXX code, but application-port automation only works when the surrounding AROS environment and the target application provide compatible port support. The script cannot invent a port; it can only send commands to a port that already exists.  

Regina Rexx Command Reference 

Regina is a portable Rexx interpreter. The following table gives a compact reference for frequently used Rexx instructions, built-in functions, file/stream operations, and Regina command-line options. 

Command / FunctionTypeShort description 
regina script.rexx Interpreter command Runs a Rexx script with the Regina interpreter. 
rexx script.rexx Interpreter command Runs a Rexx script using the faster executable that does not support SAA external function packages. 
regina -i Option Starts Regina in interactive mode without running a script. 
regina -v Option Displays the Regina version and exits. 
regina -t Option Enables tracing while a program runs; useful for debugging. 
regina -a Option Passes command-line parameters as separate Rexx arguments. 
regina -r Option Runs a script in restricted mode, preventing file writes, external commands, and external package loading. ADDRESS Instruction Changes or queries the external command environment. 
ARG Instruction / function Receives or returns arguments passed to the Rexx program or routine. 
CALL Instruction Calls an internal routine, external routine, or function. 
DO ... END Instruction Creates loops or grouped blocks of statements. 
IF ... THEN ... ELSE Instruction Performs conditional branching. 
INTERPRET Instruction Executes a string as Rexx source code. 
LEAVE Instruction Exits a loop immediately. 
ITERATE Instruction Skips to the next loop iteration. 
PARSE Instruction Splits strings, arguments, or input into variables. 
PULL Instruction Reads a line from the input queue or standard input and converts it to uppercase. 
SAY Instruction Writes text to the default output stream. 
SELECT ... WHEN ... OTHERWISE Instruction Provides multi-way conditional branching. 
SIGNAL Instruction Transfers control to a label or handles conditions. 
TRACE Instruction Controls tracing and debugging output. 
ABS(number) Built-in function Returns the absolute value of a number. 
ABBREV(long, short) Built-in function Tests whether one string is a valid abbreviation of another. 
CENTER / CENTRE Built-in function Centers text within a specified width. 
COMPARE Built-in function Compares two strings and reports the first difference. 
COPIES Built-in function Repeats a string a specified number of times. 
DATE Built-in function Returns the current date in a selected format. 
LENGTH Built-in function Returns the length of a string. 
POS Built-in function Finds the position of one string inside another. 
SUBSTR Built-in function Extracts part of a string. 
TIME Built-in function Returns the current time in a selected format. 
TRANSLATE Built-in function Translates characters or converts text to uppercase. 
WORD Built-in function Returns a selected word from a string.
WORDS Built-in function Counts the number of words in a string. 
CHARIN Stream function Reads characters from a stream or file. 
CHAROUT Stream function Writes characters to a stream or file. 
LINEIN Stream function Reads a line from a stream or file. 
LINEOUT Stream function Writes a line to a stream or file. 
STREAM Stream function Queries or controls the state of a stream. 
SysLoadFuncs RexxUtil function Loads the RexxUtil function package for system and file utilities. 
SysFileTree RexxUtil function Builds a stem variable containing files matching a pattern. 
SysFileDelete RexxUtil function Deletes a file. 
SysMkDir RexxUtil function Creates a directory. 
SysRmDir RexxUtil function Removes a directory. 
SysSearchPath RexxUtil function Searches a path for a specified file. 
SysTempFileName RexxUtil function Generates a temporary file name.

ARexx vs. Regina 

Both ARexx and Regina implement the REXX language, which Mike Cowlishaw designed at IBM. They come from different worlds, though. ARexx is a small, Amiga-specific scripting and inter-application glue system. Regina is a portable, standards-oriented general-purpose interpreter. 

1. Origin and status

ARexx was written by William S. Hawes and released in 1987. It began as a commercial product, and Commodore later bundled it with AmigaOS from version 2.0 onward, which made it the standard scripting language on the Amiga. Hawes wrote it by hand in 68k assembly, so it is extremely small (only a few tens of kilobytes) and runs fast even on modest hardware. That design also ties it to the original Amiga platform: the original ARexx exists only for 68k AmigaOS, and later systems such as AmigaOS 4 and MorphOS ship their own re-implementations rather than Hawes’s code. In terms of language level, ARexx follows the REXX definition in the first edition of Mike Cowlishaw’s book The REXX Language, roughly language level 3.50. It therefore predates the official ANSI REXX standard and differs from it in several places. 

Regina has a different background. Anders Christensen started it in 1992, and Mark Hessling took it over and has maintained it for decades. It is open source under the LGPL and written in portable C rather than assembly, which is why it runs on many systems: Unix and Linux, Windows, macOS, OS/2, and ports for Amiga and AROS. Regina aims to follow the ANSI REXX standard X3.274-1996 (language level 5.00), and it offers optional compatibility modes that imitate other REXX dialects, including ARexx. The cost of this portability and completeness is size. Regina is considerably larger than ARexx and depends on a C runtime library, whereas ARexx is a self-contained piece of the operating system.

2. Philosophy and architecture 

ARexx is built into the OS as a central service:
RexxMast is a resident server process. It launches every script as its own process, so several scripts run concurrently.
rexxsyslib.library provides the API: RexxMsg structures, argstrings, and so on.
Communication runs over Exec message ports (“ARexx ports”). Any application that opens a named public port (e.g. ADDRESS 'IMAGEFX.1') becomes scriptable. This is ARexx’s defining feature and the reason it became the standard Amiga glue language.
Function hosts and function libraries are registered globally with ADDLIB()/REMLIB(), e.g. rexxsupport.library. Every running script can use them.
A global Clip List (SETCLIP()/GETCLIP()) lets scripts share data.
Global control commands: RX (run), RXC (close RexxMast), HI (halt all scripts), TS/TE (start/end tracing), and TCO/TCC (open/close the trace console).

Regina is a normal interpreter library and executable: 
There is no system-wide server; each process embeds or runs its own interpreter instance. Reentrant/multithreaded builds are available.
Applications integrate through the IBM SAA REXX API: RexxStart(), RexxRegisterSubcomExe() for command environments, RexxRegisterFunctionExe/Dll() for external functions, and RexxVariablePool().
External function packages are loaded with RxFuncAdd(), e.g. RexxUtil/regutil, RexxSQL, RexxCURL.
An external data queue is available via the rxstack daemon, which can be shared between processes and even across a network.

3. Command environments

(ADDRESS) ARexx: ADDRESS COMMAND executes AmigaDOS commands. Any other name refers to an application’s ARexx port. Results come back in RC, and with OPTIONS RESULTS the result string also lands in RESULT. Return codes follow the Amiga convention (5 = warn, 10 = error, 20 = fail).
Regina: offers environments like SYSTEM, COMMAND, PATH, CMD, plus whatever the host application registers. It supports the ANSI redirection syntax ADDRESS SYSTEM cmd WITH INPUT STEM in. OUTPUT STEM out. ERROR STEM err., which captures command output directly into stems. ARexx has nothing comparable.

4. Conditions and error handling 

ARexx SIGNAL ON conditions: BREAK_C, BREAK_D, BREAK_E, BREAK_F (the Amiga Ctrl-C to Ctrl-F break signals), ERROR, FAILURE, HALT, IOERR, NOVALUE, SYNTAX.
Regina (ANSI): ERROR, FAILURE, HALT, NOVALUE, NOTREADY, SYNTAX, LOSTDIGITS. It also offers CALL ON for the appropriate conditions and the CONDITION() function with full ANSI semantics.
ARexx’s IOERR roughly corresponds to ANSI NOTREADY.
Error numbers and messages differ between the two, so scripts that test specific error codes are not portable.

5. File I/O 

(the biggest practical difference) ARexx uses its own model with logical file names:

Arexx-source
IF OPEN('f', 'RAM:test.txt', 'W') THEN DO 
CALL WRITELN('f', 'Hello') 
CALL CLOSE('f') 
END 

Its functions are OPEN, CLOSE, READLN, WRITELN, READCH, WRITECH, EOF, and SEEK. STDIN, STDOUT and STDERR are predefined. 

Regina uses the standard REXX stream functions:

Regina-rexx-source
CALL LINEOUT 'test.txt', 'Hello' 
CALL STREAM 'test.txt', 'C', 'CLOSE' 

Its functions are LINEIN, LINEOUT, CHARIN, CHAROUT, LINES, CHARS, and STREAM. Streams open implicitly. 

Regina helps with porting: OPTIONS AREXX_BIFS enables ARexx-style built-ins (OPEN, READLN, WRITELN, EOF, SEEK, ...), and OPTIONS AREXX_SEMANTICS adjusts certain behaviors to match ARexx. 

6. Built-in functions 

Only in ARexx (Amiga/system-oriented): Memory access and raw pointers: ALLOCMEM, FREEMEM, GETSPACE, FREESPACE, IMPORT, EXPORT, STORAGE, OFFSET, NEXT, NULL. You can poke directly into Amiga structures.
System and library calls: ADDLIB, REMLIB, SHOW (lists ports, libraries, clips), PRAGMA (current directory, priority, stack size), SETCLIP, GETCLIP.
Other extensions: C2B, B2C, BITSET, BITCLR, BITCHG, BITTST, BITCOMP, HASH, RANDU, UPPER, TRIM, COMPRESS.
More come from rexxsupport.library, e.g. SHOWDIR, STATEF, DELETE, MAKEDIR, OPENPORT, WAITPKT, GETPKT, REPLY. With these, ARexx scripts can even open their own message ports.

In Regina: The full ANSI set (CHANGESTR, COUNTSTR, DATE/TIME with conversion arguments, QUALIFY, ...).
Many common extensions from other REXX dialects (CMS, OS/2), plus the ARexx compatibility functions mentioned above. Some are switched on via OPTIONS.

7. Numbers, strings, limits 

Precision: ARexx’s arithmetic has limited internal precision. Regina implements arbitrary-precision decimal arithmetic as REXX intends, so NUMERIC DIGITS 100 really gives 100 digits.
String length: ARexx strings are capped at 65,535 bytes. Regina is limited only by memory.
Speed: ARexx is very fast and lightweight on a 68k machine thanks to its assembly code. Regina is more general and heavier, but more complete.

8. Tracing and debugging 

ARexx: TRACE plus interactive tracing, and system-wide control via TS/TE. You can switch tracing on for all running scripts from outside, and output goes to a separate trace console (TCO).
Regina: standard TRACE with interactive mode (TRACE ?R), per-process only. It also offers profiling/debugging options and command-line switches.

9. Portability of scripts 

ARexx → Regina: usually works for pure string logic. Typical stumbling blocks are file I/O (solvable with OPTIONS AREXX_BIFS), Amiga-specific functions (memory, ports, clips), BREAK_x conditions, and anything that relies on application ports.
Regina → ARexx: harder. ANSI streams, ADDRESS ... WITH, CALL ON, and many newer BIFs are missing.

10. Relevance for AROS m68k 

On AROS there is no original Hawes ARexx. As far as I know, AROS’s ARexx subsystem (RexxMast, rexxsyslib.library, RX) is built on Regina, with an ARexx compatibility layer on top. In practice this means: ARexx ports and ADDRESS 'PORTNAME' work as you’d expect from AmigaOS.
Behind the scenes, the language core is Regina. Some edge cases (error numbers, numeric precision, exotic memory functions like IMPORT/EXPORT) may behave differently from classic ARexx.
If you want to make your own programs scriptable, an ARexx port via Exec message ports is the native approach and works for both worlds.
In short: ARexx is the Amiga-native IPC and scripting system with direct OS integration. Regina is a modern, standards-compliant, portable REXX interpreter that can emulate ARexx behavior but doesn’t come from the same design philosophy.