Error Trapping
The PowerBASIC philosophy of generating tight, fast code has resulted in elimination of much (but not all) automatic error trapping. Trapping means detecting when an error occurs, providing error information to the program, running designated code in response to the program and preventing the program from termination early.

The 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.

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.

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.
  • 0 - no error
  • 5 - illegal function call
  • 6 - overflow
  • 7 - out of memory
  • 9 - subscript/pointer out of range
  • 11 - division by zero
  • 24 - device time-out
  • 51 - internal error
  • 52 - bad file name/number
  • 53 - file not found
  • 54 - bad file mode
  • 55 - file already open
  • 57 - device I/O error
  • 58 - file already exists
  • 61 - disk full
  • 62 - input past end
  • 63 - bad record number
  • 64 - bad file name
  • 67 - too many files
  • 68 - device unavailable
  • 69 - COMM error
  • 70 - permission denied
  • 71 - disk not ready
  • 72 - disk media error
  • 74 - rename across disks
  • 75 - path/file access error
  • 76 - path not found
  • 99 - object error
  • 241 - global memory corrupt
  • 242 - string space corrupt

Error Trapping Function Summary

Error Trapping Function Reference
Here's a quick reference of the available error trapping functions, in alphabetical order.

If you have any suggestions or corrections, please let me know.