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.