Error TrappingThe elimination of (most) error trapping by PowerBASIC means that when most errors occurs (such as divide by zero), PowerBASIC does not stop operation, it does not display an error message, it does not set error variables (such as ERR - see below). It just continues execution with no warning to the programmer. The results of the statements and variable involved will be undefined and will likely result in the program giving unexpected results.
However, some errors are so serious that Windows will force the program to stop - a General Protection Fault (GPF). Some GPFs can even cause the PC to shut down and reboot!
Fortunately, PowerBASIC provides several ways for a programmer to trap run-time errors to prevent unexpected results or untimely termination of the program. Here's a categorized list of the PowerBASIC error functions.
| erl, erl$, err, errclear, error$ |
| error |
| On Error, resume, Try/End Try |
The tutorial on debugging provides additional information on PowerBASIC capabilities for identifying errors with program code.
Exceptions to Error Detection
PowerBASIC does detect disk access violations. The types of
errors detected are listed further down this page, under "Run-Time Errors".
PowerBASIC programs can also detect out-of-bounds array, pointer access, and memory allocation failures - but only when the compiler directive #DEBUG ERROR ON is used. It is OFF by default.
Trapping Run-Time Errors
Instead of simply letting an application crash when a run-time
error occurs, a programmer can make use of two PowerBASIC tools
for handling errors which happen while the program is running.
Normally, the goal of a programmer is to monitor inputs from users, or the system, and to prevent the occurrence of errors. However, that may not always be possible, in which case the programmer can turn to one of the following methods of capturing an error and continuing to execute code that works around the error.
Consider what happens in the next example application, which does not have error trapping. If the filename entered by the user does not exist, the Open statement fails with an error. Without an error trap, the error is ignored, except that the PowerBASIC error functions (err, error$, erl, erl$) are set. The next line is executed, a% is set to 5, and the program ends.
Function PBMain () As Long
f$ = InputBox$ "Filename?: ",,"") ' ask user for filename
Open "xx.xx" For Input as #1 ' error if not exist
a% = 5 ' executes regardless of error
End Function
The error functions could be examined at this time to check for an error. However, the next example shows how to have PowerBASIC respond automatically to the error.
The first line adds error trapping by adding the On Error statement. If the Open statement fails to find the file, an error is generated. Because the On Error statement is present, PowerBASIC jumps to the line labeled "mistake" and continues execution. At that point, a messagebox displays the error message found in Error$. When the messagebox is dismissed, the application ends.
Function PBMain () As Long
On Error GoTo mistake ' mistake is a label name
f$ = InputBox$ "Filename?: ",,"") ' ask user for filename
Open "xx.xx" For Input as #1 ' error if not exist
a% = 5 ' executes if not error
Exit Function
mistake: ' on error, execution continues here
MsgBox Error$ ' error displayed
End Function
Rather than simply display the error message, the program would normally react to the error, perhaps by asking the user for another filename. The point is that by using On Error the program traps the run-time error and executes specified code in response to the error. The programmer has to decide what response is appropriate, but the opportunity to respond is made possible by the use of On Error.
Two variations of the On GoTo statement are provided by PowerBASIC.
On Error Resume Next
On Error GoTo 0
The Resume Next simply tells PowerBASIC to ignore the error and continue execution with the line following the one where the error occurred. This statement would be used instead of the GoTo xx statement, telling PowerBASIC that there is no error trapping code to execute.
The GoTo 0 turns off error trapping. This statement can be inserted at any point in the procedure to disable any future response by PowerBASIC to an error.
Finally, a RESUME statement may be included within the error trap code. If used, the resume jumps to the directed location. Next refers to the line of code following the one where the error occurred. Label refers to any source code line within the procedure with the specified label or line number.
Resume next
Resume Label
TRY
... statements1
CATCH
... error handler statement2
FINALLY 'optional
... statements3
END TRY
When a Try/End Try code block is reached in a program, the TRY statements are executed normally. If an error occurs in that code, the CATCH statements are executed. If not error occurs, the CATCH statements are ignored.
Regardless of whether an error occurs, the statements in the optional FINALLY section are executed.
Here's the Try/End Try code again, with some actual statements. The file name "xxx.xxx" won't exist and so an error occurs, causing the Catch statement to be executed. The single line of Finally code will execute regardless of whether an error occurred or whether the Catch statements were executed.
Try
Open "xxx.xxx" For Input As #1
Catch
MsgBox "Error: xxx.xxx not found!"
Finally
MsgBox "no matter what"
End Try
Try levels can be nested. Because of that the ERR value is local to the Try structure. Whatever ERR was before the Try structure was entered, will be restored on the Try structure is exited.
While not prevented, PowerBASIC discourages exiting a Try structure except by passing through the Exit Try statement.
On Error GoTo can be used in the same procedure as a Try structure, but not within a Try structure.
Once an error is trapped within PowerBASIC (using either of the techniques above), PowerBASIC makes information about the error available to the program, as discussed in the next section.
Information About Run-Time Errors
When an error is trapped, there are four pieces of information
that PowerBASIC makes available to the programmer:
ERL returns the last numbered line that was executed before the error. If lines are not numbered, ERL returns zero. It does not return the simple physical position of the source code line within the program.
ERL$ extends the capability of ERL, covering not only the last numbered line but the last label or procedure executed prior to the error. Only a single value is returned - whichever of the three is closest to the line where the error occurred.
ERR returns the error code can be used to look up a description of the error, as shown in the table of trappable run-time error codes that is listed further down this page. Another PowerBASIC error function ERRClear can also be used to retreive the error code. However, then ERRClear is used, it also clears ERR.
ERROR$ provides a description that matches the error code - just like the table below but available to the application so that it can display the error to users as an aide to debugging.
Simulating Errors - ERROR
When writing a program a programmer needs to see if the program
can handle errors. One approach is to write code that causes
a real error. However, it's simpler to use the ERROR statement,
which causes a specified run-time error to be generated.
Error Trapping Points to Remember
Remember that PowerBASIC simply does not trap numeric errors.
If a division by zero occurs, the use of an On Error will not
work because PowerBASIC does not trap the error. The programmer
must detect/test, and then correct, the conditions that would cause
an error.
PowerBASIC does capture all file I/O errors and using the On Error statement will allow a program to respond to the error by executing specified code.
Error trapping is local to a procedure. The target of a GOTO must be in the same procedure as the GOTO statement.
Error trapping cannot occur in an expression.
Error trapping for array out-of-bounds and null-pointer values can be trapped, but only if the compiler directive #DEBUG ERROR ON is used. This is often used during program development but then removed for production software.
Run-Time Errors Here's a listing of the pre-assigned run-time errors.
|
|
Error Trapping Function Summary
Error Trapping Function Reference
Here's a quick reference of the available error trapping functions, in alphabetical
order.
iLine& = ERL 'last numbered line
Line& = ERL$ 'last named code block
Only the first 8 characters of the code block name will be retreived.
iError% = ERR 'gets error number
iError% = ERRClear 'gets error number AND clears ERR
ERRClear 'clear the error
ERROR 12 'generate error #12
Use error values 1-255.
desc$ = ERROR$ 'description of error
Function PBMain () As Long
On Error GoTo mistake ' mistake is a label name
f$ = InputBox$ "Filename?: ",,"") ' ask user for filename
Open "xx.xx" For Input as #1 ' error if not exist
a% = 5 ' executes if not error
Exit Function
mistake: ' on error, execution continues here
MsgBox Error$ ' error displayed
End Function
This code is discussed further up the page.
Resume Next 'continue at line following error
Resume label 'continue at specified line
Try
Open "xxx.xxx" For Input As #1
Catch
MsgBox "Error: xxx.xxx not found!"
Finally
MsgBox "no matter what"
End Try
This code is discussed further up the page
If you have any suggestions or corrections, please let me know.