Error handling is the process of anticipating and responding to errors that might occur in your application. 4D provides a comprehensive support for catching and reporting errors at runtime, as well as for investigating their conditions.
Error handling meets two main needs:
- finding out and fixing potential errors and bugs in your code during the development phase,
- catching and recovering from unexpected errors in deployed applications; in particular, you can replace system error dialogs (disk full, missing file, etc.) with you own interface.
It is highly recommended to install an error-handling method on 4D Server, for all code running on the server. This method would avoid unexpected dialog boxes to be displayed on the server machine, and could log errors in a dedicated file for further analyses.
Error or status
Many 4D class functions, such as
transporter.send(), return a status object. This object is used to store "predictable" errors in the runtime context, e.g. invalid password, locked entity, etc., that do not stop program execution. This category of errors can be handled by regular code.
Other "unpredictable" errors include disk write error, network failure, or in general any unexpected interruption. This category of errors generates exceptions and needs to be handled through an error-handling method.
Installing an error-handling method
In 4D, all errors can be caught and handled in a specific project method, the error-handling (or error-catching) method.
This project method is installed for the current process and will be automatically called for any error that occurs in the process, in interpreted or compiled mode. To install this project method, you just need to call the
ON ERR CALL command with the project method name as parameter. For example:
ON ERR CALL("IO_ERRORS") //Installs the error-handling method
To stop catching errors and give back hand to 4D, call
ON ERR CALL with an empty string:
ON ERR CALL("") //gives back control to 4D
Method called on error command allows you to know the name of the method installed by
ON ERR CALL for the current process. It is particularly useful in the context of generic code because it enables you to temporarily change and then restore the error-catching method:
$methCurrent:=Method called on error ON ERR CALL("NewMethod") //If the document cannot be opened, an error is generated $ref:=Open document("MyDocument") //Reinstallation of previous method ON ERR CALL($methCurrent)
Scope and components
You can define a single error-catching method for the whole application or different methods per application module. However, only one method can be installed per process.
An error-handling method installed by the
ON ERR CALL command only applies to the running application. In the case of an error generated by a component, the
ON ERR CALL error-handling method of the host application is not called, and vice versa.
Handling errors within the method
Within the custom error method, you have access to several pieces of information that will help you identifying the error:
dedicated system variables(*):
Error(longint): error code
Error method(text): name of the method that triggered the error
Error line(longint): line number in the method that triggered the error
Error formula(text): formula of the 4D code (raw text) which is at the origin of the error.
(*) 4D automatically maintains a number of variables called system variables, meeting different needs. See the 4D Language Reference manual.
GET LAST ERROR STACKcommand that returns information about the current stack of errors of the 4D application.
Get call chaincommand that returns a collection of objects describing each step of the method call chain within the current process.
Here is a simple error-handling system:
//installing the error handling method ON ERR CALL("errorMethod") //... executing code ON ERR CALL("") //giving control back to 4D
// errorMethod project method If(Error#1006) //this is not a user interruption ALERT("The error "+String(Error)+" occurred". The code in question is: \""+Error formula+"\"") End if
Using an empty error-handling method
If you mainly want the standard error dialog box to be hidden, you can install an empty error-handling method. The
Error system variable can be tested in any method, i.e. outside of the error-handling method:
ON ERR CALL("emptyMethod") //emptyMethod exists but is empty $doc:=Open document( "myFile.txt") If (Error=-43) ALERT("File not found.") End if ON ERR CALL("")