Amiga Emulator FAQ

ARexx Commands

Operators
Add ( + ) - Add numbers together.
Subtract ( - ) - Subtract number from another.
Multiply ( * ) - Times numbers
Divide ( / ) - Divide number by another.
Integer divide ( % ) - Divide integers to give an integer
Power (**) - Number multipled by itself by power number.
Remainder ( //) - Return remainder from a division of numbers.
Concatenate ( || ) - Join two strings together.
Boolean not (~ ) - Return the reverse value of boolean number (0 or 1).
Boolean or ( | ) -Return true if either values are true.
Boolean and ( & ) - Return true if both values are true.
Boolean xor ( ^ , &&) - Return true if oonly one of values is true.

Comparisons
Equals ( ==, =) - True if both values are the same.
Not Equals ( ~== , ~=) - True if values are not the same.
Less than ( <) - True if one value is less than another.
Greater than. ( >) - True if one value is more than another.
Less or equal to ( <= ) - True if one value is less than or equal to another.
Greater than. ( >= ) - True if one value is more than or equal to another.

Instructions

ADDRESS
Format: Address [ string | symbol | [[VALUE] [expression]]
Purpose: Specifies the host address for commands issued by the interpreter. The host is an external program such as Workbench, Ed, Command (console) etc.
Input:
String or Symbol = Name of host address.
[VALUE] expression = Specifies the new host address, and current address becomes the previous address. The word value can be omitted if the first token of the expression is not a symbol or string.
Examples: address edit, address VALUE edit n

ARG
Format: Arg [template] [,template...]
Purpose: Retreives one or more argument strings, commands tend to have one arguments, and functions upto 15 arguments.
Input: Name of argument(s)
Example: arg first, second

BREAK
Format: Break
Purpose: To exit from a DO instruction or from within an INTERPRETed string.
Example: Break from a do loop if value of i is more than 3.
do
if i>3 then break
a = a +1
y.a = name
end

CALL
Format: CALL { symbol | string } [expression] [, expression, ...]
Purpose: Call an internal or external function. Funcation name can be a symbol or string. An values from a function is returned in a special variable called RESULT.
Input:
String or synbol = Name of function
Expression(s) = arguments for function
Example: CALL myfunction name,40

DO
Format: DO [var = expr1 [TO expr2] [BY expr3]] [FOR expr4] [FOREVER] [WHILE expr5 | UNTIL expr6]
Purpose: Does a group of instructions between DO and an END instruction. The type of do loop can be a counted loop, interated loop, an infinite loop or a conditional loop.
Input:
var = Name of variable for counter in a interated loop.
expr1 = First value in a counted loop.
expr2 = Last value in a counted loop.
expr3 = Amount var to be increased by, default is 1.
expr4 = While number contained max number of interations.
Forever = Loops indefinately unless a LEAVE or BREAK statement is run.
expr5 = Continues loop if this expression is still true.
expr6 = Continues loop until this expression becomes true.
Example: DO n = 0 TO 100 BY 5

DROP
Format: DROP variable [variable ...]
Purpose: Variables are reset to their uninistialised state, in which the value of the variable becomes the name of the variable.
Input: Name of variables to drop.
Example: DROP A, B

ECHO
Format: ECHO [ expression ]
Purpose: Displays the expression result on the console. Its an alias for SAY instruction.
Input: Expression to be displayed.
Output: Result of expression on console.
Example ECHO "The result is " RESULT

ELSE
Format: ELSE [;] [condtional statement]
Purpose: Provides alternative conditional branch for IF statement if the condition was false. Use dummy else statements if using inner IF statements and use the NOP instruction. The semi-colon is a statement terminator.
Example: IF age<16 THEN say "Child" ELSE say "Adult"

END
Format: END [variable]
Purpose: The End instruction terminates a DO or SELECT instruction. Optionally you can specify the index variable of the DO statement.
Input: variable = Name of index variable in a DO loop.
Example: DO i=1 TO 15; say i; END i

EXIT
Format: EXIT [expression]
Purpose: This terminates the execution of a program and can be run from anywhere in a program. An optional expression can be used to return as a program or function result.
Input: Expression = returning result value
Example: EXIT 10

IF
Format: IF expression THEN [;] [conditional statement]
Purpose: To evaluate the expression and if the result is true (1), then the conditional statement(s) are executed. Optionally an ELSE clause can be appended if condition is not true. If multiple statements are required, then they can be in a DO .. END group
Input: expression = Boolean conditional expression
Example: IF price > 100 THEN say "It's too high."

INTERPRET
Format: Interpret expression
Purpose: The expression is evaluated and the result is executed as one or more instruction. This allows for programs to be dynamically constructed and run or program fragments can be passed as arguments to functions.
Input: expression = Instruction(s) to evaluate
Example: print = 'say'; interpret print hello

INTERATE
Format: Interate [variable]
Purpose: This instruction terminates the current iteration of a DO loop and starts the next iteration before it normally completes the loop.
This effectively jumps to the END statement and onto the DO statement to begin next loop.
Input: variable = Specifies the index variable of the DO loop to interate on.
Example: DO j=1 TO 100; IF j=55 THEN INTERATE j; END

LEAVE
Format: LEAVE [variable]
Purpose: This causes the program to immediate leave a DO loop and continue on after the END statement.
Input: variable = Specifies the index variable of the DO loop to leave
Example: DO FOREVER; IF value >20 THEN LEAVE; END

NOP
Format: NOP
Purpose: A no-operation instruction, useful for use in compound IF ELSE statements.
Example: IF a=b THEN a=10 ELSE NOP

NUMERIC
Format:
Numeric {DIGITS | FUZZ} expression
Numeric FORM {SCIENTIFIC | ENGINEERING}
Purpose: This sets options for the numeric precision and format.
Input:
DIGITS = Number of digits of precision for arithmetic calculations.
FUZZ = Number of digits to be ignored in comparison instructions. Must be less than current DIGITS settings.
FORM SCIENTIFIC = Numbers that require exponential notation so that the mantissa is between 1 and 10 (default).
FORM ENGINEERING = Numbers that require exponential notation so that the mantissa is between 1 and 1000.
Example: NUMERIC DIGITS 4

OPTIONS
Format:
OPTIONS [FAILAT expression]
OPTIONS [PROMPT expression]
OPTIONS [RESULTS]
Purpose: Sets various internal defauls for errors, pull prompt strings and requesting result strings from external hosts.
Input:
FAILAT = Sets the limit at or above which command return codes signal as errors. Return an integer value.
PROMPT = Sets a string for used as a prompt for the PULL or PARSE PULL instructions.
RESULT = Tells interpreter that it should request a result string when it issues commands to the external host.
Example: OPTIONS FAILAT 20

OTHERWISE
Format: OTHERWISE [;] [conditional statement]
Purpose: Used within the SELECT instruction and after the WHEN .. THEN statements. If none of the preceeding WHEN clauses have
successed then the statements after the OTHERWISE instruction is executed.
Example:
SELECT
WHEN i=1 THEN SAY 'one'
WHEN i=2 THEN SAY 'two'
OTHERWISE say 'other'
END

PARSE
Format: PARSE [UPPER] input-source [template] [,template...]
Purpose: Parse provides a method to extract one or more substrings from a string and assign them to variables. Input string can be from argument strings, an expression or from the console. The templates provides the variables and way to determine the values.
Input:
UPPER = Optional keyword to be used with any of the input sources.
ARG = Retreive argument strings.
EXTERNAL = Input string is read from the console
NUMERIC = Curret numeric options are placed in a string seperated by spaces.
FULL = Read a string from the input console.
SOURCE = A Source string for program is retreived in format as {COMMAND | FUNCTION} {0 | 1} called resolved ext host.
VALUE expr WITH = Input string is the result of the supplied expression. It is parsed with multiple templates.
VAR variable = The value of the variable is the input string. Current value is used when using multiple templates.
VERSION = Returns version of the interpreter e.g. ARexx version cpu mpu video freq.
Templates = Consists of symbols, strings, operators and parenthesis to parse the input by either Tokenisation, Position or Pattern.
Output: Result of parsed input.
Example:
/* Assume argument is "1234567890" */
PARSE ARG 1 a 3 b +2 1 c
SAY a b c /* ==> 12 34 1234567890 */

PROCEDURE
Format: PROCEDURE [EXPOSE variable [variable ...]]
Purpose: To define a seperate function and pass variables in the ESPOSE list to the new function. The procedure name is defined by a label at the start.
Input: Variable(s) = Arguments which can be passed by reference to the procedure. They can include stems or compound symbols .
Output: Values can be RETURNed to the calling instuctions.
Example:
fact: PROCEDURE
arg i
IF i <= 1
THEN RETURN 1
ELSE RETURN i*fact(i-1)

PULL
Format: PULL [template] [,template...]
Purpose: A short hand version of the PARSE UPPER PULL instruction. It will read a string from input console, translate it to uppercase and parse it using the template.
Input: Templates = Name of templates
Example: PULL firstname lastname

PUSH
Format: PUSH [expression]
Purpose: Instruction pushes data onto the STDIN (standard input) stream, in last-in, first-out (stack) order. The stacked data can then be read by a command shell or other program.
Input: Expression = Data to be added to stack.
Example; PUSH cmd1; PUSH cmd2; PUSH cmd3

QUEUE
Format: QUEUE [expression]
Purpose: Instruction pushes data onto the STDIN (standard input) stream, in first-in, first-out order. The stacked data can then be read by a command shell or other program.
Input: Expression = Data to be added to the queue.
Example; QUEUE cmd1; QUEUE cmd2; QUEUE cmd3

RETURN
Format: RETURN [expression]
Purpose: This leaves a function or procedure and returns to instruction after the calling instruction. Optionally, it can return a result.
Input: Expression = Data to be returned to calling function.
Example: RETURN (a*b)

SAY
Format: SAY [ expression ]
Purpose: Displays the expression result on the console with a newline added. If no expression is specified, a null string is sent.
Input: Expression to be displayed.
Output: Result of expression on console.
Example SAY "The result is " myresult

SELECT
Format: SELECT [WHEN condition THEN statement ...] [OTHERWISE statement] END
Purpose: To run instructions depending on the condition in one or more WHEN clauses, otherwise if no conditions are met, run the OTHERWISE instructions.
Input: Condition = A condition for each WHEN close and if true, the statement(s) are run.
Example:
SELECT
WHEN tax = 20 THEN result = value * tax/100
WHEN tax = 40 THEN result = value * tax/100
OTHERWISE result=value
END

SHELL
Format: SHELL [symbol | string] [expression]
Purpose: This is a synonym for the Address instruction, to set the external host address.
Input:
String or Symbol = Name of host address.
expression = Specifies the new host address, and current address becomes the previous address. The word value can be omitted if the first token of the expression is not a symbol or string.
Examples: shell edit, address 'edit n'

SIGNAL
Format: SIGNAL ON | OFF condition
or SIGNAL [VALUE] expression
Purpose:
a) Control the state of the internal interrupt flags, which are used to detect and retain control control when errors occur.
The condition is a pre-defined keyword to specify what to detect to cause a change of signal.
b) The expression is evaluation and an immediate interrupt is generated to transfer control to the label specified by the expression.
Thus, it works, like a computer goto command.
The variable SIGL contains the current line number when a transfer of control occurs. The variable RC contains an error code.
Input:
condition = BREAK_C, BREAK_D, BREAK_E, BREAK_F, ERROR, HALT, IOERR, NOVALUE, SYNTAX.
expression = epxression or label to jump to.
Examples: SIGNAL ON ERROR, SIGNAL OFF SYNTAX, SIGNAL START.

THEN
Format: THEN[;] [conditional statement]
Purpose: The THEN statement must follow an IF statement and if the codition is true, then the conditional statements are executed.
Examples:
IF i>50
THEN say 'Value is over 50'

TRACE
Format: [symbol | string | [[VALUE] expression]]
Input: Symbol = Poptional pre-fix character (? , ! )
string = alphabetic options
expression = numeric value, if negative a suppression count
Purpose: This is used to set the internal tracing mode. If a symbol or string is supplied, it is interpreted as a lteral otherwise it is evaluated
as an expression. VALUE keyword can be omitted if the expression doesn't start with a symbol or string. The result string is converted to
uppercase and check for the alphabetic options (ALL, COMMANDS, ERRORS, INTERMEDIATES, LABELS, RESULTS and SCAN)
otherwise it is coverted to an integer. Pre-fix characters may be used in front of the alphabetic characters. The '?' character means interactive
tracing and '!' controls command inhibition. They can act as toggles, to select or de-select modes. A negative value, means that it is a suppression cound, so
it will pass over a number of clauses before resuming tracing.
Examples: TRACE ?r , TRACE OFF, TRACE -20

UPPER
Format: UPPER variable [ variable ..]
Purpose: Converts the values of the variable(s) to upper case.
Input/Output: variable = Expression to convert to upper case.
Example:
text = 'This is some text.'
upper text

WHEN
Format: WHEN expression [THEN [;] [conditional statement]
Purpose: This instruction is similar to an IF statement, but it is only used within a SELECT range.
If the expression is true then the conditional statements are executed.
Input:
expression = condition to be evaulated.
conditional statement = Statements to be run if expression is true
Example:
SELECT;
WHEN I<J THEN say 'less'
WHEN I=J THEN say 'equal'
OTHERWISE say 'greater'
END

Back to UAE FAQ.