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