Programming with ON ERROR
Proper use of ON ERROR adds polish to a dBASE III PLUS system, and is
an essential ingredient in network applications.
By Chuck Litzell, Phil Talsky and Mark Ware
The fact that an error occurs in a dBASE III PLUS program doesn't
necessarily mean that anything is wrong. Errors can be used to
communicate with the program's environment. Local area networks
(LANs) are the best example of this. An error will occur if you
attempt to access a record or file that is locked by another
user. There is no way to know about the lock until you attempt
the access, so this is a type of "error" that you can expect will
occasionally occur and you must be prepared to handle it. Even if
you aren't writing a program to run on a LAN, it's a good idea to
allow for the possibility of errors, because errors are always
The ON ERROR command, with a few related commands and functions,
makes it possible to install a centralized error-handling routine
that kicks in whenever an error occurs. What's more, the routine
can be intelligent, handling some errors without the user ever
knowing they happened. Even when an unrecoverable error does
occur, an error-handling routine can provide useful information
and advice before the program terminates so that the user can
take steps to correct the error.
Nearly every command in dBASE III PLUS has the potential to
produce an error. A list of errors can be found in Chapter 7 of
Using dBASE III PLUS. Additional errors that apply only to the
dBASE III PLUS ADMINISTRATOR are listed in the Network Appendices
section of Programming with dBASE III PLUS. Errors have error
numbers, shown in square brackets in the listings. Figure 1 lists
errors in numeric order, including errors that were not included
in some versions of the documentation.
The Default Error-Handler
dBASE III PLUS has a default error-handling routine to which you
have certainly been introduced. When an error occurs, the default
routine displays a message like
File does not exist.
Called from - C:NOPROG.prg
Cancel, Ignore, Suspend?
The first line, "File does not exist." is an error message,
which you can find in the error listings referenced above. The
next line has a question mark, positioned above and to the right
of the part of the command that caused the error. If the error
occurred while a program was executing (as opposed to a statement
entered at the dot prompt) a list of the programs that were
active when the error occurred is displayed on the next lines,
followed by the familiar "Cancel, Ignore, Suspend?" prompt. The
user must then make a decision.
The default error-handler assumes that the user has enough
familiarity with dBASE III PLUS to understand the consequences of
each of the three options. Many users are more comfortable with
the three-finger option that isn't listedCtrl-Alt-Del-which
reboots the computer. This is unquestionably the worst thing they
could do, possibly leading to lost or damaged data.
With a customized error-handling routine, your program can be
much more helpful to the user when an error occurs. You can, to a
degree, diagnose the problem and sometimes correct it without
terminating the program. If it isn't possible to recover from
within the program, you can at least display a helpful,
instructive error message. Then the user understands what is
wrong and what steps are needed to correct the situation. For
instance, the error message above might instead become
WARNING! A Program Exception has Occurred.
Code 1: File does not exist.
An essential file appears to be missing. First, try running the
program again. If this message appears a second time, RESTORE
yesterday's backup and try a second time. If the problem
persists, contact O. McDonald, programmer, at (213) 555-3732.
Press Any Key to Return to DOS
This message describes the problem, offers advice on how to deal
with it, and then returns control to DOS. No choices need to be
Establishing an Error-Handling Routine
The ON ERROR command activates an error-handling routine. The
syntax for the command is
ON ERROR should be executed at the beginning of the highest-level
program before any statements that could result in an error. Any
dBASE III PLUS command can be substituted in place of .
Thereafter, whenever an error occurs, the specified command is
executed, much as if it were inserted into the program at the
line where the error occurred. The only command that really makes
much sense is
ON ERROR DO Errprg
where Errprg.PRG is a program you have written to handle the
The default error-handler can be reinstated by executing the ON
ERROR command with no parameter:
Error-Handling Program Strategies
When an error occurs, dBASE III PLUS stores the error number
internally. The ERROR() function makes that number available to
your program, and the MESSAGE() function makes available the
error message. This is a starting point for your error-handling
program. Figure 2 is an example of a very simple error-handling
program. It uses the ERROR() and MESSAGE() functions to tell the
user something is wrong, then QUITs dBASE III PLUS.
The RETRY command is specifically provided for use in
error-handling programs. In a way similar to the RETURN command,
RETRY returns control from the current program to the program
from which it was called. The difference between RETRY and RETURN
is that RETRY returns control to the program statement that
called the subprogram, and RETURN gives control to the statement
following the statement which called the subprogram. RETRY can be
used in an error-handler with little or no diagnostics. You would
give the user an option to try again or cancel the application
program. Figure 3 is an error-handling routine that demonstrates
the use of RETRY.
If you use the RETRY command without some restrictions, it is
possible that your program will get into an infinite loop. The
error occurs, RETRY returns control to the same program line, the
error occurs again, RETRY again returns to the error-statement,
and so on. To avoid this you should always let the user decide
whether to RETRY.
In version 1.0 of dBASE III PLUS, RETRY always returns control to
the previous program file. This means that if RETRY is in a
procedure, and that procedure is called by another procedure in
the same procedure file, control is passed back from the
procedure file to the program above it. Figure 4 demonstrates
this anomaly, which was fixed in version 1.1.
Another RETRY anomaly was published in TechNotes in February
1987. "When a program contains ON ERROR RETRY or ON ERROR DO
and contains RETRY, the command line executed
by RETRY may be truncated when RETRYed." This anomaly occurs
infrequently. For more details, and a solution, see "Try RETRY
Again" in the December 1987 TechNotes.
An error-handling program can use a special form of the RETURN
command to reset the application program to its beginning. RETURN
TO MASTER returns control to the highest-level programthe one
that is executed from the dot prompt. The next statement to be
executed is the line following the line which called the
Using RETURN TO MASTER makes some assumptions about the design of
your application program. Often, the highest-level program is a
menu program that, based on the user's selection, calls
subprograms to perform specific tasks. If this is true of your
application, then using RETURN TO MASTER in your error-handling
program will put your application back in its main menu. If your
application consists of just one program, however, or if the
error occurs in the highest-level program, RETURN TO MASTER is
equivalent to RETURN. Control will be returned to the dot prompt.
Adding diagnostics to the error-handler is not a difficult step,
but it is complicated by the fact that dBASE III PLUS has over
100 trappable errors. One approach is to use a DO CASE...END CASE
structure to handle specific errors, and take care of the rest in
the OTHERWISE clause. Once you decide which errors are to receive
special treatment, the ERROR() function fits nicely into the DO
CASE structure in Figure 5.
Errprg3 (Figure 6) demonstrates this approach to error-handling.
You can extend this error-handler to treat other errors specially
by adding a CASE statement to the DO CASE structure.
Error-handling programs have the distinction of being generic;
once you develop one that works well it can be used in any
application program with little or no modification.