AmigaOS Documentation Wiki - User contributions [en]

AmigaOS Manual: ARexx Functions

2021-10-18T03:06:15Z

Tony Wyatt: Added [] around "digits" in X2D()

A function is a program or group of statements that is executed whenever that function name is called in a particular context. A function may be part of an internal program, part of a library, or a separate external program. Functions are an important building block of modular programming because they allow you to construct large programs from a series of small, easily developed modules.

This chapter explains the different types of functions and how they are evaluated. It also provides an alphabetical reference of ARexx's built-in function library.

= Invoking a Function =

Within a ARexx program, a function is defined as a symbol or string followed immediately by an open parenthesis. The symbol or string (taken as a literal) specifies the function name, and the open parenthesis begins the argument list. Between the opening and closing parentheses are zero or more argument expressions, separated by commas, that supply the data being passed to the function.

Valid function calls are:

<syntaxhighlight lang="rexx">
CENTER( 'title', 20 )
ADDRESS()
'ALLOCMEM'( 256*4, 1 )
</syntaxhighlight>

Each argument expression is evaluated in turn and the resulting strings are passed as the argument list to the function. Each argument expression, while often just a single literal value, can include arithmetic or string operations or even other function calls. Argument expressions are evaluated from left to right.

Functions can also be invoked using the CALL instruction. The CALL instruction, described in Chapter 4, can be used to invoke a function that may not return a value.

= Types of Functions =

There are three types of functions:

* Internal functions - defined within the ARexx program.
* Built-in functions - supplied by the ARexx programming language.
* Function Libraries - a special Amiga shared library.

== Internal Functions ==

An internal function is identified by a label within the program. When the internal function is called. ARexx creates a new storage environment so that the previous caller's environment is preserved. The new environment inherits the values from its predecessor, but subsequent changes to the environment variables do not affect the previous environment.

The specific values preserved are:

* The current and previous host addresses.
* The NUMERIC DIGITS, FUZZ, and FORM settings.
* The trace option, inhibit flag, and interactive flag.
* The state of the interrupt flags as defined by the SIGNAL instruction.
* The current prompt string as set by the OPTIONS PROMPT instruction.

The new environment does not automatically get a new symbol table, so initially all of the variables in the previous environment are available to the called function. The PROCEDURE instruction can be used to create a table and thereby protect the caller's symbol values. PROCEDURE can also be used to allow the same variable name to be used in two different areas with two different values.

Execution of the internal function proceeds until a RETURN instruction is executed. At this point the new environment is dismantled, and control resumes at the point of the function call. The expression supplied with the RETURN instruction is evaluated and passed back to the caller as the function result.

== Built-In Functions ==

ARexx provides a substantial library of predefined functions as part of the language system. These functions are always available and have been optimized to work with the internal data structures. In general, the built-in functions execute much faster than an equivalent interpreted function, so their usage is strongly recommended.

Several of the built-in functions create and manipulate external AmigaDOS files. Files are referenced by a logical name, a case-sensitive name that is assigned to a file when it is first opened. The initial input and output streams are given the names STDIN (standard input) and STDOUT (standard output). There is no theoretical limit to the number of files that may be open simultaneously, although a limit will be imposed by available memory. All open files are closed automatically when the program exits.

== External Function Libraries ==

A function library is a collection of one or more functions organized as an Amiga shared library. The library must reside in LIBS:, but may be either memory or disk-resident. Disk-resident libraries are loaded and opened as needed.

The library has to be especially tailored for use by ARexx. Each function library must contain a library name, a search priority, an entry point offset, and a version number. When ARexx is searching for a function, the interpreter opens each library and checks its "query" entry point. This entry point must be specified as an integer offset (e.g. "-30") from the library base. The return code from the query call indicates whether the desired function was found. If the function is found, it is called with the parameters passed by the interpreter, and the function result is returned to the caller. If it is not found, a "Function not found" error code is returned, and the search continues with the next library in the list. Function libraries are always closed after being checked so that the operating system can reclaim the memory space if required.

=== The Library List ===

The ARexx resident process maintains a list of the currently available function libraries and function hosts called the Library List. Application programs can add or remove function libraries as required.

The Library List is maintained as a priority-sorted queue. Each entry has an associated search priority in the range 100 (highest) to -100 (lowest). Entries can be added at an appropriate priority to control the function name resolution. Libraries with higher priorities are searched first. Within a given priority level, those libraries added first are searched first. The priority levels are significant if any of the libraries have duplicate function name definitions, since the function located further down the search chain could never be called.

== External Function Hosts ==

The name associated with a function host is the name of its public message port. Function calls are passed to the host as a message packet; it is then up to the individual host to determine whether the specified function name is one that it recognizes. The name resolution is completely internal to the host, so function hosts provide a natural gateway mechanism for implementing remote procedure calls to other machines in a network. The ARexx resident process is a function host and is installed in the Library List with a priority of -60.

= The Search Order =

Function linkages in ARexx are established at the time of the function call. A specific search order is followed until a function matching the name symbol or string is found. If the specified function cannot be located, an error is generated and the expression evaluation is terminated. The full search order is:

; Internal Functions
: The program source is examined for a label that matches the function name. If a match is found, a new storage environment is created and control is transferred to the label.

; Built-In Functions
: The built-in function library is searched for the specified name. All of these functions are defined by uppercase names.

; Function Libraries and Function Hosts
: The available function libraries and function hosts are maintained in the Library List, which is searched starting at the highest priority until the requested function is found or the end of the list is reached. Function hosts are called using a message-passing protocol similar to that used for commands and may be used as gateways for remote procedure calls to other machines in a network.

; External ARexx Programs
: The final search step is to check for an external ARexx program file by sending an invocation message to the ARexx resident process. The search always begins in the current directory and follows the same search path as the original ARexx program invocation. The name matching process is not case-sensitive.

The function name-matching procedure may be case-sensitive for some of the search steps, but not for others. The matching procedure used in a function library or function host is design dependent. Functions defined with mixed-case names must be called using a string token, since symbol names are always translated to uppercase.

The full search order is followed whenever the function name is defined by a symbol token. However, the search for internal functions is bypassed if the name is specified by a string token. This allows internal functions to usurp the names of external functions, as in the following example:

<syntaxhighlight lang="rexx">
CENTER: /*internal "CENTER"*/
ARG string, length /* get arguments */
length = MIN( length, 60 ) /* compute length */
RETURN 'CENTER'( string, length )
</syntaxhighlight>

Here the built-in function CENTER() has been replaced by an internal function after modifying the length argument.

= The Clip List =

The Clip List is a publicly accessible mechanism that can be used as a general clipboard for intertask communication. Many functions use the clipboard for retrieving different types of information, such as predefined constants or strings.

The Clip List maintains a set of (name, value) pairs that may be used for a variety of purposes. ([[AmigaOS_Manual:_ARexx_Functions#SETCLIP.28.29|SETCLIP()]] is used to add pairs to the list.) Each entry in the list consists of a name and a value string and may be located by name. In general, the names used should be chosen to be unique to an application to prevent unintended duplications with other programs. Any number of entries may be posted to the list.

One potential application for the Clip List is as a mechanism for loading predefined constants into an ARexx program. For example:

pi=3.14159; e=2.718; sqrt2=1.414 . . .

(i.e., a series of assignments separated by semicolons). In use, such a string could be retrieved by name using the built-in function [[AmigaOS_Manual:_ARexx_Functions#GETCLIP.28.29|GETCLIP()]] and then INTERPRETed within the program. The assignment statements within the string would then create the required constant definitions. For example:

<syntaxhighlight lang="rexx">
/*Assume a string called "numbers" is available*/
numbers = GETCLIP( 'numbers' )
INTERPRET numbers /*. . . assignments*/
</syntaxhighlight>

The strings would not be restricted to contain only assignment statements, but could include any valid ARexx statements. The Clip List could thus provide a series of programs for initializations or other processing tasks.

The resident process supports addition and deletion operations for maintaining the Clip List. The names in the (name,value) pairs are assumed to be in mixed case and are maintained to be unique in the list. An attempt to add a string with an existing name will simply update the value string. The name and value strings are copied when an entry is posted to the list, so the program that adds an entry is not required to maintain the strings.

Entries posted to the Clip List remain available until explicitly removed. The Clip List is automatically released when the resident process exits.

= Built-in Functions Reference =

This section provides an alphabetical list of the built-in functions. The syntax of each function is shown to the right of the function keyword.

== Syntax ==

Optional arguments are shown in brackets and generally have a default value that is used if the argument is omitted. When an option keyword is specified as an argument, only the first character is significant. Option keywords are not case-sensitive.

Many functions accept a pad character argument. Pad characters are inserted to fill or create spaces. For functions that accept a pad argument, only the first character of the argument string is significant. If a null string is supplied, the default padding character, usually a blank, will be used.

In the following examples, an arrow (->) is used as an abbreviation for "evaluates as." The arrow will not be displayed when a program is run. For example:

<syntaxhighlight lang="rexx">
SAY ABS( -5.35 ) -> 5.35
</syntaxhighlight>

This means that SAY ABS(-5.35) is evaluated as 5.35.

== Alphabetical Reference ==

=== ABBREV() ===

<nowiki>ABBREV(string1,string2[,length])</nowiki>

Returns a Boolean value that indicates whether string2 is an abbreviation of string1 with length greater than or equal to the specified length argument. The default length is 0, so the null string is an acceptable abbreviation. For example:

<syntaxhighlight lang="rexx">
SAY ABBREV( 'fullname', 'ful' ) -> 1
SAY ABBREV( 'almost', 'alm', 4 ) -> 0
SAY ABBREV( 'any', '' ) -> 1
</syntaxhighlight>

=== ABS() ===

<nowiki>ABS(number)</nowiki>

Returns the absolute value of the number argument. This value must be numeric. For example:

<syntaxhighlight lang="rexx">
SAY ABS( -5.35 ) -> 5.35
SAY ABS( 10 ) -> 10
</syntaxhighlight>

=== ADDLIB() ===

<nowiki>ADDLIB(name,priority[,offset,version])</nowiki>

Adds a function library or a function host to the library list maintained by the resident process. The name argument specifies either the name of a function library or the public message port associated with a function host. The name is case-sensitive. Any specified libraries should reside in the system LIBS: directory.

The priority argument specifies the search priority and must be an integer between 100 and -100, inclusive. The offset and version arguments apply only to libraries. The offset is the integer offset to the library's "query" entry point, and the version is an integer specifying the minimum acceptable release level of the library.

The function returns a Boolean result that indicates whether the operation was successful. If a library is specified, it is not actually opened at this time. Similarly, ARexx does not check to see whether a specified function host port is open. See also [[AmigaOS_Manual:_ARexx_Functions#REMLIB.28.29|REMLIB()]]. For example:

<syntaxhighlight lang="rexx">
SAY ADDLIB( "rexxsupport.library", 0, -30, 0 ) -> 1
CALL ADDLIB "EtherNet", -20 /* A gateway */
</syntaxhighlight>

=== ADDRESS() ===

<nowiki>ADDRESS()</nowiki>

Returns the current host address string. The host address is the message port to which commands will be sent. The SHOW() function can be used to check whether the required external host is actually available. See also [[AmigaOS_Manual:_ARexx_Functions#SHOW.28.29|SHOW()]]. For example:

<syntaxhighlight lang="rexx">
SAY ADDRESS() -> REXX
</syntaxhighlight>

=== ARG() ===

<nowiki>ARG([number][,'EXISTS'|'OMITTED'])</nowiki>

ARG() returns the number of arguments supplied to the current environment. If only the number parameter is supplied, the corresponding argument string is returned. If a number and the EXISTS or OMITTED keyword is given, the Boolean return indicates the status of the corresponding argument. The existence or omission test does not indicate whether the string has a null value, but only whether a string was supplied. For example:

<syntaxhighlight lang="rexx">
/*Assume arguments were: ('one',,10)*/
SAY ARG() -> 3
SAY ARG( 1 ) -> one
SAY ARG( 2, 'O' ) -> 1
</syntaxhighlight>

=== B2C() ===

<nowiki>B2C(string)</nowiki>

Converts a string of binary digits (0,1) into the corresponding (packed) character representation. The conversion is the same as though the argument string had been specified as a literal binary string (e.g. '1010'B). Blanks are permitted in the string, but only at byte boundaries. This function is particularly useful for creating strings that are to be used as bit masks. See also [[AmigaOS_Manual:_ARexx_Functions#X2C.28.29|X2C()]]. For example:

<syntaxhighlight lang="rexx">
SAY B2C( '00110011' ) -> 3
SAY B2C( '01100001' ) -> a
</syntaxhighlight>

=== BITAND() ===

<nowiki>BITAND(string1,string2[,pad])</nowiki>

The argument strings are logically ANDed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight lang="rexx">
BITAND( '0313'x, 'FFF0'x ) -> '0310'x
</syntaxhighlight>

=== BITCHG() ===

<nowiki>BITCHG(string,bit)</nowiki>

Changes the state of the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight lang="rexx">
BITCHG( '0313'x, 4 ) -> '0303'x
</syntaxhighlight>

=== BITCLR() ===

<nowiki>BITCLR(string,bit)</nowiki>

Clears (sets to zero) the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight lang="rexx">
BITCLR( '0313'x, 4 ) -> '0303'x
</syntaxhighlight>

=== BITCOMP() ===

<nowiki>BITCOMP(string1,string2[,pad])</nowiki>

Compares the argument strings bit-by-bit, starting at bit number 0. The returned value is the bit number of the first bit in which the strings differ, or -1 if the strings are identical. For example:

<syntaxhighlight lang="rexx">
BITCOMP( '7F'x, 'FF'x ) -> 7 /*Seventh bit*/
BITCOMP( 'FF'x, 'FF'x ) -> -1
</syntaxhighlight>

=== BITOR() ===

<nowiki>BITOR(string1,string2[,pad])</nowiki>

The argument strings are logically ORed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight lang="rexx">
BITOR( '0313'x, '00F'x ) -> '033F'x
</syntaxhighlight>

=== BITSET() ===

<nowiki>BITSET(string,bit)</nowiki>

Sets the specified bit in the argument string to 1. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight lang="rexx">
BITSET( '313'x, 2 ) -> '0317'x
</syntaxhighlight>

=== BITTST() ===

<nowiki>BITTST(string,bit)</nowiki>

The Boolean return indicates the state of the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight lang="rexx">
BITTST( '0313'x, 4 ) -> 1
</syntaxhighlight>

=== BITXOR() ===

<nowiki>BITXOR(string1,string2[,pad])</nowiki>

The argument strings are logically and exclusively-ORed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight lang="rexx">
BITXOR( '0313'x, '001F'x ) -> '030C'X
</syntaxhighlight>

=== C2B() ===

<nowiki>C2B(string)</nowiki>

Converts the character string into the equivalent string of binary digits. See also [[AmigaOS_Manual:_ARexx_Functions#C2X.28.29|C2X()]]. For example:

<syntaxhighlight lang="rexx">
SAY C2B( 'abc' ) -> 011000010110001001100011
</syntaxhighlight>

=== C2D() ===

<nowiki>C2D(string[,n])</nowiki>

Converts the string argument from its character representation to the corresponding decimal number, expressed as ASCII digits (0-9). If n is supplied, the character string is considered to be a number expressed in n bytes. The string is truncated or padded with nulls on the left as required, and the sign bit is extended for the conversion. For example:

<syntaxhighlight lang="rexx">
SAY C2D( '0020'x ) -> 32
SAY C2D( 'FFFF ffff'x ) -> -1
SAY C2D( 'FF0100'x, 2 ) -> 256
</syntaxhighlight>

=== C2X() ===

<nowiki>C2X(string)</nowiki>

Converts the string argument from its character representation to the corresponding hexadecimal number, expressed as the ASCII characters 0-9 and A-F. See also [[AmigaOS_Manual:_ARexx_Functions#C2B.28.29|C2B()]]. For example:

<syntaxhighlight lang="rexx">
SAY C2X( 'abc' ) -> 616263
</syntaxhighlight>

=== CENTER()/CENTRE() ===

<nowiki>CENTER(string,length[,pad])</nowiki>
<nowiki>CENTRE(string,length[,pad])</nowiki>

Centers the string argument in a string with the specified length. If the length is longer than that of the string, pad characters or blanks are added as necessary. For example:

<syntaxhighlight lang="rexx">
SAY CENTER( 'abc', 6 ) -> ' abc '
SAY CENTER( 'abc', 6, '+' ) -> '+abc++'
SAY CENTER( '123456', 3 ) -> '234'
</syntaxhighlight>

=== CLOSE() ===

<nowiki>CLOSE(file)</nowiki>

Closes the file specified by the given logical name. The returned value is a Boolean success flag and will be 1 unless the specified file was not open. For example:

<syntaxhighlight lang="rexx">
SAY CLOSE( 'input' ) -> 1
</syntaxhighlight>

=== COMPARE() ===

<nowiki>COMPARE(string1,string2[,pad])</nowiki>

Compares two strings and returns the index of the first position in which they differ or 0 if the strings are identical. The shorter string is padded as required using the supplied character or blanks. For example:

<syntaxhighlight lang="rexx">
SAY COMPARE( 'abcde', 'abcce' ) -> 4
SAY COMPARE( 'abcde', 'abcde' ) -> 0
SAY COMPARE( 'abc++', 'abc+-', '+' ) -> 5
</syntaxhighlight>

=== COMPRESS() ===

<nowiki>COMPRESS(string[,list])</nowiki>

If the list argument is omitted, the function removes leading, trailing or embedded blank characters from the string argument. If the optional list is supplied, it specifies the characters to be removed from the string. For example:

<syntaxhighlight lang="rexx">
SAY COMPRESS( ' why not ' ) -> whynot
SAY COMPRESS( '++12-34-+', '+-' ) -> 1234
</syntaxhighlight>

=== COPIES() ===

<nowiki>COPIES(string,number)</nowiki>

Creates a new string by concatenating the specified number of copies of the original. The number argument may be zero, in which case the null string is returned. For example:

<syntaxhighlight lang="rexx">
SAY COPIES( 'abc', 3 ) -> abcabcabc
</syntaxhighlight>

=== D2C() ===

<nowiki>D2C(number)</nowiki>

Creates a string whose value is the binary (packed) representation of the given decimal number. For example:

<syntaxhighlight lang="rexx">
D2C( 65 ) -> A
</syntaxhighlight>

=== D2X() ===

<nowiki>D2X(number[,digits])</nowiki>

Converts a decimal number to hexadecimal. For example:

<syntaxhighlight lang="rexx">
D2X( 31 ) -> 1F
</syntaxhighlight>

=== DATATYPE() ===

<nowiki>DATATYPE(string[,option])</nowiki>

If only the string argument is specified, DATATYPE() tests whether the string parameter is a valid number and returns either NUM or CHAR. If an option keyword is given, the Boolean return indicates whether the string satisfied the requested test. The following option keywords are recognized:

; ALPHANUMERIC
: Accepts alphabetic (A-Z, a-z) or numeric (0-9) characters

; BINARY
: Accepts a binary digits string

; LOWERCASE
: Accepts lower case alphabetic (a-z) characters

; MIXED
: Accepts mixed upper/lower case characters

; NUMERIC
: Accepts valid numbers

; SYMBOL
: Accepts valid REXX symbols

; UPPER
: Accepts upper case alphabetic (A-Z) characters

; WHOLE
: Accepts integer numbers

; X
: Accepts Hex digit strings

For example:

<syntaxhighlight lang="rexx">
SAY DATATYPE( '123' ) -> NUM
SAY DATATYPE( '1a f2', 'X' ) -> 1
SAY DATATYPE( 'aBcde', 'L' ) -> 0
</syntaxhighlight>

=== DATE() ===

<nowiki>DATE([option][,date][format])</nowiki>

Returns the current date in the specified format. The default ('NORMAL') option returns the date in the form DD MMM YYYY, as in 20 APR 1988. The options recognized are:

; BASEDATE
: The number of days since January 1, 0001

; CENTURY
: The number of days since January 1 of the century

; DAYS
: The number of days since January 1 of the current year

; EUROPEAN
: The date in the form DD/MM/YY

; INTERNAL
: Internal system days

; JULIAN
: The date in the form YYDDD

; MONTH
: The current month (in mixed case)

; NORMAL
: The date in the form DD MMM YYYY

; ORDERED
: The date in the form YY/MM/DD

; SORTED
: The date in the form YYYYMMDD

; USA
: The date in the form MM/DD/YY

; WEEKDAY
: The day of the week (in mixed case)

These options can be shortened to just the first character.

The DATE() function also accepts optional second and third arguments to supply the date either in the form of internal system days or in the 'sorted' form YYYYMMDD. The second argument is specifying either system days (the default) or a sorted date. The third argument specifies the form of the date and can be either 'I' or 'S'. The current date in system days can be retrieved using DATE('INTERNAL'). For example:

<syntaxhighlight lang="rexx">
SAY DATE() -> 14 Jul 1992
SAY DATE( 'M' ) -> July
SAY DATE( S ) -> 19920714
SAY DATE( 'S', DATE( 'I' ) + 21 ) -> 19920804
SAY DATE( 'W', 19890609, 'S' ) -> Friday
</syntaxhighlight>

=== DELSTR() ===

<nowiki>DELSTR(string,n[,length])</nowiki>

Deletes the substring of the string argument beginning with the nth character for the specified length in characters. The default length is the remaining length of the string. For example:

<syntaxhighlight lang="rexx">
SAY DELSTR( '123456', 2, 3 ) -> 156
</syntaxhighlight>

=== DELWORD() ===

<nowiki>DELWORD(string,n[,length])</nowiki>

Deletes the substring of the string argument beginning with the nth word for the specified length in words. The default length is the remaining length of the string. The deleted string includes any trailing blanks following the last word. For example:

<syntaxhighlight lang="rexx">
SAY DELWORD( 'Tell me a story', 2, 2 ) -> 'Tell story'
SAY DELWORD( 'one two three', 3 ) -> 'one two '
</syntaxhighlight>

=== DIGITS() ===

<nowiki>DIGITS()</nowiki>

Returns the current Numeric Digits setting. For example:

<syntaxhighlight lang="rexx">
NUMERIC DIGITS 6
SAY DIGITS() -> 6
</syntaxhighlight>

=== EOF() ===

<nowiki>EOF(file)</nowiki>

Checks the specified logical file name and returns the Boolean value 1 (True), if the end-of-file has been reached, and 0 (False) otherwise. For example:

<syntaxhighlight lang="rexx">
SAY EOF( infile ) -> 1
</syntaxhighlight>

=== ERRORTEXT() ===

<nowiki>ERRORTEXT(n)</nowiki>

Returns the error message associated with the specified ARexx error code. The null string is returned if the number is not a valid error code. For example:

<syntaxhighlight lang="rexx">
SAY ERRORTEXT( 41 ) -> Invalid expression
</syntaxhighlight>

=== EXISTS() ===

<nowiki>EXISTS(filename)</nowiki>

Tests whether an external file of the given filename exists. The name string may include device and directory specifications. For example:

<syntaxhighlight lang="rexx">
SAY EXISTS( 'SYS:C/ED' ) -> 1
</syntaxhighlight>

=== EXPORT() ===

<nowiki>EXPORT(address[,string][,length][,pad])</nowiki>

Copies data from the optional string into a previously-allocated memory area. This memory area must be specified as a four-byte address. The length parameter specifies the maximum number of characters to be copied. The default is the length of the string. If the specified length is longer than the string, the remaining area is filled with the pad character or nulls ('00'x). The returned value is the number of characters copied.

{{Note|title=Caution|text=Any area of memory can be overwritten, possibly causing a system crash. Task switching is forbidden while the copy is being done, so system performance may be degraded if long strings are copied.}}

See also [[AmigaOS_Manual:_ARexx_Functions#IMPORT.28.29|IMPORT()]] and [[AmigaOS_Manual:_ARexx_Functions#STORAGE.28.29|STORAGE()]]. For example:

<syntaxhighlight lang="rexx">
count = EXPORT( '0004 0000'x, 'The answer' )
</syntaxhighlight>

=== FIND() ===

<nowiki>FIND(string,phrase)</nowiki>

The FIND() function locates a phrase of words in a larger string of words and returns the word number of the matched position. For example:

<syntaxhighlight lang="rexx">
SAY FIND( 'Now is the time', 'is the' ) -> 2
</syntaxhighlight>

=== FORM() ===

<nowiki>FORM()</nowiki>

Returns the current NUMERIC FORM setting. For example:

<syntaxhighlight lang="rexx">
NUMERIC FORM SCIENTIFIC
SAY FORM() -> SCIENTIFIC
</syntaxhighlight>

=== FREESPACE() ===

<nowiki>FREESPACE(address,length)</nowiki>

Returns a block of memory of a given length to the interpreter's internal pool. The address argument must be a 4 byte string obtained by a prior call to GETSPACE(), the internal allocator. It is not always necessary to release internally allocated memory, since it will be released to the system when the program terminates. However, if a very large block has been allocated, returning it to the pool may avoid memory space problems. The return value is a Boolean success flag. See also [[AmigaOS_Manual:_ARexx_Functions#GETSPACE.28.29|GETSPACE()]].

Calling FREESPACE() with no arguments will return the amount of memory available in the interpreter's internal pool. For example:

<syntaxhighlight lang="rexx">
FREESPACE( '00042000'x, 32 ) -> 1
</syntaxhighlight>

=== FUZZ() ===

<nowiki>FUZZ()</nowiki>

Returns the current [[AmigaOS_Manual:_ARexx_Instructions#NUMERIC|NUMERIC FUZZ]] setting. For example:

<syntaxhighlight lang="rexx">
NUMERIC FUZZ 3
SAY FUZZ() -> 3
</syntaxhighlight>

=== GETCLIP() ===

<nowiki>GETCLIP(name)</nowiki>

Searches the Clip List for an entry matching the supplied name parameter and returns the associated value string. The name matching is case-sensitive. The null string is returned if the name cannot be found. See also [[AmigaOS_Manual:_ARexx_Functions#SHOW.28.29|SHOW()]] and [[AmigaOS_Manual:_ARexx_Functions#SETCLIP.28.29|SETCLIP()]]. For example:

<syntaxhighlight lang="rexx">
/*Assume 'numbers' contains 'PI=3.14159'*/
SAY GETCLIP( 'numbers' ) -> PI=3.14159
</syntaxhighlight>

=== GETSPACE() ===

<nowiki>GETSPACE(length)</nowiki>

Allocates a block of memory of the specified length from the interpreter's internal pool. The returned value is the four-byte address of the allocated block, which is not cleared or otherwise initialized. Internal memory is automatically returned to the system when the ARexx program terminates, so this function should not be used to allocate memory for use by external programs. The REXXSupport.Library includes the function ALLOCMEM(), which allocates memory from the system free list. See also [[AmigaOS_Manual:_ARexx_Functions#FREESPACE.28.29|FREESPACE()]]. For example:

<syntaxhighlight lang="rexx">
SAY C2X( GETSPACE( 32 ) ) -> '0003BF40'x
</syntaxhighlight>

=== HASH() ===

<nowiki>HASH(string)</nowiki>

Returns the hash attribute of a string as a decimal number and updates the internal hash value of the string. For example:

<syntaxhighlight lang="rexx">
SAY HASH( '1' ) -> 49
</syntaxhighlight>

=== IMPORT() ===

<nowiki>IMPORT(address[,length])</nowiki>

Creates a string by copying data from the specified four-byte address. If the length parameter is not supplied, the copy terminates when a null byte is found. See also [[AmigaOS_Manual:_ARexx_Functions#EXPORT.28.29|EXPORT()]]. For example:

<syntaxhighlight lang="rexx">
extval = IMPORT( '0004 0000'x, 8 )
</syntaxhighlight>

=== INDEX() ===

<nowiki>INDEX(string,pattern[,start])</nowiki>

Searches for the first occurrence of the pattern argument in the string argument, beginning at the specified start position. The default start position is 1. The returned value is the index of the matched pattern or 0 if the pattern was not found. For example:

<syntaxhighlight lang="rexx">
SAY INDEX( "123456", "23" ) -> 2
SAY INDEX( "123456", "77" ) -> 0
SAY INDEX( "123123", "23", 3 ) -> 5
</syntaxhighlight>

=== INSERT() ===

<nowiki>INSERT(new,old[,start][,length][,pad])</nowiki>

Inserts the new string into the old string after the specified start position. The default starting position is 0. The new string is truncated or padded to the specified length as required, using the supplied pad character or blanks. If the start position is beyond the end of the string, the old string is padded on the right. For example:

<syntaxhighlight lang="rexx">
SAY INSERT( 'ab', '12345' ) -> ab12345
SAY INSERT( '123', '++', 3, 5, '-' ) -> ++-123--
</syntaxhighlight>

=== LASTPOS() ===

<nowiki>LASTPOS(pattern,string[,start])</nowiki>

Searches backwards for the first occurrence of the pattern argument in the string argument, beginning at the specified start position. The default starting position is the end of the string. The returned value is the index of the matched pattern or 0 if the pattern was not found. For example:

<syntaxhighlight lang="rexx">
SAY LASTPOS( '2', '1234' ) -> 2
SAY LASTPOS( '2', '1234234' ) -> 5
SAY LASTPOS( '2', '123234', 3 ) -> 2
SAY LASTPOS( '2', '13579' ) -> 0
</syntaxhighlight>

=== LEFT() ===

<nowiki>LEFT(string,length[,pad])</nowiki>

Returns the leftmost substring in the given string argument with the specified length. If the substring is shorter than the requested length, it is padded on the right with the supplied pad character or blanks. For example:

<syntaxhighlight lang="rexx">
SAY LEFT( '123456', 3 ) -> 123
SAY LEFT( '123456', 8, '+' ) -> 123456++
</syntaxhighlight>

=== LENGTH() ===

<nowiki>LENGTH(string)</nowiki>

Returns the length of the string. For example:

<syntaxhighlight lang="rexx">
SAY LENGTH( 'three' ) -> 5
</syntaxhighlight>

=== LINES() ===

<nowiki>LINES(file)</nowiki>

Returns the number of lines queued or typed ahead at the logical file, which must refer to an interactive stream. The line count is obtained as the secondary result of a [http://wiki.amigaos.net/amiga/autodocs/dos.doc.txt dos library's] '''WaitForChar()''' call. For example:

<syntaxhighlight lang="rexx">
PUSH 'a line'
PUSH 'another one'
SAY LINES( STDIN ) -> 2
</syntaxhighlight>

=== MAX() ===

<nowiki>MAX(number,number[,number,...])</nowiki>

Returns the maximum of the supplied arguments, all of which must be numeric. At least two parameters must be supplied. For example:

<syntaxhighlight lang="rexx">
SAY MAX( 2.1, 3, -1 ) -> 3
</syntaxhighlight>

=== MIN() ===

<nowiki>MIN(number,number[,number,...])</nowiki>

Returns the minimum of the supplied arguments, all of which must be numeric. At least two parameters must be supplied. For example:

<syntaxhighlight lang="rexx">
SAY MIN( 2.1, 3, -1 ) -> -1
</syntaxhighlight>

=== OPEN() ===

<nowiki>OPEN(file,filename[,'APPEND'|'READ'|'WRITE'])</nowiki>

Opens an external file for the specified operation. The ''file'' argument defines the logical name by which the file will be referenced. STDIN and STDOUT are logical files that are available by default. The ''filename'' is the external name of the file and may include device and directory specifications. The function returns a Boolean value that indicates whether the operation was successful. There is no limit to the number of files that can be open simultaneously, and all open files are closed automatically when the program exits. See also [[AmigaOS_Manual:_ARexx_Functions#CLOSE.28.29|CLOSE()]], [[AmigaOS_Manual:_ARexx_Functions#READCH.28.29|READCH()]], [[AmigaOS_Manual:_ARexx_Functions#READLN.28.29|READLN()]], [[AmigaOS_Manual:_ARexx_Functions#WRITECH.28.29|WRITECH()]], and [[AmigaOS_Manual:_ARexx_Functions#WRITELN.28.29|WRITELN()]]. For example:

<syntaxhighlight lang="rexx">
SAY OPEN( 'MyCon', 'CON:160/50/320/100/MyCON/cds' ) -> 1
SAY OPEN( 'outfile', 'ram:temp', 'W' ) -> 1
</syntaxhighlight>

=== OVERLAY() ===

<nowiki>OVERLAY(new,old[,start][,length][,pad])</nowiki>

Overlays the new string onto the old string beginning at the specified start position, which must be positive. The default starting position is 1. The new string is truncated or padded to the specified length as required, using the supplied pad character or blanks. If the start position is beyond the end of the old string, the old string is padded on the right. For example:

<syntaxhighlight lang="rexx">
SAY OVERLAY( 'bb', 'abcd' ) -> bbcd
SAY OVERLAY( '4', '123', 5, 5, '-' ) -> 123-4----
</syntaxhighlight>

=== POS() ===

<nowiki>POS(pattern,string[,start])</nowiki>

Searches for the first occurrence of the pattern argument in the string argument, beginning at the position specified by the start argument. The default starting position is 1. The value is the index of the matched string or 0 if the pattern wasn't found. For example:

<syntaxhighlight lang="rexx">
SAY POS('23', '123234') -> 2
SAY POS('77', '123234') -> 0
SAY POS('23', '123234',3) -> 4
</syntaxhighlight>

=== PRAGMA() ===

<nowiki>PRAGMA(option[,value])</nowiki>

This function allows a program to change various attributes relating to the system environment within which the program executes. The option argument is a keyword that specifies an environmental attribute. The value argument supplies the new attribute value to be installed. The value returned by the function depends on the attribute selected. Some attributes return the previous value installed, while others may simply set a Boolean success flag.

The currently defined option keywords are:

; DIRECTORY
: Specifies a new current directory. The current directory is used as the root for filenames that do not explicitly include a device specification. The return is the old directory name. PRAGMA('D') is equivalent to PRAGMA('D',"). It returns the path of the current directory without changing the directory.

; PRIORITY
: Specifies a new task priority. The priority value must be an integer in the range - 128 to 127, but the practical range is much more limited. ARexx programs should never be run at a priority higher than that of the resident process, which currently runs at a priority of 4. The returned value is the previous priority level.

; ID
: Returns the task ID (the address of the task block) as an 8-character hex string. The task ID is a unique identifier of the particular ARexx invocation and may be used to create a unique name for it.

; STACK
: Specifies a new stack value for your current ARexx program. When a new stack value is declared, the previous stack value is returned.

The currently implemented options are:

; PRAGMA('W',{'NULL'|' WORKBENCH'})
: Controls the task's WindowPtr field. Setting it to 'NULL' will suppress any requesters that might otherwise be generated by a DOS call.

; PRAGMA('*'[,name])
: Defines the specified logical name as the current ("*") console handler, allowing the user to open two streams on one window. If the name is omitted, the console handler is set to that of the client's process.

<syntaxhighlight lang="rexx">
SAY PRAGMA( 'D', 'DF0:C') -> Extras
SAY PRAGMA( 'D', 'DF1:C') -> Workbench:C
SAY PRAGMA( 'PRIORITY', -5) -> 0
SAY PRAGMA( 'ID') -> 00221ABC
CALL PRAGMA '*', STDOUT
SAY PRAGMA( "STACK", 8092 ) -> 4000
</syntaxhighlight>

=== RANDOM() ===

<nowiki>RANDOM([MIN][,MAX][,seed])</nowiki>

Returns a pseudo-random integer in the interval specified by the min and max arguments. The default minimum value is 0 and the default maximum value is 999. The interval max-min must be less than or equal to 1000. If a greater range of random integers is required, the values from the RANDU() function can be suitably scaled and translated. The seed argument can be supplied to initialize the internal state of the random number generator. See also [[AmigaOS_Manual:_ARexx_Functions#RANDU.28.29|RANDU()]]. For example:

<syntaxhighlight lang="rexx">
thisroll = RANDOM( 1, 6 ) /*Might be 1*/
nextroll = RANDOM( 1, 6 ) /*Might be snake eyes*/
</syntaxhighlight>

=== RANDU() ===

<nowiki>RANDU([seed])</nowiki>

Returns a uniformly-distributed, pseudo-random number between 0 and 1. The number of digits of precision in the result is always equal to the current Numeric Digits setting. With the choice of suitable scaling and translation values, RANDU() can be used to generate pseudo-random numbers on an arbitrary interval.

The optional integer seed argument is used to initialize the internal state of the random number generator. See also [[AmigaOS_Manual:_ARexx_Functions#RANDOM.28.29|RANDOM()]]. For example:

<syntaxhighlight lang="rexx">
firsttry = RANDU() /*0.371902021?*/
NUMERIC DIGITS 3
tryagain = RANDU() /*0.873?*/
</syntaxhighlight>

=== READCH() ===

<nowiki>READCH(file,length)</nowiki>

Reads the specified number of characters from the given logical file into a string. The length of the returned string is the actual number of characters read and may be less than the requested length if, for example, the end-of-file was reached. See also [[AmigaOS_Manual:_ARexx_Functions#READLN.28.29|READLN()]]. For example:

<syntaxhighlight lang="rexx">
instring = READCH( 'input', 10 )
</syntaxhighlight>

=== READLN() ===

<nowiki>READLN(file)</nowiki>

Reads characters from the given logical file into a string until a newline character is found. The returned string does not include the newline. See also [[AmigaOS_Manual:_ARexx_Functions#READCH.28.29|READCH()]]. For example:

<syntaxhighlight lang="rexx">
instring = READLN( 'MyFile' )
</syntaxhighlight>

=== REMLIB() ===

<nowiki>REMLIB(name)</nowiki>

Removes an entry with the given name from the Library List maintained by the resident process. The Boolean return is 1 if the entry was found and successfully removed. This function does not make a distinction between function libraries and function hosts, but simply removes a named entry. See also [[AmigaOS_Manual:_ARexx_Functions#ADDLIB.28.29|ADDLIB()]]. For example:

<syntaxhighlight lang="rexx">
SAY REMLIB( 'MyLibrary.library' ) -> 1
</syntaxhighlight>

=== REVERSE() ===

<nowiki>REVERSE(string)</nowiki>

Reverses the sequence of characters in the string. For example:

<syntaxhighlight lang="rexx">
SAY REVERSE( '?ton yhw' ) -> why not?
</syntaxhighlight>

=== RIGHT() ===

<nowiki>RIGHT(string,length[,pad])</nowiki>

Returns the rightmost substring in the given string argument with the specified length. If the substring is shorter than the requested length, it is padded on the left with the supplied pad character or blanks. For example:

<syntaxhighlight lang="rexx">
SAY RIGHT( '123456', 4 ) -> 3456
SAY RIGHT( '123456', 8, '+' ) -> ++123456
</syntaxhighlight>

=== SEEK() ===

<nowiki>SEEK(file,offset[,'BEGIN'|'CURRENT'|'END'])</nowiki>

Moves to a new position in the given logical file, specified as an offset from an anchor position. The default anchor is Current. The returned value is the new position relative to the start of the file. For example:

<syntaxhighlight lang="rexx">
SAY SEEK( 'input', 10, 'B' ) -> 10
SAY SEEK( 'input', 0, 'E' ) -> 356 /*file length*/
</syntaxhighlight>

=== SETCLIP() ===

<nowiki>SETCLIP(name[,value])</nowiki>

Adds a name-value pair to the Clip List maintained by the resident process. If an entry of the same name already exists, its value is updated to the supplied value string. Entries may be removed by specifying a null value. The function returns a Boolean value that indicates whether the operation was successful. See also [[AmigaOS_Manual:_ARexx_Functions#GETCLIP.28.29|GETCLIP()]]. For example:

<syntaxhighlight lang="rexx">
SAY SETCLIP( 'path', 'DF0:s' ) -> 1
SAY SETCLIP( 'path' ) -> 1
</syntaxhighlight>

=== SHOW() ===

<nowiki>SHOW(option[,name][,pad])</nowiki>

Returns the names in the resource list specified by the option argument, or tests to see whether an entry with the specified name is available. The currently implemented options keywords are:

; CLIP
: Examines the names in the Clip List

; FILES
: Examines the currently open logical file names

; LIBRARIES
: Examines the names in the Library List, which are either function libraries or function hosts.

; PORTS
: Examines the names in the system Ports List

If the name argument is omitted, the function returns a string with the resource names separated by a blank space or the pad character, if one was supplied. If the name argument is given, the returned Boolean value indicates whether the name was found in the resource list. The name entries are case-sensitive.

=== SIGN() ===

<nowiki>SIGN(number)</nowiki>

Returns 1 if the number argument is positive or zero and -1 if the number is negative. The argument must be numeric. For example:

<syntaxhighlight lang="rexx">
SAY SIGN( 12 ) -> 1
SAY SIGN( -33 ) -> -1
</syntaxhighlight>

=== SOURCELINE() ===

<nowiki>SOURCELINE([line])</nowiki>

Returns the text for the specified line of the currently executing ARexx program. If the line argument is omitted, the function returns the total number of lines in the file. This function is often used to embed "help" information in a program. For example:

<syntaxhighlight lang="rexx">
/*A simple test program*/
SAY SOURCELINE() -> 3
SAY SOURCELINE( 1 ) -> /*A simple test program*/
</syntaxhighlight>

=== SPACE() ===

<nowiki>SPACE(string,n[,pad])</nowiki>

Reformats the string argument so that there are n spaces (blank characters) between each pair of words. If the pad character is specified, it is used instead of blanks as the separator character. Specifying n as 0 will remove all blanks from the string. For example:

<syntaxhighlight lang="rexx">
SAY SPACE( 'Now is the time', 3 ) -> 'Now is the time'
SAY SPACE( 'Now is the time', 0 ) -> 'Nowisthetime'
SAY SPACE( '1 2 3', 1, '+' ) -> '1+2+3'
</syntaxhighlight>

=== STORAGE() ===

<nowiki>STORAGE([address][,string][,length][,pad])</nowiki>

STORAGE() with no arguments returns the available system memory. If the address argument is given, it must be a four-byte string. The function copies data from the (optional) string to the indicated memory address. The length parameter specifies the maximum number of bytes to be copied and defaults to the length of the string. If the specified length is longer than the string, the remaining area is filled with the pad character or nulls ('00'x).

The returned value is the previous contents of the memory area. This can be used in a subsequent call to restore the original contents. See also [[AmigaOS_Manual:_ARexx_Functions#EXPORT.28.29|EXPORT()]].

{{Note|title=Caution|text=Any area of memory can be overwritten, possibly causing a system crash. Task switching is forbidden while the copy is being done, so system performance may be degraded if long strings are copied.}}

For example:

<syntaxhighlight lang="rexx">
SAY STORAGE() -> '248400'
oldval = STORAGE( '0004 0000'x, 'The answer' )
CALL STORAGE '0004 0000'x, , 32, '+'
</syntaxhighlight>

=== STRIP() ===

<nowiki>STRIP(string[,{'B' | 'L' | 'T'}][,pad])</nowiki>

If neither of the optional parameters is supplied, the function removes both leading and trailing blanks from the string argument. The second argument specifies whether Leading, Trailing or Both (leading and trailing) characters are to be removed. The optional pad (or unpad) argument selects the character to be removed. For example:

<syntaxhighlight lang="rexx">
SAY STRIP( ' say what? ') -> 'say What?'
SAY STRIP( ' say what? ', 'L' ) -> 'say what?'
SAY STRIP( '++123+++', 'B', '+' ) -> '123'
</syntaxhighlight>

=== SUBSTR() ===

<nowiki>SUBSTR(string,start[,length][,pad])</nowiki>

Returns the substring of the string argument beginning at the specified start position for the specified length. The starting position must be positive, and the default length is the remaining length of the string. If the substring is shorter than the requested length, it is padded on the right with the blanks or the specified pad character. For example:

<syntaxhighlight lang="rexx">
SAY SUBSTR( '123456', 4, 2 ) -> 45
SAY SUBSTR( 'myname', 3, 6, '=' ) -> 'name=='
</syntaxhighlight>

=== SUBWORD() ===

<nowiki>SUBWORD(string,n[,length])</nowiki>

Returns the substring of the string argument beginning with the nth word for the specified length in words. The default length is the remaining length of the string. The returned string will never have leading or trailing blanks. For example:

<syntaxhighlight lang="rexx">
SAY SUBWORD( 'Now is the time ', 2, 2 ) -> 'is the'
</syntaxhighlight>

=== SYMBOL() ===

<nowiki>SYMBOL(name)</nowiki>

Tests whether the name argument is a valid ARexx symbol. If the name is not a valid symbol, the function returns the string BAD. If the symbol is uninitialized, the returned string is LIT. If the symbol has been assigned a value, VAR is returned. For example:

<syntaxhighlight lang="rexx">
SAY SYMBOL( 'J' ) -> 'VAR'
SAY SYMBOL( 'x' ) -> 'LIT'
SAY SYMBOL( '++' ) -> 'BAD'
</syntaxhighlight>

=== TIME() ===

<nowiki>TIME(option)</nowiki>

Returns the current system time or controls the internal elapsed time counter. The valid option keywords are:

; CIVIL
: Current time in 12 hour format (a.m./p.m.) hours/minutes

; ELAPSED
: Elapsed time in seconds since program start

; HOURS
: Current time in hours since midnight

; MINUTES
: Current time in minutes since midnight

; NORMAL
: Current time in 24 hour format (hours/minutes/seconds)

; RESET
: Reset the elapsed time clock

; SECONDS
: Current time in seconds since midnight

If no option is specified, the function returns the current system time in the form HH:MM:SS. For example:

<syntaxhighlight lang="rexx">
/*Suppose that the time is 1:02 AM . . .*/
SAY TIME( 'C' ) -> '1:02 AM'
SAY TIME( 'HOURS' ) -> 1
SAY TIME( 'M' ) -> 62
SAY TIME( 'N' ) -> '01:02:54'
SAY TIME( 'S' ) -> 3720
call TIME( 'R' ) /*reset timer*/
SAY TIME( 'E' ) -> .020
SAY TIME() -> '01:02:00'
</syntaxhighlight>

=== TRACE() ===

<nowiki>TRACE(option)</nowiki>

Sets the tracing mode (see [[AmigaOS Manual: ARexx Debugging|Chapter 6. Debugging]]) to that specified by the option keyword, which must be one of the valid alphabetic or prefix options. The TRACE() function will alter the tracing mode even during interactive tracing, when TRACE instructions in the source program are ignored. The returned value is the mode in effect before the function call. This allows the previous trace mode to be restored later. For example:

<syntaxhighlight lang="rexx">
/*Assume tracing mode is ALL*/
SAY TRACE( 'Results' ) -> A
</syntaxhighlight>

=== TRANSLATE() ===

<nowiki>TRANSLATE(string[,output][,input][,pad])</nowiki>

This function constructs a translation table and uses it to replace selected characters in the argument string. If only the string argument is given, it is translated to upper case. If an input table is supplied, it modifies the translation table so that characters in the argument string that occur in the input table are replaced with the corresponding character in the output table. Characters beyond the end of the output table are replaced with the specified pad character or a blank. The result string is always of the same length as the original string. The input and output tables may be of any length. For example:

<syntaxhighlight lang="rexx">
SAY TRANSLATE( "abcde", "123", "cbade", "+" ) -> 321++
SAY TRANSLATE( "low" ) -> LOW
SAY TRANSLATE( "0110", "10", "01" ) -> 1001
</syntaxhighlight>

=== TRIM() ===

<nowiki>TRIM(string)</nowiki>

Removes trailing blanks from the string argument. For example:

<syntaxhighlight lang="rexx">
SAY LENGTH( TRIM( ' abc ' ) ) -> 4
</syntaxhighlight>

=== TRUNC() ===

<nowiki>TRUNC(number[,places])</nowiki>

Returns the integer part of the number argument followed by the specified number of decimal places. The default number of decimal places is 0. The number is padded with zeroes as necessary. For example:

<syntaxhighlight lang="rexx">
SAY TRUNC( 123.456 ) -> 123
SAY TRUNC( 123.456, 4 ) -> 123.4560
</syntaxhighlight>

=== UPPER() ===

<nowiki>UPPER(string)</nowiki>

Translate the string to upper case. The action of this function is equivalent to that of TRANSLATE(string), but it is slightly faster for short strings. For example:

<syntaxhighlight lang="rexx">
SAY UPPER( 'One Fine Day' ) -> ONE FINE DAY
</syntaxhighlight>

=== VALUE() ===

<nowiki>VALUE(name)</nowiki>

Returns the value of the symbol represented by the name argument. For example:

<syntaxhighlight lang="rexx">
/*Assume that J has the value 12*/
SAY VALUE( 'j' ) -> 12
</syntaxhighlight>

=== VERIFY() ===

<nowiki>VERIFY(string,list[,'MATCH'])</nowiki>

Returns the index of the first character in the string argument which is not contained in the list argument or 0 if all of the characters are in the list. If the MATCH keyword is supplied, the function returns the index of the first character which is in the list or 0 if none of the characters is in the list. For example:

<syntaxhighlight lang="rexx">
SAY VERIFY( '123456', '0123456789' ) -> 0
SAY VERIFY( '123a56', '0123456789' ) -> 4
SAY VERIFY( '123a45', 'abcdefghij', 'm' ) -> 4
</syntaxhighlight>

=== WORD() ===

<nowiki>WORD(string,n)</nowiki>

Returns the nth word in the string argument or the null string if there are fewer than n words. For example:

<syntaxhighlight lang="rexx">
SAY WORD( 'Now is the time ', 2 ) -> is
</syntaxhighlight>

=== WORDINDEX() ===

<nowiki>WORDINDEX(string,n)</nowiki>

Returns the starting position of the nth word in the argument string or 0 if there are fewer than n words. For example:

<syntaxhighlight lang="rexx">
SAY WORDINDEX( 'Now is the time ', 3 ) -> 8
</syntaxhighlight>

=== WORDLENGTH() ===

<nowiki>WORDLENGTH(string,n)</nowiki>

Returns the length of the nth word in the string argument. For example:

<syntaxhighlight lang="rexx">
SAY WORDLENGTH( 'one two three', 3 ) -> 5
</syntaxhighlight>

=== WORDS() ===

<nowiki>WORDS(string)</nowiki>

Returns the number of words in the string argument. For example:

<syntaxhighlight lang="rexx">
SAY WORDS( "You don't SAY!" ) -> 3
</syntaxhighlight>

=== WRITECH() ===

<nowiki>WRITECH(file,string)</nowiki>

Writes the string argument to the given logical file. The returned value is the actual number of characters written. For example:

<syntaxhighlight lang="rexx">
SAY WRITECH( 'output', 'Testing' ) -> 7
</syntaxhighlight>

=== WRITELN() ===

<nowiki>WRITELN(file,string)</nowiki>

Writes the string argument to the given logical file with a newline appended. The returned value is the actual number of characters written. For example:

<syntaxhighlight lang="rexx">
SAY WRITELN( 'output', 'Testing' ) -> 8
</syntaxhighlight>

=== X2C() ===

<nowiki>X2C(string)</nowiki>

Converts a string of hex digits into the (packed) character representation. Blank characters are permitted in the argument string at byte boundaries. For example:

<syntaxhighlight lang="rexx">
SAY X2C( '12ab' ) -> '12ab'x
SAY X2C( '12 ab' ) -> '12ab'x
SAY X2C( 61 ) -> a
</syntaxhighlight>

=== X2D() ===

<nowiki>X2D(hex[,digits])</nowiki>

Converts a hexadecimal number to decimal. For example:

<syntaxhighlight lang="rexx">
SAY X2D( '1f' ) -> 31
</syntaxhighlight>

=== XRANGE() ===

<nowiki>XRANGE([start][,end])</nowiki>

Generates a string consisting of all characters numerically between the specified start and end values. The default start character is '00'x, and the default end character is 'FF'x. Only the first character of the start and end arguments is significant. For example:

<syntaxhighlight lang="rexx">
SAY XRANGE() -> '00010203 . . . FDFEFF'x
SAY XRANGE( 'a', 'f' ) -> 'abcdef'
SAY XRANGE( , '0A'x ) -> '000102030405060708090A'x
</syntaxhighlight>

== Example Program ==

The following example program illustrates many of the built-in functions that manipulate character strings.

=== Program 13. Changestrings.rexx ===

<syntaxhighlight lang="rexx">
/*This ARexx program shows the effect of built-in functions that change strings. The functions come in two groups: one that manipulates individual characters and one that manipulates whole strings.*/

teststring1 = " every good boy does fine "

/*The first group is composed of the functions STRIP(), COMPRESS(), SPACE(), TRIM(), TRANSLATE(), DELSTR(), DELWORD(), INSERT(), OVERLAY(), and REVERSE().*/

/*STRIP() removes only leading and trailing characters.*/

/*Print the original string, for comparison. We put a period at the end of the string, so you can see what happens to the spaces at the end of the string.*/
SAY " every good boy does fine "

/*The same string stripped of leading and trailing spaces*/
SAY STRIP( " every good boy does fine " )"."

/*Failed attempt to remove leading and trailing "e"s*/
SAY STRIP( " every good boy does fine", , "e" )"."

/*The "e"'s were protected by the leading and trailing spaces. Removing them exposes the "e"'s to the effects of STRIP()*/
SAY STRIP( "every good boy does fine", , "e" )"."

/*Remove "e"'s and spaces from the original string*/
SAY STRIP( " every good boy does fine ", , " e" )"."

/*We are now using the variable "teststring1", defined above. Remove only the trailing spaces in the test string.*/
SAY STRIP( teststring1, T )"."

/*Remove the trailing spaces and the "e"*/
SAY STRIP( teststring1, T, " e" )"."

/*Compress() removes characters anywhere in the string. This removes all blanks from the test string*/
SAY COMPRESS( teststring1 )

CALL TIME( 'r' )
SAY TIME( 'Civil' ) /*Civilian time HH:MM{AM | PM}*/
SAY TIME( 'h' ) /*Hours since midnight*/
SAY TIME( 'm' ) /*Minutes since midnight*/
SAY TIME( 's' ) /*Seconds since midnight*/
SAY TIME( 'e' ) /*Elapsed time since program start*/

/*Function:TRACE Usage: TRACE( [option] )*/
SAY TRACE()
SAY TRACE( TRACE() ) /*Leave it unchanged*/

/*Function:TRANSLATE Usage: TRANSLATE(string[,output][,input] [,pad])*/
SAY TRANSLATE( 'aBCdef' ) /*Translate to Uppercase*/
SAY TRANSLATE( 'abcdef', '1234' )
SAY TRANSLATE( '654321', 'abcdef', '123456' )
SAY TRANSLATE( 'abcdef', '123', 'abcdef', '+' )

/*Function: TRIM Usage: TRIM(string)*/
SAY TRIM( ' abc ' )

/*Function: TRUNC Usage: TRUNC(number[,places])*/
SAY TRUNC( 123.456 )
SAY '$'TRUNC( 134566.123, 2 )

/*Function: UPPER Usage: UPPER(string)*/
SAY UPPER( 'aBCdef12' )

/*Function: VALUE Usage: VALUE(name)*/
abc = 'my name'
SAY VALUE( 'abc' )

/*Function: VERIFY Usage: VERIFY(string,list[,'M'])*/
SAY VERIFY( '123a45', '0123456789' )
SAY VERIFY( 'abc3de', '012456789', 'M' )

/*Function: WORD Usage: WORD(string,n)*/
SAY WORD( 'Now is the time', 3 )

/*Function: WORDINDEX Usage: WORDINDEX(string,n)*/
SAY WORDINDEX( 'Now is the time ', 3 )

/*Function: WORDLENGTH Usage: WORDLENGTH(string,n)*/
SAY WORDLENGTH( 'Now is the time ', 4 )

/*Function: WORDS Usage: WORDS(string)*/
SAY WORDS( 'Now is the time' )

/*Function: WRITECH Usage: WRITECH(logical,string)*/
IF OPEN( 'test', 'ram:test$$', 'W' ) THEN DO
SAY WRITECH( 'test', 'message' ) /*Write the string*/
CALL CLOSE 'test'
END

/*Function: WRITELN Usage: WRITELN(logical,string)*/
IF OPEN( 'test', 'ram:test$$', 'W' ) THEN DO
SAY WRITELN( 'test', 'message' )
/*Write the string (with newline)*/
CALL CLOSE 'test'
END

/*Function: X2C Usage: X2C(heystring)*/
SAY X2C( '616263' ) /*Convent to character (pack)*/

/*Function: XRANGE Usage: XRANGE([start] [,end])*/
SAY C2X( XRANGE( 'f0'x ) )
SAY XRANGE( 'a', 'g' )
EXIT
</syntaxhighlight>

The output of Program 13 is:

every good boy does fine
every good boy does fine.
every good boy does fine .
very good boy does fin.
very good boy does fin.
every good boy does fine.
every good boy does fin.
everygoodboydoesfine
1:23PM /*These results vary depending*/
13 /*on the time the program is run.*/
803
48199
0.80
N
N
ABCDEF
abcdef
fedcba
123+++
abc
123
$134566.12
ABCDEF12
my name
4
0
the
8
4
4
7
8
abc
F0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF
abcdefg

= REXXSupport.Library Functions =

The functions listed in this section are part of the REXXSupport.library. They may only be used if this library has been opened. Below is an example that shows you how to open this library.

== Program 14. OpenLibrary.rexx ==

<syntaxhighlight lang="rexx">
/*Add rexxsupport.library if it isn't already open.*/
IF ~ SHOW( 'L', "rexxsupport.library" ) THEN DO
/*If the library isn't open, try to open it*/
IF ADDLIB( 'rexxsupport.library', 0, -30, 0 )
THEN SAY "Added rexxsupport.library."
ELSE DO
SAY 'ARexx support library not available, exiting'
EXIT 10 /*Exit if ADDLIB() failed*/
END
END
</syntaxhighlight>

== ALLOCMEM() ==

<nowiki>ALLOCMEM(length[,attribute])</nowiki>

Allocates a block of memory of the specified length from the system free-memory pool and returns its address as a four-byte string. The optional attribute parameter must be a standard EXEC memory allocation flag, supplied as a four-byte string. The default attribute is for "PUBLIC" memory (not cleared). Refer to [[Exec_Memory_Allocation|Exec Memory Allocation]] for information on memory types and attribute parameters.

This function should be used whenever memory is allocated for use by external programs. It is the user's responsibility to release the memory space when it is no longer needed. See also [[AmigaOS_Manual:_ARexx_Functions#FREEMEM.28.29|FREEMEM()]]. For example:

<syntaxhighlight lang="rexx">
SAY C2X( ALLOCMEM( 1000 ) ) -> 00050000
SAY C2X( ALLOCMEM( 1000, '00 01 00 0 1'X ) ) -> 00228400
/*1000 bytes of CLEAR Public memory*/
</syntaxhighlight>

== CLOSEPORT() ==

<nowiki>CLOSEPORT(name)</nowiki>

Closes the message port specified by the name argument, which must have been allocated by a call to OPENPORT() within the current ARexx program. Any messages received but not yet REPLYed are automatically returned with the return code set to 10. See also [[AmigaOS_Manual:_ARexx_Functions#OPENPORT.28.29|OPENPORT()]]. For example:

<syntaxhighlight lang="rexx">
CALL CLOSEPORT myport
</syntaxhighlight>

== FREEMEM() ==

<nowiki>FREEMEM(address,length)</nowiki>

Releases a block of memory of the given length to the system free list. The address parameter is a four-byte string, typically obtained by a prior call to ALLOCMEM(). FREEMEM() cannot be used to release memory allocated using GETSPACE(), the ARexx internal memory allocator. The returned value is a Boolean success flag. See also [[AmigaOS_Manual:_ARexx_Functions#ALLOCMEM.28.29|ALLOCMEM()]]. For example:

<syntaxhighlight lang="rexx">
MemoryRequest = 1024
MyMem = ALLOCMEM( MemoryRequest )
SAY C2X( MyMem ) -> 07C987B0
SAY FREEMEM( MyMem, MemoryRequest ) -> 1
/*Or: SAY FREEMEM( '07C987B0'x, 1024 )*/
</syntaxhighlight>

{{Note|title=Caution|text=Before your program terminates, you must use a matching FREEMEM() to release the exact amount of memory you allocated with each ALLOCMEM(). Otherwise, you may crash the system or leave memory unavailable until you reboot.}}

== GETARG() ==

<nowiki>GETARG(packet[,n])</nowiki>

Extracts a command, function name or argument string from a message packet. The packet argument must be a four-byte address obtained from a prior call to GETPKT(). The optional [n] argument specifies the slot containing the string to be extracted and must be less than or equal to the actual argument count for the packet. Commands and function names are always in slot 0. Function packets my have argument strings in slots 1-15. For example:

<syntaxhighlight lang="rexx">
command = GETARG( packet )
function = GETARG( packet, 0 ) /*name string*/
arg1 = GETARG( packet, 1 ) /*1st argument*/
</syntaxhighlight>

== GETPKT() ==

<nowiki>GETPKT(name)</nowiki>

Checks the message port specified by the name argument to see whether any messages are available. The named message port must have been opened by a prior call to OPENPRT() within the current ARexx program. The returned value is the four-byte address of the first message packet, or '0000 0000'x if no packets were available.

The function returns immediately whether or not a packet is enqueued at the message port. Programs should never be designed to "busy-loop" on a message port. If there is no useful work to be done until the next message packet arrives, the program should call WAITPKT() and allow other tasks to proceed. See also [[AmigaOS_Manual:_ARexx_Functions#WAITPKT.28.29|WAITPKT()]]. For example:

<syntaxhighlight lang="rexx">
packet = GETPKT( 'MyPort' )
</syntaxhighlight>

== OPENPORT() ==

<nowiki>OPENPORT(name)</nowiki>

Creates a public message port with the given name. The returned Boolean value indicates whether the port was successfully opened. An initialization failure will occur if another port of the same name already exists or if a signal bit couldn't be allocated. The message port is allocated as a Port Resource node and is linked into the program's global data structure. Ports are automatically closed when the program exits and any pending messages are returned to the sender. See also [[AmigaOS_Manual:_ARexx_Functions#CLOSEPORT.28.29|CLOSEPORT()]]. For example:

<syntaxhighlight lang="rexx">
success = OPENPORT( "MyPort" )
</syntaxhighlight>

== REPLY() ==

<nowiki>REPLY(packet,rc)</nowiki>

Returns a message packet to the sender, with the primary result field set to the value given by the rc argument. The secondary result is cleared. The packet argument must be supplied as a four-byte address, and the rc argument must be a whole number. For example:

<syntaxhighlight lang="rexx">
CALL REPLY( packet, 10 ) /*Error return*/
</syntaxhighlight>

== SHOWDIR() ==

<nowiki>SHOWDIR(directory[,'ALL'|'FILE'|'DIR'][,pad])</nowiki>

Returns the contents of the specified directory as a string of names separated by blanks. The second parameter is an option keyword that selects whether all entries, only files, or only subdirectories, will be included. For example:

<syntaxhighlight lang="rexx">
SAY SHOWDIR( 'SYS:REXXC', 'f', ';' ) -> WaitForPort;TS;TE;TCO;RXSET;RXLIB;RXC;RX;HI
</syntaxhighlight>

== SHOWLIST() ==

<nowiki>SHOWLIST({'A' | 'D' | 'H' | 'T' | 'L' | 'M' | 'P' | 'R' | 'S' | 'T' | 'V' | 'W'}[,name][,pad])</nowiki>

An argument is entered using its initial letter. The arguments are:

; A
: ASSIGNS and Assigned Device

; D
: Device Drivers

; H
: Handlers

; I
: Interrupts

; L
: Libraries

; M
: Memory List Items

; P
: Ports

; R
: Resources

; S
: Semaphores

; T
: Tasks (Ready)

; V
: Volume Names

; W
: Waiting Tasks

If only one argument is supplied, SHOWLIST() returns a string separated by blanks: If a pad character is supplied, names will be separated by the pad rather than by blanks. If the name parameter is supplied. SHOWLIST() returns a Boolean value which indicates if the specified list contains that name. Names are case-sensitive. To provide an accurate snapshot of the current list, task switching is forbidden when the list is scanned.

<syntaxhighlight lang="rexx">
SAY SHOWLIST( 'P' ) -> REXX MyCon
SAY SHOWLIST( 'P', , ';' ) -> REXX;MyCon
SAY SHOWLIST( 'P', 'REXX' ) -> 1
</syntaxhighlight>

== STATEF() ==

<nowiki>STATEF(filename)</nowiki>

Returns a string containing information about an external file. The string is formatted as:

<nowiki>"{DIR | FILE} length blocks protection days minutes ticks comment."</nowiki>

The length token gives the file length in bytes, and the block token specifies the file length in blocks. For example:

<syntaxhighlight lang="rexx">
SAY STATEF( "LIBS:REXXSupport.library" )
/*might give "File 2524 5 ----RW-D 4866 817 2088*/
</syntaxhighlight>

== WAITPKT() ==

<nowiki>WAITPKT(name)</nowiki>

Waits for a message to be received at the specified (named) port, which must have been opened by a call to OPENPORT() within the current ARexx program. The returned Boolean value indicates whether a message packet is available at the port. Normally the returned value will be 1 (True), since the function waits until an event occurs at the message port.

The packet must then be removed by a call to GETPKT() and should be returned eventually using the REPLY() function. Any message packets received but not returned when an ARexx program exits are automatically REPLYed with the return code set to 10. For example:

<syntaxhighlight lang="rexx">
CALL WAITPKT 'MyPort' /*Wait awhile*/
</syntaxhighlight>

= REXXMathLib.Library Functions =

The functions listed in this section are part of the REXXMathLib.library. They may only be used if this library has been opened. Below is an example that shows you how to open this library.

== Program 15. OpenRexxMathLibLibrary.rexx ==

<syntaxhighlight lang="rexx">
/* Add rexxmathlib.library, if it isn't already added. */
library = 'rexxmathlib.library'
IF ~SHOW( 'L', library ) THEN DO
IF ~ADDLIB( library, 0, -30, 0 ) THEN DO
SAY 'Failed to add library ' || library || '.'
EXIT 10
END
END
</syntaxhighlight>

== ACOS() ==

<nowiki>ACOS(number)</nowiki>

Calculates the inverse cosine of the argument ''number'' in radiants. The valid number is between -1.0 and 1.0.

Examples:
<syntaxhighlight lang="rexx">
SAY ACOS( 0.3 ) -> 1.266103672779499
SAY ACOS( -0.162 ) -> 1.733513416182851
</syntaxhighlight>

== ACOSH() ==

<nowiki>ACOSH(number)</nowiki>

Calculates the inverse hyperbolic cosine of the argument ''number''. The valid number is >= 1.0. For example:

<syntaxhighlight lang="rexx">
SAY ACOSH( 1.0 ) -> 1.734723475976807E-18
SAY ACOSH( 438756.328746 ) -> 13.68484665870913
</syntaxhighlight>

== ASIN() ==

<nowiki>ASIN(number)</nowiki>

Calculates the inverse sine of the argument ''number'' in radiants. The valid number is between -1.0 and 1.0. For example:

<syntaxhighlight lang="rexx">
SAY ASIN( -1 ) -> -1.570796326794897
SAY ASIN( 0.95 ) -> 1.253235897503375
</syntaxhighlight>

== ASINH() ==

<nowiki>ASINH(number)</nowiki>

Calculates the inverse hyperbolic sine of the supplied argument. For example:

<syntaxhighlight lang="rexx">
SAY ASINH( 123.012 ) -> 5.50544561307145
SAY ASINH( -143 ) -> -5.656004036134436
</syntaxhighlight>

== ATAN() ==

<nowiki>ATAN(number)</nowiki>

Calculates the inverse tangent of the supplied argument. The result is in radiants.

Examples:

<syntaxhighlight lang="rexx">
SAY ATAN( -21.0083 ) -> -3.738630743180481
SAY ATAN( 0.0001 ) -> 9.999999983308343E-5
</syntaxhighlight>

== ATAN2() ==

<nowiki>ATAN2(y,x)</nowiki>

Calculates the angle between the point [y,x] and the origin in radiants. Note that the coordinate [0,0] is invalid and will result an error.

Examples:
<syntaxhighlight lang="rexx">
SAY ATAN2( 3.0, 3.5 ) -> 0.7086262721276703
SAY ATAN2( 0, 0.1 ) -> 0
SAY ATAN2( -13.2, 0 ) -> -1.570796326794897
</syntaxhighlight>

== ATANH() ==

<nowiki>ATANH(number)</nowiki>

Calculates the inverse hyperbolic tangent of the argument ''number''. The valid number is greater than -1.0 and less than 1.0. For example:

<syntaxhighlight lang="rexx">
SAY ATANH( -0.999 ) -> -0.7611738616605497
SAY ATANH( 0.75 ) -> 0.6351489523872721
</syntaxhighlight>

== CEIL() ==

<nowiki>CEIL(number)</nowiki>

Returns the lowest integer higher than the supplied argument. For example:

<syntaxhighlight lang="rexx">
SAY CEIL( -15.999 ) -> -15
SAY CEIL( 31.4679 ) -> 32
SAY CEIL( 4.5 ) -> 5
</syntaxhighlight>

== COS() ==

<nowiki>COS(number)</nowiki>

Calculates the cosine of the argument ''number''. The result is in radiants. For example:

<syntaxhighlight lang="rexx">
SAY COS( 45.3 ) -> 0.250400079038432
SAY COS( -90 ) -> -0.4480736161291653
</syntaxhighlight>

== COSEC() ==

<nowiki>COSEC(number)</nowiki>

Calculates the cosecans of the argument ''number''. Argument value 0 is invalid.

Examples:

<syntaxhighlight lang="rexx">
SAY COSEC( 1.11 ) -> 1.116446876597528
SAY COSEC( -0.1 ) -> -10.01668613163478
</syntaxhighlight>

Function aliases:

* [[AmigaOS_Manual:_ARexx_Functions#CSC.28.29|CSC()]]

== CSC() ==

<nowiki>CSC(number)</nowiki>

Calculates the cosecans of the argument ''number''. Argument value 0 is invalid.

Examples:

<syntaxhighlight lang="rexx">
SAY COSEC( 1.11 ) -> 1.116446876597528
SAY COSEC( -0.1 ) -> -10.01668613163478
</syntaxhighlight>

Function aliases:

* [[AmigaOS_Manual:_ARexx_Functions#COSEC.28.29|COSEC()]]

== COSH() ==

<nowiki>COSH(number)</nowiki>

Calculates the hyperbolic cosine of the argument ''number''. The valid argument is between -709 and 709. For example:

<syntaxhighlight lang="rexx">
SAY COSH( -709 ) -> 1.701411733192644E+38
SAY COSH( -5.14 ) -> 85.34667884485665
SAY COSH( 0 ) -> 1
SAY COSH( 5.14 ) -> 85.36081289447829
SAY COSH( 709 ) -> 4.109203730776653E+307
</syntaxhighlight>

== COT() ==

<nowiki>COT(number)</nowiki>

Calculates the hyperbolic cotangent of the argument ''number'' in radiants. Argument value 0 is invalid.

Examples:

<syntaxhighlight lang="rexx">
SAY COT( -31 ) -> 2.264002793782034
SAY COT( 12.7 ) -> 7.438787706407688
</syntaxhighlight>

Function aliases:

* [[AmigaOS_Manual:_ARexx_Functions#COTAN.28.29|COTAN()]]

== COTAN() ==

<nowiki>COTAN(number)</nowiki>

Calculates the hyperbolic cotangent of the argument ''number'' in radiants. Argument value 0 is invalid.

Examples:

<syntaxhighlight lang="rexx">
SAY COT( -31 ) -> 2.264002793782034
SAY COT( 12.7 ) -> 7.438787706407688
</syntaxhighlight>

Function aliases:

* [[AmigaOS_Manual:_ARexx_Functions#COT.28.29|COT()]]

== DEG() ==

<nowiki>DEG(number)</nowiki>

Converts degrees in radiants. For example:

<syntaxhighlight lang="rexx">
SAY DEG( 0 ) -> 0
SAY DEG( -3.55 ) -> -0.06195918844579868
</syntaxhighlight>

== E() ==

<nowiki>E()</nowiki>

Returns the value of E, the base of the natural logarithm.

== EPSM() ==

<nowiki>EPSM(number)</nowiki>

Returns the highest floating point number lower than and distinguishable from the argument ''number''. For example:

<syntaxhighlight lang="rexx">
SAY EPSM( -15 ) -> -15
SAY EPSM( 31.4679 ) -> 31.4679
SAY EPSM( 4 ) -> 3.999999999999999
</syntaxhighlight>

== EPSP() ==

<nowiki>EPSP(number)</nowiki>

Returns the lowest floating point number higher than and distinguishable from the argument ''number''. For example:

<syntaxhighlight lang="rexx">
SAY EPSP( -15 ) -> -15
SAY EPSP( 31.4679 ) -> 31.4679
SAY EPSP( 4 ) -> 4.000000000000001
</syntaxhighlight>

== EXP() ==

<nowiki>EXP(number)</nowiki>

Calculates the exponential of the argument ''number''. The valid argument is equal or less than 709. For example:

<syntaxhighlight lang="rexx">
SAY EXP( -709 ) -> 1.216780750623518E-308
SAY EXP( 1.76 ) -> 5.812437394401813
SAY EXP( 709 ) -> 8.218407461553307E+307
</syntaxhighlight>

== FABS() ==

<nowiki>FABS(number)</nowiki>

Returns the absolute value of the ''number'' argument. For example:

<syntaxhighlight lang="rexx">
SAY FABS( -5.35 ) -> 5.35
SAY FABS( 10 ) -> 10
</syntaxhighlight>

== FACT() ==

<nowiki>FACT(number)</nowiki>

Calculates the factorial of the ''number'' argument. The supplied value must be integer between 0 and 87. For example:

<syntaxhighlight lang="rexx">
SAY FACT( 0 ) -> 1
SAY FACT( 21 ) -> 5.109094217170944E+19
SAY FACT( 87 ) -> 2.107757298379517E+132
</syntaxhighlight>

== FLOOR() ==

<nowiki>FLOOR(number)</nowiki>

Returns the highest integer lower than the ''number'' argument. For example:

<syntaxhighlight lang="rexx">
SAY FLOOR( -15.999 ) -> -16
SAY FLOOR( 31.4679 ) -> 31
SAY FLOOR( 4.5 ) -> 4
</syntaxhighlight>

Function aliases:

* [[AmigaOS_Manual:_ARexx_Functions#INT.28.29|INT()]]

== FRACT() ==

<nowiki>FRACT(number)</nowiki>

Returns the fractional part of the ''number'' argument. For examples:

<syntaxhighlight lang="rexx">
SAY FRACT( 63.003 ) ->
SAY FRACT( 0.0829 ) ->
SAY FRACT( -17.63 ) ->
</syntaxhighlight>

== INT() ==

<nowiki>INT(number)</nowiki>

Returns the highest integer lower than the ''number'' argument. For example:

<syntaxhighlight lang="rexx">
SAY FLOOR( -15.999 ) -> -16
SAY FLOOR( 31.4679 ) -> 31
SAY FLOOR( 4.5 ) -> 4
</syntaxhighlight>

Function aliases:

* [[AmigaOS_Manual:_ARexx_Functions#FLOOR.28.29|FLOOR()]]

== LN() ==

<nowiki>LN(number)</nowiki>

Calculates the natural logarithm of the ''number'' argument. The supplied argument must be greater than 0. For example:

<syntaxhighlight lang="rexx">
SAY LOG( 0.0001 ) -> -9.21034037197618
SAY LOG( 104.8 ) -> 4.652053771886941
SAY LOG( 2730.3 ) -> 7.912166772251418
</syntaxhighlight>

Function aliases:

* [[AmigaOS_Manual:_ARexx_Functions#LOG.28.29|LOG()]]

== LOG() ==

<nowiki>LOG(number)</nowiki>

Calculates the natural logarithm of the ''number'' argument. The supplied argument must be greater than zero. For example:

<syntaxhighlight lang="rexx">
SAY LOG( 0.0001 ) -> -9.21034037197618
SAY LOG( 104.8 ) -> 4.652053771886941
SAY LOG( 2730.3 ) -> 7.912166772251418
</syntaxhighlight>

Function aliases:

* [[AmigaOS_Manual:_ARexx_Functions#LN.28.29|LN()]]

== LOG10() ==

<nowiki>LOG10(number)</nowiki>

Calculates the decadic logarithm of the ''number'' argument. The supplied argument must be greater than 0. For example:

<syntaxhighlight lang="rexx">
SAY LOG( 0.0001 ) -> -3.999999999999998
SAY LOG( 104.8 ) -> 2.020361282647707
SAY LOG( 2730.3 ) -> 3.436210369087053
</syntaxhighlight>

== NINT() ==

<nowiki>NINT(number)</nowiki>

Returns the nearest integer to the ''number'' argument. For example:

<syntaxhighlight lang="rexx">
SAY NINT( -15.999 ) -> -16
SAY NINT( 31.4679 ) -> 31
SAY NINT( 4.5 ) -> 5
</syntaxhighlight>

== PI() ==

<nowiki>PI()</nowiki>

Returns the value of PI.

== POL() ==

<nowiki>POL(x,y)</nowiki>

Calculates the angle between the point [x,y] and the origin in radiants. Note that the coordinate [0,0] is invalid and will result an error.

Examples:
<syntaxhighlight lang="rexx">
SAY POL( 3.5, 3.0 ) -> 0.7086262721276703
SAY POL( 0.1, 0 ) -> 0
SAY POL( 0, -13.2 ) -> -1.570796326794897
</syntaxhighlight>

== POW() ==

<nowiki>POW(base,exponent)</nowiki>

Returns the value of a number (''base'') raised to another (''exponent''). You can use positive or negative integers, or positive floating point numbers. When using integers, both base and exponent cannot be zeros at the same time. In addition exponent cannot be less than 1, if base is 0. If you use floating point numbers, base and exponent can be zeros at the same time.

Examples:

<syntaxhighlight lang="rexx">
SAY POW( 2, 0 ) -> 1
SAY POW( -93, 2 ) -> 8649
SAY POW( 93, -2 ) -> 1.156203029251937E-4
SAY POW( 0, 1 ) -> 0
SAY POW( 0.0, 0.0 ) -> 1
SAY POW( 3.0, 0.3 ) -> 1.39038917031567
SAY POW( 1.23, -8 ) -> 0.1908794207865751
</syntaxhighlight>

Function aliases:

* [[AmigaOS_Manual:_ARexx_Functions#POWER.28.29|POWER()]]
* [[AmigaOS_Manual:_ARexx_Functions#XTOY.28.29|XTOY()]]

== POWER() ==

<nowiki>POWER(base,exponent)</nowiki>

Returns the value of a number (''base'') raised to another (''exponent''). You can use positive or negative integers, or positive floating point numbers. When using integers, both base and exponent cannot be zeros at the same time. In addition exponent cannot be less than 1, if base is 0. If you use floating point numbers, base and exponent can be zeros at the same time.

Examples:

<syntaxhighlight lang="rexx">
SAY POW( 2, 0 ) -> 1
SAY POW( -93, 2 ) -> 8649
SAY POW( 93, -2 ) -> 1.156203029251937E-4
SAY POW( 0, 1 ) -> 0
SAY POW( 0.0, 0.0 ) -> 1
SAY POW( 3.0, 0.3 ) -> 1.39038917031567
SAY POW( 1.23, -8 ) -> 0.1908794207865751
</syntaxhighlight>

Function aliases:

* [[AmigaOS_Manual:_ARexx_Functions#POW.28.29|POW()]]
* [[AmigaOS_Manual:_ARexx_Functions#XTOY.28.29|XTOY()]]

== RAD() ==

<nowiki>RAD(number)</nowiki>

Converts radiants in degrees. For example:

<syntaxhighlight lang="rexx">
SAY RAD( 0.3 ) -> 17.1887338539247
SAY RAD( -1.35 ) -> -77.34930234266113
</syntaxhighlight>

== ROOT() ==

<nowiki>ROOT(x,y)</nowiki>

Returns the y-th root of x.

The following rules apply:
* When y is a floating point number, x must be a positive number or zero.
* When y is a non-zero odd integer number, x can be a positive or negative number.

Examples:

<syntaxhighlight lang="rexx">
SAY ROOT( 1, 2.0 ) -> 0.999999999999999
SAY ROOT( -27, 3) -> -2,999999999999451
SAY ROOT( 0, 1 ) -> 0
SAY ROOT( 4, 2 ) -> 2
</syntaxhighlight>

== SEC() ==

<nowiki>SEC(number)</nowiki>

Calculates the secans of the ''number'' argument. The result is in radiants.

Examples:

<syntaxhighlight lang="rexx">
SAY SEC( 20 ) -> 2.4504875209567
SAY SEC( -33.01 ) -> -42.9644890047367
</syntaxhighlight>

== SIN() ==

<nowiki>SIN(number)</nowiki>

Calculates the sine of the ''number'' argument. The result is in radiants. For example:

<syntaxhighlight lang="rexx">
SAY SIN( 0 ) -> 0
SAY SIN( 270 ) -> -0.176045946471159
</syntaxhighlight>

== SINH() ==

<nowiki>SINH(number)</nowiki>

Calculates the hyperbolic sine of the ''number'' argument. The valid argument is between -709 and 709. For example:

<syntaxhighlight lang="rexx">
SAY SINH( 0 ) -> 0
SAY SINH( 90 ) -> 6.102016471587611E+38
</syntaxhighlight>

== SQR() ==

<nowiki>SQR(number)</nowiki>

Calculates the square root of the ''number'' argument. The supplied argument must be a positive number or zero. For example:

<syntaxhighlight lang="rexx">
SAY SQR( 0 ) -> 0
SAY SQR( 9 ) -> 3
SAY SQR( 256 ) -> 16
</syntaxhighlight>

Function aliases:

* [[AmigaOS_Manual:_ARexx_Functions#SQRT.28.29|SQRT()]]

== SQRT() ==

<nowiki>SQRT(number)</nowiki>

Calculates the square root of the ''number'' argument. The supplied argument must be a positive number or zero. For example:

<syntaxhighlight lang="rexx">
SAY SQR( 0 ) -> 0
SAY SQR( 9 ) -> 3
SAY SQR( 256 ) -> 16
</syntaxhighlight>

Function aliases:

* [[AmigaOS_Manual:_ARexx_Functions#SQR.28.29|SQR()]]

== TAN() ==

<nowiki>TAN(number)</nowiki>

Calculates the tangent of the ''number'' argument. The result is in radiants. For example:

<syntaxhighlight lang="rexx">
SAY TAN( 0 ) -> 0
SAY TAN( 270 ) -> -0.178839063798397
</syntaxhighlight>

== TANH() ==

<nowiki>TANH(number)</nowiki>

Calculates the hyperbolic tangent of the ''number'' argument. The result is in radiants. For example:

<syntaxhighlight lang="rexx">
SAY TANH( 0 ) -> 0
SAY TANH( 270 ) -> 0.999999999999998
</syntaxhighlight>

== XTOY() ==

<nowiki>XTOY(base,exponent)</nowiki>

Returns the value of a number (''base'') raised to another (''exponent''). You can use positive or negative integers, or positive floating point numbers. When using integers, both base and exponent cannot be zeros at the same time. In addition exponent cannot be less than 1, if base is 0. If you use floating point numbers, base and exponent can be zeros at the same time.

Examples:

<syntaxhighlight lang="rexx">
SAY POW( 2, 0 ) -> 1
SAY POW( -93, 2 ) -> 8649
SAY POW( 93, -2 ) -> 1.156203029251937E-4
SAY POW( 0, 1 ) -> 0
SAY POW( 0.0, 0.0 ) -> 1
SAY POW( 3.0, 0.3 ) -> 1.39038917031567
SAY POW( 1.23, -8 ) -> 0.1908794207865751
</syntaxhighlight>

Function aliases:

* [[AmigaOS_Manual:_ARexx_Functions#POW.28.29|POW()]]
* [[AmigaOS_Manual:_ARexx_Functions#POWER.28.29|POWER()]]

= Notification Function Host Commands =

This section provides an alphabetical list of the commands supported by Notification. Notification is an [[Application_Library|application library]] feature for displaying application alerts and notifications for the user. Messages show up on the Workbench screen in boxes which fade away after a time or which should be closed by the user.

Before sending commands host address must be set to Notication's message port (NOTIFYA). Below is an example that shows you how to set the host address.

== Program 16. SetHostAddress.rexx ==

<syntaxhighlight lang="rexx">
/* Set host address */
port = 'NOTIFYA'
IF ~SHOW( 'P', port ) THEN DO
SAY 'Notification system is not available.'
EXIT 10
END
ADDRESS VALUE port
</syntaxhighlight>

== NOTIFY ==

<nowiki>NOTIFY APP/K/A,UPDATE/S,CLOSEONDC/S,PRI/K,SCREEN/K,IMG/K,IMGVALIGN/K/N,LOGONLY/S,TITLE/K,SOUND/K,BACKRXMSG/K,AREXXPORT/K,TEXT/F</nowiki>

== REGISTERAPP ==

<nowiki>REGISTERAPP APP/K/A,UPDATE/S,IMG/K,ICON/K,TITLE/K,SOUND/K,TEXT/F</nowiki>

== UNREGISTERAPP ==

<nowiki>UNREGISTERAPP APP/K/A</nowiki>

AmigaOS Manual: AmigaDOS Additional Amiga Directories

2017-10-02T21:55:47Z

Tony Wyatt: Fixed wrong ENV: description.

In addition to the AmigaDOS commands, there are other files and directories on your Workbench disk. This chapter includes the following:

* DEVS:
* S:
* L:
* FONTS:
* LIBS:
* REXX:
* LOCALE:
* ENVARC:
* ENV:
* CLIPS:
* T:
* Classes
* C:

The drawers contained in DEVS: are described in the Workbench User's Guide .

You do not need a detailed understanding of the contents of the directories listed here. Unless specifically directed otherwise, you can safely ignore them. However, you should know their purposes and locations in case you inadvertently delete or rename a file in a directory or need to copy something to the appropriate directory.

Figure B-1 illustrates the standard directory structure of a hard disk Amiga system. Directories with icons visible from Workbench (drawers) are shown on the left; other directories are on the right. The standard contents and structure of these directories may change as the AmigaOS development team adds, changes, or removes resources.

[[File:DosFigB-1.png|center|frame|System Directory Tree]]

Most of these directories are automatically assigned to the SYS: volume or to the Ram Disk. These directories, as well as SYS:, can be ASSIGNed to different volume when necessary.

For example, you can assign FONTS: to a particular disk, such as FontDisk:. Most applications automatically look for the fonts that they need in the FONTS: directory, regardless of where that is. By changing the FONTS: assignment, you can allow applications to use the fonts on FontDisk:

= DEVS: =

In addition to the DOSDrivers, Keymaps, Printers, Monitors, and DataTypes drawers described in the Workbench User's Guide, the DEVS: drawer contains files and subdirectories that pertain to the devices that can be used with the Amiga.

Note that you can refer to the DEVS:Keymaps and DEVS:Printers drawers by their assigned names KEYMAPS: and PRINTERS:, respectively.

== Device Files ==

The following lists the .device files in DEVS: and their functions:

{| class="wikitable"
| clipboard.device || Controls access to CLIPS:.
|-
| Parallel.device || Controls access to the parallel port.
|-
| printer.device || Controls access to the printer device.
|-
| Serial.device || Controls access to the serial port.
|-
| mfm.device || Controls access to MS-DOS disks with CrossDOS.
|}

For more information on the .device files, see [[Devices|Amiga Devices]].

== Other Files ==

The following additional files are found in DEVS:

{| class="wikitable"
| system-configuration || Holds certain Preferences configuration data needed when booting.
|-
| Postscript_init.ps || Holds information needed to initialize a PostScript printer when using PrinterPS.
|}

=== Using Mount Files or a MountList ===

To access new devices, the Amiga must be informed when any are added. These may be physical devices, such as a tape drive, or software (logical) devices, such as a recoverable RAM disk. There are several ways to do this:

* Placing a driver in the Expansion drawer
* Placing a mount file in the DOSDrivers drawer
* Making an entry for the device in a MountList file and using the MOUNT command

A mount file represents a device, handler, or file system. Standard devices have their own mount file with icons in the DOSDrivers drawer in DEVS:. These are mounted automatically during the standard Startup-sequence. Alternatively, devices can use the MOUNT command to read a MountList entry that determines the characteristics of the device.

The need to use a MountList and the MOUNT command has been eliminated by the mount file method used in Amiga system software Release 2.1 and beyond. Rather than requiring a MountList file with entries for each device you want to mount, DEVS: now contains the DOSDrivers drawer, which holds a separate mount file or DOS driver for each device. The contents of a mount file are essentially the same as an individual MountList entry.

You can, however, continue to use a MountList to mount devices. Copy the MountList to DEVS: and remove any DOS drivers in the DOSDrivers drawers that have the same name as one of your MountList entries. (A mount file overrides a MountList entry of the same name.)

=== Creating a MountFile or MountList Entry ===

The following information on mount files also applies to MountLists, except as noted.

Mount files contain keywords describing the device, handler, or file system, as well as values for those keywords. Some keywords apply only to a file system or a handler. If a keyword is omitted, a default value is used. Be sure that the default value is appropriate for the device.

The following are rules for creating a mount file or MountList:

* The file must be a plain ASCII text file.
* The mount file name must be the name of the device; the name of a MountList should be MountList.
* Each entry in a MountList must start with the name of the device. Omit this for a mount file.
* Keywords are followed by an equals sign (=).
* Keywords must be separated by a semicolon or be placed on separate lines.
* Comments are allowed in standard C style (that is, comments start with /* and end with */).
* Each MountList entry must end with the # symbol. Omit this for a mount file.

When creating a new mount file or MountList entry, refer to the documentation that came with the device or start with an example of one for a similar device. Change or add only the necessary keywords.

The following table, lists keywords and their default values supported in a mount file or MountList and their functions. Default values are shown in angle brackets.

{| class="wikitable"
! Keyword !! Function
|-
| Handler=<none> || A handler entry (for example, Handler = L:eque-handler).
|-
| Ehandler=<none> || An environment handler entry.
|-
| FileSystem=<none> || A file system entry (for example, FileSystem = L:CrossDosFileSystem).
|-
| Device=<none> || A device entry (for example, Device = DEVS:mfm.device). This argument is required to mount a file system. There is no default value for Device; you must supply a value.
|-
| Priority=<10> || The priority of the process; 5 is good for handlers, 10 for file systems.
|-
| Unit=<0> || The unit number of the device (for example, 0 for PC0:).
|-
| Flags=<0> || Flags for OpenDevice (usually 0).
|-
| Surfaces=<none> || The number of surfaces (2 for floppy devices, varies for hard drives). This argument is required to mount a file system. There is no default value for Surfaces; you must supply a value.
|-
| SectorsPerBlock=<none> || Defines the number of physical disk sectors in each logical block used by the file system.
|-
| SectorsPerTrack=<none> || The number of blocks per track. This argument is required to mount a file system. There is no default value for SectorsPerTrack; you must supply a value.
|-
| SectorSize=<512> || Specifies the number of bytes in a block on the device. Most devices use a 512 byte block; however, some devices use other sizes (for example, CD-ROMs use 2048 bytes).
|-
| Reserved=<2> || The number of blocks reserved for the boot block; should be 2.
|-
| Interleave=<0> || Interleave value; varies with the device.
|-
| LowCyl=<none> || Starting cylinder to use. This argument is required to mount a file system. There is no default value for LowCyl; you must supply a value.
|-
| HighCyl_<none> || Ending cylinder to use. This argument is required to mount a file system. There is no default value for HighCyl; you must supply a value.
|-
| Stacksize=<600> || Amount of stack allocated to the process.
|-
| Buffers=<5> || Number of initial 512-byte cache buffers. Increase this for higher disk performance if you have RAM to spare.
|-
| BufMem Type=<3> || Memory type used for buffers; (0 and 1 = Any, 2 and 3 = Chip, 4 and 5 = Fast).
|-
| Mount=<0> || See the description of ACTIVATE, which is a synonym for MOUNT.
|-
| MaxTransfer=<0x7ffffff> || The maximum number of bytes transferred at one time with any file system. Use Max Transfer for compatibility with older hard drive systems.
|-
| Mask=<0xffffffff> || Address Mask to specify memory range that DMA transfers can use at one time with any file system. Use Mask for compatibility with older hard drive systems.
|-
| Glob Vec=<2> || A global vector for the process; -1 is no Global Vector (for C and assembler programs), 0 sets up a private GV; if the keyword is absent, the shared Global Vector is used. Omit this keyword for Amiga file system devices.
|-
| Startup=<none> || A string passed to the device, handler, or file system on startup as a BPTR to a BSTR.
|-
| Activate=<0> || If a positive value, ACTIVATE loads the device or handler immediately rather than waiting for first access. Synonymous with MOUNT.
|-
| BootPri=<0> || A value that sets the boot priority of a bootable and mountable device. This value can range from -129 to 127. By convention, -129 indicates that the device is not bootable and is not automatically mounted.
|-
| DosType=<0x444F5300> || Indicates the type of file system, giving hexadecimal ASCII codes for three letters and a concluding number as follows:
{| class="wikitable"
! Value !! ASCII !! File System
|-
| 0x444F5300 || DOS0 || Original (OFS)
|-
| 0x444F5301 || DOS1 || FastFileSystem (FFS)
|-
| 0x444F5302 || DOS2 || International Mode OFS
|-
| 0x444F5303 || DOS3 || International Mode FFS
|-
| 0x444F5304 || DOS4 || Directory caching International Mode OFS
|-
| 0x444F5305 || DOS5 || Directory caching International Mode FFS
|-
| 0x4D534400 || MSD0 || MS-DOS
|}
|-
| Baud=<1200> || Serial device baud rate.
|-
| Control=<0> || Serial device word length, parity, and stop bits.
|-
| Forceload=<0> || Forces a file system to be loaded form disk even though a suitable entry is in the resource list. If 0 (the default), check the resource list before the disk. If 1, always load from disk.
|}

= S: Directory =

The S: directory is generally reserved for AmigaDOS and ARexx scripts. However, you may place non-script files in S: or place script files in other directories. In addition to the Startup-sequence file, the User-startup file that you create, and Shell-startup files, the S: directory also contains teh scripts described in this section.

== ED-Startup ==

This file contains ED commands used to configure the ED text editor, assigning the default function key options. Key assignments can be customized by editing this file. Removing or renaming this file activates expanded ED command menus; see Chapter 4 for instructions on how to do this.

Other files containing ED commands can be stored in S: for use by the WITH keyword of ED, which allows ED command files to perform custom editing operations.

== SPat, DPat ==

These scripts allow pattern matching with commands that do not normally support it. When run with a command, SPat and DPat use the LIST command to create temporary script files in the T: directory and then execute the scripts. SPat and DPat can be used within command aliases.

SPat adds pattern matching to single-argument commands. For example, to use ED to edit all the files in the S: directory beginning with the letter's, enter:

1> SPat ED S:s#?

A script similiar to the following is generated:

ED "s:Shell-startup"
ED "s:SPat"
ED "s:Startup-sequence"

SPat executes the script, invoking ED three times to display the files.

DPat adds pattern matching to double-argument commands. After DPat and the command name, enter the two arguments separated by a space, using the wildcards required to produce the desired matches.

== PCD ==

Like the CD command, the PCD script changes the current directory. However, PCD also remembers the directory from which you are changing, so you can return to it without entering the entire path. Each Shell has an independent PCD memory.

The first time you use PCD in a given Shell, you must give it the path to a directory. When entered with this path argument, PCD has the same effect as CD, changing to the named directory, but it also stores the path to the directory from which you changed. You can then change the current directory by the usual methods. To return to the initial directory, enter PCD alone. For example:

1.System:> PCD Work:Paint/24bit
1.Work:Paint/24bit> PCD
1.System:>

Subsequent invocations of PCD switch to the directory in which you last used PCD:

1.System:> PCD
1.Work:Paint/24bit> /
1.Work:Paint> PCD
1.System:>

PCD use the assign list to store the remembered directory. When you use PCD, the list contains the assignment from<n> , where <n> is the Shell number. Using PCD with no argument before establishing the first from directory produces an error requester.

For further examples of PCD, see Chapter 8.

= L: Directory =

This directory contains device handlers, which are software modules that go between AmigaDOS and the devices used by the Amiga. However, most handlers are treated as if they are actual physical devices and they are referred to by their device name.

Handlers must be named in the mount file or MountList for their respective devices. Handlers are called and manipulated by programs, not users. New handlers can be supplied with some devices or programs and should be copied to the L: directory.

== Aux-Handler ==

The Aux-handler provides unbuffered serial input and output. It is essentially a console handler that uses the serial port rather than the Amiga screen and keyboard.

The DOSDrivers mount file for AUX is:

Handler = L:Aux-handler
Stacksize = 1000
Priority = 5

You can use Aux-Handler to use a serial terminal with your Amiga. For example:

1> NEWSHELL AUX:

== Queue-Handler (PIPE:) ==

The Queue-Handler is an input/output mechanism used to provide I/O communication between programs. It creates an interprocess communication channel named PIPE. For more information about PIPE:, see Appendix D.

== Port-Handler ==

The Port-Handler is the AmigaDOS interface for the SER:, PAR:, and PRT: devices.

When accessing SER:, you can supply settings for the baud rate and control information. The form for this is SER:<baud/control>, where baud is a number representing the baud rate and where control is a three character sequence indicating the following:

{| class="wikitable"
| Number of read/write bits || First character; either 7 or 8
|-
| Parity || Second character; N (no parity), O (odd parity), E (even parity), M (mark parity), S (space parity)
|-
| Number of stops bits || Third character; either 1 or 2
|}

For example:

SER:9600/8N1

connects to the serial port, sets the baud rate to 9600 with a bit data, no parity, and one stop bit.

If you specify no baud rate or control values when accessing SER:, the values set in the Serial Preferences editor are used.

== CrossDOSFileSystem ==

The CrossDOSFileSystem is required to use CrossDOS.

== FileSystem_Trans ==

The FileSystem_Trans directory contains the following files required for CrossDOS text translation:

{| class="wikitable"
| DANSK.crossdos || Filters Danish text files
|-
| INTL.crossdos || Preserves international characters
|-
| MAC.crossdos || Converts Apple Macintosh ASCII files
|}

== CDFileSystem ==

The CDFileSystem is required to use a CD-ROM drive.

= FONTS: =

FONTS: is the disk or directory that contains the information for all of the different styles of fonts available to the Amiga. Font information is stored differently for bitmap and outline fonts.

== Bitmap Fonts ==

For each bitmap font, there is a subdirectory and a .font file. The font subdirectory contains files for the different point sizes that are available. Each of these files contains the bitmap representation of every character in the font at that point size.

For example, for the Emerald font, there is an Emerald directory and an Emerald.font file. The Emerald directory contains two files: 17 and 20. The files contain the data needed for the 17 point Emerald font and the 20 point Emerald font, respectively. The Emerald.font file contains the list of point sizes and any available styles, such as bold and italics for the font.

Many word processor or desktop publishing programs contain additional fonts that you should copy to your FONTS: directory. After you add new fonts to FONTS:, run the FixFonts program to create the .font file for the new additions.

The Topaz font is the default font used by the Amiga. In addition to existing in FONTS:, Topaz 8 and Topaz 9 are built into ROM so that text can always be displayed; however only Topaz 11 is in the Topaz directory.

== Outline Fonts ==

The Compugraphic Intellifont outline font system used on the Amiga stores font data differently. As with the bitmap fonts, there is a .font file for each typeface. There is also a .otag file for each. The two subdirectories _bullet and _bullet_outlines contain the actual outline information for the typefaces installed on your system. You should not try to manipulate these files directly. Always use the Intellifont program or your applications' font installation tools to manage outline fonts.

= LIBS: Directory =

LIBS: contains libraries of software routines and math functions commonly used by the operating system and applications. The files found in the LIBS: directory are:

{| class="wikitable"
! .library File !! Function
|-
| amigaguide.library || Functions used by the AmigaGuide hypertext system.
|-
| asl.library || File, font, and screen mode requester functions.
|-
| Bullet.library || Library functions for finding and loading outline fonts.
|-
| Commodities.library || Functions used by Commodities Exchange programs.
|-
| datatypes.library || Functions for enabling manipulation ot the file types in DEVS:DataTypes.
|-
| Diskfont.library || Library functions for finding and loading font files.
|-
| iffparse.library || Functions to read IFF files.
|-
| locale.library || Functions for using localization features in the Amiga operating system.
|-
| lowlevel.library || Library to aid in game programming.
|-
| mathieeedoubbas.library || Double-precision IEEE math routine functions for basic functions (addition, subtraction, and so forth).
|-
| mathieeedoubtrans.library || Double-precision IEEE math routine functions for transcendental functions (sine, cosine, and so forth).
|-
| mathieeesingtrans.library || Fast single-precision IEEE math routine functions.
|-
| Mathtrans.library || FFP transcendental function math routine functions.
|-
| Realtime.library || Function to synchronize multimedia events, such as music and animation.
|-
| Rexxsupport.library || Functions used by ARexx.
|-
| Rexxsyslib.library || Main ARexx functions.
|-
| Version.library || Contains current software version and revision information.
|-
| 68040.library || Functions needed on Amigas using the 68040 microprocessor chip.
|}

= REXX: =

REXX: is another name normally assigned to the SYS:S directory in addition to S:. Storing any ARexx programs you write in REXX: allows you to execute them without entering the full path. Create a new directory and reASSIGN REXX: to it if you wish to keep ARexx programs separate from AmigaDOS scripts.

= LOCALE: =

LOCALE: is where the Amiga looks for language and country files when it needs to display non-English text. On floppy systems, LOCALE: is the Locale floppy. On hard disk systems, it is the SYS:Locale directory.

LOCALE: contains four directories:

{| class="wikitable"
| Countries || Contains a .country file for all available countries. These files hold country-specific information, such as date/time format and monetary symbols.
|-
| Languages || Contains .language files for the available languages. These files hold general language-specific information, such as the days of the week.
|-
| Catalogs || Contains subdirectories for the available languages, each of which contains a Sys directory. This directory holds translated text for that language. Catalogs/<language>/Sys holds menu, gadget, and message text for that language.
|-
| Help (HELP:) || Contains subdirectories for the available languages, each of which contains a Sys directory. This directory holds translated text for that language. Help/<language>/Sys is reserved for AmigaGuide text files for any applications that have AmigaGuide help in that language.
|}

= ENVARC: =

ENVARC: is the name assigned to the directory SYS:Prefs/Env-Archive. ENVARC: always contains a Sys directory, in which each of the Preferences editors stores the .prefs file created when you save a setting with its Save gadget. Custom default icons created in IconEdit are also saved here. (Named settings saved with the Save As menu item in an Editor are stored by default in the Prefs/Presets drawer.)

Other Workbench programs that allow you to save configuration settings, such as MultiView, also place their files in ENVARC:

The contents of ENVARC: are copied to ENV: at boot time.

= ENV: =

ENV: is a cache that holds the working copy of ENVARC:. Since ENV:'s contents are memory-resident, accesses to its contents do not have to read the system disk. ENV: is an Assign, into which the contents of ENVARC: are copied when booting. Preferences settings activated with Save or Use gadgets are stored in ENV:. Global environment variables are also stored here, as small files.

In OS3.x and earlier, ENV: was assigned to a directory RAM:Env/, but in OS4, ENV: is a handler with its own storage, only accessible to the user through the ENV: assign.

= CLIPS: =

The directory RAM:Clipboards has the assigned name CLIPS:. It stores information clipped with the Cut or Copy items on a program's Edit menu.

= T: =

T: is the RAM:T directory, which may be used by scripts and some commands for storing miscellaneous temporary files.

= Classes =

The Classes directory stores information related to the object-oriented features of the Workbench, such as the DataTypes system upon which MultiView is based. Classes contains the directories DataTypes and Gadgets.

= C: =

C: is the SYS:C directory, which stores non-internal AmigaDOS commands. It is always in the search path.

UserDoc:BIOS

2017-09-02T03:38:15Z

Tony Wyatt: Added references to X5000 and A1222 machines, fixed some typos.

When your Amiga computer system is powered on or reset, the BIOS or firmware's job is to initialize the hardware and to start the booting process of the operating system. It also enables you to define some settings that you may want to use either for the next boot or for every time you use your computer. There are two interface modes that can be used; a console mode and a graphical mode. If you are not an expert don't panic, because once you have set up some firmware variables, you'll use the console very rarely. Typically you will only use the graphic mode, i.e. the menus, which are easier to use. Your computer can boot in many different ways, depending how you set up your variables.

The firmware will generally not be updated very often. The reason for this is because the hardware itself is not changing. The firmware's job is to initialize the hardware to a pointer where the operating system can take over and nothing more.

The BIOS of a new generation Amiga computer will not be explained here as it depends on the hardware. Hence, it is the manufacturer's job to provide a manual describing how the BIOS works and which options you can select to operate the computer.

For now, there are:
* [http://www.denx.de/wiki/U-Boot/WebHome Das U-Boot] used on the Sam440, Sam460 and AmigaOne 500 products from [http://www.acube-systems.biz ACube Systems]. U-Boot was also used by Eyetech for their AmigaOne-XE and MicroA1-C products and various developer boards.
* [http://wiki.openwrt.org/doc/techref/bootloader/cfe CFE] used on the AmigaOne X1000 built by [http://a-eon.com/ A-EON Technology].
* [http://www.denx.de/wiki/U-Boot/WebHome Das U-Boot] used on the AmigaOne X5000 and AmigaOne A1222 built by [http://a-eon.com/ A-EON Technology].
* Custom [http://http://en.wikipedia.org/wiki/Open_Firmware Open Firmware] compliant firmware was used on the Pegasos2 made by Genesi.

= Das U-Boot Environment Variables =

Environment Variables are values that can be set during the boot process to control the behaviour of various pieces of software running on the computer. Some variables are shared by more than one process, while other are unique to a process, but there is no finite list of Environment Variables.

== Displaying Environment Variables ==

To find out what Environment Variables are set on your machine type printenv at the U-Boot Console. The display will show each variable defined and its value, but it will NOT be alphabetically ordered as shown, and you will only be able to see the last 22 lines of the list.

In order to see the complete list, you must change the "stdout" environment variable from "vga" to "serial" and use a null modem cable from the serial port on the AmigaOne connected to the serial port of another computer running a serial comms program that can display the incoming data stream.

Alternatively, if you suspect a particular variable and want to check its contents, type printenv followed by the name of the variable, e.g.

]printenv autostart
autostart=yes

== Listing Environment Variables ==

Once AmigaOS has been installed you can obtain a complete unsorted list by typing NVGetVar from a Shell to display all of the UBoot environment variables. Typing NVGetVar >RAM:varlist will output the list to a file on the RAM Disk which you can print off for reference if required.

{{Note|title=Warning|text=The battery on the motherboards used to maintain these variables has a life of around 3 years and will need to be replaced periodically. If the battery dies, or when you remove it to replace it, you will lose all of the U-Boot environment variables, so it is important to keep an up-to-date listing handy in order that you can reconfigure your machine when the need arises.}}

== Changing Environment Variables ==

If you find that an Environment Variable contains the wrong value, you can change it using the "setenv" command at the U-Boot console. For example, suppose you want to change the delay time for the U-Boot Initialisation Display, you simply enter a new value for the "bootdelay" variable, i.e.

]printenv bootdelay
bootdelay=10
]setenv bootdelay 3
]saveenv
]printenv bootdelay
bootdelay=3

Notice that the "=" sign is NOT used when specifying values for the setenv command. However, if the value contains any embedded blanks, the value must be enclosed within " marks.

== Creating New Environment Variables ==

Anyone can create new variables for whatever they wish, and some people even create their own variables to save them having to key in repetitive commands each time, e.g.

]setenv lx "diskboot 500000 2:0 0; bootm"
]saveenv
]printenv lx
lx=diskboot 500000 2:0 0; bootm

In future, rather than having to type the full command to install Debian from CD-ROM, they can simply type "lx". Note how more than one command can be specified on the same line separated by a semi colon " ; ".

== Resetting or Removing Environment Variables ==

If you want to reset or remove an Environment Variable simply leave off the value, e.g.

]setenv lx
]saveenv
]printenv lx
## Error: "lx" not defined

== Understanding Environment Variables ==

It can be very useful to know what some of these variables are and what they contain, particularly when things don't behave as expected, so we have compiled a list of common environment variables that we know about with typical values to give you some idea where to look.

{| class="wikitable"
|+ U-Boot Environment Variables
! Variable Name !! Common Values and Description
|-
| a1ide_conf
|
{| class="wikitable"
| (not set) || scan IDE buses and auto-configure
|-
| 4 chars - (primary master,primary slave,secondary master,secondary slave)
|
{| class="wikitable"
| 0 || nothing
|-
| 1 || hard disk
|-
| 2 || dvd/cdrom reader/writer
|}
|}
Onboard VIA686B only - specifies the configuration that a1ide.device will use.
|-
| a1ide_irq
|
{| class="wikitable"
| (not set) || use IRQs
|-
| 4 chars - (primary master,primary slave,secondary master,secondary slave)
|
{| class="wikitable"
| 1 || use IRQs
|-
| any other value || don't use IRQs
|}
|}
Onboard VIA686B only - specifies whether a1ide.device will use IRQs.
Using interrupts relieves the CPU (PIO approx 20%, UDMA approx 95%).
It also affects transfer speed (PIO 10-20% lower, UDMA 10-20% faster).
|-
| a1ide_maxbus
|
{| class="wikitable"
| (not set) || both IDE channels
|-
| 0 || no IDE channel at all
|-
| 1 || only primary IDE channe
|-
| 2 || both IDE channels
|}
Onboard VIA686B only - specifies which IDE Buses a1ide.device will use.
|-
| a1ide_timeout
|
{| class="wikitable"
| (not set) || 20
|-
| 1 - 30 || specified timeout
|}
Onboard VIA686B only - specifies the timeout interval in seconds for a1ide connected devices.
The recommended ATA(PI) specification is 30 seconds.
|-
| a1ide_xfer
|
{| class="wikitable"
| (not set) || use best PIO mode
|-
| 4 chars - (primary master,primary slave,secondary master,secondary slave)
|
{| class="wikitable"
| 0 || Automatic (best PIO mode)
|-
| a || PIO 0 (3 MB/s, modeid 8)
|-
| b || PIO 1 (5 MB/s, modeid 9)
|-
| c || PIO 2 (8 MB/s, modeid 10)
|-
| d || PIO 3 (11 MB/s, modeid 11)
|-
| e || PIO 4 (16 MB/s, modeid 12)
|-
| A || UDMA 0 (16 MB/s, modeid 64)
|-
| B || UDMA 1 (25 MB/s, modeid 65)
|-
| C || UDMA 2 (33 MB/s, modeid 66)
|-
| D || UDMA 3 (44 MB/s, modeid 67)
|-
| E || UDMA 4 (66 MB/s, modeid 68)
|-
| F || UDMA 5 (100 MB/s, modeid 69)
|}
|}
Onboard VIA686B only - specifies the transfer mode that a1ide.device will use for each device.
If you specify an unsupported mode, it will use the best mode the drive claims to support.
|-
| agp_enable
|
{| class="wikitable"
| on || enables the AGP bus
|-
| off || disables the AGP bus
|}
|-
| agp_sideband
|
{| class="wikitable"
| on || enables sideband addressing on the AGP bus
|-
| off || disables sideband addressing on the AGP bus
|}
|-
| agp_speed
|
{| class="wikitable"
| 1x || 1X speed
|-
| 2x || 2X speed
|}
|-
| autostart
|
{| class="wikitable"
| yes || execute the kernel as soon as it has been loaded
|-
| no || do not execute the kernel after loading
|}
|-
| baudrate
|
{| class="wikitable"
| 9600 (default)
|-
| 19200
|-
| 38400
|-
| 57600
|-
| 115200
|-
| 230400
|-
| 460800
|-
| 921600
|}
Serial port baud rate.
|-
| boot1
|
{| class="wikitable"
| cdrom || IDE CDROM
|-
| floppy || Floppy disk
|-
| ide || IDE Disk
|-
| net || Network
|-
| psii || SII Parallel Disk
|-
| psiicdrom || SII Parallel CDROM
|-
| scdrom || SCSI CDROM
|-
| scsi || SCSI Disk
|-
| sii || SII Serial Disk
|-
| siicdrom || SII Serial CDROM\)
|-
| ucdrom || USB CDROM
|-
| usb || USB Disk
|}
Specifies the first device to boot from. Normally cdrom.
|-
| boot2
|
{| class="wikitable"
| cdrom || IDE CDROM
|-
| floppy || Floppy disk
|-
| ide || IDE Disk
|-
| net || Network
|-
| psii || SII Parallel Disk
|-
| psiicdrom || SII Parallel CDROM
|-
| scdrom || SCSI CDROM
|-
| scsi || SCSI Disk
|-
| sii || SII Serial Disk
|-
| siicdrom || SII Serial CDROM\)
|-
| ucdrom || USB CDROM
|-
| usb || USB Disk
|}
Specifies the second device to boot from. Normally ide.
|-
| boot3
|
{| class="wikitable"
| cdrom || IDE CDROM
|-
| floppy || Floppy disk
|-
| ide || IDE Disk
|-
| net || Network
|-
| psii || SII Parallel Disk
|-
| psiicdrom || SII Parallel CDROM
|-
| scdrom || SCSI CDROM
|-
| scsi || SCSI Disk
|-
| sii || SII Serial Disk
|-
| siicdrom || SII Serial CDROM\)
|-
| ucdrom || USB CDROM
|-
| usb || USB Disk
|}
Specifies the third device to boot from.
|-
| boot4
|
{| class="wikitable"
| cdrom || IDE CDROM
|-
| floppy || Floppy disk
|-
| ide || IDE Disk
|-
| net || Network
|-
| psii || SII Parallel Disk
|-
| psiicdrom || SII Parallel CDROM
|-
| scdrom || SCSI CDROM
|-
| scsi || SCSI Disk
|-
| sii || SII Serial Disk
|-
| siicdrom || SII Serial CDROM\)
|-
| ucdrom || USB CDROM
|-
| usb || USB Disk
|}
Specifies the fourth device to boot from.
|-
| boot_command || Diskboot 
Specifies a command to be executed to invoke a disk boot.
|-
| boot_config || Default 
Specifies the name of the AmigaOS kickstart label to boot with. The SYS:Kickstart/kicklayout file contains one or more layouts and each one has a unique label.
|-
| boot_method
|
{| class="wikitable"
| boota || Amiga multiboot method
|-
| diskboot || Linux direct method
|}
Specifies how the machine is to be booted.
|-
| boota_keep_countdown
|
{| class="wikitable"
| on || Stop timer after a selection
|-
| off || Continue timer after a selection (default)
|}
Specifies whether the boota timer should continue after a selection is made.
|-
| boota_no_video_menu
|
{| class="wikitable"
| on || Display selection menu
|-
| off || Disable selection menu (default)
|}
Specifies whether the boota selection menu should be suppressed.
|-
| boota_scan_all_HDD
|
{| class="wikitable"
| on || Scan all hard drives
|-
| off || Do not scan all hard drives (default)
|}
Specifies whether boota should scan all Hard Disk Drives.
|-
| boota_timeout
| 10
Specifies the delay time in seconds for the Amiga Multi-boot Menu.
|-
| bootargs
| arg1 arg2 arg3 ... 
Specifies the argument string that should be passed to Linux on booting.
|-
| bootcmd
|
{| class="wikitable"
| diskboot || Immediately boot from the designated disk (Linux).
|-
| "menu; run menuboot_cmd" || Execute the "menu" command and then run the command in the "menuboot_cmd" variable (AmigaOS).
|}
|-
| bootdelay
| 5 
Specifies the delay time in seconds for the U-Boot Initialisation Display.
|-
| bootdevice
| Specifies the hardware device for Linux to boot from.
|-
| ethact
| Specifies the Ethernet device.
|-
| ethaddr
| Specifies your unique Ethernet (MAC) address for network operation.
|-
| ide
|
{| class="wikitable"
| (not set) || defaults to VIA IDE
|-
| psii || sii0680ide (PATA)
|-
| ssii || sii3112ide, sii3114ide or sii3512ide (SATA)
|}
SIIxxxx only - Specifies the type of drives U-Boot should use for booting.
|-
| ide_cd_timeout
| 30 
Specifies the time in seconds to wait for an IDE CDROM drive before timing out.
|-
| ide_doreset
|
{| class="wikitable"
| on (default)
|-
| off
|}
Specifies whether to run "ide reset" as part of the boot sequence.
|-
| ide_maxbus
|
{| class="wikitable"
| 0 || no devices attached to either channel
|-
| 1 || devices only attached to channel 1
|-
| 2 || devices attached to both channels
|}
Specifies the maximum number of active IDE Buses for the onboard VIA controller.
|-
| ide_swap
|
{| class="wikitable"
| 0 || use normal channels
|-
| 1 || swap channels
|}
Specifies that the Primary and Secondary bus should be swapped.
|-
| ipaddr
| Specifies the local TCP/IP address for network booting - only used for TFTP booting.
|-
| kbddev_mapping
| fromkey=tokey (fromkey=tokey....) 
Specifies whether keyboard remapping is required and which key(s) should be remapped and is typically used where a keyboard may not have particular keys.
|-
| kbddev_norwin
|
{| class="wikitable"
| off || Do not remap keys (default)
|-
| on || Right Windows key should be mapped as the Menu key.
|}
|-
| kbddev_sysreqishelp
|
{| class="wikitable"
| off || Do not remap keys (default)
|-
| on || Map PRNSCR/SYSREQ or PRNSCR/SYSRQ (as shown on many keyboards) key should be mapped as the Help key.
|}
|-
| limit_memory
| 512 
Specifies a memory limit to restrict use of the available memory.\
|-
| menu_netboot
|
{| class="wikitable"
| DHCP
|-
| BOOTP
|-
| ARP
|-
| TFTP
|}
Specifies the network boot type when booting over a network. It is not used by AmigaOS or boota.
|-
| menuboot_cmd
|
{| class="wikitable"
| (not set)
|-
| "ide reset; diskboot" || Linux
|-
| "ide reset; boota; boota; boota" || AmigaOS Multiboot
|}
Specifies the commands to be issued on completion of the Menuboot delay. 
Note the AmigaOS Multiboot sequence requires a command for each bootable device so boota is repeated.
|-
| menuboot_delay
| 3 
Specifies the delay time in seconds for the Menuboot Delay panel.
|-
| menucmd
| menu 
Specifies the command to be executed to invoke the boot menu.
|-
| os4_commandline
| debuglevel=0 
Specifies the argument string that should be passed to the AmigaOS kernel on booting.
|-
| parallel_address
|
{| class="wikitable"
| 278
|-
| 378 (normal)
|}
Specifies the Parallel Port address.
|-
| parallel_mode
|
{| class="wikitable"
| 0 || ECP
|-
| 1 || EPP
|-
| 2 || Off (normal)
|-
| 3 || UNI
|}
Specifies the Parallel Port mode.
|-
| pci_irqa || 9 
Specifies the IRQ level for PCI Interrupt A.
|-
| pci_irqa_select
|
{| class="wikitable"
| edge || Edge-triggered interrupts.
|-
| level || Level-triggered interrupts. (normal)
|}
|-
| pci_irqb || 10 
Specifies the IRQ level for PCI Interrupt B.
|-
| pci_irqb_select
|
{| class="wikitable"
| edge || Edge-triggered interrupts.
|-
| level || Level-triggered interrupts. (normal)
|}
|-
| pci_irqc || 11 
Specifies the IRQ level for PCI Interrupt C.
|-
| pci_irqc_select
|
{| class="wikitable"
| edge || Edge-triggered interrupts.
|-
| level || Level-triggered interrupts. (normal)
|}
|-
| pci_irqd || 7 
Specifies the IRQ level for PCI Interrupt D.
|-
| pci_irqd_select
|
{| class="wikitable"
| edge || Edge-triggered interrupts.
|-
| level || Level-triggered interrupts. (normal)
|}
|-
| preboot || (not set) 
Specifies any pre-boot commands.
|-
| rescan_bootunits
|
{| class="wikitable"
| off (normal)
|-
| on
|}
Specifies whether boota should rescan all of the boot units.
|-
| serial1_address
|
{| class="wikitable"
| 2E8
|-
| 2F8
|-
| 3E8
|-
| 3F8 (normal)
|}
Specifies the hardware address where Serial port 1 will be located.
|-
| serial2_address
|
{| class="wikitable"
| 2E8
|-
| 2F8 (normal)
|-
| 3E8
|-
| 3F8
|}
Specifies the hardware address where Serial port 2 will be located.
|-
| serverip
| Specifies the server IP address. 
The server must be running a supported networking boot service.
|-
| sii0680ide_conf
|
{| class="wikitable"
| (not set) || scan IDE buses and auto-configure
|-
| 4 chars - (primary master,primary slave,secondary master,secondary slave)
|
{| class="wikitable"
| 0 || nothing
|-
| 1 || hard disk
|-
| 2 || dvd/cdrom reader/writer
|}
|}
SII0680 only - specifies the configuration that sii0680ide.device will use.
|-
| sii0680ide_irq
|
{| class="wikitable"
| (not set) || use IRQs
|-
| 4 chars - (primary master,primary slave,secondary master,secondary slave)
|
{| class="wikitable"
| 1 || use IRQs
|-
| any other value || don't use IRQs
|}
|}
SII0680 only - specifies whether sii0680ide.device will use IRQs.
Using interrupts relieves the CPU (PIO approx 20%, UDMA approx 95%).
It also affects transfer speed (PIO 10-20% lower, UDMA 10-20% faster).
|-
| sii0680ide_maxbus
|
{| class="wikitable"
| (not set) || both IDE channels
|-
| 0 || no IDE channel at all
|-
| 1 || only primary IDE channe
|-
| 2 || both IDE channels
|}
SII0680 only - specifies which IDE Buses sii0680ide.device will use.
|-
| sii0680ide_timeout
|
{| class="wikitable"
| (not set) || 20
|-
| 1 - 30 || specified timeout
|}
SII0680 only - specifies the timeout interval in seconds for sii0680ide connected devices.
The recommended ATA(PI) specification is 30 seconds.
|-
| sii0680ide_xfer
|
{| class="wikitable"
| (not set) || use best UDMA mode (best PIO mode on Eyetech boards)
|-
| 4 chars - (primary master,primary slave,secondary master,secondary slave)
|
{| class="wikitable"
| 0 || Automatic (same as not set)
|-
| a || PIO 0 (3 MB/s, modeid 8)
|-
| b || PIO 1 (5 MB/s, modeid 9)
|-
| c || PIO 2 (8 MB/s, modeid 10)
|-
| d || PIO 3 (11 MB/s, modeid 11)
|-
| e || PIO 4 (16 MB/s, modeid 12)
|-
| A || UDMA 0 (16 MB/s, modeid 64)
|-
| B || UDMA 1 (25 MB/s, modeid 65)
|-
| C || UDMA 2 (33 MB/s, modeid 66)
|-
| D || UDMA 3 (44 MB/s, modeid 67)
|-
| E || UDMA 4 (66 MB/s, modeid 68)
|-
| F || UDMA 5 (100 MB/s, modeid 69)
|-
| G || UDMA 6 (133 MB/s, modeid 70)
|}
|}
SII0680 only - specifies the transfer mode that sii0680ide.device will use for each device.
If you specify an unsupported mode, it will use the best mode the drive claims to support.
|-
| sii3112ide_conf
|
{| class="wikitable"
| (not set) || scan IDE buses and auto-configure
|-
| 2 chars - (primary bus/unit0,secondary bus/unit1)
|
{| class="wikitable"
| 0 || nothing
|-
| 1 || hard disk
|-
| 2 || dvd/cdrom reader/writer
|}
|}
SII3112 only - specifies the configuration that sii3112ide.device will use.
|-
| sii3112ide_irq
|
{| class="wikitable"
| (not set) || use IRQs
|-
| 2 chars - (primary bus/unit0,secondary bus/unit1)
|
{| class="wikitable"
| 1 || use IRQs
|-
| any other value || don't use IRQs
|}
|}
SII3112 only - specifies whether sii3112ide.device will use IRQs.
Using interrupts relieves the CPU (PIO approx 20%, UDMA approx 95%).
It also affects transfer speed (PIO 10-20% lower, UDMA 10-20% faster).
|-
| sii3112ide_maxbus
|
{| class="wikitable"
| (not set) || both IDE channels
|-
| 0 || no IDE channel at all
|-
| 1 || only primary IDE channel
|-
| 2 || both IDE channels
|}
SII3112 only - specifies which IDE Buses sii3112ide.device will use.
|-
| sii3112ide_timeout
|
{| class="wikitable"
| (not set) || 20
|-
| 1 - 30 || specified timeout
|}
SII3112 only - specifies the timeout interval in seconds for sii3112ide connected devices.
The recommended ATA(PI) specification is 30 seconds.
|-
| sii3112ide_xfer
|
{| class="wikitable"
| (not set) || use best UDMA mode (best PIO mode on Eyetech boards)
|-
| 2 chars - (primary bus/unit0,secondary bus/unit1)
|
{| class="wikitable"
| 0 || Automatic (same as not set)
|-
| a || PIO 0 (3 MB/s, modeid 8)
|-
| b || PIO 1 (5 MB/s, modeid 9)
|-
| c || PIO 2 (8 MB/s, modeid 10)
|-
| d || PIO 3 (11 MB/s, modeid 11)
|-
| e || PIO 4 (16 MB/s, modeid 12)
|-
| A || UDMA 0 (16 MB/s, modeid 64)
|-
| B || UDMA 1 (25 MB/s, modeid 65)
|-
| C || UDMA 2 (33 MB/s, modeid 66)
|-
| D || UDMA 3 (44 MB/s, modeid 67)
|-
| E || UDMA 4 (66 MB/s, modeid 68)
|-
| F || UDMA 5 (100 MB/s, modeid 69)
|-
| G || UDMA 6 (133 MB/s, modeid 70)
|}
|}
SII3112 only - specifies the transfer mode that sii3112ide.device will use for each device.
If you specify an unsupported mode, it will use the best mode the drive claims to support.
|-
| sii3114ide_conf
|
{| class="wikitable"
| (not set) || scan IDE buses and auto-configure
|-
| 4 chars - (primary master,primary slave,secondary master,secondary slave)
|
{| class="wikitable"
| 0 || nothing
|-
| 1 || hard disk
|-
| 2 || dvd/cdrom reader/writer
|}
|}
SII3114 only - specifies the configuration that sii3114ide.device will use.
|-
| sii3114ide_irq
|
{| class="wikitable"
| (not set) || use IRQs
|-
| 4 chars - (primary master,primary slave,secondary master,secondary slave)
|
{| class="wikitable"
| 1 || use IRQs
|-
| any other value || don't use IRQs
|}
|}
SII3114 only - specifies whether sii3114ide.device will use IRQs.
Using interrupts relieves the CPU (PIO approx 20%, UDMA approx 95%).
It also affects transfer speed (PIO 10-20% lower, UDMA 10-20% faster).
|-
| sii3114ide_maxbus
|
{| class="wikitable"
| (not set) || both IDE channels
|-
| 0 || no IDE channel at all
|-
| 1 || only primary IDE channel
|-
| 2 || both IDE channels
|}
SII3114 only - specifies which IDE Buses sii3114ide.device will use.
|-
| sii3114ide_timeout
|
{| class="wikitable"
| (not set) || 20
|-
| 1 - 30 || specified timeout
|}
SII3114 only - specifies the timeout interval in seconds for sii3114ide connected devices.
The recommended ATA(PI) specification is 30 seconds.
|-
| sii3114ide_xfer
|
{| class="wikitable"
| (not set) || use best UDMA mode (best PIO mode on Eyetech boards)
|-
| 4 chars - (primary master,primary slave,secondary master,secondary slave)
|
{| class="wikitable"
| 0 || Automatic (same as not set)
|-
| a || PIO 0 (3 MB/s, modeid 8)
|-
| b || PIO 1 (5 MB/s, modeid 9)
|-
| c || PIO 2 (8 MB/s, modeid 10)
|-
| d || PIO 3 (11 MB/s, modeid 11)
|-
| e || PIO 4 (16 MB/s, modeid 12)
|-
| A || UDMA 0 (16 MB/s, modeid 64)
|-
| B || UDMA 1 (25 MB/s, modeid 65)
|-
| C || UDMA 2 (33 MB/s, modeid 66)
|-
| D || UDMA 3 (44 MB/s, modeid 67)
|-
| E || UDMA 4 (66 MB/s, modeid 68)
|-
| F || UDMA 5 (100 MB/s, modeid 69)
|-
| G || UDMA 6 (133 MB/s, modeid 70)
|}
|}
SII3114 only - specifies the transfer mode that sii3114ide.device will use for each device.
If you specify an unsupported mode, it will use the best mode the drive claims to support.
|-
| sii3512ide_conf
|
{| class="wikitable"
| (not set) || scan IDE buses and auto-configure
|-
| 2 chars - (primary bus/unit0,secondary bus/unit1)
|
{| class="wikitable"
| 0 || nothing
|-
| 1 || hard disk
|-
| 2 || dvd/cdrom reader/writer
|}
|}
SII3512 only - specifies the configuration that sii3512ide.device will use.
|-
| sii3512ide_irq
|
{| class="wikitable"
| (not set) || use IRQs
|-
| 2 chars - (primary bus/unit0,secondary bus/unit1)
|
{| class="wikitable"
| 1 || use IRQs
|-
| any other value || don't use IRQs
|}
|}
SII3512 only - specifies whether sii3512ide.device will use IRQs.
Using interrupts relieves the CPU (PIO approx 20%, UDMA approx 95%).
It also affects transfer speed (PIO 10-20% lower, UDMA 10-20% faster).
|-
| sii3512ide_maxbus
|
{| class="wikitable"
| (not set) || both IDE channels
|-
| 0 || no IDE channel at all
|-
| 1 || only primary IDE channel
|-
| 2 || both IDE channels
|}
SII3512 only - specifies which IDE Buses sii3512ide.device will use.
|-
| sii3512ide_timeout
|
{| class="wikitable"
| (not set) || 20
|-
| 1 - 30 || specified timeout
|}
SII3512 only - specifies the timeout interval in seconds for sii3512ide connected devices.
The recommended ATA(PI) specification is 30 seconds.
|-
| sii3512ide_xfer
|
{| class="wikitable"
| (not set) || use best UDMA mode (best PIO mode on Eyetech boards)
|-
| 2 chars - (primary bus/unit0,secondary bus/unit1)
|
{| class="wikitable"
| 0 || Automatic (same as not set)
|-
| a || PIO 0 (3 MB/s, modeid 8)
|-
| b || PIO 1 (5 MB/s, modeid 9)
|-
| c || PIO 2 (8 MB/s, modeid 10)
|-
| d || PIO 3 (11 MB/s, modeid 11)
|-
| e || PIO 4 (16 MB/s, modeid 12)
|-
| A || UDMA 0 (16 MB/s, modeid 64)
|-
| B || UDMA 1 (25 MB/s, modeid 65)
|-
| C || UDMA 2 (33 MB/s, modeid 66)
|-
| D || UDMA 3 (44 MB/s, modeid 67)
|-
| E || UDMA 4 (66 MB/s, modeid 68)
|-
| F || UDMA 5 (100 MB/s, modeid 69)
|-
| G || UDMA 6 (133 MB/s, modeid 70)
|}
|}
SII3512 only - specifies the transfer mode that sii3512ide.device will use for each device.
If you specify an unsupported mode, it will use the best mode the drive claims to support.
|-
| stdin
|
{| class="wikitable"
| amiga || Catweasel with Classic Amiga keyboard
|-
| amikbd || Catweasel with Classic Amiga keyboard
|-
| ps2 || standard PS2 keyboard
|-
| ps2kbd || standard PS2 keyboard (normal)
|-
| serial || external serial port
|}
Specifies the standard input device.
|-
| stdout
|
{| class="wikitable"
| serial || external serial port
|-
| vga || VGA display device (normal)
|}
Specifies the standard output device.
|-
| usb0_enable
|
{| class="wikitable"
| on || Enable back panel ports (0/1)
|-
| off || Disable back panel ports (0/1)
|}
|-
| usb1_enable
|
{| class="wikitable"
| on || Enable header ports (2/3)
|-
| off || Disable header ports (2/3)
|}
|-
| usb_use_header
|
{| class="wikitable"
| 0 || Use rear USB ports
|-
| 1 || Use front USB ports
|}
|-
| use_memory_limit
| yes
Specifies whether the "memory_limit" variable is to be used.
|-
| vga_bg_color
|
{| class="wikitable"
| 0 || Black (default)
|-
| 1 || Blue
|-
| 2 || Green
|-
| 3 || Cyan
|-
| 4 || Red
|-
| 5 || Magenta
|-
| 6 || Brown (Dark Yellow)
|-
| 7 || Light Gray
|-
| 8 || Dark Gray
|-
| 9 || Light Blue
|-
| 10 || Light Green
|-
| 11 || Light Cyan
|-
| 12 || Light Red
|-
| 13 || Light Magenta
|-
| 14 || Light Yellow
|-
| 15 || White
|}
Specifies the background color for the UBoot initialisation screens.
|-
| vga_fg_color
|
{| class="wikitable"
| 0 || Black
|-
| 1 || Blue
|-
| 2 || Green
|-
| 3 || Cyan
|-
| 4 || Red
|-
| 5 || Magenta
|-
| 6 || Brown (Dark Yellow)
|-
| 7 || Light Gray
|-
| 8 || Dark Gray
|-
| 9 || Light Blue
|-
| 10 || Light Green
|-
| 11 || Light Cyan
|-
| 12 || Light Red
|-
| 13 || Light Magenta
|-
| 14 || Light Yellow
|-
| 15 || White (default)
|}
Specifies the foreground color for the UBoot initialisation screens.
|-
| video_num
| 1
Specifies the number of video devices.
|}

UserDoc:How AmigaOS Works

2017-09-02T02:47:58Z

Tony Wyatt:

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that translates them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable and script bits set.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage media you can purchase at a computer store. We use them to store our files. They can be internal hard disks, external hard drives, USB interface devices (i.e., SD cards, CF cards, "flash" drives, etc.), and floppy disk drives.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done by virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also, you can see a greyed area which is a blank area on the disk (i.e., no partition is defined at this position). Several different file systems can be used on the same Amiga drive. It's your choice.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we must read the physical data off the partition. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

Volume names can refer to either a physical or virtual named space. See the autodoc section for the ASSIGN command in the C: directory as well as the MOUNT command which provides more information on naming and the concept of volumes.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duty is to draw graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find them all in the '''Kickstart''' directory on the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like the conductor of an orchestra. Its job is to make everything work together. It creates processes, handles memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a unique kernel that has existed since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the user can employ to define some settings before starting AmigaOS
* con-handler.kmod - it directs read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the reads/writes of environment variables
* FileSystem.resource.kmod - handles access to the different filesystems
* gadtools.library.kmod - a collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the reads/writes of game pads and joysticks
* graphics.library.kmod - a collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - a set of functions to read a data stream into memory
* input.device.kmod - handles input events like keyboard events or mouse clicks
* intuition.library.kmod - a collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the reads/writes to the NVRAM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handle the '''Ram disk:'''.
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform low level graphic operations on graphics cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded optionally. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout (now obsolescent)
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* NGFileSystem - an experimental file system designed to gradually replace the FastFileSystem
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allows the use of disks connected to a disk controller. These files are named after the controller they support. As an example, the '''sii3114ide.device.kmod''' allows the use of disks connected to a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

==== Misc modules ====

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== Control of the Kickstart ==

The Kickstart/ drawer contains an ASCII file called "Kicklayout". This file lists all the modules that must be loaded from the system volume during the boot process. It is read by the boot loaders "SLB" or "amigaboot".

The Kicklayout file consists of a number of configurations, each of which describes a set of Kickstart modules. Each configuration has a label and the various configurations are listed by label on the boot screen. The user may elect to load the default configuration or to select any one of the other configurations. Often a developer will have several configurations in his/her Kicklayout file, some of which may be experimental, while the default is a "known good" configuration to which (s)he can fall back.

You can edit the Kicklayout file using Notepad or any other ASCII editor. You are strongly advised to leave the original configuration unchanged (as a fall-back) and to add new configurations at the end of the file, each with its own label. That way you can still recover if you make a mistake while editing.

<nowiki>; Configuration name
LABEL MainSystem
; Exec name
EXEC Kickstart/loader.of
;
; PPC native modules
;
MODULE Kickstart/kernel
;
MODULE Kickstart/FastFileSystem
MODULE Kickstart/CDFileSystem
MODULE Kickstart/NGFileSystem
;
(etc)</nowiki>

Note that lines that start with a semicolon (";") are treated as comments and are ignored. Each configuration must start with a "LABEL" keyword and should be separated from the previous configuration by a blank line. The blank line signifies "Stop loading here".

Each module to be loaded is defined by the "MODULE" keyword, followed by the path and file name. You can use any path ''on the system volume'', so you could have two or more drawers containing Kickstart modules and address them independently if you so wished. You can not refer to modules on other volumes, since they have not been mounted by DOS (which does not exist yet) and only the system volume is available at this early stage.

=== Selecting the Default Configuration ===

You can specify in the NVRAM the label of the default configuration in the Kicklayout. For instance, if your default configuration is called "MainSystem", the LABEL line will look like this:

LABEL MainSystem

You can define an NVRAM variable called "boot_config" using U-Boot, CFE or the "nvsetvar" tool. Simply type:

nvsetvar boot_config "MainSystem"

[Note that nvsetvar may be inhibited from writing to the NVRAM on some systems, in which case you will have to use U-Boot or CFE to set the variable]

If you do not specify a default configuration with the "boot_config" variable, the boot loader will default to the first configuration in the Kicklayout.

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when needed. These files are stored in different directories in the system volume.
A default AmigaOS installation looks like this:

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definitions for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains Internet-related files and configurations
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Lib'''rairies of functions
* Locale
contains all files used to customise the system for your locality (catalogs, keymaps...)
* MUI
contains the files needed for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the system's '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files, not currently used
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default, Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add to the list all files from libs:xad and also xadmaster.library.

= AmigaOS boot procedure =

Classic Amigas with PowerPC accelerators, the original AmigaOne SE/XE and the Sam series of Amigas all use the Second Level Booter (SLB) to read their Kickstart modules from the system volume. The newer A-Eon machines (X1000, X5000, A1222) all use a loader called AmigaBoot. In the X1000, AmigaBoot must be read from an FFS partition, while in the later machines, it is stored in the on-board CF card. The process of loading the kickstart modules is the same in all cases.

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
The BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information is displayed. This shows if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly set up to make this drive useable.
* Depending on the machine type, the BIOS will look on the harddisk to find the Second Level Booter (SLB) or AmigaBoot, or will execute the AmigaBoot program from the on-board NVRAM. Whereas the BIOS does not know about AmigaOS disk structure, the SLB/AmigaBoot can ''understand'' the AmigaOS partitions and file systems. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
SLB/AmigaBoot analyses all Amiga partitions on the system disk. It reads each system configuration it finds on the partition and displays them all for the user to select one to load. AmigaBoot (not SLB) also displays configurations from Kickstart/Kicklayout files on every "bootable" partition.
The user can [[UserDoc:How_AmigaOS_Works#Control_of_the_Kickstart|define]] many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
SLB/AmigaBoot loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* The AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* The Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* The Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2017-09-02T02:22:15Z

Tony Wyatt:

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that translates them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable and script bits set.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage media you can purchase at a computer store. We use them to store our files. They can be internal hard disks, external hard drives, USB interface devices (i.e., SD cards, CF cards, "flash" drives, etc.), and floppy disk drives.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done by virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also, you can see a greyed area which is a blank area on the disk (i.e., no partition is defined at this position). Several different file systems can be used on the same Amiga drive. It's your choice.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we must read the physical data off the partition. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

Volume names can refer to either a physical or virtual named space. See the autodoc section for the ASSIGN command in the C: directory as well as the MOUNT command which provides more information on naming and the concept of volumes.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duty is to draw graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find them all in the '''Kickstart''' directory on the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like the conductor of an orchestra. Its job is to make everything work together. It creates processes, handles memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a unique kernel that has existed since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the user can employ to define some settings before starting AmigaOS
* con-handler.kmod - it directs read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the reads/writes of environment variables
* FileSystem.resource.kmod - handles access to the different filesystems
* gadtools.library.kmod - a collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the reads/writes of game pads and joysticks
* graphics.library.kmod - a collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - a set of functions to read a data stream into memory
* input.device.kmod - handles input events like keyboard events or mouse clicks
* intuition.library.kmod - a collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the reads/writes to the NVRAM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handle the '''Ram disk:'''.
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform low level graphic operations on graphics cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded optionally. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout (now obsolescent)
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* NGFileSystem - an experimental file system designed to gradually replace the FastFileSystem
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allows the use of disks connected to a disk controller. These files are named after the controller they support. As an example, the '''sii3114ide.device.kmod''' allows the use of disks connected to a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

==== Misc modules ====

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== Control of the Kickstart ==

The Kickstart/ drawer contains an ASCII file called "Kicklayout". This file lists all the modules that must be loaded from the system volume during the boot process. It is read by the boot loaders "SLB" or "amigaboot".

The Kicklayout file consists of a number of configurations, each of which describes a set of Kickstart modules. Each configuration has a label and the various configurations are listed by label on the boot screen. The user may elect to load the default configuration or to select any one of the other configurations. Often a developer will have several configurations in his/her Kicklayout file, some of which may be experimental, while the default is a "known good" configuration to which (s)he can fall back.

You can edit the Kicklayout file using Notepad or any other ASCII editor. You are strongly advised to leave the original configuration unchanged (as a fall-back) and to add new configurations at the end of the file, each with its own label. That way you can still recover if you make a mistake while editing.

<nowiki>; Configuration name
LABEL MainSystem
; Exec name
EXEC Kickstart/loader.of
;
; PPC native modules
;
MODULE Kickstart/kernel
;
MODULE Kickstart/FastFileSystem
MODULE Kickstart/CDFileSystem
MODULE Kickstart/NGFileSystem
;
(etc)</nowiki>

Note that lines that start with a semicolon (";") are treated as comments and are ignored. Each configuration must start with a "LABEL" keyword and should be separated from the previous configuration by a blank line. The blank line signifies "Stop loading here".

Each module to be loaded is defined by the "MODULE" keyword, followed by the path and file name. You can use any path ''on the system volume'', so you could have two or more drawers containing Kickstart modules and address them independently if you so wished. You can not refer to modules on other volumes, since they have not been mounted by DOS (which does not exist yet) and only the system volume is available at this early stage.

=== Selecting the Default Configuration ===

You can specify in the NVRAM the label of the default configuration in the Kicklayout. For instance, if your default configuration is called "MainSystem", the LABEL line will look like this:

LABEL MainSystem

You can define an NVRAM variable called "boot_config" using U-Boot, CFE or the "nvsetvar" tool. Simply type:

nvsetvar boot_config "MainSystem"

[Note that nvsetvar may be inhibited from writing to the NVRAM on some systems, in which case you will have to use U-Boot or CFE to set the variable]

If you do not specify a default configuration with the "boot_config" variable, the boot loader will default to the first configuration in the Kicklayout.

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when needed. These files are stored in different directories in the system volume.
A default AmigaOS installation looks like this:

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definitions for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains Internet-related files and configurations
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Lib'''rairies of functions
* Locale
contains all files used to customise the system for your locality (catalogs, keymaps...)
* MUI
contains the files needed for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the system's '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files, not currently used
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default, Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add to the list all files from libs:xad and also xadmaster.library.

= AmigaOS boot procedure =

Classic Amigas with PowerPC accelerators, the original AmigaOne SE/XE and the Sam series of Amigas all use the Second Level Booter (SLB) to read their Kickstart modules from the system volume. The newer A-Eon machines (X1000, X5000, A1222) all use a loader called AmigaBoot. In the X1000, AmigaBoot must be read from an FFS partition, while in the later machines, it is stored in the on-board CF card. The process of loading the kickstart modules is the same in all cases.

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
The BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information is displayed. This shows if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly set up to make this drive useable.
* Depending on how you set up the BIOS it will look on the harddisk to find the Second Level Booter (SLB) or will execute the AmigaBoot program from the on-board NVRAM. Whereas the BIOS does not know about AmigaOS disk structure, the SLB/AmigaBoot will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
SLB/AmigaBoot analyses all Amiga partitions on the system disk. It reads each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partition. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
SLB/AmigaBoot loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* The AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* The Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* The Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2017-09-02T02:18:15Z

Tony Wyatt:

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that translates them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable and script bits set.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage media you can purchase at a computer store. We use them to store our files. They can be internal hard disks, external hard drives, USB interface devices (i.e., SD cards, CF cards, "flash" drives, etc.), and floppy disk drives.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done by virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also, you can see a greyed area which is a blank area on the disk (i.e., no partition is defined at this position). Several different file systems can be used on the same Amiga drive. It's your choice.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we must read the physical data off the partition. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

Volume names can refer to either a physical or virtual named space. See the autodoc section for the ASSIGN command in the C: directory as well as the MOUNT command which provides more information on naming and the concept of volumes.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duty is to draw graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find them all in the '''Kickstart''' directory on the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like the conductor of an orchestra. Its job is to make everything work together. It creates processes, handles memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a unique kernel that has existed since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the user can employ to define some settings before starting AmigaOS
* con-handler.kmod - it directs read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the reads/writes of environment variables
* FileSystem.resource.kmod - handles access to the different filesystems
* gadtools.library.kmod - a collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the reads/writes of game pads and joysticks
* graphics.library.kmod - a collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - a set of functions to read a data stream into memory
* input.device.kmod - handles input events like keyboard events or mouse clicks
* intuition.library.kmod - a collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the reads/writes to the NVRAM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handle the '''Ram disk:'''.
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform low level graphic operations on graphics cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded optionally. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout (now obsolescent)
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* NGFileSystem - an experimental file system designed to gradually replace the FastFileSystem
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allows the use of disks connected to a disk controller. These files are named after the controller they support. As an example, the '''sii3114ide.device.kmod''' allows the use of disks connected to a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

==== Misc modules ====

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== Control of the Kickstart ==

The Kickstart/ drawer contains an ASCII file called "Kicklayout". This file lists all the modules that must be loaded from the system volume during the boot process. It is read by the boot loaders "SLB" or "amigaboot".

The Kicklayout file consists of a number of configurations, each of which describes a set of Kickstart modules. Each configuration has a label and the various configurations are listed by label on the boot screen. The user may elect to load the default configuration or to select any one of the other configurations. Often a developer will have several configurations in his/her Kicklayout file, some of which may be experimental, while the default is a "known good" configuration to which (s)he can fall back.

You can edit the Kicklayout file using Notepad or any other ASCII editor. You are strongly advised to leave the original configuration unchanged (as a fall-back) and to add new configurations at the end of the file, each with its own label. That way you can still recover if you make a mistake while editing.

<nowiki>; Configuration name
LABEL MainSystem
; Exec name
EXEC Kickstart/loader.of
;
; PPC native modules
;
MODULE Kickstart/kernel
;
MODULE Kickstart/FastFileSystem
MODULE Kickstart/CDFileSystem
MODULE Kickstart/NGFileSystem
;
(etc)</nowiki>

Note that lines that start with a semicolon (";") are treated as comments and are ignored. Each configuration must start with a "LABEL" keyword and should be separated from the previous configuration by a blank line. The blank line signifies "Stop loading here".

Each module to be loaded is defined by the "MODULE" keyword, followed by the path and file name. You can use any path ''on the system volume'', so you could have two or more drawers containing Kickstart modules and address them independently if you so wished. You can not refer to modules on other volumes, since they have not been mounted by DOS (which does not exist yet) and only the system volume is available at this early stage.

=== Selecting the Default Configuration ===

You can specify in the NVRAM the label of the default configuration in the Kicklayout. For instance, if your default configuration is called "MainSystem", the LABEL line will look like this:

LABEL MainSystem

You can define an NVRAM variable called "boot_config" using U-Boot, CFE or the "nvsetvar" tool. Simply type:

nvsetvar boot_config "MainSystem"

[Note that nvsetvar may be inhibited from writing to the NVRAM on some systems, in which case you will have to use U-Boot or CFE to set the variable]

If you do not specify a default configuration with the "boot_config" variable, the boot loader will default to the first configuration in the Kicklayout.

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when needed. These files are stored in different directories in the system volume.
A default AmigaOS installation looks like this:

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definitions for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains Internet-related files and configurations
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Lib'''rairies of functions
* Locale
contains all files used to customise the system for your locality (catalogs, keymaps...)
* MUI
contains the files needed for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the system's '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files, not currently used
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default, Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add to the list all files from libs:xad and also xadmaster.library.

= AmigaOS boot procedure =

Classic Amigas with PowerPC accelerators, the original AmigaOne SE/XE and the Sam series of Amigas all use the Second Level Booter (SLB) to read their Kickstart modules from the system volume. The newer A-Eon machines (X1000, X5000, A1222) all use a loader called AmigaBoot, which is stored in the on-board NVRAM or CF card. The process of loading the kickstart modules is the same in all cases.

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
The BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information is displayed. This shows if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly set up to make this drive useable.
* Depending on how you set up the BIOS it will look on the harddisk to find the Second Level Booter (SLB) or will execute the AmigaBoot program from the on-board NVRAM. Whereas the BIOS does not know about AmigaOS disk structure, the SLB/AmigaBoot will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
SLB/AmigaBoot analyses all Amiga partitions on the system disk. It reads each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partition. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
SLB/AmigaBoot loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* The AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* The Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* The Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2017-09-02T02:01:11Z

Tony Wyatt:

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that translates them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable and script bits set.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage media you can purchase at a computer store. We use them to store our files. They can be internal hard disks, external hard drives, USB interface devices (i.e., SD cards, CF cards, "flash" drives, etc.), and floppy disk drives.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done by virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also, you can see a greyed area which is a blank area on the disk (i.e., no partition is defined at this position). Several different file systems can be used on the same Amiga drive. It's your choice.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we must read the physical data off the partition. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

Volume names can refer to either a physical or virtual named space. See the autodoc section for the ASSIGN command in the C: directory as well as the MOUNT command which provides more information on naming and the concept of volumes.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duty is to draw graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find them all in the '''Kickstart''' directory on the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like the conductor of an orchestra. Its job is to make everything work together. It creates processes, handles memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a unique kernel that has existed since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the user can employ to define some settings before starting AmigaOS
* con-handler.kmod - it directs read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the reads/writes of environment variables
* FileSystem.resource.kmod - handles access to the different filesystems
* gadtools.library.kmod - a collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the reads/writes of game pads and joysticks
* graphics.library.kmod - a collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - a set of functions to read a data stream into memory
* input.device.kmod - handles input events like keyboard events or mouse clicks
* intuition.library.kmod - a collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the reads/writes to the NVRAM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handle the '''Ram disk:'''.
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform low level graphic operations on graphics cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded optionally. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout (now obsolescent)
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* NGFileSystem - an experimental file system designed to gradually replace the FastFileSystem
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allows the use of disks connected to a disk controller. These files are named after the controller they support. As an example, the '''sii3114ide.device.kmod''' allows the use of disks connected to a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

==== Misc modules ====

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== Control of the Kickstart ==

The Kickstart/ drawer contains an ASCII file called "Kicklayout". This file lists all the modules that must be loaded from the system volume during the boot process. It is read by the boot loaders "SLB" or "amigaboot".

The Kicklayout file consists of a number of configurations, each of which describes a set of Kickstart modules. Each configuration has a label and the various configurations are listed by label on the boot screen. The user may elect to load the default configuration or to select any one of the other configurations. Often a developer will have several configurations in his/her Kicklayout file, some of which may be experimental, while the default is a "known good" configuration to which (s)he can fall back.

You can edit the Kicklayout file using Notepad or any other ASCII editor. You are strongly advised to leave the original configuration unchanged (as a fall-back) and to add new configurations at the end of the file, each with its own label. That way you can still recover if you make a mistake while editing.

<nowiki>; Configuration name
LABEL MainSystem
; Exec name
EXEC Kickstart/loader.of
;
; PPC native modules
;
MODULE Kickstart/kernel
;
MODULE Kickstart/FastFileSystem
MODULE Kickstart/CDFileSystem
MODULE Kickstart/NGFileSystem
;
(etc)</nowiki>

Note that lines that start with a semicolon (";") are treated as comments and are ignored. Each configuration must start with a "LABEL" keyword and should be separated from the previous configuration by a blank line. The blank line signifies "Stop loading here".

Each module to be loaded is defined by the "MODULE" keyword, followed by the path and file name. You can use any path ''on the system volume'', so you could have two or more drawers containing Kickstart modules and address them independently if you so wished. You can not refer to modules on other volumes, since they have not been mounted by DOS (which does not exist yet) and only the system volume is available at this early stage.

=== Selecting the Default Configuration ===

You can specify in the NVRAM the label of the default configuration in the Kicklayout. For instance, if your default configuration is called "MainSystem", the LABEL line will look like this:

LABEL MainSystem

You can define an NVRAM variable called "boot_config" using U-Boot, CFE or the "nvsetvar" tool. Simply type:

nvsetvar boot_config "MainSystem"

[Note that nvsetvar may be inhibited from writing to the NVRAM on some systems, in which case you will have to use U-Boot or CFE to set the variable]

If you do not specify a default configuration with the "boot_config" variable, the boot loader will default to the first configuration in the Kicklayout.

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when needed. These files are stored in different directories in the system volume.
A default AmigaOS installation looks like this:

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definitions for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains Internet-related files and configurations
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Lib'''rairies of functions
* Locale
contains all files used to customise the system for your locality (catalogs, keymaps...)
* MUI
contains the files needed for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the system's '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files, not currently used
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2017-09-02T01:49:08Z

Tony Wyatt:

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that translates them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable and script bits set.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage media you can purchase at a computer store. We use them to store our files. They can be internal hard disks, external hard drives, USB interface devices (i.e., SD cards, CF cards, "flash" drives, etc.), and floppy disk drives.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done by virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also, you can see a greyed area which is a blank area on the disk (i.e., no partition is defined at this position). Several different file systems can be used on the same Amiga drive. It's your choice.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we must read the physical data off the partition. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

Volume names can refer to either a physical or virtual named space. See the autodoc section for the ASSIGN command in the C: directory as well as the MOUNT command which provides more information on naming and the concept of volumes.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duty is to draw graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find them all in the '''Kickstart''' directory on the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like the conductor of an orchestra. Its job is to make everything work together. It creates processes, handles memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a unique kernel that has existed since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the user can employ to define some settings before starting AmigaOS
* con-handler.kmod - it directs read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the reads/writes of environment variables
* FileSystem.resource.kmod - handles access to the different filesystems
* gadtools.library.kmod - a collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the reads/writes of game pads and joysticks
* graphics.library.kmod - a collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - a set of functions to read a data stream into memory
* input.device.kmod - handles input events like keyboard events or mouse clicks
* intuition.library.kmod - a collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the reads/writes to the NVRAM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handle the '''Ram disk:'''.
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform low level graphic operations on graphics cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded optionally. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout (now obsolescent)
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* NGFileSystem - an experimental file system designed to gradually replace the FastFileSystem
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allows the use of disks connected to a disk controller. These files are named after the controller they support. As an example, the '''sii3114ide.device.kmod''' allows the use of disks connected to a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

==== Misc modules ====

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== Control of the Kickstart ==

The Kickstart/ drawer contains an ASCII file called "Kicklayout". This file lists all the modules that must be loaded from the system volume during the boot process. It is read by the boot loaders "SLB" or "amigaboot".

The Kicklayout file consists of a number of configurations, each of which describes a set of Kickstart modules. Each configuration has a label and the various configurations are listed by label on the boot screen. The user may elect to load the default configuration or to select any one of the other configurations. Often a developer will have several configurations in his/her Kicklayout file, some of which may be experimental, while the default is a "known good" configuration to which (s)he can fall back.

You can edit the Kicklayout file using Notepad or any other ASCII editor. You are strongly advised to leave the original configuration unchanged (as a fall-back) and to add new configurations at the end of the file, each with its own label. That way you can still recover if you make a mistake while editing.

[[File: kicklayout.png|frame|right|Portion of a typical Kicklayout]]

Note that lines that start with a semicolon (";") are treated as comments and are ignored. Each configuration must start with a "LABEL" keyword and should be separated from the previous configuration by a blank line. The blank line signifies "Stop loading here".

Each module to be loaded is defined by the "MODULE" keyword, followed by the path and file name. You can use any path ''on the system volume'', so you could have two or more drawers containing Kickstart modules and address them independently if you so wished. You can not refer to modules on other volumes, since they have not been mounted by DOS (which does not exist yet) and only the system volume is available at this early stage.

=== Selecting the Default Configuration ===

You can specify in the NVRAM the label of the default configuration in the Kicklayout. For instance, if your default configuration is called "MainSystem", the LABEL line will look like this:

LABEL MainSystem

You can define an NVRAM variable called "boot_config" using U-Boot, CFE or the "nvsetvar" tool. Simply type:

nvsetvar boot_config "MainSystem"

[Note that nvsetvar may be inhibited from writing to the NVRAM on some systems, in which case you will have to use U-Boot or CFE to set the variable]

If you do not specify a default configuration with the "boot_config" variable, the boot loader will default to the first configuration in the Kicklayout.

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when needed. These files are stored in different directories in the system volume.
A default AmigaOS installation looks like this:

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definitions for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains Internet-related files and configurations
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Lib'''rairies of functions
* Locale
contains all files used to customise the system for your locality (catalogs, keymaps...)
* MUI
contains the files needed for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the system's '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files, not currently used
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2017-09-02T01:43:27Z

Tony Wyatt:

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that translates them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable and script bits set.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage media you can purchase at a computer store. We use them to store our files. They can be internal hard disks, external hard drives, USB interface devices (i.e., SD cards, CF cards, "flash" drives, etc.), and floppy disk drives.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done by virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also, you can see a greyed area which is a blank area on the disk (i.e., no partition is defined at this position). Several different file systems can be used on the same Amiga drive. It's your choice.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we must read the physical data off the partition. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

Volume names can refer to either a physical or virtual named space. See the autodoc section for the ASSIGN command in the C: directory as well as the MOUNT command which provides more information on naming and the concept of volumes.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duty is to draw graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find them all in the '''Kickstart''' directory on the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like the conductor of an orchestra. Its job is to make everything work together. It creates processes, handles memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a unique kernel that has existed since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the user can employ to define some settings before starting AmigaOS
* con-handler.kmod - it directs read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the reads/writes of environment variables
* FileSystem.resource.kmod - handles access to the different filesystems
* gadtools.library.kmod - a collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the reads/writes of game pads and joysticks
* graphics.library.kmod - a collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - a set of functions to read a data stream into memory
* input.device.kmod - handles input events like keyboard events or mouse clicks
* intuition.library.kmod - a collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the reads/writes to the NVRAM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handle the '''Ram disk:'''.
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform low level graphic operations on graphics cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded optionally. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout (now obsolescent)
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* NGFileSystem - an experimental file system designed to gradually replace the FastFileSystem
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allows the use of disks connected to a disk controller. These files are named after the controller they support. As an example, the '''sii3114ide.device.kmod''' allows the use of disks connected to a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

==== Misc modules ====

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== Control of the Kickstart ==

The Kickstart/ drawer contains an ASCII file called "Kicklayout". This file lists all the modules that must be loaded from the system volume during the boot process. It is read by the boot loaders "SLB" or "amigaboot".

The Kicklayout file consists of a number of configurations, each of which describes a set of Kickstart modules. Each configuration has a label and the various configurations are listed by label on the boot screen. The user may elect to load the default configuration or to select any one of the other configurations. Often a developer will have several configurations in his/her Kicklayout file, some of which may be experimental, while the default is a "known good" configuration to which (s)he can fall back.

You can edit the Kicklayout file using Notepad or any other ASCII editor. You are strongly advised to leave the original configuration unchanged (as a fall-back) and to add new configurations at the end of the file, each with its own label. That way you can still recover if you make a mistake while editing.

[[File: kicklayout.png|frame|right|Portion of a typical Kicklayout]]

Note that lines that start with a semicolon (";") are treated as comments and are ignored. Each configuration must start with a "LABEL" keyword and should be separated from the previous configuration by a blank line. The blank line signifies "Stop loading here".

Each module to be loaded is defined by the "MODULE" keyword, followed by the path and file name. You can use any path ''on the system volume'', so you could have two or more drawers containing Kickstart modules and address them independently if you so wished. You can not refer to modules on other volumes, since they have not been mounted by DOS (which does not exist yet) and only the system volume is available at this early stage.

=== Selecting the Default Configuration ===

You can specify in the NVRAM the label of the default configuration in the Kicklayout. For instance, if your default configuration is called "MainSystem", the LABEL line will look like this:

LABEL MainSystem

You can define an NVRAM variable called "boot_config" using U-Boot, CFE or the "nvsetvar" tool. Simply type:

nvsetvar boot_config "MainSystem"

[Note that nvsetvar may be inhibited from writing to the NVRAM on some systems, in which case you will have to use U-Boot or CFE to set the variable]

If you do not specify a default configuration with the "boot_config" variable, the boot loader will default to the first configuration in the Kicklayout.

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2017-09-02T01:13:11Z

Tony Wyatt:

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage media you can purchase at a computer store. We use them to store our files. They can be internal hard disks, external hard drives, USB interface devices (i.e., SD cards, CF cards, "flash" drives, etc.), and floppy disk drives.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done by virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also, you can see a greyed area which is a blank area on the disk (i.e., no partition is defined at this position). Several different file systems can be used on the same Amiga drive. It's your choice.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

Volume names can refer to either a physical or virtual named space. See the autodoc section for the ASSIGN command in the C: directory as well as the MOUNT command which provides more information on naming and the concept of volumes.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

==== Misc modules ====

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== Control of the Kickstart ==

The Kickstart/ drawer contains an ASCII file called "Kicklayout". This file lists all the modules that must be loaded from the system volume during the boot process. It is read by the boot loaders "SLB" or "amigaboot".

The Kicklayout file consists of a number of configurations, each of which describes a set of Kickstart modules. Each configuration has a label and the various configurations are listed by label on the boot screen. The user may elect to allow the default configuration or to select any one of the other configurations. Often a developer may have several configurations in his/her Kicklayout file, some of which may be experimental, while the default is a "known good" configuration to which (s)he can fall back.

You can edit the Kicklayout file using Notepad or any other ASCII editor. You are strongly advised to leave the original configuration unchanged (as a fall-back) and to add new configurations at the end of the file, each with its own label. That way you can still recover if you make a mistake while editing.

[[File: kicklayout.png|frame|right|Portion of a typical Kicklayout]]

Note that lines that start with a semicolon (";") are treated as comments and are ignored. Each configuration must start with a "LABEL" keyword and should be separated from the previous configuration by a blank line. The blank line signifies "Stop loading here".

Each module to be loaded is defined by the "MODULE" keyword, followed by the path and file name. You can use any path '''on the system volume''', so you could have two or more drawers containing Kickstart modules and address them independently if you so wished. You can not refer to modules on other volumes, since they have not been mounted by DOS (which does not exist yet) and only the system volume is available at this early stage.

=== Selecting the Default Configuration ===

You can specify in the NVRAM the label of the default configuration in the Kicklayout. For instance, if your default configuration is called "MainSystem", the LABEL line will look like this:

LABEL MainSystem

You can define an NVRAM variable called "boot_config" using U-Boot, CFE or the "nvsetvar" tool. Simply type:

nvsetvar boot_config "MainSystem"

[Note that nvsetvar may be inhibited from writing to the NVRAM on some systems, in which case you will have to use U-Boot or CFE to set the variable]

If you do not specify a default configuration with the "boot_config" variable, the boot loader will default to the first configuration in the Kicklayout.

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2017-09-02T00:39:14Z

Tony Wyatt: Added editing description for Kicklayout

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage media you can purchase at a computer store. We use them to store our files. They can be internal hard disks, external hard drives, USB interface devices (i.e., SD cards, CF cards, "flash" drives, etc.), and floppy disk drives.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done by virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also, you can see a greyed area which is a blank area on the disk (i.e., no partition is defined at this position). Several different file systems can be used on the same Amiga drive. It's your choice.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

Volume names can refer to either a physical or virtual named space. See the autodoc section for the ASSIGN command in the C: directory as well as the MOUNT command which provides more information on naming and the concept of volumes.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

=== Control of the Kickstart ===

The Kickstart/ drawer contains an ASCII file called "Kicklayout". This file lists all the modules that must be loaded from the system volume during the boot process. It is read by the boot loaders "SLB" or "amigaboot".

The Kicklayout file consists of a number of configurations, each of which describes a set of Kickstart modules. Each configuration has a label and the various configurations are listed by label on the boot screen. The user may elect to allow the default configuration or to select any one of the available configurations. Often a developer may have several configurations in his/her Kicklayout file, some of which may be experimental, while the default is a "known good" configuration to which (s)he can fall back.

You can edit the Kicklayout file using Notepad or any other ASCIII editor. You are strongly advised to leave the original configuration unchanged (as a fall-back) and to add new configurations at the end of the file, each with its own label. That way you can still recover if you make a mistake while editing.

The individual configurations are headed by lines like these:
; Configuration name
LABEL DefaultSystem
; Exec name
EXEC Kickstart/loader.of
;
; PPC native modules
;
MODULE Kickstart/kernel
(etc)

Note that lines that start with a semicolon (";") are treated as comments and are ignored. Each configuration must start with a "LABEL" and should be separated from the previous configuration by a blank line.

Each module to be loaded is defined by the "MODULE" keyword, followed by the path and file name. You can use any path '''on the system volume''', so you could have two or more drawers containing Kickstart modules and address them independently if you so wished. You can not refer to modules on other volumes, since they have not been mounted by DOS (which does not exist yet) and only the system volume is available at this early stage.

=== Selecting the Default Configuration ===

You can specify in the NVRAM the label of the default configuration in the Kicklayout. For instance, if your default configuration is called "MainSystem", the LABEL line will look like this:

LABEL MainSystem

You can define an NVRAM variable called "boot_config" using U-Boot, CFE or the "nvsetvar" tool. Simply type:

nvsetvar boot_config "MainSystem"

[Note that nvsetvar may be inhibited from writing to the NVRAM on some systems, in which case you will have to use U-Boot or CFE to set the variable]

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

Programming AmigaOS 4: Datatypes - Making Life Easy

2017-08-24T23:14:51Z

Tony Wyatt: Fixed typos in paths, para under heading "DataTypes Internally"

''This article was adapted from Amiga Future magazine's series on developing for AmigaOS....''

Although the Datatypes haven't really been changed or reworked in AmigaOS 4, they should however still be he given some attention in the context of this workshop, because they can make the life of the programmer significantly easier.

Datatypes are an ingenious concept, unlike anything found on other platforms in this form. The specific program requires a file of a certain datatype (such as; images, sound, text) and the operating system automatically takes care of changing the format to the required one on the harddrive, at least when there is an interpreter available.

The main groups that exist are:
{| class="wikitable"
| GID_SYSTEM || (syst) || System-Files
|-
| GID_TEXT || (text) || ASCII-Text
|-
| GID_DOCUMENT || (docu) || Document (Text and Graphics)
|-
| GID_SOUND || (soun) || Sound/Sample
|-
| GID_INSTRUMENT || (inst) || Music instrument
|-
| GID_MUSIC || (musi) || Music
|-
| GID_PICTURE || (pict) || Single Image
|-
| GID_ANIMATION || (anim) || multiple Images/Animation
|-
| GID_MOVIE || (movi) || Animation with graphics and Sound
|}

In the application there should ideally be a rough preliminary check, because in a painting program there will surely be nothing to show for a music file. A conversion of sound into note signs doesn't exist yet, but could be an interesting application. :-)

= The first step =

The simplest function available in the datatype.library is determining of the datatype and respectively the datatype concerning the file. The function IDataTypes->ObtainDataType() expects a Taglist, which in the simplest of cases should only contain the name of the file.

<syntaxhighlight>
if((lock = IDOS->Lock("dateiname",SHARED_LOCK)))
{
if((dtn = IDataTypes->ObtainDataType(DTST_FILE, (APTR) lock, TAG_END)))
{
...
IDataTypes->ReleaseDataType(dtn);
}
IDOS->UnLock(lock);
}
</syntaxhighlight>

So, that leads us right into the first example program "GetFileType.c", which can be given a file and returns the format type as a result. In case AmigaOS can't do anything with this file it returns "Object not found".

<syntaxhighlight>
/* GetFileType.c
*
* gcc GetFileType.c -o GetFileType -l auto
*/

/******************************* INCLUDES *************************************/

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/datatypes.h>
#include <proto/iffparse.h>

/******************************************************************************/

uint32 GetTyp(STRPTR filename)
{
uint32 typ = 0;
BPTR lock;
struct DataType *dtn;
uint8 buffer[5];

if((lock = IDOS->Lock(filename, SHARED_LOCK)))
{
if((dtn = IDataTypes->ObtainDataType(DTST_FILE, (APTR) lock, TAG_END)))
{
const struct DataTypeHeader *dth = dtn->dtn_Header;

IDOS->Printf(" Filename: %s\n", filename);
IDOS->Printf("Description: %s\n", dth->dth_Name);
IDOS->Printf(" Base Name: %s\n", dth->dth_BaseName);
IDOS->Printf(" Type: %s\n", IDataTypes->GetDTString((dth->dth_Flags & DTF_TYPE_MASK) + DTMSG_TYPE_OFFSET));
IDOS->Printf(" Group: %s\n", IDataTypes->GetDTString(dth->dth_GroupID));
IDOS->Printf(" ID: %s\n", IIFFParse->IDtoStr(dth->dth_ID,buffer));

typ = dth->dth_GroupID;

IDataTypes->ReleaseDataType(dtn);
}
else IDOS->PrintFault(IDOS->IoErr(), filename);
IDOS->UnLock(lock);
}
else IDOS->PrintFault(IDOS->IoErr(), filename);

return typ;
}

/******************************************************************************/

int main(int argc, char *argv[])
{
if(argc >= 2) GetTyp(argv[1]);

return 0;
}
</syntaxhighlight>

[[File:AF109_getfiletype_grab.png|frame|center]]

= Here with the file! =

In order to actually get the file we also have to use another function with the name IDataTypes->NewDTObject(). This can even be given the name of the file directly (including path), as well as other parameters with Taglist. In case of an error it returns NULL, otherwise an object which have to be released again at the end with IDataTypes->DisposeDTObject().

<syntaxhighlight>
if((dtobj = IDataTypes->NewDTObject("sample",
DTA_SourceType, DTST_FILE,
DTA_GroupID, GID_SOUND,
TAG_END)))
{
...
IDataTypes->DisposeDTObject(dtobj);
}
</syntaxhighlight>

Merely displaying the file is something which can be handled by the Datatype as well. AddDTObject(), RefreshDTObjects() and RemoveDTObject() take care of this task. For playing back however the Play-Method must be executed:

<syntaxhighlight>
IIntuition->IDoMethod(dt,DTM_TRIGGER,NULL,STM_PLAY,NULL);
</syntaxhighlight>

Usually however you will want to process the file in your own application. In that case IDataTypes->GetDTAttrs(), with which you can request the values, image or sound data for example, will help you along. This time there are two examples concluding this theme: with "ShowPic.c" you can display an image and with "PlaySample.c" you can play back a sample file.

== ShowPic Example ==

<syntaxhighlight>
/* ShowPic.c
*
* gcc ShowPic.c -o ShowPic -l auto
*/

/******************************* INCLUDES *************************************/

#include <exec/types.h>
#include <dos/dos.h>
#include <dos/rdargs.h>
#include <datatypes/datatypes.h>
#include <datatypes/datatypesclass.h>
#include <datatypes/pictureclass.h>
#include <intuition/intuition.h>
#include <intuition/icclass.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/datatypes.h>
#include <proto/graphics.h>
#include <proto/intuition.h>
#include <proto/utility.h>

/*****************************************************************************/

#define OPT_NAME 0

/*****************************************************************************/

void PrintErrorMsg (ULONG errnum, STRPTR name)
{
TEXT errbuff[80];

if(errnum >= DTERROR_UNKNOWN_DATATYPE)
{
/* Datatypes eigener Fehlercode auswerten */
IUtility->SNPrintf(errbuff,sizeof(errbuff),IDataTypes->GetDTString(errnum),name);
}
else
{
/* allgemeinen Fehlertext eintragen */
IDOS->Fault(errnum,NULL,errbuff,sizeof(errbuff));
}

IDOS->Printf("%s\nerror #%ld\n",errbuff,errnum);
}

/*****************************************************************************/

int main(int argc, char *argv[])
{
uint32 options[1] = {0};
struct RDArgs *rdargs;

if((rdargs = IDOS->ReadArgs("NAME/A",(LONG *)options,NULL)))
{
Object *dto;

/* Datatypes Objekt ermitteln */
if((dto = IDataTypes->NewDTObject((APTR)options[OPT_NAME],
DTA_SourceType, DTST_FILE,
DTA_GroupID, GID_PICTURE,
PDTA_DestMode, PMODE_V43, /* Wichtig: 43er Modus aktivieren fÂ¸r 24 Bit Verarbeitung */
TAG_END)))
{
ULONG nomwidth, nomheight;

/* Informationen Â¸ber das Objekt erfragen */
if((IDataTypes->GetDTAttrs(dto,
DTA_NominalHoriz, &nomwidth,
DTA_NominalVert, &nomheight,
TAG_END)))
{
/* Anzeigen der Datei und dessen GrËï¬e */
IDOS->Printf("%s %ld x %ld pixels\n",
options[OPT_NAME], nomwidth, nomheight);
}

/* Umgebungsdaten verarbeiten */
struct dtFrameBox dtf = {0};
struct FrameInfo fri = {0};
dtf.MethodID = DTM_FRAMEBOX;
dtf.dtf_FrameInfo = &fri;
dtf.dtf_ContentsInfo = &fri;
dtf.dtf_SizeFrameInfo = sizeof(struct FrameInfo);
if(!(IDataTypes->DoDTMethodA(dto,NULL,NULL,(Msg)&dtf)))
IDOS->Printf("could not obtain environment information\n");

/* sicherstellen, dass eine GrËï¬e vorhanden ist */
nomwidth = ((nomwidth) ? nomwidth : 600);
nomheight = ((nomheight) ? nomheight : 200);

/* Fenster Ëffnen */
struct Window *win;
if((win = IIntuition->OpenWindowTags(NULL,
WA_InnerWidth, nomwidth,
WA_InnerHeight, nomheight,
WA_Title, options[OPT_NAME],
WA_IDCMP, IDCMP_CLOSEWINDOW | IDCMP_VANILLAKEY | IDCMP_IDCMPUPDATE,
WA_DragBar, TRUE,
WA_DepthGadget, TRUE,
WA_CloseGadget, TRUE,
WA_AutoAdjust, TRUE,
WA_SimpleRefresh, TRUE,
WA_BusyPointer, TRUE,
WA_Activate, TRUE,
TAG_END)))
{
/* Die GrËï¬e fÂ¸r das Datatypes Objekt setzen */
IDataTypes->SetDTAttrs(dto,NULL,NULL,
GA_Left, win->BorderLeft,
GA_Top, win->BorderTop,
GA_Width, win->Width - win->BorderLeft - win->BorderRight,
GA_Height, win->Height - win->BorderTop - win->BorderBottom,
ICA_TARGET, ICTARGET_IDCMP,
TAG_END);

/* Das Datatype Objekt ins Fenster einhâ°ngen */
IDataTypes->AddDTObject(win,NULL,dto,-1);

/* einen Refresh des Datatypes Objekts auslËsen, */
/* damit es im Programmkontext gezeichnet wird */
IDataTypes->RefreshDTObjects(dto,win,NULL,NULL);

BOOL going = TRUE;
while(going)
{
/* warten auf ein Ereignis */
ULONG signal = IExec->Wait((1 << win->UserPort->mp_SigBit) | SIGBREAKF_CTRL_C);

/* bei Benutzerabbruch das Programm beenden */
if(signal & SIGBREAKF_CTRL_C) going = FALSE;

/* alle Nachrichten von Intuition verarbeiten */
struct IntuiMessage *imsg;
while((imsg = (struct IntuiMessage *) IExec->GetMsg(win->UserPort)))
{
struct TagItem *tstate, *tag, *tags;
ULONG tidata;

/* die einzelnen Nachrichten verarbeiten */
switch(imsg->Class)
{
case IDCMP_CLOSEWINDOW:
going = FALSE;
break;

case IDCMP_VANILLAKEY:
if(imsg->Code == 27 /* ESC-Taste */) going = FALSE;
break;

case IDCMP_IDCMPUPDATE:
tstate = tags = (struct TagItem *) imsg->IAddress;
while(tag = IUtility->NextTagItem (&tstate))
{
tidata = tag->ti_Data;
switch(tag->ti_Tag)
{
/* Wartezeiger anzeigen bzw. wegnehmen */
case DTA_Busy:
if(tidata)
IIntuition->SetWindowPointer(win,WA_BusyPointer,TRUE,TAG_END);
else
IIntuition->SetWindowPointer(win,WA_Pointer,NULL,TAG_END);
break;

/* Fehlerbehandlung */
case DTA_ErrorLevel:
if(tidata)
{
const ULONG errnum = IUtility->GetTagData(DTA_ErrorNumber,0,tags);
PrintErrorMsg(errnum,(STRPTR) options[OPT_NAME]);
}
break;

/* Refresh des Datatype-Objekts ausfÂ¸hren */
case DTA_Sync:
IDataTypes->RefreshDTObjects(dto,win,NULL,NULL);
break;
}
}
break;
}

/* verarbeitete Nachrichten zurÂ¸ckschicken */
IExec->ReplyMsg((struct Message *)imsg);
}
}

/* Objekt wieder aus dem Fenster entfernen */
IDataTypes->RemoveDTObject(win,dto);

/* Fenster schlieï¬en */
IIntuition->CloseWindow(win);
}
else IDOS->Printf("could not open window\n");

/* Datatype Objekt freigeben */
IDataTypes->DisposeDTObject(dto);
}
else PrintErrorMsg(IDOS->IoErr(),(STRPTR)options[OPT_NAME]);

IDOS->FreeArgs(rdargs);
} else PrintErrorMsg(IDOS->IoErr(),NULL);

return 0;
}
</syntaxhighlight>

[[File:AF109_showpic_screenshot.png|frame|center]]
[[File:AF109_showpic_result.png|frame|center]]

== PlaySample Example ==

<syntaxhighlight>
/* PlaySample.c
*
* gcc PlaySample.c -o PlaySample -l auto
*/

#define __USE_BASETYPE__

/******************************* INCLUDES *************************************/

#include <exec/types.h>
#include <datatypes/soundclass.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/datatypes.h>
#include <proto/intuition.h>

/******************************************************************************/

extern struct Library *DataTypesBase;
extern struct DataTypesIFace *IDataTypes;
extern struct IntuitionBase *IntuitionBase;
extern struct IntuitionIFace *IIntuition;

/******************************************************************************/

int main(int argc, char *argv[])
{
if(argc >= 2)
{
Object *dt;

/* den Sample via Datatype laden */
if((dt = IDataTypes->NewDTObject(argv[1],
DTA_GroupID, GID_SOUND,
SDTA_SignalTask, IExec->FindTask(NULL),
SDTA_SignalBitMask, SIGBREAKF_CTRL_C,
TAG_END)))
{
uint32 freq, per, len;

/* verschiedene Daten des Samples erfragen */
IDataTypes->GetDTAttrs(dt,
SDTA_SamplesPerSec, &freq,
SDTA_Period, &per,
SDTA_SampleLength, &len,
TAG_END);

IDOS->Printf("Freq: %ld, Period: %ld, Len: %ld\n", freq, per, len);

/* einmal abspielen */
IIntuition->IDoMethod(dt,DTM_TRIGGER,NULL,STM_PLAY,NULL);

/* Signal wenn Sample fertig abgespielt oder Benutzerabbruch */
IExec->Wait(SIGBREAKF_CTRL_C);

/* Datatype freigeben */
IDataTypes->DisposeDTObject(dt);
}
else IDOS->PrintFault(IDOS->IoErr(),argv[1]);

return 0;
}
else return 20;
}
</syntaxhighlight>

[[File:AF109_playsample_screenshot.png|frame|center]]

= Scaling Image files =

Apropos, there is also an option to scale the requested image file straight away, in order to fit it into a window for example. So, in contrast to IGraphics->ScaleBitMap() you can also directly give it the desired height and width. The only disadvantage is that you can only scale the bitmap once before layout (meaning before the method DTM_PROCLAYOUT). The quality of scaling is determined with the tag PDTA_ScaleQuality where 0 if for fast/low quality and 1 for high/slow quality.

<syntaxhighlight>
Object *obj;
if((obj = IDataTypes->NewDTObject(filename,
DTA_SourceType, DTST_FILE,
DTA_GroupID, GID_PICTURE,
PDTA_ScaleQuality, 1,
TAG_END)))
...
struct pdtScale pdt;
pdt.MethodID = PDTM_SCALE;
pdt.ps_NewWidth = width;
pdt.ps_NewHeight = height;
pdt.ps_Flags = 0;
if(!(IDataTypes->DoDTMethodA(obj, (Msg)&pdt)))
IDOS->Printf("Datatype Skalierung fehlgeschlagen
</syntaxhighlight>

The accompanying example program "ScalePic.c" displays the image when it is started in its original size. However, when you change the window size the image will be scaled up or down to fit.

<syntaxhighlight>
/* ScalePic.c
*
* gcc ScalePic.c -o ScalePic -lauto
*/

/******************************* INCLUDES *************************************/

#define __USE_INLINE__
#define __USE_BASETYPE__

#include <exec/types.h>
#include <exec/memory.h>
#include <dos/dos.h>
#include <datatypes/datatypes.h>
#include <datatypes/datatypesclass.h>
#include <datatypes/pictureclass.h>
#include <graphics/gfx.h>
#include <graphics/scale.h>
#include <graphics/displayinfo.h>
#include <intuition/intuition.h>
#include <intuition/intuitionbase.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/graphics.h>
#include <proto/datatypes.h>

/************************ VARIABLEN DEKLARATIONEN *****************************/

struct IntuitionBase *IntuitionBase;
struct GfxBase *GfxBase;
struct Library *DataTypesBase;

Object *dt_Obj;
struct BitMap *dt_Bitmap;
struct Screen *dt_Scr;
struct Window *dt_Win;

/******************************************************************************/

BOOL ErmittleGfxSize(const UBYTE *filename, UWORD *width, UWORD *height)
{
struct BitMapHeader *bmhd;
Object *obj;

if((obj = NewDTObject((APTR)filename,
DTA_SourceType, DTST_FILE,
DTA_GroupID, GID_PICTURE,
TAG_END)))
{
if(GetDTAttrs(obj,
PDTA_BitMapHeader, &bmhd,
TAG_END))
{
*width = bmhd->bmh_Width;
*height = bmhd->bmh_Height;
}
else Printf("Kann Datei nicht laden !\n");

DisposeDTObject(obj);
}

return width && height ? TRUE : FALSE;
}

/*****************************************************************************/

LONG Load(const UBYTE *filename, ULONG scalequality, UWORD width, UWORD height)
{
struct FrameInfo fri = {0};
struct dtFrameBox dtf = {0};
struct gpLayout gpl;
struct pdtScale pdt;

SetWindowPointer(dt_Win,WA_BusyPointer,TRUE,TAG_END);

/* Bilddatei mittels Datatype laden */
if((dt_Obj = NewDTObject((APTR) filename,
DTA_SourceType, DTST_FILE,
DTA_GroupID, GID_PICTURE, /* Datei muï¬ eine Bilddatei sein */
PDTA_DestMode, PMODE_V43, /* fÂ¸r 24 Bit Verarbeitung */
PDTA_Remap, TRUE, /* Farben an Bildschirm anpassen */
PDTA_Screen, dt_Scr, /* diesen Bildschirm dazu verwenden */
PDTA_FreeSourceBitMap, TRUE, /* Source-Bitmap nach Bearbeitung sofort freigeben */
PDTA_ScaleQuality, scalequality, /* 0=schnell, 1=langsam aber gute Qualitâ°t */
TAG_END)))
{
/* Umgebung ermitteln */
dtf.MethodID = DTM_FRAMEBOX;
dtf.dtf_FrameInfo = &fri;
dtf.dtf_ContentsInfo = &fri;
dtf.dtf_SizeFrameInfo = sizeof(struct FrameInfo);
if(IDoMethodA(dt_Obj,(Msg)&dtf) && fri.fri_Dimensions.Depth)
{
/* Bild auf diese GrËï¬e skalieren */
pdt.MethodID = PDTM_SCALE;
pdt.ps_NewWidth = width;
pdt.ps_NewHeight = height;
pdt.ps_Flags = 0;
if(!(IDoMethodA(dt_Obj,(Msg)&pdt)))
Printf("Datatype Skalierung fehlgeschlagen\n");

/* das Bild noch layouten */
gpl.MethodID = DTM_PROCLAYOUT;
gpl.gpl_GInfo = NULL;
gpl.gpl_Initial = 1;
if(IDoMethodA(dt_Obj,(Msg)&gpl))
{
/* angepasste Bitmap erfragen */
GetDTAttrs(dt_Obj,
PDTA_DestBitMap, &dt_Bitmap,
TAG_END);

if(dt_Bitmap)
{
}
else Printf("Keine Bitmap ?\n");
}
else Printf("Kann Bild nicht layouten\n");
}
else Printf("Kann Umgebungsdaten nicht ermitteln\n");
}
else Printf("Kein passender Datentyp ?\n");

SetWindowPointer(dt_Win,WA_Pointer,NULL,TAG_END);

return dt_Bitmap ? TRUE : FALSE;
}

/*****************************************************************************/

void Unload()
{
if(dt_Obj) DisposeDTObject(dt_Obj); dt_Obj = NULL;
}

/*****************************************************************************/

void Display(UWORD width, UWORD height)
{
BltBitMapRastPort(dt_Bitmap,0,0,
dt_Win->RPort,dt_Win->BorderLeft,dt_Win->BorderTop,
width,height, MINTERM_ABC | MINTERM_ABNC);
}

/*****************************************************************************/

int main(int argc, char *argv[])
{
ULONG options[2] = {0};
struct RDArgs *rdargs;

if((rdargs = ReadArgs("NAME/A,SQ=SCALEQUALITY/N",(LONG *)options,NULL)))
{
const UBYTE *filename = (UBYTE*) options[0];
/* wird keine Skalierungsqualitâ°t angegeben ,dann die gute verwenden */
const ULONG scalequality = (options[1] ? *((ULONG*)options[1]) : 1);

IntuitionBase = (struct IntuitionBase *) OpenLibrary("intuition.library", 50);
GfxBase = (struct GfxBase *) OpenLibrary("graphics.library", 50);
DataTypesBase = OpenLibrary("datatypes.library", 50);

if(IntuitionBase && GfxBase && DataTypesBase)
{
dt_Scr = IntuitionBase->ActiveScreen;

UWORD width=0, height=0;
if(ErmittleGfxSize(filename,&width,&height))
{
if((dt_Win = OpenWindowTags(NULL,
WA_Left, 20,
WA_Top, 20,
WA_InnerWidth, width, /* Standard-GrËï¬e */
WA_InnerHeight, height,
WA_MinWidth, 60, /* MinimalgrËï¬e */
WA_MinHeight, 10,
WA_MaxWidth, dt_Scr->Width * 2, /* MaximalgrËï¬e */
WA_MaxHeight, dt_Scr->Height * 2,
WA_DragBar, TRUE,
WA_Activate, TRUE,
WA_CloseGadget, TRUE,
WA_SizeGadget, TRUE,
WA_SmartRefresh, TRUE,
WA_NoCareRefresh, TRUE,
WA_RMBTrap, TRUE,
WA_SizeBBottom, TRUE,
WA_IDCMP, IDCMP_CLOSEWINDOW | IDCMP_NEWSIZE | IDCMP_RAWKEY | IDCMP_MOUSEBUTTONS,
WA_Title, "Skalierbarer Bildanzeiger",
TAG_END)))
{
BOOL laufen = TRUE;
while(laufen)
{
Load(filename,scalequality,width,height); /* Bilddatei laden */
Display(width,height); /* und anzeigen */

/*
** normaler Nachrichtenloop, bis das Fenster geschlossen wird,
** oder CTRL-C an das Programm gesendet wird.
*/
BOOL msglaufen = TRUE;
while(msglaufen)
{
struct IntuiMessage *msg;
const ULONG sigs = Wait(1L << dt_Win->UserPort->mp_SigBit | SIGBREAKF_CTRL_C);

while((msg = (struct IntuiMessage *) GetMsg(dt_Win->UserPort)))
{
if(msg->Class == IDCMP_CLOSEWINDOW)
{
msglaufen = laufen = FALSE;
}
else if(msg->Class == IDCMP_NEWSIZE)
{
msglaufen = FALSE;
width = dt_Win->Width - dt_Win->BorderLeft - dt_Win->BorderRight;
height = dt_Win->Height - dt_Win->BorderTop - dt_Win->BorderBottom;
}
else if(msg->Class == IDCMP_RAWKEY)
{
}

ReplyMsg((struct Message *)msg);
}

if(sigs & SIGBREAKF_CTRL_C)
{
msglaufen = laufen = FALSE;
}
}
}
CloseWindow(dt_Win);
}
else Printf("Ã·ffnen des Fensters fehlgeschlagen.\n");
}
else Printf("Bild '%s' kann nicht geladen werden\n",filename);

Unload();
}
else Printf("Libraries fehlen.\n");

CloseLibrary(DataTypesBase);
CloseLibrary((struct Library *)GfxBase);
CloseLibrary((struct Library *)IntuitionBase);

FreeArgs(rdargs);
}
else PrintFault(IoErr(),"ScalePic");

return 0;
}
</syntaxhighlight>

Scaling quality comparison in 4x enlargement for comparison: On the left level 1 with soft edges. On the right with level one the jagged edges become especially obvious on diagonal edges.

[[File:AF109_skalierungsqualitaet.png|frame|center]]

= AHI for sound =

The sound.datatype takes care of playing back the sample using AHI (Audio Hardware Interface) and not use the old Paula chip for that anymore. Although there is nothing against playing the sample directly from Datatype, it gives you more flexibility when you use the ahi.device directly for this. Also, because it is not all that complicated, we would like to give you an additional short example. As usual a MsgPort and for the conversion an IORequest (AHIRequest here) are required in order to open the ahi.device. The AHIRequest can theoretically be copied multiple times as well when multiple samples should be played (simultaneously). After charging AHIRequest with the sample file the asynchronous playback is done with an IExec-SendIO(), (IExec->DoIO() would result in synchronous playback). The function returns immediately while the request is played back in the background. When this is completed (corresponding to completed playback) we receive the matching message on the message port. At the end of the program the device has to be closed and the MsgPort and Request have to be released. The program frame therefore should look like this:

<syntaxhighlight>
struct Library *AHIBase;
struct MsgPort *AHImp;
struct AHIRequest *AHIio;

if((AHImp = IExec->CreateMsgPort()))
{
if((AHIio = (struct AHIRequest *) IExec->CreateIORequest(AHImp,sizeof(struct AHIRequest))))
{
AHIio->ahir_Version = 4;
if(!(IExec->OpenDevice(AHINAME, 0,(struct IORequest *) AHIio,NULL)))
{
AHIBase = (struct Library *) AHIio->ahir_Std.io_Device;
...
IExec->CloseDevice((struct IORequest *)AHIio);
}
IExec->DeleteIORequest((struct IORequest *)AHIio);
}
IExec->DeleteMsgPort(AHImp);
}
</syntaxhighlight>

= Connecting sound.datatype and ahi.device =

The whole thing becomes truly elegant when the sound files are loaded using datatypes and the ahi.device is used for coordinated playback. In principle the rule is again to use the already discussed method: open ahi.device and datatypes.library and use IDataTypes->NewDataType() to identify the files. With the help of that we now fill the AHIRequest. For that we need to ascertain a few values from Datatype. Especially the address of the file and the playback frequency.

<syntaxhighlight>
BYTE *gb_Data; LONG gb_Length, gb_Freq;
IDataTypes->GetDTAttrs(gb_Obj,
SDTA_Sample, &gb_Data,
SDTA_SampleLength, &gb_Length,
SDTA_SamplesPerSec, &gb_Freq,
TAG_END);
</syntaxhighlight>

The thing is reproduced with IExec->SendIO() and with IExec->Wait() it waits until playback is completed.

<syntaxhighlight>
AHIio->ahir_Std.io_Command = CMD_WRITE;
...
IExec->SendIO((struct IORequest *) AHIio);
IExec->Wait(1L << AHImp->mp_SigBit);
</syntaxhighlight>

It is all shown together once more in the example program "PlayAHI.c".

<syntaxhighlight>
/* PlayAHI.c
*
* gcc PlayAHI.c -o PlayAHI -l auto
*/

/******************************* INCLUDES *************************************/

#define __USE_BASETYPE__

#include <devices/ahi.h>
#include <dos/dosasl.h>
#include <exec/memory.h>
#include <intuition/classusr.h>
#include <datatypes/soundclass.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/ahi.h>
#include <proto/intuition.h>
#include <proto/datatypes.h>

/************************ VARIABLEN DEKLARATIONEN *****************************/

struct Library *AHIBase;
struct Library *DataTypesBase;
struct DataTypesIFace *IDataTypes;
struct MsgPort *AHImp;
struct AHIRequest *AHIio;

BYTE *gb_Data;
LONG gb_Freq;
LONG gb_Length;
Object *gb_Obj;

/******************************************************************************/

BOOL OpenAHI(void)
{
if((AHImp = IExec->AllocSysObjectTags( ASOT_PORT, TAG_END )))
{

if((AHIio = (struct AHIRequest *) IExec->AllocSysObjectTags( ASOT_IOREQUEST,
ASOIOR_Size, sizeof( struct AHIRequest ),
ASOIOR_ReplyPort, AHImp,
TAG_END )))
{
AHIio->ahir_Version = 6;
if(!(IExec->OpenDevice(AHINAME, 0,(struct IORequest *) AHIio, 0)))
{
AHIBase = (struct Library *) AHIio->ahir_Std.io_Device;
}
}
}

return AHIBase ? TRUE : FALSE;
}

/******************************************************************************/

void CloseAHI(void)
{
if(AHIBase) IExec->CloseDevice((struct IORequest *)AHIio); AHIBase = NULL;
if(AHIio) IExec->FreeSysObject(ASOT_IOREQUEST,AHIio); AHIio = NULL;
if(AHImp) IExec->FreeSysObject(ASOT_PORT,AHImp); AHImp = NULL;
}

/******************************************************************************/

BOOL LoadSample(STRPTR filename)
{
if((gb_Obj = IDataTypes->NewDTObject((APTR)filename,
DTA_SourceType, DTST_FILE,
DTA_GroupID, GID_SOUND,
TAG_END)))
{
IDataTypes->GetDTAttrs(gb_Obj,
SDTA_Sample, &gb_Data,
SDTA_SampleLength, &gb_Length,
SDTA_SamplesPerSec, &gb_Freq,
TAG_END);
}

if(gb_Data != 0 && gb_Length > 0 && gb_Freq != 0 && gb_Obj != NULL)
return TRUE;
else
return FALSE;
}

/******************************************************************************/

void UnloadSample(void)
{
if(gb_Obj) IDataTypes->DisposeDTObject(gb_Obj); gb_Obj = NULL;
}

/******************************************************************************/

void Play(void)
{
IDOS->Printf("playing %ld bytes at %ld hz\n", gb_Length, gb_Freq);

AHIio->ahir_Std.io_Message.mn_Node.ln_Pri = 5;
AHIio->ahir_Std.io_Command = CMD_WRITE;
AHIio->ahir_Std.io_Data = gb_Data;
AHIio->ahir_Std.io_Length = gb_Length;
AHIio->ahir_Std.io_Offset = 0;
AHIio->ahir_Frequency = gb_Freq;
AHIio->ahir_Type = AHIST_M8S;
AHIio->ahir_Volume = 0x10000;
AHIio->ahir_Position = 0x8000;
AHIio->ahir_Link = NULL;

IExec->SendIO((struct IORequest *) AHIio);
}

/******************************************************************************/

void StopPlay(void)
{
if(! IExec->CheckIO((struct IORequest *) AHIio))
{
IExec->AbortIO((struct IORequest *) AHIio);
IExec->WaitIO((struct IORequest *) AHIio);
}
}

/******************************************************************************/

int main(int argc, char *argv[])
{
if((DataTypesBase = IExec->OpenLibrary("datatypes.library", 50)))
{
if((IDataTypes = (struct DataTypesIFace *) IExec->GetInterface(DataTypesBase,"main",1,NULL)))
{
if(OpenAHI())
{
if(LoadSample(argv[1]))
{
Play();

const LONG signal = IExec->Wait(SIGBREAKF_CTRL_C | (1L << AHImp->mp_SigBit));
if(signal & SIGBREAKF_CTRL_C) IDOS->Printf("*** break\n");

StopPlay();
}
else IDOS->Printf("Error load sample\n");

UnloadSample();
}
else IDOS->Printf("Error open ahi.device\n");

CloseAHI();

IExec->DropInterface((struct Interface *)IDataTypes);
}
else IDOS->Printf("Error get datatypes interface\n");

IExec->CloseLibrary(DataTypesBase);
}
else IDOS->Printf("Error open datatypes.library V50\n");

return 0;
}
</syntaxhighlight>

[[File:AF109_playahi.png|frame|center]]

= Datatypes internally =

Technically speaking the Datatypes are realised as Shared-Library and stored as single files in the directory "SYS:Classes/Datatypes" with the #?.datatype extension. Whether a datatype is active as well is stored with a second file in the directory "SYS:Devs/DataTypes". These files are already automatically activated at the start of Workbench. Inactive descriptors on the other hand are found in "SYS:Storage/DataTypes" and can additionally be started as well when needed by double clicking the icon.

= In perspective =

In our previous edition we already pointed out the new functions of intuition.library, with which it is even easier to load and use image files from harddisk, without having to do the single steps of datatypes.library. We are talking about IIntuition->ObtainBitMapSource(), IIntuition->ObtainBitMapInstance() and IIntuition->BitMapInstanceControl(). We would like to give you a quick reminder of them in view of this topic.

The other formats, like animation or text, are handled in a similar way. The most important are surely graphics and sounds, which we presented in detail.

= Important tags =

Here is an overview of the most important Datatype-Tags, to be able to query the files with IDataTypes->GetDTAttrs().

picture.datatype:
PDTA_BitMap struct BitMap * BitMap with the graphic data
PDTA_DestBitMap struct BitMap * graphics data adapted to screen colours
PDTA_ColorTable ULONG * Colour table
PDTA_NumColors UWORD Number of colours used in the image
PDTA_BitMapHeader struct BitMapHeader * Graphic-Information (Size etc.)

sound.datatype:
SDTA_SamplesPerSec UWORD Playback speed
SDTA_Period UWORD Playback speed (alternative)
SDTA_Sample UWORD * Sound-File to play
SDTA_SampleLength ULONG Lenght of the sound file
SDTA_VoiceHeader struct VoiceHeader * Sample-Information

text.datatype:
TDTA_Buffer STRPTR Text-File
TDTA_BufferLen ULONG Length of the text files

animation.datatype:
ADTA_Width ULONG Width in Pixels
ADTA_Height ULONG Height in Pixels
ADTA_Depth ULONG Colour depth
ADTA_Frames ULONG Number of frames in the Animation
ADTA_FramesPerSecond ULONG Playback speed
ADTA_Sample UWORD * Sound-file of the Animation

= Authors =

Written by Michael Christoph 
Translation by Richard Mulder. 
Copyright (c) 2013 Michael Christoph

AmigaOS Manual: Workbench ARexx Port

2014-01-28T05:08:58Z

Tony Wyatt: /* WINDOW command */

Workbench acts as an ARexx host under the name of "WORKBENCH". It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the RexxMast program must have been started.

= ACTIVATEWINDOW command =

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Activate the root window. */ ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

= CHANGEWINDOW command =

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window; move it to position 10,30 and change its size to 200x100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

= DELETE command =

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
: <syntaxhighlight>
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

= FAULT command =

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
: <syntaxhighlight>
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

= GETATTR command =

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library.

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "6 26 12 6". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be ' ' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the "MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
: <syntaxhighlight>
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO window_list.count-1
SAY window_list.i;
END;

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

= HELP command =

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
: <syntaxhighlight>
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR' command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

= ICON command =

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

= INFO command =

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

= KEYBOARD command =

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* "test.wb" to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

= LOCKGUI command =

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

= MENU command =

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the "Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the "Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows is currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the "Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

= MOVEWINDOW command =

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

= NEWDRAWER command =

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
: <syntaxhighlight>
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

= RENAME command =

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
: <syntaxhighlight>
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

= RX command =

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

= SIZEWINDOW command =

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window size to 200x100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

= UNLOCKGUI command =

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

= UNZOOMWINDOW command =

; Purpose:
: This command will attempt to return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

= VIEW command =

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Moves the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Moves the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Moves the view left by about 1/8 of the window width. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Moves the view right by about 1/8 of the window width. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window's current view position, use the GETATTR command and query the window's WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
: <syntaxhighlight>
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

= WINDOW command =

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

= WINDOWTOBACK command =

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

= WINDOWTOFRONT command =

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

= ZOOMWINDOW command =

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

AmigaOS Manual: Workbench ARexx Port

2014-01-28T05:04:03Z

Tony Wyatt: /* HELP command */

Workbench acts as an ARexx host under the name of "WORKBENCH". It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the RexxMast program must have been started.

= ACTIVATEWINDOW command =

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Activate the root window. */ ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

= CHANGEWINDOW command =

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window; move it to position 10,30 and change its size to 200x100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

= DELETE command =

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
: <syntaxhighlight>
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

= FAULT command =

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
: <syntaxhighlight>
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

= GETATTR command =

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library.

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "6 26 12 6". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be ' ' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the "MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
: <syntaxhighlight>
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO window_list.count-1
SAY window_list.i;
END;

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

= HELP command =

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
: <syntaxhighlight>
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR' command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

= ICON command =

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

= INFO command =

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

= KEYBOARD command =

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* "test.wb" to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

= LOCKGUI command =

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

= MENU command =

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the "Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the "Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows is currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the "Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

= MOVEWINDOW command =

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

= NEWDRAWER command =

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
: <syntaxhighlight>
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

= RENAME command =

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
: <syntaxhighlight>
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

= RX command =

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

= SIZEWINDOW command =

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window size to 200x100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

= UNLOCKGUI command =

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

= UNZOOMWINDOW command =

; Purpose:
: This command will attempt to return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

= VIEW command =

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Moves the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Moves the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Moves the view left by about 1/8 of the window width. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Moves the view right by about 1/8 of the window width. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window's current view position, use the GETATTR command and query the window's WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
: <syntaxhighlight>
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

= WINDOW command =

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" to for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

= WINDOWTOBACK command =

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

= WINDOWTOFRONT command =

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

= ZOOMWINDOW command =

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

AmigaOS Manual: Workbench ARexx Port

2014-01-28T05:01:07Z

Tony Wyatt: /* VIEW command */

Workbench acts as an ARexx host under the name of "WORKBENCH". It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the RexxMast program must have been started.

= ACTIVATEWINDOW command =

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Activate the root window. */ ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

= CHANGEWINDOW command =

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window; move it to position 10,30 and change its size to 200x100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

= DELETE command =

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
: <syntaxhighlight>
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

= FAULT command =

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
: <syntaxhighlight>
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

= GETATTR command =

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library.

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "6 26 12 6". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be ' ' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the "MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
: <syntaxhighlight>
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO window_list.count-1
SAY window_list.i;
END;

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

= HELP command =

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
: <syntaxhighlight>
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR` command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

= ICON command =

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

= INFO command =

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

= KEYBOARD command =

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* "test.wb" to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

= LOCKGUI command =

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

= MENU command =

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the "Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the "Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows is currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the "Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

= MOVEWINDOW command =

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

= NEWDRAWER command =

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
: <syntaxhighlight>
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

= RENAME command =

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
: <syntaxhighlight>
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

= RX command =

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

= SIZEWINDOW command =

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window size to 200x100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

= UNLOCKGUI command =

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

= UNZOOMWINDOW command =

; Purpose:
: This command will attempt to return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

= VIEW command =

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Moves the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Moves the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Moves the view left by about 1/8 of the window width. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Moves the view right by about 1/8 of the window width. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window's current view position, use the GETATTR command and query the window's WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
: <syntaxhighlight>
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

= WINDOW command =

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" to for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

= WINDOWTOBACK command =

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

= WINDOWTOFRONT command =

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

= ZOOMWINDOW command =

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

AmigaOS Manual: Workbench ARexx Port

2014-01-28T04:57:11Z

Tony Wyatt: /* UNZOOMWINDOW command */

Workbench acts as an ARexx host under the name of "WORKBENCH". It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the RexxMast program must have been started.

= ACTIVATEWINDOW command =

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Activate the root window. */ ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

= CHANGEWINDOW command =

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window; move it to position 10,30 and change its size to 200x100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

= DELETE command =

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
: <syntaxhighlight>
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

= FAULT command =

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
: <syntaxhighlight>
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

= GETATTR command =

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library.

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "6 26 12 6". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be ' ' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the "MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
: <syntaxhighlight>
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO window_list.count-1
SAY window_list.i;
END;

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

= HELP command =

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
: <syntaxhighlight>
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR` command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

= ICON command =

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

= INFO command =

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

= KEYBOARD command =

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* "test.wb" to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

= LOCKGUI command =

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

= MENU command =

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the "Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the "Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows is currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the "Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

= MOVEWINDOW command =

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

= NEWDRAWER command =

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
: <syntaxhighlight>
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

= RENAME command =

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
: <syntaxhighlight>
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

= RX command =

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

= SIZEWINDOW command =

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window size to 200x100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

= UNLOCKGUI command =

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

= UNZOOMWINDOW command =

; Purpose:
: This command will attempt to return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

= VIEW command =

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Move the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Move the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Move the view left by about 1/8 of the window height. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Move the view right by about 1/8 of the window height. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window`s current view position, use the GETATTR command and query the window`s WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
: <syntaxhighlight>
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

= WINDOW command =

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" to for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

= WINDOWTOBACK command =

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

= WINDOWTOFRONT command =

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

= ZOOMWINDOW command =

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

AmigaOS Manual: Workbench ARexx Port

2014-01-28T04:55:26Z

Tony Wyatt: /* SIZEWINDOW command */

Workbench acts as an ARexx host under the name of "WORKBENCH". It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the RexxMast program must have been started.

= ACTIVATEWINDOW command =

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Activate the root window. */ ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

= CHANGEWINDOW command =

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window; move it to position 10,30 and change its size to 200x100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

= DELETE command =

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
: <syntaxhighlight>
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

= FAULT command =

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
: <syntaxhighlight>
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

= GETATTR command =

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library.

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "6 26 12 6". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be ' ' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the "MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
: <syntaxhighlight>
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO window_list.count-1
SAY window_list.i;
END;

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

= HELP command =

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
: <syntaxhighlight>
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR` command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

= ICON command =

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

= INFO command =

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

= KEYBOARD command =

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* "test.wb" to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

= LOCKGUI command =

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

= MENU command =

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the "Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the "Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows is currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the "Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

= MOVEWINDOW command =

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

= NEWDRAWER command =

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
: <syntaxhighlight>
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

= RENAME command =

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
: <syntaxhighlight>
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

= RX command =

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

= SIZEWINDOW command =

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window size to 200x100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

= UNLOCKGUI command =

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

= UNZOOMWINDOW command =

; Purpose:
: This command will attempt return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

= VIEW command =

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Move the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Move the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Move the view left by about 1/8 of the window height. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Move the view right by about 1/8 of the window height. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window`s current view position, use the GETATTR command and query the window`s WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
: <syntaxhighlight>
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

= WINDOW command =

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" to for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

= WINDOWTOBACK command =

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

= WINDOWTOFRONT command =

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

= ZOOMWINDOW command =

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

AmigaOS Manual: Workbench ARexx Port

2014-01-28T04:50:02Z

Tony Wyatt: /* MENU command */

Workbench acts as an ARexx host under the name of "WORKBENCH". It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the RexxMast program must have been started.

= ACTIVATEWINDOW command =

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Activate the root window. */ ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

= CHANGEWINDOW command =

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window; move it to position 10,30 and change its size to 200x100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

= DELETE command =

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
: <syntaxhighlight>
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

= FAULT command =

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
: <syntaxhighlight>
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

= GETATTR command =

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library.

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "6 26 12 6". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be ' ' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the "MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
: <syntaxhighlight>
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO window_list.count-1
SAY window_list.i;
END;

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

= HELP command =

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
: <syntaxhighlight>
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR` command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

= ICON command =

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

= INFO command =

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

= KEYBOARD command =

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* "test.wb" to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

= LOCKGUI command =

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

= MENU command =

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the "Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the "Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows is currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the "Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

= MOVEWINDOW command =

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

= NEWDRAWER command =

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
: <syntaxhighlight>
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

= RENAME command =

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
: <syntaxhighlight>
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

= RX command =

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

= SIZEWINDOW command =

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window size to 200100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

= UNLOCKGUI command =

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

= UNZOOMWINDOW command =

; Purpose:
: This command will attempt return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

= VIEW command =

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Move the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Move the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Move the view left by about 1/8 of the window height. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Move the view right by about 1/8 of the window height. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window`s current view position, use the GETATTR command and query the window`s WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
: <syntaxhighlight>
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

= WINDOW command =

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" to for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

= WINDOWTOBACK command =

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

= WINDOWTOFRONT command =

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

= ZOOMWINDOW command =

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

AmigaOS Manual: Workbench ARexx Port

2014-01-28T04:38:41Z

Tony Wyatt: /* LOCKGUI command */

Workbench acts as an ARexx host under the name of "WORKBENCH". It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the RexxMast program must have been started.

= ACTIVATEWINDOW command =

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Activate the root window. */ ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

= CHANGEWINDOW command =

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window; move it to position 10,30 and change its size to 200x100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

= DELETE command =

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
: <syntaxhighlight>
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

= FAULT command =

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
: <syntaxhighlight>
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

= GETATTR command =

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library.

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "6 26 12 6". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be ' ' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the "MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
: <syntaxhighlight>
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO window_list.count-1
SAY window_list.i;
END;

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

= HELP command =

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
: <syntaxhighlight>
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR` command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

= ICON command =

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

= INFO command =

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

= KEYBOARD command =

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* "test.wb" to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

= LOCKGUI command =

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

= MENU command =

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

= MOVEWINDOW command =

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

= NEWDRAWER command =

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
: <syntaxhighlight>
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

= RENAME command =

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
: <syntaxhighlight>
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

= RX command =

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

= SIZEWINDOW command =

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window size to 200100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

= UNLOCKGUI command =

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

= UNZOOMWINDOW command =

; Purpose:
: This command will attempt return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

= VIEW command =

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Move the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Move the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Move the view left by about 1/8 of the window height. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Move the view right by about 1/8 of the window height. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window`s current view position, use the GETATTR command and query the window`s WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
: <syntaxhighlight>
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

= WINDOW command =

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" to for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

= WINDOWTOBACK command =

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

= WINDOWTOFRONT command =

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

= ZOOMWINDOW command =

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

AmigaOS Manual: Workbench ARexx Port

2014-01-28T04:36:58Z

Tony Wyatt: /* KEYBOARD command */

Workbench acts as an ARexx host under the name of "WORKBENCH". It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the RexxMast program must have been started.

= ACTIVATEWINDOW command =

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Activate the root window. */ ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

= CHANGEWINDOW command =

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window; move it to position 10,30 and change its size to 200x100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

= DELETE command =

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
: <syntaxhighlight>
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

= FAULT command =

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
: <syntaxhighlight>
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

= GETATTR command =

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library.

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "6 26 12 6". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be ' ' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the "MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
: <syntaxhighlight>
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO window_list.count-1
SAY window_list.i;
END;

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

= HELP command =

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
: <syntaxhighlight>
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR` command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

= ICON command =

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

= INFO command =

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

= KEYBOARD command =

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* "test.wb" to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

= LOCKGUI command =

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command nests".

; Example:
: <syntaxhighlight>
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

= MENU command =

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

= MOVEWINDOW command =

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

= NEWDRAWER command =

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
: <syntaxhighlight>
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

= RENAME command =

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
: <syntaxhighlight>
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

= RX command =

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

= SIZEWINDOW command =

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window size to 200100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

= UNLOCKGUI command =

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

= UNZOOMWINDOW command =

; Purpose:
: This command will attempt return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

= VIEW command =

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Move the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Move the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Move the view left by about 1/8 of the window height. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Move the view right by about 1/8 of the window height. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window`s current view position, use the GETATTR command and query the window`s WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
: <syntaxhighlight>
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

= WINDOW command =

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" to for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

= WINDOWTOBACK command =

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

= WINDOWTOFRONT command =

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

= ZOOMWINDOW command =

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

AmigaOS Manual: Workbench ARexx Port

2014-01-28T04:30:16Z

Tony Wyatt: /* GETATTR command */

Workbench acts as an ARexx host under the name of "WORKBENCH". It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the RexxMast program must have been started.

= ACTIVATEWINDOW command =

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Activate the root window. */ ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

= CHANGEWINDOW command =

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window; move it to position 10,30 and change its size to 200x100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

= DELETE command =

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
: <syntaxhighlight>
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

= FAULT command =

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
: <syntaxhighlight>
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

= GETATTR command =

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library.

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "6 26 12 6". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportionally spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be ' ' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the "MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
: <syntaxhighlight>
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO window_list.count-1
SAY window_list.i;
END;

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

= HELP command =

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
: <syntaxhighlight>
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR` command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

= ICON command =

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

= INFO command =

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

= KEYBOARD command =

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* test.wb" to be executed. ARexx will search for that program
* in the REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item * to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

= LOCKGUI command =

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command nests".

; Example:
: <syntaxhighlight>
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

= MENU command =

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

= MOVEWINDOW command =

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

= NEWDRAWER command =

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
: <syntaxhighlight>
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

= RENAME command =

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
: <syntaxhighlight>
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

= RX command =

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

= SIZEWINDOW command =

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window size to 200100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

= UNLOCKGUI command =

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

= UNZOOMWINDOW command =

; Purpose:
: This command will attempt return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

= VIEW command =

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Move the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Move the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Move the view left by about 1/8 of the window height. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Move the view right by about 1/8 of the window height. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window`s current view position, use the GETATTR command and query the window`s WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
: <syntaxhighlight>
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

= WINDOW command =

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" to for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

= WINDOWTOBACK command =

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

= WINDOWTOFRONT command =

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

= ZOOMWINDOW command =

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

AmigaOS Manual: Workbench ARexx Port

2014-01-28T04:19:31Z

Tony Wyatt: /* CHANGEWINDOW command */

Workbench acts as an ARexx host under the name of "WORKBENCH". It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the RexxMast program must have been started.

= ACTIVATEWINDOW command =

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Activate the root window. */ ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

= CHANGEWINDOW command =

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window; move it to position 10,30 and change its size to 200x100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

= DELETE command =

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
: <syntaxhighlight>
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

= FAULT command =

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
: <syntaxhighlight>
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

= GETATTR command =

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library".

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "4 3 4 3". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportional spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportional spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be '' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
: <syntaxhighlight>
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO window_list.count-1
SAY window_list.i;
END;

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

= HELP command =

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
: <syntaxhighlight>
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR` command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

= ICON command =

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

= INFO command =

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

= KEYBOARD command =

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* test.wb" to be executed. ARexx will search for that program
* in the REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item * to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

= LOCKGUI command =

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command nests".

; Example:
: <syntaxhighlight>
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

= MENU command =

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

= MOVEWINDOW command =

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

= NEWDRAWER command =

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
: <syntaxhighlight>
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

= RENAME command =

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
: <syntaxhighlight>
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

= RX command =

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

= SIZEWINDOW command =

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window size to 200100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

= UNLOCKGUI command =

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

= UNZOOMWINDOW command =

; Purpose:
: This command will attempt return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

= VIEW command =

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Move the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Move the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Move the view left by about 1/8 of the window height. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Move the view right by about 1/8 of the window height. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window`s current view position, use the GETATTR command and query the window`s WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
: <syntaxhighlight>
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

= WINDOW command =

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" to for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

= WINDOWTOBACK command =

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

= WINDOWTOFRONT command =

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

= ZOOMWINDOW command =

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

AmigaOS Manual: Workbench ARexx Port

2014-01-28T04:15:48Z

Tony Wyatt: /* ACTIVATEWINDOW command */

Workbench acts as an ARexx host under the name of "WORKBENCH". It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the RexxMast program must have been started.

= ACTIVATEWINDOW command =

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Activate the root window. */ ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

= CHANGEWINDOW command =

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window; move it to position 10,30. * and change its size to 200100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

= DELETE command =

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
: <syntaxhighlight>
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

= FAULT command =

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
: <syntaxhighlight>
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

= GETATTR command =

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library".

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "4 3 4 3". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportional spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportional spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be '' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
: <syntaxhighlight>
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO window_list.count-1
SAY window_list.i;
END;

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

= HELP command =

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
: <syntaxhighlight>
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR` command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

= ICON command =

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

= INFO command =

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

= KEYBOARD command =

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* test.wb" to be executed. ARexx will search for that program
* in the REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item * to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

= LOCKGUI command =

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command nests".

; Example:
: <syntaxhighlight>
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

= MENU command =

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

= MOVEWINDOW command =

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

= NEWDRAWER command =

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
: <syntaxhighlight>
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

= RENAME command =

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
: <syntaxhighlight>
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

= RX command =

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

= SIZEWINDOW command =

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window size to 200100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

= UNLOCKGUI command =

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

= UNZOOMWINDOW command =

; Purpose:
: This command will attempt return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

= VIEW command =

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Move the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Move the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Move the view left by about 1/8 of the window height. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Move the view right by about 1/8 of the window height. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window`s current view position, use the GETATTR command and query the window`s WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
: <syntaxhighlight>
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

= WINDOW command =

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" to for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

= WINDOWTOBACK command =

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

= WINDOWTOFRONT command =

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

= ZOOMWINDOW command =

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

AmigaOS Manual: Workbench ARexx Port

2014-01-28T03:03:29Z

Tony Wyatt: First pass typos

Workbench acts as an ARexx host under the name of "WORKBENCH". It supports a number of commands as will be described below. Note that for the ARexx interface to work, rexxsyslib.library must be installed (this library is part of a regular Workbench installation) and the RexxMast program must have been started.

= ACTIVATEWINDOW command =

; Purpose:
: This command will attempt to make a window the active one.

; Format:
: ACTIVATEWINDOW [WINDOW] <ROOT|Drawer name>

; Template:
: ACTIVATEWINDOW WINDOW

; Parameters:
: WINDOW
:: Either "ROOT" to activate the Workbench root window (where volume icons and AppIcons live) or the fully qualified name of a drawer window to activate. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be activated. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window activated that is not the root window you must make sure that the window name is given as a fully qualified path name. For example Work:" is a fully qualified name, and so is SYS:Utilities". Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Activate the root window. */ ADDRESS workbench
ACTIVATEWINDOW root

/* Activate the "Work:" partition's window. */
ACTIVATEWINDOW 'Work:'
</syntaxhighlight>

= CHANGEWINDOW command =

; Purpose:
: This command will attempt to change the size and the position of a window.

; Format:
: CHANGEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>][[TOPEDGE] <new top edge position>][[WIDTH] <new window width>][[HEIGHT] <new window height>]

; Template:
: CHANGEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N,WIDTH/N,HEIGHT/N

; Parameter:
: WINDOW
:: Either "ROOT" to resize/move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.
: WIDTH
:: New window width.
: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be changed; this can also happen if you specified ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window; move it to position 10,30. * and change its size to 200100 pixels. */
ADDRESS workbench
CHANGEWINDOW root LEFTEDGE 10 TOPEDGE 30 WIDTH 200 HEIGHT 100

/* Change the currently active window. */
CHANGEWINDOW active 20 40 200 100
</syntaxhighlight>

= DELETE command =

; Purpose:
: This command is for deleting files and drawers (and their contents).

; Format:
: DELETE [NAME] <File or drawer name> [ALL]

; Template:
: DELETE NAME/A,ALL/S

; Parameters:
: NAME
:: Name of the file or drawer or volume to delete.

: ALL
:: If the object in question is a drawer, attempt to delete the contents of the drawer as well as the drawer itself. If this option is not specified, the DELETE command will only attempt to delete the drawer itself, which may fail if the drawer is not yet empty.

; Errors:
: 10 - If the named file, drawer or volume could not be found or could not be deleted.

; Result:
: -

; Notes:
: The file name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example:
: <syntaxhighlight>
/* Delete the contents of the drawer RAM:Empty". */

ADDRESS workbench
DELETE 'RAM:Empty' ALL
</syntaxhighlight>

= FAULT command =

; Purpose:
: This command will return a human readable explanation corresponding to an error code.

; Format:
: FAULT [CODE] <Error code>

; Template:
: FAULT CODE/A/N

; Parameters:
: CODE
:: Error code to return a human readable explanation for.

; Errors:
: -

; Result:
: -

; Example:
: <syntaxhighlight>
/* Query the error message corresponding to error code #205. */
ADDRESS workbench
OPTIONS RESULTS
FAULT 205
SAY result
</syntaxhighlight>

= GETATTR command =

; Purpose:
: This command will retrieve information from the Workbench database, such the names of the drawers currently open and the icons currently selected.

; Format:
: GETATTR [OBJECT] <Object name> [NAME <Item name>][STEM <Name of stem variable>] [VAR <Variable name>]

; Template:
: GETATTR OBJECT/A,NAME/K,STEM/K,VAR/K

; Parameters:
: OBJECT
:: Name of the database entry to retrieve. For a list of valid entries see below.

: NAME
:: For some datatabase entries further information is required to identify the data to retrieve. This is when you will need to provide a name.

: STEM
:: If you request more than one database entry you will need to provide a variable to store the information in. For an example of its use, see below.

: VAR
:: If you want the queried information to be stored in a specific variable (other than the RESULT variable), this is where you provide its name.

; Attributes:
: You can obtain information on the following attributes:
: APPLICATION.VERSION
:: Version number of workbench.library".

:APPLICATION.SCREEN
:: Name of the public screen Workbench uses.

: APPLICATION.AREXX
:: Name of the Workbench ARexx port.

: APPLICATION.LASTERROR
:: Number of the last error caused by the ARexx interface.

: APPLICATION.ICONBORDER
:: Sizes of the icon borders, returned as four numbers separated by blank spaces, e.g. "4 3 4 3". The four numbers represent the left border width, the top border height, the right border width and the bottom border height (in exactly that order).

: APPLICATION.FONT.SCREEN.NAME
:: Name of the Workbench screen font.

: APPLICATION.FONT.SCREEN.WIDTH APPLICATION.FONT.SCREEN.HEIGHT
:: Size of a single character of the Workbench screen font. Please note that since the font in question may be proportional spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.SCREEN.SIZE
:: Size of a text, measured in pixels, in reference to the screen font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.ICON.NAME
:: Name of the Workbench icon font.

: APPLICATION.FONT.ICON.WIDTH APPLICATION.FONT.ICON.HEIGHT
:: Size of a single character of the Workbench icon font. Please note that since the font in question may be proportional spaced the width information may be of little value. To measure the accurate pixel width of a text in reference to the font, use the .SIZE attribute.

: APPLICATION.FONT.ICON.SIZE
:: Size of a text, measured in pixels, in reference to the icon font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: APPLICATION.FONT.SYSTEM.NAME
:: Name of the system font.

: APPLICATION.FONT.SYSTEM.WIDTH
: APPLICATION.FONT.SYSTEM.HEIGHT
:: Size of a single character of the system font.

: APPLICATION.FONT.SYSTEM.SIZE
:: Size of a text, measured in pixels, in reference to the system font. The text to measure must be provided with the NAME parameter of the GETATTR command.

: WINDOWS.COUNT
:: Number of the drawer windows currently open. This can be 0.

: WINDOWS.0 .. WINDOWS.N
:: Names of the windows currently open.

: WINDOWS.ACTIVE
:: Name of the currently active Workbench window; this will be '' if none of Workbench's windows is currently active.

: KEYCOMMANDS.COUNT
:: Number of keyboard commands assigned. This can be 0.

: KEYCOMMANDS.0 .. KEYCOMMANDS.N
:: Information on all the keyboard commands assigned.

: KEYCOMMANDS.<n>.NAME
:: Name of the keyboard command.

: KEYCOMMANDS.<n>.KEY
:: The key combination assigned to this keyboard command.

: KEYCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this key combination.

: MENUCOMMANDS.COUNT
:: Number of menu commands assigned (through the MENU ADD .." command). This can be 0.

: MENUCOMMANDS.0 .. MENUCOMMANDS.N
:: Information on all the menu commands assigned.

: MENUCOMMANDS.<n>.NAME
:: Name of this menu item.

: MENUCOMMANDS.<n>.TITLE
:: Title of this menu item.

: MENUCOMMANDS.<n>.SHORTCUT
:: The keyboard shortcut assigned to this menu item.

: MENUCOMMANDS.<n>.COMMAND
:: The ARexx command assigned to this menu item.

: The following attributes require the name of the window to obtain information.
: WINDOW.LEFT
:: Left edge of the window.

: WINDOW.TOP
:: Top edge of the window.

: WINDOW.WIDTH
:: Width of the window.

: WINDOW.HEIGHT
:: Height of the window.

: WINDOW.MIN.WIDTH
:: Minimum width of the window.

: WINDOW.MIN.HEIGHT
:: Minimum height of the window.

: WINDOW.MAX.WIDTH
:: Maximum width of the window.

: WINDOW.MAX.HEIGHT
:: Maximum height of the window.

: WINDOW.VIEW.LEFT
:: Horizontal offset of the drawer contents; this value corresponds to the horizontal window scroller position.

: WINDOW.VIEW.TOP
:: Vertical offset of the drawer contents; this value corresponds to the vertical window scroller position.

: WINDOW.SCREEN.NAME
:: Name of the public screen the window was opened on.

: WINDOW.SCREEN.WIDTH WINDOW.SCREEN.HEIGHT
:: Size of the public screen the window was opened on.

: WINDOW.ICONS.ALL.COUNT
:: Number of the icons displayed in the window. This can be 0.

: WINDOW.ICONS.ALL.0 .. WINDOW.ICONS.ALL.N
:: Information on all the icons displayed in the window:

: WINDOW.ICONS.ALL.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.ALL.<n>.LEFT WINDOW.ICONS.ALL.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.ALL.<n>.WIDTH WINDOW.ICONS.ALL.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.ALL.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.ALL.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and "CLOSED".

: WINDOW.ICONS.SELECTED.COUNT
:: Number of the selected icons displayed in the window. This can be 0.

: WINDOW.ICONS.SELECTED.0 .. WINDOW.ICONS.SELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.SELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.LEFT WINDOW.ICONS.SELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.WIDTH WINDOW.ICONS.SELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.SELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT,GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.SELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "SELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "UNSELECTED" and CLOSED". Of course, for the WINDOW.ICONS.SELECTED stem the icon status will always be reported as "SELECTED".

: WINDOW.ICONS.UNSELECTED.COUNT
:: Number of the unselected icons displayed in the window. This can be 0.

: WINDOW.ICONS.UNSELECTED.0 .. WINDOW.ICONS.UNSELECTED.N
:: Information on all selected the icons in the window:

: WINDOW.ICONS.UNSELECTED.<n>.NAME
:: Name of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.LEFT WINDOW.ICONS.UNSELECTED.<n>.TOP
:: Position of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.WIDTH WINDOW.ICONS.UNSELECTED.<n>.HEIGHT
:: Size of the icon in question.

: WINDOW.ICONS.UNSELECTED.<n>.TYPE
:: Type of the icon; one of DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON.

: WINDOW.ICONS.UNSELECTED.<n>.STATUS
:: Whether the icon is selected and (if the icon is a drawer-like object, such as a disk, drawer or trashcan icon) whether the corresponding drawer is currently open or closed. This attribute is returned in the form of a string, such as "UNSELECTED OPEN" which means that the icon is selected and the corresponding drawer is currently open. The other options include "SELECTED" and CLOSED". Of course, for the WINDOW.ICONS.UNSELECTED stem the icon status will always be reported as "UNSELECTED".

; Errors:
: 10 - If the requester information could not be retrieved, you requested more than one database entry and did not provide a stem variable or if you provided a stem variable but did not request more than one database entry. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT - The information retrieved from the database.

; Example:
: <syntaxhighlight>
/* Query the Workbench version. */
ADDRESS workbench
OPTIONS RESULTS

GETATTR application.version
SAY result

/* Query the Workbench version and store it in the * variable 'version_number'. */
GETATTR application.version
VAR version_number
SAY version_number

/* Query the names of all currently open windows, * then print them. */
GETATTR windows
STEM window_list

DO i = 0 TO window_list.count-1
SAY window_list.i;
END;

/* Query name, position and size of the first icon * shown in the root window. */
GETATTR window.icons.all.0
NAME root
STEM root

SAY root.name
SAY root.left
SAY root.top
SAY root.width
SAY root.height
SAY root.type

/* Query the width and height of the root window. */
GETATTR window.width
NAME root
SAY result

GETATTR window.height
NAME root
SAY result

/* Query the length of a text (in pixels) with reference * to the icon font. */
GETATTR application.font.icon.size
NAME 'Text to measure'
SAY result
</syntaxhighlight>

= HELP command =

; Purpose:
: This command can be used to open the online help and to obtain information on the supported menus, commands and command parameters.

; Format:
: HELP [COMMAND <Command name>] [MENUS] [PROMPT]

; Template:
: HELP COMMAND/K,MENUS/S,PROMPT/S

; Parameters:
: COMMAND
:: Name of the command whose command template should be retrieved.

: MENUS
:: Specify this parameter to retrieve a list of menu items currently available.

: PROMPT
:: Specify this parameter to invoke the online help system.

:: If no parameter is provided, a list of supported commands will be returned.

; Errors:
: 10 - If the named command is not supported by the ARexx interface. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: RESULT
: The command template, list of menu items or commands, as specified in the command parameters.

; Example:
: <syntaxhighlight>
/* Retrieve the list of supported commands. */
ADDRESS workbench
OPTIONS results

HELP
SAY result

/* Retrieve the command template of the 'GETATTR` command. */
HELP COMMAND getattr
SAY result

/* Retrieve the list of available menu items. */
HELP MENUS
SAY result
</syntaxhighlight>

= ICON command =

; Purpose:
: This command is for manipulating the icons displayed in a window.

; Format:
: ICON [WINDOW] <Window name> <Icon name> .. <Icon name> [OPEN] [MAKEVISIBLE] [SELECT] [UNSELECT] [UP <Pixels>] [DOWN <Pixels>] [LEFT <Pixels>] [RIGHT <Pixels>] [X <Horizontal position>] [Y <Vertical position>] [ACTIVATE UP|DOWN|LEFT|RIGHT] [CYCLE PREVIOUS|NEXT] [MOVE IN|OUT]

; Template:
: ICON WINDOW,NAMES/M,OPEN/S,MAKEVISIBLE/S,SELECT/S,UNSELECT/S, UP/N,DOWN/N,LEFT/N,RIGHT/N,X/N,Y/N,ACTIVATE/K,CYCLE/K, MOVE/K

; Parameters:
: WINDOW
:: Name of the window whose icons should be manipulated. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: NAMES
:: Names of the icons to manipulate.

: OPEN
:: Specifies that the named icons should be opened.

: MAKEVISIBLE
:: Specifies that the named icons should be made visible. This generally works well for the first icon in a list but does not always work for a whole list.

: SELECT
:: Select the named icons.

: UNSELECT
:: Unselect the named icons.

: UP, DOWN, LEFT, RIGHT
:: Move the named icons by the specified number of pixels.

: X, Y
:: Move the named icons to the specified position.

: ACTIVATE
:: This command is for activating the icon closest to the currently selected icon in the window. "Activating" in this context means selecting an icon, whilst at the same time unselecting all others. Thus, the "active" icon is the only selected icon in the window.

:: You can indicate which direction the next icon to be activated should be searched for, relative to the currently active icon. "UP" searches upwards, "DOWN" searches downwards, "LEFT" searches to the left and "RIGHT" searches to the right.

: CYCLE
:: This command is for cycling through all icons in a window, making each one the active one in turn (for a description of what "active" means in this context, see the "ACTIVATE" description above). You must indicate in which direction you want to cycle through the icons: you can either specify "PREVIOUS" or "NEXT".

: MOVE
:: This command is not for moving icons but for moving through a file system hierarchy. Thus, moving "in" will open a drawer and moving "out" will open the drawer's parent directory. The "IN" parameter will cause the drawer represented by the active icon to be opened. Please note that an icon must be selected and it must be a drawer. The "OUT" parameter will open the drawer's parent directory, and it also requires that in the drawer there is an icon selected. This may sound strange, but this feature is not meant as a replacement for the "Open Parent" menu item.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Select the icons of the "Workbench" and "Work" volumes displayed in the root window. */
ADDRESS workbench

ICON WINDOW root
NAMES Workbench Work SELECT

/* Open the "Workbench" volume icon displayed in the root window. */
ICON WINDOW root
NAMES Workbench OPEN
</syntaxhighlight>

= INFO command =

; Purpose:
: This command is for opening the Workbench icon information requester.

; Format:
: INFO [NAME] <File, drawer or volume name>

; Template:
: INFO NAME/A

; Parameters :
: NAME
:: Name of the file, drawer or volume to open the information window for.

; Errors:
: 10 - If the named file, drawer or volume could not be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Open the information window for SYS:". */
ADDRESS workbench

INFO NAME 'SYS:'
</syntaxhighlight>

= KEYBOARD command =

; Purpose:
: This command can be used to bind ARexx commands to key combinations.

; Format:
: KEYBOARD [NAME] <Name of key combination> ADD|REMOVE [KEY <Key combination>] [CMD <ARexx command>]

; Template:
: KEYBOARD NAME/A,ADD/S,REMOVE/S,KEY,CMD/F

; Parameters:
: NAME
:: Name of the key combination to add or remove. Each key combination must have a name with which it is associated. The name must be unique.

: ADD
:: This tells the KEYBOARD command to add a new keyboard combination. You will also need to specify the KEY and CMD parameters.

: REMOVE
:: This tells the KEYBOARD command to remove an existing keyboard combination.

: KEY
:: The keyboard combination to add; this must be in the same format as used by the Commodities programs.

: CMD
:: This is the ARexx command to bind to the keyboard combination. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

; Errors:
: 10 - The command will fail if you tried to add a duplicate of an existing key combination or if the key combination to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Bind an ARexx script to the [Control]+A key combination.
* When pressed, this will cause the ARexx script by the name
* test.wb" to be executed. ARexx will search for that program
* in the REXX:" directory. If no "test.wb" file can be found, ARexx will attempt to execute a script
* by the name of test.rexx". */

ADDRESS workbench

KEYBOARD ADD NAME test1 KEY ,"ctrl a", CMD ,'test'

/* Bind an ARexx script to the [Alt]+[F1] key combination.
* When pressed, this will cause a short inline program to be
* executed. */
KEYBOARD ADD NAME test2 KEY ,"alt f1", CMD "say 42"

/* Bind an ARexx script to the [Shift]+[Help] key combination.
* When pressed, this will cause the "Workbench About" menu item * to be invoked. */
KEYBOARD ADD NAME test3 KEY ,"shift help", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first key combination we added above. */
KEYBOARD REMOVE NAME test1
</syntaxhighlight>

= LOCKGUI command =

; Purpose:
: This command will block access to all Workbench drawer windows.

; Format:
: LOCKGUI

; Template:
: LOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command nests".

; Example:
: <syntaxhighlight>
/* Block access to all Workbench drawer windows. */
ADDRESS workbench

LOCKGUI
</syntaxhighlight>

= MENU command =

; Purpose:
: This command is for invoking items of the Workbench menu, as if the user had selected them with the mouse and for adding/removing user menus.

; Format:
: MENU [WINDOW <Window name>] [INVOKE] <Menu name> [NAME <Menu name>] [TITLE <Menu title>] [SHORTCUT <Menu shortcut>] [ADD|REMOVE] [CMD <ARexx command>]

; Template:
: MENU WINDOW/K,INVOKE,NAME/K,TITLE/K,SHORTCUT/K,ADD/S,REMOVE/S,CMD/K/F

; Parameters:
: The following set of parameters can be used solely for invoking menu items.
: WINDOW
:: Name of the window whose menu should be invoked. This can be "ROOT" to work on the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to work on the currently active Workbench window or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: INVOKE
:: Name of the menu to invoke. See below for a list of available menu items.

: The following set of parameters are for adding and removing menu items.
: NAME
:: Name of the menu item to add or remove. Each menu item must have a name with which it is associated. The name must be unique and has nothing to do with the title of the item, as shown in the Tools" menu.

: TITLE
:: This is the text that will be used as the menu item title, as it will appear in the Tools" menu. This parameter is required if you ADD a new menu item.

: SHORTCUT
:: When adding a new menu item, this will be the menu shortcut associated with the item. Please note that the shortcut cannot be longer than a single character and that it will be ignored if there already is an item in any of the menus which uses this shortcut. This parameter is optional.

: ADD
:: This tells the MENU command to add a new item to the "Tools" menu. When adding a menu item you will also need to specify the NAME, TITLE and CMD parameters.

: REMOVE
:: This tells the MENU command to remove a menu item previously added via the ARexx interface. When removing a menu item you will also need to specify the NAME parameter.

: CMD
:: This is the ARexx command to bind to the new menu item. The command can either be the name of an ARexx script to execute or a short ARexx program in a single line.

: Menu items:
: WORKBENCH.BACKDROP
:: Toggles the Workbench "Backdrop" window switch.

: WORKBENCH.EXECUTE
:: Invokes the Workbench "Execute Command" requester. The user will be prompted to enter the command to be executed.

: WORKBENCH.REDRAWALL
:: Invokes the Workbench "Redraw All" function.

: WORKBENCH.UPDATEALL
:: Invokes the Workbench "Update All" function.

: WORKBENCH.LASTMESSAGE
:: Redisplays the last Workbench error message.

: WORKBENCH.ABOUT
:: Displays the "Workbench About..." requester.

: WORKBENCH.QUIT
:: Attempts to close Workbench; this may bring up a requester the user will have to answer.

: WINDOW.NEWDRAWER
:: Prompts the user to enter the name of a new drawer to be created.

: WINDOW.OPENPARENT
:: If possible, this will open the parent directory of the drawer the command operates on.

: WINDOW.CLOSE
:: If possible, this will close the drawer the command operates on.

: WINDOW.UPDATE
:: This will update the drawer the command operates on, i.e. the contents will be reread.

: WINDOW.SELECTCONTENTS
:: This will select the contents of the drawer the command operates on.

: WINDOW.CLEARSELECTION
:: This unselects all icons selected in the drawer the command operates on.

: WINDOW.CLEANUPBY.COLUMN
:: This will sort the contents of the drawer and place the icons in columns.

: WINDOW.CLEANUPBY.NAME
:: This will sort the contents of the drawer by name and place the icons in rows.

: WINDOW.CLEANUPBY.DATE
:: This will sort the contents of the drawer by date and place the icons in rows.

: WINDOW.CLEANUPBY.SIZE
:: This will sort the contents of the drawer by size and place the icons in rows.

: WINDOW.CLEANUPBY.TYPE
:: This will sort the contents of the drawer by type and place the icons in rows.

: WINDOW.RESIZETOFIT
:: This will resize the drawer window, trying to make it just as large as to allow all its icons to fit.

: WINDOW.SNAPSHOT.WINDOW
:: This will snapshot the drawer window, but none of its contents.

: WINDOW.SNAPSHOT.ALL
:: This will snapshot the drawer window and its contents.

: WINDOW.SHOW.ONLYICONS
:: This will change the display mode of the drawer to show only files and drawers which have icons attached.

: WINDOW.SHOW.ALLFILES
:: This will change the display mode of the drawer to show all files and drawers, regardless of whether they have icons attached or not.

: WINDOW.VIEWBY.ICON
:: This will change the display mode of the drawer to show its contents as icons.

: WINDOW.VIEWBY.NAME
:: This will change the display mode of the drawer to show its contents in textual format, sorted by name.

: WINDOW.VIEWBY.DATE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by date.

: WINDOW.VIEWBY.SIZE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by size.

: WINDOW.VIEWBY.TYPE
:: This will change the display mode of the drawer to show its contents in textual format, sorted by type.

: ICONS.OPEN
:: This will open the currently selected icons. Workbench may bring up a requester in case project icons are found which lack a default tool.

: ICONS.COPY
:: This will duplicate the currently selected icons.

: ICONS.RENAME
:: This will prompt the user to choose a new name for each currently selected icon.

: ICONS.INFORMATION
:: This will open the information window for every currently selected icon.

: ICONS.SNAPSHOT
:: This will lock the position of every currently selected icon.

: ICONS.UNSNAPSHOT
:: This will unlock the position of every currently selected icon.

: ICONS.LEAVEOUT
:: This will permanently put all currently selected icons on the Workbench root window.

: ICONS.PUTAWAY
:: This will move all currently selected icons out of the root window and put them back into the drawers they belong.

: ICONS.DELETE
:: This will cause all currently selected files to be deleted, provided the user confirms this action first.

: ICONS.FORMATDISK
:: This will invoke the "Format" command on every currently selected disk icon. This will not format the disks immediately. The user will have to confirm this action first.

: ICONS.EMPTYTRASH
:: With a trashcan icon selected, this will empty it.

: TOOLS.RESETWB
:: This will close and reopen all Workbench windows.

: The HELP command will provide a complete list of menu items that can be invoked. Depending on the state of each menu item (e.g. the "Open" menu item will be disabled if no icon is currently selected) the MENU command can silently fail to invoke the item you had in mind.

; Errors:
: 10 - If the named window cannot be found, none of the Workbench windows are currently active and the command was set to work on the currently active Workbench window. The command can also fail if you tried to add a duplicate of an existing menu item or if the menu item to remove does not exist. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Invoke the "About" menu. */
ADDRESS workbench

MENU WINDOW root INVOKE WORKBENCH.ABOUT

/* Add an item to the Tools" menu; selecting it
* will cause the ARexx script by the name "test.wb"
* to be executed. ARexx will search for that program
* in the "REXX:" directory. If no "test.wb" file can
* be found, ARexx will attempt to execute a script
* by the name of "test.rexx". */
MENU ADD NAME test1 TITLE ,"Execute a script", SHORTCUT ,'!' CMD ,'test'

/* Add an item to the "Tools" menu; selecting it
* will cause a short inline program to be executed. */
MENU ADD NAME test2 TITLE ,"Short inline program", CMD "say 42"

/* Add an item to the "Tools" menu; selecting it
* will cause the Workbench "About" menu item to be invoked. */
MENU ADD NAME test3 TITLE ,"About...", CMD "MENU INVOKE WORKBENCH.ABOUT"

/* Remove the first menu item we added above. */
MENU REMOVE NAME test1
</syntaxhighlight>

= MOVEWINDOW command =

; Purpose:
: This command will attempt to change the position of a window.

; Format:
: MOVEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[LEFTEDGE] <new left edge position>] [[TOPEDGE] <new top edge position>]

; Template:
: MOVEWINDOW WINDOW,LEFTEDGE/N,TOPEDGE/N

; Parameters:
: WINDOW
:: Either "ROOT" to move the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to move the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: LEFTEDGE
:: New left edge window position.

: TOPEDGE
:: New top edge window position.

; Errors:
: 10 - If the named window cannot be moved; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Move the root window to position 10,30. */
ADDRESS workbench

MOVEWINDOW root LEFTEDGE 10 TOPEDGE 30

/* Move the currently active window. */
MOVEWINDOW active 20 40
</syntaxhighlight>

= NEWDRAWER command =

; Purpose:
: This command is for creating new drawers.

; Format:
: NEWDRAWER [NAME] <Name of drawer to create>

; Template:
: NEWDRAWER NAME/A

; Parameters:
: NAME
:: Name of the drawer to be created.

; Errors:
: 10 - If the named drawer could not be created.

; Result:
: -

; Notes:
: The drawer name given must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney" will not work.

; Example :
: <syntaxhighlight>
/* Create a drawer by the name of "Empty" in the RAM disk. */
ADDRESS workbench

NEWDRAWER 'RAM:Empty'
</syntaxhighlight>

= RENAME command =

; Purpose:
: This command is for renaming files, drawers and volumes.

; Format:
: RENAME [OLDNAME] <Name of file/drawer/volume to rename> [NEWNAME] <New name of the file/drawer/volume>

; Template:
: RENAME OLDNAME/A,NEWNAME/A

; Parameters:
: OLDNAME
:: Name of the file/drawer/volume to be renamed. This must be an absolute path, such as in "RAM:Empty". A relative path, such as "/fred/barney", will not work.

: NEWNAME
:: The new name to assign to the file/drawer/volume. This must not be an absolute or relative path. For example, "wilma" is valid new name, "/wilma" or "wilma:" would be invalid names.

; Errors:
: 10 - If the object cannot be renamed.

; Result:
: -

; Notes:
: The RENAME command does not work like for example the AmigaDOS "Rename" command. For example, RENAME 'ram:empty' ,'newname' will rename the file 'RAM:empty' to 'RAM:newname'.

; Example:
: <syntaxhighlight>
/* Rename a drawer by the name of "Old" in the RAM disk to "New". */
ADDRESS workbench

RENAME 'RAM:Old' 'New'
</syntaxhighlight>

= RX command =

; Purpose:
: This command is for executing ARexx scripts and commands.

; Format:
: RX [CONSOLE] [ASYNC] [CMD] <Command to execute>

; Template:
: RX CONSOLE/S,ASYNC/S,CMD/A/F

; Parameters:
: CONSOLE
:: This switch indicates that a console (for default I/O) is needed.

: ASYNC
:: This switch indicates that the command should be run asynchronously, i.e. the "RX" command will return as soon as ARexx has been instructed to run the command you specified. Otherwise, the "RX" command will wait for the specified ARexx command to complete execution.

: COMMAND
:: This is the name of the ARexx program to execute.

; Errors:
: 10 - If the given ARexx program could not be executed.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Execute an ARexx program by the name of 'test.wb';
* its output should be sent to a console window. */
ADDRESS workbench

RX CONSOLE CMD 'test.wb'
</syntaxhighlight>

= SIZEWINDOW command =

; Purpose:
: This command will attempt to change the size of a window.

; Format:
: SIZEWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name> [[WIDTH] <new window width>] [[HEIGHT] <new window height>]

; Template:
: SIZEWINDOW WINDOW,WIDTH/N,HEIGHT/N

; Parameters:
: WINDOW
:: Either "ROOT" to resize the Workbench root window (where volume icons and AppIcons live), "ACTIVE" to resize the currently active Workbench window or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: WIDTH
:: New window width.

: HEIGHT
:: New window height.

; Errors:
: 10 - If the named window cannot be resized; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window resized that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Change the root window size to 200100 pixels. */
ADDRESS workbench

SIZEWINDOW root 30 WIDTH 200 HEIGHT 100

/* Resize the currently active window. */
SIZEWINDOW active 200 100
</syntaxhighlight>

= UNLOCKGUI command =

; Purpose:
: This command will allow access to all Workbench drawer windows locked with the LOCKGUI command.

; Format:
: UNLOCKGUI

; Template:
: UNLOCKGUI

; Parameters:
: -

; Errors:
: -

; Result:
: -

; Notes:
: It takes as many UNLOCKGUI commands as there were LOCKGUI commands to make the Workbench drawer windows usable again. In other words, the LOCKGUI command "nests".

; Example:
: <syntaxhighlight>
/* Reallow access to all Workbench drawer windows. */
ADDRESS workbench

UNLOCKGUI
</syntaxhighlight>

= UNZOOMWINDOW command =

; Purpose:
: This command will attempt return a window to its original position and dimensions.

; Format:
: UNZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: UNZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

UNZOOMWINDOW root
</syntaxhighlight>

= VIEW command =

; Purpose:
: This command will change the position of the viewable display area of a window.

; Format:
: VIEW [WINDOW] <ROOT|ACTIVE|Drawer name> [PAGE|PIXEL] [UP|DOWN|LEFT|RIGHT]

; Template:
: VIEW WINDOW,PAGE/S,PIXEL/S,UP/S,DOWN/S,LEFT/S,RIGHT/S

; Parameters:
: WINDOW
:: Either "ROOT" to change the Workbench root window view (where volume icons and AppIcons live), "ACTIVE" to change the currently active Workbench window view or the fully qualified name of a drawer window to change. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

: UP
:: Move the view up by about 1/8 of the window height. If PAGE is specified, moves the view up by a whole page. If PIXEL is specified, moves the view up by a single pixel.

: DOWN
:: Move the view down by about 1/8 of the window height. If PAGE is specified, moves the view down by a whole page. If PIXEL is specified, moves the view down by a single pixel.

: LEFT
:: Move the view left by about 1/8 of the window height. If PAGE is specified, moves the view left by a whole page. If PIXEL is specified, moves the view left by a single pixel.

: RIGHT
:: Move the view right by about 1/8 of the window height. If PAGE is specified, moves the view right by a whole page. If PIXEL is specified, moves the view right by a single pixel.

; Errors:
: 10 - If the named window view cannot be changed; this can also happen if you specified "ACTIVE" as the window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window view changed that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

: To find out about a window`s current view position, use the GETATTR command and query the window`s WINDOW.VIEW.LEFT and WINDOW.VIEW.TOP attributes.

; Example:
: <syntaxhighlight>
/* Change the root window view; move it up by a whole page. */
ADDRESS workbench

VIEW root PAGE UP
</syntaxhighlight>

= WINDOW command =

; Purpose:
: This command will change, open, close or snapshot windows.

; Format:
: WINDOW [WINDOWS] <Window name> .. <Window name> [OPEN|CLOSE] [SNAPSHOT] [ACTIVATE] [MIN|MAX] [FRONT|BACK] [CYCLE PREVIOUS|NEXT]

; Template:
: WINDOW WINDOWS/M/A,OPEN/S,CLOSE/S,SNAPSHOT/S,ACTIVATE/S,MIN/S,MAX/S, FRONT/S,BACK/S,CYCLE/K

; Parameters:
: WINDOWS
:: Names of the windows to operate on. This can be "ROOT" to for the Workbench root window (where volume icons and AppIcons live), "ACTIVE" for the currently active Workbench window or the fully qualified name of a drawer window.

: OPEN
:: Attempt to open the specified windows.

: CLOSE
:: Close the specified windows. Note that if a window is closed no further operations (such as SNAPSHOT, ACTIVATE, etc.) can be performed on it.

: SNAPSHOT
:: Snapshot the sizes and positions of the specified windows.

: ACTIVATE
:: Activate the specified windows. With multiple windows to activate, only one window will wind up as the active one. Commonly, this will be the last window in the list.

: MIN
:: Resize the windows to their minimum dimensions.

: MAX
:: Resize the windows to their maximum dimensions.

: FRONT
:: Move the windows into the foreground.

: BACK
:: Move the windows into the background.

: CYCLE
:: This command operates on the currently active drawer window. You can specify either "PREVIOUS", to activate the previous drawer window in the list, or "NEXT", to activate the next following drawer window in the list.

; Errors:
: 10 - If the named windows cannot be opened or operated on; this can also happen if you specified "ACTIVE" as a window name and none of the Workbench windows is currently active. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window operated on that is neither the root nor the active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Open the "Work:" drawer. */
ADDRESS workbench

WINDOW 'Work:' OPEN

/* Activate the root window. */
WINDOW root ACTIVATE
</syntaxhighlight>

= WINDOWTOBACK command =

; Purpose:
: This command will push a window into the background.

; Format:
: WINDOWTOBACK [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOBACK WINDOW

; Parameters:
: WINDOW
:: "ROOT" to push the the Workbench root window (where volume icons and AppIcons live) into to the background, "ACTIVE" to push the currently active Workbench window into the background or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window pushed into the background that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Push the root window into the background. */
ADDRESS workbench

WINDOWTOBACK root
</syntaxhighlight>

= WINDOWTOFRONT command =

; Purpose:
: This command will bring a window to the foreground.

; Format:
: WINDOWTOFRONT [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: WINDOWTOFRONT WINDOW

; Parameters:
: WINDOW
:: "ROOT" to bring the the Workbench root window (where volume icons and AppIcons live) to the foreground, "ACTIVE" to bring the currently active Workbench window to the foreground or the fully qualified name of a drawer window. Note that the drawer window must already be open.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Notes:
: If you choose to have a window brought to the foreground that is not the root window or the currently active window you must make sure that the window name is given as a fully qualified path name. For example "Work:" is a fully qualified name, and so is "SYS:Utilities". "Devs/Printers" would not be a fully qualified name. A fully qualified name always contains the name of an assignment, a volume or a device.

; Example:
: <syntaxhighlight>
/* Bring the root window to the foreground. */
ADDRESS workbench

WINDOWTOFRONT root
</syntaxhighlight>

= ZOOMWINDOW command =

; Purpose:
: This command will change a window to alternate position and dimensions.

; Format:
: ZOOMWINDOW [WINDOW] <ROOT|ACTIVE|Drawer name>

; Template:
: ZOOMWINDOW WINDOW

; Parameters:
: WINDOW
:: Name of the window to operate on. "ROOT" will use the Workbench root window (where volume icons and AppIcons live), "ACTIVE" will use the currently active Workbench window. Any other fully qualified path name will use the drawer window corresponding to the path.
:: If no WINDOW parameter is specified, this command will try to operate on the currently active Workbench window.

; Errors:
: 10 - If the named window cannot be found. The error code will be placed in the WORKBENCH.LASTERROR variable.

; Result:
: -

; Example:
: <syntaxhighlight>
/* Change the root window. */
ADDRESS workbench

ZOOMWINDOW root
</syntaxhighlight>

AmigaOS Manual: ARexx Glossary

2014-01-28T02:59:10Z

Tony Wyatt: Fixed typos

This glossary provides definitions of terms used in the ARexx manual.

; Address
: An identifying number assigned to every byte of information in a computer's memory and every sector on a disk.

; argument
: An additional piece of information included with an instruction or function. The argument determines the action to be taken.

; assignment clause
: A variable symbol (simple, stem or compound symbol) followed by an = operator. In an assignment clause, the tokens to the right of the = sign are evaluated and the result is assigned to the variable symbol.

; Boolean
: Having two possible states: 0 (false) or 1 (true).

; clause
: The smallest executable language unit.

; clip list
: A clipboard used for intertask communication. Name and value pairs can be added to the clip list with the SETCLIP() function.

; command clause
: An ARexx expression in which the result is issued as a command to an external application.

; command interface
: A message port through which ARexx issues commands to compatible applications.

; comment
: A group of characters enclosed in /*...*/ symbols. Each ARexx program starts with a comment.

; compound symbol
: A token made up of alphanumeric or ., !, ?, $, _ characters with one or more periods within the name. Compound symbols have the structure stem.n1.n2...nk.

; concatenation
: The process of linking together two strings.

; debugging
: Finding and fixing errors in a program.

; delimiter
: A character that marks the beginning and end of a string. ARexx delimiters are a single quote (') and a double quote (").

; expression
: A group of tokens to be evaluated. Expressions are made up of strings, symbols, operators, and parentheses.

; fixed symbol
: A token beginning with a digit or a period.

; function
: A group of statements that can be executed as a whole. Functions allow you to build complex programs from smaller modules.

; function hosts
: An external application that contains an ARexx port. The name of a function host is the name of the program's public message port.

; function libraries
: A collection of one or more functions organized as an Amiga shared library. A function library must contain a library name, a search priority, an entry point offset, and a version number.

; global environment
: The fixed components of an ARexx program, including the program source code, static data strings and argument strings.

; host address
: In an outside application, the host address is the name of the message port to which ARexx commands can be sent.

; instruction
: A clause beginning with a certain keyword that tells ARexx to perform an action.

; interprocess communication
: The exchange of information between applications.

; interrupts
: Internal flags in ARexx that allow a program to detect errors and retain control when the program would normally abort. Interrupts are controlled by the SIGNAL: instruction.

; iterating
: Repeating a section of a program.

; label
: A symbol token followed by a colon (:). Labels identify a particular location in the program.

; library list
: An internal list, maintained by ARexx, of all the currently available function libraries and function hosts. Applications can add or remove functions as needed.

; macro
: Another name for an ARexx program.

; marker
: A token that determines the beginning and end of a parse string.

; message port
: An interface in an Amiga application that allows the program to communicate with an ARexx program.

; null clause
: A blank line or a comment line.

; numeric precision
: The number of decimal places in an arithmetic result. As the number of decimal places decreases, the result becomes less precise.

; operators
: A character such as (+), (-), or (|) used in an arithmetic, concatenation, comparison, or logical operation.

; parsing
: Breaking a string into smaller units.

; return code
: The severity level of an error. This number (5, 10, or 20) is displayed when an error occurs in an ARexx program.

; RexxMast
: The program that acts as an interpreter for ARexx programs.

; simple symbol
: A token that does not begin with a digit or contain any periods.

; statement
: An assignment, instruction, or command clause.

; stem symbol
: A token that has one period at the end of its name. Stem symbols are used to initialize compound symbols.

; storage environment
: The variable components of an ARexx program, including the symbol table, numeric options, trace options and host address strings.

; string
: A group of characters beginning and ending with a delimiter (single or double quote). The value of a string is the string itself.

; symbol
: Any group of the alphanumeric characters a-z, A-Z, 0-9, period (.), exclamation point (!), question mark (?), dollar sign ($), or underscore (_).

; symbol table
: An internal table created by ARexx that stores the value strings that have been assigned to the variables in a program.

; target
: A symbol, usually a variable symbol, that is assigned a value during a parsing operation.

; template
: A group of tokens that specifies the variables used in a parsing operation. It also specifies the way in which the values will be determined.

; tokenization
: The process of breaking a statement into its individual tokens.

; tokens
: The smallest entities of the ARexx language.

; tracing
: Displaying the lines of an ARexx program as the program is executing. This allows you to determine exactly where any errors are occurring.

; variable
: A symbol that can be assigned a value.

AmigaOS Manual: ARexx Command Utilities

2014-01-28T02:47:59Z

Tony Wyatt: Fixed typos

ARexx provides a number of command utilities, located in the REXXC Directory, that provide various control functions. These are executable modules that can be run from the Shell and are relevant only when the ARexx resident process is active.

= HI =

<nowiki>HI</nowiki>

Sets the global halt flag, which causes all active ARexx programs to receive an external halt request. Each program will exit immediately unless its HALT interrupt has been enabled. The halt flag does not remain set, but is cleared automatically after all current programs have received the request.

= RX =

<nowiki>RX name [arguments]</nowiki>

Launches an ARexx program. If the specified name includes an explicit path, only that directory is searched for the program; otherwise, the current directory and REXX: are checked for a program with the given name. The optional argument string is passed to the program.

= RXSET =

<nowiki>RXSET [name [[=] value]]</nowiki>

Adds a (name,value) pair to the Clip List. Name strings are assumed to be in mixed case. If a pair with the same name already exists, its value is replaced with the current string. If a name without a value string is given, the entry is removed from the Clip List. If RXSET is invoked without arguments, it will list all (name, value) pairs in the Clip List.

= RXC =

<nowiki>RXC</nowiki>

Close the resident process. The "REXX" public port is withdrawn immediately, and the resident process exits as soon as the last ARexx program finishes. No new programs can be launched after a close request.

= TCC =

<nowiki>TCC</nowiki>

Closes the global tracing console as soon as all active programs are no longer using it. All read requests queued to the console must be satisfied before it can be closed.

= TCO =

<nowiki>TCO</nowiki>

Opens the global tracing console. The tracing output from all active programs is diverted automatically to the new console. The console window can be moved and resized by the user and can be closed with the TCC command.

= TE =

<nowiki>TE</nowiki>

Clears the global tracing flag, which forces the tracing mode to OFF for all active ARexx programs.

= TS =

<nowiki>TS</nowiki>

Starts interactive tracing by setting the external trace flag, which forces all active ARexx programs into interactive tracing mode. Programs will start producing trace output and will pause after the next statement. This command is useful for regaining control over programs caught in infinite loops or otherwise misbehaving. The trace flag remains set until cleared by the TE command, so subsequent program invocations will be executed in interactive tracing mode.

= WaitForPort =

<nowiki>WaitForPort [name of port]</nowiki>

WaitForPort waits 10 seconds for the specified port to appear. A return code of 0 indicates that the port was found. A return code of 5 indicates that the application is not currently running or that the port does not exist. Port names are case sensitive. For example:

WaitForPort ED_1
WaitForPort MyPort

AmigaOS Manual: ARexx Error Messages

2014-01-28T00:28:29Z

Tony Wyatt: More typos

When the ARexx interpreter detects an error in a program, it returns an error code to indicate the nature of the problem. Errors are normally handled by displaying the error code, the source line number where the error occurred and a brief message explaining the error condition. Unless the SYNTAX interrupt has been previously enabled (using the SIGNAL instruction), the program then terminates and control returns to the caller. Most syntax and execution errors can be trapped by the SYNTAX interrupt, allowing the user to retain and perform whatever special error processing is required. Certain errors are generated outside of the context of an ARexx program and therefore cannot be trapped by this mechanism. Refer to Chapter 6 for further information on error trapping and processing.

Each error code is associated with a severity level that is reported to the calling program as the primary result code. The values of these results codes are 5 (least serious), 10 (moderately serious), and 20 (very serious). The error code itself is returned as the secondary result. The subsequent propagation or reporting of these codes is dependent on the external (calling) program.

The following pages list all of the currently-defined error codes, along with the associated result code and message strings.

{| class="wikitable"
|+ Table A-1. Error Codes and Messages
! Error !! Result Code !! Message !! Explanation
|-
| 1 || 5 || Program not found || The named program could not be found or was not an ARexx program. ARexx program are expected to start with a comment (/*...*/). This error is detected by the external interface and cannot be trapped by the SYNTAX interrupt.
|-
| 2 || 10 || Execution halted || A Ctrl+C break or an external halt request was received and the program terminated. This error will be trapped if the HALT interrupt has been enabled.
|-
| 3 || 20 || Insufficient memory || The interpreter was unable to allocate enough memory for an operation. Since memory space is required for all parsing and execution operations, this error cannot usually be trapped by the SYNTAX interrupt.
|-
| 4 || 10 || Invalid character || A non-ASCII character was found in the program. Control codes and other non-ASCII characters may be used in a program by defining them as hex or binary strings. This is a scan-phase error and cannot be trapped by the SYNTAX interrupt.
|-
| 5 || 10 || Unmatched quote || A closing single or double quote was missing. Check that each string is properly delimited. This is a scan-phase error and cannot be trapped by the SYNTAX interrupt.
|-
| 6 || 10 || Unterminated comment || The closing */ of a comment was not found. Remember that comments may be nested, so each /* must be matched by a */. This is a scan-phase error and cannot be trapped by the SYNTAX interrupt.
|-
| 7 || 10 || Clause too long || A clause was too long for the internal buffer. The source line should be broken into smaller parts. This is a scan-phase error and cannot be trapped by the SYNTAX interrupt.
|-
| 8 || 10 || Invalid token || An unrecognized lexical token was found, or a clause could not be properly classified. This is a scan-phase error and cannot be trapped by the SYNTAX interrupt.
|-
| 9 || 10 || Symbol or string too long || An attempt was made to create a string longer than the maximum allowed.
|-
| 10 || 10 || Invalid message packet || An invalid action code was found in a message packet sent to the ARexx resident process. The packet was returned without being processed. This error is detected by the external interface and cannot be trapped by the SYNTAX interrupt.
|-
| 11 || 10 || Command string error || A command string could not be processed. This error is detected by the external interface and cannot be trapped by the SYNTAX interrupt.
|-
| 12 || 10 || Error return from function || An external function returned a non-zero error code. Check that the correct parameters were supplied to the function.
|-
| 13 || 10 || Host environment not found || The message port corresponding to a host address string could not be found. Check that the required external host is active.
|-
| 14 || 10 || Requested library not found || An attempt was made to open a function library included in the Library List, but the library could not be opened. Check that the correct name and version of the library were specified when the library was added to the resource list.
|-
| 15 || 10 || Function not found || A function was called that could not be found in any of the currently accessible libraries and could not be located as an external program. Check that the appropriate function libraries have been added to the Libraries List.
|-
| 16 || 10 || Function did not return a value || A function was called which failed to return a result string, but did not otherwise report an error. Check that the function was programmed correctly or invoke it using the CALL instruction.
|-
| 17 || 10 || Wrong number of arguments || A call was made to a function which expected a different number of arguments. This error will be generated if a built-in or external function is called with more arguments than can be accommodated in the message packet used for external communications.
|-
| 18 || 10 || Invalid argument to function || An inappropriate argument was supplied to a function or a required argument was missing. Check the parameter requirements specified for the function.
|-
| 19 || 10 || Invalid PROCEDURE || A PROCEDURE instruction was issued in an invalid context. Either no internal functions were active or a PROCEDURE had already been issued in the current storage environment.
|-
| 20 || 10 || Unexpected THEN or WHEN || A WHEN or THEN instruction was executed outside of a valid context. The WHEN instruction is valid only within a SELECT range, and THEN must be the next instruction following in IF or WHEN.
|-
| 21 || 10 || Unexpected ELSE or OTHERWISE || An ELSE or OTHERWISE was found outside of a valid context. The OTHERWISE instruction is valid only within a SELECT range. ELSE is valid only following the THEN branch of an IF range.
|-
| 22 || 10 || Unexpected BREAK, LEAVE or ITERATE || The BREAK instruction is valid only within a DO range or inside an INTERPRETed string. The LEAVE and ITERATE instructions are valid only within an iterative DO range.
|-
| 23 || 10 || Invalid statement in SELECT || An invalid statement was encountered within a SELECT range. Only WHEN, THEN and OTHERWISE statements are valid within a SELECT range, except for the conditional statements following THEN or OTHERWISE clauses.
|-
| 24 || 10 || Missing or multiple THEN || An expected THEN clause was not found or another THEN was found after one had already been executed.
|-
| 25 || 10 || Missing OTHERWISE || None of the WHEN clauses in a SELECT succeeded, but no OTHERWISE clause was supplied.
|-
| 26 || 10 || Missing or unexpected END || The program source ended before an END was found for a DO or SELECT instruction, or an END was encountered outside a DO or SELECT range.
|-
| 27 || 10 || Symbol mismatch || The symbol specified on an END, ITERATE or LEAVE instruction did not match the index variable for the DO range. Check that the active loops have been nested properly.
|-
| 28 || 10 || Invalid DO syntax || An invalid DO instruction was executed. An initializer expression must be given if a TO or BY expression is specified. A FOR expression must yield a non-negative integer result.
|-
| 29 || 10 || Incomplete IF or SELECT || An IF or SELECT range ended before all of the required statements were found. Check whether the conditional statement following a THEN, ELSE or OTHERWISE clause was omitted.
|-
| 30 || 10 || Label not found || A label specified by a SIGNAL instruction or implicitly referenced by an enabled interrupt could not be found in the program source. Labels defined dynamically by an INTERPRET instruction or by interactive input are not included in the search.
|-
| 31 || 10 || Symbol expected || A non-symbol token was found where only a symbol token is valid. The DROP, END, LEAVE, ITERATE and UPPER instructions may only be followed by a symbol token. This message will also be issued if a required symbol is missing.
|-
| 32 || 10 || Symbol or string expected || An invalid token was found in a context where only a symbol or string is valid.
|-
| 33 || 10 || Invalid keyword || A symbol token in an instruction clause was identified as a keyword, but was invalid in the specific context.
|-
| 34 || 10 || Required keyword missing || An instruction clause required a specific keyword token to be present, but it was not supplied. This message will be issued if a SIGNAL ON instruction is not followed by one of the interrupt keywords (e.g., SYNTAX).
|-
| 35 || 10 || Extraneous characters || A seemingly valid statement was executed, but extra characters were found at the end of the clause.
|-
| 36 || 10 || Keyword conflict || Two mutually exclusive keywords were included in an instruction clause, or a keyword was included twice in the same instruction.
|-
| 37 || 10 || Invalid template || The template provided with an ARG, PARSE or PULL instruction was not properly constructed.
|-
| 38 || 10 || Invalid TRACE request || The alphabetic keyword supplied with a TRACE instruction or as the argument to the TRACE() built-in function was not valid.
|-
| 39 || 10 || Uninitialized variable || An attempt was made to use an uninitialized variable while the NOVALUE interrupt was enabled.
|-
| 40 || 10 || Invalid variable || An attempt was made to assign a value to a fixed symbol.
|-
| 41 || 10 || Invalid expression || An error was detected during the evaluation of an expression. Check that each operator has the correct number of operands and that no extraneous tokens appear in the expression. This error will be detected only in expressions that are actually evaluated. No checking is performed on expressions in clauses that are being skipped.
|-
| 42 || 10 || Unbalanced parentheses || An expression was found with an unequal number of opening and closing parentheses.
|-
| 43 || 10 || Nesting limit exceeded || The number of subexpressions in an expression was greater than the maximum allowed. Simplify the expression by breaking it into two or more intermediate expressions.
|-
| 44 || 10 || Invalid expression result || The result of an expression was not valid within its context. This message will be issued if an increment or limit expression in a DO instruction yields a non-numeric result.
|-
| 45 || 10 || Expression required || An expression was omitted in a context where one is required. For example, the SIGNAL instruction, if not followed by the keywords ON or OFF, must be followed by an expression.
|-
| 46 || 10 || Boolean value not 0 or 1 || An expression result was expected to yield a Boolean result, but evaluated to something other than 0 or 1.
|-
| 47 || 10 || Arithmetic conversion error || A non-numeric operand was used in an operation requiring numeric operands. This message will also be generated by an invalid hex or binary string.
|-
| 48 || 10 || Invalid operand || An operand was not valid for the intended operation. This message will be generated if an attempt is made to divide by 0 or if a fractional exponent is used in an exponentiation operation.
|}

AmigaOS Manual: ARexx Error Messages

2014-01-28T00:25:56Z

Tony Wyatt: Fixed typos

When the ARexx interpreter detects an error in a program, it returns an error code to indicate the nature of the problem. Errors are normally handled by displaying the error code, the source line number where the error occurred and a brief message explaining the error condition. Unless the SYNTAX interrupt has been previously enabled (using the SIGNAL instruction), the program then terminates and control returns to the caller. Most syntax and execution errors can be trapped by the SYNTAX interrupt, allowing the user to retain and perform whatever special error processing is required. Certain errors are generated outside of the context of an ARexx program and therefore cannot be trapped by this mechanism. Refer to Chapter 6 for further information on error trapping and processing.

Each error code is associated with a severity level that is reported to the calling program as the primary result code. The values of these results codes are 5 (least serious), 10 (moderately serious), and 20 (very serious). The error code itself is returned as the secondary result. The subsequent propagation or reporting of these codes is dependent on the external (calling) program.

The following pages list all of the currently-defined error codes, along with the associated result code and message strings.

{| class="wikitable"
|+ Table A-1. Error Codes and Messages
! Error !! Result Code !! Message !! Explanation
|-
| 1 || 5 || Program not found || The named program could not be found or was not an ARexx program. ARexx program are expected to start with a comment (/*...*/). This error is detected by the external interface and cannot be trapped by the SYNTAX interrupt.
|-
| 2 || 10 || Execution halted || A Ctrl+C break or an external halt request was received and the program terminated. This error will be trapped if the HALT interrupt has been enabled.
|-
| 3 || 20 || Insufficient memory || The interpreter was unable to allocate enough memory for an operation. Since memory space is required for all parsing and execution operations, this error cannot usually be trapped by the SYNTAX interrupt.
|-
| 4 || 10 || Invalid character || A non-ASCII character was found in the program. Control codes and other non-ASCII characters may be used in a program by defining them as hex or binary strings. This is a scan-phase error and cannot be trapped by the SYNTAX interrupt.
|-
| 5 || 10 || Unmatched quote || A closing single or double quote was missing. Check that each string is properly delimited. This is a scan-phase error and cannot be trapped by the SYNTAX interrupt.
|-
| 6 || 10 || Unterminated comment || The closing */ of a comment was not found. Remember that comments may be nested, so each /* must be matched by a */. This is a scan-phase error and cannot be trapped by the SYNTAX interrupt.
|-
| 7 || 10 || Clause too long || A clause was too long for the internal buffer. The source line should be broken into smaller parts. This is a scan-phase error and cannot be trapped by the SYNTAX interrupt.
|-
| 8 || 10 || Invalid token || An unrecognized lexical token was found, or a clause could not be properly classified. This is a scan-phase error and cannot be trapped by the SYNTAX interrupt.
|-
| 9 || 10 || Symbol or string too long || An attempt was made to create a string longer than the maximum allowed.
|-
| 10 || 10 || Invalid message packet || An invalid action code was found in a message packet sent to the ARexx resident process. The packet was returned without being processed. This error is detected by the external interface and cannot be trapped by the SYNTAX interrupt.
|-
| 11 || 10 || Command string error || A command string could not be processed. This error is detected by the external interface and cannot be trapped by the SYNTAX interrupt.
|-
| 12 || 10 || Error return from function || An external function returned a non-zero error code. Check that the correct parameters were supplied to the function.
|-
| 13 || 10 || Host environment not found || The message port corresponding to a host address string could not be found. Check that the required external host is active.
|-
| 14 || 10 || Requested library not found || An attempt was made to open a function library included in the Library List, but the library could not be opened. Check that the correct name and version of the library were specified when the library was added to the resource list.
|-
| 15 || 10 || Function not found || A function was called that could not be found in any of the currently accessible libraries and could not be located as an external program. Check that the appropriate function libraries have been added to the Libraries List.
|-
| 16 || 10 || Function did not return a value || A function was called which failed to return a result string, but did not otherwise report an error. Check that the function was programmed correctly or invoke it using the CALL instruction.
|-
| 17 || 10 || Wrong number of arguments || A call was made to a function which expected a different number of arguments. This error will be generated if a built-in or external function is called with more arguments than can be accommodated in the message packet used for external communications.
|-
| 18 || 10 || Invalid argument to function || An inappropriate argument was supplied to a function or a required argument was missing. Check the parameter requirements specified for the function.
|-
| 19 || 10 || Invalid PROCEDURE || A PROCEDURE instruction was issued in an invalid context. Either no internal functions were active or a PROCEDURE had already been issued in the current storage environment.
|-
| 20 || 10 || Unexpected THEN or WHEN || A WHEN or THEN instruction was executed outside of a valid context. The WHEN instruction is valid only within a SELECT range, and THEN must be the next instruction following in IF or WHEN.
|-
| 21 || 10 || Unexpected ELSE or OTHERWISE || An ELSE or OTHERWISE was found outside of a valid context. The OTHERWISE instruction is valid only within a SELECT range. ELSE is valid only following the THEN branch of an IF range.
|-
| 22 || 10 || Unexpected BREAK, LEAVE or ITERATE || The BREAK instruction is valid only within a DO range or inside an INTERPRETed string. The LEAVE and ITERATE instructions are valid only within an iterative DO range.
|-
| 23 || 10 || Invalid statement in SELECT || An invalid statement was encountered within a SELECT range. Only WHEN, THEN and OTHERWISE statements are valid within a SELECT range, except for the conditional statements following THEN or OTHERWISE clauses.
|-
| 24 || 10 || Missing or multiple THEN || An expected THEN clause was not found or another THEN was found after one had already been executed.
|-
| 25 || 10 || Missing OTHERWISE || None of the WHEN clauses in a SELECT succeeded, but no OTHERWISE clause was supplied.
|-
| 26 || 10 || Missing or unexpected END || The program source ended before an END was found for a DO or SELECT instruction, or an END was encountered outside a DO or SELECT range.
|-
| 27 || 10 || Symbol mismatch || The symbol specified on an END, ITERATE or LEAVE instruction did not match the index variable for the DO range. Check that the active loops have been nested properly.
|-
| 28 || 10 || Invalid DO syntax || An invalid DO instruction was executed. An initializer expression must be given if a TO or BY expression is specified. A FOR expression must yield a non-negative integer result.
|-
| 29 || 10 || Incomplete IF or SELECT || An IF or SELECT range ended before all of the required statements were found. Check whether the conditional statement following a THEN, ELSE or OTHERWISE clause was omitted.
|-
| 30 || 10 || Label not found || A label specified by a SIGNAL instruction or implicitly referenced by a enabled interrupt could not be found in the program source. Labels defined dynamically by an INTERPRET instruction or by interactive input are not included in the search.
|-
| 31 || 10 || Symbol expected || A non-symbol token was found where only a symbol token is valid. The DROP, END, LEAVE, ITERATE and UPPER instructions may only be followed by a symbol token. This message will also be issued if a required symbol is missing.
|-
| 32 || 10 || Symbol or string expected || An invalid token was found in a context where only a symbol or string is valid.
|-
| 33 || 10 || Invalid keyword || A symbol token in an instruction clause was identified as a keyword, but was invalid in the specific context.
|-
| 34 || 10 || Required keyword missing || An instruction clause required a specific keyword token to be present, but it was not supplied. This message will be issued if a SIGNAL ON instruction is not followed by one of the interrupt keywords (e.g., SYNTAX).
|-
| 35 || 10 || Extraneous characters || A seemingly valid statement was executed, but extra characters were found at the end of the clause.
|-
| 36 || 10 || Keyword conflict || Two mutually exclusive keywords were included in an instruction clause, or a keyword was included twice in the same instruction.
|-
| 37 || 10 || Invalid template || The template provided with an ARG, PARSE or PULL instruction was not properly constructed.
|-
| 38 || 10 || Invalid TRACE request || The alphabetic keyword supplied with a TRACE instruction or as the argument to the TRACE() built-in function was not valid.
|-
| 39 || 10 || Uninitialized variable || An attempt was made to use an uninitialized variable while the NOVALUE interrupt was enabled.
|-
| 40 || 10 || Invalid variable || An attempt was made to assign a value to a fixed symbol.
|-
| 41 || 10 || Invalid expression || An error was detected during the evaluation of an expression. Check that each operator has the correct number of operands and that no extraneous tokens appear in the expression. This error will be detected only in expressions that are actually evaluated. No checking is performed on expressions in clauses that are being skipped.
|-
| 42 || 10 || Unbalanced parentheses || An expression was found with an unequal number of opening and closing parentheses.
|-
| 43 || 10 || Nesting limit exceeded || The number of subexpressions in an expression was greater than the maximum allowed. Simplify the expression by breaking it into two or more intermediate expressions.
|-
| 44 || 10 || Invalid expression result || The result of an expression was not valid within its context. This message will be issued if an increment or limit expression in a DO instruction yields a non-numeric result.
|-
| 45 || 10 || Expression required || An expression was omitted in a context where one is required. For example, the SIGNAL instruction, if not followed by the keywords ON or OFF, must be followed by an expression.
|-
| 46 || 10 || Boolean value not 0 or 1 || An expression result was expected to yield a Boolean result, but evaluated to something other than 0 or 1.
|-
| 47 || 10 || Arithmetic conversion error || A non-numeric operand was used in an operation requiring numeric operands. This message will also be generated by an invalid hex or binary string.
|-
| 48 || 10 || Invalid operand || An operand was not valid for the intended operation. This message will be generated if an attempt is made to divide by 0 or if a fractional exponent is used in an exponentiation operation.
|}

AmigaOS Manual: ARexx Parsing

2014-01-28T00:01:13Z

Tony Wyatt: Fixed typos

Parsing extracts substrings from a string and assigns them to variables. Parsing is performed using the PARSE instruction or its variants ARG and PULL. The operation input is called the parse string and comes from several sources, including argument strings, expressions, or the console.

String-manipulation functions like SUBSTR() and INDEX() may be used for parsing, but the PARSE instruction statement is more efficient, especially if extracting many fields from a string.

= Templates =

Parsing is controlled by a template, a group of tokens that specifies both the variables to be given values and the way to determine the value strings. The way tokens are arranged in the template determines whether the token is one of two basic template objects: a marker or a target.

; Marker
: Determines the starting and ending position in the parse string or the scan position.

; Target
: A symbol assigned a value by the parsing operation. That value is the substring determined by the marker positions.

== Markers ==

There are three types of marker objects:

; Absolute markers
: Actual index position in the parse string.

; Relative markers
: A positive or negative offset from the current position.

; Pattern markers
: Matches the pattern against the parse string beginning at the current scan position.

== Targets ==

Targets, like markers, can affect the scan position if value strings are being extracted by tokenization. Parsing by tokenization extracts words (tokens) from the parse string and is used whenever a target is followed immediately by another target. During tokenization the current scan position is advanced past any blanks to the start of the next word. The ending index is the position just past the end of the word and the value string has neither leading nor trailing blanks.

Targets are specified by variable symbols. The place holder, denoted by a period (.), is a special type of target and behaves like a normal target except that it does not have an assigned value.

=== Template Objects ===

Each template object is specified by one or more tokens:

; Symbols
: A symbol may specify a target or a marker. It's a marker if it follows an operator (+, - or =) and the symbol value is used as an absolute or relative position. Symbols enclosed in parentheses specify pattern markers, and the symbol value is used as the pattern string. It specifies a target if neither of the preceding cases applies and the symbol is variable. Fixed symbols always specify absolute markers and must be whole numbers. The only exception is the place holder (.) target.

; Strings
: A string always represents a pattern marker.

; Parentheses
: A symbol enclosed in parentheses is a pattern marker and the value of the symbol is used as the pattern string. While the symbol may be either fixed or variable, it will usually be a variable. A fixed pattern could be given more simply as a string.

; Operators
: The three operators (+, - and =) are valid within a template and must be followed by a fixed or variable symbol. The value of the symbol is used as a marker and must represent a whole number. The "+" and "-" operators signify a relative marker, whose value is negated by the "-" operator. The "=" operator indicates an absolute marker and is optional if the marker is defined by a fixed symbol.

; Commas
: The comma (,) marks the end of a template. It is also used as a separator when multiple templates are provided with an instruction. The interpreter obtains a new parse string before processing each succeeding template. For some source options, the new string will be identical to the previous one. The ARG, EXTERNAL and PULL options will generally supply a different string, as will the VAR option if the variable has been modified.

The ARexx interface command parser has been generalized to recognize double-delimiter sequences within a (quoted) string file. The quoting convention is convenient for short programs, but it is easy to run out of quoting levels in longer programs. Single and double-quotes within a REXX program are equivalent, but the external environment may make a distinction.

AmigaDOS uses double-quotes. Strings entered from a Shell must begin with a double-quote, especially if you wish to include semicolons. For example:

<nowiki>
RX "SAY 'It''s possible, indeed; you ain''t seen nothin'' yet!' "
-> It's possible, indeed; you ain't seen nothin' yet!

RX "SAY '""Hello!""'"-> "Hello!"
</nowiki>

= The Scanning Process =

Scan positions are expressed as an index in the parse string and can range from 1 (the start of the string) to the length of the string plus 1 (the end).

The substring specified by two scan indices includes the characters from the starting position up to, but not including, the ending position. For example, the indices 1 and 10 specify characters 1-9 in the parse string. If the second scan index is less than or equal to the first, the remainder of the parse string is used as the substring. This means that a template specification like:

<syntaxhighlight>
PARSE ARG 1 all 1 first second
</syntaxhighlight>

will assign the entire parse string to the variable ALL. If the current scan index is already at the end of the parse string, the remainder is the null string.

When a pattern marker is matched against the parse string, the marker position is the index of the first character of the matched pattern or the end of the string if no match was found. The pattern is removed from the string whenever a match is found. This is the only operation that modifies the parse string during the parsing process.

Templates are scanned from left to right with the initial scan index set to 1. The scan position is updated each time a marker object is encountered, according to the type and value of the marker.

Whenever a target object is found, the assigned value is determined by examining the next template object. If the next object is another target, the value string is determined by tokenizing the parse string. Otherwise, the current scan position is used as the start of the value string and the position specified by the following marker is used as the end point.

The scan continues until all of the objects in the template have been used. Every target will be assigned a value. Once the parse string has been exhausted, the null string is assigned to any remaining targets.

= Parsing Examples =

== Parsing by Tokenization ==

Computer programs frequently split a string into its component words or tokens. This is accomplished with a template consisting entirely of variables (targets).

<syntaxhighlight>
/*Assume "hammer 1 each $600.00" was entered*/
PULL item qty units cost .
</syntaxhighlight>

In this example the input line from the PULL instruction is split into words and assigned to the variables in the template. The variable item receives the value "hammer", qty is set to "1", units is set to "each" and cost gets the value "$600.00". The final place holder (.) is given a null value, since there are only four words in the input. However, it forces the preceding variable cost to be given a tokenized value. If the place holder were omitted, the remainder of the parse string would be assigned to cost, which would then have a leading blank.

<syntaxhighlight>
answer = "Only Amiga makes it possible."
DO forever
PARSE VAR answer first answer
/*Place first word into 'first' and the rest into 'answer'.*/
IF first =='' THEN LEAVE
/*Stop if there are no more words*/
SAY answer
END
</syntaxhighlight>

The first word of a string is removed and the remainder is placed back in the string. The process continues until no more words are extracted. The output is:

Amiga makes it possible.
makes it possible.
it possible.
possible.

== Parsing by Pattern ==

Pattern markers extract the desired fields. The "pattern" in this case is very simple - a single character - but could be an arbitrary string of any length. This form of parsing is useful whenever delimiter characters are present in the parse string.

<syntaxhighlight>
/*Assume an argument string "12, 35.5,1" */
ARG hours ',' rate ',' withhold
</syntaxhighlight>

The pattern is actually removed from the parse string when a match is found. If the parse string is scanned again from the beginning, the length and structure of the string may be different than at the start of the parsing process. The original source of the string, however, is never modified.

== Parsing by Positional Markers ==

Parsing with positional markers is used whenever the files of interest are known to be in certain positions in a string.

<syntaxhighlight>
/* Records look like: */
/* Start: 1-5 */
/* Length: 6-10 */
/* Name: @ (start,length)*/
PARSE value record with 1 start +5 length +5 =start name +length
</syntaxhighlight>

The records being processed contain a variable length field. The starting position and length of the field are given in the first part of the record with a variable positional marker used to extract the desired field.

The "=start" sequence is an absolute marker whose value is the position placed in the variable start earlier in the scan. The "+length" sequence supplies the effective length of the field.

== Multiple Templates ==

More than one template can be specified with an instruction by separating the templates with a comma. The ARG instruction (or PARSE UPPER ARG) accesses the argument strings provided when the program was called. Each template accesses the succeeding argument string. For example:

<syntaxhighlight>
/*Assume arguments are ('one two',12,sort)*/
ARG first second,amount,action,option
</syntaxhighlight>

The first template consists of the variables first and second, which are set to the values "one" and "two". In the next two templates, amount gets the value "12" and action is set to "SORT". The last template consists of the variable "option", which is set to the null string, since only three arguments were available.

When multiple templates are used with the EXTERNAL or PULL source options, each additional template requests an additional line of input from the user:

<syntaxhighlight>
/*Read last, first, and middle names and ssn*/
PULL last ',' first middle,ssn
</syntaxhighlight>

Two lines of input are read. The first input line is expected to have three words which are assigned to the variables "last", "first", and "middle": The first variable is followed by a comma. The entire second input line is assigned to the variable "ssn".

Multiple templates can be useful even with a source option that returns the identical parse string. If the first template included pattern markers that altered the parse string, the subsequent templates could still access the original string. Subsequent parse strings obtained from the VALUE source do not cause the expression to be re-evaluated, but only retrieve the prior result.

AmigaOS Manual: ARexx Debugging

2014-01-27T23:39:26Z

Tony Wyatt: Typos

ARexx provides tracing and source-level debugging facilities. Tracing displays selected statements in a program as the program executes. When a clause is traced, its line number, source text, and related information are displayed on the console.

The internal interrupt system enables an ARexx program to detect certain synchronous or asynchronous events and to take special actions when they occur. Events such as a syntax error or an external halt request that would normally cause the program to exit can instead be trapped so that corrective actions can be taken.

= Tracing =

The tracing action selects which source clauses will be traced and has two modifier flags that control command inhibition and interactive tracing. Trace options can be shortened to one letter. The Trace options are:

; ALL
: All clauses are traced.

; BACKGROUND
: No tracing is performed and the program cannot be forced into interactive tracing.

; COMMANDS
: All command clauses are traced before being sent to the external host. Non-zero return codes are displayed on the console.

; ERRORS
: Commands that generate a non-zero return code are traced after the clause is executed.

; INTERMEDIATES
: All clauses are traced and intermediate results are displayed during expression evaluation. These include the values retrieved for variables, expanded compound names, and the results of function calls.

; LABELS
: All label clauses are traced as they are executed. A label will be displayed each time a transfer of control takes place

; NORMAL (Default)
: Command clauses with return codes that exceed the current error failure level are traced after execution and an error message is displayed.

; OFF
: Tracing is turned off.

; RESULTS
: All clauses are traced before execution and the final result of each expression is displayed. Values assigned to variables by ARG, PARSE or PULL instructions are also displayed. This option is recommended for general-purpose testing.

; SCAN
: This is a special option that traces all clauses and checks for errors, but suppresses the actual execution of the statements. If is helpful as a preliminary screening step for a newly-created program.

The tracing mode can be set using either the TRACE instruction or the TRACE() built-in function. Tracing can be selectively disabled from within a program to skip previously tested parts of a program.

Each trace line displayed on the console is indented to show the effective control (nesting) level at that clause and is identified by a special three-character code, as shown in Table 6-1. The source for each clause is preceded by its line number in the program.

Expression results or intermediates are enclosed in double quotes so that leading and trailing blanks will be apparent.

{| class="wikitable"
|+ Table 6-1. Special Three Character Codes
! Code !! Displayed Values
|-
| +++ || Command or syntax error
|-
| >C> || Expanded compound name
|-
| >F> || Result of a function call
|-
| >L> || Label clause
|-
| >O> || Result of a dyadic operation
|-
| >P> || Result of a prefix operation
|-
| >U> || Uninitialized variable
|-
| >V> || Value of a variable
|-
| >>> || Expression or template result
|-
| >.> || "Place holder" token value
|}

== Tracing Output ==

The tracing output from a program is always directed to one of two logical streams. The interpreter first checks for a stream named STDERR and directs the output there if the stream exists.

Otherwise, the trace output goes to the standard output stream STDOUT and will be interleaved with the normal console output of the program. The STDERR and STDOUT streams can be opened and closed under program control, so the programmer has complete control over the destination of tracing output.

In some cases a program may not have a predefined output stream. For example, a program invoked from a host application that did not provide input and output streams would not have an output console. To provide a tracing facility for such programs, the resident process can open a special global tracing console for use by any active program. When this console opens, the interpreter automatically opens a stream named STDERR for each ARexx program in which STDERR is not currently defined. The program then diverts its tracing output to the new stream.

A global tracing console can be opened using the TCO command utility. ARexx programs will automatically divert their tracing output to the new window, which is opened as a standard AmigaDOS console. The user can move it and resize it as required.

The tracing console also serves as the input stream for programs during interactive tracing. When a program pauses for tracing input, the input must be entered at the trace console. Any number of programs may use the tracing console simultaneously, although it is recommended that only one program at a time be traced.

The global console can be closed using the TCC command. The closing is delayed until all read requests to the console have been satisfied. Only when all of the active programs indicate that they are no longer using the console will it actually be closed.

== Command Inhibition ==

ARexx provides a tracing mode called command inhibition that suppresses host commands. In this mode command clauses are evaluated in the normal manner, but the command is not actually sent to the external host, and the return code is set to zero. This provides a way to test programs that issue potentially destructive commands, such as erasing files or formatting disks. Command inhibition does not apply to command clauses that are entered interactively. These commands are always performed, but the value of the special variable RC is left unchanged.

Command inhibition may be used in conjunction with any trace option. It is controlled by the "!" character, which may appear by itself or may precede any of the alphabetic options in a TRACE instruction. Each occurrence of the "!" character "toggles" the inhibition mode currently in effect. Command inhibition is cleared when tracing is set to OFF.

== Interactive Tracing ==

Interactive tracing is a debugging facility that allows the user to enter source statements while a program is executing. These statements may be used to examine or modify variable values, issue commands, or otherwise interact with the program. Any valid language statements can be entered interactively, with the same rules and restrictions that apply to the INTERPRET instruction. In particular, compound statements such as DO and SELECT must be complete within the entered line.

Interactive tracing can be used with any of the trace options. While in interactive tracing mode, the interpreter pauses after each traced clause and prompts for input with the code "+++". At each pause, three types of user responses are possible:

* If a null line is entered, the program continues to the next pause point.
* If a "=" character is entered, the preceding clause is executed again.
* Any other input is treated as a debugging statement and is scanned and executed.

The interpreter pauses after traceable clauses. Tracing options determine the location of the pauses. The interpreter does not pause after the instructions CALL, DO, ELSE, IF, THEN, and OTHERWISE. When any clause generates an execution error, the interpreter exits the program.

Interactive tracing is controlled by the "?" character, either by itself or in combination with an alphabetic trace option. Any number of "?" characters may precede an option. Each occurrence toggles the mode currently in effect. For example, if the current trace option was NORMAL, "TRACE ?R" would set the option to RESULTS and select interactive tracing mode. A subsequent "TRACE ?" would turn off interactive tracing.

=== Error Processing ===

The ARexx interpreter provides error processing during debugging. Errors found during interactive debugging are reported, but do not terminate the program. This special processing only applies to statements entered interactively.

ARexx also disables the internal interrupt flags during interactive debugging. This prevents an accidental transfer of control due to an error or uninitialized variable. However, if a "SIGNAL label" instruction is entered, the transfer will take place and any remaining interactive input will be abandoned. The SIGNAL instruction can still be used to alter the interrupt flags, and the new setting will take effect when the interpreter returns to normal processing.

Each ARexx task initializes its command failure level to the client's failure level (usually 10) to suppress printing of nuisance command errors. The failure level can be changed using OPTIONS FAILAT. Command errors (RC > 0) and failure (RC >= FAILAT) can be separately trapped using SIGNAL ON ERROR and SIGNAL ON FAILURE.

=== The External Tracing Flag ===

ARexx has an external tracing flag used to force programs into interactive tracing mode. When this tracing flag is set, using the TS command utility, any program not already in interactive tracing mode will enter it immediately. The internal trace option is set to RESULTS unless it is currently set to INTERMEDIATES or SCAN, in which case it remains unchanged. Programs invoked while the external tracing flags is set will begin executing in interactive tracing mode.

The external tracing flag provides a way to regain control over looping or unresponsive programs. Once a program enters interactive tracing mode, the user can step through the program statements and diagnose the problem. External tracing is a global flag, so all currently-active programs are affected by it. The tracing flag remains set until it is cleared using the TE command utility. Each program maintains an internal copy of the last state of the tracing flag and sets its tracing option to OFF when it observes that the tracing flag has been cleared. Programs in BACKGROUND tracing mode do not respond to the external tracing flag.

= Interrupts =

ARexx maintains an internal interrupt system used to detect and trap certain error conditions. When an interrupt is enabled and its corresponding condition arises, a transfer of control to the label specific to that interrupt occurs. This allows a program to retain control in circumstances that might otherwise cause the program to terminate. The interrupt conditions can be caused by either synchronous events, like a syntax error, or asynchronous events, like a Ctrl+C break request.

{{Note|These internal interrupts are completely separate from the hardware interrupt system managed by the EXEC operating system.}}

The name assigned to each interrupt is actually the label to which control will be transferred. Thus, a SYNTAX interrupt will transfer control to the label "SYNTAX:". Interrupts can be enabled or disabled using the SIGNAL instruction. For example, the instruction "SIGNAL ON SYNTAX" would enable the SYNTAX interrupt.

The interrupts supported by ARexx are:

; BREAK_C
: This traps (detects and treats as a signal and not as normal output) a Ctrl+C break request generated by AmigaDOS. If the interrupt is not enabled, the program terminates immediately with the error message "Execution halted" and returns with the error code set to 2.

; BREAK_D
: This traps a Ctrl+D break request issued by AmigaDOS. The break request is ignored if the interrupt is not enabled.

; BREAK_E
: This traps a Ctrl+E break request issued by AmigaDOS. The break request is ignored if the interrupt is not enabled.

; BREAK_F
: This traps a Ctrl+F break request issued by AmigaDOS. The break request is ignored if the interrupt is not enabled.

; ERROR
: This interrupt is generated by any host command that returns a non-zero code.

; HALT
: An external halt request is trapped if this interrupt is enabled. Otherwise, the program terminates immediately with the error message "Execution halted".

; IOERR
: Errors detected by the I/O system are trapped if this interrupt is enabled.

; NOVALUE
: An interrupt occurs if an uninitialized variable is used while this condition is enabled. The usage could be within an expression, in the UPPER instruction, or with the VALUE() built-in function.

; SYNTAX
: A syntax or execution error is generated by this interrupt. Not all such errors can be trapped. Certain errors occur before a program is executed and those detected by the ARexx external interface cannot be trapped by the SYNTAX interrupt.

When an interrupt forces a transfer of control, all of the currently active control ranges are dismantled and the interrupt that caused the transfer is disabled. This disabling prevents a possible recursive interrupt loop. Only the control structures in the current environment are affected, so an interrupt generated within a function will not affect the caller's environment.

Two special variables are affected when an interrupt occurs:

; SIGL
: Always set to the current line number before the transfer of control takes place. This allows the determination of which source line is executed.

; RC
: Set to the error code that caused the condition. For ERROR interrupts, this value will be a command return code and can usually be interpreted as an error severity level. The value for SYNTAX interrupts is always an ARexx error code.

Interrupts are useful for error-recovery actions. This involves informing external programs that an error occurred or reporting further diagnostics to isolate the problem. Program 15 issues a "message" command to an external host called "MyEdit" whenever a syntax error is detected.

== Program 15. Interrupt.rexx ==

<syntaxhighlight>
/*A macro program for 'MyEdit'*/
SIGNAL ON SYNTAX /*Enable interrupt*/
(normal processing)
EXIT
SYNTAX: /*Syntax error detected*/
ADDRESS 'MyEdit'
'message' 'error' RC errortext (RC)
EXIT 10
</syntaxhighlight>

AmigaOS Manual: ARexx Instructions

2014-01-27T22:36:46Z

Tony Wyatt: More typos

An instruction clause begins with the name of a particular instruction and tells ARexx to perform a certain action. This chapter provides an alphabetical list of the instructions available in ARexx.

Each instruction keyword may be followed by one or more subkeywords, expressions, or other instruction-specific information. Instruction keywords and subkeywords are recognized only in this specific context. This allows the same keywords to be used in a different context as variables or function names. An instruction keyword cannot be followed by a colon (:) or an equals (=) operator.

= Syntax =

The syntax for each instruction is shown to the right of the keyword heading. The conventions used in the syntax are shown in Table 4-1:

{| class="wikitable"
|+ Table 4-1. Syntax Conventions
! Convention !! Definition
|-
| KEYWORD || All keywords and subkeywords are shown in upper case letters
|-
| <nowiki>|</nowiki> (vertical bar) || Alternative selections are separated by a vertical bar
|-
| { } (braces) || Required alternatives are enclosed by braces
|-
| [ ] (brackets) || Optional instruction parts are enclosed in brackets
|}

{{Note|The syntax conventions do not apply to the specifications following the keyword heading. They only apply to the syntax shown to the right of the instruction keyword.}}

For example, the format for the CALL instruction is:

CALL {symbol | string} [expression] [,expression,...]

You must supply a symbol or a string as an argument. The vertical bar identifies the alternative selections, and the braces indicate that the use of an argument is required. The specification of an expression is optional, as indicated by the brackets.

Examples are given at the end of the instruction specification. Explanations or evaluations of the examples are shown as ARexx comments /*...*/.

= Alphabetical Reference =

This section provides an alphabetical list of ARexx's built-in instructions. The syntax of each instruction is shown to the right of the instruction keyword.

== ADDRESS ==

<nowiki>ADDRESS [[symbol | string] | [VALUE][expressions]] </nowiki>

This instruction specifies a host address for commands issued by the interpreter. A host address is the name of an application's message port to which ARexx commands are sent. ARexx maintains two host addresses: a current and a previous value. Whenever a new host address is supplied, the previous address is lost and the current address becomes the previous one. These host addresses are part of a program's storage environment and are preserved across internal function calls. The current address can be retrieved with the built-in function ADDRESS().

The ADDRESS keyword alone interchanges the current and previous hosts. Repeated execution will toggle between the two host addresses.

ADDRESS {string | symbol]} specifies that the new host address is the string or symbol. The value of the string or symbol is the token itself. Message port names are case-sensitive. The appropriate syntax for a program command to a message port named MyPort is:

<syntaxhighlight>
ADDRESS 'MyPort'
</syntaxhighlight>

If you omit the single quotes around MyPort, ARexx will look for the message port MYPORT and generate an error. The current host address becomes the previous address. An expression specified after a string or symbol is evaluated and the result is issued to the specified host. No changes are made to the current or previous address strings. This provides a convenient way to issue a single command to an external host without disturbing the current host addresses. The return code from the command is treated as it would be from a command clause.

If ADDRESS [VALUE] expression is specified. ARexx uses the result of the expression as the new host address, and the current address becomes the previous address. The VALUE keyword may be omitted if the first token of the expression is not a symbol or string. For example:

<syntaxhighlight>
ADDRESS /*Swap current and previous address.*/
ADDRESS edit /*The new host address is EDIT.*/
ADDRESS edit 'top' /*Move to the top.*/
ADDRESS VALUE edit in /*Compute a new host address.*/
</syntaxhighlight>

== ARG ==

<nowiki>ARG [template] [,template...]</nowiki>

ARG is a shorthand form for the PARSE UPPER ARG instruction. It retrieves one or more of the argument strings available to the program and assigns values to the variables in the template. The number of argument strings available depends on whether the program was invoked as a command or a function. Command invocations normally have only one argument string, but functions may have up to 15. The argument strings are not altered by the ARG instruction. ARG returns upper case letters. For example:

<syntaxhighlight>
ARG first,second /*Retrieve arguments*/
</syntaxhighlight>

The structure and processing of templates is described briefly with the PARSE instruction.

== BREAK ==

<nowiki>BREAK</nowiki>

The BREAK instruction is used to exit from the range of a DO instruction or from within an INTERPRETed string. It is valid only in these contexts. If used within a DO statement, BREAK exits from the innermost DO statement containing the BREAK. This contrasts with the similar LEAVE instruction, which exits only from an iterative (repeating) DO. For example:

<syntaxhighlight>
DO /*Begin block*/
IF i>3 THEN BREAK /*Finished?*/
a = a + 1
y.a = name
END /*End block*/
</syntaxhighlight>

== CALL ==

<nowiki>CALL {symbol | string} [expressions] [,expression, ...]</nowiki>

The CALL instruction is used to invoke an internal or external function. The function name is specified by the symbol or string token. Any expressions that follow are evaluated and become the arguments to the called function. The value returned by the function is assigned to the special variable RESULT. It is not an error if a result string is not returned. In this case the variable RESULT is DROPped (becomes uninitialized).

The linkage to the function is established dynamically at the time of the call. ARexx follows a specific search order in attempting to locate the called function. For example:

<syntaxhighlight>
CALL CENTER name, length+4, '+'
</syntaxhighlight>

CENTER is the called function. The expressions will be evaluated and passed as arguments to CENTER.

== DO ==

<nowiki>DO [[var=exp] | [exp] [TO exp] [BY exp]] [FOR exp] [FOREVER] [WHILE exp | UNTIL exp]</nowiki>

The DO instruction begins a group of instructions executed as a block. The range of the DO instruction includes all statements up to and including an eventual END instruction.

If no subkeywords follow the DO instruction, the block is executed once. Subkeywords can be used to iterate the block until a termination condition occurs. An interative DO instruction is sometimes called a loop since ARexx "loops back" to perform the instruction repeatedly. The various parts of the DO instruction are:

* An initializer expression of the form "variable=expression" defines the index variable of the loop. The expression is evaluated when the DO range is first activated and the result is assigned to the index variable. On subsequent iterations an expression of the form "variable = variable + increment" is evaluated, where the increment is the result of the BY expression. If specified, the initializer expression must precede any of the other subkeywords.

* The expression following a BY symbol defines the increment to be added to the index variable in each subsequent iteration. The expression must yield a numeric result, which may be positive or negative and need not be an integer. The default increment is 1.

* The result of the TO expression specifies the upper (or lower) limit for the index variable. At each iteration the index variable is compared to the TO result. If the increment (BY result) is positive and the variable is greater than the limit, the DO instruction terminates and control passes to the statement following the END instruction. The loop also terminates if the increment is negative and the index variable is less than the limit.

* The FOR expression must yield a positive whole number when evaluated and specifies the maximum number of iterations to be performed. The loop terminates when this limit is reached, irrespective of the value of the index variable.

* The initializer BY, TO and FOR expressions are evaluated only when the instruction is first activated, so the increment and limits are fixed through the execution. A limit is not required. For example, the instruction "DO i=1" will simply count away forever.

* The FOREVER keyword can be used if an iterative DO instruction is required but no index variable is necessary. The loop will be terminated by a LEAVE or BREAK instruction contained within the loop.

* The WHILE expression is evaluated at the beginning of each iteration and must result in a Boolean value. The iteration proceeds if the result is 1 (true); otherwise, the loop terminates.

* The UNTIL expression is evaluated at the end of each iteration and must result in a Boolean value. The instruction continues with the next iteration if the result is 0 (false), and terminates otherwise. (WHILE and UNTIL are mutually exclusive.)

=== Program 12. Iteration.rexx ===

<syntaxhighlight>
/*Examples of DO*/
LIMIT = 20; number = 1
DO i=1 to LIMIT for 10 WHILE number < 20
number = i * number
SAY "Iteration" i "number=" number
END
number = number/3.345; i = 0
DO number for LIMIT/5
i = i + 1
SAY "Iteration" i "number=" number
END
</syntaxhighlight>

The output is shown with comment lines for explanation. The comments would not appear on your screen.

Iteration 1 number = 1 /*1 * 1 = 1*/
Iteration 2 number = 2 /*2 * 1 = 2*/
Iteration 3 number = 6 /*3 * 2 = 6*/
Iteration 4 number = 24 /*4 * 6 = 24*/
Iteration 1 number = 7.17488789 /*24/3.345 = 7.17488789*/
Iteration 2 number = 7.17488789 /*number doesn't change*/
Iteration 3 number = 7.17488789 /*limit/5 = 20/5 = 4*/
Iteration 4 number = 7.17488789 /*operation repeats 4 times*/

{{Note|If a FOR limit is also present, the initial expression is still evaluated, but the result need not be a positive integer.}}

== DROP ==

<nowiki>DROP variable [variable ...]</nowiki>

The specified variable symbols are reset to their unintialized state, in which the value of the variable is the variable name itself. It is not an error to DROP a variable that is already uninitialized. DROPping a stem symbol is equivalent to DROPping the values of all possible compound symbols derived from the stem. For example:

<syntaxhighlight>
a = 123 /*Assign a value to a */
DROP a b /*DROP (remove) the values from A and B*/
SAY a b /*Results in A B.*/
</syntaxhighlight>

== ECHO ==

<nowiki>ECHO [expression]</nowiki>

The ECHO instruction is a synonym for the SAY instruction. It displays the expression result on the console. For example:

<syntaxhighlight>
ECHO "you don't say"
</syntaxhighlight>

== ELSE ==

<nowiki>ELSE [;] [conditional statement]</nowiki>

The ELSE instruction provides the alternative conditional branch for an IF statement. It is valid only within the range of an IF instruction and must follow the conditional statement of the THEN branch. If the THEN branch isn't executed, the statement following the ELSE clause is performed.

ELSE clauses always bind to the nearest, preceding IF statement. It may be necessary to provide "dummy" ELSE clauses for the inner IF ranges of a compound IF statement to allow alternative branches for the outer IF statements. It is not sufficient to follow the ELSE with a semicolon or a null clause. Instead, the NOP (no-operation) instruction can be used. For example:

<syntaxhighlight>
IF i > 2 THEN SAY 'Really?'
ELSE SAY 'I thought so'
</syntaxhighlight>

== END ==

<nowiki>END [variable]</nowiki>

The END instruction terminates the range of a DO or SELECT instruction. If the optional variable symbol is supplied, it is compared to the index variable of the DO statement (which must be iterative). An error is generated if the symbols do not match. For example:

<syntaxhighlight>
DO i=1 to 5 /*Index variable is i*/
SAY i
END i /*End "i" loop*/
</syntaxhighlight>

== EXIT ==

<nowiki>EXIT [expression]</nowiki>

The EXIT instruction terminates the execution of a program. It is valid anywhere within a program. The evaluated expression is passed back to the caller as the function or command result.

The processing of the EXIT result depends on whether a result string was requested by the calling program and whether the current invocation resulted from a command or function call.

* If a result string was requested, the expression result is copied to a block of allocated memory and a pointer to the block is returned as the secondary result of the call.

* If the caller did not request a result string and the program was invoked as a command, an attempt is made to convert the expression result to an integer. This value is then returned as the primary result, with 0 as the secondary result. This allows the EXIT information to be interpreted as a return code by the caller.

For example:

<syntaxhighlight>
EXIT /*No result needed*/
EXIT 10 /*An error return*/
</syntaxhighlight>

== IF ==

<nowiki>IF expression [THEN] [;] [conditional statement]</nowiki>

The IF instruction is used in conjunction with THEN and ELSE instructions to conditionally execute a statement. The result of the expression must be a Boolean value. If the result is 1 (True), the statement following the THEN symbol is executed. Otherwise, control passes to the next statement. The THEN keyword need not immediately follow the IF expression, but may appear as a separate clause.

The instruction is analyzed as "IF expression; THEN; statement". The expression following the IF statement establishes the test condition that determines whether subsequent THEN or ELSE clauses will be performed. Any valid statement may follow the THEN symbol. In particular, a "DO ... END;" group allows a series of statements to be performed conditionally. For example:

<syntaxhighlight>
IF result < 0 THEN exit /*All done?*/
</syntaxhighlight>

== INTERPRET ==

<nowiki>INTERPRET expression</nowiki>

The INTERPRET command treats the expression as though it were a source statement block. The expression is evaluated and the result is executed as one or more program statements. The statements are considered as a group, as if surrounded by a "DO ... END" combination. Any statements can be included in the INTERPRETed source, including DO or SELECT instructions. The BREAK instruction can be used to terminate the processing of INTERPRETed statements.

An INTERPRET instruction activates a control range when it is executed, which serves as a boundary for LEAVE and ITERATE instructions. These instructions can only be used with DO loops defined within the INTERPRET. While it is not an error to include label clauses within the interpreted string, only those labels defined in the original program are searched during a transfer of control.

The INTERPRET instruction can be used to construct programs dynamically and then execute them. Program fragments may be passed as arguments to functions, which then INTERPRET the fragments. For example:

<syntaxhighlight>
inst = 'SAY' /*An instruction*/
INTERPRET inst hello /*. . . "SAY HELLO"*/
</syntaxhighlight>

== ITERATE ==

<nowiki>ITERATE [variable]</nowiki>

The ITERATE instruction terminates the current iteration of a DO instruction and begins the next iteration. Effectively, control passes to the END statement and then (depending on the outcome of the UNTIL expression) back to the DO statement. The instruction normally acts on the innermost iterative DO range. An error results if the ITERATE instruction is not contained within an iterative DO instruction.

If several nested ranges exist, the optional variable symbol specifies which DO range is to be exited. The variable is taken as a literal and must match the index variable of a currently active DO instruction. An error results if a matching DO instruction is not found. For example:

<syntaxhighlight>
DO i=1 to 5
IF i = 3 THEN ITERATE i
SAY i
END
</syntaxhighlight>

== LEAVE ==

<nowiki>LEAVE [variable]</nowiki>

LEAVE forces an immediate exit from the iterative DO range containing the instruction. An error results if the LEAVE instruction is not contained within an iterative DO instruction. If several nested ranges exist, the optional variable symbol specifies which DO range is to be exited. The variable is taken as a literal and must match the index variable of a currently active DO instruction. An error results if a matching DO instruction is not found. For example:

<syntaxhighlight>
DO i = 1 to limit
IF i > 5 THEN LEAVE /*Maximum iterations*/
END
</syntaxhighlight>

== NOP ==

<nowiki>NOP</nowiki>

The NOP (NO-oPeration) instruction is provided to control the binding of ELSE clauses in compound IF statements. For example:

<syntaxhighlight>
IF i = j THEN /*First (outer) IF*/
IF j = k THEN a = 0 /*Inner IF*/
ELSE NOP /*Binds to inner IF*/
ELSE a = a + 1 /*Binds to outer IF*/
</syntaxhighlight>

== NUMERIC ==

<nowiki>NUMERIC {DIGITS | FUZZ} expression NUMERIC FORM {SCIENTIFIC | ENGINEERING}</nowiki>

* The NUMERIC instruction sets options relating to numeric precision and format. The numeric options are preserved when an internal function is called.

* The DIGITS expression option specifies the number of digits of precision for arithmetic calculations. The expression must evaluate to a positive whole number.

* The FUZZ expression option specifies the number of digits to be ignored in numeric comparison operations. This must be a positive whole number, less than the current DIGITS setting.

* The FORM SCIENTIFIC option specifies that numbers that require exponential notation be expressed in scientific notation. The exponent is adjusted so that the mantissa for non-zero number is between 1 and 10. This is the default format.

* The FORM ENGINEERING option selects engineering format for numbers that require exponential notation. Engineering format normalizes a number so that its exponent is a multiple of three and the mantissa (if not 0) is between 1 and 1000.

<syntaxhighlight>
NUMERIC DIGITS 12 /*12 digits of precision*/
NUMERIC FORM SCIENTIFIC /*Result in scientific notation*/
</syntaxhighlight>

== OPTIONS ==

<nowiki>OPTIONS [FAILAT expression]</nowiki>
<nowiki>OPTIONS [PROMPT expression]</nowiki>
<nowiki>OPTIONS [RESULTS]</nowiki>
<nowiki>OPTIONS [CACHE]</nowiki>

The OPTIONS instruction is used to set various internal defaults. The FAILAT expression sets the limit at or above which command return codes will be signaled as errors. It must evaluate to an integer value. The PROMPT expression provides a string to be used as the prompt with the PULL (or PARSE PULL) instruction. The RESULTS keyword indicates that the interpreter should request a result string when it issues commands to an external host.

The internal options controlled by this instruction are preserved across function calls, so an OPTIONS instruction can be issued within an internal function without affecting the caller's environment. If no keyword is specified with the OPTIONS instruction, all controlled options revert to their default settings. The OPTIONS instruction also accepts a NO keyword to reset a selected option to its default value, making it more convenient to reset the RESULTS attribute for a single command without having to reset the FAILAT and PROMPT options.

OPTIONS also accepts a CACHE keyword that can be used to enable or disable an internal statement-caching scheme. The cache is normally enabled. For example:

<syntaxhighlight>
OPTIONS FAILAT 10
OPTIONS PROMPT "Yes Boss?"
OPTIONS RESULTS
</syntaxhighlight>

== OTHERWISE ==

<nowiki>OTHERWISE [;] [conditional statement]</nowiki>

This instruction is valid only within the range of a SELECT instruction and must follow all of the "WHEN ... THEN" statements. If none of the preceding WHEN clauses has succeeded, the statement following the OTHERWISE instruction is executed. An OTHERWISE is not mandatory within a SELECT range. However, an error will result if the OTHERWISE clause is omitted and none of the WHEN instructions succeeds. For example:

<syntaxhighlight>
SELECT
WHEN i=1 THEN say 'one'
WHEN i=2 THEN say 'two'
OTHERWISE SAY 'other'
END
</syntaxhighlight>

== PARSE ==

<nowiki>PARSE [UPPER] inputsource [template] [,template ...]</nowiki>

The PARSE instruction provides a mechanism to extract one or more substrings from a string and assign them to variables. The input string can come from a variety of sources, including argument strings, an expression, or from the console.

Parsing is controlled by a template, which may consist of symbols, strings, operators and parentheses. The template provides both the variables to be given values and the way to determine the value strings. During the parsing operation the input string is split into substrings that are assigned to the variable symbols in the template. The process continues until all of the variables in the template have been assigned a value. If the input string is "used up", any remaining variables are given null values.

When a variable in the template is followed immediately by another variable, the value string is determined by breaking the input string into words separated by blanks. Leading and trailing blanks are not permitted. Each word is assigned to a variable in the template. Normally the last variable receives the untokenized remainder of the input string, since it is not followed by a symbol. A placeholder symbol, a period (.), forces the variable with the period to terminate at the first space in the input stream. Placeholders behave like variables except that they are never assigned a value.

The template may be omitted if the instruction is intended only to create the input string. Templates are described in Chapter 7.

The goal of the parsing operation is to associate a current and next position with each variable symbol in the template. The substring between these positions is then assigned as the value to the variable.

The different options of the instruction are described below.

* The optional UPPER keyword may be used with any of the input sources and specifies that the input string is to be translated to upper case before being parsed. It must be the first token following PARSE.
* The sources for the input strings are specified by the keyword symbols explained below. When multiple templates are supplied, each template receives a new input string, although for some source options the new string will be identical to the previous one. The input source string is copied before being parsed, so the original strings are never altered by the parsing process.
:* The ARG input option retrieves the argument strings supplied when the program was invoked. Command invocations normally have only a single argument string, but functions may have up to 15 argument strings.
:* The EXTERNAL input string is read from STDERR stream, (see Chapter 6) so as not to disturb any PUSHed or QUEUEd data. If multiple templates are supplied, each template will read a new string. This source option is the same as PULL.
:* The NUMERIC input option places the current numeric options in a string in the order DIGITS, FUZZ and FORM, separated by a single space.
:* The PULL input option reads a string from the input console. If multiple templates are supplied, each template will read a new string.
:* The SOURCE input option retrieves the "source" string for the program. This string is formatted as:
: <syntaxhighlight>
{COMMAND | FUNCTION} {0 | 1} CALLED RESOLVED EXT HOST
</syntaxhighlight>
: where:
:* {COMMAND | FUNCTION} indicates whether the program was invoked as a command or as a function.
:* {0 | 1} is a Boolean flag indicating whether a result string was requested by the caller.
:* CALLED is the name used to invoke this program.
:* RESOLVED is the final resolved name of the program.
:* EXT is the file extension to be used for searching (the default is "REXX").
:* HOST is the initial host address for commands.
: The SOURCE option now returns the full path name of the ARexx program file. Formerly just a relative name was given, which was not sufficient to locate the program's source file.
: The "VALUE expression WITH" input string is the result of the supplied expression. The WITH keyword is required to separate the expression from the template. The expression result may be parsed repeatedly by using multiple templates, but the expression is not re-evaluated.
: The "VAR variable" input option uses the value of the specified variable as the input string. When multiple templates are provided, each template uses the current value of the variable. This value may change if the variable is included as an assignment target in any of the templates.
: The VERSION input option of the current configuration of the ARexx interpreter is supplied in the form:
: <syntaxhighlight>
ARexx VERSION CPU MPU VIDEO FREQ
</syntaxhighlight>
: where:
:* VERSION is the release level of the interpreter, formatted as 1.14.
:* CPU indicates the processor currently running the program, and will be one of the values 68000, 68010, 68020, 68030 or 68040.
:* MPU will be either NONE, 68881, or 68882, depending on whether a math coprocessor is available.
:* VIDEO will indicate either NTSC or PAL.
:* FREQ gives the clock (line) frequency as either 60Hz or 50Hz.

For example:

<syntaxhighlight>
/*Numeric string is: "9 0 SCIENTIFIC"*/
PARSE NUMERIC DIGITS FUZZ FORM .
SAY Digits /*9*/
SAY fuzz /*0*/
SAY form /*SCIENTIFIC*/
myvar = 1234567890
PARSE VAR myvar 1 a 3 b +2 c 1 d
SAY a
SAY b
SAY c
SAY d
</syntaxhighlight>

This is the output:

12
34
567890
1234567890

== PROCEDURE ==

<nowiki>PROCEDURE [EXPOSE variable [variable...]]</nowiki>

The PROCEDURE instruction is used within an internal function to create a new symbol table. This protects the symbols defined in the caller's environment from being altered by the execution of the function. PROCEDURE is usually the first statement within the function, although it is valid anywhere within the function body. It is an error to execute two PROCEDURE statements within the same function.

The EXPOSE subkeyword provides a selective mechanism for accessing the caller's symbol table, and or passing global variables to a function. The variables following the EXPOSE keyword are taken to refer to symbols in the caller's table. Any subsequent changes made to these variables will be reflected in the caller's environment.

The variables in the EXPOSE list may include stem or compound symbols, in which case the ordering of the variables becomes significant. The EXPOSE list is processed from left to right and compound symbols are expanded based on the values in effect in the new generation. For example, suppose that the value of the symbol J in the previous generation is 123, and that J is uninitialized in the new generation. Then PROCEDURE EXPOSE J A.J will expose J and A.123, whereas PROCEDURE EXPOSE A.J J will expose A.J and J. Exposing a stem has the effect of exposing all possible compound symbols derived from that stem. That is, PROCEDURE EXPOSE A. exposes A.I, A.J, A.J.J, A.123, etc. For example:

<syntaxhighlight>
fact: PROCEDURE /*A recursive function*/
ARG i
IF i = 1
THEN RETURN 1
ELSE RETURN i * fact (i-1)
</syntaxhighlight>

== PULL ==

<nowiki>PULL [template] [,template...]</nowiki>

Pull is the shorthand form of the PARSE UPPER PULL instruction. It reads a string from the input console, translates it to upper case and parses it using the template. Multiple strings can be read by supplying additional templates. The instruction will read from the console even if no template is given. (Templates are described in Chapter 7.) For example:

<syntaxhighlight>
PULL first last . /*Read names*/
</syntaxhighlight>

== PUSH ==

<nowiki>PUSH [expression]</nowiki>

The PUSH instruction is used to prepare a stream of data to be read by a command shell or other program. It appends a newline to the result of the expression then stacks or "pushes" it into the STDIN stream. Stacked lines are placed in the stream in "last-in, first-out" order and are available to be read just as though they had been entered interactively. For example, after issuing the instructions:

<syntaxhighlight>
PUSH line 1
PUSH line 2
PUSH line 3
</syntaxhighlight>

the stream would be read in the order line 3, line 2, and line 1.

PUSH allows the STDIN stream to be used as a private scratch pad to prepare data for subsequent processing. For example, several files could be concatenated with delimiters between them by simply reading the input files, PUSHing the line into the stream and inserting a delimiter where required. For example:

<syntaxhighlight>
DO i=1 to 5
PUSH 'echo "Line 'i'"'
END
</syntaxhighlight>

== QUEUE ==

<nowiki>QUEUE [expression]</nowiki>

The QUEUE instruction is used to prepare a stream of data to be read by a command shell or other program. It is very similar to the PUSH instruction and differs only in that the data lines are placed in the STDIN stream in "first-in, first-out" order. In this case, the instructions:

<syntaxhighlight>
QUEUE line 1
QUEUE line 2
QUEUE line 3
</syntaxhighlight>

would be read in the order line 1, line 2, and line 3. The QUEUEd lines always precede all interactively-entered lines and always follow any PUSHed (stacked) lines. For example:

<syntaxhighlight>
DO i=1 to 5
QUEUE 'echo "Line 'i'"'
END
</syntaxhighlight>

== RETURN ==

<nowiki>RETURN [expression]</nowiki>

RETURN is used to leave a function and return control to the point of the function's invocation. The evaluated expression is returned as the function result. If an expression is not supplied, an error may result in the caller's environment. Functions called from within an expression must return a result string and will generate an error if no result is available. Functions invoked by the CALL instruction need to return a result.

A RETURN issued from the base environment of a program is not an error and is equivalent to an EXIT instruction. Refer to the EXIT instruction for a description of how result strings are passed back to an external caller. For example:

<syntaxhighlight>
RETURN 6*7 /*Returns 42*/
</syntaxhighlight>

== SAY ==

<nowiki>SAY [expression]</nowiki>

The result of the evaluated expressions is written to the output console, with a newline character appended. If the expression is omitted, a null string is sent to the console. For example:

<syntaxhighlight>
SAY 'The answer is ' value
</syntaxhighlight>

== SELECT ==

<nowiki>SELECT</nowiki>

SELECT begins a group of instructions containing one or more WHEN clauses and possibly a single OTHERWISE clause, each followed by a conditional statement. Only one of the conditional statements within the SELECT group will be executed. Each WHEN statement is executed in succession until one succeeds. If none succeeds, the OTHERWISE statement is executed. The SELECT range must be terminated by an END statement. For example:

<syntaxhighlight>
SELECT
WHEN i=1 THEN SAY 'one'
WHEN i=2 THEN SAY 'two'
OTHERWISE SAY 'other'
END
</syntaxhighlight>

== SHELL ==

<nowiki>SHELL [symbol | string | [[VALUE] [expression]]</nowiki>

The SHELL instruction is a synonym for the ADDRESS instruction. For example:

<syntaxhighlight>
SHELL edit /*Set host to 'EDIT'*/
</syntaxhighlight>

== SIGNAL ==

<nowiki>SIGNAL {ON | OFF} condition SIGNAL [VALUE] expression</nowiki>

SIGNAL {ON | OFF} controls the state of the internal interrupt flags. Interrupts allow a program to detect and retain control when certain errors occur. In this form SIGNAL must be followed by one of the keywords ON or OFF and one of the condition keywords listed below. The interrupt flag specified by the condition symbol is then set to the indicated state. The valid signal conditions are:

{| class="wikitable"
| '''BREAK_C''' || A Ctrl+C break was detected.
|-
| '''BREAK_D''' || A Ctrl+D break was detected.
|-
| '''BREAK_E''' || A Ctrl+E break was detected.
|-
| '''BREAK_F''' || A Ctrl+F break was detected.
|-
| '''ERROR''' || A host command returned a non-zero code.
|-
| '''HALT''' || An external HALT request was detected.
|-
| '''IOERR''' || An error was detected by the I/O system.
|-
| '''NOVALUE''' || An uninitialized variable was used.
|-
| '''SYNTAX''' || A syntax or execution error was detected.
|}

The condition keywords are interpreted as labels to which control will be transferred if the selected condition occurs. For example, if the ERROR interrupt is enabled and a command returns a non-zero code, ARexx will transfer control to the label ERROR:. The condition label must be defined in the program; otherwise, an immediate SYNTAX error results and the program exits.

In SIGNAL [VALUE] expression, the tokens following SIGNAL are evaluated as an expression. An immediate interrupt is generated that transfers control to the label specified by the expression result. The instruction thus acts as a "computed goto".

Whenever an interrupt occurs, all currently active control ranges (IF, DO, SELECT, INTERPRET, or interactive TRACE) are dismantled before the transfer of control. Thus, the transfer cannot be used to jump into the range of a DO loop or other control structure. Only the control structures in the current environment are affected by a SIGNAL condition, making it safe to SIGNAL from within an internal function without affecting the state of the caller's environment.

The special variable SIGL is set to the current line number whenever a transfer of control occurs. The program can inspect SIGL to determine which line was being executed before the transfer. If an ERROR or SYNTAX condition causes an interrupt, the special variable RC is set to the error code that triggered the interrupt. For the ERROR condition, this code is usually an error severity level. Refer to Appendix A for further details on error codes and severity levels. The SYNTAX condition will always indicate an ARexx error code. For example:

<syntaxhighlight>
SIGNAL on error /*Enable interrupt*/
SIGNAL off syntax /*Disable SYNTAX*/
SIGNAL start /*Goto START*/
</syntaxhighlight>

== WHEN ==

<nowiki>WHEN expression [THEN [;] [conditional statement]]</nowiki>

The WHEN instruction is similar to the IF instruction, but is valid only within a SELECT range. Each WHEN expression is evaluated in turn and must result in a Boolean value. If the result is a 1, the conditional statement is executed and control passes to the END statement that terminates the SELECT. As with the IF instruction, the THEN need not be part of the same clause. For example:

<syntaxhighlight>
SELECT
WHEN i<j THEN SAY 'less'
WHEN i=j THEN SAY 'equal'
OTHERWISE SAY 'greater'
END
</syntaxhighlight>

AmigaOS Manual: ARexx Elements of ARexx

2014-01-27T22:34:31Z

Tony Wyatt: More typos

This chapter introduces the rules and concepts that make up the ARexx programming language and explains how ARexx interprets the characters and words used in programs. The different elements that are explained include:

* Tokens - the smallest element of the ARexx language
* Clauses - the smallest executable unit, similar to a sentence
* Expressions - a group of evaluated tokens
* The Command Interface - the process by which ARexx programs communicate with ARexx-compatible applications

This chapter also includes a discussion of the ARexx execution environment. This is intended for more advanced Amiga users and includes technical details on interprocess communication.

= Tokens =

Tokens, the smallest distinct entities of the ARexx language, may be a single character or a series of characters. There are five categories of tokens:

* comments
* symbols
* strings
* operators
* special characters

== Comments ==

A comment is any group of characters beginning with the sequence /* (slash asterisk) and ending with */ (asterisk slash). Each ARexx program must begin with a comment. Each /* must have a matching */ . For example:

<syntaxhighlight>
/*This is an ARexx comment*/
</syntaxhighlight>

Comments may be placed anywhere in a program and can even be nested within one another. For example:

<syntaxhighlight>
/*A /*nested*/ comment*/
</syntaxhighlight>

Insert comments throughout your program. Comments remind you and others of the program's intentions. Because the interpreter ignores comments when it scans your programs, comments do not slow down the execution of your program.

== Symbols ==

A symbol is any group of the characters a-z, A-Z, 0-9, and period (.), exclamation point (!), question mark (?), dollar sign ($), and underscore (_). Symbols are translated to uppercase as the interpreter scans the program, so the symbol MyName is equivalent to MYNAME. The four types of recognized symbols are:

; Fixed symbols
: A series of numeric characters that begins with a digit (0-9) or a period (.). The value of a fixed symbol is always the symbol name itself, translated to uppercase. 12345 is an example of a fixed symbol.

; Simple symbols
: A series of alphabetic characters that begins with a letter A-Z. "MyName" is an example of a simple symbol.

; Stem symbols
: A series of alphanumeric characters that ends with one period. "A." and "Stem9." Are examples of stem symbols.

; Compound symbols
: A series of alphanumeric characters that includes one or more periods within the characters. "A.1.Index" is an example of a compound symbol.

Simple, stem, and compound symbols are called variables and may be assigned a value during the course of the program execution. If a variable has not yet been assigned a value, it is uninitialized. The value for an uninitialized variable is the variable name itself (translated to uppercase, if applicable).

Stems and compound symbols have special properties that make them useful for building arrays and lists. Stem symbols provide a way to initialize a whole class of compound symbols. A compound symbol can be regarded as having the structure stem.n1.n2...nk, where the leading name is a stem symbol and each node, n1...nk, is a fixed or simple symbol.

When an assignment is made to a stem symbol, it assigns that value to all possible compound symbols derived from the stem. Thus, the value of a compound symbol depends on the prior assignments made to itself or its associated stem.

Whenever a compound symbol appears in a program, its name is expanded by replacing each node with its current value. The value string may consist of any characters, including embedded blanks, and will not be converted to uppercase. The result of the expansion is a new name that is used in place of the compound symbol. For example, if J has the value 3 and K has the value 7, then the compound symbol A.J.K will expand to A.3.7.

Compound symbols can be regarded as a form of associative or content-addressable memory. For example, suppose that you needed to store and retrieve a set of names and telephone numbers. The conventional approach would be to set up two arrays, NAME and NUMBER, each indexed by an integer running from one to the number of entries. A number would be looked up by scanning the name array until the given name was found, say in NAME.12, and then retrieving NUMBER.12. With compound symbols, the symbol NAME could hold the name to be retrieved, and NUMBER.NAME would then expand to the corresponding number, for example, NUMBER.CBM.

Compound symbols can also be used as conventional indexed arrays, with the added convenience that only a single assignment (to the stem) is required to initialize the entire array.

For instance, the program below uses the stems "number." and "addr." to create a computerized telephone directory.

=== Program 8. Phone.rexx ===

<syntaxhighlight>
/*A telephone book to show compound variables.*/
IF ARG () ~ = 1 THEN DO
SAY "USAGE: rx phone name"
EXIT 5
END
/*Open window to display phone nos/addresses.*/
CALL OPEN out, "con:0/0/640/60/ARexx Phonebook"
IF ~ result THEN DO
SAY "Open failure ... sorry"
EXIT 10
END
/*Number definitions*/
number. = '(not found)'
number.wsh = '(555) 001-0001'
addr. = '(not found)'
number.CBM = '(555) 002-0002'
addr.CBM = '1200 Wilson Dr., West Chester, PA, 19380'
/*(Work is done here)*/
ARG name /*The name*/
CALLWRITELN out, name | | " 's number is" number.name
CALL WRITELN out,name | | " 's address is" addr.name
CALL WRITELN out, "Press Return to exit."
CALL READLN out
EXIT
</syntaxhighlight>

To execute the program, activate a Shell window and enter:

RX Phone cbm

A window will display the name and address assigned to CBM.

== Strings ==

A string is any group of characters beginning and ending with a quote (') or double quote (") delimiter. The same delimiter must be used at both ends of the string. To include the delimiter character in the string, use a double-delimiter sequence ('' or ""). For example:

"Now is the time." An example of a normal string.

'Can''t you see?' An example of a string using a double-delimiter sequence.

The value of a string is the string itself. The number of characters in the string is called its length. If the string does not contain any characters, it is called a null string.

Strings that are followed by an X or B character are classified as hex or binary strings, respectively, and must be composed of hexadecimal digits (0-9, A-F) or binary digits (0,1). For example:

'4A 3B C0'X
'00110111'B

Blanks are permitted at byte boundaries to improve readability. Hex and binary strings are convenient for specifying non-ASCII characters and machine-specific information, like addresses. They are converted immediately to the packed (machine-compressed) internal form.

== Operators ==

Operators are a combination of the following characters: ~ + - * / = > < & | ^, as explained in this section. There are four types of operators:

* Arithmetic operators require one or two numeric operands and produce a numeric result.
* Concatenation operators join two strings into a single string.
* Comparison operators require two operands and produce a Boolean (0 or 1) result.
* Logical operators require one or two Boolean operands and produce a Boolean result.

Each operator has an associated priority that determines the order in which operations will be performed in an expression. Operators with higher priorities (8) are performed before those with lower priorities (1).

=== Arithmetic Operators ===

An important class of operands is that representing numbers. Numbers consist of the characters 0-9, a period (.), plus sign (+), minus sign (-), and blanks. To indicate exponential notation, a number may be followed by an "e" or "E" and a (signed) integer.

Both strings and symbols may be used to specify numbers. Since the language is typeless, variables do not have to be declared as numeric before use in an arithmetic operation. Instead, each value string is examined when it is used in order to verify that it represents a number. The following examples are all valid numbers:

33
" 12.3 "
0.321e12
' + 15. '

Leading and trailing blanks are permitted. Blanks may be embedded between a plus (+) or minus (-) sign and the number, but not within the number itself.

You can modify the basic precision used for arithmetic calculations while a program is executing. The number of significant figures used in arithmetic operations is determined by the Numeric Digits setting and may be modified using the NUMERIC instruction described in Chapter 4.

The number of decimal places used for a result depends on the operation and the number of decimal places in the operands. ARexx preserves trailing zeroes to indicate the precision of the result. If the total number of digits required to express a value exceeds the current Numeric Digits setting, the number is formatted in exponential notation. They are:

* Scientific notation - the exponent is adjusted so that a single digit is placed to the left of the decimal point.
* Engineering notation - the number is scaled so that the exponent is a multiple of 3 and the digits to the left of the decimal point range from 1 to 999.

{| class="wikitable"
|+ Table 3-1. Arithmetic Operators
! Operator !! Priority !! Example !! Result
|-
| + (prefix conversion) || 8 || '3.12' || 3.12
|-
| - (prefix negation) || 8 || -"3.12" || -3.12
|-
| ** (exponentiation) || 7 || 0.5**3 || 0.125
|-
| * (multiplication) || 6 || 1.5*1.50 || 2.250
|-
| / (division) || 6 || 6 / 3 || 2
|-
| % (integer division) || 6 || -8 % 3 || -2
|-
| // (remainder) || 6 || 5.1//0.2 || 7.15
|-
| + (addition) || 5 || 3.1+4.05 || 7.15
|-
| - (subtraction) || 5 || 5.55 - 1 || 4.55
|}

=== Concatenation Operators ===

ARexx defines two concatenation operators. The first, identified by the operator sequence || (two vertical bars), joins two strings into a single string with no intervening blank. This type of concatenation can also be specified implicitly. When a symbol and a string are typed without any intervening spaces, ARexx behaves as if the || operator had been specified. The second concatenation operation is identified by the blank operator and joins the two operand strings with one intervening blank.

The priority of all concatenation operations is 4. Table 3-2 summarizes the different operations.

{| class="wikitable"
|+ Table 3-2. Concatenation Operators
! Operator !! Operation !! Example !! Result
|-
| <nowiki>||</nowiki> || Concatenation || 'why me, '<nowiki>||</nowiki>'Mom?' || why me, Mom?
|-
| Blank || Blank Concatenation || 'good<nowiki>''</nowiki>times' || good times
|-
| none || Implied Concatenation || one'two'three || ONEtwoTHREE
|}

=== Comparison Operators ===

ARexx supports three types of comparisons:

* Exact comparisons - character-by-character comparison.
* String comparisons - ignore leading blanks and add blanks to the shorter string.
* Numeric comparisons - convert the operands to an internal numeric form using the current Numeric Digits setting and then run an arithmetic comparison.

Comparisons always result in a Boolean value. The numbers 0 and 1 are used to represent the Boolean values false and true. The use of a value other than 0 or 1 when a Boolean operand is expected will generate an error. Any number equivalent to 0 or 1, for example 0.000 or 0.1E1, is also acceptable as a Boolean value.

Except for the exact equality (==) and exact inequality (~==) operators, all comparison operators dynamically determine whether a string or numeric comparison is to be performed. A numeric comparison is performed if both operands are valid numbers. Otherwise, the operands are compared as strings.

All comparisons have a priority of 3. Table 3-3 lists the acceptable comparison operators.

{| class="wikitable"
|+ Table 3-3. Comparison Operators
! Operator !! Operation !! Mode
|-
| == || Exact Equality || Exact
|-
| ~== || Exact Inequality || Exact
|-
| = || Equality || String/Numeric
|-
| ~= || Inequality || String/Numeric
|-
| > || Greater Than || String/Numeric
|-
| >= or ~< || Greater Than or Equal To || String/Numeric
|-
| < || Less Than || String/Numeric
|-
| <= or ~> || Less Than or Equal To || String/Numeric
|}

=== Logical (Boolean) Operators ===

ARexx defines the four logical operations, NOT, AND, OR, and Exclusive OR, all of which require Boolean operands and produce a Boolean result. An attempt to perform a logical operation on a non-Boolean operand will generate an error. Table 3-4 shows the acceptable logical operators.

{| class="wikitable"
|+ Table 3-4. Logical Operators
! Operator !! Priority !! Operation
|-
| ~ || 8 || NOT (Inversion)
|-
| & || 2 || AND
|-
| <nowiki>|</nowiki> || 1 || OR
|-
| ^or && || 1 || Exclusive OR
|}

== Special Characters ==

A few punctuation characters have special meanings within ARexx, as shown in Table 3-5.

{| class="wikitable"
|+ Table 3-5. Special Characters
! Special Character !! Definition
|-
| (:) Colon
| A colon defines a label when preceded by a symbol token (any alphanumeric character or . ! ? $).
|-
| ( ) Parentheses
| Parentheses are used to group operators and operands into subexpressions to override the normal operator priorities. An open parenthesis also serves to identify a function call within an expression. A Symbol or string followed immediately by an open parenthesis defines a function name. Parentheses must always be matched within a statement.
|-
| (;) Semicolon
| A semicolon acts as a statement terminator. Several statements that fit on one line may be separated by semicolons.
|-
| (,) Comma
| A comma acts as the continuation character for statements broken into several lines and as a separator of argument expressions in a function call.
|}

= Clauses =

Clauses, the smallest language unit that can be executed as a statement, are formed from token groupings.

As the program is read, the language interpreter splits the program into groups of clauses. These groups of one or more clauses are then broken down into tokens and each clause is classified as a particular type. Seemingly small syntactic differences may completely change the semantic content of a statement. For example:

<syntaxhighlight>
SAY 'Hello, Bill'
</syntaxhighlight>

is an instruction clause and will display "Hello, Bill" on the console, but:

<syntaxhighlight>
''SAY 'Hello, Bill'
</syntaxhighlight>

is a command clause, and will issue "SAY Hello, Bill" as a command to an external program. The presence of the leading null string ('') changes the classification from an instruction clause to a command clause.

The end of a line normally acts as the implicit end of a clause. A clause can be continued on the next line by ending the line with a comma. The comma is ignored by the program, and the next line is considered as a continuation of the clause. There is no limit to the number of continuations that may occur (except for those limits imposed by the command buffer).

String and comment tokens are automatically continued if a line ends before the closing delimiter has been found, and the newline (i.e., Enter) character is not considered to be part of the token.

== Null Clauses ==

Null clauses are lines of blanks or comments and may appear anywhere in a program. They have no function in the execution of a program, except to aid its readability and to increment the line count.

== Label Clauses ==

A label clause is a symbol followed by a colon (:). A label acts as a place marker in the program, but no action occurs with the execution of a label. The colon is considered as an implicit clause terminator, so each label stands as a separate clause. Label clauses may appear anywhere in a program. For example:

<syntaxhighlight>
start: /*Begin execution*/
syntax: /*Error processing*/
</syntaxhighlight>

== Assignment Clauses ==

Assignment clauses are identified by a variable symbol followed by an = operator. (In this context the = operator's normal definition of equality comparison is overridden.) The tokens to the right of the = are evaluated as an expression and the result is assigned to the variable. For example:

<syntaxhighlight>
When = 'Now is the time'
answ = 3.14 * fact(5)
</syntaxhighlight>

The equal sign (=) assigns the value 'Now is the time' to the variable 'when', and assigns the result of 3.14 * fact(5) to the variable 'answ'.

== Instruction Clauses ==

Instruction clauses begin with the name of the instruction and tell ARexx to perform an action. Instruction names are described in Chapter 4. For example:

<syntaxhighlight>
DROP a b c
SAY 'please'
IF j > 5 THEN LEAVE;
</syntaxhighlight>

== Command Clauses ==

Command clauses are any ARexx expression that cannot be classified as one of the preceding types of clauses. The expression is evaluated and the result is issued as a command to an external host. For example:

<syntaxhighlight>
'delete' 'myfile' /*AmigaDOS command*/
'jump' current+10 /*An editor command*/
</syntaxhighlight>

The delete command is not recognized as an ARexx command, so it is sent to the external host, in this case AmigaDOS. The jump command in the second example is assumed to be understood by an external text editor.

= Expressions =

Expressions are a group of evaluated tokens. Most statements contain at least one expression. Expressions are composed of:

* Strings - The value of a string is the string itself.
* Symbols - The value of a fixed symbol is the symbol itself, translated to uppercase. Symbols may be used as variables and may have an assigned value.
* Operators - An operator has a priority order that determines when it will be performed.
* Parentheses - Parentheses may be used to alter the normal order of evaluation in the expression or to identify function calls. A symbol or string followed immediately by an open parenthesis defines the function name, and the tokens between the opening and closing parenthesis form the argument list for the function. For example, the expression:

<syntaxhighlight>
J 'factorial is' fact (J)
</syntaxhighlight>

is composed of:

* a symbol - J
* a blank operator
* a string - factorial is
* another blank
* a symbol - fact
* an open parenthesis
* a symbol - J
* a closing parenthesis

In this example, FACT is a function name and (J) is its argument list, the single expression J.

Before the evaluation of an expression proceeds, ARexx must obtain a value for each symbol in the expression. For fixed symbols the value is the symbol name itself, but variable symbols must be looked up in the current symbol table. In the example above, if the symbol J was assigned the value 3, the expression after symbol resolution would be:

<syntaxhighlight>
3 'factorial is' FACT (3)
</syntaxhighlight>

To avoid ambiguities in the values assigned to symbols during the resolution process, ARexx guarantees a strict left-to-right resolution order. Symbol resolution proceeds irrespective of operator priority or parenthetical grouping. If a function call is found, the resolution is suspended while the function is evaluated. It is possible for the same symbol to have more than one value in an expression.

If the previous example was rearranged to read:

<syntaxhighlight>
FACT(J) 'is' J 'factorial'
</syntaxhighlight>

would the second occurrence of symbol J still resolve to 3? In general, function calls may have side effects that include altering the values of variables. If the example was rearranged, the value of J might have been changed by the call to FACT.

After all symbol values have been resolved, the expression is evaluated based on operator priority and subexpression grouping. ARexx does not guarantee an order of evaluation among operators of equal priority and does not employ a "fast path" evaluation of Boolean operations. For example, in the expression:

<syntaxhighlight>
(1 = 2) & (FACT(3) = 6)
</syntaxhighlight>

the call to the FACT function will be made even though the first term of the AND (&) operation is 0. This example points out that ARexx will continue reading left to right, even though the given example is false and will return a value of 0.

= 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 ===

<syntaxhighlight>
/*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
</syntaxhighlight>

== 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 ===

<syntaxhighlight>
/*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*/
</syntaxhighlight>

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 ===

<syntaxhighlight>
/*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
</syntaxhighlight>

= The Execution Environment =

{{Note|The material in this section is intended for advanced Amiga users. This information assumes a working knowledge of the Amiga operating system and a familiarity with the reference material on this wiki.}}

The ARexx interpreter, RexxMast, provides a uniform execution environment by running each program as a separate process in the Amiga's multitasking operating system. This allows for a flexible interface between an external host program and RexxMast. The host program can proceed concurrently with its operations or can wait for the interpreted ARexx program to finish. Each ARexx program has both an external and internal environment.

== The External Environment ==

The external environment includes its process structure, input and output streams, and current directory. When each ARexx process is created, it inherits the input and output streams and current directory from its client, the external program that invoked the ARexx program. For example, if an ARexx program was started from a Shell, the ARexx program will inherit the input and output stream and current directory of that Shell. The current directory is used as the starting point in any search for a program or data file. External functions are limited to a maximum of 15 arguments.

== The Internal Environment ==

The internal environment of an ARexx program consists of a static global structure and one or more storage environments. The global data values are fixed (static) at the time the program is invoked. These values include the program source code, static data strings, and argument strings. Once the program is running, these values cannot be changed.

ARexx programs invoked as commands usually have only one argument string, although the command tokenization option may provide more than one. A program invoked as an internal function can have any number of arguments. These arguments persist for the duration of the program.

The storage environment includes the symbol table used for variable values, numeric options, trace options, and host address strings. While the global environment is unique, there may be many storage environments during the course of the program execution. Each time an internal function is called, a new storage environment is activated and initialized. The initial values for most fields are inherited from the previous environment, but values may be changed afterwards without affecting the caller's environment. The new environment persists until control returns from the function.

Every storage environment includes a symbol table to store the value strings that have been assigned to variables. This symbol table is organized as a two-level binary tree. The primary level stores entries for simple and stem symbols. The secondary level is used for compound symbols. All of the compound symbols associated with a particular stem are stored in one tree, with the entry for the stem being the root of the tree.

Symbols are not entered into the table until an assignment is made to the symbol. Once created, entries at the primary level are never removed, even if the symbol subsequently becomes uninitialized. Secondary trees are released whenever a new assignment is made to the stem associated with that tree.

== Resource Tracking ==

ARexx provides complete tracking for all of the dynamically allocated resources that it uses to execute a program. These resources include memory space, DOS files and related structures, and the message port structure. The tracking system was designed to allow a program to shut down at any point without leaving any resources hanging.

It is possible to go outside of the interpreter's resource tracking net by making calls directly to the Amiga operating system from within an ARexx program. It is the programmer's responsibility to trace and return any resources allocated outside of the ARexx resource tracking system. ARexx provides a special interrupt facility so that a program can retain control after an execution error, perform the required cleanup, and exit.

AmigaOS Manual: ARexx Getting Started

2014-01-27T22:29:18Z

Tony Wyatt: More typos

This chapter shows you how to:

* Start ARexx
* Save Programs
* Store Programs
* Use sample programs

= Starting ARexx =

To start using ARexx, you activate the RexxMast program. The RexxMast program can be started automatically or manually. Each time ARexx is started or stopped, a text message appears.

== To Start ARexx Automatically ==

There are two methods to start ARexx automatically: add RexxMast to the WBStartup Prefs window or edit the S:User-Startup file.

To place RexxMast in the WBStartup Prefs list:

# Open the Prefs drawer.
# Open the WBStartup prefs.
# Click the "Add" button.
# Select SYS:System/RexxMast in the requester that pops up
# Click on "Save"
# Reboot your Amiga.

The command to start RexxMast should already be in the S:Startup-Sequence file. If the command has been removed from S:Startup-Sequence, we suggest that you add it to the S:User-Startup file.
To edit the S:User-Startup file:

# Open a text editor like Notepad.
# Open the S:User-Startup file.
# Enter ''SYS:System/RexxMast >NIL:''
# Save the file.
# Reboot your Amiga.

== To Start ARexx Manually ==

There are two ways to start RexxMast manually: double-click on the RexxMast icon in Workbench or start it from the Shell.

To start RexxMast from Workbench:

# Open the System Drawer.
# Double-click on the RexxMast icon.

To start RexxMast from the Shell:

# Open a Shell.
# Type ''RexxMast >NIL:'' and press Enter.

= About ARexx Programs =

ARexx programs are usually stored in the REXX: directory (which is generally assigned to the SYS:S/ARexx directory). Although programs can be stored in any directory, storing them in REXX: has several advantages:

* You can run the program without having to type the complete path.
* All of your ARexx programs will be in the same place.
* Most applications search for ARexx programs in REXX:.

Just as you can store an ARexx program anywhere, you can also name it anything you choose. However, adopting a simple naming convention will make program management much easier. Programs run from the Shell should have a .rexx extension to distinguish them from files run from other applications.

== Running ARexx Programs ==

The Rx command is used to run an ARexx program. If a complete path is included with the program name, only that directory is searched for the program. If no path is included, the current directory and ''REXX:'' are checked. The "Rx" may be in any case, for example, "RX", "rx" and "Rx" will all work the same.

As long as your program is stored in the ''REXX:'' directory, you do not need to include the .rexx extension when specifying your program name. In other words, typing:

Rx Program.rexx

is the same as:

Rx Program

A short program can be entered directly at the command line by enclosing the program line in double-quotes. For example, the following program will send five files named myfile.1 through myfile.5 to the printer.

Rx "DO i=1 to 5;
ADDRESS command 'copy myfile.' | | i 'prt:'; END"

When an application is ARexx-compatible, you can run ARexx programs from within the application by choosing a menu item or by specifying command options. Refer to the application's documentation for more information.

ARexx programs can be run from the Workbench by creating a tool or project icon for the program. You must specify the Rx command as the Default Tool for the icon. In the icon's Information window, enter:

Default Tool: SYS:C/Rx

When the icon is opened, Rx starts RexxMast (if it is not already running). It executes the file associated with the icon as an ARexx program.

ARexx accepts two Tool Types: Console, to specify a window, and CMD, to specify a command string. You enter these Tool Types in the project icon's Information window as:

Console=CON:0/0/640/200/Example/Close
CMD=rexxprogram

= Program Examples =

The following examples illustrate how to use ARexx to display text strings on your screen, to perform calculations, and to activate the error checking feature.

Programs can be entered into any text editor, such as Notepad or a word processor. Save your program as an ASCII file if you use a word processor. ARexx supports the extended ASCII character set (Å, Æ, ß). These extended characters are recognized as ordinary printing characters and will be mapped from lowercase to uppercase.

The examples also illustrate the use of some basic ARexx syntax requirements such as:

* Comment lines
* Spacing rules
* Case-sensitivity
* Use of single and double quotes

Each ARexx program consists of a comment line that describes the program and an instruction that displays text on the console. ARexx programs must always begin with a comment line. The initial (slash asterisk) /* matched with an ending (asterisk slash) */ tells the RexxMast interpreter that it has found an ARexx program. Without the /* and the */, RexxMast will not view the file as an ARexx program. Once it begins executing the program, ARexx ignores any additional comment lines within the file. However, comment lines are extremely useful when reading the program. They can help organize and make sense of a program.

== Amiga.rexx ==

This program shows how to use SAY in a set of instructions to display text strings on the screen. Instructions are language statements that denote a certain action to be performed. Each statement always begins with a symbol. In the following example, the symbol is SAY. (Symbols are always translated to uppercase letters when the program is run.) Following SAY is an example of a string. A string is a series of characters surrounded by single quotes (') or double quotes (").

=== Program 1. Amiga.rexx ===

<syntaxhighlight>
/*A simple program*/
SAY 'Amiga. The Computer For the Creative Mind.'
</syntaxhighlight>

Enter the above program, and save it as REXX:Amiga.rexx . To run the program, open a Shell window and type:

Rx Amiga

Although the full path and program name is ''Rexx:Amiga.rexx'', you do not need to type the REXX: directory name or the .rexx extension if the program has been saved in the REXX: directory.

You should see the following text in your Shell window:

Amiga. The Computer for the Creative Mind.

== Age.rexx ==

This program displays a prompt for input and then reads entered information.

=== Program 2. Age.rexx ===

<syntaxhighlight>
/*Calculate age in days*/
SAY 'Please enter your age:'
PULL age
SAY 'You are about' age*365 'days old.'
</syntaxhighlight>

Save this program as ''REXX:Age.rexx'' and run it with the command:

Rx age

This program begins with a comment line that describes what the program will do. All ARexx programs begin with a comment. The SAY instruction displays a request for input on the console.

The PULL instruction reads a line of input from the user, which in this case is the user's age. PULL takes the input, converts it to uppercase letters, and stores it in a variable. Variables are symbols which may be assigned a value. Choose descriptive variable names! This example uses the variable name "age" to hold the entered number.

The final line multiplies the variable "age" by 365 and issues the SAY instruction to display the result. The "age" variable did not have to be declared as a number because its value was checked when it was used in the expression. This is an example of typeless data. To see what would happen if age was not a number, try running the program again with a non-numeric entry for the age. The resulting error message shows the line number and type of error that occurred.

== Calc.rexx ==

This program introduces the DO instruction, which repeats the execution of program statements. It also illustrates the exponentiation operator ( ** ). Enter this program and save it as ''REXX:Calc.rexx''. To run the program, use the "Rx calc" command.

=== Program 3. Calc.rexx ===

<syntaxhighlight>
/*Calculate some squares and cubes.*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
SAY i i**2 i**3 /*Perform calculations*/
END /*End of loop*/
SAY 'All done.'
</syntaxhighlight>

The DO instruction repeatedly executes the statements between the DO and END instructions. The variable "i" is the index variable for the loop and is incremented by 1 for each iteration (repetition). The number following the symbol TO is the limit for the DO instruction and could have been a variable or a full expression rather than just the constant 10.

Generally, ARexx programs use single spacing between alphanumeric characters. In Program 3, however, spacing is closed up between the exponentiation characters ( ** ) and the variables ( i and 2, i and 3).

The statements within the loop have been indented. This is not required by the language, but it makes the program more readable, because you can easily visualize where the loop starts and stops.

== Even.rexx ==

The IF instruction allows statements to be conditionally executed. In this example, the numbers from 1 to 10 are classified as odd or even by dividing them by 2 and then checking the remainder. The // arithmetic operator calculates the remainder after a division operation.

=== Program 4. Even.rexx ===

<syntaxhighlight>
/*Even or odd?*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
IF 1 // 2 = 0 THEN type = 'even'
ELSE type = 'odd'
SAY i 'is' type
END /*End loop*/
</syntaxhighlight>

The IF line states that if the remainder of the division of the variable "i" by 2 equals 0, then set the variable "type" to even. If the remainder is not 0, the program will skip over the THEN branch and execute the ELSE branch, setting variable "type" to odd.

== Square.rexx ==

This example introduces the concept of a function, a group of statements executed by mentioning the function name in a suitable context. Functions allow you to build large complex programs from smaller modules. Functions also permit the same code for similar operations in a different program.

Functions are specified in an expression as a name followed by an open parenthesis. (There is no space between the name and the parenthesis.) One or more expressions, called arguments, may follow the parenthesis. The last argument must be followed by a closing parenthesis. These arguments pass information to the function for processing.

=== Program 5. Square.rexx ===

<syntaxhighlight>
/*Defining and calling a function.*/

DO i = 1 to 5
SAY i square(i) /*Call the "square" function*/
END
EXIT
square: /*Function name*/
ARG x /*Get the argument*/
RETURN x**2 /*Square it and return*/
</syntaxhighlight>

Starting with DO and ending with END , a loop is set up with an index variable "i", that will increment by 1. The loop will iterate (repeat) five times. The loop contains an expression that calls the function "square" when the expression is evaluated. The function's result is displayed using the SAY instruction.

The function "square", defined by the ARG and RETURN instructions, calculates the squared values. ARG retrieves the value of the argument string "i" and RETURN passes the function's result back to the SAY instruction.

Once the function is called by the loop, the program looks for the function name "square", retrieves the argument "i", performs a calculation, and returns to the line within the DO/END loop. The EXIT instruction ends the program after the final loop.

== Results.rexx ==

The TRACE instruction activates ARexx's error checking feature.

=== Program 6. Results.rexx ===

<syntaxhighlight>
/*Demonstrate "results" tracing*/
TRACE results
sum = 0 ; sumsq = 0;
DO i = 1 to 5
sum = sum + 1
sumsq = sumsq + i**2
END
SAY 'sum=' sum 'sumsq=' sumsq
</syntaxhighlight>

The console displays the executed source lines, each pass through the DO/END loop, and the expression's final results. Removing the TRACE instruction, would display only the final result: sum = 15 sumsq = 55 .

== Grades.rexx ==

This program calculates the final grade for a given student based on four essay grades and a class participation grade. The average of Essay 1 and Essay 2 is worth 30%, the average of Essay 3 and Essay 4 is worth 45%, and participation is worth 25% of the final grade.

Once a final grade is displayed, an option to continue with another calculation is presented. The response is "PULLed" and if it does not equal "Q" (quit), the loop continues. If the response equals "Q" , the program quits the loop and exits.

=== Program 7. Grades.rexx ===

<syntaxhighlight>
/*Grading program*/
SAY "Hallo, I will calculate your grades for you."
Response = 0
DO while response ~ = "Q" /*Loop while response isn't Q*/
SAY "Please enter all grades for the student."
SAY "Essay 1:"
PULL es1
SAY "Essay 2:"
PULL es2
SAY "Essay 3:"
PULL es3
SAY "Essay 4:"
PULL es4
SAY "Participation:"
PULL p
Final = (((es1 + es2)/2*.3) + ((es3 + es4)/2*.45) + (p*.25))
SAY "Your final grade for this student is " Final
SAY "Would you like to continue? (Q for quit.)"
PULL response
END
EXIT
</syntaxhighlight>

AmigaOS Manual: ARexx Functions

2014-01-27T11:47:30Z

Tony Wyatt: More typos

A function is a program or group of statements that is executed whenever that function name is called in a particular context. A function may be part of an internal program, part of a library, or a separate external program. Functions are an important building block of modular programming because they allow you to construct large programs from a series of small, easily developed modules.

This chapter explains the different types of functions and how they are evaluated. It also provides an alphabetical reference of ARexx's built-in function library.

= Invoking a Function =

Within a ARexx program, a function is defined as a symbol or string followed immediately by an open parenthesis. The symbol or string (taken as a literal) specifies the function name, and the open parenthesis begins the argument list. Between the opening and closing parentheses are zero or more argument expressions, separated by commas, that supply the data being passed to the function.

Valid function calls are:

<syntaxhighlight>
CENTER ('title', 20)
ADDRESS()
'ALLOCMEM' (256*4,1)
</syntaxhighlight>

Each argument expression is evaluated in turn and the resulting strings are passed as the argument list to the function. Each argument expression, while often just a single literal value, can include arithmetic or string operations or even other function calls. Argument expressions are evaluated from left to right.

Functions can also be invoked using the CALL instruction. The CALL instruction, described in Chapter 4, can be used to invoke a function that may not return a value.

= Types of Functions =

There are three types of functions:

* Internal functions - defined within the ARexx program.
* Built-in functions - supplied by the ARexx programming language.
* Function Libraries - a special Amiga shared library.

== Internal Functions ==

An internal function is identified by a label within the program. When the internal function is called. ARexx creates a new storage environment so that the previous caller's environment is preserved. The new environment inherits the values from its predecessor, but subsequent changes to the environment variables do not affect the previous environment.

The specific values preserved are:

* The current and previous host addresses.
* The NUMERIC DIGITS, FUZZ, and FORM settings.
* The trace option, inhibit flag, and interactive flag.
* The state of the interrupt flags as defined by the SIGNAL instruction.
* The current prompt string as set by the OPTIONS PROMPT instruction.

The new environment does not automatically get a new symbol table, so initially all of the variables in the previous environment are available to the called function. The PROCEDURE instruction can be used to create a table and thereby protect the caller's symbol values. PROCEDURE can also be used to allow the same variable name to be used in two different areas with two different values.

Execution of the internal function proceeds until a RETURN instruction is executed. At this point the new environment is dismantled, and control resumes at the point of the function call. The expression supplied with the RETURN instruction is evaluated and passed back to the caller as the function result.

== Built-In Functions ==

ARexx provides a substantial library of predefined functions as part of the language system. These functions are always available and have been optimized to work with the internal data structures. In general, the built-in functions execute much faster than an equivalent interpreted function, so their usage is strongly recommended.

Several of the built-in functions create and manipulate external AmigaDOS files. Files are referenced by a logical name, a case-sensitive name that is assigned to a file when it is first opened. The initial input and output streams are given the names STDIN (standard input) and STDOUT (standard output). There is no theoretical limit to the number of files that may be open simultaneously, although a limit will be imposed by available memory. All open files are closed automatically when the program exits.

== External Function Libraries ==

A function library is a collection of one or more functions organized as an Amiga shared library. The library must reside in LIBS:, but may be either memory or disk-resident. Disk-resident libraries are loaded and opened as needed.

The library has to be especially tailored for use by ARexx. Each function library must contain a library name, a search priority, an entry point offset, and a version number. When ARexx is searching for a function, the interpreter opens each library and checks its "query" entry point. This entry point must be specified as an integer offset (e.g. "-30") from the library base. The return code from the query call indicates whether the desired function was found. If the function is found, it is called with the parameters passed by the interpreter, and the function result is returned to the caller. If it is not found, a "Function not found" error code is returned, and the search continues with the next library in the list. Function libraries are always closed after being checked so that the operating system can reclaim the memory space if required.

=== The Library List ===

The ARexx resident process maintains a list of the currently available function libraries and function hosts called the Library List. Application programs can add or remove function libraries as required.

The Library List is maintained as a priority-sorted queue. Each entry has an associated search priority in the range 100 (highest) to -100 (lowest). Entries can be added at an appropriate priority to control the function name resolution. Libraries with higher priorities are searched first. Within a given priority level, those libraries added first are searched first. The priority levels are significant if any of the libraries have duplicate function name definitions, since the function located further down the search chain could never be called.

== External Function Hosts ==

The name associated with a function host is the name of its public message port. Function calls are passed to the host as a message packet; it is then up to the individual host to determine whether the specified function name is one that it recognizes. The name resolution is completely internal to the host, so function hosts provide a natural gateway mechanism for implementing remote procedure calls to other machines in a network. The ARexx resident process is a function host and is installed in the Library List with a priority of -60.

= The Search Order =

Function linkages in ARexx are established at the time of the function call. A specific search order is followed until a function matching the name symbol or string is found. If the specified function cannot be located, an error is generated and the expression evaluation is terminated. The full search order is:

; Internal Functions
: The program source is examined for a label that matches the function name. If a match is found, a new storage environment is created and control is transferred to the label.

; Built-In Functions
: The built-in function library is searched for the specified name. All of these functions are defined by uppercase names.

; Function Libraries and Function Hosts
: The available function libraries and function hosts are maintained in the Library List, which is searched starting at the highest priority until the requested function is found or the end of the list is reached. Function hosts are called using a message-passing protocol similar to that used for commands and may be used as gateways for remote procedure calls to other machines in a network.

; External ARexx Programs
: The final search step is to check for an external ARexx program file by sending an invocation message to the ARexx resident process. The search always begins in the current directory and follows the same search path as the original ARexx program invocation. The name matching process is not case-sensitive.

The function name-matching procedure may be case-sensitive for some of the search steps, but not for others. The matching procedure used in a function library or function host is design dependent. Functions defined with mixed-case names must be called using a string token, since symbol names are always translated to uppercase.

The full search order is followed whenever the function name is defined by a symbol token. However, the search for internal functions is bypassed if the name is specified by a string token. This allows internal functions to usurp the names of external functions, as in the following example:

<syntaxhighlight>
CENTER: /*internal "CENTER"*/
ARG string, length /*get arguments*/
length = MIN(length,60) /*compute length*/
return 'CENTER' (string, length)
</syntaxhighlight>

Here the built-in function CENTER() has been replaced by an internal function after modifying the length argument.

= The Clip List =

The Clip List is a publicly accessible mechanism that can be used as a general clipboard for intertask communication. Many functions use the clipboard for retrieving different types of information, such as predefined constants or strings.

The Clip List maintains a set of (name, value) pairs that may be used for a variety of purposes. (SETCLIP() is used to add pairs to the list.) Each entry in the list consists of a name and a value string and may be located by name. In general, the names used should be chosen to be unique to an application to prevent unintended duplications with other programs. Any number of entries may be posted to the list.

One potential application for the Clip List is as a mechanism for loading predefined constants into an ARexx program. For example:

<syntaxhighlight>
pi=3.14159; e=2.718; sqrt2=1.414 . . .
</syntaxhighlight>

(i.e., a series of assignments separated by semicolons). In use, such a string could be retrieved by name using the built-in function GETCLIP() and then INTERPRETed within the program. The assignment statements within the string would then create the required constant definitions. For example:

<syntaxhighlight>
/*Assume a string called "numbers" is available*/
numbers = GETCLIP ('numbers')
INTERPRET numbers /*. . . assignments*/
</syntaxhighlight>

The strings would not be restricted to contain only assignment statements, but could include any valid ARexx statements. The Clip List could thus provide a series of programs for initializations or other processing tasks.

The resident process supports addition and deletion operations for maintaining the Clip List. The names in the (name,value) pairs are assumed to be in mixed case and are maintained to be unique in the list. An attempt to add a string with an existing name will simply update the value string. The name and value strings are copied when an entry is posted to the list, so the program that adds an entry is not required to maintain the strings.

Entries posted to the Clip List remain available until explicitly removed. The Clip List is automatically released when the resident process exits.

= Built-in Functions Reference =

This section provides an alphabetical list of the built-in functions. The syntax of each function is shown to the right of the function keyword.

== Syntax ==

Optional arguments are shown in brackets and generally have a default value that is used if the argument is omitted. When an option keyword is specified as an argument, only the first character is significant. Option keywords are not case-sensitive.

Many functions accept a pad character argument. Pad characters are inserted to fill or create spaces. For functions that accept a pad argument, only the first character of the argument string is significant. If a null string is supplied, the default padding character, usually a blank, will be used.

In the following examples, an arrow (->) is used as an abbreviation for "evaluates as." The arrow will not be displayed when a program is run. For example:

<syntaxhighlight>
SAY ABS (-5.35) -> 5.35
</syntaxhighlight>

This means that SAY ABS(-5.35) is evaluated as 5.35.

== Alphabetical Reference ==

=== ABBREV() ===

<nowiki>ABBREV(string1,string2[,length])</nowiki>

Returns a Boolean value that indicates whether string2 is an abbreviation of string1 with length greater than or equal to the specified length argument. The default length is 0, so the null string is an acceptable abbreviation. For example:

<syntaxhighlight>
SAY ABBREV ('fullname', 'ful') -> 1
SAY ABBREV ('almost', 'alm',4) -> 0
SAY ABBREV ('any','') -> 1
</syntaxhighlight>

=== ABS() ===

<nowiki>ABS(number)</nowiki>

Returns the absolute value of the number argument. This value must be numeric. For example:

<syntaxhighlight>
SAY ABS(-5.35) -> 5.35
SAY ABS(10) -> 10
</syntaxhighlight>

=== ADDLIB() ===

<nowiki>ADDLIB(name,priority[,offset,version])</nowiki>

Adds a function library or a function host to the library list maintained by the resident process. The name argument specifies either the name of a function library or the public message port associated with a function host. The name is case-sensitive. Any specified libraries should reside in the system LIBS: directory.

The priority argument specifies the search priority and must be an integer between 100 and -100, inclusive. The offset and version arguments apply only to libraries. The offset is the integer offset to the library's "query" entry point, and the version is an integer specifying the minimum acceptable release level of the library.

The function returns a Boolean result that indicates whether the operation was successful. If a library is specified, it is not actually opened at this time. Similarly, ARexx does not check to see whether a specified function host port is open. For example:

<syntaxhighlight>
SAY ADDLIB ("rexxsupport.library",0,-30,0) -> 1
CALL ADDLIB "EtherNet",-20 /*A gateway*/
</syntaxhighlight>

=== ADDRESS() ===

<nowiki>ADDRESS()</nowiki>

Returns the current host address string. The host address is the message port to which commands will be sent. The SHOW() function can be used to check whether the required external host is actually available. See also SHOW(). For example:

<syntaxhighlight>
SAY ADDRESS() -> REXX
</syntaxhighlight>

=== ARG() ===

<nowiki>ARG([number][,'EXISTS'|'OMITTED'])</nowiki>

ARG() returns the number of arguments supplied to the current environment. If only the number parameter is supplied, the corresponding argument string is returned. If a number and the Exists or Omitted keyword is given, the Boolean return indicates the status of the corresponding argument. The existence or omission test does not indicate whether the string has a null value, but only whether a string was supplied. For example:

<syntaxhighlight>
/*Assume arguments were: ('one',,10)*/
SAY ARG() -> 3
SAY ARG(1) -> one
SAY ARG(2,'O') -> 1
</syntaxhighlight>

=== B2C() ===

<nowiki>B2C(string)</nowiki>

Converts a string of binary digits (0,1) into the corresponding (packed) character representation. The conversion is the same as though the argument string had been specified as a literal binary string (e.g. '1010'B). Blanks are permitted in the string, but only at byte boundaries. This function is particularly useful for creating strings that are to be used as bit masks. See also X2C(). For example:

<syntaxhighlight>
SAY B2C('00110011') -> 3
SAY B2C('01100001') -> a
</syntaxhighlight>

=== BITAND() ===

<nowiki>BITAND(string1,string2[,pad])</nowiki>

The argument strings are logically ANDed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITAND('0313'x, 'FFF0'x) -> '0310'x
</syntaxhighlight>

=== BITCHG() ===

<nowiki>BITCHG(string,bit)</nowiki>

Changes the state of the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITCHG('0313'x,4) -> '0303'x
</syntaxhighlight>

=== BITCLR() ===

<nowiki>BITCLR(string,bit)</nowiki>

Clears (sets to zero) the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITCLR('0313'x,4) -> '0303'x
</syntaxhighlight>

=== BITCOMP() ===

<nowiki>BITCOMP(string1,string2[,pad])</nowiki>

Compares the argument strings bit-by-bit, starting at bit number 0. The returned value is the bit number of the first bit in which the strings differ, or -1 if the strings are identical. For example:

<syntaxhighlight>
BITCOMP('7F'x, 'FF'x) -> 7 /*Seventh bit*/
BITCOMP('FF'x, 'FF'x) -> -1
</syntaxhighlight>

=== BITOR() ===

<nowiki>BITOR(string1,string2[,pad])</nowiki>

The argument strings are logically ORed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITOR('0313'x, '00F'x) -> '033F'x
</syntaxhighlight>

=== BITSET() ===

<nowiki>BITSET(string,bit)</nowiki>

Sets the specified bit in the argument string to 1. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITSET('313'x,2) -> '0317'x
</syntaxhighlight>

=== BITTST() ===

<nowiki>BITTST(string,bit)</nowiki>

The Boolean return indicates the state of the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITTST('0313=x,4) -> 1
</syntaxhighlight>

=== BITXOR() ===

<nowiki>BITXOR(string1,string2[,pad])</nowiki>

The argument strings are logically and exclusively-ORed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITXOR('0313'x, '001F'x) -> '030C'X
</syntaxhighlight>

=== C2B() ===

<nowiki>C2B(string)</nowiki>

Converts the character string into the equivalent string of binary digits. See also C2X(). For example:

<syntaxhighlight>
SAY C2B('abc') -> 011000010110001001100011
</syntaxhighlight>

=== C2D() ===

<nowiki>C2D(string[,n])</nowiki>

Converts the string argument from its character representation to the corresponding decimal number, expressed as ASCII digits (0-9). If n is supplied, the character string is considered to be a number expressed in n bytes. The string is truncated or padded with nulls on the left as required, and the sign bit is extended for the conversion. For example:

<syntaxhighlight>
SAY C2D('0020'x) -> 32
SAY C2D('FFFF ffff'x) -> -1
SAY C2D('FF0100'x,2) -> 256
</syntaxhighlight>

=== C2X() ===

<nowiki>C2X(string)</nowiki>

Converts the string argument from its character representation to the corresponding hexadecimal number, expressed as the ASCII characters 0-9 and A-F. See also C2B(). For example:

<syntaxhighlight>
SAY C2X('abc') -> 616263
</syntaxhighlight>

=== CENTER()/CENTRE() ===

<nowiki>CENTER(string,length[,pad])</nowiki>
<nowiki>CENTRE(string,length[,pad])</nowiki>

Centers the string argument in a string with the specified length. If the length is longer than that of the string, pad characters or blanks are added as necessary. For example:

<syntaxhighlight>
SAY CENTER('abc',6) -> ' abc '
SAY CENTER('abc',6,'+') -> '+abc++'
SAY CENTER ('123456',3) -> '234'
</syntaxhighlight>

=== CLOSE() ===

<nowiki>CLOSE(file)</nowiki>

Closes the file specified by the given logical name. The returned value is a Boolean success flag and will be 1 unless the specified file was not open. For example:

<syntaxhighlight>
SAY CLOSE('input') -> 1
</syntaxhighlight>

=== COMPARE() ===

<nowiki>COMPARE(string1,string2[,pad])</nowiki>

Compares two strings and returns the index of the first position in which they differ or 0 if the strings are identical. The shorter string is padded as required using the supplied character or blanks. For example:

<syntaxhighlight>
SAY COMPARE('abcde', 'abcce') -> 4
SAY COMPARE('abcde', 'abcde') -> 0
SAY COMPARE('abc++', 'abc+-', '+') -> 5
</syntaxhighlight>

=== COMPRESS() ===

<nowiki>COMPRESS(string[,list])</nowiki>

If the list argument is omitted, the function removes leading, trailing or embedded blank characters from the string argument. If the optional list is supplied, it specifies the characters to be removed from the string. For example:

<syntaxhighlight>
SAY COMPRESS(' why not ') -> whynot
SAY COMPRESS('++12-34-+', '+-') -> 1234
</syntaxhighlight>

=== COPIES() ===

<nowiki>COPIES(string,number)</nowiki>

Creates a new string by concatenating the specified number of copies of the original. The number argument may be zero, in which case the null string is returned. For example:

<syntaxhighlight>
SAY COPIES('abc',3) -> abcabcabc
</syntaxhighlight>

=== D2C() ===

<nowiki>D2C(number)</nowiki>

Creates a string whose value is the binary (packed) representation of the given decimal number. For example:

<syntaxhighlight>
D2C(65) -> A
</syntaxhighlight>

=== D2X() ===

<nowiki>D2X(number[,digits])</nowiki>

Converts a decimal number to hexadecimal. For example:

<syntaxhighlight>
D2X(31) -> 1F
</syntaxhighlight>

=== DATATYPE() ===

<nowiki>DATATYPE(string[,option])</nowiki>

If only the string argument is specified, DATATYPE() tests whether the string parameter is a valid number and returns either NUM or CHAR. If an option keyword is given, the Boolean return indicates whether the string satisfied the requested test. The following option keywords are recognized:

; ALPHANUMERIC
: Accepts alphabetic (A-Z, a-z) or numeric (0-9) characters

; BINARY
: Accepts a binary digits string

; LOWERCASE
: Accepts lower case alphabetic (a-z) characters

; MIXED
: Accepts mixed upper/lower case characters

; NUMERIC
: Accepts valid numbers

; SYMBOL
: Accepts valid REXX symbols

; UPPER
: Accepts upper case alphabetic (A-Z) characters

; WHOLE
: Accepts integer numbers

; X
: Accepts Hex digit strings

For example:

<syntaxhighlight>
SAY DATATYPE('123') -> NUM
SAY DATATYPE('1a f2', 'X') -> 1
SAY DATATYPE('aBcde', 'L') -> 0
</syntaxhighlight>

=== DATE() ===

<nowiki>DATE([option][,date][format])</nowiki>

Returns the current date in the specified format. The default ('NORMAL') option returns the date in the form DD MMM YYYY, as in 20 APR 1988. The options recognized are:

; BASEDATE
: The number of days since January 1, 0001

; CENTURY
: The number of days since January 1 of the century

; DAYS
: The number of days since January 1 of the current year

; EUROPEAN
: The date in the form DD/MM/YY

; INTERNAL
: Internal system days

; JULIAN
: The date in the form YYDDD

; MONTH
: The current month (in mixed case)

; NORMAL
: The date in the form DD MMM YYYY

; ORDERED
: The date in the form YY/MM/DD

; SORTED
: The date in the form YYYYMMDD

; USA
: The date in the form MM/DD/YY

; WEEKDAY
: The day of the week (in mixed case)

These options can be shortened to just the first character.

The DATE() function also accepts optional second and third arguments to supply the date either in the form of internal system days or in the 'sorted' form YYYYMMDD. The second argument is specifying either system days (the default) or a sorted date. The third argument specifies the form of the date and can be either 'I' or 'S'. The current date in system days can be retrieved using DATE('INTERNAL'). For example:

<syntaxhighlight>
SAY DATE() -> 14 Jul 1992
SAY DATE('M') -> July
SAY DATE(S) -> 19920714
SAY DATE('S' ,DATE('I')+21) -> 19920804
SAY DATE('W' ,19890609, 'S') -> Friday
</syntaxhighlight>

=== DELSTR() ===

<nowiki>DELSTR(string,n[,length])</nowiki>

Deletes the substring of the string argument beginning with the nth character for the specified length in characters. The default length is the remaining length of the string. For example:

<syntaxhighlight>
SAY DELSTR('123456',2,3) -> 156
</syntaxhighlight>

=== DELWORD() ===

<nowiki>DELWORD(string,n[,length])</nowiki>

Deletes the substring of the string argument beginning with the nth word for the specified length in words. The default length is the remaining length of the string. The deleted string includes any trailing blanks following the last word. For example:

<syntaxhighlight>
SAY DELWORD('Tell me a story',2,2) -> 'Tell story'
SAY DELWORD('one two three',3) -> 'one two '
</syntaxhighlight>

=== DIGITS() ===

<nowiki>DIGITS()</nowiki>

Returns the current Numeric Digits setting. For example:

<syntaxhighlight>
NUMERIC DIGITS 6
SAY DIGITS() -> 6
</syntaxhighlight>

=== EOF() ===

<nowiki>EOF(file)</nowiki>

Checks the specified logical file name and returns the Boolean value 1 (True), if the end-of-file has been reached, and 0 (False) otherwise. For example:

<syntaxhighlight>
SAY EOF(infile) -> 1
</syntaxhighlight>

=== ERRORTEXT() ===

<nowiki>ERRORTEXT(n)</nowiki>

Returns the error message associated with the specified ARexx error code. The null string is returned if the number is not a valid error code. For example:

<syntaxhighlight>
SAY ERRORTEXT(41) -> Invalid expression
</syntaxhighlight>

=== EXISTS() ===

<nowiki>EXISTS(filename)</nowiki>

Tests whether an external file of the given filename exists. The name string may include device and directory specifications. For example:

<syntaxhighlight>
SAY EXISTS('SYS:C/ED') -> 1
</syntaxhighlight>

=== EXPORT() ===

<nowiki>EXPORT(address[,string][,length][,pad])</nowiki>

Copies data from the optional string into a previously-allocated memory area. This memory area must be specified as a four-byte address. The length parameter specifies the maximum number of characters to be copied. The default is the length of the string. If the specified length is longer than the string, the remaining area is filled with the pad character or nulls ('00'x). The returned value is the number of characters copied.

{{Note|title=Caution|text=Any area of memory can be overwritten, possibly causing a system crash. Task switching is forbidden while the copy is being done, so system performance may be degraded if long strings are copied.}}

See also IMPORT() and STORAGE(). For example:

<syntaxhighlight>
count = EXPORT('0004 0000'x, 'The answer')
</syntaxhighlight>

=== FIND() ===

<nowiki>FIND(string,phrase)</nowiki>

The FIND() function locates a phrase of words in a larger string of words and returns the word number of the matched position. For example:

<syntaxhighlight>
SAY FIND('Now is the time', 'is the') -> 2
</syntaxhighlight>

=== FORM() ===

<nowiki>FORM()</nowiki>

Returns the current NUMERIC FORM setting. For example:

<syntaxhighlight>
NUMERIC FORM SCIENTIFIC
SAY FORM() -> SCIENTIFIC
</syntaxhighlight>

=== FREESPACE() ===

<nowiki>FREESPACE(address,length)</nowiki>

Returns a block of memory of a given length to the interpreter's internal pool. The address argument must be a 4 byte string obtained by a prior call to GETSPACE(), the internal allocator. It is not always necessary to release internally allocated memory, since it will be released to the system when the program terminates. However, if a very large block has been allocated, returning it to the pool may avoid memory space problems. The return value is a Boolean success flag. See also GETSPACE().

Calling FREESPACE() with no arguments will return the amount of memory available in the interpreter's internal pool. For example:

<syntaxhighlight>
FREESPACE('00042000'x,32) -> 1
</syntaxhighlight>

=== FUZZ() ===

<nowiki>FUZZ()</nowiki>

Returns the current NUMERIC FUZZ setting. For example:

<syntaxhighlight>
NUMERIC FUZZ 3
SAY FUZZ() -> 3
</syntaxhighlight>

=== GETCLIP() ===

<nowiki>GETCLIP(name)</nowiki>

Searches the Clip List for an entry matching the supplied name parameter and returns the associated value string. The name matching is case-sensitive. The null string is returned if the name cannot be found. See also SETCLIP(). For example:

<syntaxhighlight>
/*Assume 'numbers' contains 'PI=3.14159'*/
SAY GETCLIP('numbers') -> PI=3.14159
</syntaxhighlight>

=== GETSPACE() ===

<nowiki>GETSPACE(length)</nowiki>

Allocates a block of memory of the specified length from the interpreter's internal pool. The returned value is the four-byte address of the allocated block, which is not cleared or otherwise initialized. Internal memory is automatically returned to the system when the ARexx program terminates, so this function should not be used to allocate memory for use by external programs. The REXXSupport.Library includes the function ALLOCMEM(), which allocates memory from the system free list. See also FREESPACE(). For example:

<syntaxhighlight>
SAY C2X (GETSPACE(32)) -> '0003BF40'x
</syntaxhighlight>

=== HASH() ===

<nowiki>HASH(string)</nowiki>

Returns the hash attribute of a string as a decimal number and updates the internal hash value of the string. For example:

<syntaxhighlight>
SAY HASH('1') -> 49
</syntaxhighlight>

=== IMPORT() ===

<nowiki>IMPORT(address[,length])</nowiki>

Creates a string by copying data from the specified four-byte address. If the length parameter is not supplied, the copy terminates when a null byte is found. See also EXPORT(). For example:

<syntaxhighlight>
extval = IMPORT('0004 0000'x,8)
</syntaxhighlight>

=== INDEX() ===

<nowiki>INDEX(string,pattern[,start])</nowiki>

Searches for the first occurrence of the pattern argument in the string argument, beginning at the specified start position. The default start position is 1. The returned value is the index of the matched pattern or 0 if the pattern was not found. For example:

<syntaxhighlight>
SAY INDEX("123456", "23") -> 2
SAY INDEX("123456", "77") -> 0
SAY INDEX("123123", "23",3) -> 5
</syntaxhighlight>

=== INSERT() ===

<nowiki>INSERT(new,old[,start][,length][,pad])</nowiki>

Inserts the new string into the old string after the specified start position. The default starting position is 0. The new string is truncated or padded to the specified length as required, using the supplied pad character or blanks. If the start position is beyond the end of the string, the old string is padded on the right. For example:

<syntaxhighlight>
SAY INSERT('ab', '12345') -> ab12345
SAY INSERT('123', '++',3,5, '-') -> ++-123--
</syntaxhighlight>

=== LASTPOS() ===

<nowiki>LASTPOS(pattern,string[,start])</nowiki>

Searches backwards for the first occurrence of the pattern argument in the string argument, beginning at the specified start position. The default starting position is the end of the string. The returned value is the index of the matched pattern or 0 if the pattern was not found. For example:

<syntaxhighlight>
SAY LASTPOS('2', '1234') -> 2
SAY LASTPOS('2', '1234234') -> 5
SAY LASTPOS('2', '123234',3) -> 2
SAY LASTPOS('2', '13579') -> 0
</syntaxhighlight>

=== LEFT() ===

<nowiki>LEFT(string,length[,pad])</nowiki>

Returns the leftmost substring in the given string argument with the specified length. If the substring is shorter than the requested length, it is padded on the right with the supplied pad character or blanks. For example:

<syntaxhighlight>
SAY LEFT('123456',3) -> 123
SAY LEFT('123456',8, '+') -> 123456++
</syntaxhighlight>

=== LENGTH() ===

<nowiki>LENGTH(string)</nowiki>

Returns the length of the string. For example:

<syntaxhighlight>
SAY LENGTH('three') -> 5
</syntaxhighlight>

=== LINES() ===

<nowiki>LINES(file)</nowiki>

Returns the number of lines queued or typed ahead at the logical file, which must refer to an interactive stream. The line count is obtained as the secondary result of a WaitForChar() call. For example:

<syntaxhighlight>
PUSH 'a line'
PUSH 'another one'
SAY LINES(STDIN) -> 2
</syntaxhighlight>

=== MAX() ===

<nowiki>MAX(number,number[,number,...])</nowiki>

Returns the maximum of the supplied arguments, all of which must be numeric. At least two parameters must be supplied. For example:

<syntaxhighlight>
SAY MAX(2.1,3,-1) -> 3
</syntaxhighlight>

=== MIN() ===

<nowiki>MIN(number,number[,number,...])</nowiki>

Returns the minimum of the supplied arguments, all of which must be numeric. At least two parameters must be supplied. For example:

<syntaxhighlight>
SAY MIN(2.1,3,-1) -> -1
</syntaxhighlight>

=== OPEN() ===

<nowiki>OPEN(file,filename[,'APPEND'|'READ'|'WRITE'])</nowiki>

Opens an external file for the specified operation. The file argument defines the logical name by which the file will be referenced. The filename is the external name of the file and may include device and directory specifications. The function returns a Boolean value that indicates whether the operation was successful. There is no limit to the number of files that can be open simultaneously, and all open files are closed automatically when the program exits. See also CLOSE(), READ(), and WRITE(). For example:

<syntaxhighlight>
SAY OPEN('MyCon', 'CON:160/50/320/100/MyCON/cds') P-> 1
SAY OPEN('outfile', 'ram:temp', 'W') -> 1
</syntaxhighlight>

=== OVERLAY() ===

<nowiki>OVERLAY(new,old[,start][,length][,pad])</nowiki>

Overlays the new string onto the old string beginning at the specified start position, which must be positive. The default starting position is 1. The new string is truncated or padded to the specified length as required, using the supplied pad character or blanks. If the start position is beyond the end of the old string, the old string is padded on the right. For example:

<syntaxhighlight>
SAY OVERLAY('bb', 'abcd') -> bbcd
SAY OVERLAY('4', '123',5,5, '-') -> 123-4----
</syntaxhighlight>

=== POS() ===

<nowiki>POS(pattern,string[,start])</nowiki>

Searches for the first occurrence of the pattern argument in the string argument, beginning at the position specified by the start argument. The default starting position is 1. The value is the index of the matched string or 0 if the pattern wasn't found. For example:

<syntaxhighlight>
SAY POS('23', '123234') -> 2
SAY POS('77', '123234') -> 0
SAY POS('23', '123234',3) -> 4
</syntaxhighlight>

=== PRAGMA() ===

<nowiki>PRAGMA(option[,value])</nowiki>

This function allows a program to change various attributes relating to the system environment within which the program executes. The option argument is a keyword that specifies an environmental attribute. The value argument supplies the new attribute value to be installed. The value returned by the function depends on the attribute selected. Some attributes return the previous value installed, while others may simply set a Boolean success flag.

The currently defined option keywords are:

; DIRECTORY
: Specifies a new current directory. The current directory is used as the root for filenames that do not explicitly include a device specification. The return is the old directory name. PRAGMA('D') is equivalent to PRAGMA('D',"). It returns the path of the current directory without changing the directory.

; PRIORITY
: Specifies a new task priority. The priority value must be an integer in the range - 128 to 127, but the practical range is much more limited. ARexx programs should never be run at a priority higher than that of the resident process, which currently runs at a priority of 4. The returned value is the previous priority level.

; ID
: Returns the task ID (the address of the task block) as an 8-character hex string. The task ID is a unique identifier of the particular ARexx invocation and may be used to create a unique name for it.

; STACK
: Specifies a new stack value for your current ARexx program. When a new stack value is declared, the previous stack value is returned.

The currently implemented options are:

; PRAGMA('W',{'NULL'|' WORKBENCH'})
: Controls the task's WindowPtr field. Setting it to 'NULL' will suppress any requesters that might otherwise be generated by a DOS call.

; PRAGMA('*'[,name])
: Defines the specified logical name as the current ("*") console handler, allowing the user to open two streams on one window. If the name is omitted, the console handler is set to that of the client's process.

<syntaxhighlight>
SAY PRAGMA('D', 'DF0:C') -> Extras
SAY PRAGMA('D', 'DF1:C') -> Workbench:C
SAY PRAGMA('PRIORITY', -5) -> 0
SAY PRAGMA('ID') -> 00221ABC
CALL PRAGMA '*',STDOUT
SAY PRAGMA("STACK",8092) -> 4000
</syntaxhighlight>

=== RANDOM() ===

<nowiki>RANDOM([MIN][,MAX][,seed])</nowiki>

Returns a pseudo-random integer in the interval specified by the min and max arguments. The default minimum value is 0 and the default maximum value is 999. The interval max-min must be less than or equal to 1000. If a greater range of random integers is required, the values from the RANDU() function can be suitably scaled and translated. The seed argument can be supplied to initialize the internal state of the random number generator. See also RANDU(). For example:

<syntaxhighlight>
thisroll = RANDOM(1,6) /*Might be 1*/
nextroll = RANDOM(1,6) /*Might be snake eyes*/
</syntaxhighlight>

=== RANDU() ===

<nowiki>RANDU([seed])</nowiki>

Returns a uniformly-distributed, pseudo-random number between 0 and 1. The number of digits of precision in the result is always equal to the current Numeric Digits setting. With the choice of suitable scaling and translation values, RANDU() can be used to generate pseudo-random numbers on an arbitrary interval.

The optional integer seed argument is used to initialize the internal state of the random number generator. See also RANDOM(). For example:

<syntaxhighlight>
firsttry = RANDU() /*0.371902021?*/
NUMERIC DIGITS 3
tryagain = RANDU () /*0.873?*/
</syntaxhighlight>

=== READCH() ===

<nowiki>READCH(file,length)</nowiki>

Reads the specified number of characters from the given logical file into a string. The length of the returned string is the actual number of characters read and may be less than the requested length if, for example, the end-of-file was reached. See also READLN(). For example:

<syntaxhighlight>
instring = READCH('input',10)
</syntaxhighlight>

=== READLN() ===

<nowiki>READLN(file)</nowiki>

Reads characters from the given logical file into a string until a newline character is found. The returned string does not include the newline. See also READCH(). For example:

<syntaxhighlight>
instring = READLN('MyFile')
</syntaxhighlight>

=== REMLIB() ===

<nowiki>REMLIB(name)</nowiki>

Removes an entry with the given name from the Library List maintained by the resident process. The Boolean return is 1 if the entry was found and successfully removed. This function does not make a distinction between function libraries and function hosts, but simply removes a named entry. See also ADDLIB(). For example:

<syntaxhighlight>
SAY REMLIB('MyLibrary.library') -> 1
</syntaxhighlight>

=== REVERSE() ===

<nowiki>REVERSE(string)</nowiki>

Reverses the sequence of characters in the string. For example:

<syntaxhighlight>
SAY REVERSE('?ton yhw') -> why not?
</syntaxhighlight>

=== RIGHT() ===

<nowiki>RIGHT(string,length[,pad])</nowiki>

Returns the rightmost substring in the given string argument with the specified length. If the substring is shorter than the requested length, it is padded on the left with the supplied pad character or blanks. For example:

<syntaxhighlight>
SAY RIGHT('123456',4) -> 3456
SAY RIGHT('123456',8, '+') -> ++123456
</syntaxhighlight>

=== SEEK() ===

<nowiki>SEEK(file,offset[,'BEHIN'|'CURRENT'|'END'])</nowiki>

Moves to a new position in the given logical file, specified as an offset from an anchor position. The default anchor is Current. The returned value is the new position relative to the start of the file. For example:

<syntaxhighlight>
SAY SEEK('input',10,'B') -> 10
SAY SEEK('input',0,E') -> 356 /*file length*/
</syntaxhighlight>

=== SETCLIP() ===

<nowiki>SETCLIP(name[,value])</nowiki>

Adds a name-value pair to the Clip List maintained by the resident process. If an entry of the same name already exists, its value is updated to the supplied value string. Entries may be removed by specifying a null value. The function returns a Boolean value that indicates whether the operation was successful. For example:

<syntaxhighlight>
SAY SETCLIP('path', 'DF0:s') -> 1
SAY SETCLIP('path') -> 1
</syntaxhighlight>

=== SHOW() ===

<nowiki>SHOW(option[,name][,pad])</nowiki>

Returns the names in the resource list specified by the option argument, or tests to see whether an entry with the specified name is available. The currently implemented options keywords are:

; CLIP
: Examines the names in the Clip List

; FILES
: Examines the currently open logical file names

; LIBRARIES
: Examines the names in the Library List, which are either function libraries or function hosts.

; PORTS
: Examines the names in the system Ports List

If the name argument is omitted, the function returns a string with the resource names separated by a blank space or the pad character, if one was supplied. If the name argument is given, the returned Boolean value indicates whether the name was found in the resource list. The name entries are case-sensitive.

=== SIGN() ===

<nowiki>SIGN(number)</nowiki>

Returns 1 if the number argument is positive or zero and -1 if the number is negative. The argument must be numeric. For example:

<syntaxhighlight>
SAY SIGN(12) -> 1
SAY SIGN(-33) -> -1
</syntaxhighlight>

=== SOURCELINE() ===

<nowiki>SOURCELINE([line])</nowiki>

Returns the text for the specified line of the currently executing ARexx program. If the line argument is omitted, the function returns the total number of lines in the file. This function is often used to embed "help" information in a program. For example:

<syntaxhighlight>
/*A simple test program*/
SAY SOURCELINE() -> 3
SAY SOURCELINE(1)-> /*A simple test program*/
</syntaxhighlight>

=== SPACE() ===

<nowiki>SPACE(string,n[,pad])</nowiki>

Reformats the string argument so that there are n spaces (blank characters) between each pair of words. If the pad character is specified, it is used instead of blanks as the separator character. Specifying n as 0 will remove all blanks from the string. For example:

<syntaxhighlight>
SAY SPACE('Now is the time',3) -> 'Now is the time'
SAY SPACE('Now is the time',0) -> 'Nowisthetime'
SAY SPACE('1 2 3',1, '+') -> '1+2+3'
</syntaxhighlight>

=== STORAGE() ===

<nowiki>STORAGE([address][,string][,length][,pad])</nowiki>

STORAGE() with no arguments returns the available system memory. If the address argument is given, it must be a four-byte string. The function copies data from the (optional) string to the indicated memory address. The length parameter specifies the maximum number of bytes to be copied and defaults to the length of the string. If the specified length is longer than the string, the remaining area is filled with the pad character or nulls ('00'x).

The returned value is the previous contents of the memory area. This can be used in a subsequent call to restore the original contents. See also EXPORT().

{{Note|title=Caution|text=Any area of memory can be overwritten, possibly causing a system crash. Task switching is forbidden while the copy is being done, so system performance may be degraded if long strings are copied.}}

For example:

<syntaxhighlight>
SAY STORAGE() -> ' 248400
oldval = STORAGE('0004 0000'x, 'The answer')
CALL STORAGE '0004 0000'x,,32, '+'
</syntaxhighlight>

=== STRIP() ===

<nowiki>STRIP(string[,{'B' | 'L' | 'T'}][,pad])</nowiki>

If neither of the optional parameters is supplied, the function removes both leading and trailing blanks from the string argument. The second argument specifies whether Leading, Trailing or Both (leading and trailing) characters are to be removed. The optional pad (or unpad) argument selects the character to be removed. For example:

<syntaxhighlight>
SAY STRIP(' say what? ') -> 'say What?'
SAY STRIP(' say what? ','L') -> 'say what?
SAY STRIP('++123+++', 'B', '+') -> '123'
</syntaxhighlight>

=== SUBSTR() ===

<nowiki>SUBSTR(string,start[,length][,pad])</nowiki>

Returns the substring of the string argument beginning at the specified start position for the specified length. The starting position must be positive, and the default length is the remaining length of the string. If the substring is shorter than the requested length, it is padded on the right with the blanks or the specified pad character. For example:

<syntaxhighlight>
SAY SUBSTR('123456',4,2) -> 45
SAY SUBSTR('myname',3,6, '=') -> 'name=='
</syntaxhighlight>

=== SUBWORD() ===

<nowiki>SUBWORD(string,n[,length])</nowiki>

Returns the substring of the string argument beginning with the nth word for the specified length in words. The default length is the remaining length of the string. The returned string will never have leading or trailing blanks. For example:

<syntaxhighlight>
SAY SUBWORD('Now is the time ',2,2) -> 'is the'
</syntaxhighlight>

=== SYMBOL() ===

<nowiki>SYMBOL(name)</nowiki>

Tests whether the name argument is a valid ARexx symbol. If the name is not a valid symbol, the function returns the string BAD. If the symbol is uninitialized, the returned string is LIT. If the symbol has been assigned a value, VAR is returned. For example:

<syntaxhighlight>
SAY SYMBOL('J') -> VAR
SAY SYMBOL('x') -> LIT
SAY SYMBOL('++') -> BAD
</syntaxhighlight>

=== TIME() ===

<nowiki>TIME(option)</nowiki>

Returns the current system time or controls the internal elapsed time counter. The valid option keywords are:

; CIVIL
: Current time in 12 hour format (a.m./p.m.) hours/minutes

; ELAPSED
: Elapsed time in seconds since program start

; HOURS
: Current time in hours since midnight

; MINUTES
: Current time in minutes since midnight

; NORMAL
: Current time in 24 hour format (hours/minutes/seconds)

; RESET
: Reset the elapsed time clock

; SECONDS
: Current time in seconds since midnight

If no option is specified, the function returns the current system time in the form HH:MM:SS. For example:

<syntaxhighlight>
/*Suppose that the time is 1:02 AM . . .*/
SAY TIME('C'( -> 1:02 AM
SAY TIME('HOURS') -> 1
SAY TIME('M') -> 62
SAY TIME('N') -> 01:02:54
SAY TIME('S') -> 3720
call TIME('R') /*reset timer*/
SAY TIME('E') -> .020
SAY TIME() -> 01:02:00
</syntaxhighlight>

=== TRACE() ===

<nowiki>TRACE(option)</nowiki>

Sets the tracing mode (see Chapter 6) to that specified by the option keyword, which must be one of the valid alphabetic or prefix options. The TRACE() function will alter the tracing mode even during interactive tracing, when TRACE instructions in the source program are ignored. The returned value is the mode in effect before the function call. This allows the previous trace mode to be restored later. For example:

<syntaxhighlight>
/*Assume tracing mode is ?ALL*/
SAY TRACE('Results') -> ?A
</syntaxhighlight>

=== TRANSLATE() ===

<nowiki>TRANSLATE(string[,output][,input][,pad])</nowiki>

This function constructs a translation table and uses it to replace selected characters in the argument string. If only the string argument is given, it is translated to upper case. If an input table is supplied, it modifies the translation table so that characters in the argument string that occur in the input table are replaced with the corresponding character in the output table. Characters beyond the end of the output table are replaced with the specified pad character or a blank. The result string is always of the same length as the original string. The input and output tables may be of any length. For example:

<syntaxhighlight>
SAY TRANSLATE("abcde", "123", "cbade", "+") -> 321++
SAY TRANSLATE("low") -> LOW
SAY TRANSLATE("0110", "10", "01") -> 1001
</syntaxhighlight>

=== TRIM() ===

<nowiki>TRIM(string)</nowiki>

Removes trailing blanks from the string argument. For example:

<syntaxhighlight>
SAY length (TRIM(' abc ')) -> 4
</syntaxhighlight>

=== TRUNC() ===

<nowiki>TRUNC(number[,places])</nowiki>

Returns the integer part of the number argument followed by the specified number of decimal places. The default number of decimal places is 0. The number is padded with zeroes as necessary. For example:

<syntaxhighlight>
SAY TRUNC(123.456) -> 123
SAY TRUNC(123.456,4) -> 123.4560
</syntaxhighlight>

=== UPPER() ===

<nowiki>UPPER(string)</nowiki>

Translate the string to upper case. The action of this function is equivalent to that of TRANSLATE(string), but it is slightly faster for short strings. For example:

<syntaxhighlight>
SAY UPPER('One Fine Day') -> ONE FINE DAY
</syntaxhighlight>

=== VALUE() ===

<nowiki>VALUE(name)</nowiki>

Returns the value of the symbol represented by the name argument. For example:

<syntaxhighlight>
/*Assume that J has the value 12*/
SAY VALUE('j') -> 12
</syntaxhighlight>

=== VERIFY() ===

<nowiki>VERIFY(string,list[,'MATCH'])</nowiki>

Returns the index of the first character in the string argument which is not contained in the list argument or 0 if all of the characters are in the list. If the MATCH keyword is supplied, the function returns the index of the first character which is in the list or 0 if none of the characters is in the list. For example:

<syntaxhighlight>
SAY VERIFY('123456', '0123456789') -> 0
SAY VERIFY('123a56', '0123456789') -> 4
SAY VERIFY('123a45', 'abcdefghij', 'm') -> 4
</syntaxhighlight>

=== WORD() ===

<nowiki>WORD(string,n)</nowiki>

Returns the nth word in the string argument or the null string if there are fewer than n words. For example:

<syntaxhighlight>
SAY WORD('Now is the time ',2) -> is
</syntaxhighlight>

=== WORDINDEX() ===

<nowiki>WORDINDEX(string,n)</nowiki>

Returns the starting position of the nth word in the argument string or 0 if there are fewer than n words. For example:

<syntaxhighlight>
SAY WORDINDEX('Now is the time ',3) -> 8
</syntaxhighlight>

=== WORDLENGTH() ===

<nowiki>WORDLENGTH(string,n)</nowiki>

Returns the length of the nth word in the string argument. For example:

<syntaxhighlight>
SAY WORDLENGTH('one two three',3) -> 5
</syntaxhighlight>

=== WORDS() ===

<nowiki>WORDS(string)</nowiki>

Returns the number of words in the string argument. For example:

<syntaxhighlight>
SAY WORDS("You don't SAY!") -> 3
</syntaxhighlight>

=== WRITECH() ===

<nowiki>WRITECH(file,string)</nowiki>

Writes the string argument to the given logical file. The returned value is the actual number of characters written. For example:

<syntaxhighlight>
SAY WRITECH('output', 'Testing') -> 7
</syntaxhighlight>

=== WRITELN() ===

<nowiki>WRITELN(file,string)</nowiki>

Writes the string argument to the given logical file with a newline appended. The returned value is the actual number of characters written. For example:

<syntaxhighlight>
SAY WRITELN('output', 'Testing') -> 8
</syntaxhighlight>

=== X2C() ===

<nowiki>X2C(string)</nowiki>

Converts a string of hex digits into the (packed) character representation. Blank characters are permitted in the argument string at byte boundaries. For example:

<syntaxhighlight>
SAY X2C('12ab') -> '12ab'x
SAY X2C('12 ab') -> '12ab'x
SAY X2C(61) -> a
</syntaxhighlight>

=== X2D() ===

<nowiki>X2D(hex,digits)</nowiki>

Converts a hexadecimal number to decimal. For example:

<syntaxhighlight>
SAY X2D('1f') -> 31
</syntaxhighlight>

=== XRANGE() ===

<nowiki>XRANGE([start][,end])</nowiki>

Generates a string consisting of all characters numerically between the specified start and end values. The default start character is '00'x, and the default end character is 'FF'x. Only the first character of the start and end arguments is significant. For example:

<syntaxhighlight>
SAY XRANGE() -> '00010203 . . . FDFEFF'x
SAY XRANGE('a', 'f') -> 'abcdef'
SAY XRANGE(,'0A'x) -> '000102030405060708090A'x
</syntaxhighlight>

== Example Program ==

The following example program illustrates many of the built-in functions that manipulate character strings.

=== Program 13. Changestrings.rexx ===

<syntaxhighlight>
/*This ARexx program shows the effect of built-in functions that change strings. The functions come in two groups: one that manipulates individual characters and one that manipulates whole strings.*/

teststring1 = " every good boy does fine "

/*The first group is composed of the functions STRIP(), COMPRESS(), SPACE(), TRIM(), TRANSLATE(), DELSTR(), DELWORD(), INSERT(), OVERLAY(), and REVERSE().*/

/*STRIP() removes only leading and trailing characters.*/

/*Print the original string, for comparison. We put a period at the end of the string, so you can see what happens to the spaces at the end of the string.*/
SAY " every good boy does fine "

/*The same string stripped of leading and trailing spaces*/
SAY STRIP(" every good boy does fine ")"."

/*Failed attempt to remove leading and trailing "e"s*/
SAY STRIP(" every good boy does fine",,"e")"."

/*The "e"'s were protected by the leading and trailing spaces. Removing them exposes the "e"'s to the effects of STRIP()*/
SAY STRIP("every good boy does fine",,"e")"."

/*Remove "e"'s and spaces from the original string*/
SAY STRIP(" every good boy does fine ",," e")"."

/*We are now using the variable "teststring1", defined above. Remove only the trailing spaces in the test string.*/
SAY STRIP(teststring1, T)"."

/*Remove the trailing spaces and the "e"*/
SAY STRIP(teststring1,T," e")"."

/*Compress() removes characters anywhere in the string. This removes all blanks from the test string*/
SAY COMPRESS(teststring1)

CALL TIME('r')
SAY TIME('Civil') /*Civilian time HH:MM{AM | PM}*/
SAY TIME('h') /*Hours since midnight*/
SAY TIME('m') /*Minutes since midnight*/
SAY TIME('s') /*Seconds since midnight*/
SAY TIME('e') /*Elapsed time since program start*/

/*Function:TRACE Usage: TRACE( [option] )*/
SAY TRACE()
SAY TRACE(TRACE()) /*Leave it unchanged*/

/*Function:TRANSLATE Usage: TRANSLATE(string[,output][,input] [,pad])*/
SAY TRANSLATE('aBCdef') /*Translate to Uppercase*/
SAY TRANSLATE ('abcdef', '1234')
SAY TRANSLATE('654321', 'abcdef', '123456')
SAY TRANSLATE('abcdef', '123', 'abcdef', '+')

/*Function: TRIM Usage: TRIM(string)*/
SAY TRIM(' abc ')

/*Function: TRUNC Usage: TRUNC(number[,places])*/
SAY TRUNC(123.456)
SAY '$'TRUNC(134566.123,2)

/*Function: UPPER Usage: UPPER(string)*/
SAY UPPER('aBCdef12')

/*Function: VALUE Usage: VALUE(name)*/
abc = 'my name'
SAY VALUE('abc')

/*Function: VERIFY Usage: VERIFY(string,list[,'M'])*/
SAY VERIFY('123a45', '0123456789')
SAY VERIFY('abc3de', '012456789', 'M')

/*Function: WORD Usage: WORD(string,n)*/
SAY WORD('Now is the time',3)

/*Function: WORDINDEX Usage: WORDINDEX(string,n)*/
SAY WORDINDEX('Now is the time ',3)

/*Function: WORDLENGTH Usage: WORDLENGTH(string,n)*/
SAY WORDLENGTH('Now is the time ',4)

/*Function: WORDS Usage: WORDS(string)*/
SAY WORDS('Now is the time')

/*Function: WRITECH Usage: WRITECH(logical,string)*/
IF OPEN('test','ram:test$$', 'W') THEN DO
SAY WRITECH('test', 'message') /*Write the string*/
CALL CLOSE 'test'
END

/*Function: WRITELN Usage: WRITELN(logical,string)*/
IF OPEN('test', 'ram:test$$', 'W') THEN DO
SAY WRITELN('test', 'message')
/*Write the string (with newline)*/
CALL CLOSE 'test'
END

/*Function: X2C Usage: X2C(heystring)*/
SAY X2C('616263') /*Convent to character (pack)*/

/*Function: XRANGE Usage: XRANGE([start] [,end])*/
SAY C2X(xrange('f0'x))
SAY XRANGE('a', 'g')
EXIT
</syntaxhighlight>

The output of Program 13 is:

every good boy does fine
every good boy does fine.
every good boy does fine .
very good boy does fin.
very good boy does fin.
every good boy does fine.
every good boy does fin.
everygoodboydoesfine
1:23PM /*These results vary depending*/
13 /*on the time the program is run.*/
803
48199
0.80
N
N
ABCDEF
abcdef
fedcba
123+++
abc
123
$134566.12
ABCDEF12
my name
4
0
the
8
4
4
7
8
abc
F0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF
abcdefg

= REXXSupport.Library Functions =

The functions listed in this section are part of the REXXSupport.library. They may only be used if this library has been opened. Below is an example that shows you how to open this library.

== Program 14. OpenLibrary.rexx ==

<syntaxhighlight>
/*Add rexxsupport.library if it isn't already open.*/
IF ~ SHOW ('L', "rexxsupport.library") THEN DO
/*If the library isn't open, try to open it*/
IF ADDLIB('rexxsupport.library', 0, -30,0)
THEN SAY "Added rexxsupport.library."
ELSE DO
SAY 'ARexx support library not available, exiting'
EXIT 10 /*Exit if ADDLIB() failed*/
END
END
</syntaxhighlight>

== ALLOCMEM() ==

<nowiki>ALLOCMEM(length[,attribute])</nowiki>

Allocates a block of memory of the specified length from the system free-memory pool and returns its address as a four-byte string. The optional attribute parameter must be a standard EXEC memory allocation flag, supplied as a four-byte string. The default attribute is for "PUBLIC" memory (not cleared). Refer to [[Exec_Memory_Allocation|Exec Memory Allocation]] for information on memory types and attribute parameters.

This function should be used whenever memory is allocated for use by external programs. It is the user's responsibility to release the memory space when it is no longer needed. See also FREEMEM(). For example:

<syntaxhighlight>
SAY C2X(ALLOCMEM(1000)) -> 00050000
SAY C2X(ALLOCMEM (1000, '00 01 00 0 1'X)) -> 00228400
/*1000 bytes of CLEAR Public memory*/
</syntaxhighlight>

== CLOSEPORT() ==

<nowiki>CLOSEPORT(name)</nowiki>

Closes the message port specified by the name argument, which must have been allocated by a call to OPENPORT() within the current ARexx program. Any messages received but not yet REPLYed are automatically returned with the return code set to 10. See also OPENPORT(). For example:

<syntaxhighlight>
CALL CLOSEPORT myport
</syntaxhighlight>

== FREEMEM() ==

<nowiki>FREEMEM(address,length)</nowiki>

Releases a block of memory of the given length to the system free list. The address parameter is a four-byte string, typically obtained by a prior call to ALLOCMEM(). FREEMEM() cannot be used to release memory allocated using GETSPACE(), the ARexx internal memory allocator. The returned value is a Boolean success flag. See also ALLOCMEM(). For example:

<syntaxhighlight>
MemoryRequest = 1024
MyMem = ALLOCMEM(MemoryRequest)
SAY C2X(MyMem) -> 07C987B0
SAY FREEMEM(MyMem, MemoryRequest) -> 1
/*Or: SAY FREEMEM('07C987B0'x,1024)*/
</syntaxhighlight>

{{Note|title=Caution|text=Before your program terminates, you must use a matching FREEMEM() to release the exact amount of memory you allocated with each ALLOCMEM(). Otherwise, you may crash the system or leave memory unavailable until you reboot.}}

== GETARG() ==

<nowiki>GETARG(packet[,n])</nowiki>

Extracts a command, function name or argument string from a message packet. The packet argument must be a four-byte address obtained from a prior call to GETPKT(). The optional [n] argument specifies the slot containing the string to be extracted and must be less than or equal to the actual argument count for the packet. Commands and function names are always in slot 0. Function packets my have argument strings in slots 1-15. For example:

<syntaxhighlight>
command = GETARG(packet)
function = GETARG(packet,0) /*name string*/
arg1 = GETARG(packet,1) /*1st argument*/
</syntaxhighlight>

== GETPKT() ==

<nowiki>GETPKT(name)</nowiki>

Checks the message port specified by the name argument to see whether any messages are available. The named message port must have been opened by a prior call to OPENPRT() within the current ARexx program. The returned value is the four-byte address of the first message packet, or '0000 0000'x if no packets were available.

The function returns immediately whether or not a packet is enqueued at the message port. Programs should never be designed to "busy-loop" on a message port. If there is no useful work to be done until the next message packet arrives, the program should call WAITPKT() and allow other tasks to proceed. See also WAITPKT(). For example:

<syntaxhighlight>
packet = GETPKT ('MyPort')
</syntaxhighlight>

== OPENPORT() ==

<nowiki>OPENPORT(name)</nowiki>

Creates a public message port with the given name. The returned Boolean value indicates whether the port was successfully opened. An initialization failure will occur if another port of the same name already exists or if a signal bit couldn't be allocated. The message port is allocated as a Port Resource node and is linked into the program's global data structure. Ports are automatically closed when the program exits and any pending messages are returned to the sender. See also CLOSEPORT(). For example:

<syntaxhighlight>
success = OPENPORT("MyPort")
</syntaxhighlight>

== REPLY() ==

<nowiki>REPLY(packet,rc)</nowiki>

Returns a message packet to the sender, with the primary result field set to the value given by the rc argument. The secondary result is cleared. The packet argument must be supplied as a four-byte address, and the rc argument must be a whole number. For example:

<syntaxhighlight>
CALL REPLY(packet,10) /*Error return*/
</syntaxhighlight>

== SHOWDIR() ==

<nowiki>SHOWDIR(directory[,'ALL'|'FILE'|'DIR'][,pad])</nowiki>

Returns the contents of the specified directory as a string of names separated by blanks. The second parameter is an option keyword that selects whether all entries, only files, or only subdirectories, will be included. For example:

<syntaxhighlight>
SAY SHOWDIR('SYS:REXXC', 'f', ';') -> WaitForPort;TS;TE;TCO;RXSET;RXLIB;RXC;RX;HI
</syntaxhighlight>

== SHOWLIST() ==

<nowiki>SHOWLIST({'A' | 'D' | 'H' | 'T' | 'L' | 'M' | 'P' | 'R' | 'S' | 'T' | 'V' | 'W'}[,name][,pad])</nowiki>

An argument is entered using its initial letter. The arguments are:

; A
: ASSIGNS and Assigned Device

; D
: Device Drivers

; H
: Handlers

; I
: Interrupts

; L
: Libraries

; M
: Memory List Items

; P
: Ports

; R
: Resources

; S
: Semaphores

; T
: Tasks (Ready)

; V
: Volume Names

; W
: Waiting Tasks

If only one argument is supplied, SHOWLIST() returns a string separated by blanks: If a pad character is supplied, names will be separated by the pad rather than by blanks. If the name parameter is supplied. SHOWLIST() returns a Boolean value which indicates if the specified list contains that name. Names are case-sensitive. To provide an accurate snapshot of the current list, task switching is forbidden when the list is scanned.

<syntaxhighlight>
SAY SHOWLIST('P') -> REXX MyCon
SAY SHOWLIST('P',,';') -> REXX;MyCon
SAY SHOWLIST('P', 'REXX') -> 1
</syntaxhighlight>

== STATEF() ==

<nowiki>STATEF(filename)</nowiki>

Returns a string containing information about an external file. The string is formatted as:

<nowiki>"{DIR | FILE} length blocks protection days minutes ticks comment."</nowiki>

The length token gives the file length in bytes, and the block token specifies the file length in blocks. For example:

<syntaxhighlight>
SAY STATEF("LIBS:REXXSupport.library")
/*might give "File 2524 5 ----RW-D 4866 817 2088*/
</syntaxhighlight>

== WAITPKT() ==

<nowiki>WAITPKT(name)</nowiki>

Waits for a message to be received at the specified (named) port, which must have been opened by a call to OPENPORT() within the current ARexx program. The returned Boolean value indicates whether a message packet is available at the port. Normally the returned value will be 1 (True), since the function waits until an event occurs at the message port.

The packet must then be removed by a call to GETPKT() and should be returned eventually using the REPLY() function. Any message packets received but not returned when an ARexx program exits are automatically REPLYed with the return code set to 10. For example:

<syntaxhighlight>
CALL WAITPKT 'MyPort' /*Wait awhile*/
</syntaxhighlight>

AmigaOS Manual: ARexx Functions

2014-01-27T11:36:03Z

Tony Wyatt: More typos

A function is a program or group of statements that is executed whenever that function name is called in a particular context. A function may be part of an internal program, part of a library, or a separate external program. Functions are an important building block of modular programming because they allow you to construct large programs from a series of small, easily developed modules.

This chapter explains the different types of functions and how they are evaluated. It also provides an alphabetical reference of ARexx's built-in function library.

= Invoking a Function =

Within a ARexx program, a function is defined as a symbol or string followed immediately by an open parenthesis. The symbol or string (taken as a literal) specifies the function name, and the open parenthesis begins the argument list. Between the opening and closing parentheses are zero or more argument expressions, separated by commas, that supply the data being passed to the function.

Valid function calls are:

<syntaxhighlight>
CENTER ('title', 20)
ADDRESS()
'ALLOCMEM' (256*4,1)
</syntaxhighlight>

Each argument expression is evaluated in turn and the resulting strings are passed as the argument list to the function. Each argument expression, while often just a single literal value, can include arithmetic or string operations or even other function calls. Argument expressions are evaluated from left to right.

Functions can also be invoked using the CALL instruction. The CALL instruction, described in Chapter 4, can be used to invoke a function that may not return a value.

= Types of Functions =

There are three types of functions:

* Internal functions - defined within the ARexx program.
* Built-in functions - supplied by the ARexx programming language.
* Function Libraries - a special Amiga shared library.

== Internal Functions ==

An internal function is identified by a label within the program. When the internal function is called. ARexx creates a new storage environment so that the previous caller's environment is preserved. The new environment inherits the values from its predecessor, but subsequent changes to the environment variables do not affect the previous environment.

The specific values preserved are:

* The current and previous host addresses.
* The NUMERIC DIGITS, FUZZ, and FORM settings.
* The trace option, inhibit flag, and interactive flag.
* The state of the interrupt flags as defined by the SIGNAL instruction.
* The current prompt string as set by the OPTIONS PROMPT instruction.

The new environment does not automatically get a new symbol table, so initially all of the variables in the previous environment are available to the called function. The PROCEDURE instruction can be used to create a table and thereby protect the caller's symbol values. PROCEDURE can also be used to allow the same variable name to be used in two different areas with two different values.

Execution of the internal function proceeds until a RETURN instruction is executed. At this point the new environment is dismantled, and control resumes at the point of the function call. The expression supplied with the RETURN instruction is evaluated and passed back to the caller as the function result.

== Built-In Functions ==

ARexx provides a substantial library of predefined functions as part of the language system. These functions are always available and have been optimized to work with the internal data structures. In general, the built-in functions execute much faster than an equivalent interpreted function, so their usage is strongly recommended.

Several of the built-in functions create and manipulate external AmigaDOS files. Files are referenced by a logical name, a case-sensitive name that is assigned to a file when it is first opened. The initial input and output streams are given the names STDIN (standard input) and STDOUT (standard output). There is no theoretical limit to the number of files that may be open simultaneously, although a limit will be imposed by available memory. All open files are closed automatically when the program exits.

== External Function Libraries ==

A function library is a collection of one or more functions organized as an Amiga shared library. The library must reside in LIBS:, but may be either memory or disk-resident. Disk-resident libraries are loaded and opened as needed.

The library has to be especially tailored for use by ARexx. Each function library must contain a library name, a search priority, an entry point offset, and a version number. When ARexx is searching for a function, the interpreter opens each library and checks its "query" entry point. This entry point must be specified as an integer offset (e.g. "-30") from the library base. The return code from the query call indicates whether the desired function was found. If the function is found, it is called with the parameters passed by the interpreter, and the function result is returned to the caller. If it is not found, a "Function not found" error code is returned, and the search continues with the next library in the list. Function libraries are always closed after being checked so that the operating system can reclaim the memory space if required.

=== The Library List ===

The ARexx resident process maintains a list of the currently available function libraries and function hosts called the Library List. Application programs can add or remove function libraries as required.

The Library List is maintained as a priority-sorted queue. Each entry has an associated search priority in the range 100 (highest) to -100 (lowest). Entries can be added at an appropriate priority to control the function name resolution. Libraries with higher priorities are searched first. Within a given priority level, those libraries added first are searched first. The priority levels are significant if any of the libraries have duplicate function name definitions, since the function located further down the search chain could never be called.

== External Function Hosts ==

The name associated with a function host is the name of its public message port. Function calls are passed to the host as a message packet; it is then up to the individual host to determine whether the specified function name is one that it recognizes. The name resolution is completely internal to the host, so function hosts provide a natural gateway mechanism for implementing remote procedure calls to other machines in a network. The ARexx resident process is a function host and is installed in the Library List with a priority of -60.

= The Search Order =

Function linkages in ARexx are established at the time of the function call. A specific search order is followed until a function matching the name symbol or string is found. If the specified function cannot be located, an error is generated and the expression evaluation is terminated. The full search order is:

; Internal Functions
: The program source is examined for a label that matches the function name. If a match is found, a new storage environment is created and control is transferred to the label.

; Built-In Functions
: The built-in function library is searched for the specified name. All of these functions are defined by uppercase names.

; Function Libraries and Function Hosts
: The available function libraries and function hosts are maintained in the Library List, which is searched starting at the highest priority until the requested function is found or the end of the list is reached. Function hosts are called using a message-passing protocol similar to that used for commands and may be used as gateways for remote procedure calls to other machines in a network.

; External ARexx Programs
: The final search step is to check for an external ARexx program file by sending an invocation message to the ARexx resident process. The search always begins in the current directory and follows the same search path as the original ARexx program invocation. The name matching process is not case-sensitive.

The function name-matching procedure may be case-sensitive for some of the search steps, but not for others. The matching procedure used in a function library or function host is design dependent. Functions defined with mixed-case names must be called using a string token, since symbol names are always translated to uppercase.

The full search order is followed whenever the function name is defined by a symbol token. However, the search for internal functions is bypassed if the name is specified by a string token. This allows internal functions to usurp the names of external functions, as in the following example:

<syntaxhighlight>
CENTER: /*internal "CENTER"*/
ARG string, length /*get arguments*/
length = MIN(length,60) /*compute length*/
return 'CENTER' (string, length)
</syntaxhighlight>

Here the built-in function CENTER() has been replaced by an internal function after modifying the length argument.

= The Clip List =

The Clip List is a publicly accessible mechanism that can be used as a general clipboard for intertask communication. Many functions use the clipboard for retrieving different types of information, such as predefined constants or strings.

The Clip List maintains a set of (name, value) pairs that may be used for a variety of purposes. (SETCLIP() is used to add pairs to the list.) Each entry in the list consists of a name and a value string and may be located by name. In general, the names used should be chosen to be unique to an application to prevent unintended duplications with other programs. Any number of entries may be posted to the list.

One potential application for the Clip List is as a mechanism for loading predefined constants into an ARexx program. For example:

<syntaxhighlight>
pi=3.14159; e=2.718; sqrt2=1.414 . . .
</syntaxhighlight>

(i.e., a series of assignments separated by semicolons). In use, such a string could be retrieved by name using the built-in function GETCLIP() and then INTERPRETed within the program. The assignment statements within the string would then create the required constant definitions. For example:

<syntaxhighlight>
/*Assume a string called "numbers" is available*/
numbers = GETCLIP ('numbers')
INTERPRET numbers /*. . . assignments*/
</syntaxhighlight>

The strings would not be restricted to contain only assignment statements, but could include any valid ARexx statements. The Clip List could thus provide a series of programs for initializations or other processing tasks.

The resident process supports addition and deletion operations for maintaining the Clip List. The names in the (name,value) pairs are assumed to be in mixed case and are maintained to be unique in the list. An attempt to add a string with an existing name will simply update the value string. The name and value strings are copied when an entry is posted to the list, so the program that adds an entry is not required to maintain the strings.

Entries posted to the Clip List remain available until explicitly removed. The Clip List is automatically released when the resident process exits.

= Built-in Functions Reference =

This section provides an alphabetical list of the built-in functions. The syntax of each function is shown to the right of the function keyword.

== Syntax ==

Optional arguments are shown in brackets and generally have a default value that is used if the argument is omitted. When an option keyword is specified as an argument, only the first character is significant. Option keywords are not case-sensitive.

Many functions accept a pad character argument. Pad characters are inserted to fill or create spaces. For functions that accept a pad argument, only the first character of the argument string is significant. If a null string is supplied, the default padding character, usually a blank, will be used.

In the following examples, an arrow (->) is used as an abbreviation for "evaluates as." The arrow will not be displayed when a program is run. For example:

<syntaxhighlight>
SAY ABS (-5.35) -> 5.35
</syntaxhighlight>

This means that SAY ABS(-5.35) is evaluated as 5.35.

== Alphabetical Reference ==

=== ABBREV() ===

<nowiki>ABBREV(string1,string2[,length])</nowiki>

Returns a Boolean value that indicates whether string2 is an abbreviation of string1 with length greater than or equal to the specified length argument. The default length is 0, so the null string is an acceptable abbreviation. For example:

<syntaxhighlight>
SAY ABBREV ('fullname', 'ful') -> 1
SAY ABBREV ('almost', 'alm',4) -> 0
SAY ABBREV ('any','') -> 1
</syntaxhighlight>

=== ABS() ===

<nowiki>ABS(number)</nowiki>

Returns the absolute value of the number argument. This value must be numeric. For example:

<syntaxhighlight>
SAY ABS(-5.35) -> 5.35
SAY ABS(10) -> 10
</syntaxhighlight>

=== ADDLIB() ===

<nowiki>ADDLIB(name,priority[,offset,version])</nowiki>

Adds a function library or a function host to the library list maintained by the resident process. The name argument specifies either the name of a function library or the public message port associated with a function host. The name is case-sensitive. Any specified libraries should reside in the system LIBS: directory.

The priority argument specifies the search priority and must be an integer between 100 and -100, inclusive. The offset and version arguments apply only to libraries. The offset is the integer offset to the library's "query" entry point, and the version is an integer specifying the minimum acceptable release level of the library.

The function returns a Boolean result that indicates whether the operation was successful. If a library is specified, it is not actually opened at this time. Similarly, ARexx does not check to see whether a specified function host port is open. For example:

<syntaxhighlight>
SAY ADDLIB ("rexxsupport.library",0,-30,0) -> 1
CALL ADDLIB "EtherNet",-20 /*A gateway*/
</syntaxhighlight>

=== ADDRESS() ===

<nowiki>ADDRESS()</nowiki>

Returns the current host address string. The host address is the message port to which commands will be sent. The SHOW() function can be used to check whether the required external host is actually available. See also SHOW(). For example:

<syntaxhighlight>
SAY ADDRESS() -> REXX
</syntaxhighlight>

=== ARG() ===

<nowiki>ARG([number][,'EXISTS'|'OMITTED'])</nowiki>

ARG() returns the number of arguments supplied to the current environment. If only the number parameter is supplied, the corresponding argument string is returned. If a number and the Exists or Omitted keyword is given, the Boolean return indicates the status of the corresponding argument. The existence or omission test does not indicate whether the string has a null value, but only whether a string was supplied. For example:

<syntaxhighlight>
/*Assume arguments were: ('one',,10)*/
SAY ARG() -> 3
SAY ARG(1) -> one
SAY ARG(2,'O') -> 1
</syntaxhighlight>

=== B2C() ===

<nowiki>B2C(string)</nowiki>

Converts a string of binary digits (0,1) into the corresponding (packed) character representation. The conversion is the same as though the argument string had been specified as a literal binary string (e.g. `1010'B). Blanks are permitted in the string, but only at byte boundaries. This function is particularly useful for creating strings that are to be used as bit masks. See also X2C(). For example:

<syntaxhighlight>
SAY B2C('00110011') -> 3
SAY B2C('01100001') -> a
</syntaxhighlight>

=== BITAND() ===

<nowiki>BITAND(string1,string2[,pad])</nowiki>

The argument strings are logically ANDed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITAND('0313'x, 'FFF0'x) -> '0310'x
</syntaxhighlight>

=== BITCHG() ===

<nowiki>BITCHG(string,bit)</nowiki>

Changes the state of the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITCHG('0313'x,4) -> '0303'x
</syntaxhighlight>

=== BITCLR() ===

<nowiki>BITCLR(string,bit)</nowiki>

Clears (sets to zero) the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITCLR('0313'x,4) -> '0303'x
</syntaxhighlight>

=== BITCOMP() ===

<nowiki>BITCOMP(string1,string2[,pad])</nowiki>

Compares the argument strings bit-by-bit, starting at bit number 0. The returned value is the bit number of the first bit in which the strings differ, or -1 if the strings are identical. For example:

<syntaxhighlight>
BITCOMP('7F'x, 'FF'x) -> 7 /*Seventh bit*/
BITCOMP('FF'x, 'FF'x) -> -1
</syntaxhighlight>

=== BITOR() ===

<nowiki>BITOR(string1,string2[,pad])</nowiki>

The argument strings are logically ORed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITOR('0313'x, '00F'x) -> '033F'x
</syntaxhighlight>

=== BITSET() ===

<nowiki>BITSET(string,bit)</nowiki>

Sets the specified bit in the argument string to 1. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITSET('313'x,2) -> '0317'x
</syntaxhighlight>

=== BITTST() ===

<nowiki>BITTST(string,bit)</nowiki>

The Boolean return indicates the state of the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITTST('0313=x,4) -> 1
</syntaxhighlight>

=== BITXOR() ===

<nowiki>BITXOR(string1,string2[,pad])</nowiki>

The argument strings are logically and exclusively-ORed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITXOR('0313'x, '001F'x) -> '030C'X
</syntaxhighlight>

=== C2B() ===

<nowiki>C2B(string)</nowiki>

Converts the character string into the equivalent string of binary digits. See also C2X(). For example:

<syntaxhighlight>
SAY C2B('abc') -> 011000010110001001100011
</syntaxhighlight>

=== C2D() ===

<nowiki>C2D(string[,n])</nowiki>

Converts the string argument from its character representation to the corresponding decimal number, expressed as ASCII digits (0-9). If n is supplied, the character string is considered to be a number expressed in n bytes. The string is truncated or padded with nulls on the left as required, and the sign bit is extended for the conversion. For example:

<syntaxhighlight>
SAY C2D('0020'x) -> 32
SAY C2D('FFFF ffff'x) -> -1
SAY C2D('FF0100'x,2) -> 256
</syntaxhighlight>

=== C2X() ===

<nowiki>C2X(string)</nowiki>

Converts the string argument from its character representation to the corresponding hexadecimal number, expressed as the ASCII characters 0-9 and A-F. See also C2B(). For example:

<syntaxhighlight>
SAY C2X('abc') -> 616263
</syntaxhighlight>

=== CENTER()/CENTRE() ===

<nowiki>CENTER(string,length[,pad])</nowiki>
<nowiki>CENTRE(string,length[,pad])</nowiki>

Centers the string argument in a string with the specified length. If the length is longer than that of the string, pad characters or blanks are added as necessary. For example:

<syntaxhighlight>
SAY CENTER('abc',6) -> ' abc '
SAY CENTER('abc',6,'+') -> '+abc++'
SAY CENTER ('123456',3) -> '234'
</syntaxhighlight>

=== CLOSE() ===

<nowiki>CLOSE(file)</nowiki>

Closes the file specified by the given logical name. The returned value is a Boolean success flag and will be 1 unless the specified file was not open. For example:

<syntaxhighlight>
SAY CLOSE('input') -> 1
</syntaxhighlight>

=== COMPARE() ===

<nowiki>COMPARE(string1,string2[,pad])</nowiki>

Compares two strings and returns the index of the first position in which they differ or 0 if the strings are identical. The shorter string is padded as required using the supplied character or blanks. For example:

<syntaxhighlight>
SAY COMPARE('abcde', 'abcce') -> 4
SAY COMPARE('abcde', 'abcde') -> 0
SAY COMPARE('abc++', 'abc+-', '+') -> 5
</syntaxhighlight>

=== COMPRESS() ===

<nowiki>COMPRESS(string[,list])</nowiki>

If the list argument is omitted, the function removes leading, trailing or embedded blank characters from the string argument. If the optional list is supplied, it specifies the characters to be removed from the string. For example:

<syntaxhighlight>
SAY COMPRESS(' why not ') -> whynot
SAY COMPRESS('++12-34-+', '+-') -> 1234
</syntaxhighlight>

=== COPIES() ===

<nowiki>COPIES(string,number)</nowiki>

Creates a new string by concatenating the specified number of copies of the original. The number argument may be zero, in which case the null string is returned. For example:

<syntaxhighlight>
SAY COPIES('abc',3) -> abcabcabc
</syntaxhighlight>

=== D2C() ===

<nowiki>D2C(number)</nowiki>

Creates a string whose value is the binary (packed) representation of the given decimal number. For example:

<syntaxhighlight>
D2C(65) -> A
</syntaxhighlight>

=== D2X() ===

<nowiki>D2X(number[,digits])</nowiki>

Converts a decimal number to hexadecimal. For example:

<syntaxhighlight>
D2X(31) -> 1F
</syntaxhighlight>

=== DATATYPE() ===

<nowiki>DATATYPE(string[,option])</nowiki>

If only the string argument is specified, DATATYPE() tests whether the string parameter is a valid number and returns either NUM or CHAR. If an option keyword is given, the Boolean return indicates whether the string satisfied the requested test. The following option keywords are recognized:

; ALPHANUMERIC
: Accepts alphabetic (A-Z, a-z) or numeric (0-9) characters

; BINARY
: Accepts a binary digits string

; LOWERCASE
: Accepts lower case alphabetic (a-z) characters

; MIXED
: Accepts mixed upper/lower case characters

; NUMERIC
: Accepts valid numbers

; SYMBOL
: Accepts valid REXX symbols

; UPPER
: Accepts upper case alphabetic (A-Z) characters

; WHOLE
: Accepts integer numbers

; X
: Accepts Hex digit strings

For example:

<syntaxhighlight>
SAY DATATYPE('123') -> NUM
SAY DATATYPE('1a f2', 'X') -> 1
SAY DATATYPE('aBcde', 'L') -> 0
</syntaxhighlight>

=== DATE() ===

<nowiki>DATE([option][,date][format])</nowiki>

Returns the current date in the specified format. The default (`NORMAL') option returns the date in the form DD MMM YYYY, as in 20 APR 1988. The options recognized are:

; BASEDATE
: The number of days since January 1, 0001

; CENTURY
: The number of days since January 1 of the century

; DAYS
: The number of days since January 1 of the current year

; EUROPEAN
: The date in the form DD/MM/YY

; INTERNAL
: Internal system days

; JULIAN
: The date in the form YYDDD

; MONTH
: The current month (in mixed case)

; NORMAL
: The date in the form DD MMM YYYY

; ORDERED
: The date in the form YY/MM/DD

; SORTED
: The date in the form YYYYMMDD

; USA
: The date in the form MM/DD/YY

; WEEKDAY
: The day of the week (in mixed case)

These options can be shortened to just the first character.

The DATE() function also accepts optional second and third arguments to supply the date either in the form of internal system days or in the 'sorted' form YYYYMMDD. The second argument is specifying either system days (the default) or a sorted date. The third argument specifies the form of the date and can be either 'I' or 'S'. The current date in system days can be retrieved using DATE('INTERNAL'). For example:

<syntaxhighlight>
SAY DATE() -> 14 Jul 1992
SAY DATE('M') -> July
SAY DATE(S) -> 19920714
SAY DATE('S' ,DATE('I')+21) -> 19920804
SAY DATE('W' ,19890609, 'S') -> Friday
</syntaxhighlight>

=== DELSTR() ===

<nowiki>DELSTR(string,n[,length])</nowiki>

Deletes the substring of the string argument beginning with the nth character for the specified length in characters. The default length is the remaining length of the string. For example:

<syntaxhighlight>
SAY DELSTR('123456',2,3) -> 156
</syntaxhighlight>

=== DELWORD() ===

<nowiki>DELWORD(string,n[,length])</nowiki>

Deletes the substring of the string argument beginning with the nth word for the specified length in words. The default length is the remaining length of the string. The deleted string includes any trailing blanks following the last word. For example:

<syntaxhighlight>
SAY DELWORD('Tell me a story',2,2) -> 'Tell story'
SAY DELWORD('one two three',3) -> 'one two '
</syntaxhighlight>

=== DIGITS() ===

<nowiki>DIGITS()</nowiki>

Returns the current Numeric Digits setting. For example:

<syntaxhighlight>
NUMERIC DIGITS 6
SAY DIGITS() -> 6
</syntaxhighlight>

=== EOF() ===

<nowiki>EOF(file)</nowiki>

Checks the specified logical file name and returns the Boolean value 1 (True), if the end-of-file has been reached, and 0 (False) otherwise. For example:

<syntaxhighlight>
SAY EOF(infile) -> 1
</syntaxhighlight>

=== ERRORTEXT() ===

<nowiki>ERRORTEXT(n)</nowiki>

Returns the error message associated with the specified ARexx error code. The null string is returned if the number is not a valid error code. For example:

<syntaxhighlight>
SAY ERRORTEXT(41) -> Invalid expression
</syntaxhighlight>

=== EXISTS() ===

<nowiki>EXISTS(filename)</nowiki>

Tests whether an external file of the given filename exists. The name string may include device and directory specifications. For example:

<syntaxhighlight>
SAY EXISTS('SYS:C/ED') -> 1
</syntaxhighlight>

=== EXPORT() ===

<nowiki>EXPORT(address[,string][,length][,pad])</nowiki>

Copies data from the optional string into a previously-allocated memory area. This memory area must be specified as a four-byte address. The length parameter specifies the maximum number of characters to be copied. The default is the length of the string. If the specified length is longer than the string, the remaining area is filled with the pad character or nulls ('00'x). The returned value is the number of characters copied.

{{Note|title=Caution|text=Any area of memory can be overwritten, possibly causing a system crash. Task switching is forbidden while the copy is being done, so system performance may be degraded if long strings are copied.}}

See also IMPORT() and STORAGE(). For example:

<syntaxhighlight>
count = EXPORT('0004 0000'x, 'The answer')
</syntaxhighlight>

=== FIND() ===

<nowiki>FIND(string,phrase)</nowiki>

The FIND() function locates a phrase of words in a larger string of words and returns the word number of the matched position. For example:

<syntaxhighlight>
SAY FIND('Now is the time', 'is the') -> 2
</syntaxhighlight>

=== FORM() ===

<nowiki>FORM()</nowiki>

Returns the current NUMERIC FORM setting. For example:

<syntaxhighlight>
NUMERIC FORM SCIENTIFIC
SAY FORM() -> SCIENTIFIC
</syntaxhighlight>

=== FREESPACE() ===

<nowiki>FREESPACE(address,length)</nowiki>

Returns a block of memory of a given length to the interpreter's internal pool. The address argument must be a 4 byte string obtained by a prior call to GETSPACE(), the internal allocator. It is not always necessary to release internally allocated memory, since it will be released to the system when the program terminates. However, if a very large block has been allocated, returning it to the pool may avoid memory space problems. The return value is a Boolean success flag. See also GETSPACE().

Calling FREESPACE() with no arguments will return the amount of memory available in the interpreter's internal pool. For example:

<syntaxhighlight>
FREESPACE('00042000'x,32) -> 1
</syntaxhighlight>

=== FUZZ() ===

<nowiki>FUZZ()</nowiki>

Returns the current NUMERIC FUZZ setting. For example:

<syntaxhighlight>
NUMERIC FUZZ 3
SAY FUZZ() -> 3
</syntaxhighlight>

=== GETCLIP() ===

<nowiki>GETCLIP(name)</nowiki>

Searches the Clip List for an entry matching the supplied name parameter and returns the associated value string. The name matching is case-sensitive. The null string is returned if the name cannot be found. See also SETCLIP(). For example:

<syntaxhighlight>
/*Assume 'numbers' contains 'PI=3.14159'*/
SAY GETCLIP('numbers') -> PI=3.14159
</syntaxhighlight>

=== GETSPACE() ===

<nowiki>GETSPACE(length)</nowiki>

Allocates a block of memory of the specified length from the interpreter's internal pool. The returned value is the four-byte address of the allocated block, which is not cleared or otherwise initialized. Internal memory is automatically returned to the system when the ARexx program terminates, so this function should not be used to allocate memory for use by external programs. The REXXSupport.Library includes the function ALLOCMEM(), which allocates memory from the system free list. See also FREESPACE(). For example:

<syntaxhighlight>
SAY C2X (GETSPACE(32)) -> '0003BF40'x
</syntaxhighlight>

=== HASH() ===

<nowiki>HASH(string)</nowiki>

Returns the hash attribute of a string as a decimal number and updates the internal hash value of the string. For example:

<syntaxhighlight>
SAY HASH('1') -> 49
</syntaxhighlight>

=== IMPORT() ===

<nowiki>IMPORT(address[,length])</nowiki>

Creates a string by copying data from the specified four-byte address. If the length parameter is not supplied, the copy terminates when a null byte is found. See also EXPORT(). For example:

<syntaxhighlight>
extval = IMPORT('0004 0000'x,8)
</syntaxhighlight>

=== INDEX() ===

<nowiki>INDEX(string,pattern[,start])</nowiki>

Searches for the first occurrence of the pattern argument in the string argument, beginning at the specified start position. The default start position is 1. The returned value is the index of the matched pattern or 0 if the pattern was not found. For example:

<syntaxhighlight>
SAY INDEX("123456", "23") -> 2
SAY INDEX("123456", "77") -> 0
SAY INDEX("123123", "23",3) -> 5
</syntaxhighlight>

=== INSERT() ===

<nowiki>INSERT(new,old[,start][,length][,pad])</nowiki>

Inserts the new string into the old string after the specified start position. The default starting position is 0. The new string is truncated or padded to the specified length as required, using the supplied pad character or blanks. If the start position is beyond the end of the string, the old string is padded on the right. For example:

<syntaxhighlight>
SAY INSERT('ab', '12345') -> ab12345
SAY INSERT('123', '++',3,5, '-') -> ++-123--
</syntaxhighlight>

=== LASTPOS() ===

<nowiki>LASTPOS(pattern,string[,start])</nowiki>

Searches backwards for the first occurrence of the pattern argument in the string argument, beginning at the specified start position. The default starting position is the end of the string. The returned value is the index of the matched pattern or 0 if the pattern was not found. For example:

<syntaxhighlight>
SAY LASTPOS('2', '1234') -> 2
SAY LASTPOS('2', '1234234') -> 5
SAY LASTPOS('2', '123234',3) -> 2
SAY LASTPOS('2', '13579') -> 0
</syntaxhighlight>

=== LEFT() ===

<nowiki>LEFT(string,length[,pad])</nowiki>

Returns the leftmost substring in the given string argument with the specified length. If the substring is shorter than the requested length, it is padded on the right with the supplied pad character or blanks. For example:

<syntaxhighlight>
SAY LEFT('123456',3) -> 123
SAY LEFT('123456',8, '+') -> 123456++
</syntaxhighlight>

=== LENGTH() ===

<nowiki>LENGTH(string)</nowiki>

Returns the length of the string. For example:

<syntaxhighlight>
SAY LENGTH('three') -> 5
</syntaxhighlight>

=== LINES() ===

<nowiki>LINES(file)</nowiki>

Returns the number of lines queued or typed ahead at the logical file, which must refer to an interactive stream. The line count is obtained as the secondary result of a WaitForChar() call. For example:

<syntaxhighlight>
PUSH 'a line'
PUSH 'another one'
SAY LINES(STDIN) -> 2
</syntaxhighlight>

=== MAX() ===

<nowiki>MAX(number,number[,number,...])</nowiki>

Returns the maximum of the supplied arguments, all of which must be numeric. At least two parameters must be supplied. For example:

<syntaxhighlight>
SAY MAX(2.1,3,-1) -> 3
</syntaxhighlight>

=== MIN() ===

<nowiki>MIN(number,number[,number,...])</nowiki>

Returns the minimum of the supplied arguments, all of which must be numeric. At least two parameters must be supplied. For example:

<syntaxhighlight>
SAY MIN(2.1,3,-1) -> -1
</syntaxhighlight>

=== OPEN() ===

<nowiki>OPEN(file,filename[,'APPEND'|'READ'|'WRITE'])</nowiki>

Opens an external file for the specified operation. The file argument defines the logical name by which the file will be referenced. The filename is the external name of the file and may include device and directory specifications. The function returns a Boolean value that indicates whether the operation was successful. There is no limit to the number of files that can be open simultaneously, and all open files are closed automatically when the program exits. See also CLOSE(), READ(), and WRITE(). For example:

<syntaxhighlight>
SAY OPEN('MyCon', 'CON:160/50/320/100/MyCON/cds') P-> 1
SAY OPEN('outfile', 'ram:temp', 'W') -> 1
</syntaxhighlight>

=== OVERLAY() ===

<nowiki>OVERLAY(new,old[,start][,length][,pad])</nowiki>

Overlays the new string onto the old string beginning at the specified start position, which must be positive. The default starting position is 1. The new string is truncated or padded to the specified length as required, using the supplied pad character or blanks. If the start position is beyond the end of the old string, the old string is padded on the right. For example:

<syntaxhighlight>
SAY OVERLAY('bb', 'abcd') -> bbcd
SAY OVERLAY('4', '123',5,5, '-') -> 123-4----
</syntaxhighlight>

=== POS() ===

<nowiki>POS(pattern,string[,start])</nowiki>

Searches for the first occurrence of the pattern argument in the string argument, beginning at the position specified by the start argument. The default starting position is 1. The value is the index of the matched string or 0 if the pattern wasn't found. For example:

<syntaxhighlight>
SAY POS('23', '123234') -> 2
SAY POS('77', '123234') -> 0
SAY POS('23', '123234',3) -> 4
</syntaxhighlight>

=== PRAGMA() ===

<nowiki>PRAGMA(option[,value])</nowiki>

This function allows a program to change various attributes relating to the system environment within which the program executes. The option argument is a keyword that specifies an environmental attribute. The value argument supplies the new attribute value to be installed. The value returned by the function depends on the attribute selected. Some attributes return the previous value installed, while others may simply set a Boolean success flag.

The currently defined option keywords are:

; DIRECTORY
: Specifies a new current directory. The current directory is used as the root for filenames that do not explicitly include a device specification. The return is the old directory name. PRAGMA('D') is equivalent to PRAGMA('D',"). It returns the path of the current directory without changing the directory.

; PRIORITY
: Specifies a new task priority. The priority value must be an integer in the range - 128 to 127, but the practical range is much more limited. ARexx programs should never be run at a priority higher than that of the resident process, which currently runs at a priority of 4. The returned value is the previous priority level.

; ID
: Returns the task ID (the address of the task block) as an 8-character hex string. The task ID is a unique identifier of the particular ARexx invocation and may be used to create a unique name for it.

; STACK
: Specifies a new stack value for your current ARexx program. When a new stack value is declared, the previous stack value is returned.

The currently implemented options are:

; PRAGMA('W',{'NULL'|' WORKBENCH'})
: Controls the task's WindowPtr field. Setting it to 'NULL' will suppress any requesters that might otherwise be generated by a DOS call.

; PRAGMA('*'[,name])
: Defines the specified logical name as the current ("*") console handler, allowing the user to open two streams on one window. If the name is omitted, the console handler is set to that of the client's process.

<syntaxhighlight>
SAY PRAGMA('D', 'DF0:C') -> Extras
SAY PRAGMA('D', 'DF1:C') -> Workbench:C
SAY PRAGMA('PRIORITY', -5) -> 0
SAY PRAGMA('ID') -> 00221ABC
CALL PRAGMA '*',STDOUT
SAY PRAGMA("STACK",8092) -> 4000
</syntaxhighlight>

=== RANDOM() ===

<nowiki>RANDOM([MIN][,MAX][,seed])</nowiki>

Returns a pseudo-random integer in the interval specified by the min and max arguments. The default minimum value is 0 and the default maximum value is 999. The interval max-min must be less than or equal to 1000. If a greater range of random integers is required, the values from the RANDU() function can be suitably scaled and translated. The seed argument can be supplied to initialize the internal state of the random number generator. See also RANDU(). For example:

<syntaxhighlight>
thisroll = RANDOM(1,6) /*Might be 1*/
nextroll = RANDOM(1,6) /*Might be snake eyes*/
</syntaxhighlight>

=== RANDU() ===

<nowiki>RANDU([seed])</nowiki>

Returns a uniformly-distributed, pseudo-random number between 0 and 1. The number of digits of precision in the result is always equal to the current Numeric Digits setting. With the choice of suitable scaling and translation values, RANDU() can be used to generate pseudo-random numbers on an arbitrary interval.

The optional integer seed argument is used to initialize the internal state of the random number generator. See also RANDOM(). For example:

<syntaxhighlight>
firsttry = RANDU() /*0.371902021?*/
NUMERIC DIGITS 3
tryagain = RANDU () /*0.873?*/
</syntaxhighlight>

=== READCH() ===

<nowiki>READCH(file,length)</nowiki>

Reads the specified number of characters from the given logical file into a string. The length of the returned string is the actual number of characters read and may be less than the requested length if, for example, the end-of-file was reached. See also READLN(). For example:

<syntaxhighlight>
instring = READCH('input',10)
</syntaxhighlight>

=== READLN() ===

<nowiki>READLN(file)</nowiki>

Reads characters from the given logical file into a string until a newline character is found. The returned string does not include the newline. See also READCH(). For example:

<syntaxhighlight>
instring = READLN('MyFile')
</syntaxhighlight>

=== REMLIB() ===

<nowiki>REMLIB(name)</nowiki>

Removes an entry with the given name from the Library List maintained by the resident process. The Boolean return is 1 if the entry was found and successfully removed. This function does not make a distinction between function libraries and function hosts, but simply removes a named entry. See also ADDLIB(). For example:

<syntaxhighlight>
SAY REMLIB('MyLibrary.library') -> 1
</syntaxhighlight>

=== REVERSE() ===

<nowiki>REVERSE(string)</nowiki>

Reverses the sequence of characters in the string. For example:

<syntaxhighlight>
SAY REVERSE('?ton yhw') -> why not?
</syntaxhighlight>

=== RIGHT() ===

<nowiki>RIGHT(string,length[,pad])</nowiki>

Returns the rightmost substring in the given string argument with the specified length. If the substring is shorter than the requested length, it is padded on the left with the supplied pad character or blanks. For example:

<syntaxhighlight>
SAY RIGHT('123456',4) -> 3456
SAY RIGHT('123456',8, '+') -> ++123456
</syntaxhighlight>

=== SEEK() ===

<nowiki>SEEK(file,offset[,'BEHIN'|'CURRENT'|'END'])</nowiki>

Moves to a new position in the given logical file, specified as an offset from an anchor position. The default anchor is Current. The returned value is the new position relative to the start of the file. For example:

<syntaxhighlight>
SAY SEEK('input',10,'B') -> 10
SAY SEEK('input',0,E') -> 356 /*file length*/
</syntaxhighlight>

=== SETCLIP() ===

<nowiki>SETCLIP(name[,value])</nowiki>

Adds a name-value pair to the Clip List maintained by the resident process. If an entry of the same name already exists, its value is updated to the supplied value string. Entries may be removed by specifying a null value. The function returns a Boolean value that indicates whether the operation was successful. For example:

<syntaxhighlight>
SAY SETCLIP('path', 'DF0:s') -> 1
SAY SETCLIP('path') -> 1
</syntaxhighlight>

=== SHOW() ===

<nowiki>SHOW(option[,name][,pad])</nowiki>

Returns the names in the resource list specified by the option argument, or tests to see whether an entry with the specified name is available. The currently implemented options keywords are:

; CLIP
: Examines the names in the Clip List

; FILES
: Examines the currently open logical file names

; LIBRARIES
: Examines the names in the Library List, which are either function libraries or function hosts.

; PORTS
: Examines the names in the system Ports List

If the name argument is omitted, the function returns a string with the resource names separated by a blank space or the pad character, if one was supplied. If the name argument is given, the returned Boolean value indicates whether the name was found in the resource list. The name entries are case-sensitive.

=== SIGN() ===

<nowiki>SIGN(number)</nowiki>

Returns 1 if the number argument is positive or zero and -1 if the number is negative. The argument must be numeric. For example:

<syntaxhighlight>
SAY SIGN(12) -> 1
SAY SIGN(-33) -> -1
</syntaxhighlight>

=== SOURCELINE() ===

<nowiki>SOURCELINE([line])</nowiki>

Returns the text for the specified line of the currently executing ARexx program. If the line argument is omitted, the function returns the total number of lines in the file. This function is often used to embed "help" information in a program. For example:

<syntaxhighlight>
/*A simple test program*/
SAY SOURCELINE() -> 3
SAY SOURCELINE(1)-> /*A simple test program*/
</syntaxhighlight>

=== SPACE() ===

<nowiki>SPACE(string,n[,pad])</nowiki>

Reformats the string argument so that there are n spaces (blank characters) between each pair of words. If the pad character is specified, it is used instead of blanks as the separator character. Specifying n as 0 will remove all blanks from the string. For example:

<syntaxhighlight>
SAY SPACE('Now is the time',3) -> 'Now is the time'
SAY SPACE('Now is the time',0) -> 'Nowisthetime'
SAY SPACE('1 2 3',1, '+') -> '1+2+3'
</syntaxhighlight>

=== STORAGE() ===

<nowiki>STORAGE([address][,string][,length][,pad])</nowiki>

STORAGE() with no arguments returns the available system memory. If the address argument is given, it must be a four-byte string. The function copies data from the (optional) string to the indicated memory address. The length parameter specifies the maximum number of bytes to be copied and defaults to the length of the string. If the specified length is longer than the string, the remaining area is filled with the pad character or nulls ('00'x).

The returned value is the previous contents of the memory area. This can be used in a subsequent call to restore the original contents. See also EXPORT().

{{Note|title=Caution|text=Any area of memory can be overwritten, possibly causing a system crash. Task switching is forbidden while the copy is being done, so system performance may be degraded if long strings are copied.}}

For example:

<syntaxhighlight>
SAY STORAGE() -> ' 248400
oldval = STORAGE('0004 0000'x, 'The answer')
CALL STORAGE '0004 0000'x,,32, '+'
</syntaxhighlight>

=== STRIP() ===

<nowiki>STRIP(string[,{`B' | `L' | `T'}][,pad])</nowiki>

If neither of the optional parameters is supplied, the function removes both leading and trailing blanks from the string argument. The second argument specifies whether Leading, Trailing or Both (leading and trailing) characters are to be removed. The optional pad (or unpad) argument selects the character to be removed. For example:

<syntaxhighlight>
SAY STRIP(' say what? ') -> 'say What?'
SAY STRIP(' say what? ','L') -> 'say what?
SAY STRIP('++123+++', 'B', '+') -> '123'
</syntaxhighlight>

=== SUBSTR() ===

<nowiki>SUBSTR(string,start[,length][,pad])</nowiki>

Returns the substring of the string argument beginning at the specified start position for the specified length. The starting position must be positive, and the default length is the remaining length of the string. If the substring is shorter than the requested length, it is padded on the right with the blanks or the specified pad character. For example:

<syntaxhighlight>
SAY SUBSTR('123456',4,2) -> 45
SAY SUBSTR('myname',3,6, '=') -> 'name=='
</syntaxhighlight>

=== SUBWORD() ===

<nowiki>SUBWORD(string,n[,length])</nowiki>

Returns the substring of the string argument beginning with the nth word for the specified length in words. The default length is the remaining length of the string. The returned string will never have leading or trailing blanks. For example:

<syntaxhighlight>
SAY SUBWORD('Now is the time ',2,2) -> 'is the'
</syntaxhighlight>

=== SYMBOL() ===

<nowiki>SYMBOL(name)</nowiki>

Tests whether the name argument is a valid ARexx symbol. If the name is not a valid symbol, the function returns the string BAD. If the symbol is uninitialized, the returned string is LIT. If the symbol has been assigned a value, VAR is returned. For example:

<syntaxhighlight>
SAY SYMBOL('J') -> VAR
SAY SYMBOL('x') -> LIT
SAY SYMBOL('++') -> BAD
</syntaxhighlight>

=== TIME() ===

<nowiki>TIME(option)</nowiki>

Returns the current system time or controls the internal elapsed time counter. The valid option keywords are:

; CIVIL
: Current time in 12 hour format (a.m./p.m.) hours/minutes

; ELAPSED
: Elapsed time in seconds since program start

; HOURS
: Current time in hours since midnight

; MINUTES
: Current time in minutes since midnight

; NORMAL
: Current time in 24 hour format (hours/minutes/seconds)

; RESET
: Reset the elapsed time clock

; SECONDS
: Current time in seconds since midnight

If no option is specified, the function returns the current system time in the form HH:MM:SS. For example:

<syntaxhighlight>
/*Suppose that the time is 1:02 AM . . .*/
SAY TIME('C'( -> 1:02 AM
SAY TIME('HOURS') -> 1
SAY TIME('M') -> 62
SAY TIME('N') -> 01:02:54
SAY TIME('S') -> 3720
call TIME('R') /*reset timer*/
SAY TIME('E') -> .020
SAY TIME() -> 01:02:00
</syntaxhighlight>

=== TRACE() ===

<nowiki>TRACE(option)</nowiki>

Sets the tracing mode (see Chapter 6) to that specified by the option keyword, which must be one of the valid alphabetic or prefix options. The TRACE() function will alter the tracing mode even during interactive tracing, when TRACE instructions in the source program are ignored. The returned value is the mode in effect before the function call. This allows the previous trace mode to be restored later. For example:

<syntaxhighlight>
/*Assume tracing mode is ?ALL*/
SAY TRACE('Results') -> ?A
</syntaxhighlight>

=== TRANSLATE() ===

<nowiki>TRANSLATE(string[,output][,input][,pad])</nowiki>

This function constructs a translation table and uses it to replace selected characters in the argument string. If only the string argument is given, it is translated to upper case. If an input table is supplied, it modifies the translation table so that characters in the argument string that occur in the input table are replaced with the corresponding character in the output table. Characters beyond the end of the output table are replaced with the specified pad character or a blank. The result string is always of the same length as the original string. The input and output tables may be of any length. For example:

<syntaxhighlight>
SAY TRANSLATE("abcde", "123", "cbade", "+") -> 321++
SAY TRANSLATE("low") -> LOW
SAY TRANSLATE("0110", "10", "01") -> 1001
</syntaxhighlight>

=== TRIM() ===

<nowiki>TRIM(string)</nowiki>

Removes trailing blanks from the string argument. For example:

<syntaxhighlight>
SAY length (TRIM(' abc ')) -> 4
</syntaxhighlight>

=== TRUNC() ===

<nowiki>TRUNC(number[,places])</nowiki>

Returns the integer part of the number argument followed by the specified number of decimal places. The default number of decimal places is 0. The number is padded with zeroes as necessary. For example:

<syntaxhighlight>
SAY TRUNC(123.456) -> 123
SAY TRUNC(123.456,4) -> 123.4560
</syntaxhighlight>

=== UPPER() ===

<nowiki>UPPER(string)</nowiki>

Translate the string to upper case. The action of this function is equivalent to that of TRANSLATE(string), but it is slightly faster for short strings. For example:

<syntaxhighlight>
SAY UPPER('One Fine Day') -> ONE FINE DAY
</syntaxhighlight>

=== VALUE() ===

<nowiki>VALUE(name)</nowiki>

Returns the value of the symbol represented by the name argument. For example:

<syntaxhighlight>
/*Assume that J has the value 12*/
SAY VALUE('j') -> 12
</syntaxhighlight>

=== VERIFY() ===

<nowiki>VERIFY(string,list[,'MATCH'])</nowiki>

Returns the index of the first character in the string argument which is not contained in the list argument or 0 if all of the characters are in the list. If the MATCH keyword is supplied, the function returns the index of the first character which is in the list or 0 if none of the characters is in the list. For example:

<syntaxhighlight>
SAY VERIFY('123456', '0123456789') -> 0
SAY VERIFY('123a56', '0123456789') -> 4
SAY VERIFY('123a45', 'abcdefghij', 'm') -> 4
</syntaxhighlight>

=== WORD() ===

<nowiki>WORD(string,n)</nowiki>

Returns the nth word in the string argument or the null string if there are fewer than n words. For example:

<syntaxhighlight>
SAY WORD('Now is the time ',2) -> is
</syntaxhighlight>

=== WORDINDEX() ===

<nowiki>WORDINDEX(string,n)</nowiki>

Returns the starting position of the nth word in the argument string or 0 if there are fewer than n words. For example:

<syntaxhighlight>
SAY WORDINDEX('Now is the time ',3) -> 8
</syntaxhighlight>

=== WORDLENGTH() ===

<nowiki>WORDLENGTH(string,n)</nowiki>

Returns the length of the nth word in the string argument. For example:

<syntaxhighlight>
SAY WORDLENGTH('one two three',3) -> 5
</syntaxhighlight>

=== WORDS() ===

<nowiki>WORDS(string)</nowiki>

Returns the number of words in the string argument. For example:

<syntaxhighlight>
SAY WORDS("You don't SAY!") -> 3
</syntaxhighlight>

=== WRITECH() ===

<nowiki>WRITECH(file,string)</nowiki>

Writes the string argument to the given logical file. The returned value is the actual number of characters written. For example:

<syntaxhighlight>
SAY WRITECH('output', 'Testing') -> 7
</syntaxhighlight>

=== WRITELN() ===

<nowiki>WRITELN(file,string)</nowiki>

Writes the string argument to the given logical file with a newline appended. The returned value is the actual number of characters written. For example:

<syntaxhighlight>
SAY WRITELN('output', 'Testing') -> 8
</syntaxhighlight>

=== X2C() ===

<nowiki>X2C(string)</nowiki>

Converts a string of hex digits into the (packed) character representation. Blank characters are permitted in the argument string at byte boundaries. For example:

<syntaxhighlight>
SAY X2C('12ab') -> '12ab'x
SAY X2C('12 ab') -> '12ab'x
SAY X2C(61) -> a
</syntaxhighlight>

=== X2D() ===

<nowiki>X2D(hex,digits)</nowiki>

Converts a hexadecimal number to decimal. For example:

<syntaxhighlight>
SAY X2D('1f') -> 31
</syntaxhighlight>

=== XRANGE() ===

<nowiki>XRANGE([start][,end])</nowiki>

Generates a string consisting of all characters numerically between the specified start and end values. The default start character is '00'x, and the default end character is 'FF'x. Only the first character of the start and end arguments is significant. For example:

<syntaxhighlight>
SAY XRANGE() -> '00010203 . . . FDFEFF'x
SAY XRANGE('a', 'f') -> 'abcdef'
SAY XRANGE(,'0A'x) -> '000102030405060708090A'x
</syntaxhighlight>

== Example Program ==

The following example program illustrates many of the built-in functions that manipulate character strings.

=== Program 13. Changestrings.rexx ===

<syntaxhighlight>
/*This ARexx program shows the effect of built-in functions that change strings. The functions come in two groups: one that manipulates individual characters and one that manipulates whole strings.*/

teststring1 = " every good boy does fine "

/*The first group is composed of the functions STRIP(), COMPRESS(), SPACE(), TRIM(), TRANSLATE(), DELSTR(), DELWORD(), INSERT(), OVERLAY(), and REVERSE().*/

/*STRIP() removes only leading and trailing characters.*/

/*Print the original string, for comparison. We put a period at the end of the string, so you can see what happens to the spaces at the end of the string.*/
SAY " every good boy does fine "

/*The same string stripped of leading and trailing spaces*/
SAY STRIP(" every good boy does fine ")"."

/*Failed attempt to remove leading and trailing "e"s*/
SAY STRIP(" every good boy does fine",,"e")"."

/*The "e"'s were protected by the leading and trailing spaces. Removing them exposes the "e"'s to the effects of STRIP()*/
SAY STRIP("every good boy does fine",,"e")"."

/*Remove "e"'s and spaces from the original string*/
SAY STRIP(" every good boy does fine ",," e")"."

/*We are now using the variable "teststring1", defined above. Remove only the trailing spaces in the test string.*/
SAY STRIP(teststring1, T)"."

/*Remove the trailing spaces and the "e"*/
SAY STRIP(teststring1,T," e")"."

/*Compress() removes characters anywhere in the string. This removes all blanks from the test string*/
SAY COMPRESS(teststring1)

CALL TIME('r')
SAY TIME('Civil') /*Civilian time HH:MM{AM | PM}*/
SAY TIME('h') /*Hours since midnight*/
SAY TIME('m') /*Minutes since midnight*/
SAY TIME('s') /*Seconds since midnight*/
SAY TIME('e') /*Elapsed time since program start*/

/*Function:TRACE Usage: TRACE( [option] )*/
SAY TRACE()
SAY TRACE(TRACE()) /*Leave it unchanged*/

/*Function:TRANSLATE Usage: TRANSLATE(string[,output][,input] [,pad])*/
SAY TRANSLATE('aBCdef') /*Translate to Uppercase*/
SAY TRANSLATE ('abcdef', '1234')
SAY TRANSLATE('654321', 'abcdef', '123456')
SAY TRANSLATE('abcdef', '123', 'abcdef', '+')

/*Function: TRIM Usage: TRIM(string)*/
SAY TRIM(' abc ')

/*Function: TRUNC Usage: TRUNC(number[,places])*/
SAY TRUNC(123.456)
SAY '$'TRUNC(134566.123,2)

/*Function: UPPER Usage: UPPER(string)*/
SAY UPPER('aBCdef12')

/*Function: VALUE Usage: VALUE(name)*/
abc = 'my name'
SAY VALUE('abc')

/*Function: VERIFY Usage: VERIFY(string,list[,'M'])*/
SAY VERIFY('123a45', '0123456789')
SAY VERIFY('abc3de', '012456789', 'M')

/*Function: WORD Usage: WORD(string,n)*/
SAY WORD('Now is the time',3)

/*Function: WORDINDEX Usage: WORDINDEX(string,n)*/
SAY WORDINDEX('Now is the time ',3)

/*Function: WORDLENGTH Usage: WORDLENGTH(string,n)*/
SAY WORDLENGTH('Now is the time ',4)

/*Function: WORDS Usage: WORDS(string)*/
SAY WORDS('Now is the time')

/*Function: WRITECH Usage: WRITECH(logical,string)*/
IF OPEN('test','ram:test$$', 'W') THEN DO
SAY WRITECH('test', 'message') /*Write the string*/
CALL CLOSE 'test'
END

/*Function: WRITELN Usage: WRITELN(logical,string)*/
IF OPEN('test', 'ram:test$$', 'W') THEN DO
SAY WRITELN('test', 'message')
/*Write the string (with newline)*/
CALL CLOSE 'test'
END

/*Function: X2C Usage: X2C(heystring)*/
SAY X2C('616263') /*Convent to character (pack)*/

/*Function: XRANGE Usage: XRANGE([start] [,end])*/
SAY C2X(xrange('f0'x))
SAY XRANGE('a', 'g')
EXIT
</syntaxhighlight>

The output of Program 13 is:

every good boy does fine
every good boy does fine.
every good boy does fine .
very good boy does fin.
very good boy does fin.
every good boy does fine.
every good boy does fin.
everygoodboydoesfine
1:23PM /*These results vary depending*/
13 /*on the time the program is run.*/
803
48199
0.80
N
N
ABCDEF
abcdef
fedcba
123+++
abc
123
$134566.12
ABCDEF12
my name
4
0
the
8
4
4
7
8
abc
F0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF
abcdefg

= REXXSupport.Library Functions =

The functions listed in this section are part of the REXXSupport.library. They may only be used if this library has been opened. Below is an example that shows you how to open this library.

== Program 14. OpenLibrary.rexx ==

<syntaxhighlight>
/*Add rexxsupport.library if it isn't already open.*/
IF ~ SHOW ('L', "rexxsupport.library") THEN DO
/*If the library isn't open, try to open it*/
IF ADDLIB('rexxsupport.library', 0, -30,0)
THEN SAY "Added rexxsupport.library."
ELSE DO
SAY 'ARexx support library not available, exiting'
EXIT 10 /*Exit if ADDLIB() failed*/
END
END
</syntaxhighlight>

== ALLOCMEM() ==

<nowiki>ALLOCMEM(length[,attribute])</nowiki>

Allocates a block of memory of the specified length from the system free-memory pool and returns its address as a four-byte string. The optional attribute parameter must be a standard EXEC memory allocation flag, supplied as a four-byte string. The default attribute is for "PUBLIC" memory (not cleared). Refer to [[Exec_Memory_Allocation|Exec Memory Allocation]] for information on memory types and attribute parameters.

This function should be used whenever memory is allocated for use by external programs. It is the user's responsibility to release the memory space when it is no longer needed. See also FREEMEM(). For example:

<syntaxhighlight>
SAY C2X(ALLOCMEM(1000)) -> 00050000
SAY C2X(ALLOCMEM (1000, '00 01 00 0 1'X)) -> 00228400
/*1000 bytes of CLEAR Public memory*/
</syntaxhighlight>

== CLOSEPORT() ==

<nowiki>CLOSEPORT(name)</nowiki>

Closes the message port specified by the name argument, which must have been allocated by a call to OPENPORT() within the current ARexx program. Any messages received but not yet REPLYed are automatically returned with the return code set to 10. See also OPENPORT(). For example:

<syntaxhighlight>
CALL CLOSEPORT myport
</syntaxhighlight>

== FREEMEM() ==

<nowiki>FREEMEM(address,length)</nowiki>

Releases a block of memory of the given length to the system free list. The address parameter is a four-byte string, typically obtained by a prior call to ALLOCMEM(). FREEMEM() cannot be used to release memory allocated using GETSPACE(), the ARexx internal memory allocator. The returned value is a Boolean success flag. See also ALLOCMEM(). For example:

<syntaxhighlight>
MemoryRequest = 1024
MyMem = ALLOCMEM(MemoryRequest)
SAY C2X(MyMem) -> 07C987B0
SAY FREEMEM(MyMem, MemoryRequest) -> 1
/*Or: SAY FREEMEM('07C987B0'x,1024)*/
</syntaxhighlight>

{{Note|title=Caution|text=Before your program terminates, you must use a matching FREEMEM() to release the exact amount of memory you allocated with each ALLOCMEM(). Otherwise, you may crash the system or leave memory unavailable until you reboot.}}

== GETARG() ==

<nowiki>GETARG(packet[,n])</nowiki>

Extracts a command, function name, or argument string from a message packet. The packet argument must be a four-byte address obtained from a prior call to GETPKT(). The optional [n] argument specifies the slot containing the string to be extracted and must be less than or equal to the actual argument count for the packet. Commands and function names are always in slot 0. Function packets my have argument strings in slots 1-15. For example:

<syntaxhighlight>
command = GETARG(packet)
function = GETARG(packet,0) /*name string*/
arg1 = GETARG(packet,1) /*1st argument*/
</syntaxhighlight>

== GETPKT() ==

<nowiki>GETPKT(name)</nowiki>

Checks the message port specified by the name argument to see whether any messages are available. The named message port must have been opened by a prior call to OPENPRT() within the current ARexx program. The returned value is the four-byte address of the first message packet, or '0000 0000'x if no packets were available.

The function returns immediately whether or not a packet is enqueued at the message port. Programs should never be designed to "busy-loop" on a message port. If there is no useful work to be done until the next message packet arrives, the program should call WAITPKT() and allow other tasks to proceed. See also WAITPKT(). For example:

<syntaxhighlight>
packet = GETPKT ('MyPort')
</syntaxhighlight>

== OPENPORT() ==

<nowiki>OPENPORT(name)</nowiki>

Creates a public message port with the given name. The returned Boolean value indicates whether the port was successfully opened. An initialization failure will occur if another port of the same name already exists or if a signal bit couldn't be allocated. The message port is allocated as a Port Resource node and is linked into the program's global data structure. Ports are automatically closed when the program exits and any pending messages are returned to the sender. See also CLOSEPORT(). For example:

<syntaxhighlight>
success = OPENPORT("MyPort")
</syntaxhighlight>

== REPLY() ==

<nowiki>REPLY(packet,rc)</nowiki>

Returns a message packet to the sender, with the primary result field set to the value given by the rc argument. The secondary result is cleared. The packet argument must be supplied as a four-byte address, and the rc argument must be a whole number. For example:

<syntaxhighlight>
CALL REPLY(packet,10) /*Error return*/
</syntaxhighlight>

== SHOWDIR() ==

<nowiki>SHOWDIR(directory[,'ALL'|'FILE'|'DIR'][,pad])</nowiki>

Returns the contents of the specified directory as a string of names separated by blanks. The second parameter is an option keyword that selects whether all entries, only files, or only subdirectories, will be included. For example:

<syntaxhighlight>
SAY SHOWDIR('SYS:REXXC', 'f', ';') -> WaitForPort;TS;TE;TCO;RXSET;RXLIB;RXC;RX;HI
</syntaxhighlight>

== SHOWLIST() ==

<nowiki>SHOWLIST({`A' | `D' | `H' | `T' | `L' | `M' | `P' | `R' | `S' | `T' | `V' | `W'}[,name][,pad])</nowiki>

An argument is entered using its initial letter. The arguments are:

; A
: ASSIGNS and Assigned Device

; D
: Device Drivers

; H
: Handlers

; I
: Interrupts

; L
: Libraries

; M
: Memory List Items

; P
: Ports

; R
: Resources

; S
: Semaphores

; T
: Tasks (Ready)

; V
: Volume Names

; W
: Waiting Tasks

If only one argument is supplied, SHOWLIST() returns a string separated by blanks: If a pad character is supplied, names will be separated by the pad rather than by blanks. If the name parameter is supplied. SHOWLIST() returns a Boolean value which indicates if the specified list contains that name. Names are case-sensitive. To provide an accurate snapshot of the current list, task switching is forbidden when the list is scanned.

<syntaxhighlight>
SAY SHOWLIST('P') -> REXX MyCon
SAY SHOWLIST('P',,';') -> REXX;MyCon
SAY SHOWLIST('P', 'REXX') -> 1
</syntaxhighlight>

== STATEF() ==

<nowiki>STATEF(filename)</nowiki>

Returns a string containing information about an external file. The string is formatted as:

<nowiki>"{DIR | FILE} length blocks protection days minutes ticks comment."</nowiki>

The length token gives the file length in bytes, and the block token specifies the file length in blocks. For example:

<syntaxhighlight>
SAY STATEF("LIBS:REXXSupport.library")
/*might give "File 2524 5 ----RW-D 4866 817 2088*/
</syntaxhighlight>

== WAITPKT() ==

<nowiki>WAITPKT(name)</nowiki>

Waits for a message to be received at the specified (named) port, which must have been opened by a call to OPENPORT() within the current ARexx program. The returned Boolean value indicates whether a message packet is available at the port. Normally the returned value will be 1 (True), since the function waits until an event occurs at the message port.

The packet must then be removed by a call to GETPKT() and should be returned eventually using the REPLY() function. Any message packets received but not returned when an ARexx program exits are automatically REPLYed with the return code set to 10. For example:

<syntaxhighlight>
CALL WAITPKT 'MyPort' /*Wait awhile*/
</syntaxhighlight>

AmigaOS Manual: ARexx Functions

2014-01-27T10:41:15Z

Tony Wyatt: More typos

A function is a program or group of statements that is executed whenever that function name is called in a particular context. A function may be part of an internal program, part of a library, or a separate external program. Functions are an important building block of modular programming because they allow you to construct large programs from a series of small, easily developed modules.

This chapter explains the different types of functions and how they are evaluated. It also provides an alphabetical reference of ARexx's built-in function library.

= Invoking a Function =

Within a ARexx program, a function is defined as a symbol or string followed immediately by an open parenthesis. The symbol or string (taken as a literal) specifies the function name, and the open parenthesis begins the argument list. Between the opening and closing parentheses are zero or more argument expressions, separated by commas, that supply the data being passed to the function.

Valid function calls are:

<syntaxhighlight>
CENTER ('title', 20)
ADDRESS()
'ALLOCMEM' (256*4,1)
</syntaxhighlight>

Each argument expression is evaluated in turn and the resulting strings are passed as the argument list to the function. Each argument expression, while often just a single literal value, can include arithmetic or string operations or even other function calls. Argument expressions are evaluated from left to right.

Functions can also be invoked using the CALL instruction. The CALL instruction, described in Chapter 4, can be used to invoke a function that may not return a value.

= Types of Functions =

There are three types of functions:

* Internal functions - defined within the ARexx program.
* Built-in functions - supplied by the ARexx programming language.
* Function Libraries - a special Amiga shared library.

== Internal Functions ==

An internal function is identified by a label within the program. When the internal function is called. ARexx creates a new storage environment so that the previous caller's environment is preserved. The new environment inherits the values from its predecessor, but subsequent changes to the environment variables do not affect the previous environment.

The specific values preserved are:

* The current and previous host addresses.
* The NUMERIC DIGITS, FUZZ, and FORM settings.
* The trace option, inhibit flag, and interactive flag.
* The state of the interrupt flags as defined by the SIGNAL instruction.
* The current prompt string as set by the OPTIONS PROMPT instruction.

The new environment does not automatically get a new symbol table, so initially all of the variables in the previous environment are available to the called function. The PROCEDURE instruction can be used to create a table and thereby protect the caller's symbol values. PROCEDURE can also be used to allow the same variable name to be used in two different areas with two different values.

Execution of the internal function proceeds until a RETURN instruction is executed. At this point the new environment is dismantled, and control resumes at the point of the function call. The expression supplied with the RETURN instruction is evaluated and passed back to the caller as the function result.

== Built-In Functions ==

ARexx provides a substantial library of predefined functions as part of the language system. These functions are always available and have been optimized to work with the internal data structures. In general, the built-in functions execute much faster than an equivalent interpreted function, so their usage is strongly recommended.

Several of the built-in functions create and manipulate external AmigaDOS files. Files are referenced by a logical name, a case-sensitive name that is assigned to a file when it is first opened. The initial input and output streams are given the names STDIN (standard input) and STDOUT (standard output). There is no theoretical limit to the number of files that may be open simultaneously, although a limit will be imposed by available memory. All open files are closed automatically when the program exits.

== External Function Libraries ==

A function library is a collection of one or more functions organized as an Amiga shared library. The library must reside in LIBS:, but may be either memory or disk-resident. Disk-resident libraries are loaded and opened as needed.

The library has to be especially tailored for use by ARexx. Each function library must contain a library name, a search priority, an entry point offset, and a version number. When ARexx is searching for a function, the interpreter opens each library and checks its "query" entry point. This entry point must be specified as an integer offset (e.g. "-30") from the library base. The return code from the query call indicates whether the desired function was found. If the function is found, it is called with the parameters passed by the interpreter, and the function result is returned to the caller. If it is not found, a "Function not found" error code is returned, and the search continues with the next library in the list. Function libraries are always closed after being checked so that the operating system can reclaim the memory space if required.

=== The Library List ===

The ARexx resident process maintains a list of the currently available function libraries and function hosts called the Library List. Application programs can add or remove function libraries as required.

The Library List is maintained as a priority-sorted queue. Each entry has an associated search priority in the range 100 (highest) to -100 (lowest). Entries can be added at an appropriate priority to control the function name resolution. Libraries with higher priorities are searched first. Within a given priority level, those libraries added first are searched first. The priority levels are significant if any of the libraries have duplicate function name definitions, since the function located further down the search chain could never be called.

== External Function Hosts ==

The name associated with a function host is the name of its public message port. Function calls are passed to the host as a message packet; it is then up to the individual host to determine whether the specified function name is one that it recognizes. The name resolution is completely internal to the host, so function hosts provide a natural gateway mechanism for implementing remote procedure calls to other machines in a network. The ARexx resident process is a function host and is installed in the Library List with a priority of -60.

= The Search Order =

Function linkages in ARexx are established at the time of the function call. A specific search order is followed until a function matching the name symbol or string is found. If the specified function cannot be located, an error is generated and the expression evaluation is terminated. The full search order is:

; Internal Functions
: The program source is examined for a label that matches the function name. If a match is found, a new storage environment is created and control is transferred to the label.

; Built-In Functions
: The built-in function library is searched for the specified name. All of these functions are defined by uppercase names.

; Function Libraries and Function Hosts
: The available function libraries and function hosts are maintained in the Library List, which is searched starting at the highest priority until the requested function is found or the end of the list is reached. Function hosts are called using a message-passing protocol similar to that used for commands and may be used as gateways for remote procedure calls to other machines in a network.

; External ARexx Programs
: The final search step is to check for an external ARexx program file by sending an invocation message to the ARexx resident process. The search always begins in the current directory and follows the same search path as the original ARexx program invocation. The name matching process is not case-sensitive.

The function name-matching procedure may be case-sensitive for some of the search steps, but not for others. The matching procedure used in a function library or function host is design dependent. Functions defined with mixed-case names must be called using a string token, since symbol names are always translated to uppercase.

The full search order is followed whenever the function name is defined by a symbol token. However, the search for internal functions is bypassed if the name is specified by a string token. This allows internal functions to usurp the names of external functions, as in the following example:

<syntaxhighlight>
CENTER: /*internal "CENTER"*/
ARG string, length /*get arguments*/
length = MIN(length,60) /*compute length*/
return 'CENTER' (string, length)
</syntaxhighlight>

Here the built-in function CENTER() has been replaced by an internal function after modifying the length argument.

= The Clip List =

The Clip List is a publicly accessible mechanism that can be used as a general clipboard for intertask communication. Many functions use the clipboard for retrieving different types of information, such as predefined constants or strings.

The Clip List maintains a set of (name, value) pairs that may be used for a variety of purposes. (SETCLIP() is used to add pairs to the list.) Each entry in the list consists of a name and a value string and may be located by name. In general, the names used should be chosen to be unique to an application to prevent unintended duplications with other programs. Any number of entries may be posted to the list.

One potential application for the Clip List is as a mechanism for loading predefined constants into an ARexx program. For example:

<syntaxhighlight>
pi=3.14159; e=2.718; sqrt2=1.414 . . .
</syntaxhighlight>

(i.e., a series of assignments separated by semicolons). In use, such a string could be retrieved by name using the built-in function GETCLIP() and then INTERPRETed within the program. The assignment statements within the string would then create the required constant definitions. For example:

<syntaxhighlight>
/*Assume a string called "numbers" is available*/
numbers = GETCLIP ('numbers')
INTERPRET numbers /*. . . assignments*/
</syntaxhighlight>

The strings would not be restricted to contain only assignment statements, but could include any valid ARexx statements. The Clip List could thus provide a series of programs for initializations or other processing tasks.

The resident process supports addition and deletion operations for maintaining the Clip List. The names in the (name,value) pairs are assumed to be in mixed case and are maintained to be unique in the list. An attempt to add a string with an existing name will simply update the value string. The name and value strings are copied when an entry is posted to the list, so the program that adds an entry is not required to maintain the strings.

Entries posted to the Clip List remain available until explicitly removed. The Clip List is automatically released when the resident process exits.

= Built-in Functions Reference =

This section provides an alphabetical list of the built-in functions. The syntax of each function is shown to the right of the function keyword.

== Syntax ==

Optional arguments are shown in brackets and generally have a default value that is used if the argument is omitted. When an option keyword is specified as an argument, only the first character is significant. Option keywords are not case-sensitive.

Many functions accept a pad character argument. Pad characters are inserted to fill or create spaces. For functions that accept a pad argument, only the first character of the argument string is significant. If a null string is supplied, the default padding character, usually a blank, will be used.

In the following examples, an arrow (->) is used as an abbreviation for "evaluates as." The arrow will not be displayed when a program is run. For example:

<syntaxhighlight>
SAY ABS (-5.35) -> 5.35
</syntaxhighlight>

This means that SAY ABS(-5.35) is evaluated as 5.35.

== Alphabetical Reference ==

=== ABBREV() ===

<nowiki>ABBREV(string1,string2[,length])</nowiki>

Returns a Boolean value that indicates whether string2 is an abbreviation of string1 with length greater than or equal to the specified length argument. The default length is 0, so the null string is an acceptable abbreviation. For example:

<syntaxhighlight>
SAY ABBREV ('fullname', 'ful') -> 1
SAY ABBREV ('almost', 'alm',4) -> 0
SAY ABBREV ('any','') -> 1
</syntaxhighlight>

=== ABS() ===

<nowiki>ABS(number)</nowiki>

Returns the absolute value of the number argument. This value must be numeric. For example:

<syntaxhighlight>
SAY ABS(-5.35) -> 5.35
SAY ABS(10) -> 10
</syntaxhighlight>

=== ADDLIB() ===

<nowiki>ADDLIB(name,priority[,offset,version])</nowiki>

Adds a function library or a function host to the library list maintained by the resident process. The name argument specifies either the name of a function library or the public message port associated with a function host. The name is case-sensitive. Any specified libraries should reside in the system LIBS: directory.

The priority argument specifies the search priority and must be an integer between 100 and -100, inclusive. The offset and version arguments apply only to libraries. The offset is the integer offset to the library's "query" entry point, and the version is an integer specifying the minimum acceptable release level of the library.

The function returns a Boolean result that indicates whether the operation was successful. If a library is specified, it is not actually opened at this time. Similarly, ARexx does not check to see whether a specified function host port is open. For example:

<syntaxhighlight>
SAY ADDLIB ("rexxsupport.library",0,-30,0) -> 1
CALL ADDLIB "EtherNet",-20 /*A gateway*/
</syntaxhighlight>

=== ADDRESS() ===

<nowiki>ADDRESS()</nowiki>

Returns the current host address string. The host address is the message port to which commands will be sent. The SHOW() function can be used to check whether the required external host is actually available. See also SHOW(). For example:

<syntaxhighlight>
SAY ADDRESS() -> REXX
</syntaxhighlight>

=== ARG() ===

<nowiki>ARG([number][,'EXISTS'|'OMITTED'])</nowiki>

ARG() returns the number of arguments supplied to the current environment. If only the number parameter is supplied, the corresponding argument string is returned. If a number and the Exists or Omitted keyword is given, the Boolean return indicates the status of the corresponding argument. The existence or omission test does not indicate whether the string has a null value, but only whether a string was supplied. For example:

<syntaxhighlight>
/*Assume arguments were: ('one',,10)*/
SAY ARG() -> 3
SAY ARG(1) -> one
SAY ARG(2,'O') -> 1
</syntaxhighlight>

=== B2C() ===

<nowiki>B2C(string)</nowiki>

Converts a string of binary digits (0,1) into the corresponding (packed) character representation. The conversion is the same as though the argument string had been specified as a literal binary string (e.g. `1010'B). Blanks are permitted in the string, but only at byte boundaries. This function is particularly useful for creating strings that are to be used as bit masks. See also X2C(). For example:

<syntaxhighlight>
SAY B2C('00110011') -> 3
SAY B2C('01100001') -> a
</syntaxhighlight>

=== BITAND() ===

<nowiki>BITAND(string1,string2[,pad])</nowiki>

The argument strings are logically ANDed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITAND('0313'x, 'FFF0'x) -> '0310'x
</syntaxhighlight>

=== BITCHG() ===

<nowiki>BITCHG(string,bit)</nowiki>

Changes the state of the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITCHG('0313'x,4) -> '0303'x
</syntaxhighlight>

=== BITCLR() ===

<nowiki>BITCLR(string,bit)</nowiki>

Clears (sets to zero) the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITCLR('0313'x,4) -> '0303'x
</syntaxhighlight>

=== BITCOMP() ===

<nowiki>BITCOMP(string1,string2[,pad])</nowiki>

Compares the argument strings bit-by-bit, starting at bit number 0. The returned value is the bit number of the first bit in which the strings differ, or -1 if the strings are identical. For example:

<syntaxhighlight>
BITCOMP('7F'x, 'FF'x) -> 7 /*Seventh bit*/
BITCOMP('FF'x, 'FF'x) -> -1
</syntaxhighlight>

=== BITOR() ===

<nowiki>BITOR(string1,string2[,pad])</nowiki>

The argument strings are logically ORed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITOR('0313'x, '00F'x) -> '033F'x
</syntaxhighlight>

=== BITSET() ===

<nowiki>BITSET(string,bit)</nowiki>

Sets the specified bit in the argument string to 1. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITSET('313'x,2) -> '0317'x
</syntaxhighlight>

=== BITTST() ===

<nowiki>BITTST(string,bit)</nowiki>

The Boolean return indicates the state of the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITTST('0313=x,4) -> 1
</syntaxhighlight>

=== BITXOR() ===

<nowiki>BITXOR(string1,string2[,pad])</nowiki>

The argument strings are logically and exclusively-ORed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITXOR('0313'x, '001F'x) -> '030C'X
</syntaxhighlight>

=== C2B() ===

<nowiki>C2B(string)</nowiki>

Converts the character string into the equivalent string of binary digits. See also C2X(). For example:

<syntaxhighlight>
SAY C2B('abc') -> 011000010110001001100011
</syntaxhighlight>

=== C2D() ===

<nowiki>C2D(string[,n])</nowiki>

Converts the string argument from its character representation to the corresponding decimal number, expressed as ASCII digits (0-9). If n is supplied, the character string is considered to be a number expressed in n bytes. The string is truncated or padded with nulls on the left as required, and the sign bit is extended for the conversion. For example:

<syntaxhighlight>
SAY C2D('0020'x) -> 32
SAY C2D('FFFF ffff'x) -> -1
SAY C2D('FF0100'x,2) -> 256
</syntaxhighlight>

=== C2X() ===

<nowiki>C2X(string)</nowiki>

Converts the string argument from its character representation to the corresponding hexadecimal number, expressed as the ASCII characters 0-9 and A-F. See also C2B(). For example:

<syntaxhighlight>
SAY C2X('abc') -> 616263
</syntaxhighlight>

=== CENTER()/CENTRE() ===

<nowiki>CENTER(string,length[,pad])</nowiki>
<nowiki>CENTRE(string,length[,pad])</nowiki>

Centers the string argument in a string with the specified length. If the length is longer than that of the string, pad characters or blanks are added as necessary. For example:

<syntaxhighlight>
SAY CENTER('abc',6) -> ' abc '
SAY CENTER('abc',6,'+') -> '+abc++'
SAY CENTER ('123456',3) -> '234'
</syntaxhighlight>

=== CLOSE() ===

<nowiki>CLOSE(file)</nowiki>

Closes the file specified by the given logical name. The returned value is a Boolean success flag and will be 1 unless the specified file was not open. For example:

<syntaxhighlight>
SAY CLOSE('input') -> 1
</syntaxhighlight>

=== COMPARE() ===

<nowiki>COMPARE(string1,string2[,pad])</nowiki>

Compares two strings and returns the index of the first position in which they differ or 0 if the strings are identical. The shorter string is padded as required using the supplied character or blanks. For example:

<syntaxhighlight>
SAY COMPARE('abcde', 'abcce') -> 4
SAY COMPARE('abcde', 'abcde') -> 0
SAY COMPARE('abc++', 'abc+-', '+') -> 5
</syntaxhighlight>

=== COMPRESS() ===

<nowiki>COMPRESS(string[,list])</nowiki>

If the list argument is omitted, the function removes leading, trailing or embedded blank characters from the string argument. If the optional list is supplied, it specifies the characters to be removed from the string. For example:

<syntaxhighlight>
SAY COMPRESS(' why not ') -> whynot
SAY COMPRESS('++12-34-+', '+-') -> 1234
</syntaxhighlight>

=== COPIES() ===

<nowiki>COPIES(string,number)</nowiki>

Creates a new string by concatenating the specified number of copies of the original. The number argument may be zero, in which case the null string is returned. For example:

<syntaxhighlight>
SAY COPIES('abc',3) -> abcabcabc
</syntaxhighlight>

=== D2C() ===

<nowiki>D2C(number)</nowiki>

Creates a string whose value is the binary (packed) representation of the given decimal number. For example:

<syntaxhighlight>
D2C(65) -> A
</syntaxhighlight>

=== D2X() ===

<nowiki>D2X(number[,digits])</nowiki>

Converts a decimal number to hexadecimal. For example:

<syntaxhighlight>
D2X(31) -> 1F
</syntaxhighlight>

=== DATATYPE() ===

<nowiki>DATATYPE(string[,option])</nowiki>

If only the string argument is specified, DATATYPE() tests whether the string parameter is a valid number and returns either NUM or CHAR. If an option keyword is given, the Boolean return indicates whether the string satisfied the requested test. The following option keywords are recognized:

; ALPHANUMERIC
: Accepts alphabetic (A-Z, a-z) or numeric (0-9) characters

; BINARY
: Accepts a binary digits string

; LOWERCASE
: Accepts lower case alphabetic (a-z) characters

; MIXED
: Accepts mixed upper/lower case characters

; NUMERIC
: Accepts valid numbers

; SYMBOL
: Accepts valid REXX symbols

; UPPER
: Accepts upper case alphabetic (A-Z) characters

; WHOLE
: Accepts integer numbers

; X
: Accepts Hex digit strings

For example:

<syntaxhighlight>
SAY DATATYPE('123') -> NUM
SAY DATATYPE('1a f2', 'X') -> 1
SAY DATATYPE('aBcde', 'L') -> 0
</syntaxhighlight>

=== DATE() ===

<nowiki>DATE([option][,date][format])</nowiki>

Returns the current date in the specified format. The default (`NORMAL') option returns the date in the form DD MMM YYYY, as in 20 APR 1988. The options recognized are:

; BASEDATE
: The number of days since January 1, 0001

; CENTURY
: The number of days since January 1 of the century

; DAYS
: The number of days since January 1 of the current year

; EUROPEAN
: The date in the form DD/MM/YY

; INTERNAL
: Internal system days

; JULIAN
: The date in the form YYDDD

; MONTH
: The current month (in mixed case)

; NORMAL
: The date in the form DD MMM YYYY

; ORDERED
: The date in the form YY/MM/DD

; SORTED
: The date in the form YYYYMMDD

; USA
: The date in the form MM/DD/YY

; WEEKDAY
: The day of the week (in mixed case)

These options can be shortened to just the first character.

The DATE() function also accepts optional second and third arguments to supply the date either in the form of internal system days or in the 'sorted' form YYYYMMDD. The second argument is specifying either system days (the default) or a sorted date. The third argument specifies the form of the date and can be either 'I' or 'S'. The current date in system days can be retrieved using DATE('INTERNAL'). For example:

<syntaxhighlight>
SAY DATE() -> 14 Jul 1992
SAY DATE('M') -> July
SAY DATE(S) -> 19920714
SAY DATE('S' ,DATE('I')+21) -> 19920804
SAY DATE('W' ,19890609, 'S') -> Friday
</syntaxhighlight>

=== DELSTR() ===

<nowiki>DELSTR(string,n[,length])</nowiki>

Deletes the substring of the string argument beginning with the nth character for the specified length in characters. The default length is the remaining length of the string. For example:

<syntaxhighlight>
SAY DELSTR('123456',2,3) -> 156
</syntaxhighlight>

=== DELWORD() ===

<nowiki>DELWORD(string,n[,length])</nowiki>

Deletes the substring of the string argument beginning with the nth word for the specified length in words. The default length is the remaining length of the string. The deleted string includes any trailing blanks following the last word. For example:

<syntaxhighlight>
SAY DELWORD('Tell me a story',2,2) -> 'Tell story'
SAY DELWORD('one two three',3) -> 'one two '
</syntaxhighlight>

=== DIGITS() ===

<nowiki>DIGITS()</nowiki>

Returns the current Numeric Digits setting. For example:

<syntaxhighlight>
NUMERIC DIGITS 6
SAY DIGITS() -> 6
</syntaxhighlight>

=== EOF() ===

<nowiki>EOF(file)</nowiki>

Checks the specified logical file name and returns the Boolean value 1 (True), if the end-of-file has been reached, and 0 (False) otherwise. For example:

<syntaxhighlight>
SAY EOF(infile) -> 1
</syntaxhighlight>

=== ERRORTEXT() ===

<nowiki>ERRORTEXT(n)</nowiki>

Returns the error message associated with the specified ARexx error code. The null string is returned if the number is not a valid error code. For example:

<syntaxhighlight>
SAY ERRORTEXT(41) -> Invalid expression
</syntaxhighlight>

=== EXISTS() ===

<nowiki>EXISTS(filename)</nowiki>

Tests whether an external file of the given filename exists. The name string may include device and directory specifications. For example:

<syntaxhighlight>
SAY EXISTS('SYS:C/ED') -> 1
</syntaxhighlight>

=== EXPORT() ===

<nowiki>EXPORT(address[,string][,length][,pad])</nowiki>

Copies data from the optional string into a previously-allocated memory area. This memory area must be specified as a four-byte address. The length parameter specifies the maximum number of characters to be copied. The default is the length of the string. If the specified length is longer than the string, the remaining area is filled with the pad character or nulls ('00'x). The returned value is the number of characters copied.

{{Note|title=Caution|text=Any area of memory can be overwritten, possibly causing a system crash. Task switching is forbidden while the copy is being done, so system performance may be degraded if long strings are copied.}}

See also IMPORT() and STORAGE(). For example:

<syntaxhighlight>
count = EXPORT('0004 0000'x, 'The answer')
</syntaxhighlight>

=== FIND() ===

<nowiki>FIND(string,phrase)</nowiki>

The FIND() function locates a phrase of words in a larger string of words and returns the word number of the matched position. For example:

<syntaxhighlight>
SAY FIND('Now is the time', 'is the') -> 2
</syntaxhighlight>

=== FORM() ===

<nowiki>FORM()</nowiki>

Returns the current NUMERIC FORM setting. For example:

<syntaxhighlight>
NUMERIC FORM SCIENTIFIC
SAY FORM() -> SCIENTIFIC
</syntaxhighlight>

=== FREESPACE() ===

<nowiki>FREESPACE(address,length)</nowiki>

Returns a block of memory of a given length to the interpreter's internal pool. The address argument must be a 4 byte string obtained by a prior call to GETSPACE(), the internal allocator. It is not always necessary to release internally allocated memory, since it will be released to the system when the program terminates. However, if a very large block has been allocated, returning it to the pool may avoid memory space problems. The return value is a Boolean success flag. See also GETSPACE().

Calling FREESPACE() with no arguments will return the amount of memory available in the interpreter's internal pool. For example:

<syntaxhighlight>
FREESPACE('00042000'x,32) -> 1
</syntaxhighlight>

=== FUZZ() ===

<nowiki>FUZZ()</nowiki>

Returns the current NUMERIC FUZZ setting. For example:

<syntaxhighlight>
NUMERIC FUZZ 3
SAY FUZZ() -> 3
</syntaxhighlight>

=== GETCLIP() ===

<nowiki>GETCLIP(name)</nowiki>

Searches the Clip List for an entry matching the supplied name parameter and returns the associated value string. The name matching is case-sensitive. The null string is returned if the name cannot be found. See also SETCLIP(). For example:

<syntaxhighlight>
/*Assume 'numbers' contains 'PI=3.14159'*/
SAY GETCLIP('numbers') -> PI=3.14159
</syntaxhighlight>

=== GETSPACE() ===

<nowiki>GETSPACE(length)</nowiki>

Allocates a block of memory of the specified length from the interpreter's internal pool. The returned value is the four-byte address of the allocated block, which is not cleared or otherwise initialized. Internal memory is automatically returned to the system when the ARexx program terminates, so this function should not be used to allocate memory for use by external programs. The REXXSupport.Library includes the function ALLOCMEM(), which allocates memory from the system free list. See also FREESPACE(). For example:

<syntaxhighlight>
SAY C2X (GETSPACE(32)) -> '0003BF40'x
</syntaxhighlight>

=== HASH() ===

<nowiki>HASH(string)</nowiki>

Returns the hash attribute of a string as a decimal number and updates the internal hash value of the string. For example:

<syntaxhighlight>
SAY HASH('1') -> 49
</syntaxhighlight>

=== IMPORT() ===

<nowiki>IMPORT(address[,length])</nowiki>

Creates a string by copying data from the specified four-byte address. If the length parameter is not supplied, the copy terminates when a null byte is found. See also EXPORT(). For example:

<syntaxhighlight>
extval = IMPORT('0004 0000'x,8)
</syntaxhighlight>

=== INDEX() ===

<nowiki>INDEX(string,pattern[,start])</nowiki>

Searches for the first occurrence of the pattern argument in the string argument, beginning at the specified start position. The default start position is 1. The returned value is the index of the matched pattern or 0 if the pattern was not found. For example:

<syntaxhighlight>
SAY INDEX("123456", "23") -> 2
SAY INDEX("123456", "77") -> 0
SAY INDEX("123123", "23",3) -> 5
</syntaxhighlight>

=== INSERT() ===

<nowiki>INSERT(new,old[,start][,length][,pad])</nowiki>

Inserts the new string into the old string after the specified start position. The default starting position is 0. The new string is truncated or padded to the specified length as required, using the supplied pad character or blanks. If the start position is beyond the end of the string, the old string is padded on the right. For example:

<syntaxhighlight>
SAY INSERT('ab', '12345') -> ab12345
SAY INSERT('123', '++',3,5, '-') -> ++-123--
</syntaxhighlight>

=== LASTPOS() ===

<nowiki>LASTPOS(pattern,string[,start])</nowiki>

Searches backwards for the first occurrence of the pattern argument in the string argument, beginning at the specified start position. The default starting position is the end of the string. The returned value is the index of the matched pattern or 0 if the pattern was not found. For example:

<syntaxhighlight>
SAY LASTPOS('2', '1234') -> 2
SAY LASTPOS('2', '1234234') -> 5
SAY LASTPOS('2', '123234',3) -> 2
SAY LASTPOS('2', '13579') -> 0
</syntaxhighlight>

=== LEFT() ===

<nowiki>LEFT(string,length[,pad])</nowiki>

Returns the leftmost substring in the given string argument with the specified length. If the substring is shorter than the requested length, it is padded on the right with the supplied pad character or blanks. For example:

<syntaxhighlight>
SAY LEFT('123456',3) -> 123
SAY LEFT('123456',8, '+') -> 123456++
</syntaxhighlight>

=== LENGTH() ===

<nowiki>LENGTH(string)</nowiki>

Returns the length of the string. For example:

<syntaxhighlight>
SAY LENGTH('three') -> 5
</syntaxhighlight>

=== LINES() ===

<nowiki>LINES(file)</nowiki>

Returns the number of lines queued or typed ahead at the logical file, which must refer to an interactive stream. The line count is obtained as the secondary result of a WaitForChar() call. For example:

<syntaxhighlight>
PUSH 'a line'
PUSH 'another one'
SAY LINES(STDIN) -> 2
</syntaxhighlight>

=== MAX() ===

<nowiki>MAX(number,number[,number,...])</nowiki>

Returns the maximum of the supplied arguments, all of which must be numeric. At least two parameters must be supplied. For example:

<syntaxhighlight>
SAY MAX(2.1,3,-1) -> 3
</syntaxhighlight>

=== MIN() ===

<nowiki>MIN(number,number[,number,...])</nowiki>

Returns the minimum of the supplied arguments, all of which must be numeric. At least two parameters must be supplied. For example:

<syntaxhighlight>
SAY MIN(2.1,3,-1) -> -1
</syntaxhighlight>

=== OPEN() ===

<nowiki>OPEN(file,filename[,'APPEND'|'READ'|'WRITE'])</nowiki>

Opens an external file for the specified operation. The file argument defines the logical name by which the file will be referenced. The filename is the external name of the file and may include device and directory specifications. The function returns a Boolean value that indicates whether the operation was successful. There is no limit to the number of files that can be open simultaneously, and all open files are closed automatically when the program exits. See also CLOSE(), READ(), and WRITE(). For example:

<syntaxhighlight>
SAY OPEN('MyCon', 'CON:160/50/320/100/MyCON/cds') P-> 1
SAY OPEN('outfile', 'ram:temp', 'W') -> 1
</syntaxhighlight>

=== OVERLAY() ===

<nowiki>OVERLAY(new,old[,start][,length][,pad])</nowiki>

Overlays the new string onto the old string beginning at the specified start position, which must be positive. The default starting position is 1. The new string is truncated or padded to the specified length as required, using the supplied pad character or blanks. If the start position is beyond the end of the old string, the old string is padded on the right. For example:

<syntaxhighlight>
SAY OVERLAY('bb', 'abcd') -> bbcd
SAY OVERLAY('4', '123',5,5, '-') -> 123-4----
</syntaxhighlight>

=== POS() ===

<nowiki>POS(pattern,string[,start])</nowiki>

Searches for the first occurrence of the pattern argument in the string argument, beginning at the position specified by the start argument. The default starting position is 1. The value is the index of the matched string or 0 if the pattern wasn't found. For example:

<syntaxhighlight>
SAY POS('23', '123234') -> 2
SAY POS('77', '123234') -> 0
SAY POS('23', '123234',3) -> 4
</syntaxhighlight>

=== PRAGMA() ===

<nowiki>PRAGMA(option[,value])</nowiki>

This function allows a program to change various attributes relating to the system environment within which the program executes. The option argument is a keyword that specifies an environmental attribute. The value argument supplies the new attribute value to be installed. The value returned by the function depends on the attribute selected. Some attributes return the previous value installed, while others may simply set a Boolean success flag.

The currently defined option keywords are:

; DIRECTORY
: Specifies a new current directory. The current directory is used as the root for filenames that do not explicitly include a device specification. The return is the old directory name. PRAGMA('D') is equivalent to PRAGMA('D',"). It returns the path of the current directory without changing the directory.

; PRIORITY
: Specifies a new task priority. The priority value must be an integer in the range - 128 to 127, but the practical range is much more limited. ARexx programs should never be run at a priority higher than that of the resident process, which currently runs at a priority of 4. The returned value is the previous priority level.

; ID
: Returns the task ID (the address of the task block) as an 8-character hex string. The task ID is a unique identifier of the particular ARexx invocation and may be used to create a unique name for it.

; STACK
: Specifies a new stack value for your current ARexx program. When a new stack value is declared, the previous stack value is returned.

The currently implemented options are:

; PRAGMA('W',{'NULL'|' WORKBENCH'})
: Controls the task's WindowPtr field. Setting it to 'NULL' will suppress any requesters that might otherwise be generated by a DOS call.

; PRAGMA('*'[,name])
: Defines the specified logical name as the current ("*") console handler, allowing the user to open two streams on one window. If the name is omitted, the console handler is set to that of the client's process.

<syntaxhighlight>
SAY PRAGMA('D', 'DF0:C') -> Extras
SAY PRAGMA('D', 'DF1:C') -> Workbench:C
SAY PRAGMA('PRIORITY', -5) -> 0
SAY PRAGMA('ID') -> 00221ABC
CALL PRAGMA '*',STDOUT
SAY PRAGMA("STACK",8092) -> 4000
</syntaxhighlight>

=== RANDOM() ===

<nowiki>RANDOM([MIN][,MAX][,seed])</nowiki>

Returns a pseudo-random integer in the interval specified by the min and max arguments. The default minimum value is 0 and the default maximum value is 999. The interval max-min must be less than or equal to 1000. If a greater range of random integers is required, the values from the RANDU() function can be suitably scaled and translated. The seed argument can be supplied to initialize the internal state of the random number generator. See also RANDU(). For example:

<syntaxhighlight>
thisroll = RANDOM(1,6) /*Might be 1*/
nextroll = RANDOM(1,6) /*Might be snake eyes*/
</syntaxhighlight>

=== RANDU() ===

<nowiki>RANDU([seed])</nowiki>

Returns a uniformly-distributed, pseudo-random number between 0 and 1. The number of digits of precision in the result is always equal to the current Numeric Digits setting. With the choice of suitable scaling and translation values, RANDU() can be used to generate pseudo-random numbers on an arbitrary interval.

The optional integer seed argument is used to initialize the internal state of the random number generator. See also RANDOM(). For example:

<syntaxhighlight>
firsttry = RANDU() /*0.371902021?*/
NUMERIC DIGITS 3
tryagain = RANDU () /*0.873?*/
</syntaxhighlight>

=== READCH() ===

<nowiki>READCH(file,length)</nowiki>

Reads the specified number of characters from the given logical file into a string. The length of the returned string is the actual number of characters read and may be less than the requested length if, for example, the end-of-file was reached. See also READLN(). For example:

<syntaxhighlight>
instring = READCH('input',10)
</syntaxhighlight>

=== READLN() ===

<nowiki>READLN(file)</nowiki>

Reads characters from the given logical file into a string until a newline character is found. The returned string does not include the newline. See also READCH(). For example:

<syntaxhighlight>
instring = READLN('MyFile')
</syntaxhighlight>

=== REMLIB() ===

<nowiki>REMLIB(name)</nowiki>

Removes an entry with the given name from the Library List maintained by the resident process. The Boolean return is 1 if the entry was found and successfully removed. This function does not make a distinction between function libraries and function hosts, but simply removes a named entry. See also ADDLIB(). For example:

<syntaxhighlight>
SAY REMLIB('MyLibrary.library') -> 1
</syntaxhighlight>

=== REVERSE() ===

<nowiki>REVERSE(string)</nowiki>

Reverses the sequence of characters in the string. For example:

<syntaxhighlight>
SAY REVERSE('?ton yhw') -> why not?
</syntaxhighlight>

=== RIGHT() ===

<nowiki>RIGHT(string,length[,pad])</nowiki>

Returns the rightmost substring in the given string argument with the specified length. If the substring is shorter than the requested length, it is padded on the left with the supplied pad character or blanks. For example:

<syntaxhighlight>
SAY RIGHT('123456',4) -> 3456
SAY RIGHT('123456',8, '+') -> ++123456
</syntaxhighlight>

=== SEEK() ===

<nowiki>SEEK(file,offset[,'BEHIN'|'CURRENT'|'END'])</nowiki>

Moves to a new position in the given logical file, specified as an offset from an anchor position. The default anchor is Current. The returned value is the new position relative to the start of the file. For example:

<syntaxhighlight>
SAY SEEK('input',10,'B') -> 10
SAY SEEK('input',0,E') -> 356 /*file length*/
</syntaxhighlight>

=== SETCLIP() ===

<nowiki>SETCLIP(name[,value])</nowiki>

Adds a name-value pair to the Clip List maintained by the resident process. If an entry of the same name already exists, its value is updated to the supplied value string. Entries may be removed by specifying a null value. The function returns a Boolean value that indicates whether the operation was successful. For example:

<syntaxhighlight>
SAY SETCLIP('path', 'DF0:s') -> 1
SAY SETCLIP('path') -> 1
</syntaxhighlight>

=== SHOW() ===

<nowiki>SHOW(option[,name][,pad])</nowiki>

Returns the names in the resource list specified by the option argument, or tests to see whether an entry with the specified name is available. The currently implemented options keywords are:

; CLIP
: Examines the names in the Clip List

; FILES
: Examines the currently open logical file names

; LIBRARIES
: Examines the names in the Library List, which are either function libraries or function hosts.

; PORTS
: Examines the names in the system Ports List

If the name argument is omitted, the function returns a string with the resource names separated by a blank space or the pad character, if one was supplied. If the name argument is given, the returned Boolean value indicates whether the name was found in the resource list. The name entries are case-sensitive.

=== SIGN() ===

<nowiki>SIGN(number)</nowiki>

Returns 1 if the number argument is positive or zero and -1 if the number is negative. The argument must be numeric. For example:

<syntaxhighlight>
SAY SIGN(12) -> 1
SAY SIGN(-33) -> -1
</syntaxhighlight>

=== SOURCELINE() ===

<nowiki>SOURCELINE([line])</nowiki>

Returns the text for the specified line of the currently executing ARexx program. If the line argument is omitted, the function returns the total number of lines in the file. This function is often used to embed "help" information in a program. For example:

<syntaxhighlight>
/*A simple test program*/
SAY SOURCELINE() -> 3
SAY SOURCELINE(1)-> /*A simple test program*/
</syntaxhighlight>

=== SPACE() ===

<nowiki>SPACE(string,n[,pad])</nowiki>

Reformats the string argument so that there are n spaces (blank characters) between each pair of words. If the pad character is specified, it is used instead of blanks as the separator character. Specifying n as 0 will remove all blanks from the string. For example:

<syntaxhighlight>
SAY SPACE('Now is the time',3) -> 'Now is the time'
SAY SPACE('Now is the time',0) -> 'Nowisthetime'
SAY SPACE('1 2 3',1, '+') -> '1+2+3'
</syntaxhighlight>

=== STORAGE() ===

<nowiki>STORAGE([address][,string][,length][,pad])</nowiki>

STORAGE() with no arguments returns the available system memory. If the address argument is given, it must be a four-byte string. The function copies data from the (optional) string to the indicated memory address. The length parameter specifies the maximum number of bytes to be copied and defaults to the length of the string. If the specified length is longer than the string, the remaining area is filled with the pad character or nulls ('00'x).

The returned value is the previous contents of the memory area. This can be used in a subsequent call to restore the original contents. See also EXPORT().

{{Note|title=Caution|text=Any area of memory can be overwritten, possibly causing a system crash. Task switching is forbidden while the copy is being done, so system performance may be degraded if long strings are copied.}}

For example:

<syntaxhighlight>
SAY STORAGE() -> ' 248400
oldval = STORAGE('0004 0000'x, 'The answer')
CALL STORAGE '0004 0000'x,,32, '+'
</syntaxhighlight>

=== STRIP() ===

<nowiki>STRIP(string[,{`B' | `L' | `T'}][,pad])</nowiki>

If neither of the optional parameters is supplied, the function removes both leading and trailing blanks from the string argument. The second argument specifies whether Leading, Trailing or Both (leading and trailing) characters are to be removed. The optional pad (or unpad) argument selects the character to be removed. For example:

<syntaxhighlight>
SAY STRIP(' say what? ') -> 'say What?'
SAY STRIP(' say what? ','L') -> 'say what?
SAY STRIP('++123+++', 'B', '+') -> '123'
</syntaxhighlight>

=== SUBSTR() ===

<nowiki>SUBSTR(string,start[,length][,pad])</nowiki>

Returns the substring of the string argument beginning at the specified start position for the specified length. The starting position must be positive, and the default length is the remaining length of the string. If the substring is shorter than the requested length, it is padded on the right with the blanks or the specified pad character. For example:

<syntaxhighlight>
SAY SUBSTR('123456',4,2) -> 45
SAY SUBSTR('myname',3,6, '=') -> 'name=='
</syntaxhighlight>

=== SUBWORD() ===

<nowiki>SUBWORD(string,n[,length])</nowiki>

Returns the substring of the string argument beginning with the nth word for the specified length in words. The default length is the remaining length of the string. The returned string will never have leading or trailing blanks. For example:

<syntaxhighlight>
SAY SUBWORD('Now is the time ',2,2) -> 'is the'
</syntaxhighlight>

=== SYMBOL() ===

<nowiki>SYMBOL(name)</nowiki>

Tests whether the name argument is a valid ARexx symbol. If the name is not a valid symbol, the function returns the string BAD. If the symbol is uninitialized, the returned string is LIT. If the symbol has been assigned a value, VAR is returned. For example:

<syntaxhighlight>
SAY SYMBOL('J') -> VAR
SAY SYMBOL('x') -> LIT
SAY SYMBOL('++') -> BAD
</syntaxhighlight>

=== TIME() ===

<nowiki>TIME(option)</nowiki>

Returns the current system time or controls the internal elapsed time counter. The valid option keywords are:

; CIVIL
: Current time in 12 hour format (a.m./p.m.) hours/minutes

; ELAPSED
: Elapsed time in seconds since program start

; HOURS
: Current time in hours since midnight

; MINUTES
: Current time in minutes since midnight

; NORMAL
: Current time in 24 hour format (hours/minutes/seconds)

; RESET
: Reset the elapsed time clock

; SECONDS
: Current time in seconds since midnight

If no option is specified, the function returns the current system time in the form HH:MM:SS. For example:

<syntaxhighlight>
/*Suppose that the time is 1:02 AM . . .*/
SAY TIME('C'( -> 1:02 AM
SAY TIME('HOURS') -> 1
SAY TIME('M') -> 62
SAY TIME('N') -> 01:02:54
SAY TIME('S') -> 3720
call TIME('R') /*reset timer*/
SAY TIME('E') -> .020
SAY TIME() -> 01:02:00
</syntaxhighlight>

=== TRACE() ===

<nowiki>TRACE(option)</nowiki>

Sets the tracing mode (see Chapter 6) to that specified by the option keyword, which must be one of the valid alphabetic or prefix options. The TRACE() function will alter the tracing mode even during interactive tracing, when TRACE instructions in the source program are ignored. The returned value is the mode in effect before the function call. This allows the previous trace mode to be restored later. For example:

<syntaxhighlight>
/*Assume tracing mode is ?ALL*/
SAY TRACE('Results') -> ?A
</syntaxhighlight>

=== TRANSLATE() ===

<nowiki>TRANSLATE(string[,output][,input][,pad])</nowiki>

This function constructs a translation table and uses it to replace selected characters in the argument string. If only the string argument is given, it is translated to uppercase. If an input table is supplied, it modifies the translation table so that characters in the argument string that occur in the input table are replaced with the corresponding character in the output table. Characters beyond the end of the output table are replaced with the specified pad character or a blank. The result string is always for the same length as the original string. The input and output tables may be of any length. For example:

<syntaxhighlight>
SAY TRANSLATE("abcde", "123", "cbade", "+") -> 321++
SAY TRANSLATE("low") -> LOW
SAY TRANSLATE("0110", "10", "01") -> 1001
</syntaxhighlight>

=== TRIM() ===

<nowiki>TRIM(string)</nowiki>

Removes trailing blanks from the string argument. For example:

<syntaxhighlight>
SAY length (TRIM(' abc ')) -> 4
</syntaxhighlight>

=== TRUNC() ===

<nowiki>TRUNC(number[,places])</nowiki>

Returns the integer part of the number argument followed by the specified number of decimal places. The default number of decimal places is 0. The number is padded with zeroes as necessary. For example:

<syntaxhighlight>
SAY TRUNC(123.456) -> 123
SAY TRUNC(123.456,4) -> 123.4560
</syntaxhighlight>

=== UPPER() ===

<nowiki>UPPER(string)</nowiki>

Translate the string to uppercase. The action of this function is equivalent to that of TRANSLATE(string), but it is slightly faster for short strings. For example:

<syntaxhighlight>
SAY UPPER('One Fine Day') -> ONE FINE DAY
</syntaxhighlight>

=== VALUE() ===

<nowiki>VALUE(name)</nowiki>

Returns the value of the symbol represented by the name argument. For example:

<syntaxhighlight>
/*Assume that J has the value 12*/
SAY VALUE('j') -> 12
</syntaxhighlight>

=== VERIFY() ===

<nowiki>VERIFY(string,list[,'MATCH'])</nowiki>

Returns the index of the first character in the string argument which is not contained in the list argument or 0 if all of the characters are in the list. If the MATCH keyword is supplied, the function returns the index of the first character which is in the list or 0 if none of the characters are in the list. For example:

<syntaxhighlight>
SAY VERIFY('123456', '0123456789') -> 0
SAY VERIFY('123a56', '0123456789') -> 4
SAY VERIFY('123a45', 'abcdefghij', 'm') -> 4
</syntaxhighlight>

=== WORD() ===

<nowiki>WORD(string,n)</nowiki>

Returns the nth word in the string argument or the null string if there are fewer than n words. For example:

<syntaxhighlight>
SAY WORD('Now is the time ',2) -> is
</syntaxhighlight>

=== WORDINDEX() ===

<nowiki>WORDINDEX(string,n)</nowiki>

Returns the starting position of the nth word in the argument string or 0 if there are fewer than n words. For example:

<syntaxhighlight>
SAY WORDINDEX('Now is the time ',3) -> 8
</syntaxhighlight>

=== WORDLENGTH() ===

<nowiki>WORDLENGTH(string,n)</nowiki>

Returns the length of the nth word in the string argument. For example:

<syntaxhighlight>
SAY WORDLENGTH('one two three',3) -> 5
</syntaxhighlight>

=== WORDS() ===

<nowiki>WORDS(string)</nowiki>

Returns the number of words in the string argument. For example:

<syntaxhighlight>
SAY WORDS("You don't SAY!") -> 3
</syntaxhighlight>

=== WRITECH() ===

<nowiki>WRITECH(file,string)</nowiki>

Writes the string argument to the given logical file. The returned value is the actual number of characters written. For example:

<syntaxhighlight>
SAY WRITECH('output', 'Testing') -> 7
</syntaxhighlight>

=== WRITELN() ===

<nowiki>WRITELN(file,string)</nowiki>

Writes the string argument to the given logical file with a newline appended. The returned value is the actual number of characters written. For example:

<syntaxhighlight>
SAY WRITELN('output', 'Testing') -> 8
</syntaxhighlight>

=== X2C() ===

<nowiki>X2C(string)</nowiki>

Converts a string of hex digits into the (packed) character representation. Blank characters are permitted in the argument string at byte boundaries. For example:

<syntaxhighlight>
SAY X2C('12ab') -> '12ab'x
SAY X2C('12 ab') -> '12ab'x
SAY X2C(61) -> a
</syntaxhighlight>

=== X2D() ===

<nowiki>X2D(hex,digits)</nowiki>

Converts a hexadecimal number to decimal. For example:

<syntaxhighlight>
SAY X2D('1f') -> 31
</syntaxhighlight>

=== XRANGE() ===

<nowiki>XRANGE([start][,end])</nowiki>

Generates a string consisting of all characters numerically between the specified start and end values. The default start character is '00'x, and the default end character is 'FF'x. Only the first character of the start and end arguments is significant. For example:

<syntaxhighlight>
SAY XRANGE() -> '00010203 . . . FDFEFF'x
SAY XRANGE('a', 'f') -> 'abcdef'
SAY XRANGE(,'0A'x) -> '000102030405060708090A'x
</syntaxhighlight>

== Example Program ==

The following example program illustrates many of the built-in functions that manipulate character strings.

=== Program 13. Changestrings.rexx ===

<syntaxhighlight>
/*This ARexx program shows the effect of built-in functions that change strings. The functions come in two groups: one that manipulates individual characters and one that manipulates whole strings.*/

teststring1 = " every good boy does fine "

/*The first group is composed of the functions STRIP(), COMPRESS(), SPACE(), TRIM(), TRANSLATE(), DELSTR(), DELWORD(), INSERT(), OVERLAY(), and REVERSE().*/

/*STRIP() removes only leading and trailing characters.*/

/*Print the original string, for comparison. We put a period at the end of the string, so you can see what happens to the spaces at the end of the string.*/
SAY " every good boy does fine "

/*The same string stripped of leading and trailing spaces*/
SAY STRIP(" every good boy does fine ")"."

/*Failed attempt to remove leading and trailing "e"s*/
SAY STRIP(" every good boy does fine",,"e")"."

/*The "e"'s were protected by the leading and trailing spaces. Removing them exposes the "e"'s to the effects of STRIP()*/
SAY STRIP("every good boy does fine",,"e")"."

/*Remove "e"'s and spaces from the original string*/
SAY STRIP(" every good boy does fine ",," e")"."

/*We are now using the variable "teststring1", defined above. Remove only the trailing spaces in the test string.*/
SAY STRIP(teststring1, T)"."

/*Remove the trailing spaces and the "e"*/
SAY STRIP(teststring1,T," e")"."

/*Compress() removes characters anywhere in the string. This removes all blanks from the test string*/
SAY COMPRESS(teststring1)

CALL TIME('r')
SAY TIME('Civil') /*Civilian time HH:MM{AM | PM}*/
SAY TIME('h') /*Hours since midnight*/
SAY TIME('m') /*Minutes since midnight*/
SAY TIME('s') /*Seconds since midnight*/
SAY TIME('e') /*Elapsed time since program start*/

/*Function:TRACE Usage: TRACE( [option] )*/
SAY TRACE()
SAY TRACE(TRACE()) /*Leave it unchanged*/

/*Function:TRANSLATE Usage: TRANSLATE(string[,output][,input] [,pad])*/
SAY TRANSLATE('aBCdef') /*Translate to Uppercase*/
SAY TRANSLATE ('abcdef', '1234')
SAY TRANSLATE('654321', 'abcdef', '123456')
SAY TRANSLATE('abcdef', '123', 'abcdef', '+')

/*Function: TRIM Usage: TRIM(string)*/
SAY TRIM(' abc ')

/*Function: TRUNC Usage: TRUNC(number[,places])*/
SAY TRUNC(123.456)
SAY '$'TRUNC(134566.123,2)

/*Function: UPPER Usage: UPPER(string)*/
SAY UPPER('aBCdef12')

/*Function: VALUE Usage: VALUE(name)*/
abc = 'my name'
SAY VALUE('abc')

/*Function: VERIFY Usage: VERIFY(string,list[,'M'])*/
SAY VERIFY('123a45', '0123456789')
SAY VERIFY('abc3de', '012456789', 'M')

/*Function: WORD Usage: OWRD(string,n)*/
SAY WORD('Now is the time',3)

/*Function: WORDINDEX Usage: WORDINDEX(string,n)*/
SAY WORDINDEX('Now is the time ',3)

/*Function: WORDLENGTH Usage: WORDLENGTH(string,n)*/
SAY WORDLENGTH('Now is the time ',4)

/*Function: WORDS Usage: WORDS(string)*/
SAY WORDS('Now is the time')

/*Function: WRITECH Usage: WRITECH(logical,string)*/
IF OPEN('test','ram:test$$', 'W') THEN DO
SAY WRITECH('test', 'message') /*Write the string*/
CALL CLOSE 'test'
END

/*Function: WRITELN Usage: WRITELN(logical,string)*/
IF OPEN('test', 'ram:test$$', 'W') THEN DO
SAY WRITELN('test', 'message')
/*Write the string (with newline)*/
CALL CLOSE 'test'
END

/*Function: X2C Usage: X2C(heystring)*/
SAY X2C('616263') /*Convent to character (pack)*/

/*Function: XRANGE Usage: XRANGE([start] [,end])*/
SAY C2X(xrange('f0'x))
SAY XRANGE('a', 'g')
EXIT
</syntaxhighlight>

The output of Program 13 is:

every good boy does fine
every good boy does fine.
every good boy does fine .
very good boy does fin.
very good boy does fin.
every good boy does fine.
every good boy does fin.
everygoodboydoesfine
1:23PM /*These results vary depending*/
13 /*on the time the program is run.*/
803
48199
0.80
N
N
ABCDEF
abcdef
fedcba
123+++
abc
123
$134566.12
ABCDEF12
my name
4
0
the
8
4
4
7
8
abc
F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF
abcdefg

= REXXSupport.Library Functions =

The functions listed in this section are part of the REXXSupport.library. They may only be used if this library has been opened. Below is an example that shows you how to open this library.

== Program 14. OpenLibrary.rexx ==

<syntaxhighlight>
/*Add rexxsupport.library if it isn't already open.*/
IF ~ SHOW ('L', "rexxsupport.library") THEN DO
/*If the library isn't open, try to open it*/
IF ADDLIB('rexxsupport.library', 0, -30,0)
THEN SAY "Added rexxsupport.library."
ELSE DO
SAY 'ARexx support library not available, exiting'
EXIT 10 /*Exit if ADDLIB() failed*/
END
END
</syntaxhighlight>

== ALLOCMEM() ==

<nowiki>ALLOCMEM(length[,attribute])</nowiki>

Allocates a block of memory of the specified length from the system free-memory pool and returns its address as a four-byte string. The optional attribute parameter must be a standard EXEC memory allocation flag, supplied as a four-byte string. The default attribute is for "PUBLIC" memory (not cleared). Refer to [[Exec_Memory_Allocation|Exec Memory Allocation]] for information on memory types and attribute parameters.

This function should be used whenever memory is allocated for use by external programs. It is the user's responsibility to release the memory space when it is no longer needed. See also FREEMEM(). For example:

<syntaxhighlight>
SAY C2X(ALLOCMEM(1000)) -> 00050000
SAY C2X(ALLOCMEM (1000, '00 01 00 0 1'X)) -> 00228400
/*1000 bytes of CLEAR Public memory*/
</syntaxhighlight>

== CLOSEPORT() ==

<nowiki>CLOSEPORT(name)</nowiki>

Closes the message port specified by the name argument, which must have been allocated by a call to OPENPORT() within the current ARexx program. Any messages received but not yet REPLYed are automatically returned with the return code set to 10. See also OPENPORT(). For example:

<syntaxhighlight>
CALL CLOSEPORT myport
</syntaxhighlight>

== FREEMEM() ==

<nowiki>FREEMEM(address,length)</nowiki>

Releases a block of memory of the given length to the system free list. The address parameter is a four-byte string, typically obtained by a prior call to ALLOCMEM(). FREEMEM() cannot be used to release memory allocated using GETSPACE(), the ARexx internal memory allocator. The returned value is a Boolean success flag. See also ALLOCMEM(). For example:

<syntaxhighlight>
MemoryRequest = 1024
MyMem = ALLOCMEM(MemoryRequest)
SAY C2X(MyMem) -> 07C987B0
SAY FREEMEM(MyMem, MemoryRequest) -> 1
/*Or: SAY FREEMEM('07C987B0'x,1024)*/
</syntaxhighlight>

{{Note|title=Caution|text=Before your program terminates, you must use a matching FREEMEM() to release the exact amount of memory you allocated with each ALLOCMEM(). Otherwise, you may crash the system or leave memory unavailable until you reboot.}}

== GETARG() ==

<nowiki>GETARG(packet[,n])</nowiki>

Extracts a command, function name, or argument string from a message packet. The packet argument must be a four-byte address obtained from a prior call to GETPKT(). The optional [n] argument specifies the slot containing the string to be extracted and must be less than or equal to the actual argument count for the packet. Commands and function names are always in slot 0. Function packets my have argument strings in slots 1-15. For example:

<syntaxhighlight>
command = GETARG(packet)
function = GETARG(packet,0) /*name string*/
arg1 = GETARG(packet,1) /*1st argument*/
</syntaxhighlight>

== GETPKT() ==

<nowiki>GETPKT(name)</nowiki>

Checks the message port specified by the name argument to see whether any messages are available. The named message port must have been opened by a prior call to OPENPRT() within the current ARexx program. The returned value is the four-byte address of the first message packet, or '0000 0000'x if no packets were available.

The function returns immediately whether or not a packet is enqueued at the message port. Programs should never be designed to "busy-loop" on a message port. If there is no useful work to be done until the next message packet arrives, the program should call WAITPKT() and allow other tasks to proceed. See also WAITPKT(). For example:

<syntaxhighlight>
packet = GETPKT ('MyPort')
</syntaxhighlight>

== OPENPORT() ==

<nowiki>OPENPORT(name)</nowiki>

Creates a public message port with the given name. The returned Boolean value indicates whether the port was successfully opened. An initialization failure will occur if another port of the same name already exists or if a signal bit couldn't be allocated. The message port is allocated as a Port Resource node and is linked into the program's global data structure. Ports are automatically closed when the program exits and any pending messages are returned to the sender. See also CLOSEPORT(). For example:

<syntaxhighlight>
success = OPENPORT("MyPort")
</syntaxhighlight>

== REPLY() ==

<nowiki>REPLY(packet,rc)</nowiki>

Returns a message packet to the sender, with the primary result field set to the value given by the rc argument. The secondary result is cleared. The packet argument must be supplied as a four-byte address, and the rc argument must be a whole number. For example:

<syntaxhighlight>
CALL REPLY(packet,10) /*Error return*/
</syntaxhighlight>

== SHOWDIR() ==

<nowiki>SHOWDIR(directory[,'ALL'|'FILE'|'DIR'][,pad])</nowiki>

Returns the contents of the specified directory as a string of names separated by blanks. The second parameter is an option keyword that selects whether all entries, only files, or only subdirectories, will be included. For example:

<syntaxhighlight>
SAY SHOWDIR('SYS:REXXC', 'f', ';') -> WaitForPort;TS;TE;TCO;RXSET;RXLIB;RXC;RX;HI
</syntaxhighlight>

== SHOWLIST() ==

<nowiki>SHOWLIST({`A' | `D' | `H' | `T' | `L' | `M' | `P' | `R' | `S' | `T' | `V' | `W'}[,name][,pad])</nowiki>

An argument is entered using its initial letter. The arguments are:

; A
: ASSIGNS and Assigned Device

; D
: Device Drivers

; H
: Handlers

; I
: Interrupts

; L
: Libraries

; M
: Memory List Items

; P
: Ports

; R
: Resources

; S
: Semaphores

; T
: Tasks (Ready)

; V
: Volume Names

; W
: Waiting Tasks

If only one argument is supplied, SHOWLIST() returns a string separated by blanks: If a pad character is supplied, names will be separated by the pad rather than by blanks. If the name parameter is supplied. SHOWLIST() returns a Boolean value which indicates if the specified list contains that name. Names are case-sensitive. To provide an accurate snapshot of the current list, task switching is forbidden when the list is scanned.

<syntaxhighlight>
SAY SHOWLIST('P') -> REXX MyCon
SAY SHOWLIST('P',,';') -> REXX;MyCon
SAY SHOWLIST('P', 'REXX') -> 1
</syntaxhighlight>

== STATEF() ==

<nowiki>STATEF(filename)</nowiki>

Returns a string containing information about an external file. The string is formatted as:

<nowiki>"{DIR | FILE} length blocks protection days minutes ticks comment."</nowiki>

The length token gives the file length in bytes, and the block token specifies the file length in blocks. For example:

<syntaxhighlight>
SAY STATEF("LIBS:REXXSupport.library")
/*might give "File 2524 5 ----RW-D 4866 817 2088*/
</syntaxhighlight>

== WAITPKT() ==

<nowiki>WAITPKT(name)</nowiki>

Waits for a message to be received at the specified (named) port, which must have been opened by a call to OPENPORT() within the current ARexx program. The returned Boolean value indicates whether a message packet is available at the port. Normally the returned value will be 1 (True), since the function waits until an event occurs at the message port.

The packet must then be removed by a call to GETPKT() and should be returned eventually using the REPLY() function. Any message packets received but not returned when an ARexx program exits are automatically REPLYed with the return code set to 10. For example:

<syntaxhighlight>
CALL WAITPKT 'MyPort' /*Wait awhile*/
</syntaxhighlight>

AmigaOS Manual: ARexx Functions

2014-01-27T10:22:44Z

Tony Wyatt: More typos

A function is a program or group of statements that is executed whenever that function name is called in a particular context. A function may be part of an internal program, part of a library, or a separate external program. Functions are an important building block of modular programming because they allow you to construct large programs from a series of small, easily developed modules.

This chapter explains the different types of functions and how they are evaluated. It also provides an alphabetical reference of ARexx's built-in function library.

= Invoking a Function =

Within a ARexx program, a function is defined as a symbol or string followed immediately by an open parenthesis. The symbol or string (taken as a literal) specifies the function name, and the open parenthesis begins the argument list. Between the opening and closing parentheses are zero or more argument expressions, separated by commas, that supply the data being passed to the function.

Valid function calls are:

<syntaxhighlight>
CENTER ('title', 20)
ADDRESS()
'ALLOCMEM' (256*4,1)
</syntaxhighlight>

Each argument expression is evaluated in turn and the resulting strings are passed as the argument list to the function. Each argument expression, while often just a single literal value, can include arithmetic or string operations or even other function calls. Argument expressions are evaluated from left to right.

Functions can also be invoked using the CALL instruction. The CALL instruction, described in Chapter 4, can be used to invoke a function that may not return a value.

= Types of Functions =

There are three types of functions:

* Internal functions - defined within the ARexx program.
* Built-in functions - supplied by the ARexx programming language.
* Function Libraries - a special Amiga shared library.

== Internal Functions ==

An internal function is identified by a label within the program. When the internal function is called. ARexx creates a new storage environment so that the previous caller's environment is preserved. The new environment inherits the values from its predecessor, but subsequent changes to the environment variables do not affect the previous environment.

The specific values preserved are:

* The current and previous host addresses.
* The NUMERIC DIGITS, FUZZ, and FORM settings.
* The trace option, inhibit flag, and interactive flag.
* The state of the interrupt flags as defined by the SIGNAL instruction.
* The current prompt string as set by the OPTIONS PROMPT instruction.

The new environment does not automatically get a new symbol table, so initially all of the variables in the previous environment are available to the called function. The PROCEDURE instruction can be used to create a table and thereby protect the caller's symbol values. PROCEDURE can also be used to allow the same variable name to be used in two different areas with two different values.

Execution of the internal function proceeds until a RETURN instruction is executed. At this point the new environment is dismantled, and control resumes at the point of the function call. The expression supplied with the RETURN instruction is evaluated and passed back to the caller as the function result.

== Built-In Functions ==

ARexx provides a substantial library of predefined functions as part of the language system. These functions are always available and have been optimized to work with the internal data structures. In general, the built-in functions execute much faster than an equivalent interpreted function, so their usage is strongly recommended.

Several of the built-in functions create and manipulate external AmigaDOS files. Files are referenced by a logical name, a case-sensitive name that is assigned to a file when it is first opened. The initial input and output streams are given the names STDIN (standard input) and STDOUT (standard output). There is no theoretical limit to the number of files that may be open simultaneously, although a limit will be imposed by available memory. All open files are closed automatically when the program exits.

== External Function Libraries ==

A function library is a collection of one or more functions organized as an Amiga shared library. The library must reside in LIBS:, but may be either memory or disk-resident. Disk-resident libraries are loaded and opened as needed.

The library has to be especially tailored for use by ARexx. Each function library must contain a library name, a search priority, an entry point offset, and a version number. When ARexx is searching for a function, the interpreter opens each library and checks its "query" entry point. This entry point must be specified as an integer offset (e.g. "-30") from the library base. The return code from the query call indicates whether the desired function was found. If the function is found, it is called with the parameters passed by the interpreter, and the function result is returned to the caller. If it is not found, a "Function not found" error code is returned, and the search continues with the next library in the list. Function libraries are always closed after being checked so that the operating system can reclaim the memory space if required.

=== The Library List ===

The ARexx resident process maintains a list of the currently available function libraries and function hosts called the Library List. Application programs can add or remove function libraries as required.

The Library List is maintained as a priority-sorted queue. Each entry has an associated search priority in the range 100 (highest) to -100 (lowest). Entries can be added at an appropriate priority to control the function name resolution. Libraries with higher priorities are searched first. Within a given priority level, those libraries added first are searched first. The priority levels are significant if any of the libraries have duplicate function name definitions, since the function located further down the search chain could never be called.

== External Function Hosts ==

The name associated with a function host is the name of its public message port. Function calls are passed to the host as a message packet; it is then up to the individual host to determine whether the specified function name is one that it recognizes. The name resolution is completely internal to the host, so function hosts provide a natural gateway mechanism for implementing remote procedure calls to other machines in a network. The ARexx resident process is a function host and is installed in the Library List with a priority of -60.

= The Search Order =

Function linkages in ARexx are established at the time of the function call. A specific search order is followed until a function matching the name symbol or string is found. If the specified function cannot be located, an error is generated and the expression evaluation is terminated. The full search order is:

; Internal Functions
: The program source is examined for a label that matches the function name. If a match is found, a new storage environment is created and control is transferred to the label.

; Built-In Functions
: The built-in function library is searched for the specified name. All of these functions are defined by uppercase names.

; Function Libraries and Function Hosts
: The available function libraries and function hosts are maintained in the Library List, which is searched starting at the highest priority until the requested function is found or the end of the list is reached. Function hosts are called using a message-passing protocol similar to that used for commands and may be used as gateways for remote procedure calls to other machines in a network.

; External ARexx Programs
: The final search step is to check for an external ARexx program file by sending an invocation message to the ARexx resident process. The search always begins in the current directory and follows the same search path as the original ARexx program invocation. The name matching process is not case-sensitive.

The function name-matching procedure may be case-sensitive for some of the search steps, but not for others. The matching procedure used in a function library or function host is design dependent. Functions defined with mixed-case names must be called using a string token, since symbol names are always translated to uppercase.

The full search order is followed whenever the function name is defined by a symbol token. However, the search for internal functions is bypassed if the name is specified by a string token. This allows internal functions to usurp the names of external functions, as in the following example:

<syntaxhighlight>
CENTER: /*internal "CENTER"*/
ARG string, length /*get arguments*/
length = MIN(length,60) /*compute length*/
return 'CENTER' (string, length)
</syntaxhighlight>

Here the built-in function CENTER() has been replaced by an internal function after modifying the length argument.

= The Clip List =

The Clip List is a publicly accessible mechanism that can be used as a general clipboard for intertask communication. Many functions use the clipboard for retrieving different types of information, such as predefined constants or strings.

The Clip List maintains a set of (name, value) pairs that may be used for a variety of purposes. (SETCLIP() is used to add pairs to the list.) Each entry in the list consists of a name and a value string and may be located by name. In general, the names used should be chosen to be unique to an application to prevent unintended duplications with other programs. Any number of entries may be posted to the list.

One potential application for the Clip List is as a mechanism for loading predefined constants into an ARexx program. For example:

<syntaxhighlight>
pi=3.14159; e=2.718; sqrt2=1.414 . . .
</syntaxhighlight>

(i.e., a series of assignments separated by semicolons). In use, such a string could be retrieved by name using the built-in function GETCLIP() and then INTERPRETed within the program. The assignment statements within the string would then create the required constant definitions. For example:

<syntaxhighlight>
/*Assume a string called "numbers" is available*/
numbers = GETCLIP ('numbers')
INTERPRET numbers /*. . . assignments*/
</syntaxhighlight>

The strings would not be restricted to contain only assignment statements, but could include any valid ARexx statements. The Clip List could thus provide a series of programs for initializations or other processing tasks.

The resident process supports addition and deletion operations for maintaining the Clip List. The names in the (name,value) pairs are assumed to be in mixed case and are maintained to be unique in the list. An attempt to add a string with an existing name will simply update the value string. The name and value strings are copied when an entry is posted to the list, so the program that adds an entry is not required to maintain the strings.

Entries posted to the Clip List remain available until explicitly removed. The Clip List is automatically released when the resident process exits.

= Built-in Functions Reference =

This section provides an alphabetical list of the built-in functions. The syntax of each function is shown to the right of the function keyword.

== Syntax ==

Optional arguments are shown in brackets and generally have a default value that is used if the argument is omitted. When an option keyword is specified as an argument, only the first character is significant. Option keywords are not case-sensitive.

Many functions accept a pad character argument. Pad characters are inserted to fill or create spaces. For functions that accept a pad argument, only the first character of the argument string is significant. If a null string is supplied, the default padding character, usually a blank, will be used.

In the following examples, an arrow (->) is used as an abbreviation for "evaluates as." The arrow will not be displayed when a program is run. For example:

<syntaxhighlight>
SAY ABS (-5.35) -> 5.35
</syntaxhighlight>

This means that SAY ABS(-5.35) is evaluated as 5.35.

== Alphabetical Reference ==

=== ABBREV() ===

<nowiki>ABBREV(string1,string2[,length])</nowiki>

Returns a Boolean value that indicates whether string2 is an abbreviation of string1 with length greater than or equal to the specified length argument. The default length is 0, so the null string is an acceptable abbreviation. For example:

<syntaxhighlight>
SAY ABBREV ('fullname', 'ful') -> 1
SAY ABBREV ('almost', 'alm',4) -> 0
SAY ABBREV ('any','') -> 1
</syntaxhighlight>

=== ABS() ===

<nowiki>ABS(number)</nowiki>

Returns the absolute value of the number argument. This value must be numeric. For example:

<syntaxhighlight>
SAY ABS(-5.35) -> 5.35
SAY ABS(10) -> 10
</syntaxhighlight>

=== ADDLIB() ===

<nowiki>ADDLIB(name,priority[,offset,version])</nowiki>

Adds a function library or a function host to the library list maintained by the resident process. The name argument specifies either the name of a function library or the public message port associated with a function host. The name is case-sensitive. Any specified libraries should reside in the system LIBS: directory.

The priority argument specifies the search priority and must be an integer between 100 and -100, inclusive. The offset and version arguments apply only to libraries. The offset is the integer offset to the library's "query" entry point, and the version is an integer specifying the minimum acceptable release level of the library.

The function returns a Boolean result that indicates whether the operation was successful. If a library is specified, it is not actually opened at this time. Similarly, ARexx does not check to see whether a specified function host port is open. For example:

<syntaxhighlight>
SAY ADDLIB ("rexxsupport.library",0,-30,0) -> 1
CALL ADDLIB "EtherNet",-20 /*A gateway*/
</syntaxhighlight>

=== ADDRESS() ===

<nowiki>ADDRESS()</nowiki>

Returns the current host address string. The host address is the message port to which commands will be sent. The SHOW() function can be used to check whether the required external host is actually available. See also SHOW(). For example:

<syntaxhighlight>
SAY ADDRESS() -> REXX
</syntaxhighlight>

=== ARG() ===

<nowiki>ARG([number][,'EXISTS'|'OMITTED'])</nowiki>

ARG() returns the number of arguments supplied to the current environment. If only the number parameter is supplied, the corresponding argument string is returned. If a number and the Exists or Omitted keyword is given, the Boolean return indicates the status of the corresponding argument. The existence or omission test does not indicate whether the string has a null value, but only whether a string was supplied. For example:

<syntaxhighlight>
/*Assume arguments were: ('one',,10)*/
SAY ARG() -> 3
SAY ARG(1) -> one
SAY ARG(2,'O') -> 1
</syntaxhighlight>

=== B2C() ===

<nowiki>B2C(string)</nowiki>

Converts a string of binary digits (0,1) into the corresponding (packed) character representation. The conversion is the same as though the argument string had been specified as a literal binary string (e.g. `1010'B). Blanks are permitted in the string, but only at byte boundaries. This function is particularly useful for creating strings that are to be used as bit masks. See also X2C(). For example:

<syntaxhighlight>
SAY B2C('00110011') -> 3
SAY B2C('01100001') -> a
</syntaxhighlight>

=== BITAND() ===

<nowiki>BITAND(string1,string2[,pad])</nowiki>

The argument strings are logically ANDed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITAND('0313'x, 'FFF0'x) -> '0310'x
</syntaxhighlight>

=== BITCHG() ===

<nowiki>BITCHG(string,bit)</nowiki>

Changes the state of the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITCHG('0313'x,4) -> '0303'x
</syntaxhighlight>

=== BITCLR() ===

<nowiki>BITCLR(string,bit)</nowiki>

Clears (sets to zero) the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITCLR('0313'x,4) -> '0303'x
</syntaxhighlight>

=== BITCOMP() ===

<nowiki>BITCOMP(string1,string2[,pad])</nowiki>

Compares the argument strings bit-by-bit, starting at bit number 0. The returned value is the bit number of the first bit in which the strings differ, or -1 if the strings are identical. For example:

<syntaxhighlight>
BITCOMP('7F'x, 'FF'x) -> 7 /*Seventh bit*/
BITCOMP('FF'x, 'FF'x) -> -1
</syntaxhighlight>

=== BITOR() ===

<nowiki>BITOR(string1,string2[,pad])</nowiki>

The argument strings are logically ORed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITOR('0313'x, '00F'x) -> '033F'x
</syntaxhighlight>

=== BITSET() ===

<nowiki>BITSET(string,bit)</nowiki>

Sets the specified bit in the argument string to 1. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITSET('313'x,2) -> '0317'x
</syntaxhighlight>

=== BITTST() ===

<nowiki>BITTST(string,bit)</nowiki>

The Boolean return indicates the state of the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITTST('0313=x,4) -> 1
</syntaxhighlight>

=== BITXOR() ===

<nowiki>BITXOR(string1,string2[,pad])</nowiki>

The argument strings are logically and exclusively-ORed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITXOR('0313'x, '001F'x) -> '030C'X
</syntaxhighlight>

=== C2B() ===

<nowiki>C2B(string)</nowiki>

Converts the character string into the equivalent string of binary digits. See also C2X(). For example:

<syntaxhighlight>
SAY C2B('abc') -> 011000010110001001100011
</syntaxhighlight>

=== C2D() ===

<nowiki>C2D(string[,n])</nowiki>

Converts the string argument from its character representation to the corresponding decimal number, expressed as ASCII digits (0-9). If n is supplied, the character string is considered to be a number expressed in n bytes. The string is truncated or padded with nulls on the left as required, and the sign bit is extended for the conversion. For example:

<syntaxhighlight>
SAY C2D('0020'x) -> 32
SAY C2D('FFFF ffff'x) -> -1
SAY C2D('FF0100'x,2) -> 256
</syntaxhighlight>

=== C2X() ===

<nowiki>C2X(string)</nowiki>

Converts the string argument from its character representation to the corresponding hexadecimal number, expressed as the ASCII characters 0-9 and A-F. See also C2B(). For example:

<syntaxhighlight>
SAY C2X('abc') -> 616263
</syntaxhighlight>

=== CENTER()/CENTRE() ===

<nowiki>CENTER(string,length[,pad])</nowiki>
<nowiki>CENTRE(string,length[,pad])</nowiki>

Centers the string argument in a string with the specified length. If the length is longer than that of the string, pad characters or blanks are added as necessary. For example:

<syntaxhighlight>
SAY CENTER('abc',6) -> ' abc '
SAY CENTER('abc',6,'+') -> '+abc++'
SAY CENTER ('123456',3) -> '234'
</syntaxhighlight>

=== CLOSE() ===

<nowiki>CLOSE(file)</nowiki>

Closes the file specified by the given logical name. The returned value is a Boolean success flag and will be 1 unless the specified file was not open. For example:

<syntaxhighlight>
SAY CLOSE('input') -> 1
</syntaxhighlight>

=== COMPARE() ===

<nowiki>COMPARE(string1,string2[,pad])</nowiki>

Compares two strings and returns the index of the first position in which they differ or 0 if the strings are identical. The shorter string is padded as required using the supplied character or blanks. For example:

<syntaxhighlight>
SAY COMPARE('abcde', 'abcce') -> 4
SAY COMPARE('abcde', 'abcde') -> 0
SAY COMPARE('abc++', 'abc+-', '+') -> 5
</syntaxhighlight>

=== COMPRESS() ===

<nowiki>COMPRESS(string[,list])</nowiki>

If the list argument is omitted, the function removes leading, trailing or embedded blank characters from the string argument. If the optional list is supplied, it specifies the characters to be removed from the string. For example:

<syntaxhighlight>
SAY COMPRESS(' why not ') -> whynot
SAY COMPRESS('++12-34-+', '+-') -> 1234
</syntaxhighlight>

=== COPIES() ===

<nowiki>COPIES(string,number)</nowiki>

Creates a new string by concatenating the specified number of copies of the original. The number argument may be zero, in which case the null string is returned. For example:

<syntaxhighlight>
SAY COPIES('abc',3) -> abcabcabc
</syntaxhighlight>

=== D2C() ===

<nowiki>D2C(number)</nowiki>

Creates a string whose value is the binary (packed) representation of the given decimal number. For example:

<syntaxhighlight>
D2C(65) -> A
</syntaxhighlight>

=== D2X() ===

<nowiki>D2X(number[,digits])</nowiki>

Converts a decimal number to hexadecimal. For example:

<syntaxhighlight>
D2X(31) -> 1F
</syntaxhighlight>

=== DATATYPE() ===

<nowiki>DATATYPE(string[,option])</nowiki>

If only the string argument is specified, DATATYPE() tests whether the string parameter is a valid number and returns either NUM or CHAR. If an option keyword is given, the Boolean return indicates whether the string satisfied the requested test. The following option keywords are recognized:

; ALPHANUMERIC
: Accepts alphabetic (A-Z, a-z) or numeric (0-9) characters

; BINARY
: Accepts a binary digits string

; LOWERCASE
: Accepts lower case alphabetic (a-z) characters

; MIXED
: Accepts mixed upper/lower case characters

; NUMERIC
: Accepts valid numbers

; SYMBOL
: Accepts valid REXX symbols

; UPPER
: Accepts upper case alphabetic (A-Z) characters

; WHOLE
: Accepts integer numbers

; X
: Accepts Hex digit strings

For example:

<syntaxhighlight>
SAY DATATYPE('123') -> NUM
SAY DATATYPE('1a f2', 'X') -> 1
SAY DATATYPE('aBcde', 'L') -> 0
</syntaxhighlight>

=== DATE() ===

<nowiki>DATE([option][,date][format])</nowiki>

Returns the current date in the specified format. The default (`NORMAL') option returns the date in the form DD MMM YYYY, as in 20 APR 1988. The options recognized are:

; BASEDATE
: The number of days since January 1, 0001

; CENTURY
: The number of days since January 1 of the century

; DAYS
: The number of days since January 1 of the current year

; EUROPEAN
: The date in the form DD/MM/YY

; INTERNAL
: Internal system days

; JULIAN
: The date in the form YYDDD

; MONTH
: The current month (in mixed case)

; NORMAL
: The date in the form DD MMM YYYY

; ORDERED
: The date in the form YY/MM/DD

; SORTED
: The date in the form YYYYMMDD

; USA
: The date in the form MM/DD/YY

; WEEKDAY
: The day of the week (in mixed case)

These options can be shortened to just the first character.

The DATE() function also accepts optional second and third arguments to supply the date either in the form of internal system days or in the 'sorted' form YYYYMMDD. The second argument is specifying either system days (the default) or a sorted date. The third argument specifies the form of the date and can be either 'I' or 'S'. The current date in system days can be retrieved using DATE('INTERNAL'). For example:

<syntaxhighlight>
SAY DATE() -> 14 Jul 1992
SAY DATE('M') -> July
SAY DATE(S) -> 19920714
SAY DATE('S' ,DATE('I')+21) -> 19920804
SAY DATE('W' ,19890609, 'S') -> Friday
</syntaxhighlight>

=== DELSTR() ===

<nowiki>DELSTR(string,n[,length])</nowiki>

Deletes the substring of the string argument beginning with the nth character for the specified length in characters. The default length is the remaining length of the string. For example:

<syntaxhighlight>
SAY DELSTR('123456',2,3) -> 156
</syntaxhighlight>

=== DELWORD() ===

<nowiki>DELWORD(string,n[,length])</nowiki>

Deletes the substring of the string argument beginning with the nth word for the specified length in words. The default length is the remaining length of the string. The deleted string includes any trailing blanks following the last word. For example:

<syntaxhighlight>
SAY DELWORD('Tell me a story',2,2) -> 'Tell story'
SAY DELWORD('one two three',3) -> 'one two '
</syntaxhighlight>

=== DIGITS() ===

<nowiki>DIGITS()</nowiki>

Returns the current Numeric Digits setting. For example:

<syntaxhighlight>
NUMERIC DIGITS 6
SAY DIGITS() -> 6
</syntaxhighlight>

=== EOF() ===

<nowiki>EOF(file)</nowiki>

Checks the specified logical file name and returns the Boolean value 1 (True), if the end-of-file has been reached, and 0 (False) otherwise. For example:

<syntaxhighlight>
SAY EOF(infile) -> 1
</syntaxhighlight>

=== ERRORTEXT() ===

<nowiki>ERRORTEXT(n)</nowiki>

Returns the error message associated with the specified ARexx error code. The null string is returned if the number is not a valid error code. For example:

<syntaxhighlight>
SAY ERRORTEXT(41) -> Invalid expression
</syntaxhighlight>

=== EXISTS() ===

<nowiki>EXISTS(filename)</nowiki>

Tests whether an external file of the given filename exists. The name string may include device and directory specifications. For example:

<syntaxhighlight>
SAY EXISTS('SYS:C/ED') -> 1
</syntaxhighlight>

=== EXPORT() ===

<nowiki>EXPORT(address[,string][,length][,pad])</nowiki>

Copies data from the optional string into a previously-allocated memory area. This memory area must be specified as a four-byte address. The length parameter specifies the maximum number of characters to be copied. The default is the length of the string. If the specified length is longer than the string, the remaining area is filled with the pad character or nulls ('00'x). The returned value is the number of characters copied.

{{Note|title=Caution|text=Any area of memory can be overwritten, possibly causing a system crash. Task switching is forbidden while the copy is being done, so system performance may be degraded if long strings are copied.}}

See also IMPORT() and STORAGE(). For example:

<syntaxhighlight>
count = EXPORT('0004 0000'x, 'The answer')
</syntaxhighlight>

=== FIND() ===

<nowiki>FIND(string,phrase)</nowiki>

The FIND() function locates a phrase of words in a larger string of words and returns the word number of the matched position. For example:

<syntaxhighlight>
SAY FIND('Now is the time', 'is the') -> 2
</syntaxhighlight>

=== FORM() ===

<nowiki>FORM()</nowiki>

Returns the current NUMERIC FORM setting. For example:

<syntaxhighlight>
NUMERIC FORM SCIENTIFIC
SAY FORM() -> SCIENTIFIC
</syntaxhighlight>

=== FREESPACE() ===

<nowiki>FREESPACE(address,length)</nowiki>

Returns a block of memory of a given length to the interpreter's internal pool. The address argument must be a 4 byte string obtained by a prior call to GETSPACE(), the internal allocator. It is not always necessary to release internally allocated memory, since it will be released to the system when the program terminates. However, if a very large block has been allocated, returning it to the pool may avoid memory space problems. The return value is a Boolean success flag. See also GETSPACE().

Calling FREESPACE() with no arguments will return the amount of memory available in the interpreter's internal pool. For example:

<syntaxhighlight>
FREESPACE('00042000'x,32) -> 1
</syntaxhighlight>

=== FUZZ() ===

<nowiki>FUZZ()</nowiki>

Returns the current NUMERIC FUZZ setting. For example:

<syntaxhighlight>
NUMERIC FUZZ 3
SAY FUZZ() -> 3
</syntaxhighlight>

=== GETCLIP() ===

<nowiki>GETCLIP(name)</nowiki>

Searches the Clip List for an entry matching the supplied name parameter and returns the associated value string. The name matching is case-sensitive. The null string is returned if the name cannot be found. See also SETCLIP(). For example:

<syntaxhighlight>
/*Assume 'numbers' contains 'PI=3.14159'*/
SAY GETCLIP('numbers') -> PI=3.14159
</syntaxhighlight>

=== GETSPACE() ===

<nowiki>GETSPACE(length)</nowiki>

Allocates a block of memory of the specified length from the interpreter's internal pool. The returned value is the four-byte address of the allocated block, which is not cleared or otherwise initialized. Internal memory is automatically returned to the system when the ARexx program terminates, so this function should not be used to allocate memory for use by external programs. The REXXSupport.Library includes the function ALLOCMEM(), which allocates memory from the system free list. See also FREESPACE(). For example:

<syntaxhighlight>
SAY C2X (GETSPACE(32)) -> '0003BF40'x
</syntaxhighlight>

=== HASH() ===

<nowiki>HASH(string)</nowiki>

Returns the hash attribute of a string as a decimal number and updates the internal hash value of the string. For example:

<syntaxhighlight>
SAY HASH('1') -> 49
</syntaxhighlight>

=== IMPORT() ===

<nowiki>IMPORT(address[,length])</nowiki>

Creates a string by copying data from the specified four-byte address. If the length parameter is not supplied, the copy terminates when a null byte is found. See also EXPORT(). For example:

<syntaxhighlight>
extval = IMPORT('0004 0000'x,8)
</syntaxhighlight>

=== INDEX() ===

<nowiki>INDEX(string,pattern[,start])</nowiki>

Searches for the first occurrence of the pattern argument in the string argument, beginning at the specified start position. The default start position is 1. The returned value is the index of the matched pattern or 0 if the pattern was not found. For example:

<syntaxhighlight>
SAY INDEX("123456", "23") -> 2
SAY INDEX("123456", "77") -> 0
SAY INDEX("123123", "23",3) -> 5
</syntaxhighlight>

=== INSERT() ===

<nowiki>INSERT(new,old[,start][,length][,pad])</nowiki>

Inserts the new string into the old string after the specified start position. The default starting position is 0. The new string is truncated or padded to the specified length as required, using the supplied pad character or blanks. If the start position is beyond the end of the string, the old string is padded on the right. For example:

<syntaxhighlight>
SAY INSERT('ab', '12345') -> ab12345
SAY INSERT('123', '++',3,5, '-') -> ++-123--
</syntaxhighlight>

=== LASTPOS() ===

<nowiki>LASTPOS(pattern,string[,start])</nowiki>

Searches backwards for the first occurrence of the pattern argument in the string argument, beginning at the specified start position. The default starting position is the end of the string. The returned value is the index of the matched pattern or 0 if the pattern was not found. For example:

<syntaxhighlight>
SAY LASTPOS('2', '1234') -> 2
SAY LASTPOS('2', '1234234') -> 5
SAY LASTPOS('2', '123234',3) -> 2
SAY LASTPOS('2', '13579') -> 0
</syntaxhighlight>

=== LEFT() ===

<nowiki>LEFT(string,length[,pad])</nowiki>

Returns the leftmost substring in the given string argument with the specified length. If the substring is shorter than the requested length, it is padded on the right with the supplied pad character or blanks. For example:

<syntaxhighlight>
SAY LEFT('123456',3) -> 123
SAY LEFT('123456',8, '+') -> 123456++
</syntaxhighlight>

=== LENGTH() ===

<nowiki>LENGTH(string)</nowiki>

Returns the length of the string. For example:

<syntaxhighlight>
SAY LENGTH('three') -> 5
</syntaxhighlight>

=== LINES() ===

<nowiki>LINES(file)</nowiki>

Returns the number of lines queued or typed ahead at the logical file, which must refer to an interactive stream. The line count is obtained as the secondary result of a WaitForChar() call. For example:

<syntaxhighlight>
PUSH 'a line'
PUSH 'another one'
SAY LINES(STDIN) -> 2
</syntaxhighlight>

=== MAX() ===

<nowiki>MAX(number,number[,number,...])</nowiki>

Returns the maximum of the supplied arguments, all of which must be numeric. At least two parameters must be supplied. For example:

<syntaxhighlight>
SAY MAX(2.1,3,-1) -> 3
</syntaxhighlight>

=== MIN() ===

<nowiki>MIN(number,number[,number,...])</nowiki>

Returns the minimum of the supplied arguments, all of which must be numeric. At least two parameters must be supplied. For example:

<syntaxhighlight>
SAY MIN(2.1,3,-1) -> -1
</syntaxhighlight>

=== OPEN() ===

<nowiki>OPEN(file,filename[,'APPEND'|'READ'|'WRITE'])</nowiki>

Opens an external file for the specified operation. The file argument defines the logical name by which the file will be referenced. The filename is the external name of the file and may include device and directory specifications. The function returns a Boolean value that indicates whether the operation was successful. There is no limit to the number of files that can be open simultaneously, and all open files are closed automatically when the program exits. See also CLOSE(), READ(), and WRITE(). For example:

<syntaxhighlight>
SAY OPEN('MyCon', 'CON:160/50/320/100/MyCON/cds') P-> 1
SAY OPEN('outfile', 'ram:temp', 'W') -> 1
</syntaxhighlight>

=== OVERLAY() ===

<nowiki>OVERLAY(new,old[,start][,length][,pad])</nowiki>

Overlays the new string onto the old string beginning at the specified start position, which must be positive. The default starting position is 1. The new string is truncated or padded to the specified length as required, using the supplied pad character or blanks. If the start position is beyond the end of the old string, the old string is padded on the right. For example:

<syntaxhighlight>
SAY OVERLAY('bb', 'abcd') -> bbcd
SAY OVERLAY('4', '123',5,5, '-') -> 123-4----
</syntaxhighlight>

=== POS() ===

<nowiki>POS(pattern,string[,start])</nowiki>

Searches for the first occurrence of the pattern argument in the string argument, beginning at the position specified by the start argument. The default starting position is 1. The value is the index of the matched string or 0 if the pattern wasn't found. For example:

<syntaxhighlight>
SAY POS('23', '123234') -> 2
SAY POS('77', '123234') -> 0
SAY POS('23', '123234',3) -> 4
</syntaxhighlight>

=== PRAGMA() ===

<nowiki>PRAGMA(option[,value])</nowiki>

This function allows a program to change various attributes relating to the system environment within which the program executes. The option argument is a keyword that specifies an environmental attribute. The value argument supplies the new attribute value to be installed. The value returned by the function depends on the attribute selected. Some attributes return the previous value installed, while others may simply set a Boolean success flag.

The currently defined option keywords are:

; DIRECTORY
: Specifies a new current directory. The current directory is used as the root for filenames that do not explicitly include a device specification. The return is the old directory name. PRAGMA('D') is equivalent to PRAGMA('D',''). It returns the path of the current directory without changing the directory.

; PRIORITY
: Specifies a new task priority. The priority value must be an integer in the range - 128 to 127, but the practical range is much more limited. ARexx programs should never be run at a priority higher than that of the resident process, which currently runs at a priority of 4. The returned value is the previous priority level.

; ID
: Returns the task ID (the address of the task block) as an 8-character hex string. The task ID is a unique identifier of the particular ARexx invocation and may be used to create a unique name for it.

; STACK
: Specifies a new stack value for your current ARexx program. When a new stack value is declared, the previous stack value is returned.

The currently implemented options are:

; PRAGMA('W',{'NULL'|' WORKBENCH'})
: Controls the task's WindowPtr field. Setting it to 'NULL' will suppress any requesters that might otherwise be generated by a DOS call.

; PRAGMA('*'[,name])
: Defines the specified logical name as the current ("*") console handler, allowing the user to open two streams on one window. If the name is omitted, the console handler is set to that of the client's process.

<syntaxhighlight>
SAY PRAGMA('D', 'DF0:C') -> Extras
SAY PRAGMA('D', 'DF1:C') -> Workbench:C
SAY PRAGMA('PRIORITY', -5) -> 0
SAY PRAGMA('ID') -> 00221ABC
CALL PRAGMA '*',STDOUT
SAY PRAGMA("STACK",8092) -> 4000
</syntaxhighlight>

=== RANDOM() ===

<nowiki>RANDOM([MIN][,MAX][,seed])</nowiki>

Returns a pseudo-random integer in the interval specified by the min and max arguments. The default minimum value is 0 and the default maximum value is 999. The interval max-min must be less than or equal to 1000. If a greater range of random integers is required, the values from the RANDU() function can be suitably scaled and translated. The seed argument can be supplied to initialize the internal state of the random number generator. See also RANDU(). For example:

<syntaxhighlight>
thisroll = RANDOM(1,6) /*Might be 1*/
nextroll = RANDOM(1,6) /*Might be snake eyes*/
</syntaxhighlight>

=== RANDU() ===

<nowiki>RANDU([seed])</nowiki>

Returns a uniformly-distributed, pseudo-random number between 0 and 1. The number of digits of precision in the result is always equal to the current Numeric Digits setting. With the choice of suitable scaling and translation values, RANDU() can be used to generate pseudo-random numbers on an arbitrary interval.

The optional integer seed argument is used to initialize the internal state of the random number generator. See also RANDOM(). For example:

<syntaxhighlight>
firsttry = RANDU() /*0.371902021?*/
NUMERIC DIGITS 3
tryagain = RANDU () /*0.873?*/
</syntaxhighlight>

=== READCH() ===

<nowiki>READCH(file,length)</nowiki>

Reads the specified number of characters from the given logical file into a string. The length of the returned string is the actual number of characters read and may be less than the requested length if, for example, the end-of-file was reached. See also READLN(). For example:

<syntaxhighlight>
instring = READCH('input',10)
</syntaxhighlight>

=== READLN() ===

<nowiki>READLN(file)</nowiki>

Reads characters from the given logical file into a string until a newline character is found. The returned string does not include the newline. See also READCH(). For example:

<syntaxhighlight>
instring = READLN('MyFile')
</syntaxhighlight>

=== REMLIB() ===

<nowiki>REMLIB(name)</nowiki>

Removes an entry with the given name from the Library List maintained by the resident process. The Boolean return is 1 if the entry was found and successfully removed. This function does not make a distinction between function libraries and function hosts, but simply removes a named entry. See also ADDLIB(). For example:

<syntaxhighlight>
SAY REMLIB('MyLibrary.library') -> 1
</syntaxhighlight>

=== REVERSE() ===

<nowiki>REVERSE(string)</nowiki>

Reverses the sequence of characters in the string. For example:

<syntaxhighlight>
SAY REVERSE('?ton yhw') -> why not?
</syntaxhighlight>

=== RIGHT() ===

<nowiki>RIGHT(string,length[,pad])</nowiki>

Returns the rightmost substring in the given string argument with the specified length. If the substring is shorter than the requested length, it is padded on the left with the supplied pad character or blanks. For example:

<syntaxhighlight>
SAY RIGHT('123456',4) -> 3456
SAY RIGHT('123456',8, '+') -> ++123456
</syntaxhighlight>

=== SEEK() ===

<nowiki>SEEK(file,offset[,'BEHIN'|'CURRENT'|'END'])</nowiki>

Moves to a new position in the given logical file, specified as an offset from an anchor position. The default anchor is Current. The returned value is the new position relative to the start of the file. For example:

<syntaxhighlight>
SAY SEEK('input',10,'B') -> 10
SAY SEEK('input',0,E') -> 356 /*file length*/
</syntaxhighlight>

=== SETCLIP() ===

<nowiki>SETCLIP(name[,value])</nowiki>

Adds a name-value pair to the Clip List maintained by the resident process. If an entry of the same name already exists, its value is updated to the supplied value string. Entries may be removed by specifying a null value. The function returns a Boolean value that indicates whether the operation was successful. For example:

<syntaxhighlight>
SAY SETCLIP('path', 'DF0:s') -> 1
SAY SETCLIP('path') -> 1
</syntaxhighlight>

=== SHOW() ===

<nowiki>SHOW(option[,name][,pad])</nowiki>

Returns the names in the resource list specified by the option argument, or tests to see whether an entry with the specified name is available. The currently implemented options keywords are:

; CLIP
: Examines the names in the Clip List

; FILES
: Examines the currently open logical file names

; LIBRARIES
: Examines the names in the Library List, which are either function libraries or function hosts.

; PORTS
: Examines the names in the system Ports List

If the name argument is omitted, the function returns a string with the resource names separated by a blank space or the pad character, if one was supplied. If the name argument is given, the returned Boolean value indicates whether the name was found in the resource list. The name entries are case-sensitive.

=== SIGN() ===

<nowiki>SIGN(number)</nowiki>

Returns 1 if the number argument is positive or zero and -1 if the number is negative. The argument must be numeric. For example:

<syntaxhighlight>
SAY SIGN(12) -> 1
SAY SIGN(-33) -> 1
</syntaxhighlight>

=== SOURCELINE() ===

<nowiki>SOURCELINE([line])</nowiki>

Returns the text for the specified line of the currently executing ARexx program. If the line argument is omitted, the function returns the total number of lines in the file. This function is often used to embed "help" information in a program. For example:

<syntaxhighlight>
/*A simple test program*/
SAY SOURCELINE() -> 3
SAY SOURCELINE(1)-> /*A simple test program*/
</syntaxhighlight>

=== SPACE() ===

<nowiki>SPACE(string,n[,pad])</nowiki>

Reformats the string argument so that there are n spaces (blank characters) between each pair of words. If the pad character is specified, it is used instead of blanks as the separator character. Specifying n as 0 will remove all blanks from the string. For example:

<syntaxhighlight>
SAY SPACE('Now is the time',3) -> 'Now is the time'
SAY SPACE('Now is the time',0) -> 'Nowisthetime'
SAY SPACE('1 2 3',1, '+') -> '1+2+3'
</syntaxhighlight>

=== STORAGE() ===

<nowiki>STORAGE([address][,string][,length][,pad])</nowiki>

STORAGE() with no arguments returns the available system memory. If the address argument is given, it must be a four-byte string. The function copies data from the (optional) string to the indicated memory address. The length parameter specifies the maximum number of bytes to be copied defaults to the length of the string. if the specified length is longer than the string, the remaining area is filled with the pad character or nulls ('00'x).

The returned value is the previous contents of the memory area. This can be used in a subsequent call to restore the original contents. See also EXPORT().

{{Note|title=Caution|text=Any area of memory can be overwritten, possibly causing a system crash. Task switching is forbidden while the copy is being done, so system performance may be degraded if long strings are copied.}}

For example:

<syntaxhighlight>
SAY STORAGE() -> ' 248400
oldval = STORAGE('0004 0000'x, 'The answer')
CALL STORAGE '0004 0000'x,,32, '+'
</syntaxhighlight>

=== STRIP() ===

<nowiki>STRIP(string[,{`B' | `L' | `T'}][,pad])</nowiki>

If neither of the optional parameters is supplied, the function removes both leading and trailing blanks from the string argument. The second argument specifies whether Leading, Trailing or Both (leading and trailing) characters are to be removed. The optional pad (or unpad) argument selects the character to be removed. For example:

<syntaxhighlight>
SAY STRIP(' say what? ') -> 'say What?'
SAY STRIP(' say what? ','L') -> 'say what?
SAY STRIP('++123+++', 'B', '+') -> '123'
</syntaxhighlight>

=== SUBSTR() ===

<nowiki>SUBSTR(string,start[,length][,pad])</nowiki>

Returns the substring of the string argument beginning at the specified start position for the specified length. The starting position must be positive, and the default length is the remaining length of the string. If the substring is shorter than the requested length, it is padded on the right with the blanks or the specified pad character. For example:

<syntaxhighlight>
SAY SUBSTR('123456',4,2) -> 45
SAY SUBSTR('myname',3,6, '=') -> name==
</syntaxhighlight>

=== SUBWORD() ===

<nowiki>SUBWORD(string,n[,length])</nowiki>

Returns the substring of the string argument beginning with the nth word for the specified length in words. The default length is the remaining length of the string. The returned string will never have leading or trailing blanks. For example:

<syntaxhighlight>
SAY SUBWORD('Now is the time ',2,2) -> is the
</syntaxhighlight>

=== SYMBOL() ===

<nowiki>SYMBOL(name)</nowiki>

Tests whether the name argument is a valid ARexx symbol. If the name is not a valid symbol, the function returns the string BAD. If the symbol is uninitialized, the returned string is LIT. If the symbol ha been assigned a value, VAR is returned. For example:

<syntaxhighlight>
SAY SYMBOL('J') -> VAR
SAY SYMBOL('x') -> LIT
SAY SYMBOL('++') -> BAD
</syntaxhighlight>

=== TIME() ===

<nowiki>TIME(option)</nowiki>

Returns the current system time or controls the internal elapsed time counter. The valid option keywords are:

; CIVIL
: Current time in 12 hour format (a.m./p.m.) hours/minutes

; ELAPSED
: Elapsed time in seconds since program start

; HOURS
: Current time in hours since midnight

; MINUTES
: Current time in minutes since midnight

; NORMAL
: Current time in 24 hour format (hours/minutes/seconds)

; RESET
: Reset the elapsed time clock

; SECONDS
: Current time in seconds since midnight

If no option is specified, the function returns the current system time in the form HH:MM:SS. For example:

<syntaxhighlight>
/*Suppose that the time is 1:02 AM . . .*/
SAY TIME('C'( -> 1:02 AM
SAY TIME('HOURS') -> 1
SAY TIME('M') -> 62
SAY TIME('N') -> 01:02:54
SAY TIME('S') -> 3720
call TIME('R') /*reset timer*/
SAY TIME('E') -> .020
SAY TIME() -> 01:02:00
</syntaxhighlight>

=== TRACE() ===

<nowiki>TRACE(option)</nowiki>

Sets the tracing mode (see Chapter 6) to that specified by the option keyword, which must be one of the valid alphabetic or prefix options. The TRACE() function will alter the tracing mode even during interactive tracing, when TRACE instructions in the source program are ignored. The returned value is the mode in effect before the function call. This allows the previous trace mode to be restored later. For example:

<syntaxhighlight>
/*Assume tracing mode is ?ALL*/
SAY TRACE('Results') -> ?A
</syntaxhighlight>

=== TRANSLATE() ===

<nowiki>TRANSLATE(string[,output][,input][,pad])</nowiki>

This function constructs a translation table and uses it to replace selected characters in the argument string. If only the string argument is given, it is translated to uppercase. If an input table is supplied, it modifies the translation table so that characters in the argument string that occur in the input table are replaced with the corresponding character in the output table. Characters beyond the end of the output table are replaced with the specified pad character or a blank. The result string is always for the same length as the original string. The input and output tables may be of any length. For example:

<syntaxhighlight>
SAY TRANSLATE("abcde", "123", "cbade", "+") -> 321++
SAY TRANSLATE("low") -> LOW
SAY TRANSLATE("0110", "10", "01") -> 1001
</syntaxhighlight>

=== TRIM() ===

<nowiki>TRIM(string)</nowiki>

Removes trailing blanks from the string argument. For example:

<syntaxhighlight>
SAY length (TRIM(' abc ')) -> 4
</syntaxhighlight>

=== TRUNC() ===

<nowiki>TRUNC(number[,places])</nowiki>

Returns the integer part of the number argument followed by the specified number of decimal places. The default number of decimal places is 0. The number is padded with zeroes as necessary. For example:

<syntaxhighlight>
SAY TRUNC(123.456) -> 123
SAY TRUNC(123.456,4) -> 123.4560
</syntaxhighlight>

=== UPPER() ===

<nowiki>UPPER(string)</nowiki>

Translate the string to uppercase. The action of this function is equivalent to that of TRANSLATE(string), but it is slightly faster for short strings. For example:

<syntaxhighlight>
SAY UPPER('One Fine Day') -> ONE FINE DAY
</syntaxhighlight>

=== VALUE() ===

<nowiki>VALUE(name)</nowiki>

Returns the value of the symbol represented by the name argument. For example:

<syntaxhighlight>
/*Assume that J has the value 12*/
SAY VALUE('j') -> 12
</syntaxhighlight>

=== VERIFY() ===

<nowiki>VERIFY(string,list[,'MATCH'])</nowiki>

Returns the index of the first character in the string argument which is not contained in the list argument or 0 if all of the characters are in the list. If the MATCH keyword is supplied, the function returns the index of the first character which is in the list or 0 if none of the characters are in the list. For example:

<syntaxhighlight>
SAY VERIFY('123456', '0123456789') -> 0
SAY VERIFY('123a56', '0123456789') -> 4
SAY VERIFY('123a45', 'abcdefghij', 'm') -> 4
</syntaxhighlight>

=== WORD() ===

<nowiki>WORD(string,n)</nowiki>

Returns the nth word in the string argument or the null string if there are fewer than n words. For example:

<syntaxhighlight>
SAY WORD('Now is the time ',2) -> is
</syntaxhighlight>

=== WORDINDEX() ===

<nowiki>WORDINDEX(string,n)</nowiki>

Returns the starting position of the nth word in the argument string or 0 if there are fewer than n words. For example:

<syntaxhighlight>
SAY WORDINDEX('Now is the time ',3) -> 8
</syntaxhighlight>

=== WORDLENGTH() ===

<nowiki>WORDLENGTH(string,n)</nowiki>

Returns the length of the nth word in the string argument. For example:

<syntaxhighlight>
SAY WORDLENGTH('one two three',3) -> 5
</syntaxhighlight>

=== WORDS() ===

<nowiki>WORDS(string)</nowiki>

Returns the number of words in the string argument. For example:

<syntaxhighlight>
SAY WORDS("You don't SAY!") -> 3
</syntaxhighlight>

=== WRITECH() ===

<nowiki>WRITECH(file,string)</nowiki>

Writes the string argument to the given logical file. The returned value is the actual number of characters written. For example:

<syntaxhighlight>
SAY WRITECH('output', 'Testing') -> 7
</syntaxhighlight>

=== WRITELN() ===

<nowiki>WRITELN(file,string)</nowiki>

Writes the string argument to the given logical file with a newline appended. The returned value is the actual number of characters written. For example:

<syntaxhighlight>
SAY WRITELN('output', 'Testing') -> 8
</syntaxhighlight>

=== X2C() ===

<nowiki>X2C(string)</nowiki>

Converts a string of hex digits into the (packed) character representation. Blank characters are permitted in the argument string at byte boundaries. For example:

<syntaxhighlight>
SAY X2C('12ab') -> '12ab'x
SAY X2C('12 ab') -> '12ab'x
SAY X2C(61) -> a
</syntaxhighlight>

=== X2D() ===

<nowiki>X2D(hex,digits)</nowiki>

Converts a hexadecimal number to decimal. For example:

<syntaxhighlight>
SAY X2D('1f') -> 31
</syntaxhighlight>

=== XRANGE() ===

<nowiki>XRANGE([start][,end])</nowiki>

Generates a string consisting of all characters numerically between the specified start and end values. The default start character is '00'x, and the default end character is 'FF'x. Only the first character of the start and end arguments is significant. For example:

<syntaxhighlight>
SAY XRANGE() -> '00010203 . . . FDFEFF'x
SAY XRANGE('a', 'f') -> 'abcdef'
SAY XRANGE(,'0A'x) -> '000102030405060708090A'x
</syntaxhighlight>

== Example Program ==

The following example program illustrates many of the built-in functions that manipulate character strings.

=== Program 13. Changestrings.rexx ===

<syntaxhighlight>
/*This ARexx program shows the effect of built-in functions that change strings. The functions come in two groups: one that manipulates individual characters and one that manipulates whole strings.*/

teststring1 = " every good boy does fine "

/*The first group is composed of the functions STRIP(), COMPRESS(), SPACE(), TRIM(), TRANSLATE(), DELSTR(), DELWORD(), INSERT(), OVERLAY(), and REVERSE().*/

/*STRIP() removes only leading and trailing characters.*/

/*Print the original string, for comparison. We put a period at the end of the string, so you can see what happens to the spaces at the end of the string.*/
SAY " every good boy does fine "

/*The same string stripped of leading and trailing spaces*/
SAY STRIP(" every good boy does fine ")"."

/*Failed attempt to remove leading and trailing "e"s*/
SAY STRIP(" every good boy does fine",,"e")"."

/*The "e"'s were protected by the leading and trailing spaces. Removing them exposes the "e"'s to the effects of STRIP()*/
SAY STRIP("every good boy does fine",,"e")"."

/*Remove "e"'s and spaces from the original string*/
SAY STRIP(" every good boy does fine ",," e")"."

/*We are now using the variable "teststring1", defined above. Remove only the trailing spaces in the test string.*/
SAY STRIP(teststring1, T)"."

/*Remove the trailing spaces and the "e"*/
SAY STRIP(teststring1,T," e")"."

/*Compress() removes characters anywhere in the string. This removes all blanks from the test string*/
SAY COMPRESS(teststring1)

CALL TIME('r')
SAY TIME('Civil') /*Civilian time HH:MM{AM | PM}*/
SAY TIME('h') /*Hours since midnight*/
SAY TIME('m') /*Minutes since midnight*/
SAY TIME('s') /*Seconds since midnight*/
SAY TIME('e') /*Elapsed time since program start*/

/*Function:TRACE Usage: TRACE( [option] )*/
SAY TRACE()
SAY TRACE(TRACE()) /*Leave it unchanged*/

/*Function:TRANSLATE Usage: TRANSLATE(string[,output][,input] [,pad])*/
SAY TRANSLATE('aBCdef') /*Translate to Uppercase*/
SAY TRANSLATE ('abcdef', '1234')
SAY TRANSLATE('654321', 'abcdef', '123456')
SAY TRANSLATE('abcdef', '123', 'abcdef', '+')

/*Function: TRIM Usage: TRIM(string)*/
SAY TRIM(' abc ')

/*Function: TRUNC Usage: TRUNC(number[,places])*/
SAY TRUNC(123.456)
SAY '$'TRUNC(134566.123,2)

/*Function: UPPER Usage: UPPER(string)*/
SAY UPPER('aBCdef12')

/*Function: VALUE Usage: VALUE(name)*/
abc = 'my name'
SAY VALUE('abc')

/*Function: VERIFY Usage: VERIFY(string,list[,'M'])*/
SAY VERIFY('123a45', '0123456789')
SAY VERIFY('abc3de', '012456789', 'M')

/*Function: WORD Usage: OWRD(string,n)*/
SAY WORD('Now is the time',3)

/*Function: WORDINDEX Usage: WORDINDEX(string,n)*/
SAY WORDINDEX('Now is the time ',3)

/*Function: WORDLENGTH Usage: WORDLENGTH(string,n)*/
SAY WORDLENGTH('Now is the time ',4)

/*Function: WORDS Usage: WORDS(string)*/
SAY WORDS('Now is the time')

/*Function: WRITECH Usage: WRITECH(logical,string)*/
IF OPEN('test','ram:test$$', 'W') THEN DO
SAY WRITECH('test', 'message') /*Write the string*/
CALL CLOSE 'test'
END

/*Function: WRITELN Usage: WRITELN(logical,string)*/
IF OPEN('test', 'ram:test$$', 'W') THEN DO
SAY WRITELN('test', 'message')
/*Write the string (with newline)*/
CALL CLOSE 'test'
END

/*Function: X2C Usage: X2C(heystring)*/
SAY X2C('616263') /*Convent to character (pack)*/

/*Function: XRANGE Usage: XRANGE([start] [,end])*/
SAY C2X(xrange('f0'x))
SAY XRANGE('a', 'g')
EXIT
</syntaxhighlight>

The output of Program 13 is:

every good boy does fine
every good boy does fine.
every good boy does fine .
very good boy does fin.
very good boy does fin.
every good boy does fine.
every good boy does fin.
everygoodboydoesfine
1:23PM /*These results vary depending*/
13 /*on the time the program is run.*/
803
48199
0.80
N
N
ABCDEF
abcdef
fedcba
123+++
abc
123
$134566.12
ABCDEF12
my name
4
0
the
8
4
4
7
8
abc
F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF
abcdefg

= REXXSupport.Library Functions =

The functions listed in this section are part of the REXXSupport.library. They may only be used if this library has been opened. Below is an example that shows you how to open this library.

== Program 14. OpenLibrary.rexx ==

<syntaxhighlight>
/*Add rexxsupport.library if it isn't already open.*/
IF ~ SHOW ('L', "rexxsupport.library") THEN DO
/*If the library isn't open, try to open it*/
IF ADDLIB('rexxsupport.library', 0, -30,0)
THEN SAY "Added rexxsupport.library."
ELSE DO
SAY 'ARexx support library not available, exiting'
EXIT 10 /*Exit if ADDLIB() failed*/
END
END
</syntaxhighlight>

== ALLOCMEM() ==

<nowiki>ALLOCMEM(length[,attribute])</nowiki>

Allocates a block of memory of the specified length from the system free-memory pool and returns its address as a four-byte string. The optional attribute parameter must be a standard EXEC memory allocation flag, supplied as a four-byte string. The default attribute is for "PUBLIC" memory (not cleared). Refer to [[Exec_Memory_Allocation|Exec Memory Allocation]] for information on memory types and attribute parameters.

This function should be used whenever memory is allocated for use by external programs. It is the user's responsibility to release the memory space when it is no longer needed. See also FREEMEM(). For example:

<syntaxhighlight>
SAY C2X(ALLOCMEM(1000)) -> 00050000
SAY C2X(ALLOCMEM (1000, '00 01 00 0 1'X)) -> 00228400
/*1000 bytes of CLEAR Public memory*/
</syntaxhighlight>

== CLOSEPORT() ==

<nowiki>CLOSEPORT(name)</nowiki>

Closes the message port specified by the name argument, which must have been allocated by a call to OPENPORT() within the current ARexx program. Any messages received but not yet REPLYed are automatically returned with the return code set to 10. See also OPENPORT(). For example:

<syntaxhighlight>
CALL CLOSEPORT myport
</syntaxhighlight>

== FREEMEM() ==

<nowiki>FREEMEM(address,length)</nowiki>

Releases a block of memory of the given length to the system free list. The address parameter is a four-byte string, typically obtained by a prior call to ALLOCMEM(). FREEMEM() cannot be used to release memory allocated using GETSPACE(), the ARexx internal memory allocator. The returned value is a Boolean success flag. See also ALLOCMEM(). For example:

<syntaxhighlight>
MemoryRequest = 1024
MyMem = ALLOCMEM(MemoryRequest)
SAY C2X(MyMem) -> 07C987B0
SAY FREEMEM(MyMem, MemoryRequest) -> 1
/*Or: SAY FREEMEM('07C987B0'x,1024)*/
</syntaxhighlight>

{{Note|title=Caution|text=Before your program terminates, you must use a matching FREEMEM() to release the exact amount of memory you allocated with each ALLOCMEM(). Otherwise, you may crash the system or leave memory unavailable until you reboot.}}

== GETARG() ==

<nowiki>GETARG(packet[,n])</nowiki>

Extracts a command, function name, or argument string from a message packet. The packet argument must be a four-byte address obtained from a prior call to GETPKT(). The optional [n] argument specifies the slot containing the string to be extracted and must be less than or equal to the actual argument count for the packet. Commands and function names are always in slot 0. Function packets my have argument strings in slots 1-15. For example:

<syntaxhighlight>
command = GETARG(packet)
function = GETARG(packet,0) /*name string*/
arg1 = GETARG(packet,1) /*1st argument*/
</syntaxhighlight>

== GETPKT() ==

<nowiki>GETPKT(name)</nowiki>

Checks the message port specified by the name argument to see whether any messages are available. The named message port must have been opened by a prior call to OPENPRT() within the current ARexx program. The returned value is the four-byte address of the first message packet, or '0000 0000'x if no packets were available.

The function returns immediately whether or not a packet is enqueued at the message port. Programs should never be designed to "busy-loop" on a message port. If there is no useful work to be done until the next message packet arrives, the program should call WAITPKT() and allow other tasks to proceed. See also WAITPKT(). For example:

<syntaxhighlight>
packet = GETPKT ('MyPort')
</syntaxhighlight>

== OPENPORT() ==

<nowiki>OPENPORT(name)</nowiki>

Creates a public message port with the given name. The returned Boolean value indicates whether the port was successfully opened. An initialization failure will occur if another port of the same name already exists or if a signal bit couldn't be allocated. The message port is allocated as a Port Resource node and is linked into the program's global data structure. Ports are automatically closed when the program exits and any pending messages are returned to the sender. See also CLOSEPORT(). For example:

<syntaxhighlight>
success = OPENPORT("MyPort")
</syntaxhighlight>

== REPLY() ==

<nowiki>REPLY(packet,rc)</nowiki>

Returns a message packet to the sender, with the primary result field set to the value given by the rc argument. The secondary result is cleared. The packet argument must be supplied as a four-byte address, and the rc argument must be a whole number. For example:

<syntaxhighlight>
CALL REPLY(packet,10) /*Error return*/
</syntaxhighlight>

== SHOWDIR() ==

<nowiki>SHOWDIR(directory[,'ALL'|'FILE'|'DIR'][,pad])</nowiki>

Returns the contents of the specified directory as a string of names separated by blanks. The second parameter is an option keyword that selects whether all entries, only files, or only subdirectories, will be included. For example:

<syntaxhighlight>
SAY SHOWDIR('SYS:REXXC', 'f', ';') -> WaitForPort;TS;TE;TCO;RXSET;RXLIB;RXC;RX;HI
</syntaxhighlight>

== SHOWLIST() ==

<nowiki>SHOWLIST({`A' | `D' | `H' | `T' | `L' | `M' | `P' | `R' | `S' | `T' | `V' | `W'}[,name][,pad])</nowiki>

An argument is entered using its initial letter. The arguments are:

; A
: ASSIGNS and Assigned Device

; D
: Device Drivers

; H
: Handlers

; I
: Interrupts

; L
: Libraries

; M
: Memory List Items

; P
: Ports

; R
: Resources

; S
: Semaphores

; T
: Tasks (Ready)

; V
: Volume Names

; W
: Waiting Tasks

If only one argument is supplied, SHOWLIST() returns a string separated by blanks: If a pad character is supplied, names will be separated by the pad rather than by blanks. If the name parameter is supplied. SHOWLIST() returns a Boolean value which indicates if the specified list contains that name. Names are case-sensitive. To provide an accurate snapshot of the current list, task switching is forbidden when the list is scanned.

<syntaxhighlight>
SAY SHOWLIST('P') -> REXX MyCon
SAY SHOWLIST('P',,';') -> REXX;MyCon
SAY SHOWLIST('P', 'REXX') -> 1
</syntaxhighlight>

== STATEF() ==

<nowiki>STATEF(filename)</nowiki>

Returns a string containing information about an external file. The string is formatted as:

<nowiki>"{DIR | FILE} length blocks protection days minutes ticks comment."</nowiki>

The length token gives the file length in bytes, and the block token specifies the file length in blocks. For example:

<syntaxhighlight>
SAY STATEF("LIBS:REXXSupport.library")
/*might give "File 2524 5 ----RW-D 4866 817 2088*/
</syntaxhighlight>

== WAITPKT() ==

<nowiki>WAITPKT(name)</nowiki>

Waits for a message to be received at the specified (named) port, which must have been opened by a call to OPENPORT() within the current ARexx program. The returned Boolean value indicates whether a message packet is available at the port. Normally the returned value will be 1 (True), since the function waits until an event occurs at the message port.

The packet must then be removed by a call to GETPKT() and should be returned eventually using the REPLY() function. Any message packets received but not returned when an ARexx program exits are automatically REPLYed with the return code set to 10. For example:

<syntaxhighlight>
CALL WAITPKT 'MyPort' /*Wait awhile*/
</syntaxhighlight>

AmigaOS Manual: ARexx Functions

2014-01-27T06:15:57Z

Tony Wyatt: Typos

A function is a program or group of statements that is executed whenever that function name is called in a particular context. A function may be part of an internal program, part of a library, or a separate external program. Functions are an important building block of modular programming because they allow you to construct large programs from a series of small, easily developed modules.

This chapter explains the different types of functions and how they are evaluated. It also provides an alphabetical reference of ARexx's built-in function library.

= Invoking a Function =

Within a ARexx program, a function is defined as a symbol or string followed immediately by an open parenthesis. The symbol or string (taken as a literal) specifies the function name, and the open parenthesis begins the argument list. Between the opening and closing parentheses are zero or more argument expressions, separated by commas, that supply the data being passed to the function.

Valid function calls are:

<syntaxhighlight>
CENTER ('title', 20)
ADDRESS()
'ALLOCMEM' (256*4,1)
</syntaxhighlight>

Each argument expression is evaluated in turn and the resulting strings are passed as the argument list to the function. Each argument expression, while often just a single literal value, can include arithmetic or string operations or even other function calls. Argument expressions are evaluated from left to right.

Functions can also be invoked using the CALL instruction. The CALL instruction, described in Chapter 4, can be used to invoke a function that may not return a value.

= Types of Functions =

There are three types of functions:

* Internal functions - defined within the ARexx program.
* Built-in functions - supplied by the ARexx programming language.
* Function Libraries - a special Amiga shared library.

== Internal Functions ==

An internal function is identified by a label within the program. When the internal function is called. ARexx creates a new storage environment so that the previous caller's environment is preserved. The new environment inherits the values from its predecessor, but subsequent changes to the environment variables do not affect the previous environment.

The specific values preserved are:

* The current and previous host addresses.
* The NUMERIC DIGITS, FUZZ, and FORM settings.
* The trace option, inhibit flag, and interactive flag.
* The state of the interrupt flags as defined by the SIGNAL instruction.
* The current prompt string as set by the OPTIONS PROMPT instruction.

The new environment does not automatically get a new symbol table, so initially all of the variables in the previous environment are available to the called function. The PROCEDURE instruction can be used to create a table and thereby protect the caller's symbol values. PROCEDURE can also be used to allow the same variable name to be used in two different areas with two different values.

Execution of the internal function proceeds until a RETURN instruction is executed. At this point the new environment is dismantled, and control resumes at the point of the function call. The expression supplied with the RETURN instruction is evaluated and passed back to the caller as the function result.

== Built-In Functions ==

ARexx provides a substantial library of predefined functions as part of the language system. These functions are always available and have been optimized to work with the internal data structures. In general, the built-in functions execute much faster than an equivalent interpreted function, so their usage is strongly recommended.

Several of the built-in functions create and manipulate external AmigaDOS files. Files are referenced by a logical name, a case-sensitive name that is assigned to a file when it is first opened. The initial input and output streams are given the names STDIN (standard input) and STDOUT (standard output). There is no theoretical limit to the number of files that may be open simultaneously, although a limit will be imposed by available memory. All open files are closed automatically when the program exits.

== External Function Libraries ==

A function library is a collection of one or more functions organized as an Amiga shared library. The library must reside in LIBS:, but may be either memory or disk-resident. Disk-resident libraries are loaded and opened as needed.

The library has to be especially tailored for use by ARexx. Each function library must contain a library name, a search priority, an entry point offset, and a version number. When ARexx is searching for a function, the interpreter opens each library and checks its "query" entry point. This entry point must be specified as an integer offset (e.g. "-30") from the library base. The return code from the query call indicates whether the desired function was found. If the function is found, it is called with the parameters passed by the interpreter, and the function result is returned to the caller. If it is not found, a "Function not found" error code is returned, and the search continues with the next library in the list. Function libraries are always closed after being checked so that the operating system can reclaim the memory space if required.

=== The Library List ===

The ARexx resident process maintains a list of the currently available function libraries and function hosts called the Library List. Application programs can add or remove function libraries as required.

The Library List is maintained as a priority-sorted queue. Each entry has an associated search priority in the range 100 (highest) to -100 (lowest). Entries can be added at an appropriate priority to control the function name resolution. Libraries with higher priorities are searched first. Within a given priority level, those libraries added first are searched first. The priority levels are significant if any of the libraries have duplicate function name definitions, since the function located further down the search chain could never be called.

== External Function Hosts ==

The name associated with a function host is the name of its public message port. Function calls are passed to the host as a message packet; it is then up to the individual host to determine whether the specified function name is one that it recognizes. The name resolution is completely internal to the host, so function hosts provide a natural gateway mechanism for implementing remote procedure calls to other machines in a network. The ARexx resident process is a function host and is installed in the Library List with a priority of -60.

= The Search Order =

Function linkages in ARexx are established at the time of the function call. A specific search order is followed until a function matching the name symbol or string is found. If the specified function cannot be located, an error is generated and the expression evaluation is terminated. The full search order is:

; Internal Functions
: The program source is examined for a label that matches the function name. If a match is found, a new storage environment is created and control is transferred to the label.

; Built-In Functions
: The built-in function library is searched for the specified name. All of these functions are defined by uppercase names.

; Function Libraries and Function Hosts
: The available function libraries and function hosts are maintained in the Library List, which is searched starting at the highest priority until the requested function is found or the end of the list is reached. Function hosts are called using a message-passing protocol similar to that used for commands and may be used as gateways for remote procedure calls to other machines in a network.

; External ARexx Programs
: The final search step is to check for an external ARexx program file by sending an invocation message to the ARexx resident process. The search always begins in the current directory and follows the same search path as the original ARexx program invocation. The name matching process is not case-sensitive.

The function name-matching procedure may be case-sensitive for some of the search steps, but not for others. The matching procedure used in a function library or function host is design dependent. Functions defined with mixed-case names must be called using a string token, since symbol names are always translated to uppercase.

The full search order is followed whenever the function name is defined by a symbol token. However, the search for internal functions is bypassed if the name is specified by a string token. This allows internal functions to usurp the names of external functions, as in the following example:

<syntaxhighlight>
CENTER: /*internal "CENTER"*/
ARG string, length /*get arguments*/
length = MIN(length,60) /*compute length*/
return 'CENTER' (string, length)
</syntaxhighlight>

Here the built-in function CENTER() has been replaced by an internal function after modifying the length argument.

= The Clip List =

The Clip List is a publicly accessible mechanism that can be used as a general clipboard for intertask communication. Many functions use the clipboard for retrieving different types of information, such as predefined constants or strings.

The Clip List maintains a set of (name, value) pairs that may be used for a variety of purposes. (SETCLIP() is used to add pairs to the list.) Each entry in the list consists of a name and a value string and may be located by name. In general, the names used should be chosen to be unique to an application to prevent unintended duplications with other programs. Any number of entries may be posted to the list.

One potential application for the Clip List is as a mechanism for loading predefined constants into an ARexx program. For example:

<syntaxhighlight>
pi=3.14159; e=2.718; sqrt2=1.414 . . .
</syntaxhighlight>

(i.e., a series of assignments separated by semicolons). In use, such a string could be retrieved by name using the built-in function GETCLIP() and then INTERPRETed within the program. The assignment statements within the string would then create the required constant definitions. For example:

<syntaxhighlight>
/*Assume a string called "numbers" is available*/
numbers = GETCLIP ('numbers')
INTERPRET numbers /*. . . assignments*/
</syntaxhighlight>

The strings would not be restricted to contain only assignment statements, but could include any valid ARexx statements. The Clip List could thus provide a series of programs for initializations or other processing tasks.

The resident process supports addition and deletion operations for maintaining the Clip List. The names in the (name,value) pairs are assumed to be in mixed case and are maintained to be unique in the list. An attempt to add a string with an existing name will simply update the value string. The name and value strings are copied when an entry is posted to the list, so the program that adds an entry is not required to maintain the strings.

Entries posted to the Clip List remain available until explicitly removed. The Clip List is automatically released when the resident process exits.

= Built-in Functions Reference =

This section provides an alphabetical list of the built-in functions. The syntax of each function is shown to the right of the function keyword.

== Syntax ==

Optional arguments are shown in brackets and generally have a default value that is used if the argument is omitted. When an option keyword is specified as an argument, only the first character is significant. Option keywords are not case-sensitive.

Many functions accept a pad character argument. Pad characters are inserted to fill or create spaces. For functions that accept a pad argument, only the first character of the argument string is significant. If a null string is supplied, the default padding character, usually a blank, will be used.

In the following examples, an arrow (->) is used as an abbreviation for "evaluates as." The arrow will not be displayed when a program is run. For example:

<syntaxhighlight>
SAY ABS (-5.35) -> 5.35
</syntaxhighlight>

This means that SAY ABS(-5.35) is evaluated as 5.35.

== Alphabetical Reference ==

=== ABBREV() ===

<nowiki>ABBREV(string1,string2[,length])</nowiki>

Returns a Boolean value that indicates whether string2 is an abbreviation of string1 with length greater than or equal to the specified length argument. The default length is 0, so the null string is an acceptable abbreviation. For example:

<syntaxhighlight>
SAY ABBREV ('fullname', 'ful') -> 1
SAY ABBREV ('almost', 'alm',4) -> 0
SAY ABBREV ('any','') -> 1
</syntaxhighlight>

=== ABS() ===

<nowiki>ABS(number)</nowiki>

Returns the absolute value of the number argument. This value must be numeric. For example:

<syntaxhighlight>
SAY ABS(-5.35) -> 5.35
SAY ABS(10) -> 10
</syntaxhighlight>

=== ADDLIB() ===

<nowiki>ADDLIB(name,priority[,offset,version])</nowiki>

Adds a function library or a function host to the library list maintained by the resident process. The name argument specifies either the name of a function library or the public message port associated with a function host. The name is case-sensitive. Any specified libraries should reside in the system LIBS: directory.

The priority argument specifies the search priority and must be an integer between 100 and -100, inclusive. The offset and version arguments apply only to libraries. The offset is the integer offset to the library's "query" entry point, and the version is an integer specifying the minimum acceptable release level of the library.

The function returns a Boolean result that indicates whether the operation was successful. If a library is specified, it is not actually opened at this time. Similarly, ARexx does not check to see whether a specified function host port is open. For example:

<syntaxhighlight>
SAY ADDLIB ("rexxsupport.library",0,-30,0) -> 1
CALL ADDLIB "EtherNet",-20 /*A gateway*/
</syntaxhighlight>

=== ADDRESS() ===

<nowiki>ADDRESS()</nowiki>

Returns the current host address string. The host address is the message port to which commands will be sent. The SHOW() function can be used to check whether the required external host is actually available. See also SHOW(). For example:

<syntaxhighlight>
SAY ADDRESS() -> REXX
</syntaxhighlight>

=== ARG() ===

<nowiki>ARG([number][,'EXISTS'|'OMITTED'])</nowiki>

ARG() returns the number of arguments supplied to the current environment. If only the number parameter is supplied, the corresponding argument string is returned. If a number and the Exists or Omitted keyword is given, the Boolean return indicates the status of the corresponding argument. The existence or omission test does not indicate whether the string has a null value, but only whether a string was supplied. For example:

<syntaxhighlight>
/*Assume arguments were: ('one',,10)*/
SAY ARG() -> 3
SAY ARG(1) -> one
SAY ARG(2,'O') -> 1
</syntaxhighlight>

=== B2C() ===

<nowiki>B2C(string)</nowiki>

Converts a string of binary digits (0,1) into the corresponding (packed) character representation. The conversion is the same as though the argument string had been specified as a literal binary string (e.g. `1010'B). Blanks are permitted in the string, but only at byte boundaries. This function is particularly useful for creating strings that are to be used as bit masks. See also X2C(). For example:

<syntaxhighlight>
SAY B2C('00110011') -> 3
SAY B2C('01100001') -> a
</syntaxhighlight>

=== BITAND() ===

<nowiki>BITAND(string1,string2[,pad])</nowiki>

The argument strings are logically ANDed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string, string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITAND('0313'x, 'FFF0'x) -> '0310'x
</syntaxhighlight>

=== BITCHG() ===

<nowiki>BITCHG(string,bit)</nowiki>

Changes the state of the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITCHG('0313'x,4) -> '0303'x
</syntaxhighlight>

=== BITCLR() ===

<nowiki>BITCLR(string,bit)</nowiki>

Clears (sets to zero) the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITCLR('0313'x,4) -> '0303'x
</syntaxhighlight>

=== BITCOMP() ===

<nowiki>BITCOMP(string1,string2[,pad])</nowiki>

Compares the argument strings bit-by-bit, starting at bit number 0. The returned value is the bit number of the first bit in which the strings differ, or -1 if the strings are identical. For example:

<syntaxhighlight>
BITCOMP('7F'x, 'FF'x) -> 7 /*Seventh bit*/
BITCOMP('FF'x, 'FF'x) -> -1
</syntaxhighlight>

=== BITOR() ===

<nowiki>BITOR(string1,string2[,pad])</nowiki>

The argument strings are logically ORed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded in the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITOR('0313'x, '00F'x) -> '033F'x
</syntaxhighlight>

=== BITSET() ===

<nowiki>BITSET(string,bit)</nowiki>

Sets the specified bit in the argument string to 1. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITSET('313'x,2) -> '0317'x
</syntaxhighlight>

=== BITTST() ===

<nowiki>BITTST(string,bit)</nowiki>

The Boolean return indicates the state of the specified bit in the argument string. Bit numbers are defined such that bit 0 is the low-order bit of the rightmost byte of the string. For example:

<syntaxhighlight>
BITTST('0313=x,4) -> 1
</syntaxhighlight>

=== BITXOR() ===

<nowiki>BITXOR(string1,string2[,pad])</nowiki>

The argument strings are logically and exclusively-ORed together, with the length of the result being the longer of the two operand strings. If a pad character is supplied, the shorter string is padded on the right. Otherwise, the operation terminates at the end of the shorter string, and the remainder of the longer string is appended to the result. For example:

<syntaxhighlight>
BITXOR('0313'x, '001F'x) -> '030C'X
</syntaxhighlight>

=== C2B() ===

<nowiki>C2B(string)</nowiki>

Converts the character string into the equivalent string of binary digits. See also C2X(). For example:

<syntaxhighlight>
SAY C2B('abc') -> 011000010110001001100011
</syntaxhighlight>

=== C2D() ===

<nowiki>C2D(string[,n])</nowiki>

Converts the string argument from its character representation to the corresponding decimal number, expressed as ASCII digits (0-9). If n is supplied, the character string is considered to be a number expressed in n bytes. The string is truncated or padded with nulls on the left as required, and the sign bit is extended for the conversion. For example:

<syntaxhighlight>
SAY C2D('0020'x) -> 32
SAY C2D('FFFF ffff'x) -> -1
SAY C2D('FF0100'x,2) -> 256
</syntaxhighlight>

=== C2X() ===

<nowiki>C2X(string)</nowiki>

Converts the string argument from its character representation to the corresponding hexadecimal number, expressed as the ASCII characters 0-9 and A-F. See also C2B(). For example:

<syntaxhighlight>
SAY C2X('abc') -> 616263
</syntaxhighlight>

=== CENTER()/CENTRE() ===

<nowiki>CENTER(string,length[,pad])</nowiki>
<nowiki>CENTRE(string,length[,pad])</nowiki>

Centers the string argument in a string with the specified length. If the length is longer than that of the string, pad characters or blanks are added as necessary. For example:

<syntaxhighlight>
SAY CENTER('abc',6) -> ' abc '
SAY CENTER('abc',6,'+') -> '+abc++'
SAY CENTER ('123456',3) -> '234'
</syntaxhighlight>

=== CLOSE() ===

<nowiki>CLOSE(file)</nowiki>

Closes the file specified by the given logical name. The returned value is a Boolean success flag and will be 1 unless the specified file was not open. For example:

<syntaxhighlight>
SAY CLOSE('input') -> 1
</syntaxhighlight>

=== COMPARE() ===

<nowiki>COMPARE(string1,string2[,pad])</nowiki>

Compares two strings and returns the index of the fist position in which they differ or 0 if the strings are identical. The shorter string is padded as required using the supplied character or blanks. For example:

<syntaxhighlight>
SAY COMPARE('abcde', 'abcce') -> 4
SAY COMPARE('abcde', 'abcde') -> 0
SAY COMPARE('abc++', 'abc+-', '+') -> 5
</syntaxhighlight>

=== COMPRESS() ===

<nowiki>COMPRESS(string[,list])</nowiki>

If the list argument is omitted, the function removes leading, trailing or embedded blank characters from the string argument. If the optional list is supplied, it specifies the characters to be removed from the string. For example:

<syntaxhighlight>
SAY COMPRESS(' why not ') -> whynot
SAY COMPRESS('++12-34-+', '+-') -> 1234
</syntaxhighlight>

=== COPIES() ===

<nowiki>COPIES(string,number)</nowiki>

Creates a new string by concatenating the specified number of copies of the original. The number argument may be zero, in which case the null string is returned. For example:

<syntaxhighlight>
SAY COPIES('abc',3) -> abcabcabc
</syntaxhighlight>

=== D2C() ===

<nowiki>D2C(number)</nowiki>

Creates a string whose value is the binary (packed) representation of the given decimal number. For example:

<syntaxhighlight>
D2C(65) -> A
</syntaxhighlight>

=== D2X() ===

<nowiki>D2X(number[,digits])</nowiki>

Converts a decimal number to hexadecimal. For example:

<syntaxhighlight>
D2X(31) -> 1F
</syntaxhighlight>

=== DATATYPE() ===

<nowiki>DATATYPE(string[,option])</nowiki>

If only the string argument is specified, DATATYPE() tests whether the string parameter is a valid number and returns either NUM or CHAR. If an option keyword is given, the Boolean return indicates whether the string satisfied the requested test. The following option keywords are recognized:

; ALPHANUMERIC
: Accepts alphabetic (A-Z, a-z) or numeric (0-9) characters

; BINARY
: Accepts a binary digits string

; LOWERCASE
: Accepts lowercase alphabetic (a-z) characters

; MIXED
: Accepts mixed upper/lowercase characters

; NUMERIC
: Accepts valid numbers

; SYMBOL
: Accepts valid REXX symbols

; UPPER
: Accepts uppercase alphabetic (A-Z) characters

; WHOLE
: Accepts integer numbers

; X
: Accepts Hex digits strings

For example:

<syntaxhighlight>
SAY DATATYPE('123') -> NUM
SAY DATATYPE('1a f2', 'X') -> 1
SAY DATATYPE('aBcde', 'L') -> 0
</syntaxhighlight>

=== DATE() ===

<nowiki>DATE([option][,date][format])</nowiki>

Returns the current date in the specified format. The default (`NORMAL') option returns the date in the form DD MMM YYYY, as in 20 APR 1988. The options recognized are:

; BASEDATE
: The number of days since January 1, 0001

; CENTURY
: The number of days since January 1 of the century

; DAYS
: The number of days since January 1 of the current year

; EUROPEAN
: The date in the form DD/MM/YY

; INTERNAL
: Internal system days

; JULIAN
: The date in the form YYDDD

; MONTH
: The current month (in mixed case)

; NORMAL
: The date in the form DD MMM YYYY

; ORDERED
: The date in the form YY/MM/DD

; SORTED
: The date in the form YYYYMMDD

; USA
: The date in the form MM/DD/YY

; WEEKDAY
: The day of the week (in mixed case)

These options can be shortened to just the first character.

The DATE() functions also accepts optional second and third arguments to supply the date either in the form of internal system days or in the `sorted' form YYYYMMDD. The second argument is specifying either system days (the default) or a sorted date. The third argument specifies the form of the date and can be either `I' or `S'. The current date in system days can be retrieved using DATE(`INTERNAL'). For example:

<syntaxhighlight>
SAY DATE() -> 14 Jul 1992
SAY DATE('M') -> July
SAY DATE(S) -> 19920714
SAY DATE('S' ,DATE('I')+21) -> 19920804
SAY DATE('W' ,19890609, 'S') -> Friday
</syntaxhighlight>

=== DELSTR() ===

<nowiki>DELSTR(string,n[,length])</nowiki>

Deletes the substring of the string argument beginning with the nth character for the specified length in characters. The default length is the remaining length of the string. For example:

<syntaxhighlight>
SAY DELSTR('123456',2,3) -> 156
</syntaxhighlight>

=== DELWORD() ===

<nowiki>DELWORD(string,n[,length])</nowiki>

Deletes the substring of the string argument beginning with the nth word for the specified length in words. The default length is the remaining length of the string. The deleted string includes any trailing blanks following the last word. For example:

<syntaxhighlight>
SAY DELWORD('Tell me a story',2,2) -> 'Tell story'
SAY DELWORD('one two three',3) -> 'one two '
</syntaxhighlight>

=== DIGITS() ===

<nowiki>DIGITS()</nowiki>

Returns the current Numeric Digits setting. For example:

<syntaxhighlight>
NUMERIC DIGITS 6
SAY DIGITS() -> 6
</syntaxhighlight>

=== EOF() ===

<nowiki>EOF(file)</nowiki>

Checks the specified logical file name and returns the Boolean value 1 (True), if the end-of-file has been reached, and 0 (False) otherwise. For example:

<syntaxhighlight>
SAY EOF(infile) -> 1
</syntaxhighlight>

=== ERRORTEXT() ===

<nowiki>ERRORTEXT(n)</nowiki>

Returns the error message associated with the specified ARexx error code. The null string is returned if the number is not a valid error code. For example:

<syntaxhighlight>
SAY ERRORTEXT(41) -> Invalid expression
</syntaxhighlight>

=== EXISTS() ===

<nowiki>EXISTS(filename)</nowiki>

Tests whether an external file of the given filename exists. The name string may include device and directory specifications. For example:

<syntaxhighlight>
SAY EXISTS('SYS:C/ED') -> 1
</syntaxhighlight>

=== EXPORT() ===

<nowiki>EXPORT(address[,string][,length][,pad])</nowiki>

Copies data from the optional string into a previously-allocated memory area. This memory area must be specified as a four-byte address. The length parameter specifies the maximum number of characters to be copied. The default is the length of the string. If the specified length is longer than the string, the remaining area is filled with the pad character or nulls (`00'x). The returned value is the number of characters copied.

{{Note|title=Caution|text=Any area of memory can be overwritten, possibly causing a system crash. Task switching is forbidden while the copy is being done, so system performance may be degraded if long strings are copied.}}

See also IMPORT() and STORAGE(). For example:

<syntaxhighlight>
count = EXPORT('0004 0000'x, 'The answer')
</syntaxhighlight>

=== FIND() ===

<nowiki>FIND(string,phrase)</nowiki>

The FIND() function locates a phrase of words in a larger string of words and returns the word number of the matched position. For example:

<syntaxhighlight>
SAY FIND('Now is the time', 'is the') -> 2
</syntaxhighlight>

=== FORM() ===

<nowiki>FORM()</nowiki>

Returns the current NUMERIC FORM setting. For example:

<syntaxhighlight>
NUMERIC FORM SCIENTIFIC
SAY FORM() -> SCIENTIFIC
</syntaxhighlight>

=== FREESPACE() ===

<nowiki>FREESPACE(address,length)</nowiki>

Returns a block of memory of a given length to the interpreter's internal pool. The address argument must be a 4 byte string obtained by a prior call to GETSPACE(), the internal allocator. It is not always necessary to release internally allocated memory, since it will be released to the system when the program terminates. However, if a very large block has been allocated, returning it to the pool may avoid memory space problems. The return value is a Boolean success flag. See also GETSPACE().

Calling FREESPACE() with no arguments will return the amount of memory available in the interpreter's internal pool. For example:

<syntaxhighlight>
FREESPACE('00042000'x,32) -> 1
</syntaxhighlight>

=== FUZZ() ===

<nowiki>FUZZ()</nowiki>

Returns the current NUMERIC FUZZ setting. For example:

<syntaxhighlight>
NUMERIC FUZZ 3
SAY FUZZ() -> 3
</syntaxhighlight>

=== GETCLIP() ===

<nowiki>GETCLIP(name)</nowiki>

Searches the Clip List for an entry matching the supplied name parameter and returns the associated value string. The name matching is case-sensitive. The null string is returned if the name cannot be found. See also SETCLIP(). For example:

<syntaxhighlight>
/*Assume 'numbers' contains 'PI=3.14159'*/
SAY GETCLIP('numbers') -> PI=3.14159
</syntaxhighlight>

=== GETSPACE() ===

<nowiki>GETSPACE(length)</nowiki>

Allocates a block of memory of the specified length from the interpreter's internal pool. The returned value is the four-byte address of the allocated block, which is not cleared or otherwise initialized. Internal memory is automatically returned to the system when the ARexx program terminates, so this function should not be used to allocate memory for use by external programs. The REXXSupport.Library includes the function ALLOCMEM(), which allocates memory from the system free list. See also FREESPACE(). For example:

<syntaxhighlight>
SAY C2X (GETSPACE(32)) -> '0003BF40'x
</syntaxhighlight>

=== HASH() ===

<nowiki>HASH(string)</nowiki>

Returns the hash attribute of a string as a decimal number and updates the internal hash value of the string. For example:

<syntaxhighlight>
SAY HASH('1') -> 49
</syntaxhighlight>

=== IMPORT() ===

<nowiki>IMPORT(address[,length])</nowiki>

Creates a string by copying data from the specified four-byte address. If the length parameter is not supplied, the copy terminates when a null byte is found. See also EXPORT(). For example:

<syntaxhighlight>
extval = IMPORT('0004 0000'x,8)
</syntaxhighlight>

=== INDEX() ===

<nowiki>INDEX(string,pattern[,start])</nowiki>

Searches for the first occurrence of the pattern argument in the string argument, beginning at the specified start position. The default start position is 1. The returned value is the index of the matched pattern or 0 if the pattern was not found. For example:

<syntaxhighlight>
SAY INDEX("123456", "23") -> 2
SAY INDEX("123456", "77") -> 0
SAY INDEX("123123", "23",3) -> 5
</syntaxhighlight>

=== INSERT() ===

<nowiki>INSERT(new,old[,start][,length][,pad])</nowiki>

Inserts the new string into the old string after the specified start position. The default starting position is 0. The new string is truncated or padded to the specified length as required, using the supplied pad character or blanks. If the start position is beyond the end of the string, the old string is padded on the right. For example:

<syntaxhighlight>
SAY INSERT('ab', '12345') -> ab12345
SAY INSERT('123', '++',3,5, '-') -> ++-123--
</syntaxhighlight>

=== LASTPOS() ===

<nowiki>LASTPOS(pattern,string[,start])</nowiki>

Searches backwards for the first occurrence of the pattern argument in the string argument, beginning at the specified start position. The default starting position is the end of the string. The returned value is the index of the matched pattern or 0 if the pattern was not found. For example:

<syntaxhighlight>
SAY LASTPOS('2', '1234') -> 2
SAY LASTPOS('2', '1234234') -> 5
SAY LASTPOS('2', '123234',3) -> 2
SAY LASTPOS('2', '13579') -> 0
</syntaxhighlight>

=== LEFT() ===

<nowiki>LEFT(string,length[,pad])</nowiki>

Returns the leftmost substring in the given string argument with the specified length. If the substring is shorter than the requested length, it is padded on the right with the supplied pad character or blanks. For example:

<syntaxhighlight>
SAY LEFT('123456',3) -> 123
SAY LEFT('123456',8, '+') -> 123456++
</syntaxhighlight>

=== LENGTH() ===

<nowiki>LENGTH(string)</nowiki>

Returns the length of the string. For example:

<syntaxhighlight>
SAY LENGTH('three') -> 5
</syntaxhighlight>

=== LINES() ===

<nowiki>LINES(file)</nowiki>

Returns the number of lines queued or typed ahead at the logical file, which must refer to an interactive stream. The line count is obtained as the secondary result of a WaitForChar() call. For example:

<syntaxhighlight>
PUSH 'a line'
PUSH 'another one'
SAY LINES(STDIN) -> 2
</syntaxhighlight>

=== MAX() ===

<nowiki>MAX(number,number[,number,...])</nowiki>

Returns the maximum of the supplied arguments, all of which must be numeric. At least two parameters must be supplied. For example:

<syntaxhighlight>
SAY MAX(2.1,3,-1) -> 3
</syntaxhighlight>

=== MIN() ===

<nowiki>MIN(number,number[,number,...])</nowiki>

Returns the minimum of the supplied arguments, all of which must be numeric. At least two parameters must be supplied. For example:

<syntaxhighlight>
SAY MIN(2.1,3,-1) -> -1
</syntaxhighlight>

=== OPEN() ===

<nowiki>OPEN(file,filename[,'APPEND'|'READ'|'WRITE'])</nowiki>

Opens an external file for the specified operation. The file argument defines the logical name by which the file will be referenced. The filename is the external name of he file and may include device and directory specifications. The function returns a Boolean value that indicates whether the operation was successful. There is no limit to the number of files that can be open simultaneously, and all open files are closed automatically when the program exits. See also CLOSE(), READ(), and WRITE(). For example:

<syntaxhighlight>
SAY OPEN('MyCon', 'CON:160/50/320/100/MyCON/cds') P-> 1
SAY OPEN('outfile', 'ram:temp', 'W') -> 1
</syntaxhighlight>

=== OVERLAY() ===

<nowiki>OVERLAY(new,old[,start][,length][,pad])</nowiki>

Overlays the new string onto the old string beginning at the specified start position, which must be positive. The default starting position is 1. The new string is truncated or padded to the specified length as required, using the supplied pad character or blanks. If the start position is beyond the end of the old string, the old string is padded on the right. For example:

<syntaxhighlight>
SAY OVERLAY('bb', 'abcd') -> bbcd
SAY OVERLAY('4', '123',5,5, '-') -> 123-4----
</syntaxhighlight>

=== POS() ===

<nowiki>POS(pattern,string[,start])</nowiki>

Searches for the first occurrence of the pattern argument in the string argument, beginning at the position specified by the start argument. The default starting position is 1. The value is the index of the matched string or 0 if the pattern wasn't found. For example:

<syntaxhighlight>
SAY POS('23', '123234') -> 2
SAY POS('77', '123234') -> 0
SAY POS('23', '123234',3) -> 4
</syntaxhighlight>

=== PRAGMA() ===

<nowiki>PRAGMA(option[,value])</nowiki>

This function allows a program to change various attributes relating to the system environment within which the program executes. The option argument is a keyword that specifies an environmental attribute. The value argument supplies the new attribute value to be installed. The value returned by the function depends on the attribute selected. Some attributes return the previous value installed, while others may simply set a Boolean success flag.

The currently defined option keywords are:

; DIRECTORY
: Specifies a new current directory. The current directory is used as the root for filenames that do not explicitly include a device specification. The return is the old directory name. PRAGMA(`D') is equivalent to PRAGMA(`D',"). It returns the path of the current directory without changing the directory.

; PRIORITY
: Specifies a new task priority. The priority value must be an integer in the range - 128 to 127, but the practical range is much more limited. ARexx programs should never be run at a priority higher than that of the resident process, which currently runs at a priority of 4. The returned value is the previous priority level.

; ID
: Returns the task ID (the address of the task block) as an 8-character hex string. The task ID is a unique identifier of the particular ARexx invocation and may be used to create a unique name for it.

; STACK
: Specifies a new stack value for your current ARexx program. When a new stack value is declared, the previous stack value is returned.

The currently implemented options are:

; PRAGMA('W',{'NULL'|' WORKBENCH'})
: Controls the task's WindowPtr field. Setting it to 'NULL' will suppress any requesters that might otherwise be generated by a DOS call.

; PRAGMA('*'[,name])
: Defines the specified logical name as the current ("*") console handler, allowing the user to open two streams on one window. If the name is omitted, the console handler is set to that of the client's process.

<syntaxhighlight>
SAY PRAGMA('D', 'DF0:C') -> Extras
SAY PRAGMA('D', 'DF1:C') -> Workbench:C
SAY PRAGMA('PRIORITY', -5) -> 0
SAY PRAGMA('ID') -> 00221ABC
CALL PRAGMA '*',STDOUT
SAY PRAGMA("STACK",8092) -> 4000
</syntaxhighlight>

=== RANDOM() ===

<nowiki>RANDOM([MIN][,MAX][,seed])</nowiki>

Returns a pseudo-random integer in the interval specified by the min and max arguments. The default minimum value is 0 and the default maximum value is 999. The interval max-min must be less than or equal to 1000. If a greater range of random integers is required, the values from the RANDU() function can be suitably scaled and translated. The seed argument can be supplied to initialize the internal state of the random number generator. See also RANDU(). For example:

<syntaxhighlight>
thisroll = RANDOM(1,6) /*Might be 1*/
nextroll = RANDOM(1,6) /*Might be snake eyes*/
</syntaxhighlight>

=== RANDU() ===

<nowiki>RANDU([seed])</nowiki>

Returns a uniformly-distributed, pseudo-random number between 0 and 1. The number of digits of precision in the result is always equal to the current Numeric Digits setting. With the choice of suitable scaling and translation values, RANDU() can be used to generate pseudo-random numbers on an arbitrary interval.

The optional integer seed argument is used to initialize the internal state of the random number generator. See also RANDOM(). For example:

<syntaxhighlight>
firsttry = RANDU() /*0.371902021?*/
NUMERIC DIGITS 3
tryagain = RANDU () /*0.873?*/
</syntaxhighlight>

=== READCH() ===

<nowiki>READCH(file,length)</nowiki>

Reads the specified number of characters from the given logical file into a string. The length of the returned string is the actual number of characters read and may be less than the requested length if, for example, the end-of-file was reached. See also READLN(). For example:

<syntaxhighlight>
instring = READCH('input',10)
</syntaxhighlight>

=== READLN() ===

<nowiki>READLN(file)</nowiki>

Reads characters from the given logical file into a string until a newline character is found. The returned string does not include the newline. See also READCH(). For example:

<syntaxhighlight>
instring = READLN('MyFile')
</syntaxhighlight>

=== REMLIB() ===

<nowiki>REMLIB(name)</nowiki>

Removes an entry with the given name from the Library List maintained by the resident process. The Boolean return is 1 if the entry was found and successfully removed. This function does not make a distinction between function libraries and function hosts, but simply removes a named entry. See also ADDLIB(). For example:

<syntaxhighlight>
SAY REMLIB('MyLibrary.library') -> 1
</syntaxhighlight>

=== REVERSE() ===

<nowiki>REVERSE(string)</nowiki>

Reverses the sequence of characters in the string. For example:

<syntaxhighlight>
SAY REVERSE('?ton yhw') -> why not?
</syntaxhighlight>

=== RIGHT() ===

<nowiki>RIGHT(string,length[,pad])</nowiki>

Returns the rightmost substring in the given string argument with the specified length. If the substring is shorter than the requested length, it is padded on the left with the supplied pad character or blanks. For example:

<syntaxhighlight>
SAY RIGHT('123456',4) -> 3456
SAY RIGHT('123456',8, '+') -> ++123456
</syntaxhighlight>

=== SEEK() ===

<nowiki>SEEK(file,offset[,'BEHIN'|'CURRENT'|'END'])</nowiki>

Moves to a new position in the given logical file, specified as an offset from an anchor position. The default anchor is Current. The returned value is the new position relative to the start of the file. For example:

<syntaxhighlight>
SAY SEEK('input',10,'B') -> 10
SAY SEEK('input',0,E') -> 356 /*file length*/
</syntaxhighlight>

=== SETCLIP() ===

<nowiki>SETCLIP(name[,value])</nowiki>

Adds a name-value pair to the Clip List maintained by the resident process. If an entry of the same name already exists, its value is updated to the supplied value string. Entries may be removed by specifying a null value. The function returns a Boolean value that indicates whether the operation was successful. For example:

<syntaxhighlight>
SAY SETCLIP('path', 'DF0:s') -> 1
SAY SETCLIP('path') -> 1
</syntaxhighlight>

=== SHOW() ===

<nowiki>SHOW(option[,name][,pad])</nowiki>

Returns the names in the resource list specified by the option argument, or tests to see whether an entry with the specified name is available. The currently implemented options keywords are:

; CLIP
: Examines the names in the Clip List

; FILES
: Examines the currently open logical file names

; LIBRARIES
: Examines the names in the Library List, which are either function libraries or function hosts.

; PORTS
: Examines the names in the system Ports List

If the name argument is omitted, the function returns a string with the resource names separated by a blank space or the pad character, if one was supplied. If the name argument is given, the returned Boolean value indicates whether the name was found in the resource list. The name entries are case-sensitive.

=== SIGN() ===

<nowiki>SIGN(number)</nowiki>

Returns 1 if the number argument is positive or zero and -1 if the number is negative. The argument must be numeric. For example:

<syntaxhighlight>
SAY SIGN(12) -> 1
SAY SIGN(-33) -> 1
</syntaxhighlight>

=== SOURCELINE() ===

<nowiki>SOURCELINE([line])</nowiki>

Returns the text for the specified line of the currently executing ARexx program. If the line argument is omitted, the function returns the total number of lines in the file. This function is often used to embed "help" information in a program. For example:

<syntaxhighlight>
/*A simple test program*/
SAY SOURCELINE() -> 3
SAY SOURCELINE(1)-> /*A simple test program*/
</syntaxhighlight>

=== SPACE() ===

<nowiki>SPACE(string,n[,pad])</nowiki>

Reformats the string argument so that there are n spaces (blank characters) between each pair of words. If the pad character is specified, it is used instead of blanks as the separator character. Specifying n as 0 will remove all blanks from the string. For example:

<syntaxhighlight>
SAY SPACE('Now is the time',3) -> 'Now is the time'
SAY SPACE('Now is the time',0) -> 'Nowisthetime'
SAY SPACE('1 2 3',1, '+') -> '1+2+3'
</syntaxhighlight>

=== STORAGE() ===

<nowiki>STORAGE([address][,string][,length][,pad])</nowiki>

STORAGE() with no arguments returns the available system memory. If the address argument is given, it must be a four-byte string. The function copies data from the (optional) string to the indicated memory address. The length parameter specifies the maximum number of bytes to be copied defaults to the length of the string. if the specified length is longer than the string, the remaining area is filled with the pad character or nulls ('00'x).

The returned value is the previous contents of the memory area. This can be used in a subsequent call to restore the original contents. See also EXPORT().

{{Note|title=Caution|text=Any area of memory can be overwritten, possibly causing a system crash. Task switching is forbidden while the copy is being done, so system performance may be degraded if long strings are copied.}}

For example:

<syntaxhighlight>
SAY STORAGE() -> ' 248400
oldval = STORAGE('0004 0000'x, 'The answer')
CALL STORAGE '0004 0000'x,,32, '+'
</syntaxhighlight>

=== STRIP() ===

<nowiki>STRIP(string[,{`B' | `L' | `T'}][,pad])</nowiki>

If neither of the optional parameters is supplied, the function removes both leading and trailing blanks from the string argument. The second argument specifies whether Leading, Trailing or Both (leading and trailing) characters are to be removed. The optional pad (or unpad) argument selects the character to be removed. For example:

<syntaxhighlight>
SAY STRIP(' say what? ') -> 'say What?'
SAY STRIP(' say what? ','L') -> 'say what?
SAY STRIP('++123+++', 'B', '+') -> '123'
</syntaxhighlight>

=== SUBSTR() ===

<nowiki>SUBSTR(string,start[,length][,pad])</nowiki>

Returns the substring of the string argument beginning at the specified start position for the specified length. The starting position must be positive, and the default length is the remaining length of the string. If the substring is shorter than the requested length, it is padded on the right with the blanks or the specified pad character. For example:

<syntaxhighlight>
SAY SUBSTR('123456',4,2) -> 45
SAY SUBSTR('myname',3,6, '=') -> name==
</syntaxhighlight>

=== SUBWORD() ===

<nowiki>SUBWORD(string,n[,length])</nowiki>

Returns the substring of the string argument beginning with the nth word for the specified length in words. The default length is the remaining length of the string. The returned string will never have leading or trailing blanks. For example:

<syntaxhighlight>
SAY SUBWORD('Now is the time ',2,2) -> is the
</syntaxhighlight>

=== SYMBOL() ===

<nowiki>SYMBOL(name)</nowiki>

Tests whether the name argument is a valid ARexx symbol. If the name is not a valid symbol, the function returns the string BAD. If the symbol is uninitialized, the returned string is LIT. If the symbol ha been assigned a value, VAR is returned. For example:

<syntaxhighlight>
SAY SYMBOL('J') -> VAR
SAY SYMBOL('x') -> LIT
SAY SYMBOL('++') -> BAD
</syntaxhighlight>

=== TIME() ===

<nowiki>TIME(option)</nowiki>

Returns the current system time or controls the internal elapsed time counter. The valid option keywords are:

; CIVIL
: Current time in 12 hour format (a.m./p.m.) hours/minutes

; ELAPSED
: Elapsed time in seconds since program start

; HOURS
: Current time in hours since midnight

; MINUTES
: Current time in minutes since midnight

; NORMAL
: Current time in 24 hour format (hours/minutes/seconds)

; RESET
: Reset the elapsed time clock

; SECONDS
: Current time in seconds since midnight

If no option is specified, the function returns the current system time in the form HH:MM:SS. For example:

<syntaxhighlight>
/*Suppose that the time is 1:02 AM . . .*/
SAY TIME('C'( -> 1:02 AM
SAY TIME('HOURS') -> 1
SAY TIME('M') -> 62
SAY TIME('N') -> 01:02:54
SAY TIME('S') -> 3720
call TIME('R') /*reset timer*/
SAY TIME('E') -> .020
SAY TIME() -> 01:02:00
</syntaxhighlight>

=== TRACE() ===

<nowiki>TRACE(option)</nowiki>

Sets the tracing mode (see Chapter 6) to that specified by the option keyword, which must be one of the valid alphabetic or prefix options. The TRACE() function will alter the tracing mode even during interactive tracing, when TRACE instructions in the source program are ignored. The returned value is the mode in effect before the function call. This allows the previous trace mode to be restored later. For example:

<syntaxhighlight>
/*Assume tracing mode is ?ALL*/
SAY TRACE('Results') -> ?A
</syntaxhighlight>

=== TRANSLATE() ===

<nowiki>TRANSLATE(string[,output][,input][,pad])</nowiki>

This function constructs a translation table and uses it to replace selected characters in the argument string. If only the string argument is given, it is translated to uppercase. If an input table is supplied, it modifies the translation table so that characters in the argument string that occur in the input table are replaced with the corresponding character in the output table. Characters beyond the end of the output table are replaced with the specified pad character or a blank. The result string is always for the same length as the original string. The input and output tables may be of any length. For example:

<syntaxhighlight>
SAY TRANSLATE("abcde", "123", "cbade", "+") -> 321++
SAY TRANSLATE("low") -> LOW
SAY TRANSLATE("0110", "10", "01") -> 1001
</syntaxhighlight>

=== TRIM() ===

<nowiki>TRIM(string)</nowiki>

Removes trailing blanks from the string argument. For example:

<syntaxhighlight>
SAY length (TRIM(' abc ')) -> 4
</syntaxhighlight>

=== TRUNC() ===

<nowiki>TRUNC(number[,places])</nowiki>

Returns the integer part of the number argument followed by the specified number of decimal places. The default number of decimal places is 0. The number is padded with zeroes as necessary. For example:

<syntaxhighlight>
SAY TRUNC(123.456) -> 123
SAY TRUNC(123.456,4) -> 123.4560
</syntaxhighlight>

=== UPPER() ===

<nowiki>UPPER(string)</nowiki>

Translate the string to uppercase. The action of this function is equivalent to that of TRANSLATE(string), but it is slightly faster for short strings. For example:

<syntaxhighlight>
SAY UPPER('One Fine Day') -> ONE FINE DAY
</syntaxhighlight>

=== VALUE() ===

<nowiki>VALUE(name)</nowiki>

Returns the value of the symbol represented by the name argument. For example:

<syntaxhighlight>
/*Assume that J has the value 12*/
SAY VALUE('j') -> 12
</syntaxhighlight>

=== VERIFY() ===

<nowiki>VERIFY(string,list[,'MATCH'])</nowiki>

Returns the index of the first character in the string argument which is not contained in the list argument or 0 if all of the characters are in the list. If the MATCH keyword is supplied, the function returns the index of the first character which is in the list or 0 if none of the characters are in the list. For example:

<syntaxhighlight>
SAY VERIFY('123456', '0123456789') -> 0
SAY VERIFY('123a56', '0123456789') -> 4
SAY VERIFY('123a45', 'abcdefghij', 'm') -> 4
</syntaxhighlight>

=== WORD() ===

<nowiki>WORD(string,n)</nowiki>

Returns the nth word in the string argument or the null string if there are fewer than n words. For example:

<syntaxhighlight>
SAY WORD('Now is the time ',2) -> is
</syntaxhighlight>

=== WORDINDEX() ===

<nowiki>WORDINDEX(string,n)</nowiki>

Returns the starting position of the nth word in the argument string or 0 if there are fewer than n words. For example:

<syntaxhighlight>
SAY WORDINDEX('Now is the time ',3) -> 8
</syntaxhighlight>

=== WORDLENGTH() ===

<nowiki>WORDLENGTH(string,n)</nowiki>

Returns the length of the nth word in the string argument. For example:

<syntaxhighlight>
SAY WORDLENGTH('one two three',3) -> 5
</syntaxhighlight>

=== WORDS() ===

<nowiki>WORDS(string)</nowiki>

Returns the number of words in the string argument. For example:

<syntaxhighlight>
SAY WORDS("You don't SAY!") -> 3
</syntaxhighlight>

=== WRITECH() ===

<nowiki>WRITECH(file,string)</nowiki>

Writes the string argument to the given logical file. The returned value is the actual number of characters written. For example:

<syntaxhighlight>
SAY WRITECH('output', 'Testing') -> 7
</syntaxhighlight>

=== WRITELN() ===

<nowiki>WRITELN(file,string)</nowiki>

Writes the string argument to the given logical file with a newline appended. The returned value is the actual number of characters written. For example:

<syntaxhighlight>
SAY WRITELN('output', 'Testing') -> 8
</syntaxhighlight>

=== X2C() ===

<nowiki>X2C(string)</nowiki>

Converts a string of hex digits into the (packed) character representation. Blank characters are permitted in the argument string at byte boundaries. For example:

<syntaxhighlight>
SAY X2C('12ab') -> '12ab'x
SAY X2C('12 ab') -> '12ab'x
SAY X2C(61) -> a
</syntaxhighlight>

=== X2D() ===

<nowiki>X2D(hex,digits)</nowiki>

Converts a hexadecimal number to decimal. For example:

<syntaxhighlight>
SAY X2D('1f') -> 31
</syntaxhighlight>

=== XRANGE() ===

<nowiki>XRANGE([start][,end])</nowiki>

Generates a string consisting of all characters numerically between the specified start and end values. The default start character is '00'x, and the default end character is 'FF'x. Only the first character of the start and end arguments is significant. For example:

<syntaxhighlight>
SAY XRANGE() -> '00010203 . . . FDFEFF'x
SAY XRANGE('a', 'f') -> 'abcdef'
SAY XRANGE(,'0A'x) -> '000102030405060708090A'x
</syntaxhighlight>

== Example Program ==

The following example program illustrates many of the built-in functions that manipulate character strings.

=== Program 13. Changestrings.rexx ===

<syntaxhighlight>
/*This ARexx program shows the effect of built-in functions that change strings. The functions come in two groups: one that manipulates individual characters and one that manipulates whole strings.*/

teststring1 = " every good boy does fine "

/*The first group is composed of the functions STRIP(), COMPRESS(), SPACE(), TRIM(), TRANSLATE(), DELSTR(), DELWORD(), INSERT(), OVERLAY(), and REVERSE().*/

/*STRIP() removes only leading and trailing characters.*/

/*Print the original string, for comparison. We put a period at the end of the string, so you can see what happens to the spaces at the end of the string.*/
SAY " every good boy does fine "

/*The same string stripped of leading and trailing spaces*/
SAY STRIP(" every good boy does fine ")"."

/*Failed attempt to remove leading and trailing "e"s*/
SAY STRIP(" every good boy does fine",,"e")"."

/*The "e"'s were protected by the leading and trailing spaces. Removing them exposes the "e"'s to the effects of STRIP()*/
SAY STRIP("every good boy does fine",,"e")"."

/*Remove "e"'s and spaces from the original string*/
SAY STRIP(" every good boy does fine ",," e")"."

/*We are now using the variable "teststring1", defined above. Remove only the trailing spaces in the test string.*/
SAY STRIP(teststring1, T)"."

/*Remove the trailing spaces and the "e"*/
SAY STRIP(teststring1,T," e")"."

/*Compress() removes characters anywhere in the string. This removes all blanks from the test string*/
SAY COMPRESS(teststring1)

CALL TIME('r')
SAY TIME('Civil') /*Civilian time HH:MM{AM | PM}*/
SAY TIME('h') /*Hours since midnight*/
SAY TIME('m') /*Minutes since midnight*/
SAY TIME('s') /*Seconds since midnight*/
SAY TIME('e') /*Elapsed time since program start*/

/*Function:TRACE Usage: TRACE( [option] )*/
SAY TRACE()
SAY TRACE(TRACE()) /*Leave it unchanged*/

/*Function:TRANSLATE Usage: TRANSLATE(string[,output][,input] [,pad])*/
SAY TRANSLATE('aBCdef') /*Translate to Uppercase*/
SAY TRANSLATE ('abcdef', '1234')
SAY TRANSLATE('654321', 'abcdef', '123456')
SAY TRANSLATE('abcdef', '123', 'abcdef', '+')

/*Function: TRIM Usage: TRIM(string)*/
SAY TRIM(' abc ')

/*Function: TRUNC Usage: TRUNC(number[,places])*/
SAY TRUNC(123.456)
SAY '$'TRUNC(134566.123,2)

/*Function: UPPER Usage: UPPER(string)*/
SAY UPPER('aBCdef12')

/*Function: VALUE Usage: VALUE(name)*/
abc = 'my name'
SAY VALUE('abc')

/*Function: VERIFY Usage: VERIFY(string,list[,'M'])*/
SAY VERIFY('123a45', '0123456789')
SAY VERIFY('abc3de', '012456789', 'M')

/*Function: WORD Usage: OWRD(string,n)*/
SAY WORD('Now is the time',3)

/*Function: WORDINDEX Usage: WORDINDEX(string,n)*/
SAY WORDINDEX('Now is the time ',3)

/*Function: WORDLENGTH Usage: WORDLENGTH(string,n)*/
SAY WORDLENGTH('Now is the time ',4)

/*Function: WORDS Usage: WORDS(string)*/
SAY WORDS('Now is the time')

/*Function: WRITECH Usage: WRITECH(logical,string)*/
IF OPEN('test','ram:test$$', 'W') THEN DO
SAY WRITECH('test', 'message') /*Write the string*/
CALL CLOSE 'test'
END

/*Function: WRITELN Usage: WRITELN(logical,string)*/
IF OPEN('test', 'ram:test$$', 'W') THEN DO
SAY WRITELN('test', 'message')
/*Write the string (with newline)*/
CALL CLOSE 'test'
END

/*Function: X2C Usage: X2C(heystring)*/
SAY X2C('616263') /*Convent to character (pack)*/

/*Function: XRANGE Usage: XRANGE([start] [,end])*/
SAY C2X(xrange('f0'x))
SAY XRANGE('a', 'g')
EXIT
</syntaxhighlight>

The output of Program 13 is:

every good boy does fine
every good boy does fine.
every good boy does fine .
very good boy does fin.
very good boy does fin.
every good boy does fine.
every good boy does fin.
everygoodboydoesfine
1:23PM /*These results vary depending*/
13 /*on the time the program is run.*/
803
48199
0.80
N
N
ABCDEF
abcdef
fedcba
123+++
abc
123
$134566.12
ABCDEF12
my name
4
0
the
8
4
4
7
8
abc
F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF
abcdefg

= REXXSupport.Library Functions =

The functions listed in this section are part of the REXXSupport.library. They may only be used if this library has been opened. Below is an example that shows you how to open this library.

== Program 14. OpenLibrary.rexx ==

<syntaxhighlight>
/*Add rexxsupport.library if it isn't already open.*/
IF ~ SHOW ('L', "rexxsupport.library") THEN DO
/*If the library isn't open, try to open it*/
IF ADDLIB('rexxsupport.library', 0, -30,0)
THEN SAY "Added rexxsupport.library."
ELSE DO
SAY 'ARexx support library not available, exiting'
EXIT 10 /*Exit if ADDLIB() failed*/
END
END
</syntaxhighlight>

== ALLOCMEM() ==

<nowiki>ALLOCMEM(length[,attribute])</nowiki>

Allocates a block of memory of the specified length from the system free-memory pool and returns its address as a four-byte string. The optional attribute parameter must be a standard EXEC memory allocation flag, supplied as a four-byte string. The default attribute is for "PUBLIC" memory (not cleared). Refer to [[Exec_Memory_Allocation|Exec Memory Allocation]] for information on memory types and attribute parameters.

This function should be used whenever memory is allocated for use by external programs. It is the user's responsibility to release the memory space when it is no longer needed. See also FREEMEM(). For example:

<syntaxhighlight>
SAY C2X(ALLOCMEM(1000)) -> 00050000
SAY C2X(ALLOCMEM (1000, '00 01 00 0 1'X)) -> 00228400
/*1000 bytes of CLEAR Public memory*/
</syntaxhighlight>

== CLOSEPORT() ==

<nowiki>CLOSEPORT(name)</nowiki>

Closes the message port specified by the name argument, which must have been allocated by a call to OPENPORT() within the current ARexx program. Any messages received but not yet REPLYed are automatically returned with the return code set to 10. See also OPENPORT(). For example:

<syntaxhighlight>
CALL CLOSEPORT myport
</syntaxhighlight>

== FREEMEM() ==

<nowiki>FREEMEM(address,length)</nowiki>

Releases a block of memory of the given length to the system free list. The address parameter is a four-byte string, typically obtained by a prior call to ALLOCMEM(). FREEMEM() cannot be used to release memory allocated using GETSPACE(), the ARexx internal memory allocator. The returned value is a Boolean success flag. See also ALLOCMEM(). For example:

<syntaxhighlight>
MemoryRequest = 1024
MyMem = ALLOCMEM(MemoryRequest)
SAY C2X(MyMem) -> 07C987B0
SAY FREEMEM(MyMem, MemoryRequest) -> 1
/*Or: SAY FREEMEM('07C987B0'x,1024)*/
</syntaxhighlight>

{{Note|title=Caution|text=Before your program terminates, you must use a matching FREEMEM() to release the exact amount of memory you allocated with each ALLOCMEM(). Otherwise, you may crash the system or leave memory unavailable until you reboot.}}

== GETARG() ==

<nowiki>GETARG(packet[,n])</nowiki>

Extracts a command, function name, or argument string from a message packet. The packet argument must be a four-byte address obtained from a prior call to GETPKT(). The optional [n] argument specifies the slot containing the string to be extracted and must be less than or equal to the actual argument count for the packet. Commands and function names are always in slot 0. Function packets my have argument strings in slots 1-15. For example:

<syntaxhighlight>
command = GETARG(packet)
function = GETARG(packet,0) /*name string*/
arg1 = GETARG(packet,1) /*1st argument*/
</syntaxhighlight>

== GETPKT() ==

<nowiki>GETPKT(name)</nowiki>

Checks the message port specified by the name argument to see whether any messages are available. The named message port must have been opened by a prior call to OPENPRT() within the current ARexx program. The returned value is the four-byte address of the first message packet, or '0000 0000'x if no packets were available.

The function returns immediately whether or not a packet is enqueued at the message port. Programs should never be designed to "busy-loop" on a message port. If there is no useful work to be done until the next message packet arrives, the program should call WAITPKT() and allow other tasks to proceed. See also WAITPKT(). For example:

<syntaxhighlight>
packet = GETPKT ('MyPort')
</syntaxhighlight>

== OPENPORT() ==

<nowiki>OPENPORT(name)</nowiki>

Creates a public message port with the given name. The returned Boolean value indicates whether the port was successfully opened. An initialization failure will occur if another port of the same name already exists or if a signal bit couldn't be allocated. The message port is allocated as a Port Resource node and is linked into the program's global data structure. Ports are automatically closed when the program exits and any pending messages are returned to the sender. See also CLOSEPORT(). For example:

<syntaxhighlight>
success = OPENPORT("MyPort")
</syntaxhighlight>

== REPLY() ==

<nowiki>REPLY(packet,rc)</nowiki>

Returns a message packet to the sender, with the primary result field set to the value given by the rc argument. The secondary result is cleared. The packet argument must be supplied as a four-byte address, and the rc argument must be a whole number. For example:

<syntaxhighlight>
CALL REPLY(packet,10) /*Error return*/
</syntaxhighlight>

== SHOWDIR() ==

<nowiki>SHOWDIR(directory[,'ALL'|'FILE'|'DIR'][,pad])</nowiki>

Returns the contents of the specified directory as a string of names separated by blanks. The second parameter is an option keyword that selects whether all entries, only files, or only subdirectories, will be included. For example:

<syntaxhighlight>
SAY SHOWDIR('SYS:REXXC', 'f', ';') -> WaitForPort;TS;TE;TCO;RXSET;RXLIB;RXC;RX;HI
</syntaxhighlight>

== SHOWLIST() ==

<nowiki>SHOWLIST({`A' | `D' | `H' | `T' | `L' | `M' | `P' | `R' | `S' | `T' | `V' | `W'}[,name][,pad])</nowiki>

An argument is entered using its initial letter. The arguments are:

; A
: ASSIGNS and Assigned Device

; D
: Device Drivers

; H
: Handlers

; I
: Interrupts

; L
: Libraries

; M
: Memory List Items

; P
: Ports

; R
: Resources

; S
: Semaphores

; T
: Tasks (Ready)

; V
: Volume Names

; W
: Waiting Tasks

If only one argument is supplied, SHOWLIST() returns a string separated by blanks: If a pad character is supplied, names will be separated by the pad rather than by blanks. If the name parameter is supplied. SHOWLIST() returns a Boolean value which indicates if the specified list contains that name. Names are case-sensitive. To provide an accurate snapshot of the current list, task switching is forbidden when the list is scanned.

<syntaxhighlight>
SAY SHOWLIST('P') -> REXX MyCon
SAY SHOWLIST('P',,';') -> REXX;MyCon
SAY SHOWLIST('P', 'REXX') -> 1
</syntaxhighlight>

== STATEF() ==

<nowiki>STATEF(filename)</nowiki>

Returns a string containing information about an external file. The string is formatted as:

<nowiki>"{DIR | FILE} length blocks protection days minutes ticks comment."</nowiki>

The length token gives the file length in bytes, and the block token specifies the file length in blocks. For example:

<syntaxhighlight>
SAY STATEF("LIBS:REXXSupport.library")
/*might give "File 2524 5 ----RW-D 4866 817 2088*/
</syntaxhighlight>

== WAITPKT() ==

<nowiki>WAITPKT(name)</nowiki>

Waits for a message to be received at the specified (named) port, which must have been opened by a call to OPENPORT() within the current ARexx program. The returned Boolean value indicates whether a message packet is available at the port. Normally the returned value will be 1 (True), since the function waits until an event occurs at the message port.

The packet must then be removed by a call to GETPKT() and should be returned eventually using the REPLY() function. Any message packets received but not returned when an ARexx program exits are automatically REPLYed with the return code set to 10. For example:

<syntaxhighlight>
CALL WAITPKT 'MyPort' /*Wait awhile*/
</syntaxhighlight>

AmigaOS Manual: ARexx Instructions

2014-01-26T10:41:20Z

Tony Wyatt: More typos

An instruction clause begins with the name of a particular instruction and tells ARexx to perform a certain action. This chapter provides an alphabetical list of the instructions available in ARexx.

Each instruction keyword may be followed by one or more subkeywords, expressions, or other instruction-specific information. Instruction keywords and subkeywords are recognized only in this specific context. This allows the same keywords to be used in a different context as variables or function names. An instruction keyword cannot be followed by a colon (:) or an equals (=) operator.

= Syntax =

The syntax for each instruction is shown to the right of the keyword heading. The conventions used in the syntax are shown in Table 4-1:

{| class="wikitable"
|+ Table 4-1. Syntax Conventions
! Convention !! Definition
|-
| KEYWORD || All keywords and subkeywords are shown in upper case letters
|-
| <nowiki>|</nowiki> (vertical bar) || Alternative selections are separated by a vertical bar
|-
| { } (braces) || Required alternatives are enclosed by braces
|-
| [ ] (brackets) || Optional instruction parts are enclosed in brackets
|}

{{Note|The syntax conventions do not apply to the specifications following the keyword heading. They only apply to the syntax shown to the right of the instruction keyword.}}

For example, the format for the CALL instruction is:

CALL {symbol | string} [expression] [,expression,...]

You must supply a symbol or a string as an argument. The vertical bar identifies the alternative selections, and the braces indicate that the use of an argument is required. The specification of an expression is optional, as indicated by the brackets.

Examples are given at the end of the instruction specification. Explanations or evaluations of the examples are shown as ARexx comments /*...*/.

= Alphabetical Reference =

This section provides an alphabetical list of ARexx's built-in instructions. The syntax of each instruction is shown to the right of the instruction keyword.

== ADDRESS ==

<nowiki>ADDRESS [[symbol | string] | [VALUE][expressions]] </nowiki>

This instruction specifies a host address for commands issued by the interpreter. A host address is the name of an application's message port to which ARexx commands are sent. ARexx maintains two host addresses: a current and a previous value. Whenever a new host address is supplied, the previous address is lost and the current address becomes the previous one. These host addresses are part of a program's storage environment and are preserved across internal function calls. The current address can be retrieved with the built-in function ADDRESS().

The ADDRESS keyword alone interchanges the current and previous hosts. Repeated execution will toggle between the two host addresses.

ADDRESS {string | symbol]} specifies that the new host address is the string or symbol. The value of the string or symbol is the token itself. Message port names are case-sensitive. The appropriate syntax for a program command to a message port named MyPort is:

<syntaxhighlight>
ADDRESS 'MyPort'
</syntaxhighlight>

If you omit the single quotes around MyPort, ARexx will look for the message port MYPORT and generate an error. The current host address becomes the previous address. An expression specified after a string or symbol is evaluated and the result is issued to the specified host. No changes are made to the current or previous address strings. This provides a convenient way to issue a single command to an external host without disturbing the current host addresses. The return code from the command is treated as it would be from a command clause.

If ADDRESS [VALUE] expression is specified. ARexx uses the result of the expression as the new host address, and the current address becomes the previous address. The VALUE keyword may be omitted if the first token of the expression is not a symbol or string. For example:

<syntaxhighlight>
ADDRESS /*Swap current and previous address.*/
ADDRESS edit /*The new host address is EDIT.*/
ADDRESS edit 'top' /*Move to the top.*/
ADDRESS VALUE edit in /*Compute a new host address.*/
</syntaxhighlight>

== ARG ==

<nowiki>ARG [template] [,template...]</nowiki>

ARG is a shorthand form for the PARSE UPPER ARG instruction. It retrieves one or more of the argument strings available to the program and assigns values to the variables in the template. The number of argument strings available depends on whether the program was invoked as a command or a function. Command invocations normally have only one argument string, but functions may have up to 15. The argument strings are not altered by the ARG instruction. ARG returns upper case letters. For example:

<syntaxhighlight>
ARG first,second /*Retrieve arguments*/
</syntaxhighlight>

The structure and processing of templates is described briefly with the PARSE instruction.

== BREAK ==

<nowiki>BREAK</nowiki>

The BREAK instruction is used to exit from the range of a DO instruction or from within an INTERPRETed string. It is valid only in these contexts. If used within a DO statement, BREAK exits from the innermost DO statement containing the BREAK. This contrasts with the similar LEAVE instruction, which exits only from an iterative (repeating) DO. For example:

<syntaxhighlight>
DO /*Begin block*/
IF i>3 THEN BREAK /*Finished?*/
a = a + 1
y.a = name
END /*End block*/
</syntaxhighlight>

== CALL ==

<nowiki>CALL {symbol | string} [expressions] [,expression, ...]</nowiki>

The CALL instruction is used to invoke an internal or external function. The function name is specified by the symbol or string token. Any expressions that follow are evaluated and become the arguments to the called function. The value returned by the function is assigned to the special variable RESULT. It is not an error if a result string is not returned. In this case the variable RESULT is DROPped (becomes uninitialized).

The linkage to the function is established dynamically at the time of the call. ARexx follows a specific search order in attempting to locate the called function. For example:

<syntaxhighlight>
CALL CENTER name, length+4, '+'
</syntaxhighlight>

CENTER is the called function. The expressions will be evaluated and passed as arguments to CENTER.

== DO ==

<nowiki>DO [[var=exp] | [exp] [TO exp] [BY exp]] [FOR exp] [FOREVER] [WHILE exp | UNTIL exp]</nowiki>

The DO instruction begins a group of instructions executed as a block. The range of the DO instruction includes all statements up to and including an eventual END instruction.

If no subkeywords follow the DO instruction, the block is executed once. Subkeywords can be used to iterate the block until a termination condition occurs. An interative DO instruction is sometimes called a loop since ARexx "loops back" to perform the instruction repeatedly. The various parts of the DO instruction are:

* An initializer expression of the form "variable=expression" defines the index variable of the loop. The expression is evaluated when the DO range is first activated and the result is assigned to the index variable. On subsequent iterations an expression of the form "variable = variable + increment" is evaluated, where the increment is the result of the BY expression. If specified, the initializer expression must precede any of the other subkeywords.

* The expression following a BY symbol defines the increment to be added to the index variable in each subsequent iteration. The expression must yield a numeric result, which may be positive or negative and need not be an integer. The default increment is 1.

* The result of the TO expression specifies the upper (or lower) limit for the index variable. At each iteration the index variable is compared to the TO result. If the increment (BY result) is positive and the variable is greater than the limit, the DO instruction terminates and control passes to the statement following the END instruction. The loop also terminates if the increment is negative and the index variable is less than the limit.

* The FOR expression must yield a positive whole number when evaluated and specifies the maximum number of iterations to be performed. The loop terminates when this limit is reached, irrespective of the value of the index variable.

* The initializer BY, TO and FOR expressions are evaluated only when the instruction is first activated, so the increment and limits are fixed through the execution. A limit is not required. For example, the instruction "DO i=1" will simply count away forever.

* The FOREVER keyword can be used if an iterative DO instruction is required but no index variable is necessary. The loop will be terminated by a LEAVE or BREAK instruction contained within the loop.

* The WHILE expression is evaluated at the beginning of each iteration and must result in a Boolean value. The iteration proceeds if the result is 1 (true); otherwise, the loop terminates.

* The UNTIL expression is evaluated at the end of each iteration and must result in a Boolean value. The instruction continues with the next iteration if the result is 0 (false), and terminates otherwise. (WHILE and UNTIL are mutually exclusive.)

=== Program 12. Iteration.rexx ===

<syntaxhighlight>
/*Examples of DO*/
LIMIT = 20; number = 1
DO i=1 to LIMIT for 10 WHILE number < 20
number = i * number
SAY "Iteration" i "number=" number
END
number = number/3.345; i = 0
DO number for LIMIT/5
i = i + 1
SAY "Iteration" i "number=" number
END
</syntaxhighlight>

The output is shown with comment lines for explanation. The comments would not appear on your screen.

Iteration 1 number = 1 /*1 * 1 = 1*/
Iteration 2 number = 2 /*2 * 1 = 2*/
Iteration 3 number = 6 /*3 * 2 = 6*/
Iteration 4 number = 24 /*4 * 6 = 24*/
Iteration 1 number = 7.17488789 /*24/3.345 = 7.17488789*/
Iteration 2 number = 7.17488789 /*number doesn't change*/
Iteration 3 number = 7.17488789 /*limit/5 = 20/5 = 4*/
Iteration 4 number = 7.17488789 /*operation repeats 4 times*/

{{Note|If a FOR limit is also present, the initial expression is still evaluated, but the result need not be a positive integer.}}

== DROP ==

<nowiki>DROP variable [variable ...]</nowiki>

The specified variable symbols are reset to their unintialized state, in which the value of the variable is the variable name itself. It is not an error to DROP a variable that is already uninitialized. DROPping a stem symbol is equivalent to DROPping the values of all possible compound symbols derived from the stem. For example:

<syntaxhighlight>
a = 123 /*Assign a value to a */
DROP a b /*DROP (remove) the values from A and B*/
SAY a b /*Results in A B.*/
</syntaxhighlight>

== ECHO ==

<nowiki>ECHO [expression]</nowiki>

The ECHO instruction is a synonym for the SAY instruction. It displays the expression result on the console. For example:

<syntaxhighlight>
ECHO "you don't say"
</syntaxhighlight>

== ELSE ==

<nowiki>ELSE [;] [conditional statement]</nowiki>

The ELSE instruction provides the alternative conditional branch for an IF statement. It is valid only within the range of an IF instruction and must follow the conditional statement of the THEN branch. If the THEN branch isn't executed, the statement following the ELSE clause is performed.

ELSE clauses always bind to the nearest, preceding IF statement. It may be necessary to provide "dummy" ELSE clauses for the inner IF ranges of a compound IF statement to allow alternative branches for the outer IF statements. It is not sufficient to follow the ELSE with a semicolon or a null clause. Instead, the NOP (no-operation) instruction can be used. For example:

<syntaxhighlight>
IF i > 2 THEN SAY 'Really?'
ELSE SAY 'I thought so'
</syntaxhighlight>

== END ==

<nowiki>END [variable]</nowiki>

The END instruction terminates the range of a DO or SELECT instruction. If the optional variable symbol is supplied, it is compared to the index variable of the DO statement (which must be iterative). An error is generated if the symbols do not match. For example:

<syntaxhighlight>
DO i=1 to 5 /*Index variable is i*/
SAY i
END i /*End "i" loop*/
</syntaxhighlight>

== EXIT ==

<nowiki>EXIT [expression]</nowiki>

The EXIT instruction terminates the execution of a program. It is valid anywhere within a program. The evaluated expression is passed back to the caller as the function or command result.

The processing of the EXIT result depends on whether a result string was requested by the calling program and whether the current invocation resulted from a command or function call.

* If a result string was requested, the expression result is copied to a block of allocated memory and a pointer to the block is returned as the secondary result of the call.

* If the caller did not request a result string and the program was invoked as a command, an attempt is made to convert the expression result to an integer. This value is then returned as the primary result, with 0 as the secondary result. This allows the EXIT information to be interpreted as a return code by the caller.

For example:

<syntaxhighlight>
EXIT /*No result needed*/
EXIT 10 /*An error return*/
</syntaxhighlight>

== IF ==

<nowiki>IF expression [THEN] [;] [conditional statement]</nowiki>

The IF instruction is used in conjunction with THEN and ELSE instructions to conditionally execute a statement. The result of the expression must be a Boolean value. If the result is 1 (True), the statement following the THEN symbol is executed. Otherwise, control passes to the next statement. The THEN keyword need not immediately follow the IF expression, but may appear as a separate clause.

The instruction is analyzed as "IF expression; THEN; statement". The expression following the IF statement establishes the test condition that determines whether subsequent THEN or ELSE clauses will be performed. Any valid statement may follow the THEN symbol. In particular, a "DO ... END;" group allows a series of statements to be performed conditionally. For example:

<syntaxhighlight>
IF result < 0 THEN exit /*All done?*/
</syntaxhighlight>

== INTERPRET ==

<nowiki>INTERPRET expression</nowiki>

The INTERPRET command treats the expression as though it were a source statement block. The expression is evaluated and the result is executed as one or more program statements. The statements are considered as a group, as if surrounded by a "DO ... END" combination. Any statements can be included in the INTERPRETed source, including DO or SELECT instructions. The BREAK instruction can be used to terminate the processing of INTERPRETed statements.

An INTERPRET instruction activates a control range when it is executed, which serves as a boundary for LEAVE and ITERATE instructions. These instructions can only be used with DO loops defined within the INTERPRET. While it is not an error to include label clauses within the interpreted string, only those labels defined in the original program are searched during a transfer of control.

The INTERPRET instruction can be used to construct programs dynamically and then execute them. Program fragments may be passed as arguments to functions, which then INTERPRET the fragments. For example:

<syntaxhighlight>
inst = `SAY' /*An instruction*/
INTERPRET inst hello /*. . . "SAY HELLO"*/
</syntaxhighlight>

== ITERATE ==

<nowiki>ITERATE [variable]</nowiki>

The ITERATE instruction terminates the current iteration of a DO instruction and begins the next iteration. Effectively, control passes to the END statement and then (depending on the outcome of the UNTIL expression) back to the DO statement. The instruction normally acts on the innermost iterative DO range. An error results if the ITERATE instruction is not contained within an iterative DO instruction.

If several nested ranges exist, the optional variable symbol specifies which DO range is to be exited. The variable is taken as a literal and must match the index variable of a currently active DO instruction. An error results if a matching DO instruction is not found. For example:

<syntaxhighlight>
DO i=1 to 5
IF i = 3 THEN ITERATE i
SAY i
END
</syntaxhighlight>

== LEAVE ==

<nowiki>LEAVE [variable]</nowiki>

LEAVE forces an immediate exit from the iterative DO range containing the instruction. An error results if the LEAVE instruction is not contained within an iterative DO instruction. If several nested ranges exist, the optional variable symbol specifies which DO range is to be exited. The variable is taken as a literal and must match the index variable of a currently active DO instruction. An error results if a matching DO instruction is not found. For example:

<syntaxhighlight>
DO i = 1 to limit
IF i > 5 THEN LEAVE /*Maximum iterations*/
END
</syntaxhighlight>

== NOP ==

<nowiki>NOP</nowiki>

The NOP (NO-oPeration) instruction is provided to control the binding of ELSE clauses in compound IF statements. For example:

<syntaxhighlight>
IF i = j THEN /*First (outer) IF*/
IF j = k THEN a = 0 /*Inner IF*/
ELSE NOP /*Binds to inner IF*/
ELSE a = a + 1 /*Binds to outer IF*/
</syntaxhighlight>

== NUMERIC ==

<nowiki>NUMERIC {DIGITS | FUZZ} expression NUMERIC FORM {SCIENTIFIC | ENGINEERING}</nowiki>

* The NUMERIC instruction sets options relating to numeric precision and format. The numeric options are preserved when an internal function is called.

* The DIGITS expression option specifies the number of digits of precision for arithmetic calculations. The expression must evaluate to a positive whole number.

* The FUZZ expression option specifies the number of digits to be ignored in numeric comparison operations. This must be a positive whole number, less than the current DIGITS setting.

* The FORM SCIENTIFIC option specifies that numbers that require exponential notation be expressed in scientific notation. The exponent is adjusted so that the mantissa for non-zero number is between 1 and 10. This is the default format.

* The FORM ENGINEERING option selects engineering format for numbers that require exponential notation. Engineering format normalizes a number so that its exponent is a multiple of three and the mantissa (if not 0) is between 1 and 1000.

<syntaxhighlight>
NUMERIC DIGITS 12 /*12 digits of precision*/
NUMERIC FORM SCIENTIFIC /*Result in scientific notation*/
</syntaxhighlight>

== OPTIONS ==

<nowiki>OPTIONS [FAILAT expression]</nowiki>
<nowiki>OPTIONS [PROMPT expression]</nowiki>
<nowiki>OPTIONS [RESULTS]</nowiki>
<nowiki>OPTIONS [CACHE]</nowiki>

The OPTIONS instruction is used to set various internal defaults. The FAILAT expression sets the limit at or above which command return codes will be signaled as errors. It must evaluate to an integer value. The PROMPT expression provides a string to be used as the prompt with the PULL (or PARSE PULL) instruction. The RESULTS keyword indicates that the interpreter should request a result string when it issues commands to an external host.

The internal options controlled by this instruction are preserved across function calls, so an OPTIONS instruction can be issued within an internal function without affecting the caller's environment. If no keyword is specified with the OPTIONS instruction, all controlled options revert to their default settings. The OPTIONS instruction also accepts a NO keyword to reset a selected option to its default value, making it more convenient to reset the RESULTS attribute for a single command without having to reset the FAILAT and PROMPT options.

OPTIONS also accepts a CACHE keyword that can be used to enable or disable an internal statement-caching scheme. The cache is normally enabled. For example:

<syntaxhighlight>
OPTIONS FAILAT 10
OPTIONS PROMPT "Yes Boss?"
OPTIONS RESULTS
</syntaxhighlight>

== OTHERWISE ==

<nowiki>OTHERWISE [;] [conditional statement]</nowiki>

This instruction is valid only within the range of a SELECT instruction and must follow all of the "WHEN ... THEN" statements. If none of the preceding WHEN clauses has succeeded, the statement following the OTHERWISE instruction is executed. An OTHERWISE is not mandatory within a SELECT range. However, an error will result if the OTHERWISE clause is omitted and none of the WHEN instructions succeeds. For example:

<syntaxhighlight>
SELECT
WHEN i=1 THEN say 'one'
WHEN i=2 THEN say 'two'
OTHERWISE SAY 'other'
END
</syntaxhighlight>

== PARSE ==

<nowiki>PARSE [UPPER] inputsource [template] [,template ...]</nowiki>

The PARSE instruction provides a mechanism to extract one or more substrings from a string and assign them to variables. The input string can come from a variety of sources, including argument strings, an expression, or from the console.

Parsing is controlled by a template, which may consist of symbols, strings, operators and parentheses. The template provides both the variables to be given values and the way to determine the value strings. During the parsing operation the input string is split into substrings that are assigned to the variable symbols in the template. The process continues until all of the variables in the template have been assigned a value. If the input string is "used up", any remaining variables are given null values.

When a variable in the template is followed immediately by another variable, the value string is determined by breaking the input string into words separated by blanks. Leading and trailing blanks are not permitted. Each word is assigned to a variable in the template. Normally the last variable receives the untokenized remainder of the input string, since it is not followed by a symbol. A placeholder symbol, a period (.), forces the variable with the period to terminate at the first space in the input stream. Placeholders behave like variables except that they are never assigned a value.

The template may be omitted if the instruction is intended only to create the input string. Templates are described in Chapter 7.

The goal of the parsing operation is to associate a current and next position with each variable symbol in the template. The substring between these positions is then assigned as the value to the variable.

The different options of the instruction are described below.

* The optional UPPER keyword may be used with any of the input sources and specifies that the input string is to be translated to upper case before being parsed. It must be the first token following PARSE.
* The sources for the input strings are specified by the keyword symbols explained below. When multiple templates are supplied, each template receives a new input string, although for some source options the new string will be identical to the previous one. The input source string is copied before being parsed, so the original strings are never altered by the parsing process.
:* The ARG input option retrieves the argument strings supplied when the program was invoked. Command invocations normally have only a single argument string, but functions may have up to 15 argument strings.
:* The EXTERNAL input string is read from STDERR stream, (see Chapter 6) so as not to disturb any PUSHed or QUEUEd data. If multiple templates are supplied, each template will read a new string. This source option is the same as PULL.
:* The NUMERIC input option places the current numeric options in a string in the order DIGITS, FUZZ and FORM, separated by a single space.
:* The PULL input option reads a string from the input console. If multiple templates are supplied, each template will read a new string.
:* The SOURCE input option retrieves the "source" string for the program. This string is formatted as:
: <syntaxhighlight>
{COMMAND | FUNCTION} {0 | 1} CALLED RESOLVED EXT HOST
</syntaxhighlight>
: where:
:* {COMMAND | FUNCTION} indicates whether the program was invoked as a command or as a function.
:* {0 | 1} is a Boolean flag indicating whether a result string was requested by the caller.
:* CALLED is the name used to invoke this program.
:* RESOLVED is the final resolved name of the program.
:* EXT is the file extension to be used for searching (the default is "REXX").
:* HOST is the initial host address for commands.
: The SOURCE option now returns the full path name of the ARexx program file. Formerly just a relative name was given, which was not sufficient to locate the program's source file.
: The "VALUE expression WITH" input string is the result of the supplied expression. The WITH keyword is required to separate the expression from the template. The expression result may be parsed repeatedly by using multiple templates, but the expression is not re-evaluated.
: The "VAR variable" input option uses the value of the specified variable as the input string. When multiple templates are provided, each template uses the current value of the variable. This value may change if the variable is included as an assignment target in any of the templates.
: The VERSION input option of the current configuration of the ARexx interpreter is supplied in the form:
: <syntaxhighlight>
ARexx VERSION CPU MPU VIDEO FREQ
</syntaxhighlight>
: where:
:* VERSION is the release level of the interpreter, formatted as 1.14.
:* CPU indicates the processor currently running the program, and will be one of the values 68000, 68010, 68020, 68030 or 68040.
:* MPU will be either NONE, 68881, or 68882, depending on whether a math coprocessor is available.
:* VIDEO will indicate either NTSC or PAL.
:* FREQ gives the clock (line) frequency as either 60Hz or 50Hz.

For example:

<syntaxhighlight>
/*Numeric string is: "9 0 SCIENTIFIC"*/
PARSE NUMERIC DIGITS FUZZ FORM .
SAY Digits /*9*/
SAY fuzz /*0*/
SAY form /*SCIENTIFIC*/
myvar = 1234567890
PARSE VAR myvar 1 a 3 b +2 c 1 d
SAY a
SAY b
SAY c
SAY d
</syntaxhighlight>

This is the output:

12
34
567890
1234567890

== PROCEDURE ==

<nowiki>PROCEDURE [EXPOSE variable [variable...]]</nowiki>

The PROCEDURE instruction is used within an internal function to create a new symbol table. This protects the symbols defined in the caller's environment from being altered by the execution of the function. PROCEDURE is usually the first statement within the function, although it is valid anywhere within the function body. It is an error to execute two PROCEDURE statements within the same function.

The EXPOSE subkeyword provides a selective mechanism for accessing the caller's symbol table, and or passing global variables to a function. The variables following the EXPOSE keyword are taken to refer to symbols in the caller's table. Any subsequent changes made to these variables will be reflected in the caller's environment.

The variables in the EXPOSE list may include stem or compound symbols, in which case the ordering of the variables becomes significant. The EXPOSE list is processed from left to right and compound symbols are expanded based on the values in effect in the new generation. For example, suppose that the value of the symbol J in the previous generation is 123, and that J is uninitialized in the new generation. Then PROCEDURE EXPOSE J A.J will expose J and A.123, whereas PROCEDURE EXPOSE A.J J will expose A.J and J. Exposing a stem has the effect of exposing all possible compound symbols derived from that stem. That is, PROCEDURE EXPOSE A. exposes A.I, A.J, A.J.J, A.123, etc. For example:

<syntaxhighlight>
fact: PROCEDURE /*A recursive function*/
ARG i
IF i = 1
THEN RETURN 1
ELSE RETURN i * fact (i-1)
</syntaxhighlight>

== PULL ==

<nowiki>PULL [template] [,template...]</nowiki>

Pull is the shorthand form of the PARSE UPPER PULL instruction. It reads a string from the input console, translates it to upper case and parses it using the template. Multiple strings can be read by supplying additional templates. The instruction will read from the console even if no template is given. (Templates are described in Chapter 7.) For example:

<syntaxhighlight>
PULL first last . /*Read names*/
</syntaxhighlight>

== PUSH ==

<nowiki>PUSH [expression]</nowiki>

The PUSH instruction is used to prepare a stream of data to be read by a command shell or other program. It appends a newline to the result of the expression then stacks or "pushes" it into the STDIN stream. Stacked lines are placed in the stream in "last-in, first-out" order and are available to be read just as though they had been entered interactively. For example, after issuing the instructions:

<syntaxhighlight>
PUSH line 1
PUSH line 2
PUSH line 3
</syntaxhighlight>

the stream would be read in the order line 3, line 2, and line 1.

PUSH allows the STDIN stream to be used as a private scratch pad to prepare data for subsequent processing. For example, several files could be concatenated with delimiters between them by simply reading the input files, PUSHing the line into the stream and inserting a delimiter where required. For example:

<syntaxhighlight>
DO i=1 to 5
PUSH 'echo "Line 'i'"'
END
</syntaxhighlight>

== QUEUE ==

<nowiki>QUEUE [expression]</nowiki>

The QUEUE instruction is used to prepare a stream of data to be read by a command shell or other program. It is very similar to the PUSH instruction and differs only in that the data lines are placed in the STDIN stream in "first-in, first-out" order. In this case, the instructions:

<syntaxhighlight>
QUEUE line 1
QUEUE line 2
QUEUE line 3
</syntaxhighlight>

would be read in the order line 1, line 2, and line 3. The QUEUEd lines always precede all interactively-entered lines and always follow any PUSHed (stacked) lines. For example:

<syntaxhighlight>
DO i=1 to 5
QUEUE 'echo "Line 'i'"'
END
</syntaxhighlight>

== RETURN ==

<nowiki>RETURN [expression]</nowiki>

RETURN is used to leave a function and return control to the point of the function's invocation. The evaluated expression is returned as the function result. If an expression is not supplied, an error may result in the caller's environment. Functions called from within an expression must return a result string and will generate an error if no result is available. Functions invoked by the CALL instruction need to return a result.

A RETURN issued from the base environment of a program is not an error and is equivalent to an EXIT instruction. Refer to the EXIT instruction for a description of how result strings are passed back to an external caller. For example:

<syntaxhighlight>
RETURN 6*7 /*Returns 42*/
</syntaxhighlight>

== SAY ==

<nowiki>SAY [expression]</nowiki>

The result of the evaluated expressions is written to the output console, with a newline character appended. If the expression is omitted, a null string is sent to the console. For example:

<syntaxhighlight>
SAY 'The answer is ' value
</syntaxhighlight>

== SELECT ==

<nowiki>SELECT</nowiki>

SELECT begins a group of instructions containing one or more WHEN clauses and possibly a single OTHERWISE clause, each followed by a conditional statement. Only one of the conditional statements within the SELECT group will be executed. Each WHEN statement is executed in succession until one succeeds. If none succeeds, the OTHERWISE statement is executed. The SELECT range must be terminated by an END statement. For example:

<syntaxhighlight>
SELECT
WHEN i=1 THEN SAY 'one'
WHEN i=2 THEN SAY 'two'
OTHERWISE SAY 'other'
END
</syntaxhighlight>

== SHELL ==

<nowiki>SHELL [symbol | string | [[VALUE] [expression]]</nowiki>

The SHELL instruction is a synonym for the ADDRESS instruction. For example:

<syntaxhighlight>
SHELL edit /*Set host to `EDIT'*/
</syntaxhighlight>

== SIGNAL ==

<nowiki>SIGNAL {ON | OFF} condition SIGNAL [VALUE] expression</nowiki>

SIGNAL {ON | OFF} controls the state of the internal interrupt flags. Interrupts allow a program to detect and retain control when certain errors occur. In this form SIGNAL must be followed by one of the keywords ON or OFF and one of the condition keywords listed below. The interrupt flag specified by the condition symbol is then set to the indicated state. The valid signal conditions are:

{| class="wikitable"
| '''BREAK_C''' || A Ctrl+C break was detected.
|-
| '''BREAK_D''' || A Ctrl+D break was detected.
|-
| '''BREAK_E''' || A Ctrl+E break was detected.
|-
| '''BREAK_F''' || A Ctrl+F break was detected.
|-
| '''ERROR''' || A host command returned a non-zero code.
|-
| '''HALT''' || An external HALT request was detected.
|-
| '''IOERR''' || An error was detected by the I/O system.
|-
| '''NOVALUE''' || An uninitialized variable was used.
|-
| '''SYNTAX''' || A syntax or execution error was detected.
|}

The condition keywords are interpreted as labels to which control will be transferred if the selected condition occurs. For example, if the ERROR interrupt is enabled and a command returns a non-zero code, ARexx will transfer control to the label ERROR:. The condition label must be defined in the program; otherwise, an immediate SYNTAX error results and the program exits.

In SIGNAL [VALUE] expression, the tokens following SIGNAL are evaluated as an expression. An immediate interrupt is generated that transfers control to the label specified by the expression result. The instruction thus acts as a "computed goto".

Whenever an interrupt occurs, all currently active control ranges (IF, DO, SELECT, INTERPRET, or interactive TRACE) are dismantled before the transfer of control. Thus, the transfer cannot be used to jump into the range of a DO loop or other control structure. Only the control structures in the current environment are affected by a SIGNAL condition, making it safe to SIGNAL from within an internal function without affecting the state of the caller's environment.

The special variable SIGL is set to the current line number whenever a transfer of control occurs. The program can inspect SIGL to determine which line was being executed before the transfer. If an ERROR or SYNTAX condition causes an interrupt, the special variable RC is set to the error code that triggered the interrupt. For the ERROR condition, this code is usually an error severity level. Refer to Appendix A for further details on error codes and severity levels. The SYNTAX condition will always indicate an ARexx error code. For example:

<syntaxhighlight>
SIGNAL on error /*Enable interrupt*/
SIGNAL off syntax /*Disable SYNTAX*/
SIGNAL start /*Goto START*/
</syntaxhighlight>

== WHEN ==

<nowiki>WHEN expression [THEN [;] [conditional statement]]</nowiki>

The WHEN instruction is similar to the IF instruction, but is valid only within a SELECT range. Each WHEN expression is evaluated in turn and must result in a Boolean value. If the result is a 1, the conditional statement is executed and control passes to the END statement that terminates the SELECT. As with the IF instruction, the THEN need not be part of the same clause. For example:

<syntaxhighlight>
SELECT
WHEN i<j THEN SAY 'less'
WHEN i=j THEN SAY 'equal'
OTHERWISE SAY 'greater'
END
</syntaxhighlight>

AmigaOS Manual: ARexx Instructions

2014-01-26T10:19:02Z

Tony Wyatt: Fixed typos

An instruction clause begins with the name of a particular instruction and tells ARexx to perform a certain action. This chapter provides an alphabetical list of the instructions available in ARexx.

Each instruction keyword may be followed by one or more subkeywords, expressions, or other instruction-specific information. Instruction keywords and subkeywords are recognized only in this specific context. This allows the same keywords to be used in a different context as variables or function names. An instruction keyword cannot be followed by a colon (:) or an equals (=) operator.

= Syntax =

The syntax for each instruction is shown to the right of the keyword heading. The conventions used in the syntax are shown in Table 4-1:

{| class="wikitable"
|+ Table 4-1. Syntax Conventions
! Convention !! Definition
|-
| KEYWORD || All keywords and subkeywords are shown in uppercase letters
|-
| <nowiki>|</nowiki> (vertical bar) || Alternative selections are separated by a vertical bar
|-
| { } (braces) || Required alternatives are enclosed by braces
|-
| [ ] (brackets) || Optional instruction parts are enclosed in brackets
|}

{{Note|The syntax conventions do not apply to the specifications following the keyword heading. They only apply to the syntax shown to the right of the instruction keyword.}}

For example, the format for the CALL instruction is:

CALL {symbol | string} [expression] [,expression,...]

You must supply a symbol or a string as an argument. The vertical bar identifies the alternative selections, and the braces indicate that the use of an argument is required. The specification of an expression is optional, as indicated by the brackets.

Examples are given at the end of the instruction specification. Explanations or evaluations of the examples are shown as ARexx comments /*...*/.

= Alphabetical Reference =

This section provides an alphabetical list of ARexx's built-in instructions. The syntax of each instruction is shown to the right of the instruction keyword.

== ADDRESS ==

<nowiki>ADDRESS [[symbol | string] | [VALUE][expressions]] </nowiki>

This instruction specifies a host address for commands issued by the interpreter. A host address is the name of an application's message port to which ARexx commands are sent. ARexx maintains two host addresses: a current and a previous value. Whenever a new host address is supplied, the previous address is lost and the current address becomes the previous one. These host addresses are part of a program's storage environment and are preserved across internal function calls. The current address can be retrieved with the built-in function ADDRESS().

The ADDRESS keyword alone interchanges the current and previous hosts. Repeated execution will toggle between the two host addresses.

ADDRESS {string | symbol]} specifies that the new host address is the string or symbol. The value of the string or symbol is the token itself. Message port names are case-sensitive. The appropriate syntax for a program command to a message port named MyPort is:

<syntaxhighlight>
ADDRESS 'MyPort'
</syntaxhighlight>

Omit the single quotes around MyPort and ARexx looks for the message port MYPORT and generates an error. The current host address becomes the previous address. An expression specified after a string or symbol is evaluated and the result is issued to the specified host. No changes are made to the current or previous address strings. This provides a convenient way to issue a single command to an external host without disturbing the current host addresses. The return code from the command is treated as it would be from a command clause.

If ADDRESS [VALUE] expression is specified. ARexx uses the result of the expression as the new host address, and the current address becomes the previous address. The VALUE keyword may be omitted if the first token of the expression is not a symbol or string. For example:

<syntaxhighlight>
ADDRESS /*Swap current and previous address.*/
ADDRESS edit /*The new host address is EDIT.*/
ADDRESS edit 'top' /*Move to the top.*/
ADDRESS VALUE edit in /*Compute a new host address.*/
</syntaxhighlight>

== ARG ==

<nowiki>ARG [template] [,template...]</nowiki>

ARG is a shorthand form for the PARSE UPPER ARG instruction. It retrieves one or more of the argument strings available to the program and assigns values to the variables in the template. The number of argument strings available depends on whether the program was invoked as a command or a function. Command invocations normally have only one argument string, but functions may have up to 15. The argument strings are not altered by the ARG instruction. ARG returns uppercase letters. For example:

<syntaxhighlight>
ARG first,second /*Retrieve arguments*/
</syntaxhighlight>

The structure and processing of templates is described briefly with the PARSE instruction.

== BREAK ==

<nowiki>BREAK</nowiki>

The BREAK instruction is used to exit from the range of a DO instruction or from within an INTERPRETed string. It is valid only in these contexts. If used within a DO statement, BREAK exits from the innermost DO statement containing the BREAK. This contrasts with the similar LEAVE instruction, which exits only from an iterative (repeating) DO. For example:

<syntaxhighlight>
DO /*Begin block*/
IF i>3 THEN BREAK /*Finished?*/
a = a + 1
y.a = name
END /*End block*/
</syntaxhighlight>

== CALL ==

<nowiki>CALL {symbol | string} [expressions] [,expression, ...]</nowiki>

The CALL instruction is used to invoke an internal or external function. The function name is specified by the symbol or string token. Any expressions that follow are evaluated and become the arguments to the called function. The value returned by the function is assigned to the special variable RESULT. It is not an error if a result string is not returned. In this case the variable RESULT is DROPped (becomes uninitialized).

The linkage to the function is established dynamically at the time of the call. ARexx follows a specific search order in attempting to locate the called function. For example:

<syntaxhighlight>
CALL CENTER name, length+4, '+'
</syntaxhighlight>

CENTER is the called function. The expressions will be evaluated and passed as arguments to CENTER.

== DO ==

<nowiki>DO [[var=exp] | [exp] [TO exp] [BY exp]] [FOR exp] [FOREVER] [WHILE exp | UNTIL exp]</nowiki>

The DO instruction begins a group of instructions executed as a block. The range of the DO instruction includes all statements up to and including an eventual END instruction.

If not subkeywords follow the DO instruction, the block is executed once. Subkeywords can be used to iterate the block until a termination condition occurs. An interative DO instruction is sometimes called a loop since ARexx "loops back" to perform the instruction repeatedly. The various parts of the DO instruction are:

* An initializer expression of the form "variable=expression" defines the index variable of the loop. The expression is evaluated when the DO range is first activated and the result is assigned to the index variable. On subsequent iterations an expression of the form "variable = variable + increment" is evaluated, where the increment is the result of the BY expression. If specified, the initializer expression must precede any of the other subkeywords.

* The expression following a BY symbol defines the increment to be added to the index variable in each subsequent iteration. The expression must yield a numeric result, which may be positive or negative and need not be an integer. The default increment is 1.

* The result of the TO expression specifies the upper (or lower) limit for the index variable. At each iteration the index variable is compared to the TO result. If the increment (BY result) is positive and the variable is greater than the limit, the DO instruction terminates and control passes to the statement following the END instruction. The loop also terminates if the increment is negative and the index variable is less than the limit.

* The FOR expression must yield a positive whole number when evaluated and specifies the maximum number of iterations to be performed. The loop terminates when this limit is reached, irrespective of the value of the index variable.

* The initializer BY, TO and FOR expressions are evaluated only when the instruction is first activated, so the increment and limits are fixed through the execution. A limit is not required. For example, the instruction "DO i=1" will simply count away forever.

* The FOREVER keyword can be used if an iterative DO instruction is required but no index variable is necessary. The loop will be terminated by a LEAVE or BREAK instruction contained within the loop.

* The WHILE expression is evaluated at the beginning of each iteration and must result in a Boolean value. The iteration proceeds if the result is 1 (true); otherwise, the loop terminates.

* The UNTIL expression is evaluated at the end of each iteration and must result in a Boolean value. The instruction continues with the next iteration if the result is 0 (false), and terminates otherwise. (WHILE and UNTIL are mutually exclusive.)

=== Program 12. Iteration.rexx ===

<syntaxhighlight>
/*Examples of DO*/
LIMIT = 20; number = 1
DO i=1 to LIMIT for 10 WHILE number < 20
number = i * number
SAY "Iteration" i "number=" number
END
number = number/3.345; i = 0
DO number for LIMIT/5
i = i + 1
SAY "Iteration" i "number=" number
END
</syntaxhighlight>

The output is shown with comment lines for explanation. The comments would not appear on your screen.

Iteration 1 number = 1 /*1 * 1 = 1*/
Iteration 2 number = 2 /*2 * 1 = 2*/
Iteration 3 number = 6 /*3 * 2 = 6*/
Iteration 4 number = 24 /*4 * 6 = 24*/
Iteration 1 number = 7.17488789 /*24/3.345 = 7.17488789*/
Iteration 2 number = 7.17488789 /*number doesn't change*/
Iteration 3 number = 7.17488789 /*limit/5 = 20/5 = 4*/
Iteration 4 number = 7.17488789 /*operation repeats 4 times*/

{{Note|If a FOR limit is also present, the initial expression is still evaluated, but the result need not be a positive integer.}}

== DROP ==

<nowiki>DROP variable [variable ...]</nowiki>

The specified variable symbols are reset to their unintialized state, in which the value of the variable is the variable name itself. It is not an error to DROP a variable that is already uninitialized. DROPping a stem symbol is equivalent to DROPping the values of all possible compound symbols derived from the stem. For example:

<syntaxhighlight>
a = 123 /*Assign a value to a */
DROP a b /*DROP (remove) the values from A and B*/
SAY a b /*Results in A B.*/
</syntaxhighlight>

== ECHO ==

<nowiki>ECHO [expression]</nowiki>

The ECHO instruction is a synonym for the SAY instruction. It displays the expression result on the console. For example:

<syntaxhighlight>
ECHO "you don't say"
</syntaxhighlight>

== ELSE ==

<nowiki>ELSE [;] [conditional statement]</nowiki>

The ELSE instruction provides the alternative conditional branch for an IF statement. It is valid only within the range of an IF instruction and must follow the conditional statement of the THEN branch. If the THEN branch isn't executed, the statement following the ELSE clause is performed.

ELSE clauses always bind to the nearest, preceding IF statement. It may be necessary to provide "dummy" ELSE clauses for the inner IF ranges of a compound IF statement to allow alternative branches for the outer IF statements. It is not sufficient to follow the ELSE with a semicolon or a null clause. Instead, the NOP (no-operation) instruction can be used. For example:

<syntaxhighlight>
IF i > 2 THEN SAY 'Really?'
ELSE SAY 'I thought so'
</syntaxhighlight>

== END ==

<nowiki>END [variable]</nowiki>

The END instruction terminates the range of a DO or SELECT instruction. If the optional variable symbol is supplied, it is compared to the index variable of the DO statement (which must be iterative). An error is generated if the symbols do not match. For example:

<syntaxhighlight>
DO i=1 to 5 /*Index variable is i*/
SAY i
END i /*End "i" loop*/
</syntaxhighlight>

== EXIT ==

<nowiki>EXIT [expression]</nowiki>

The EXIT instruction terminates the execution of a program. It is valid anywhere within a program. The evaluated expression is passed back to the caller as the function or command result.

The processing of the EXIT result depends on whether a result string was requested by the calling program and whether the current invocation resulted from a command or function call.

* If a result string was requested, the expression result is copied to a block of allocated memory and a pointer to the block is returned as the secondary result of the call.

* If the caller did not request a result string and the program was invoked as a command, an attempt is made to convert the expression result to an integer. This value is then returned as the primary result, with 0 as the secondary result. This allows the EXIT information to be interpreted as a return code by the caller.

For example:

<syntaxhighlight>
EXIT /*No result needed*/
EXIT 10 /*An error return*/
</syntaxhighlight>

== IF ==

<nowiki>IF expression [THEN] [;] [conditional statement]</nowiki>

The IF instruction is used in conjunction with THEN and ELSE instructions to conditionally execute a statement. The result of the expression must be a Boolean value. If the result is 1 (True), the statement following the THEN symbol is executed. Otherwise, control passes to the next statement. The THEN keyword need not immediately follow the IF expression, but may appear as a separate clause.

The instruction is analyzed as "IF expression; THEN; statement". The expression following the IF statement establishes the test condition that determines whether subsequent THEN or ELSE clauses will be performed. Any valid statement may follow the THEN symbol. In particular, a "DO ... END;" group allows a series of statements to be performed conditionally. For example:

<syntaxhighlight>
IF result < 0 THEN exit /*All done?*/
</syntaxhighlight>

== INTERPRET ==

<nowiki>INTERPRET expression</nowiki>

The INTERPRET command treats the expression as though it were a source statement block. The expression is evaluated and the result is executed as one or more program statements. The statements are considered as a group, as if surrounded by a "DO ... END" combination. Any statements can be included in the INTERPRETed source, including DO or SELECT instructions. The BREAK instruction can be used to terminate the processing of INTERPRETed statements.

An INTERPRET instruction activates a control range when it is executed, which serves as a boundary for LEAVE and ITERATE instructions. These instructions can only be used with DO loops defined within the INTERPRET. While it is not an error to include label clauses within the interpreted string, only those labels defined in the original program are searched during a transfer of control.

The INTERPRET instruction can be used to construct programs dynamically and then execute them. Program fragments may be passed as arguments to functions, which then INTERPRET the fragments. For example:

<syntaxhighlight>
inst = `SAY' /*An instruction*/
INTERPRET inst hello /*. . . "SAY HELLO"*/
</syntaxhighlight>

== ITERATE ==

<nowiki>ITERATE [variable]</nowiki>

The ITERATE instruction terminates the current iteration of a DO instruction and begins the next iteration. Effectively, control passes to the END statement and then (depending on the outcome of the UNTIL expression) back to the DO statement. The instruction normally acts on the innermost iterative DO range. An error results if the ITERATE instruction is not contained within an iterative DO instruction.

If several nested ranges exist, the optional variable symbol specifies which DO range is to be exited. The variable is taken as a literal and must match the index variable of a currently active DO instruction. An error results if a matching DO instruction is not found. For example:

<syntaxhighlight>
DO i=1 to 5
IF i = 3 THEN ITERATE i
SAY i
END
</syntaxhighlight>

== LEAVE ==

<nowiki>LEAVE [variable]</nowiki>

LEAVE forces an immediate exit from the iterative DO range containing the instruction. An error results if the LEAVE instruction is not contained within an iterative DO instruction. If several nested ranges exist, the optional variable symbol specifies which DO range is to be exited. The variable is taken as a literal and must match the index variable of a currently active DO instruction. An error results if a matching DO instruction is not found. For example:

<syntaxhighlight>
DO i = 1 to limit
IF i > 5 THEN LEAVE /*Maximum iterations*/
END
</syntaxhighlight>

== NOP ==

<nowiki>NOP</nowiki>

The NOP (NO-oPeration) instruction is provided to control the binding of ELSE clauses in compound IF statements. For example:

<syntaxhighlight>
IF i = j THEN /*First (outer) IF*/
IF j = k THEN a = 0 /*Inner IF*/
ELSE NOP /*Binds to inner IF*/
ELSE a = a + 1 /*Binds to outer IF*/
</syntaxhighlight>

== NUMERIC ==

<nowiki>NUMERIC {DIGITS | FUZZ} expression NUMERIC FORM {SCIENTIFIC | ENGINEERING}</nowiki>

* The NUMERIC instruction sets options relating to numeric precision and format. The numeric options are preserved when an internal function is called.

* The DIGITS expression option specifies the number of digits of precision for arithmetic calculations. The expression must evaluate to a positive whole number.

* The FUZZ expression option specifies the number of digits to be ignored in numeric comparison operations. This must be a positive whole number, less than the current DIGITS setting.

* The FORM SCIENTIFIC option specifies that numbers that require exponential notation be expressed in scientific notation. The exponent is adjusted so that the mantissa for non-zero number is between 1 and 10. This is the default format.

* The FORM ENGINEERING option selects engineering format for numbers that require exponential notation. Engineering format normalizes a number so that its exponent is a multiple of three and the mantissa (if not 0) is between 1 and 1000.

<syntaxhighlight>
NUMERIC DIGITS 12 /*12 digits of precision*/
NUMERIC FORM SCIENTIFIC /*Result in scientific notation*/
</syntaxhighlight>

== OPTIONS ==

<nowiki>OPTIONS [FAILAT expression]</nowiki>
<nowiki>OPTIONS [PROMPT expression]</nowiki>
<nowiki>OPTIONS [RESULTS]</nowiki>
<nowiki>OPTIONS [CACHE]</nowiki>

The OPTIONS instruction is used to set various internal defaults. The FAILAT expression sets the limit at or above which command return codes will be signaled as errors. It must evaluate to an integer value. The PROMPT expression provides a string to be used as the prompt with the PULL (or PARSE PULL) instruction. The RESULTS keyword indicates that the interpreter should request a result string when it issues commands to an external host.

The internal options controlled by this instruction are preserved across function calls, so an OPTIONS instruction can be issued within an internal function without affecting the caller's environment. If no keyword is specified with the OPTIONS instruction, all controlled options revert to their default settings. The OPTIONS instruction also accepts a NO keyword to reset a selected option to its default value, making it more convenient to reset the RESULTS attribute for a single command without having to reset the FAILAT and PROMPT options.

OPTIONS also accepts a CACHE keyword that can be used to enable or disable an internal statement-caching scheme. The cache is normally enabled. For example:

<syntaxhighlight>
OPTIONS FAILAT 10
OPTIONS PROMPT "Yes Boss?"
OPTIONS RESULTS
</syntaxhighlight>

== OTHERWISE ==

<nowiki>OTHERWISE [;] [conditional statement]</nowiki>

This instruction is valid only within the range of a SELECT instruction and must follow all of the "WHEN ... THEN" statements. If none of the preceding WHEN clauses has succeeded, the statement following the OTHERWISE instruction is executed. An OTHERWISE is not mandatory within a SELECT range. However, an error will result if the OTHERWISE clause is omitted and none of the WHEN instructions succeeds. For example:

<syntaxhighlight>
SELECT
WHEN i=1 THEN say 'one'
WHEN i=2 THEN say 'two'
OTHERWISE SAY 'other'
END
</syntaxhighlight>

== PARSE ==

<nowiki>PARSE [UPPER] inputsource [template] [,template ...]</nowiki>

The PARSE instruction provides a mechanism to extract one or more substrings from a string and assign them to variables. The input string can come from a variety of sources, including argument strings, an expression, or from the console.

Parsing is controlled by a template, which may consist of symbols, strings, operators and parentheses. The template provides both the variables to be given values and the way to determine the value strings. During the parsing operation the input string is split into substrings that are assigned to the variable symbols in the template. The process continues until all of the variables in the template have been assigned a value. If the input string is "used up", any remaining variables are given null values.

When a variable in the template is followed immediately by another variable, the value string is determined by breaking the input string into words separated by blanks. Leading and trailing blanks are not permitted. Each word is assigned to a variable in the template. Normally the last variable receives the untokenized remainder of the input string, since it is not followed by a symbol. A placeholder symbol, a period (.), forces the variable with the period to terminate at the first space in the input stream. Placeholders behave like variables except that they are never assigned a value.

The template may be omitted if the instruction is intended only to create the input string. Templates are described in Chapter 7.

The goal of the parsing operation is to associate a current and next position with each variable symbol in the template. The substring between these positions is then assigned as the value to the variable.

The different options of the instruction are described below.

* The optional UPPER keyword may be used with any of the input sources and specifies that the input string is to be translated to upper case before being parsed. It must be the first token following PARSE.
* The sources for the input strings are specified by the keyword symbols explained below. When multiple templates are supplied, each template receives a new input string, although for some source options the new string will be identical to the previous one. The input source string is copied before being parsed, so the original strings are never altered by the parsing process.
:* The ARG input option retrieves the argument strings supplied when the program was invoked. Command invocations normally have only a single argument string, but functions may have up to 15 argument strings.
:* The EXTERNAL input string is read from STDERR stream, (see Chapter 6) so as not to disturb any PUSHed or QUEUEd data. If multiple templates are supplied, each template will read a new string. This source option is the same as PULL.
:* The NUMERIC input option places the current numeric options in a string in the order DIGITS, FUZZ and FORM, separated by a single space.
:* The PULL input option reads a string from the input console. If multiple templates are supplied, each template will read a new string.
:* The SOURCE input option retrieves the "source" string for the program. This string is formatted as:
: <syntaxhighlight>
{COMMAND | FUNCTION} {0 | 1} CALLED RESOLVED EXT HOST
</syntaxhighlight>
: where:
:* {COMMAND | FUNCTION} indicates whether the program was invoked as a command or as a function.
:* {0 | 1} is a Boolean flag indicating whether a result string was requested by the caller.
:* CALLED is the name used to invoke this program.
:* RESOLVED is the final resolved name of the program.
:* EXT is the file extension to be used for searching (the default is "REXX").
:* HOST is the initial host address for commands.
: The SOURCE option now returns the full path name of the ARexx program file. Formerly just a relative name was given, which was not sufficient to locate the program's source file.
: The "VALUE expression WITH" input string is the result of the supplied expression. The WITH keyword is required to separate the expression from the template. The expression result may be parsed repeatedly by using multiple templates, but the expression is not re-evaluated.
: The "VAR variable" input option uses the value of the specified variable as the input string. When multiple templates are provided, each template uses the current value of the variable. This value may change if the variable is included as an assignment target in any of the templates.
: The VERSION input option of the current configuration of the ARexx interpreter is supplied in the form:
: <syntaxhighlight>
ARexx VERSION CPU MPU VIDEO FREQ
</syntaxhighlight>
: where:
:* VERSION is the release level of the interpreter, formatted as 1.14.
:* CPU indicates the processor currently running the program, and will be one of the values 68000, 68010, 68020, 68030 or 68040.
:* MPU will be either NONE, 68881, or 68882, depending on whether a math coprocessor is available.
:* VIDEO will indicate either NTSC or PAL.
:* FREQ gives the clock (line) frequency as either 60Hz or 50Hz.

For example:

<syntaxhighlight>
/*Numeric string is: "9 0 SCIENTIFIC"*/
PARSE NUMERIC DIGITS FUZZ FORM .
SAY Digits /*9*/
SAY fuzz /*0*/
SAY form /*SCIENTIFIC*/
myvar = 1234567890
PARSE VAR myvar 1 a 3 b +2 c 1 d
SAY a
SAY b
SAY c
SAY d
</syntaxhighlight>

This is the output:

12
34
567890
1234567890

== PROCEDURE ==

<nowiki>PROCEDURE [EXPOSE variable [variable...]]</nowiki>

The PROCEDURE instruction is used within an internal function to create a new symbol table. This protects the symbols defined in the caller's environment from being altered by the execution of the function. PROCEDURE is usually the first statement within the function, although it is valid anywhere within the function body. It is an error to execute two PROCEDURE statements within the same function.

The EXPOSE subkeyword provides a selective mechanism for accessing the caller's symbol table, and or passing global variables to a function. The variables following the EXPOSE keyword are taken to refer to symbols in the caller's table. Any subsequent changes made to these variables will be reflected in the caller's environment.

The variables in the EXPOSE list may include stem or compound symbols, in which case the ordering of the variables becomes significant. The EXPOSE list is processed from left to right and compound symbols are expanded based on the values in effect in the new generation. For example, suppose that the value of the symbol J in the previous generation is 123, and that J is uninitialized in the new generation. Then PROCEDURE EXPOSE J A.J will expose J and A.123, whereas PROCEDURE EXPOSE A.J J will expose A.J and J. Exposing a stem has the effect of exposing all possible compound symbols derived from that stem. That is, PROCEDURE EXPOSE A. exposes A.I, A.J, A.J.J, A.123, etc. For example:

<syntaxhighlight>
fact: PROCEDURE /*A recursive function*/
ARG i
IF i = 1
THEN RETURN 1
ELSE RETURN i * fact (i-1)
</syntaxhighlight>

== PULL ==

<nowiki>PULL [template] [,template...]</nowiki>

Pull is the shorthand form of the PARSE UPPER PULL instruction. It reads a string from the input console, translates it to uppercase and parses it using the template. Multiple strings can be read by supplying additional templates. The instruction will read from the console even if no template is given. (Templates are described in Chapter 7.) For example:

<syntaxhighlight>
PULL first last . /*Read names*/
</syntaxhighlight>

== PUSH ==

<nowiki>PUSH [expression]</nowiki>

The PUSH instruction is used to prepare a stream of data to be read by a command shell or other program. It appends a newline to the result of the expression then stacks or "pushes" it into the STDIN stream. Stacked lines are placed in the stream in "last-in, first-out" order and are available to be read just as though they had been entered interactively. For example, after issuing the instructions:

<syntaxhighlight>
PUSH line 1
PUSH line 2
PUSH line 3
</syntaxhighlight>

the stream would be read in the order line 3, line 2, and line 1.

PUSH allows the STDIN stream to be used as a private scratch pad to prepare data for subsequent processing. For example, several files could be concatenated with delimiters between them by simply reading the input files, PUSHing the line into the stream and inserting a delimiter where required. For example:

<syntaxhighlight>
DO i=1 to 5
PUSH 'echo "Line 'i'"'
END
</syntaxhighlight>

== QUEUE ==

<nowiki>QUEUE [expression]</nowiki>

The QUEUE instruction is used to prepare a stream of data to be read by a command shell or other program. It is very similar to the PUSH instruction and differs only in that the data lines are placed in the STDIN stream in "first-in, first-out" order. In this case, the instructions:

<syntaxhighlight>
QUEUE line 1
QUEUE line 2
QUEUE line 3
</syntaxhighlight>

would be read in the order line 1, line 2, and line 3. The QUEUEd lines always precede all interactively-entered lines and always follow any PUSHed (stacked) lines. For example:

<syntaxhighlight>
DO i=1 to 5
QUEUE 'echo "Line 'i'"'
END
</syntaxhighlight>

== RETURN ==

<nowiki>RETURN [expression]</nowiki>

RETURN is used to leave a function and return control to the point of the function's invocation. The evaluated expression is returned as the function result. If an expression is not supplied, an error may result in the caller's environment. Functions called from within an expression must return a result string and will generate an error if no result is available. Functions invoked by the CALL instruction need to return a result.

A RETURN issued from the base environment of a program is not an error and is equivalent to an EXIT instruction. Refer to the EXIT instruction for a description of how result strings are passed back to an external caller. For example:

<syntaxhighlight>
RETURN 6*7 /*Returns 42*/
</syntaxhighlight>

== SAY ==

<nowiki>SAY [expression]</nowiki>

The result of the evaluated expressions is written to the output console, with a newline character appended. If the expression is omitted, a null string is sent to the console. For example:

<syntaxhighlight>
SAY 'The answer is ' value
</syntaxhighlight>

== SELECT ==

<nowiki>SELECT</nowiki>

SELECT begins a group of instructions containing one or more WHEN clauses and possibly a single OTHERWISE clause, each followed by a conditional statement. Only one of the conditional statements within the SELECT group will be executed. Each WHEN statement is executed in succession until one succeeds. If none succeeds, the OTHERWISE statement is executed. The SELECT range must be terminated by an END statement. For example:

<syntaxhighlight>
SELECT
WHEN i=1 THEN SAY 'one'
WHEN i=2 THEN SAY 'two'
OTHERWISE SAY 'other'
END
</syntaxhighlight>

== SHELL ==

<nowiki>SHELL [symbol | string | [[VALUE] [expression]]</nowiki>

The SHELL instruction is a synonym for the ADDRESS instruction. For example:

<syntaxhighlight>
SHELL edit /*Set host to `EDIT'*/
</syntaxhighlight>

== SIGNAL ==

<nowiki>SIGNAL {ON | OFF} condition SIGNAL [VALUE] expression</nowiki>

SIGNAL {ON | OFF} controls the state of the internal interrupt flags. Interrupts allow a program to detect and retain control when certain errors occur. In this form SIGNAL must be followed by one of the keywords ON or OFF and one of the condition keywords listed below. The interrupt flag specified by the condition symbol is then set to the indicated state. The valid signal conditions are:

{| class="wikitable"
| '''BREAK_C''' || A Ctrl+C break was detected.
|-
| '''BREAK_D''' || A Ctrl+D break was detected.
|-
| '''BREAK_E''' || A Ctrl+E break was detected.
|-
| '''BREAK_F''' || A Ctrl+F break was detected.
|-
| '''ERROR''' || A host command returned a non-zero code.
|-
| '''HALT''' || An external HALT request was detected.
|-
| '''IOERR''' || An error was detected by the I/O system.
|-
| '''NOVALUE''' || An uninitialized variable was used.
|-
| '''SYNTAX''' || A syntax or execution error was detected.
|}

The condition keywords are interpreted as labels to which control will be transferred if the selected condition occurs. For example, if the ERROR interrupt is enabled and a command returns a non-zero code, ARexx will transfer control to the label ERROR:. The condition label must be defined in the program; otherwise, an immediate SYNTAX error results and the program exits.

In SIGNAL [VALUE] expression, the tokens following SIGNAL are evaluated as an expression. An immediate interrupt is generated that transfers control to the label specified by the expression result. The instruction thus acts as a "computed goto".

Whenever an interrupt occurs, all currently active control ranges (IF, DO, SELECT, INTERPRET, or interactive TRACE) are dismantled before the transfer of control. Thus, the transfer cannot be used to jump into the range of a DO loop or other control structure. Only the control structures in the current environment are affected by a SIGNAL condition, making it safe to SIGNAL from within an internal function without affecting the state of the caller's environment.

The special variable SIGL is set to the current line number whenever a transfer of control occurs. The program can inspect SIGL to determine which line was being executed before the transfer. If an ERROR or SYNTAX condition causes an interrupt, the special variable RC is set to the error code that triggered the interrupt. For the ERROR condition, this code is usually an error severity level. Refer to Appendix A for further details on error codes and severity levels. The SYNTAX condition will always indicate an ARexx error code. For example:

<syntaxhighlight>
SIGNAL on error /*Enable interrupt*/
SIGNAL off syntax /*Disable SYNTAX*/
SIGNAL start /*Goto START*/
</syntaxhighlight>

== WHEN ==

<nowiki>WHEN expression [THEN [;] [conditional statement]]</nowiki>

The WHEN instruction is similar to the IF instruction, but is valid only within a SELECT range. Each WHEN expression is evaluated in turn and must result in a Boolean value. If the result is a 1, the conditional statement is executed and control passes to the END statement that terminates the SELECT. As with the IF instruction, the THEN need not be part of the same clause. For example:

<syntaxhighlight>
SELECT
WHEN i<j THEN SAY 'less'
WHEN i=j THEN SAY 'equal'
OTHERWISE SAY 'greater'
END
</syntaxhighlight>

AmigaOS Manual: ARexx Elements of ARexx

2014-01-25T10:14:00Z

Tony Wyatt: Fixed typos, missing text in last para.

This chapter introduces the rules and concepts that make up the ARexx programming language and explains how ARexx interprets the characters and words used in programs. The different elements that are explained include:

* Tokens - the smallest element of the ARexx language
* Clauses - the smallest executable unit, similar to a sentence
* Expressions - a group of evaluated tokens
* The Command Interface - the process by which ARexx programs communicate with ARexx-compatible applications

This chapter also includes a discussion of the ARexx execution environment. This is intended for more advanced Amiga users and includes technical details on interprocess communication.

= Tokens =

Tokens, the smallest distinct entities of the ARexx language, may be a single character or a series of characters. There are five categories of tokens:

* comments
* symbols
* strings
* operators
* special characters

== Comments ==

A comment is any group of characters beginning with the sequence /* (slash asterisk) and ending with */ (asterisk slash). Each ARexx program must begin with a comment. Each /* must have a matching */ . For example:

<syntaxhighlight>
/*This is an ARexx comment*/
</syntaxhighlight>

Comments may be placed anywhere in a program and can even be nested within one another. For example:

<syntaxhighlight>
/*A /*nested*/ comment*/
</syntaxhighlight>

Insert comments throughout your program. Comments remind you and others of the program's intentions. Because the interpreter ignores comments when it scans your programs, comments do not slow down the execution of your program.

== Symbols ==

A symbol is any group of the characters a-z, A-Z, 0-9, and period (.), exclamation point (!), question mark (?), dollar sign ($), and underscore (_). Symbols are translated to uppercase as the interpreter scans the program, so the symbol MyName is equivalent to MYNAME. The four types of recognized symbols are:

; Fixed symbols
: A series of numeric characters that begins with a digit (0-9) or a period (.). The value of a fixed symbol is always the symbol name itself, translated to uppercase. 12345 is an example of a fixed symbol.

; Simple symbols
: A series of alphabetic characters that begins with a letter A-Z. "MyName" is an example of a simple symbol.

; Stem symbols
: A series of alphanumeric characters that ends with one period. "A." and "Stem9." Are examples of stem symbols.

; Compound symbols
: A series of alphanumeric characters that includes one or more periods within the characters. "A.1.Index" is an example of a compound symbol.

Simple, stem, and compound symbols are called variables and may be assigned a value during the course of the program execution. If a variable has not yet been assigned a value, it is uninitialized. The value for an uninitialized variable is the variable name itself (translated to uppercase, if applicable).

Stems and compound symbols have special properties that make them useful for building arrays and lists. Stem symbols provide a way to initialize a whole class of compound symbols. A compound symbol can be regarded as having the structure stem.n1.n2...nk, where the leading name is a stem symbol and each node, n1...nk, is a fixed or simple symbol.

When an assignment is made to a stem symbol, it assigns that value to all possible compound symbols derived from the stem. Thus, the value of a compound symbol depends on the prior assignments made to itself or its associated stem.

Whenever a compound symbol appears in a program, its name is expanded by replacing each node with its current value. The value string may consist of any characters, including embedded blanks, and will not be converted to uppercase. The result of the expansion is a new name that is used in place of the compound symbol. For example, if J has the value 3 and K has the value 7, then the compound symbol A.J.K will expand to A.3.7.

Compound symbols can be regarded as a form of associative or content-addressable memory. For example, suppose that you needed to store and retrieve a set of names and telephone numbers. The conventional approach would be to set up two arrays, NAME and NUMBER, each indexed by an integer running from one to the number of entries. A number would be looked up by scanning the name array until the given name was found, say in NAME.12, and then retrieving NUMBER.12. With compound symbols, the symbol NAME could hold the name to be retrieved, and NUMBER.NAME would then expand to the corresponding number, for example, NUMBER.CBM.

Compound symbols can also be used as conventional indexed arrays, with the added convenience that only a single assignment (to the stem) is required to initialize the entire array.

For instance, the program below uses the stems "number." and "addr." to create a computerized telephone directory.

=== Program 8. Phone.rexx ===

<syntaxhighlight>
/*A telephone book to show compound variables.*/
IF ARG () ~ = 1 THEN DO
SAY "USAGE: rx phone name"
EXIT 5
END
/*Open window to display phone nos/addresses.*/
CALL OPEN out, "con:0/0/640/60/ARexx Phonebook"
IF ~ result THEN DO
SAY "Open failure ... sorry"
EXIT 10
END
/*Number definitions*/
number. = `(not found)'
number.wsh = `(555) 001-0001'
addr. = `(not found)'
number.CBM = `(555) 002-0002'
addr.CBM = `1200 Wilson Dr., West Chester, PA, 19380'
/*(Work is done here)*/
ARG name /*The name*/
CALLWRITELN out, name | | " `s number is" number.name
CALL WRITELN out,name | | " `s address is" addr.name
CALL WRITELN out, "Press Return to exit."
CALL READLN out
EXIT
</syntaxhighlight>

To execute the program, activate a Shell window and enter:

RX Phone cbm

A window will display the name and address assigned to CBM.

== Strings ==

A string is any group of characters beginning and ending with a quote (') or double quote (") delimiter. The same delimiter must be used at both ends of the string. To include the delimiter character in the string, use a double-delimiter sequence ('' or ""). For example:

"Now is the time." An example of a normal string.

'Can''t you see?' An example of a string using a double-delimiter sequence.

The value of a string is the string itself. The number of characters in the string is called its length. If the string does not contain any characters, it is called a null string.

Strings that are followed by an X or B character are classified as hex or binary strings, respectively, and must be composed of hexadecimal digits (0-9, A-F) or binary digits (0,1). For example:

'4A 3B C0'X
'00110111'B

Blanks are permitted at byte boundaries to improve readability. Hex and binary strings are convenient for specifying non-ASCII characters and machine-specific information, like addresses. They are converted immediately to the packed (machine-compressed) internal form.

== Operators ==

Operators are a combination of the following characters: ~ + - * / = > < & | ^, as explained in this section. There are four types of operators:

* Arithmetic operators require one or two numeric operands and produce a numeric result.
* Concatenation operators join two strings into a single string.
* Comparison operators require two operands and produce a Boolean (0 or 1) result.
* Logical operators require one or two Boolean operands and produce a Boolean result.

Each operator has an associated priority that determines the order in which operations will be performed in an expression. Operators with higher priorities (8) are performed before those with lower priorities (1).

=== Arithmetic Operators ===

An important class of operands is that representing numbers. Numbers consist of the characters 0-9, a period (.), plus sign (+), minus sign (-), and blanks. To indicate exponential notation, a number may be followed by an "e" or "E" and a (signed) integer.

Both strings and symbols may be used to specify numbers. Since the language is typeless, variables do not have to be declared as numeric before use in an arithmetic operation. Instead, each value string is examined when it is used in order to verify that it represents a number. The following examples are all valid numbers:

33
" 12.3 "
0.321e12
` + 15. `

Leading and trailing blanks are permitted. Blanks may be embedded between a plus (+) or minus (-) sign and the number, but not within the number itself.

You can modify the basic precision used for arithmetic calculations while a program is executing. The number of significant figures used in arithmetic operations is determined by the Numeric Digits setting and may be modified using the NUMERIC instruction described in Chapter 4.

The number of decimal places used for a result depends on the operation and the number of decimal places in the operands. ARexx preserves trailing zeroes to indicate the precision of the result. If the total number of digits required to express a value exceeds the current Numeric Digits setting, the number is formatted in exponential notation. They are:

* Scientific notation - the exponent is adjusted so that a single digit is placed to the left of the decimal point.
* Engineering notation - the number is scaled so that the exponent is a multiple of 3 and the digits to the left of the decimal point range from 1 to 999.

{| class="wikitable"
|+ Table 3-1. Arithmetic Operators
! Operator !! Priority !! Example !! Result
|-
| + (prefix conversion) || 8 || '3.12' || 3.12
|-
| - (prefix negation) || 8 || -"3.12" || -3.12
|-
| ** (exponentiation) || 7 || 0.5**3 || 0.125
|-
| * (multiplication) || 6 || 1.5*1.50 || 2.250
|-
| / (division) || 6 || 6 / 3 || 2
|-
| % (integer division) || 6 || -8 % 3 || -2
|-
| // (remainder) || 6 || 5.1//0.2 || 7.15
|-
| + (addition) || 5 || 3.1+4.05 || 7.15
|-
| - (subtraction) || 5 || 5.55 - 1 || 4.55
|}

=== Concatenation Operators ===

ARexx defines two concatenation operators. The first, identified by the operator sequence || (two vertical bars), joins two strings into a single string with no intervening blank. This type of concatenation can also be specified implicitly. When a symbol and a string are typed without any intervening spaces, ARexx behaves as if the || operator had been specified. The second concatenation operation is identified by the blank operator and joins the two operand strings with one intervening blank.

The priority of all concatenation operations is 4. Table 3-2 summarizes the different operations.

{| class="wikitable"
|+ Table 3-2. Concatenation Operators
! Operator !! Operation !! Example !! Result
|-
| <nowiki>||</nowiki> || Concatenation || 'why me, '<nowiki>||</nowiki>'Mom?' || why me, Mom?
|-
| Blank || Blank Concatenation || 'good<nowiki>''</nowiki>times' || good times
|-
| none || Implied Concatenation || one'two'three || ONEtwoTHREE
|}

=== Comparison Operators ===

ARexx supports three types of comparisons:

* Exact comparisons - character-by-character comparison.
* String comparisons - ignore leading blanks and add blanks to the shorter string.
* Numeric comparisons - convert the operands to an internal numeric form using the current Numeric Digits setting and then run an arithmetic comparison.

Comparisons always result in a Boolean value. The numbers 0 and 1 are used to represent the Boolean values false and true. The use of a value other than 0 or 1 when a Boolean operand is expected will generate an error. Any number equivalent to 0 or 1, for example 0.000 or 0.1E1, is also acceptable as a Boolean value.

Except for the exact equality (==) and exact inequality (~==) operators, all comparison operators dynamically determine whether a string or numeric comparison is to be performed. A numeric comparison is performed if both operands are valid numbers. Otherwise, the operands are compared as strings.

All comparisons have a priority of 3. Table 3-3 lists the acceptable comparison operators.

{| class="wikitable"
|+ Table 3-3. Comparison Operators
! Operator !! Operation !! Mode
|-
| == || Exact Equality || Exact
|-
| ~== || Exact Inequality || Exact
|-
| = || Equality || String/Numeric
|-
| ~= || Inequality || String/Numeric
|-
| > || Greater Than || String/Numeric
|-
| >= or ~< || Greater Than or Equal To || String/Numeric
|-
| < || Less Than || String/Numeric
|-
| <= or ~> || Less Than or Equal To || String/Numeric
|}

=== Logical (Boolean) Operators ===

ARexx defines the four logical operations, NOT, AND, OR, and Exclusive OR, all of which require Boolean operands and produce a Boolean result. An attempt to perform a logical operation on a non-Boolean operand will generate an error. Table 3-4 shows the acceptable logical operators.

{| class="wikitable"
|+ Table 3-4. Logical Operators
! Operator !! Priority !! Operation
|-
| ~ || 8 || NOT (Inversion)
|-
| & || 2 || AND
|-
| <nowiki>|</nowiki> || 1 || OR
|-
| ^or && || 1 || Exclusive OR
|}

== Special Characters ==

A few punctuation characters have special meanings within ARexx, as shown in Table 3-5.

{| class="wikitable"
|+ Table 3-5. Special Characters
! Special Character !! Definition
|-
| (:) Colon
| A colon defines a label when preceded by a symbol token (any alphanumeric character or . ! ? $).
|-
| ( ) Parentheses
| Parentheses are used to group operators and operands into subexpressions to override the normal operator priorities. An open parenthesis also serves to identify a function call within an expression. A Symbol or string followed immediately by an open parenthesis defines a function name. Parentheses must always be matched within a statement.
|-
| (;) Semicolon
| A semicolon acts as a statement terminator. Several statements that fit on one line may be separated by semicolons.
|-
| (,) Comma
| A comma acts as the continuation character for statements broken into several lines and as a separator of argument expressions in a function call.
|}

= Clauses =

Clauses, the smallest language unit that can be executed as a statement, are formed from token groupings.

As the program is read, the language interpreter splits the program into groups of clauses. These groups of one or more clauses are then broken down into tokens and each clause is classified as a particular type. Seemingly small syntactic differences may completely change the semantic content of a statement. For example:

<syntaxhighlight>
SAY 'Hello, Bill'
</syntaxhighlight>

is an instruction clause and will display "Hello, Bill" on the console, but:

<syntaxhighlight>
''SAY 'Hello, Bill'
</syntaxhighlight>

is a command clause, and will issue "SAY Hello, Bill" as a command to an external program. The presence of the leading null string ('') changes the classification from an instruction clause to a command clause.

The end of a line normally acts as the implicit end of a clause. A clause can be continued on the next line by ending the line with a comma. The comma is ignored by the program, and the next line is considered as a continuation of the clause. There is no limit to the number of continuations that may occur (except for those limits imposed by the command buffer).

String and comment tokens are automatically continued if a line ends before the closing delimiter has been found, and the newline (i.e., Enter) character is not considered to be part of the token.

== Null Clauses ==

Null clauses are lines of blanks or comments and may appear anywhere in a program. They have no function in the execution of a program, except to aid its readability and to increment the line count.

== Label Clauses ==

A label clause is a symbol followed by a colon (:). A label acts as a place marker in the program, but no action occurs with the execution of a label. The colon is considered as an implicit clause terminator, so each label stands as a separate clause. Label clauses may appear anywhere in a program. For example:

<syntaxhighlight>
start: /*Begin execution*/
syntax: /*Error processing*/
</syntaxhighlight>

== Assignment Clauses ==

Assignment clauses are identified by a variable symbol followed by an = operator. (In this context the = operator's normal definition of equality comparison is overridden.) The tokens to the right of the = are evaluated as an expression and the result is assigned to the variable. For example:

<syntaxhighlight>
When = 'Now is the time'
answ = 3.14 * fact(5)
</syntaxhighlight>

The equal sign (=) assigns the value 'Now is the time' to the variable 'when', and assigns the result of 3.14 * fact(5) to the variable 'answ'.

== Instruction Clauses ==

Instruction clauses begin with the name of the instruction and tell ARexx to perform an action. Instruction names are described in Chapter 4. For example:

<syntaxhighlight>
DROP a b c
SAY 'please'
IF j > 5 THEN LEAVE;
</syntaxhighlight>

== Command Clauses ==

Command clauses are any ARexx expression that cannot be classified as one of the preceding types of clauses. The expression is evaluated and the result is issued as a command to an external host. For example:

<syntaxhighlight>
'delete' 'myfile' /*AmigaDOS command*/
'jump' current+10 /*An editor command*/
</syntaxhighlight>

The delete command is not recognized as an ARexx command, so it is sent to the external host, in this case AmigaDOS. The jump command in the second example is assumed to be understood by an external text editor.

= Expressions =

Expressions are a group of evaluated tokens. Most statements contain at least one expression. Expressions are composed of:

* Strings - The value of a string is the string itself.
* Symbols - The value of a fixed symbol is the symbol itself, translated to uppercase. Symbols may be used as variables and may have an assigned value.
* Operators - An operator has a priority order that determines when it will be performed.
* Parentheses - Parentheses may be used to alter the normal order of evaluation in the expression or to identify function calls. A symbol or string followed immediately by an open parenthesis defines the function name, and the tokens between the opening and closing parenthesis form the argument list for the function. For example, the expression:

<syntaxhighlight>
J 'factorial is' fact (J)
</syntaxhighlight>

is composed of:

* a symbol - J
* a blank operator
* a string - factorial is
* another blank
* a symbol - fact
* an open parenthesis
* a symbol - J
* a closing parenthesis

In this example, FACT is a function name and (J) is its argument list, the single expression J.

Before the evaluation of an expression proceeds, ARexx must obtain a value for each symbol in the expression. For fixed symbols the value is the symbol name itself, but variable symbols must be looked up in the current symbol table. In the example above, if the symbol J was assigned the value 3, the expression after symbol resolution would be:

<syntaxhighlight>
3 'factorial is' FACT (3)
</syntaxhighlight>

To avoid ambiguities in the values assigned to symbols during the resolution process, ARexx guarantees a strict left-to-right resolution order. Symbol resolution proceeds irrespective of operator priority or parenthetical grouping. If a function call is found, the resolution is suspended while the function is evaluated. It is possible for the same symbol to have more than one value in an expression.

If the previous example was rearranged to read:

<syntaxhighlight>
FACT(J) 'is' J 'factorial'
</syntaxhighlight>

would the second occurrence of symbol J still resolve to 3? In general, function calls may have side effects that include altering the values of variables. If the example was rearranged, the value of J might have been changed by the call to FACT.

After all symbol values have been resolved, the expression is evaluated based on operator priority and subexpression grouping. ARexx does not guarantee an order of evaluation among operators of equal priority and does not employ a "fast path" evaluation of Boolean operations. For example, in the expression:

<syntaxhighlight>
(1 = 2) & (FACT(3) = 6)
</syntaxhighlight>

the call to the FACT function will be made even though the first term of the AND (&) operation is 0. This example points out that ARexx will continue reading left to right, even though the given example is false and will return a value of 0.

= 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 ===

<syntaxhighlight>
/*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
</syntaxhighlight>

== 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 ===

<syntaxhighlight>
/*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*/
</syntaxhighlight>

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 ===

<syntaxhighlight>
/*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
</syntaxhighlight>

= The Execution Environment =

{{Note|The material in this section is intended for advanced Amiga users. This information assumes a working knowledge of the Amiga operating system and a familiarity with the reference material on this wiki.}}

The ARexx interpreter, RexxMast, provides a uniform execution environment by running each program as a separate process in the Amiga's multitasking operating system. This allows for a flexible interface between an external host program and RexxMast. The host program can proceed concurrently with its operations or can wait for the interpreted ARexx program to finish. Each ARexx program has both an external and internal environment.

== The External Environment ==

The external environment includes its process structure, input and output streams, and current directory. When each ARexx process is created, it inherits the input and output streams and current directory from its client, the external program that invoked the ARexx program. For example, if an ARexx program was started from a Shell, the ARexx program will inherit the input and output stream and current directory of that Shell. The current directory is used as the starting point in any search for a program or data file. External functions are limited to a maximum of 15 arguments.

== The Internal Environment ==

The internal environment of an ARexx program consists of a static global structure and one or more storage environments. The global data values are fixed (static) at the time the program is invoked. These values include the program source code, static data strings, and argument strings. Once the program is running, these values cannot be changed.

ARexx programs invoked as commands usually have only one argument string, although the command tokenization option may provide more than one. A program invoked as an internal function can have any number of arguments. These arguments persist for the duration of the program.

The storage environment includes the symbol table used for variable values, numeric options, trace options, and host address strings. While the global environment is unique, there may be many storage environments during the course of the program execution. Each time an internal function is called, a new storage environment is activated and initialized. The initial values for most fields are inherited from the previous environment, but values may be changed afterwards without affecting the caller's environment. The new environment persists until control returns from the function.

Every storage environment includes a symbol table to store the value strings that have been assigned to variables. This symbol table is organized as a two-level binary tree. The primary level stores entries for simple and stem symbols. The secondary level is used for compound symbols. All of the compound symbols associated with a particular stem are stored in one tree, with the entry for the stem being the root of the tree.

Symbols are not entered into the table until an assignment is made to the symbol. Once created, entries at the primary level are never removed, even if the symbol subsequently becomes uninitialized. Secondary trees are released whenever a new assignment is made to the stem associated with that tree.

== Resource Tracking ==

ARexx provides complete tracking for all of the dynamically allocated resources that it uses to execute a program. These resources include memory space, DOS files and related structures, and the message port structure. The tracking system was designed to allow a program to shut down at any point without leaving any resources hanging.

It is possible to go outside of the interpreter's resource tracking net by making calls directly to the Amiga operating system from within an ARexx program. It is the programmer's responsibility to trace and return any resources allocated outside of the ARexx resource tracking system. ARexx provides a special interrupt facility so that a program can retain control after an execution error, perform the required cleanup, and exit.

AmigaOS Manual: ARexx

2014-01-25T09:14:46Z

Tony Wyatt: Fixed typos

= Welcome =

ARexx, the Amiga counterpart of the IBM REXX programming language, provides the freedom to customize your work environment. It is especially useful as a scripting language which allows you to control and modify applications and to direct how they interact with each other.

This manual introduces you to ARexx, tells you how to create ARexx programs and provides a reference section of ARexx commands.

[[AmigaOS Manual: ARexx Introducing ARexx|Chapter 1. Introducing ARexx]] This chapter gives an overview of ARexx, how it works on the Amiga, and the basic features of the programming language.

[[AmigaOS Manual: ARexx Getting Started|Chapter 2. Getting Started]] This chapter tells you where to store your ARexx programs, how to execute an ARexx program, and provides several programming examples.

[[AmigaOS Manual: ARexx Elements of ARexx|Chapter 3. Elements of ARexx]] This chapter details the rules and concepts that make up the ARexx programming language.

[[AmigaOS Manual: ARexx Instructions|Chapter 4. Instructions]] This chapter contains an alphabetical listing of ARexx instructions, which are language statements that dictate an action.

[[AmigaOS Manual: ARexx Functions|Chapter 5. Functions]] This chapter describes the use of functions, which are program statements used by ARexx, and provides an alphabetical listing of the built-in ARexx functions.

[[AmigaOS Manual: ARexx Debugging|Chapter 6. Debugging]] This chapter focuses on the source-level debugging features used in the development and testing of programs.

[[AmigaOS Manual: ARexx Parsing|Chapter 7. Parsing]] This chapter explains how to extract patterns of information from strings.

[[AmigaOS Manual: Workbench ARexx Port|Chapter 8. WB-ARexx-Port]] This chapter explains how to use the Workbench ARexx port.

[[AmigaOS Manual: ARexx Error Messages|Appendix A. Error Messages]] This appendix lists the ARexx error messages.

[[AmigaOS Manual: ARexx Command Utilities|Appendix B. Command Utilities]] This appendix lists the ARexx commands that can be run from the Shell.

[[AmigaOS Manual: ARexx Glossary|Glossary]] The glossary contains common ARexx terms.

= Document Conventions =

The following conventions are used in this manual:

; KEYWORDS
: Keywords are displayed in all uppercase letters, however, the arguments are case-insensitive.

; | (vertical bar)
: Alternative selections are separated by a vertical bar.

; { } (braces)
: Required alternatives are enclosed by braces.

; [ ] (brackets)
: Optional instruction parts are enclosed in brackets.

; <n>
: Variables are displayed in angle brackets. Do not enter the angle brackets when entering the variable.

; Courier
: Text appearing in the Courier font represents output from your ARexx programs or other information that displays on your screen.

; Key1 + Key2
: Key combinations displayed with a plus sign (+) connecting them indicates pressing the keys simultaneously.

; Key1, Key2
: Key combinations displayed with a comma sign (,) separating them indicates pressing the keys in sequence.

; Amiga keys
: Two keys on the Amiga keyboard used for special functions. The left Amiga key is to the left of the space bar and is marked with a large solid A. The right Amiga key is to the right of the space bar and is an outlined A.

= Sources of Additional Information =

Further information on learning and using ARexx can be found in:

Modern Programming Using REXX , by R.P. O'Hara and D.G. Gomberg, Prentice-Hall, 1985

The REXX Language: A Practical Approach to Programming , by M.F. Cowlishaw, Prentice-Hall, 1985.

Programming in REXX , J. Ranade IBM Series, by Charles Daney.

Using ARexx on the Amiga , by Chris Zamara and Nick Sullivan, Abacus, 1991.

[[Libraries|Libraries]]

AmigaOS Manual: ARexx Getting Started

2014-01-25T09:08:12Z

Tony Wyatt:

This chapter shows you how to:

* Start ARexx
* Save Programs
* Store Programs
* Use sample programs

= Starting ARexx =

To start using ARexx, you activate the RexxMast program. The RexxMast program can be started automatically or manually. Each time ARexx is started or stopped, a text message appears.

== To Start ARexx Automatically ==

There are two methods to start ARexx automatically: add RexxMast to the WBStartup Prefs window or edit the S:User-Startup file.

To place RexxMast in the WBStartup Prefs list:

# Open the Prefs drawer.
# Open the WBStartup prefs.
# Click the "Add" button.
# Select SYS:System/RexxMast in the requester that pops up
# Click on "Save"
# Reboot your Amiga.

The command to start RexxMast should already be in the S:Startup-Sequence file. If the command has been removed from S:Startup-Sequence, we suggest that you add it to the S:User-Startup file.
To edit the S:User-Startup file:

# Open a text editor like Notepad.
# Open the S:User-Startup file.
# Enter ''SYS:System/RexxMast >NIL:''
# Save the file.
# Reboot your Amiga.

== To Start ARexx Manually ==

There are two ways to start RexxMast manually: double-click on the RexxMast icon in Workbench or start it from the Shell.

To start RexxMast from Workbench:

# Open the System Drawer.
# Double-click on the RexxMast icon.

To start RexxMast from the Shell:

# Open a Shell.
# Type ''RexxMast >NIL:'' and press Enter.

= About ARexx Programs =

ARexx programs are usually stored in the REXX: directory (which is generally assigned to the SYS:S/ARexx directory). Although programs can be stored in any directory, storing them in REXX: has several advantages:

* You can run the program without having to type the complete path.
* All of your ARexx programs will be in the same place.
* Most applications search for ARexx programs in REXX:.

Just as you can store an ARexx program anywhere, you can also name it anything you choose. However, adopting a simple naming convention will make program management much easier. Programs run from the Shell should have a .rexx extension to distinguish them from files run from other applications.

== Running ARexx Programs ==

The Rx command is used to run an ARexx program. If a complete path is included with the program name, only that directory is searched for the program. If no path is included, the current directory and ''REXX:'' are checked. The "Rx" may be in any case, for example, "RX", "rx" and "Rx" will all work the same.

As long as your program is stored in the ''REXX:'' directory, you do not need to include the .rexx extension when specifying your program name. In other words, typing:

Rx Program.rexx

is the same as:

Rx Program

A short program can be entered directly at the command line by enclosing the program line in double-quotes. For example, the following program will send five files named myfile.1 through myfile.5 to the printer.

Rx "DO i=1 to 5;
ADDRESS command `copy myfile.' | | i `prt:'; END"

When an application is ARexx-compatible, you can run ARexx programs from within the application by choosing a menu item or by specifying command options. Refer to the application's documentation for more information.

ARexx programs can be run from the Workbench by creating a tool or project icon for the program. You must specify the Rx command as the Default Tool for the icon. In the icon's Information window, enter:

Default Tool: SYS:C/Rx

When the icon is opened, Rx starts RexxMast (if it is not already running). It executes the file associated with the icon as an ARexx program.

ARexx accepts two Tool Types: Console, to specify a window, and CMD, to specify a command string. You enter these Tool Types in the project icon's Information window as:

Console=CON:0/0/640/200/Example/Close
CMD=rexxprogram

= Program Examples =

The following examples illustrate how to use ARexx to display text strings on your screen, to perform calculations, and to activate the error checking feature.

Programs can be entered into any text editor, such as Notepad or a word processor. Save your program as an ASCII file if you use a word processor. ARexx supports the extended ASCII character set (Å, Æ, ß). These extended characters are recognized as ordinary printing characters and will be mapped from lowercase to uppercase.

The examples also illustrate the use of some basic ARexx syntax requirements such as:

* Comment lines
* Spacing rules
* Case-sensitivity
* Use of single and double quotes

Each ARexx program consists of a comment line that describes the program and an instruction that displays text on the console. ARexx programs must always begin with a comment line. The initial (slash asterisk) /* matched with an ending (asterisk slash) */ tells the RexxMast interpreter that it has found an ARexx program. Without the /* and the */, RexxMast will not view the file as an ARexx program. Once it begins executing the program, ARexx ignores any additional comment lines within the file. However, comment lines are extremely useful when reading the program. They can help organize and make sense of a program.

== Amiga.rexx ==

This program shows how to use SAY in a set of instructions to display text strings on the screen. Instructions are language statements that denote a certain action to be performed. Each statement always begins with a symbol. In the following example, the symbol is SAY. (Symbols are always translated to uppercase letters when the program is run.) Following SAY is an example of a string. A string is a series of characters surrounded by single quotes (`) or double quotes (").

=== Program 1. Amiga.rexx ===

<syntaxhighlight>
/*A simple program*/
SAY `Amiga. The Computer For the Creative Mind.'
</syntaxhighlight>

Enter the above program, and save it as REXX:Amiga.rexx . To run the program, open a Shell window and type:

Rx Amiga

Although the full path and program name is ''Rexx:Amiga.rexx'', you do not need to type the REXX: directory name or the .rexx extension if the program has been saved in the REXX: directory.

You should see the following text in your Shell window:

Amiga. The Computer for the Creative Mind.

== Age.rexx ==

This program displays a prompt for input and then reads entered information.

=== Program 2. Age.rexx ===

<syntaxhighlight>
/*Calculate age in days*/
SAY `Please enter your age:'
PULL age
SAY `You are about' age*365 `days old.'
</syntaxhighlight>

Save this program as ''REXX:Age.rexx'' and run it with the command:

Rx age

This program begins with a comment line that describes what the program will do. All ARexx programs begin with a comment. The SAY instruction displays a request for input on the console.

The PULL instruction reads a line of input from the user, which in this case is the user's age. PULL takes the input, converts it to uppercase letters, and stores it in a variable. Variables are symbols which may be assigned a value. Choose descriptive variable names! This example uses the variable name "age" to hold the entered number.

The final line multiplies the variable "age" by 365 and issues the SAY instruction to display the result. The "age" variable did not have to be declared as a number because its value was checked when it was used in the expression. This is an example of typeless data. To see what would happen if age was not a number, try running the program again with a non-numeric entry for the age. The resulting error message shows the line number and type of error that occurred.

== Calc.rexx ==

This program introduces the DO instruction, which repeats the execution of program statements. It also illustrates the exponentiation operator ( ** ). Enter this program and save it as ''REXX:Calc.rexx''. To run the program, use the "Rx calc" command.

=== Program 3. Calc.rexx ===

<syntaxhighlight>
/*Calculate some squares and cubes.*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
SAY i i**2 i**3 /*Perform calculations*/
END /*End of loop*/
SAY `All done.'
</syntaxhighlight>

The DO instruction repeatedly executes the statements between the DO and END instructions. The variable "i" is the index variable for the loop and is incremented by 1 for each iteration (repetition). The number following the symbol TO is the limit for the DO instruction and could have been a variable or a full expression rather than just the constant 10.

Generally, ARexx programs use single spacing between alphanumeric characters. In Program 3, however, spacing is closed up between the exponentiation characters ( ** ) and the variables ( i and 2, i and 3).

The statements within the loop have been indented. This is not required by the language, but it makes the program more readable, because you can easily visualize where the loop starts and stops.

== Even.rexx ==

The IF instruction allows statements to be conditionally executed. In this example, the numbers from 1 to 10 are classified as odd or even by dividing them by 2 and then checking the remainder. The // arithmetic operator calculates the remainder after a division operation.

=== Program 4. Even.rexx ===

<syntaxhighlight>
/*Even or odd?*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
IF 1 // 2 = 0 THEN type = `even'
ELSE type = `odd'
SAY i `is' type
END /*End loop*/
</syntaxhighlight>

The IF line states that if the remainder of the division of the variable "i" by 2 equals 0, then set the variable "type" to even. If the remainder is not 0, the program will skip over the THEN branch and execute the ELSE branch, setting variable "type" to odd.

== Square.rexx ==

This example introduces the concept of a function, a group of statements executed by mentioning the function name in a suitable context. Functions allow you to build large complex programs from smaller modules. Functions also permit the same code for similar operations in a different program.

Functions are specified in an expression as a name followed by an open parenthesis. (There is no space between the name and the parenthesis.) One or more expressions, called arguments, may follow the parenthesis. The last argument must be followed by a closing parenthesis. These arguments pass information to the function for processing.

=== Program 5. Square.rexx ===

<syntaxhighlight>
/*Defining and calling a function.*/

DO i = 1 to 5
SAY i square(i) /*Call the "square" function*/
END
EXIT
square: /*Function name*/
ARG x /*Get the argument*/
RETURN x**2 /*Square it and return*/
</syntaxhighlight>

Starting with DO and ending with END , a loop is set up with an index variable "i", that will increment by 1. The loop will iterate (repeat) five times. The loop contains an expression that calls the function "square" when the expression is evaluated. The function's result is displayed using the SAY instruction.

The function "square", defined by the ARG and RETURN instructions, calculates the squared values. ARG retrieves the value of the argument string "i" and RETURN passes the function's result back to the SAY instruction.

Once the function is called by the loop, the program looks for the function name "square", retrieves the argument "i", performs a calculation, and returns to the line within the DO/END loop. The EXIT instruction ends the program after the final loop.

== Results.rexx ==

The TRACE instruction activates ARexx's error checking feature.

=== Program 6. Results.rexx ===

<syntaxhighlight>
/*Demonstrate "results" tracing*/
TRACE results
sum = 0 ; sumsq = 0;
DO i = 1 to 5
sum = sum + 1
sumsq = sumsq + i**2
END
SAY `sum=' sum `sumsq=' sumsq
</syntaxhighlight>

The console displays the executed source lines, each pass through the DO/END loop, and the expression's final results. Removing the TRACE instruction, would display only the final result: sum = 15 sumsq = 55 .

== Grades.rexx ==

This program calculates the final grade for a given student based on four essay grades and a class participation grade. The average of Essay 1 and Essay 2 is worth 30%, the average of Essay 3 and Essay 4 is worth 45%, and participation is worth 25% of the final grade.

Once a final grade is displayed, an option to continue with another calculation is presented. The response is "PULLed" and if it does not equal "Q" (quit), the loop continues. If the response equals "Q" , the program quits the loop and exits.

=== Program 7. Grades.rexx ===

<syntaxhighlight>
/*Grading program*/
SAY "Hallo, I will calculate your grades for you."
Response = 0
DO while response ~ = "Q" /*Loop while response isn't Q*/
SAY "Please enter all grades for the student."
SAY "Essay 1:"
PULL es1
SAY "Essay 2:"
PULL es2
SAY "Essay 3:"
PULL es3
SAY "Essay 4:"
PULL es4
SAY "Participation:"
PULL p
Final = (((es1 + es2)/2*.3) + ((es3 + es4)/2*.45) + (p*.25))
SAY "Your final grade for this student is " Final
SAY "Would you like to continue? (Q for quit.)"
PULL response
END
EXIT
</syntaxhighlight>

AmigaOS Manual: ARexx Getting Started

2014-01-25T09:07:06Z

Tony Wyatt:

This chapter shows you how to:

* Start ARexx
* Save Programs
* Store Programs
* Use sample programs

= Starting ARexx =

To start using ARexx, you activate the RexxMast program. The RexxMast program can be started automatically or manually. Each time ARexx is started or stopped, a text message appears.

== To Start ARexx Automatically ==

There are two methods to start ARexx automatically: add RexxMast to the WBStartup Prefs window or edit the S:User-Startup file.

To place RexxMast in the WBStartup Prefs list:

# Open the Prefs drawer.
# Open the WBStartup prefs.
# Click the "Add" button.
# Select SYS:System/RexxMast in the requester that pops up
# Click on "Save"
# Reboot your Amiga.

The command to start RexxMast should already be in the S:Startup-Sequence file. If the command has been removed from S:Startup-Sequence, we suggest that you add it to the S:User-Startup file.
To edit the S:User-Startup file:

# Open a text editor like Notepad.
# Open the S:User-Startup file.
# Enter ''SYS:System/RexxMast >NIL:''
# Save the file.
# Reboot your Amiga.

== To Start ARexx Manually ==

There are two ways to start RexxMast manually: double-click on the RexxMast icon in Workbench or start it from the Shell.

To start RexxMast from Workbench:

# Open the System Drawer.
# Double-click on the RexxMast icon.

To start RexxMast from the Shell:

# Open a Shell.
# Type ''RexxMast >NIL:'' and press Enter.

= About ARexx Programs =

ARexx programs are usually stored in the REXX: directory (which is generally assigned to the SYS:S/ARexx directory). Although programs can be stored in any directory, storing them in REXX: has several advantages:

* You can run the program without having to type the complete path.
* All of your ARexx programs will be in the same place.
* Most applications search for ARexx programs in REXX:.

Just as you can store an ARexx program anywhere, you can also name it anything you choose. However, adopting a simple naming convention will make program management much easier. Programs run from the Shell should have a .rexx extension to distinguish them from files run from other applications.

== Running ARexx Programs ==

The Rx command is used to run an ARexx program. If a complete path is included with the program name, only that directory is searched for the program. If no path is included, the current directory and ''REXX:'' are checked. The "Rx" may be in any case, for example, "RX", "rx" and "Rx" will all work the same.

As long as your program is stored in the ''REXX:'' directory, you do not need to include the .rexx extension when specifying your program name. In other words, typing:

Rx Program.rexx

is the same as:

Rx Program

A short program can be entered directly at the command line by enclosing the program line in double-quotes. For example, the following program will send five files named myfile.1 through myfile.5 to the printer.

Rx "DO i=1 to 5;
ADDRESS command `copy myfile.' | | i `prt:'; END"

When an application is ARexx-compatible, you can run ARexx programs from within the application by choosing a menu item or by specifying command options. Refer to the application's documentation for more information.

ARexx programs can be run from the Workbench by creating a tool or project icon for the program. You must specify the Rx command as the Default Tool for the icon. In the icon's Information window, enter:

Default Tool: SYS:C/Rx

When the icon is opened, Rx starts RexxMast (if it is not already running). It executes the file associated with the icon as an ARexx program.

ARexx accepts two Tool Types: Console, to specify a window, and CMD, to specify a command string. You enter these Tool Types in the project icon's Information window as:

Console=CON:0/0/640/200/Example/Close
CMD=rexxprogram

= Program Examples =

The following examples illustrate how to use ARexx to display text strings on your screen, to perform calculations, and to activate the error checking feature.

Programs can be entered into any text editor, such as Notepad or a word processor. Save your program as an ASCII file if you use a word processor. ARexx supports the extended ASCII character set (Å, Æ, ß). These extended characters are recognized as ordinary printing characters and will be mapped from lowercase to uppercase.

The examples also illustrate the use of some basic ARexx syntax requirements such as:

* Comment lines
* Spacing rules
* Case-sensitivity
* Use of single and double quotes

Each ARexx program consists of a comment line that describes the program and an instruction that displays text on the console. ARexx programs must always begin with a comment line. The initial (slash asterisk) /* matched with an ending (asterisk slash) */ tells the RexxMast interpreter that it has found an ARexx program. Without the /* and the */, RexxMast will not view the file as an ARexx program. Once it begins executing the program, ARexx ignores any additional comment lines within the file. However, comment lines are extremely useful when reading the program. They can help organize and make sense of a program.

== Amiga.rexx ==

This program shows how to use SAY in a set of instructions to display text strings on the screen. Instructions are language statements that denote a certain action to be performed. Each statement always begins with a symbol. In the following example, the symbol is SAY. (Symbols are always translated to uppercase letters when the program is run.) Following SAY is an example of a string. A string is a series of characters surrounded by single quotes (`) or double quotes (").

=== Program 1. Amiga.rexx ===

<syntaxhighlight>
/*A simple program*/
SAY `Amiga. The Computer For the Creative Mind.'
</syntaxhighlight>

Enter the above program, and save it as REXX:Amiga.rexx . To run the program, open a Shell window and type:

Rx Amiga

Although the full path and program name is ''Rexx:Amiga.rexx'', you do not need to type the REXX: directory name or the .rexx extension if the program has been saved in the REXX: directory.

You should see the following text in your Shell window:

Amiga. The Computer for the Creative Mind.

== Age.rexx ==

This program displays a prompt for input and then reads entered information.

=== Program 2. Age.rexx ===

<syntaxhighlight>
/*Calculate age in days*/
SAY `Please enter your age:'
PULL age
SAY `You are about' age*365 `days old.'
</syntaxhighlight>

Save this program as ''REXX:Age.rexx'' and run it with the command:

Rx age

This program begins with a comment line that describes what the program will do. All ARexx programs begin with a comment. The SAY instruction displays a request for input on the console.

The PULL instruction reads a line of input from the user, which in this case is the user's age. PULL takes the input, converts it to uppercase letters, and stores it in a variable. Variables are symbols which may be assigned a value. Choose descriptive variable names! This example uses the variable name "age" to hold the entered number.

The final line multiplies the variable "age" by 365 and issues the SAY instruction to display the result. The "age" variable did not have to be declared as a number because its value was checked when it was used in the expression. This is an example of typeless data. To see what would happen if age was not a number, try running the program again with a non-numeric entry for the age. The resulting error message shows the line number and type of error that occurred.

== Calc.rexx ==

This program introduces the DO instruction, which repeats the execution of program statements. It also illustrates the exponentiation operator ( ** ). Enter this program and save it as ''REXX:Calc.rexx''. To run the program, use the "Rx calc" command.

=== Program 3. Calc.rexx ===

<syntaxhighlight>
/*Calculate some squares and cubes.*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
SAY i i**2 i**3 /*Perform calculations*/
END /*End of loop*/
SAY `All done.'
</syntaxhighlight>

The DO instruction repeatedly executes the statements between the DO and END instructions. The variable "i" is the index variable for the loop and is incremented by 1 for each iteration (repetition). The number following the symbol TO is the limit for the DO instruction and could have been a variable or a full expression rather than just the constant 10.

Generally, ARexx programs use single spacing between alphanumeric characters. In Program 3, however, spacing is closed up between the exponentiation characters ( ** ) and the variables ( i and 2, i and 3).

The statements within the loop have been indented. This is not required by the language, but it makes the program more readable, because you can easily visualize where the loop starts and stops.

== Even.rexx ==

The IF instruction allows statements to be conditionally executed. In this example, the numbers from 1 to 10 are classified as odd or even by dividing them by 2 and then checking the remainder. The // arithmetic operator calculates the remainder after a division operation.

=== Program 4. Even.rexx ===

<syntaxhighlight>
/*Even or odd?*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
IF 1 // 2 = 0 THEN type = `even'
ELSE type = `odd'
SAY i `is' type
END /*End loop*/
</syntaxhighlight>

The IF line states that if the remainder of the division of the variable "i" by 2 equals 0, then set the variable "type" to even. If the remainder is not 0, the program will skip over the THEN branch and execute the ELSE branch, setting variable "type" to odd.

== Square.rexx ==

This example introduces the concept of a function, a group of statements executed by mentioning the function name in a suitable context. Functions allow you to build large complex programs from smaller modules. Functions also permit the same code for similar operations in a different program.

Functions are specified in an expression as a name followed by an open parenthesis. (There is no space between the name and the parenthesis.) One or more expressions, called arguments, may follow the parenthesis. The last argument must be followed by a closing parenthesis. These arguments pass information to the function for processing.

=== Program 5. Square.rexx ===

<syntaxhighlight>
/*Defining and calling a function.*/

DO i = 1 to 5
SAY i square(i) /*Call the "square" function*/
END
EXIT
square: /*Function name*/
ARG x /*Get the argument*/
RETURN x**2 /*Square it and return*/
</syntaxhighlight>

Starting with DO and ending with END , a loop is set up with an index variable "i", that will increment by 1. The loop will iterate (repeat) five times. The loop contains an expression that calls the function "square" when the expression is evaluated. The function's result is displayed using the SAY instruction.

The function "square", defined by the ARG and RETURN instructions, calculates the squared values. ARG retrieves the value of the argument string "i" and RETURN passes the function's result back to the SAY instruction.

Once the function is called by the loop, the program looks for the function name "square", retrieves the argument "i", performs a calculation, and returns to the line within the DO/END loop. The EXIT instruction ends the program after the final loop.

== Results.rexx ==

The TRACE instruction activates ARexx's error checking feature.

=== Program 6. Results.rexx ===

<syntaxhighlight>
/*Demonstrate "results" tracing*/
TRACE results
sum = 0 ; sumsq = 0;
DO i = 1 to 5
sum = sum + 1
sumsq = sumsq + i**2
END
SAY `sum=' sum `sumsq=' sumsq
</syntaxhighlight>

The console displays the executed source lines, each pass through the DO/END loop, and the expression's final results. Removing the TRACE instruction, would display only the final result: sum = 15 sumsq = 55 .

== Grades.rexx ==

This program calculates the final grade for a given student based on four essay grades and a class participation grade. The average of Essay 1 and Essay 2 is worth 30%, the average of Essay 3 and Essay 4 is worth 45%, and participation is worth 25% of the final grade.

Once a final grade is displayed, an option to continue with another calculation is presented. The response is "PULLed" and if it does not equal "Q" (quit), the loop continues. If the response equals "Q" , the program quits the loop and exits.

=== Program 7. Grades.rexx ===

<syntaxhighlight>
/*Grading program*/
SAY "Hallo, I will calculate your grades for you."
Response = 0
DO while response ~ = "Q "/*Loop while response isn't Q*/
SAY "Please enter all grades for the student."
SAY "Essay 1:"
PULL es1
SAY "Essay 2:"
PULL es2
SAY "Essay 3:"
PULL es3
SAY "Essay 4:"
PULL es4
SAY "Participation:"
PULL p
Final = (((es1 + es2)/2*.3) + ((es3 + es4)/2*.45) + (p*.25))
SAY "Your final grade for this student is " Final
SAY "Would you like to continue? (Q for quit.)"
PULL response
END
EXIT
</syntaxhighlight>

AmigaOS Manual: ARexx Getting Started

2014-01-25T09:06:02Z

Tony Wyatt: Fixed typos

This chapter shows you how to:

* Start ARexx
* Save Programs
* Store Programs
* Use sample programs

= Starting ARexx =

To start using ARexx, you activate the RexxMast program. The RexxMast program can be started automatically or manually. Each time ARexx is started or stopped, a text message appears.

== To Start ARexx Automatically ==

There are two methods to start ARexx automatically: add RexxMast to the WBStartup Prefs window or edit the S:User-Startup file.

To place RexxMast in the WBStartup Prefs list:

# Open the Prefs drawer.
# Open the WBStartup prefs.
# Click the "Add" button.
# Select SYS:System/RexxMast in the requester that pops up
# Click on "Save"
# Reboot your Amiga.

The command to start RexxMast should already be in the S:Startup-Sequence file. If the command has been removed from S:Startup-Sequence, we suggest that you add it to the S:User-Startup file.
To edit the S:User-Startup file:

# Open a text editor like Notepad.
# Open the S:User-Startup file.
# Enter ''SYS:System/RexxMast >NIL:''
# Save the file.
# Reboot your Amiga.

== To Start ARexx Manually ==

There are two ways to start RexxMast manually: double-click on the RexxMast icon in Workbench or start it from the Shell.

To start RexxMast from Workbench:

# Open the System Drawer.
# Double-click on the RexxMast icon.

To start RexxMast from the Shell:

# Open a Shell.
# Type ''RexxMast >NIL:'' and press Enter.

= About ARexx Programs =

ARexx programs are usually stored in the REXX: directory (which is generally assigned to the SYS:S/ARexx directory). Although programs can be stored in any directory, storing them in REXX: has several advantages:

* You can run the program without having to type the complete path.
* All of your ARexx programs will be in the same place.
* Most applications search for ARexx programs in REXX:.

Just as you can store an ARexx program anywhere, you can also name it anything you choose. However, adopting a simple naming convention will make program management much easier. Programs run from the Shell should have a .rexx extension to distinguish them from files run from other applications.

== Running ARexx Programs ==

The Rx command is used to run an ARexx program. If a complete path is included with the program name, only that directory is searched for the program. If no path is included, the current directory and ''REXX:'' are checked. The "Rx" may be in any case, for example, "RX", "rx" and "Rx" will all work the same.

As long as your program is stored in the ''REXX:'' directory, you do not need to include the .rexx extension when specifying your program name. In other words, typing:

Rx Program.rexx

is the same as:

Rx Program

A short program can be entered directly at the command line by enclosing the program line in double-quotes. For example, the following program will send five files named myfile.1 through myfile.5 to the printer.

Rx "DO i=1 to 5;
ADDRESS command `copy myfile.' | | i `prt:'; END"

When an application is ARexx-compatible, you can run ARexx programs from within the application by choosing a menu item or by specifying command options. Refer to the application's documentation for more information.

ARexx programs can be run from the Workbench by creating a tool or project icon for the program. You must specify the Rx command as the Default Tool for the icon. In the icon's Information window, enter:

Default Tool: SYS:C/Rx

When the icon is opened, Rx starts RexxMast (if it is not already running). It executes the file associated with the icon as an ARexx program.

ARexx accepts two Tool Types: Console, to specify a window, and CMD, to specify a command string. You enter these Tool Types in the project icon's Information window as:

Console=CON:0/0/640/200/Example/Close
CMD=rexxprogram

= Program Examples =

The following examples illustrate how to use ARexx to display text strings on your screen, to perform calculations, and to activate the error checking feature.

Programs can be entered into any text editor, such as Notepad or a word processor. Save your program as an ASCII file if you use a word processor. ARexx supports the extended ASCII character set (Å, Æ, ß). These extended characters are recognized as ordinary printing characters and will be mapped from lowercase to uppercase.

The examples also illustrate the use of some basic ARexx syntax requirements such as:

* Comment lines
* Spacing rules
* Case-sensitivity
* Use of single and double quotes

Each ARexx program consists of a comment line that describes the program and an instruction that displays text on the console. ARexx programs must always begin with a comment line. The initial (slash asterisk) /* matched with an ending (asterisk slash) */ tells the RexxMast interpreter that it has found an ARexx program. Without the /* and the */, RexxMast will not view the file as an ARexx program. Once it begins executing the program, ARexx ignores any additional comment lines within the file. However, comment lines are extremely useful when reading the program. They can help organize and make sense of a program.

== Amiga.rexx ==

This program shows how to use SAY in a set of instructions to display text strings on the screen. Instructions are language statements that denote a certain action to be performed. Each statement always begins with a symbol. In the following example, the symbol is SAY. (Symbols are always translated to uppercase letters when the program is run.) Following SAY is an example of a string. A string is a series of characters surrounded by single quotes (`) or double quotes (").

=== Program 1. Amiga.rexx ===

<syntaxhighlight>
/*A simple program*/
SAY `Amiga. The Computer For the Creative Mind.'
</syntaxhighlight>

Enter the above program, and save it as REXX:Amiga.rexx . To run the program, open a Shell window and type:

Rx Amiga

Although the full path and program name is ''Rexx:Amiga.rexx'', you do not need to type the REXX: directory name or the .rexx extension if the program has been saved in the REXX: directory.

You should see the following text in your Shell window:

Amiga. The Computer for the Creative Mind.

== Age.rexx ==

This program displays a prompt for input and then reads entered information.

=== Program 2. Age.rexx ===

<syntaxhighlight>
/*Calculate age in days*/
SAY `Please enter your age:'
PULL age
SAY `You are about' age*365 `days old.'
</syntaxhighlight>

Save this program as ''REXX:Age.rexx'' and run it with the command:

Rx age

This program begins with a comment line that describes what the program will do. All ARexx programs begin with a comment. The SAY instruction displays a request for input on the console.

The PULL instruction reads a line of input from the user, which in this case is the user's age. PULL takes the input, converts it to uppercase letters, and stores it in a variable. Variables are symbols which may be assigned a value. Choose descriptive variable names! This example uses the variable name "age" to hold the entered number.

The final line multiplies the variable "age" by 365 and issues the SAY instruction to display the result. The "age" variable did not have to be declared as a number because its value was checked when it was used in the expression. This is an example of typeless data. To see what would happen if age was not a number, try running the program again with a non-numeric entry for the age. The resulting error message shows the line number and type of error that occurred.

== Calc.rexx ==

This program introduces the DO instruction, which repeats the execution of program statements. It also illustrates the exponentiation operator ( ** ). Enter this program and save it as ''REXX:Calc.rexx''. To run the program, use the "Rx calc" command.

=== Program 3. Calc.rexx ===

<syntaxhighlight>
/*Calculate some squares and cubes.*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
SAY i i**2 i**3 /*Perform calculations*/
END /*End of loop*/
SAY `All done.'
</syntaxhighlight>

The DO instruction repeatedly executes the statements between the DO and END instructions. The variable "i" is the index variable for the loop and is incremented by 1 for each iteration (repetition). The number following the symbol TO is the limit for the DO instruction and could have been a variable or a full expression rather than just the constant 10.

Generally, ARexx programs use single spacing between alphanumeric characters. In Program 3, however, spacing is closed up between the exponentiation characters ( ** ) and the variables ( i and 2, i and 3).

The statements within the loop have been indented. This is not required by the language, but it makes the program more readable, because you can easily visualize where the loop starts and stops.

== Even.rexx ==

The IF instruction allows statements to be conditionally executed. In this example, the numbers from 1 to 10 are classified as odd or even by dividing them by 2 and then checking the remainder. The // arithmetic operator calculates the remainder after a division operation.

=== Program 4. Even.rexx ===

<syntaxhighlight>
/*Even or odd?*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
IF 1 // 2 = 0 THEN type = `even'
ELSE type = `odd'
SAY i `is' type
END /*End loop*/
</syntaxhighlight>

The IF line states that if the remainder of the division of the variable "i" by 2 equals 0, then set the variable "type" to even. If the remainder is not 0, the program will skip over the THEN branch and execute the ELSE branch, setting variable "type" to odd.

== Square.rexx ==

This example introduces the concept of a function, a group of statements executed by mentioning the function name in a suitable context. Functions allow you to build large complex programs from smaller modules. Functions also permit the same code for similar operations in a different program.

Functions are specified in an expression as a name followed by an open parenthesis. (There is no space between the name and the parenthesis.) One or more expressions, called arguments, may follow the parenthesis. The last argument must be followed by a closing parenthesis. These arguments pass information to the function for processing.

=== Program 5. Square.rexx ===

<syntaxhighlight>
/*Defining and calling a function.*/

DO i = 1 to 5
SAY i square(i) /*Call the "square" function*/
END
EXIT
square: /*Function name*/
ARG x /*Get the argument*/
RETURN x**2 /*Square it and return*/
</syntaxhighlight>

Starting with DO and ending with END , a loop is set up with an index variable "i", that will increment by 1. The loop will iterate (repeat) five times. The loop contains an expression that calls the function "square" when the expression is evaluated. The function's result is displayed using the SAY instruction.

The function "square", defined by the ARG and RETURN instructions, calculates the squared values. ARG retrieves the value of the argument string "i" and RETURN passes the function's result back to the SAY instruction.

Once the function is called by the loop, the program looks for the function name "square", retrieves the argument "i", performs a calculation, and returns to the line within the DO/END loop. The EXIT instruction ends the program after the final loop.

== Results.rexx ==

The TRACE instruction activates ARexx's error checking feature.

=== Program 6. Results.rexx ===

<syntaxhighlight>
/*Demonstrate "results" tracing*/
TRACE results
sum = 0 ; sumsq = 0;
DO i = 1 to 5
sum = sum + 1
sumsq = sumsq + i**2
END
SAY `sum=' sum `sumsq=' sumsq
</syntaxhighlight>

The console displays the executed source lines, each pass through the DO/END loop, and the expression's final results. Removing the TRACE instruction, would display only the final result: sum = 15 sumsq = 55 .

== Grades.rexx ==

This program calculates the final grade for a given student based on four essay grades and a class participation grade. The average of Essay 1 and Essay 2 is worth 30%, the average of Essay 3 and Essay 4 is worth 45%, and participation is worth 25% of the final grade.

Once a final grade is displayed, an option to continue with another calculation is presented. The response is "PULLed" and if it does not equal Q (quit), the loop continues. If the response equals "Q" , the program quits the loop and exits.

=== Program 7. Grades.rexx ===

<syntaxhighlight>
/*Grading program*/
SAY "Hallo, I will calculate your grades for you."
Response = 0
DO while response ~ = "Q "/*Loop while response isn't Q*/
SAY "Please enter all grades for the student."
SAY "Essay 1:"
PULL es1
SAY "Essay 2:"
PULL es2
SAY "Essay 3:"
PULL es3
SAY "Essay 4:"
PULL es4
SAY "Participation:"
PULL p
Final = (((es1 + es2)/2*.3) + ((es3 + es4)/2*.45) + (p*.25))
SAY "Your final grade for this student is " Final
SAY "Would you like to continue? (Q for quit.)"
PULL response
END
EXIT
</syntaxhighlight>

AmigaOS Manual: ARexx Introducing ARexx

2014-01-25T08:43:41Z

Tony Wyatt:

The ARexx programming language can act as a central hub through which applications - even those created by different companies - can exchange data and commands. For example, using ARexx you can instruct a telecommunications package to dial an electronic bulletin board, download financial data from the bulletin board, and then automatically pass the data to a spreadsheet program for statistical analysis - without any user intervention.

ARexx is an interpreted language that uses ASCII file input. The ARexx interpreter is the RexxMast program, located in the System drawer of Workbench. RexxMast monitors the execution of an ARexx program. If RexxMast finds an error while translating or executing a line, it halts and displays an error message on the screen. This interactive testing is both a learning tool and an aid in debugging programs because it immediately highlights when and where an error has occurred.

= Who is ARexx For? =

You do not need extensive Amiga experience to use ARexx programs and scripts, but you do need to know how:

* To open a Shell and enter AmigaDOS commands
* To use a text editor, such as Notepad
* To edit the User-startup file

However, to change the scripts or create your own ARexx scripts, you should have a basic understanding of both the Amiga Workbench and AmigaDOS environments. Experienced Amiga users may find ARexx easier and more powerful than AmigaDOS. In fact, ARexx can be used to enhance or replace existing AmigaDOS commands and scripts, as well as to create integrated applications.

= ARexx on the Amiga =

ARexx is supported on all Amiga hardware configurations. Beginning with the release of Amiga Workbench Version 2.0, ARexx has been integrated into the Amiga operating system. Specifically, ARexx uses two important features of the Amiga operating system: multitasking and interprocess communication.

Multitasking is the ability to run more than one program at a time. For example, you can simultaneously edit a file, format a disk, and adjust your screen's colors.

Interprocess communication (IPC) is the ability to allow the exchange of information between applications. Interprocess communication is accomplished through the use of message ports, an address contained in an application that can receive and send messages, attached to each program. Each message port has a name and sending a message to an application requires the use of the port's name in an ARexx script.

The sequence of events in sending and receiving a message is:

# On initialization an application opens its message port.
# The application waits to receive a message.
# The Amiga operating system notifies the application that a message has arrived at its port.
# The application acts on that message.
# The application notifies the message's sender (ARexx) that the message has been received and processed.

This transfer of messages is not limited to one application and ARexx. Several applications can send messages back and forth using ARexx as the central transfer location. However, all the applications must be ARexx-compatible.

= ARexx Features =

Features of the ARexx programming language are:

* Typeless Data - Data is treated as individual character strings and variable values are undeclared.
* Interpreted Execution - The read-and-execute ability of ARexx skips the extra step of program compilation.
* Automatic Resource Management - Automatic internal memory allocation removes unnecessary strings and data.
* Tracing, Trapping, and Debugging - Tracing and trapping permit handling of errors that would normally abort the program. The debugging facilities allow you to view your entire program, reducing development and testing time.
* Function Libraries - External function libraries provide extended, pre-programmed functions.

AmigaOS Manual: ARexx Introducing ARexx

2014-01-25T08:41:15Z

Tony Wyatt:

The ARexx programming language can act as a central hub through which applications - even those created by different companies - can exchange data and commands. For example, using ARexx you can instruct a telecommunications package to dial an electronic bulletin board, download financial data from the bulletin board, and then automatically pass the data to a spreadsheet program for statistical analysis - without any user intervention.

ARexx is an interpreted language that uses ASCII file input. The ARexx interpreter is the RexxMast program, located in the System drawer of Workbench. RexxMast monitors the execution of an ARexx program. If RexxMast finds an error while translating or executing a line, it halts and displays an error message on the screen. This interactive testing is both a learning tool and an aid in debugging programs because it immediately highlights when and where an error has occurred.

= Who is ARexx For? =

You do not need extensive Amiga experience to use ARexx programs and scripts, but you do need to know how:

* To open a Shell and enter AmigaDOS commands
* To use a text editor, such as Notepad
* To edit the User-startup file

However, to change the scripts or create, your own ARexx scripts, you should have a basic understanding of both the Amiga Workbench and AmigaDOS environments. Experienced Amiga users may find ARexx easier and more powerful than AmigaDOS. In fact, ARexx can be used to enhance or replace existing AmigaDOS commands and scripts, as well as to create integrated applications.

= ARexx on the Amiga =

ARexx is supported on all Amiga hardware configurations. Beginning with the release of Amiga Workbench Version 2.0, ARexx has been integrated into the Amiga operating system. Specifically, ARexx uses two important features of the Amiga operating system: multitasking and interprocess communication.

Multitasking is the ability to run more than one program at a time. For example, you can simultaneously edit a file, format a disk, and adjust your screen's colors.

Interprocess communication (IPC) is the ability to allow the exchange of information between applications. Interprocess communication is accomplished through the use of message ports, an address contained in an application that can receive and send messages, attached to each program. Each message port has a name and sending a message to an application requires the use of the port's name in an ARexx script.

The sequence of events in sending and receiving a message is:

# On initialization an application opens its message port.
# The application waits to receive a message.
# The Amiga operating system notifies the application that a message has arrived at its port.
# The application acts on that message.
# The application notifies the message's sender (ARexx) that the message has been received and processed.

This transfer of messages is not limited to one application and ARexx. Several applications can send messages back and forth using ARexx as the central transfer location. However, all the applications must be ARexx-compatible.

= ARexx Features =

Features of the ARexx programming language are:

* Typeless Data - Data is treated as individual character strings and variable values are undeclared.
* Interpreted Execution - The read-and-execute ability of ARexx skips the extra step of program compilation.
* Automatic Resource Management - Automatic internal memory allocation removes unnecessary strings and data.
* Tracing, Trapping, and Debugging - Tracing and trapping permit handling of errors that would normally abort the program. The debugging facilities allow you to view your entire program, reducing development and testing time.
* Function Libraries - External function libraries provide extended, pre-programmed functions.

AmigaOS Manual: ARexx Getting Started

2014-01-25T08:37:31Z

Tony Wyatt:

This chapter shows you how to:

* Start ARexx
* Save Programs
* Store Programs
* Use sample programs

= Starting ARexx =

To start using ARexx, you activate the RexxMast program. The RexxMast program can be started automatically or manually. Each time ARexx is started or stopped, a text message appears.

== To Start ARexx Automatically ==

There are two methods to start ARexx automatically: add RexxMast to the WBStartup Prefs window or edit the S:User-Startup file.

To place RexxMast in the WBStartup Prefs list:

# Open the Prefs drawer.
# Open the WBStartup prefs.
# Click the "Add" button.
# Select SYS:System/RexxMast in the requester that pops up
# Click on "Save"
# Reboot your Amiga.

The command to start RexxMast should already be in the S:Startup-Sequence file. If the command has been removed from S:Startup-Sequence, we suggest that you add it to the S:User-Startup file.
To edit the S:User-Startup file:

# Open a text editor like Notepad.
# Open the S:User-Startup file.
# Enter ''SYS:System/RexxMast >NIL:''
# Save the file.
# Reboot your Amiga.

== To Start ARexx Manually ==

There are two ways to start RexxMast manually: double-click on the RexxMast icon in Workbench or start it from the Shell.

To start RexxMast from Workbench:

# Open the System Drawer.
# Double-click on the RexxMast icon.

To start RexxMast from the Shell:

# Open a Shell.
# Type ''RexxMast >NIL:'' and press Enter.

= About ARexx Programs =

ARexx programs are usually stored in the REXX: directory (which is generally assigned to the SYS:S/ARexx directory). Although programs can be stored in any directory, storing them in REXX: has several advantages:

* You can run the program without having to type the complete path.
* All of your ARexx programs will be in the same place.
* Most applications search for ARexx programs in REXX:.

Just as you can store an ARexx program anywhere, you can also name it anything you choose. However, adopting a simple naming convention will make program management much easier. Programs run from the Shell should have a .rexx extension to distinguish them from files run from other applications.

== Running ARexx Programs ==

The RX command is used to run an ARexx program. If a complete path is included with the program name, only that directory is searched for the program. If no path is included, the current directory and ''REXX:'' are checked.

As long as your programs is stored in the ''REXX:'' directory, you do not need to include the .rexx extension when specifying your program name. In other words, typing:

Rx Program.rexx

is the same as:

Rx Program

A short program can be entered directly at the command line by enclosing the program line in double-quotes. For example, the following program will send five files named myfile.1 through myfile.5 to the printer.

Rx "DO i=1 to 5;
ADDRESS command `copy myfile.' | | i `prt:'; END"

When an application is ARexx-compatible, you can run ARexx programs from within the application by choosing a menu item or by specifying command options. Refer to the application's documentation for more information.

ARexx programs can be run from the Workbench by creating a tool or project icon for the program. You must specify the Rx command as the Default Tool for the icon. In the icon's Information window, enter:

Default Tool: SYS:C/Rx

When the icon is opened, Rx starts RexxMast (if it is not already running). It executes the file associated with the icon as an ARexx program.

ARexx accepts two Tool Types: Console, to specify a window, and CMD, to specify a command string. You enter these Tool Types in the project icon's Information window as:

Console=CON:0/0/640/200/Example/Close
CMD=rexxprogram

= Program Examples =

The following examples illustrate how to use ARexx to display text strings on your screen, to perform calculations, and to activate the error checking feature.

Programs can be entered into any text editor, such as Notepad or a word processor. Save your program as an ASCII file if you use a word processor. ARexx supports the extended ASCII character set (Å, Æ, ß). These extended characters are recognized as ordinary printing characters and will be mapped from lowercase to uppercase.

The examples also illustrate the use of some basic ARexx syntax requirements such as:

* Comment lines
* Spacing rules
* Case-sensitivity
* Use of single and double quotes

Each ARexx program consists of a comment line that describes the program and an instruction that displays text on the console. ARexx programs must always begin with a comment line. The initial (slash asterisk) /* balanced with an ending (asterisk slash) */ tells the RexxMast interpreter that it has found an ARexx program. Without the /* and the */, RexxMast will not view the file as an ARexx program. Once it begins executing the program, ARexx ignores any additional comment lines within the file. However, comment lines are extremely useful when reading the program. They can help organize and make sense of a program.

== Amiga.rexx ==

This program shows how to use SAY in a set of instructions to display text strings on the screen. Instructions are language statements that denote a certain action to be performed. Each statement always begins with a symbol. In the following example, the symbol is SAY. (Symbols are always translated to uppercase letters when the program is run.) Following SAY is an example of a string. A string is a series of characters surrounded by single quotes (`) or double quotes (").

=== Program 1. Amiga.rexx ===

<syntaxhighlight>
/*A simple program*/
SAY `Amiga. The Computer For the Creative Mind.'
</syntaxhighlight>

Enter the above program, and save it as REXX:Amiga.rexx . To run the program, open a Shell window and type:

Rx Amiga

Although the full path and program name is ''Rexx:Amiga.rexx'', you do not need to type the REXX: directory name or the .rexx extension if the program has been saved in the REXX: directory.

You should see the following text in your Shell window:

Amiga. The Computer for the Creative Mind.

== Age.rexx ==

This program displays a prompt for input and then reads entered information.

=== Program 2. Age.rexx ===

<syntaxhighlight>
/*Calculate age in days*/
SAY `Please enter your age:'
PULL age
SAY `You are about' age*365 `days old.'
</syntaxhighlight>

Save this program as ''REXX:Age.rexx'' and run it with the command:

Rx age

This program begins with a comment line that describes what the program will do. All ARexx programs begin with a comment. The SAY instruction displays a request for input on the console.

The PULL instruction reads a line of input from the user, which in this case is the user's age. PULL takes the input, converts it to uppercase letters, and stores it in a variable. Variables are symbols which may be assigned a value. Choose descriptive variable names. This example uses the variable name "age" to hold the entered number.

The final line multiplies the variable "age" by 365 and issues the SAY instruction to display the result. The "age" variable did not have to be declared as a number because its value was checked when it was used in the expression. This is an example of typeless data. To see what would happen if age was not a number, try running the program again with a non-numeric entry for the age. The resulting error message shows the line number and type of error that occurred.

== Calc.rexx ==

This program introduces the DO instruction, which repeats the execution of program statements. It also illustrates the exponentiation operator ( ** ). Enter this program and save it as ''REXX:Calc.rexx''. To run the program, use the " Rx calc " command.

=== Program 3. Calc.rexx ===

<syntaxhighlight>
/*Calculate some squares and cubes.*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
SAY i i**2 i**3 /*Perform calculations*/
END /*End of loop*/
SAY `All done.'
</syntaxhighlight>

The DO instruction repeatedly executes the statements between the DO and END instructions. The variable " i " is the index variable for the loop and is incremented by 1 for each iteration (repetition). The number following the symbol TO is the limit for the DO instruction and could have been a variable or a full expression rather than just the constant 10.

Generally, ARexx programs use single spacing between alphanumeric characters. In Program 3, however, spacing is closed up between the exponentiation characters ( ** ) and the variables ( i and 2, i and 3).

The statements within the loop have been indented. This is not required by the language, but it makes the program more readable, because you can easily visualize where the loop starts and stops.

== Even.rexx ==

The IF instruction allows statements to be conditionally executed. In this example, the numbers from 1 to 10 are classified as odd or even by dividing them by 2 and then checking the remainder. The // arithmetic operator calculates the remainder after a division operation.

=== Program 4. Even.rexx ===

<syntaxhighlight>
/*Even or odd?*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
IF 1 // 2 = 0 THEN type = `even'
ELSE type = `odd'
SAY i `is' type
END /*End loop*/
</syntaxhighlight>

The IF line states that if the remainder of the division of the variable " i " by 2 equals 0, then set the variable " type " to even. If the remainder is not 0, the program will skip over the THEN branch and execute the ELSE branch, setting variable " type " to odd.

== Square.rexx ==

This example introduces the concept of a function, a group of statements executed by mentioning the function name in a suitable context. Functions allow you to build large complex programs from smaller modules. Functions also permit the same code for similar operations in a different program.

Functions are specified in an expression as a name followed by an open parenthesis. (There is no space between the name and the parenthesis.) One or more expressions, called arguments, may follow the parenthesis. The last argument must be followed by a closing parenthesis. These arguments pass information to the function for processing.

=== Program 5. Square.rexx ===

<syntaxhighlight>
/*Defining and calling a function.*/

DO i = 1 to 5
SAY i square (i) /*Call the "square" function*/
END
EXIT
square: /*Function name*/
ARG x /*Get the argument*/
RETURN x**2 /*Square it and return*/
</syntaxhighlight>

Starting with DO and ending with END , a loop is set up with an index variable "i", that will increment by 1. The loop will iterate (repeat) five times. The loop contains an expression that calls the function " square " when the expression is evaluated. The function's result is displayed using the SAY instruction.

The function " square ", defined by the ARG and RETURN instructions, calculates the squared values. ARG retrieves the value of the argument string " i " and RETURN passes the function's result back to the SAY instruction.

Once the function is called by the loop, the program looks for the function name " square ", retrieves the argument " i ", performs a calculation, and returns to the line within the DO/END loop. The EXIT instruction ends the program after the final loop.

== Results.rexx ==

The TRACE instruction activates ARexx's error checking feature.

=== Program 6. Results.rexx ===

<syntaxhighlight>
/*Demonstrate "results" tracing*/
TRACE results
sum = 0 ; sumsq = 0;
DO i = 1 to 5
sum = sum + 1
sumsq = sumsq + i**2
END
SAY `sum=' sum `sumsq=' sumsq
</syntaxhighlight>

The console displays the executed source lines, each pass through the DO/END loop, and the expression's final results. Removing the TRACE instruction, would display only the final result: sum = 15 sumsq = 55 .

== Grades.rexx ==

This program calculates the final grade for a given student based on four essay grades and a class participation grade. The average of Essay 1 and Essay 2 is worth 30%, the average of Essay 3 and Essay 4 is worth 45%, and participation is worth 25% of the final grade.

Once a final grade is displayed, an option to continue with another calculation is presented. The response is " PULLed " and if it does not equal Q (quit), the loop continues. If the response equals Q , the program quits the loop and exits.

=== Program 7. Grades.rexx ===

<syntaxhighlight>
/*Grading program*/
SAY "Hallo, I will calculate your grades for you."
Response = 0
DO while response ~ = "Q "/*Loop while response isn't Q*/
SAY "Please enter all grades for the student."
SAY "Essay 1:"
PULL es1
SAY "Essay 2:"
PULL es2
SAY "Essay 3:"
PULL es3
SAY "Essay 4:"
PULL es4
SAY "Participation:"
PULL p
Final = (((es1 + es2)/2*.3) + ((es3 + es4)/2*.45) + (p*.25))
SAY "Your final grade for this student is " Final
SAY "Would you like to continue? (Q for quit.)"
PULL response
END
EXIT
</syntaxhighlight>

AmigaOS Manual: ARexx Getting Started

2014-01-25T08:27:58Z

Tony Wyatt:

This chapter shows you how to:

* Start ARexx
* Save Programs
* Store Programs
* Use sample programs

= Starting ARexx =

To start using ARexx, you activate the RexxMast program. The RexxMast program can be started automatically or manually. Each time ARexx is started or stopped, a text message appears.

== To Start ARexx Automatically ==

There are two methods to start ARexx automatically: add RexxMast to the WBStartup Prefs window or edit the S:User-Startup file.

To place RexxMast in the WBStartup Prefs list:

# Open the Prefs drawer.
# Open the WBStartup prefs.
# Click the "Add" button.
# Select SYS:System/RexxMast in the requester that pops up
# Click on "Save"
# Reboot your Amiga.

To edit the S:User-Startup file:

# Open a text editor like Notepad.
# Open the S:User-Startup file.
# Enter ''SYS:System/RexxMast >NIL:''
# Save the file.
# Reboot your Amiga.

== To Start ARexx Manually ==

There are two ways to start RexxMast manually: double-click on the RexxMast icon in Workbench or start it from the Shell.

To start RexxMast from Workbench:

# Open the System Drawer.
# Double-click on the RexxMast icon.

To start RexxMast from the Shell:

# Open a Shell.
# Type ''RexxMast >NIL:'' and press Enter.

= About ARexx Programs =

ARexx programs are usually stored in the REXX: directory (which is generally assigned to the SYS:S/ARexx directory). Although programs can be stored in any directory, storing them in REXX: has several advantages:

* You can run the program without having to type the complete path.
* All of your ARexx programs will be in the same place.
* Most applications search for ARexx programs in REXX:.

Just as you can store an ARexx program anywhere, you can also name it anything you choose. However, adopting a simple naming convention will make program management much easier. Programs run from the Shell should have a .rexx extension to distinguish them from files run from other applications.

== Running ARexx Programs ==

The RX command is used to run an ARexx program. If a complete path is included with the program name, only that directory is searched for the program. If no path is included, the current directory and ''REXX:'' are checked.

As long as your programs is stored in the ''REXX:'' directory, you do not need to include the .rexx extension when specifying your program name. In other words, typing:

Rx Program.rexx

is the same as:

Rx Program

A short program can be entered directly at the command line by enclosing the program line in double-quotes. For example, the following program will send five files named myfile.1 through myfile.5 to the printer.

Rx "DO i=1 to 5;
ADDRESS command `copy myfile.' | | i `prt:'; END"

When an application is ARexx-compatible, you can run ARexx programs from within the application by choosing a menu item or by specifying command options. Refer to the application's documentation for more information.

ARexx programs can be run from the Workbench by creating a tool or project icon for the program. You must specify the Rx command as the Default Tool for the icon. In the icon's Information window, enter:

Default Tool: SYS:C/Rx

When the icon is opened, Rx starts RexxMast (if it is not already running). It executes the file associated with the icon as an ARexx program.

ARexx accepts two Tool Types: Console, to specify a window, and CMD, to specify a command string. You enter these Tool Types in the project icon's Information window as:

Console=CON:0/0/640/200/Example/Close
CMD=rexxprogram

= Program Examples =

The following examples illustrate how to use ARexx to display text strings on your screen, to perform calculations, and to activate the error checking feature.

Programs can be entered into any text editor, such as Notepad or a word processor. Save your program as an ASCII file if you use a word processor. ARexx supports the extended ASCII character set (Å, Æ, ß). These extended characters are recognized as ordinary printing characters and will be mapped from lowercase to uppercase.

The examples also illustrate the use of some basic ARexx syntax requirements such as:

* Comment lines
* Spacing rules
* Case-sensitivity
* Use of single and double quotes

Each ARexx program consists of a comment line that describes the program and an instruction that displays text on the console. ARexx programs must always begin with a comment line. The initial (slash asterisk) /* balanced with an ending (asterisk slash) */ tells the RexxMast interpreter that it has found an ARexx program. Without the /* and the */, RexxMast will not view the file as an ARexx program. Once it begins executing the program, ARexx ignores any additional comment lines within the file. However, comment lines are extremely useful when reading the program. They can help organize and make sense of a program.

== Amiga.rexx ==

This program shows how to use SAY in a set of instructions to display text strings on the screen. Instructions are language statements that denote a certain action to be performed. Each statement always begins with a symbol. In the following example, the symbol is SAY. (Symbols are always translated to uppercase letters when the program is run.) Following SAY is an example of a string. A string is a series of characters surrounded by single quotes (`) or double quotes (").

=== Program 1. Amiga.rexx ===

<syntaxhighlight>
/*A simple program*/
SAY `Amiga. The Computer For the Creative Mind.'
</syntaxhighlight>

Enter the above program, and save it as REXX:Amiga.rexx . To run the program, open a Shell window and type:

Rx Amiga

Although the full path and program name is ''Rexx:Amiga.rexx'', you do not need to type the REXX: directory name or the .rexx extension if the program has been saved in the REXX: directory.

You should see the following text in your Shell window:

Amiga. The Computer for the Creative Mind.

== Age.rexx ==

This program displays a prompt for input and then reads entered information.

=== Program 2. Age.rexx ===

<syntaxhighlight>
/*Calculate age in days*/
SAY `Please enter your age:'
PULL age
SAY `You are about' age*365 `days old.'
</syntaxhighlight>

Save this program as ''REXX:Age.rexx'' and run it with the command:

Rx age

This program begins with a comment line that describes what the program will do. All ARexx programs begin with a comment. The SAY instruction displays a request for input on the console.

The PULL instruction reads a line of input from the user, which in this case is the user's age. PULL takes the input, converts it to uppercase letters, and stores it in a variable. Variables are symbols which may be assigned a value. Choose descriptive variable names. This example uses the variable name "age" to hold the entered number.

The final line multiplies the variable "age" by 365 and issues the SAY instruction to display the result. The "age" variable did not have to be declared as a number because its value was checked when it was used in the expression. This is an example of typeless data. To see what would happen if age was not a number, try running the program again with a non-numeric entry for the age. The resulting error message shows the line number and type of error that occurred.

== Calc.rexx ==

This program introduces the DO instruction, which repeats the execution of program statements. It also illustrates the exponentiation operator ( ** ). Enter this program and save it as ''REXX:Calc.rexx''. To run the program, use the " Rx calc " command.

=== Program 3. Calc.rexx ===

<syntaxhighlight>
/*Calculate some squares and cubes.*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
SAY i i**2 i**3 /*Perform calculations*/
END /*End of loop*/
SAY `All done.'
</syntaxhighlight>

The DO instruction repeatedly executes the statements between the DO and END instructions. The variable " i " is the index variable for the loop and is incremented by 1 for each iteration (repetition). The number following the symbol TO is the limit for the DO instruction and could have been a variable or a full expression rather than just the constant 10.

Generally, ARexx programs use single spacing between alphanumeric characters. In Program 3, however, spacing is closed up between the exponentiation characters ( ** ) and the variables ( i and 2, i and 3).

The statements within the loop have been indented. This is not required by the language, but it makes the program more readable, because you can easily visualize where the loop starts and stops.

== Even.rexx ==

The IF instruction allows statements to be conditionally executed. In this example, the numbers from 1 to 10 are classified as odd or even by dividing them by 2 and then checking the remainder. The // arithmetic operator calculates the remainder after a division operation.

=== Program 4. Even.rexx ===

<syntaxhighlight>
/*Even or odd?*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
IF 1 // 2 = 0 THEN type = `even'
ELSE type = `odd'
SAY i `is' type
END /*End loop*/
</syntaxhighlight>

The IF line states that if the remainder of the division of the variable " i " by 2 equals 0, then set the variable " type " to even. If the remainder is not 0, the program will skip over the THEN branch and execute the ELSE branch, setting variable " type " to odd.

== Square.rexx ==

This example introduces the concept of a function, a group of statements executed by mentioning the function name in a suitable context. Functions allow you to build large complex programs from smaller modules. Functions also permit the same code for similar operations in a different program.

Functions are specified in an expression as a name followed by an open parenthesis. (There is no space between the name and the parenthesis.) One or more expressions, called arguments, may follow the parenthesis. The last argument must be followed by a closing parenthesis. These arguments pass information to the function for processing.

=== Program 5. Square.rexx ===

<syntaxhighlight>
/*Defining and calling a function.*/

DO i = 1 to 5
SAY i square (i) /*Call the "square" function*/
END
EXIT
square: /*Function name*/
ARG x /*Get the argument*/
RETURN x**2 /*Square it and return*/
</syntaxhighlight>

Starting with DO and ending with END , a loop is set up with an index variable "i", that will increment by 1. The loop will iterate (repeat) five times. The loop contains an expression that calls the function " square " when the expression is evaluated. The function's result is displayed using the SAY instruction.

The function " square ", defined by the ARG and RETURN instructions, calculates the squared values. ARG retrieves the value of the argument string " i " and RETURN passes the function's result back to the SAY instruction.

Once the function is called by the loop, the program looks for the function name " square ", retrieves the argument " i ", performs a calculation, and returns to the line within the DO/END loop. The EXIT instruction ends the program after the final loop.

== Results.rexx ==

The TRACE instruction activates ARexx's error checking feature.

=== Program 6. Results.rexx ===

<syntaxhighlight>
/*Demonstrate "results" tracing*/
TRACE results
sum = 0 ; sumsq = 0;
DO i = 1 to 5
sum = sum + 1
sumsq = sumsq + i**2
END
SAY `sum=' sum `sumsq=' sumsq
</syntaxhighlight>

The console displays the executed source lines, each pass through the DO/END loop, and the expression's final results. Removing the TRACE instruction, would display only the final result: sum = 15 sumsq = 55 .

== Grades.rexx ==

This program calculates the final grade for a given student based on four essay grades and a class participation grade. The average of Essay 1 and Essay 2 is worth 30%, the average of Essay 3 and Essay 4 is worth 45%, and participation is worth 25% of the final grade.

Once a final grade is displayed, an option to continue with another calculation is presented. The response is " PULLed " and if it does not equal Q (quit), the loop continues. If the response equals Q , the program quits the loop and exits.

=== Program 7. Grades.rexx ===

<syntaxhighlight>
/*Grading program*/
SAY "Hallo, I will calculate your grades for you."
Response = 0
DO while response ~ = "Q "/*Loop while response isn't Q*/
SAY "Please enter all grades for the student."
SAY "Essay 1:"
PULL es1
SAY "Essay 2:"
PULL es2
SAY "Essay 3:"
PULL es3
SAY "Essay 4:"
PULL es4
SAY "Participation:"
PULL p
Final = (((es1 + es2)/2*.3) + ((es3 + es4)/2*.45) + (p*.25))
SAY "Your final grade for this student is " Final
SAY "Would you like to continue? (Q for quit.)"
PULL response
END
EXIT
</syntaxhighlight>

AmigaOS Manual: ARexx Getting Started

2014-01-25T08:24:27Z

Tony Wyatt: Fixed typos

This chapter shows you how to:

* Start ARexx
* Save Programs
* Store Programs
* Use sample programs

= Starting ARexx =

To start using ARexx, you activate the RexxMast program. The RexxMast program can be started automatically or manually. Each time ARexx is started or stopped, a text message appears.

== To Start ARexx Automatically ==

There are two methods to start ARexx automatically: add RexxMast to the WBStartup Prefs window or edit the S:User-Startup file.

To place RexxMast in the WBStartup Prefs list:

# Open the Prefs drawer.
# Open the WBStartup prefs.
# Click the "Add" button.
# Select SYS:System/RexxMast in the requester that pops up
# Click on "Save"
# Reboot your Amiga.

To edit the S:User-Startup file:

# Open a text editor like Notepad.
# Open the S:User-Startup file.
# Enter ''SYS:System/RexxMast >NIL:''
# Save the file.
# Reboot your Amiga.

== To Start ARexx Manually ==

There are two ways to start RexxMast manually: double-click on the RexxMast icon in Workbench or start it from the Shell.

To start RexxMast from Workbench:

# Open the System Drawer.
# Double-click on the RexxMast icon.

To start RexxMast from the Shell:

# Open a Shell.
# Type ''RexxMast >NIL:'' and press Enter.

= About ARexx Programs =

ARexx programs are usually stored in the REXX: directory (which is generally assigned to the SYS:S/ARexx directory). Although programs can be stored in any directory, storing them in REXX: has several advantages:

* You can run the program without having to type the complete path.
* All of your ARexx programs will be in the same place.
* Most applications search for ARexx programs in REXX:.

Just as you can store an ARexx program anywhere, you can also name it anything you choose. However, adopting a simple naming convention will make program management much easier. Programs run from the Shell should have a .rexx extension to distinguish them from files run from other applications.

== Running ARexx Programs ==

The RX command is used to run an ARexx program. If a complete path is included with the program name, only that directory is searched for the program. If no path is included, the current directory and ''REXX:'' are checked.

As long as your programs is stored in the ''REXX:'' directory, you do not need to include the .rexx extension when specifying your program name. In other words, typing:

RX Program.rexx

is the same as:

Rx Program

A short program can be entered directly at the command line by enclosing the program line in double-quotes. For example, the following program will send five files named myfile.1 through myfile.5 to the printer.

Rx "DO i=1 to 5;
ADDRESS command `copy myfile.' | | i `prt:'; END"

When an application is ARexx-compatible, you can run ARexx programs from within the application by choosing a menu item or by specifying command options. Refer to the application's documentation for more information.

ARexx programs can be run from the Workbench by creating a tool or project icon for the program. You must specify the Rx command as the Default Tool for the icon. In the icon's Information window, enter:

Default Tool: SYS:C/Rx

When the icon is opened, Rx starts RexxMast (if it is not already running). It executes the file associated with the icon as an ARexx program.

ARexx accepts two Tool Types: Console, to specify a window, and CMD, to specify a command string. You enter these Tool Types in the project icon's Information window as:

Console=CON:0/0/640/200/Example/Close
CMD=rexxprogram

= Program Examples =

The following examples illustrate how to use ARexx to display text strings on your screen, to perform calculations, and to activate the error checking feature.

Programs can be entered into any text editor, such as Notepad or a word processor. Save your program as an ASCII file if you use a word processor. ARexx supports the extended ASCII character set (Å, Æ, ß). These extended characters are recognized as ordinary printing characters and will be mapped from lowercase to uppercase.

The examples also illustrate the use of some basic ARexx syntax requirements such as:

* Comment lines
* Spacing rules
* Case-sensitivity
* Use of single and double quotes

Each ARexx program consists of a comment line that describes the program and an instruction that displays text on the console. ARexx programs must always begin with a comment line. The initial (slash asterisk) /* balanced with an ending (asterisk slash) */ tells the RexxMast interpreter that it has found an ARexx program. Without the /* and the */, RexxMast will not view the file as an ARexx program. Once it begins executing the program, ARexx ignores any additional comment lines within the file. However, comment lines are extremely useful when reading the program. They can help organize and make sense of a program.

== Amiga.rexx ==

This program shows how to use SAY in a set of instructions to display text strings on the screen. Instructions are language statements that denote a certain action to be performed. Each statement always begins with a symbol. In the following example, the symbol is SAY. (Symbols are always translated to uppercase letters when the program is run.) Following SAY is an example of a string. A string is a series of characters surrounded by single quotes (`) or double quotes (").

=== Program 1. Amiga.rexx ===

<syntaxhighlight>
/*A simple program*/
SAY `Amiga. The Computer For the Creative Mind.'
</syntaxhighlight>

Enter the above program, and save it as REXX:Amiga.rexx . To run the program, open a Shell window and type:

Rx Amiga

Although the full path and program name is ''Rexx:Amiga.rexx'', you do not need to type the REXX: directory name or the .rexx extension if the program has been saved in the REXX: directory.

You should see the following text in your Shell window:

Amiga. The Computer for the Creative Mind.

== Age.rexx ==

This program displays a prompt for input and then reads entered information.

=== Program 2. Age.rexx ===

<syntaxhighlight>
/*Calculate age in days*/
SAY `Please enter your age:'
PULL age
SAY `You are about' age*365 `days old.'
</syntaxhighlight>

Save this program as ''REXX:Age.rexx'' and run it with the command:

Rx age

This program begins with a comment line that describes what the program will do. All ARexx programs begin with a comment. The SAY instruction displays a request for input on the console.

The PULL instruction reads a line of input from the user, which in this case is the user's age. PULL takes the input, converts it to uppercase letters, and stores it in a variable. Variables are symbols which may be assigned a value. Choose descriptive variable names. This example uses the variable name "age" to hold the entered number.

The final line multiplies the variable "age" by 365 and issues the SAY instruction to display the result. The "age" variable did not have to be declared as a number because its value was checked when it was used in the expression. This is an example of typeless data. To see what would happen if age was not a number, try running the program again with a non-numeric entry for the age. The resulting error message shows the line number and type of error that occurred.

== Calc.rexx ==

This program introduces the DO instruction, which repeats the execution of program statements. It also illustrates the exponentiation operator ( ** ). Enter this program and save it as ''REXX:Calc.rexx''. To run the program, use the " Rx calc " command.

=== Program 3. Calc.rexx ===

<syntaxhighlight>
/*Calculate some squares and cubes.*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
SAY i i**2 i**3 /*Perform calculations*/
END /*End of loop*/
SAY `All done.'
</syntaxhighlight>

The DO instruction repeatedly executes the statements between the DO and END instructions. The variable " i " is the index variable for the loop and is incremented by 1 for each iteration (repetition). The number following the symbol TO is the limit for the DO instruction and could have been a variable or a full expression rather than just the constant 10.

Generally, ARexx programs use single spacing between alphanumeric characters. In Program 3, however, spacing is closed up between the exponentiation characters ( ** ) and the variables ( i and 2, i and 3).

The statements within the loop have been indented. This is not required by the language, but it makes the program more readable, because you can easily visualize where the loop starts and stops.

== Even.rexx ==

The IF instruction allows statements to be conditionally executed. In this example, the numbers from 1 to 10 are classified as odd or even by dividing them by 2 and then checking the remainder. The // arithmetic operator calculates the remainder after a division operation.

=== Program 4. Even.rexx ===

<syntaxhighlight>
/*Even or odd?*/
DO i = 1 to 10 /*Begin loop - 10 iterations*/
IF 1 // 2 = 0 THEN type = `even'
ELSE type = `odd'
SAY i `is' type
END /*End loop*/
</syntaxhighlight>

The IF line states that if the remainder of the division of the variable " i " by 2 equals 0, then set the variable " type " to even. If the remainder is not 0, the program will skip over the THEN branch and execute the ELSE branch, setting variable " type " to odd.

== Square.rexx ==

This example introduces the concept of a function, a group of statements executed by mentioning the function name in a suitable context. Functions allow you to build large complex programs from smaller modules. Functions also permit the same code for similar operations in a different program.

Functions are specified in an expression as a name followed by an open parenthesis. (There is no space between the name and the parenthesis.) One or more expressions, called arguments, may follow the parenthesis. The last argument must be followed by a closing parenthesis. These arguments pass information to the function for processing.

=== Program 5. Square.rexx ===

<syntaxhighlight>
/*Defining and calling a function.*/

DO i = 1 to 5
SAY i square (i) /*Call the "square" function*/
END
EXIT
square: /*Function name*/
ARG x /*Get the argument*/
RETURN x**2 /*Square it and return*/
</syntaxhighlight>

Starting with DO and ending with END , a loop is set up with an index variable "i", that will increment by 1. The loop will iterate (repeat) five times. The loop contains an expression that calls the function " square " when the expression is evaluated. The function's result is displayed using the SAY instruction.

The function " square ", defined by the ARG and RETURN instructions, calculates the squared values. ARG retrieves the value of the argument string " i " and RETURN passes the function's result back to the SAY instruction.

Once the function is called by the loop, the program looks for the function name " square ", retrieves the argument " i ", performs a calculation, and returns to the line within the DO/END loop. The EXIT instruction ends the program after the final loop.

== Results.rexx ==

The TRACE instruction activates ARexx's error checking feature.

=== Program 6. Results.rexx ===

<syntaxhighlight>
/*Demonstrate "results" tracing*/
TRACE results
sum = 0 ; sumsq = 0;
DO i = 1 to 5
sum = sum + 1
sumsq = sumsq + i**2
END
SAY `sum=' sum `sumsq=' sumsq
</syntaxhighlight>

The console displays the executed source lines, each pass through the DO/END loop, and the expression's final results. Removing the TRACE instruction, would display only the final result: sum = 15 sumsq = 55 .

== Grades.rexx ==

This program calculates the final grade for a given student based on four essay grades and a class participation grade. The average of Essay 1 and Essay 2 is worth 30%, the average of Essay 3 and Essay 4 is worth 45%, and participation is worth 25% of the final grade.

Once a final grade is displayed, an option to continue with another calculation is presented. The response is " PULLed " and if it does not equal Q (quit), the loop continues. If the response equals Q , the program quits the loop and exits.

=== Program 7. Grades.rexx ===

<syntaxhighlight>
/*Grading program*/
SAY "Hallo, I will calculate your grades for you."
Response = 0
DO while response ~ = "Q "/*Loop while response isn't Q*/
SAY "Please enter all grades for the student."
SAY "Essay 1:"
PULL es1
SAY "Essay 2:"
PULL es2
SAY "Essay 3:"
PULL es3
SAY "Essay 4:"
PULL es4
SAY "Participation:"
PULL p
Final = (((es1 + es2)/2*.3) + ((es3 + es4)/2*.45) + (p*.25))
SAY "Your final grade for this student is " Final
SAY "Would you like to continue? (Q for quit.)"
PULL response
END
EXIT
</syntaxhighlight>