Welcome

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:

ERRORTEXT()

ERRORTEXT(n)

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

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:

GETCLIP()

GETCLIP(name)

/*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

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

HASH()

HASH(string)

SAY HASH(`1') -> 49

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:

IMPORT()

IMPORT(address[,length])

extval = IMPORT(`0004 0000'x,8)

INDEX()

INDEX(string,pattern[,start])

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:

SAY INDEX("123456", "23") -> 2 SAY INDEX("123456", "77") -> 0 SAY INDEX("123123", "23",3) -> 5

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:

INSERT()

INSERT(new,old[,start][,length][,pad])

SAY INSERT(`ab', `12345') -> ab12345 SAY INSERT(`123', `++',3,5, `-`) -> ++-123--

LASTPOS()

LASTPOS(pattern,string[,start])

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:

SAY LASTPOS(`2', `1234') -> 2 SAY LASTPOS(`2', `1234234') -> 5 SAY LASTPOS(`2', `123234',3) -> 2 SAY LASTPOS(`2', `13579') -> 0

LEFT()

LEFT(string,length[,pad])

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:

SAY LEFT(`123456',3) -> 123 SAY LEFT(`123456',8, `+') -> 123456++

Returns the length of the string. For example:

LENGTH()

LENGTH(string)

SAY LENGTH(`three') -> 5

LINES()

LINES(file)

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:

PUSH `a line' PUSH `another one' SAY LINES(STDIN) -> 2

MAX()

MAX(number,number[,number,...])

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

SAY MAX(2.1,3,-1) -> 3