AmigaOS Manual: ARexx Functions

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 to 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:

CENTER ('title', 20)
ADDRESS()
'ALLOCMEM' (256*4,1)

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

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 r 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:

CENTER: /*internal "CENTER"*/
ARG string, length /*get arguments*/
length = MIN(length,60) /*compute length*/
return 'CENTER' (string, length)

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:

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 GETCLIP() and then INTERPRETed within the program. The assignment statements within the string would then create the required constant definitions. For example:

/*Assume a string called "numbers" is available*/
numbers = GETCLIP ('numbers')
INTERPRET numbers /*. . . assignments*/

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 the 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 (bitte Pfeil einsetzen) is used as an abbreviation for "evaluates as." The arrow will not be displayed when a program is run. For example:

SAY ABS (-5.35) -> 5.35

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

Alphabetical Reference

ABBREV()

ABBREV(string1,string2[,length])

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:

SAY ABBREV ('fullname', 'ful') -> 1
SAY ABBREV ('almost', 'alm',4) -> 0
SAY ABBREV ('any','') -> 1

ABS()

ABS(number)

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

SAY ABS(-5.35) -> 5.35
SAY ABS(10) -> .10

ADDLIB()

ADDLIB(name,priority[,offset,version])

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 hist port is open. For example:

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

ADDRESS()

ADDRESS()

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:

SAY ADDRESS() -> REXX

ARG()

ARG([number][,'EXISTS'|'OMITTED'])

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:

/*Assume arguments were: ('one',,10)*/
SAY ARG() -> 3
SAY ARG(1) -> one
SAY ARG(2,'O') -> 1

B2C()

B2C(string)

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:

SAY B2C('00110011') -> 3
SAY B2C('01100001') -> a

BITAND()

BITAND(string1,string2[,pad])

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:

BITAND('0313'x, 'FFF0'x) -> '0310'x

BITCHG()

BITCHG(string,bit)

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:

BITCHG('0313'x,4) -> '0303'x

BITCLR()

BITCLR(string,bit)

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:

BITCLR('0313'x,4) -> '0303'x

BITCOMP()

BITCOMP(string1,string2[,pad])

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:

BITCOMP('7F'x, 'FF'x) -> 7 /*Seventh bit*/
BITCOMP('FF'x, 'FF'x) -> -1

BITOR()

BITOR(string1,string2[,pad])

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:

BITOR('0313'x, '00F'x) -> '033F'x

BITSET()

BITSET(string,bit)

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:

BITSET('313'x,2) -> '0317'x

BITTST()

BITTST(string,bit)

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:

BITTST('0313=x,4) -> 1

BITXOR()

BITXOR(string1,string2[,pad])

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:

BITXOR('0313'x, '001F'x) -> '030C'X

C2B()

C2B(string)

Converts the character string into the equivalent string of binary digits. See also C2X(). For example:

SAY C2B('abc') -> 011000010110001001100011

C2D()

C2D(string[,n])

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:

SAY C2D('0020'x) -> 32
SAY C2D('FFFF ffff'x) -> -1
SAY C2D('FF0100'x,2) -> 256

C2X()

C2X(string)

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:

SAY C2X('abc') -> 616263

CENTER()/CENTRE()

CENTER(string,length[,pad])
CENTRE(string,length[,pad])

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:

SAY CENTER('abc',6) -> ' abc '
SAY CENTER('abc',6,'+') -> '+abc++'
SAY CENTER ('123456',3) -> '234'

CLOSE()

CLOSE(file)

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:

SAY CLOSE('input') -> 1

COMPARE()

COMPARE(string1,string2[,pad])

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:

SAY COMPARE('abcde', 'abcce') -> 4
SAY COMPARE('abcde', 'abcde') -> 0
SAY COMPARE('abc++', 'abc+-', '+') -> 5

COMPRESS()

COMPRESS(string[,list])

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:

SAY COMPRESS(' why not ') -> whynot
SAY COMPRESS('++12-34-+', '+-') -> 1234

COPIES()

COPIES(string,number)

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:

SAY COPIES('abc',3) -> abcabcabc

D2C()

D2C(number)

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

D2C(65) -> A

D2X()

D2X(number[,digits])

Converts a decimal number to hexadecimal. For example:

D2X(31) -> 1F

DATATYPE()

DATATYPE(string[,option])

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:

SAY DATATYPE('123') -> NUM
SAY DATATYPE('1a f2', 'X') -> 1
SAY DATATYPE('aBcde', 'L') -> 0

DATE()

DATE([option][,date][format])

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:

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

DELSTR()

DELSTR(string,n[,length])

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:

SAY DELSTR('123456',2,3) -> 156

DELWORD()

DELWORD(string,n[,length])

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:

SAY DELWORD('Tell me a story',2,2) -> 'Tell story'
SAY DELWORD('one two three',3) -> 'one two '

DIGITS()

DIGITS()

Returns the current Numeric Digits setting. For example:

NUMERIC DIGITS 6
SAY DIGITS() -> 6

EOF()

EOF(file)

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:

SAY EOF(infile) -> 1

ERRORTEXT()

ERRORTEXT(n)

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:

SAY ERRORTEXT(41) -> Invalid expression

EXISTS()

EXISTS(filename)

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

SAY EXISTS('SYS:C/ED') -> 1

EXPORT()

EXPORT(address[,string][,length][,pad])

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.

Caution
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:

count = EXPORT('0004 0000'x, 'The answer')

FIND()

FIND(string,phrase)

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:

SAY FIND('Now is the time', 'is the') -> 2

FORM()

FORM()

Returns the current NUMERIC FORM setting. For example:

NUMERIC FORM SCIENTIFIC
SAY FORM() -> SCIENTIFIC

FREESPACE()

FREESPACE(address,length)

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:

FREESPACE('00042000'x,32) -> 1

FUZZ()

FUZZ()

Returns the current NUMERIC FUZZ setting. For example:

NUMERIC FUZZ 3
SAY FUZZ() -> 3

GETCLIP()

GETCLIP(name)

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:

/*Assume 'numbers' contains 'PI=3.14159'*/
SAY GETCLIP('numbers') -> PI=3.14159

GETSPACE()

GETSPACE(length)

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:

SAY C2X (GETSPACE(32)) -> '0003BF40'x