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.