+---------------------------------+
|            ON ERROR             |
+---------------------------------+
ON ERROR [<command>]

-----------------------------------
Traps for error during program execution.
-----------------------------------

The ON ERROR command sets a trap for errors during program execution.
When an error occurs, the trap is triggered and the specified <command>
is executed.  An ON ERROR routine may be deactivated by issuing ON ERROR
without the <command>.

If the <command> is DO <program>, you may want to include the functions
ERROR(), MESSAGE(), LINENO() and/or PROGRAM() as parameters.  An error
routine can use the values passed by these functions to determine the
cause of the error, the error message, the line number and program name
where the error occurred.  These can be valuable when debugging a
program.

After the ON ERROR routine is completed, program execution resumes on
the line immediately following the line which caused the error.
However, if <command> is DO <program> and the <program> is exited via a
RETRY statement, execution resumes on the same line on which the error
occurred.

In FoxPro/LAN, the network version of FoxPro, an ON ERROR routine may be
used to trap for errors created when a command that attempts to lock a
record or file is unsuccessful.  If an ON ERROR routine is not in
effect, an alert is displayed indicating why the record or file lock was
unsuccessful (for example, "Record is in use by another.").  If an ON
ERROR routine is in effect, the alert isn't displayed and the ON ERROR
routine is executed.  Note that unsuccessful locking attempts by the
explicit locking functions (FLOCK(), LOCK() and RLOCK()) will never
trigger an ON ERROR routine or display an alert.  Instead these
functions return a logical true (.T.) or false (.F.) value depending on
the success of the lock attempt.

+---------------------------------+
|         Program Example         |
+---------------------------------+
ON ERROR DO errhand WITH ;
        ERROR(), MESSAGE(), MESSAGE(1), PROGRAM(), LINENO()

*** The next line should cause an error ***

USE nodatabase

PROCEDURE errhand
PARAMETER merror, mess, mess1, mprog, mlineno
? 'Error number: ' + LTRIM(STR(merror))
? 'Error message: ' + mess
? 'Line of code with error: ' + mess1
? 'Line number of error: ' + LTRIM(STR(mlineno))
? 'Program with error: ' + mprog

-----------------------------------

See Also:  ERROR(), LINENO(), MESSAGE(), PARAMETERS, PARAMETERS(),
PROGRAM(), ON READERROR, ON(), RETURN, RETRY, SYS(16) Executing program
name, SYS(2018) Error message

-----------------------------------