A: Error Messages

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.

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.