Error Trapping in Functions
Updated and November 2016
Although this topic explicitly discusses Functions, it applies equally to Procedures—which are, after all, just functions without return values. Every occurrence of the word “Function” in this topic (and nearly all others), either in the text or in syntax or examples, regardless of case, and including compound keywords like ENDFUNCTION, may be taken to apply to procedures (e.g. ENDPROCEDURE) as well.
By default, ASB errors within functions are internally filtered in such a way that the error appears to the caller to have occurred on the line that called the function. This allows the stack to be properly unwound rather than doing an unstructured ON ERROR GOTO out of the function. You may, however, create a local error trap inside the function, using the regular ON ERROR GOTO statement. The local error trap may resume back to locations within the function, or it may resume back to the caller, or even to a global error trap, including optionally forwarding an error code, using one of the following syntaxes:
RESUME {label}
RESUME ENDFUNCTION {WITH_ERROR {errno}}
RESUME EXITPROGRAM {WITH_ERROR {errno}}
The first syntax is used to clear the error and resume to the specified label within the function, including the special label $EXIT, or to the line which triggered the error if the $EXIT label is not present. Note that this variation works outside of functions as well..
The second syntax (ENDFUNCTION) terminates the current function, bypassing the local $EXIT label if present, resuming to the line that called the function.
The third syntax (EXITPROGRAM) is like the ENDFUNCTION option, except that it keeps going—terminating the current function and returning to its caller—until it gets back to the top level main program, after which it resumes to the special label $EXITPROGRAM.
Without the optional WITH_ERROR clause, the error condition is cleared. A common way to use this feature would be:
FN'name = err(0) ! assign ASB error # to function value
RESUME ENDFUNCTION ! return to caller (with error cleared)
This would clear the error condition, so it doesn't trigger the caller's ON ERROR GOTO, but it would still return to the caller the error number via the function's return value. This would enable the caller to take action in a more structured manner, as opposed to via an error trap.
If the WITH_ERROR {errno} clause is specified, then the function returns with the error number set—i.e. triggering the error handling process in the caller. Omitting errno, or setting it to 0 or err(0), preserves the current error, while specifying an errno value allows you to change the error code passed back.
Comments
The EXITPROGRAM option is useful in situations where the only sensible response to the error (besides logging it) is to terminate the program, perhaps returning to a main menu or support screen. Being able to go there directly relieves the burden on the calling functions to handle passing the status back up the chain.
Note: RESUME EXITPROGRAM is best used without the "WITH_ERROR" clause, i.e. it's best to handle and clear the error prior to resuming to your global $EXITPROGRAM label. Otherwise, with the error still set, the global error trap will redirect control to itself, so that your $EXITPROGRAM code may never get executed.
EXITPROGRAM can also be used as a standalone statement to perform the same global jump outside the context of any error.
Note that since the local error trap code must be within the function, some care must be taken to make sure that it doesn't get executed except on error. One technique would be to use an EXITFUNCTION label just above it, as shown in the following example.
Example
FUNCTION FN'TEST()
ON ERROR GOTO TRAP
...
...
EXITFUNCTION
TRAP:
PRINT "Error #";ERR(0);" in procedure TEST()"
RESUME ENDFUNCTION WITH_ERROR 199
ENDFUNCTION
See Also
History
2024 February, A-Shell 7.0.1756, compiler edit 1043: Support for EXITPROGRAM added.
