The ON ERR CALL command installs the project method, whose name you pass in errorMethod, as the method for catching (trapping) errors. This project method is called the error-handling method or error-catching method.

Once an error-handling project is installed, 4D calls the method each time an error occurs during the execution of a 4D language command.

The scope of this command is the current process. You can have only one error-handling method per process at a time, but you can have different error-handling methods for several processes.

Notes:

• In the context of the use of components, this command applies to the current database only. If an error is generated from a component, errorMethod is not called in the host database. 
• If ON ERR CALL is called from a process for which you requested preemptive execution (in compiled mode), the compiler checks whether errorMethod is thread-safe and returns errors if it is not compatible with the preemptive mode. For more information, refer to the Preemptive 4D processes section.

To stop the trapping of errors, call ON ERR CALL again and pass the empty string in errorMethod.

You can identify errors by reading the Error system variable, which contains the code number of the error. Error codes are listed in the Error Codes theme. For example, you can see the section Syntax Errors (1 -> 81). The Error variable value is significant only within the error-handling method; if you need the error code within the method that provoked the error, copy the Error variable to your own process variable. You can also access the Error method, Error line and Error formula system variables which contain, respectively, the name of the method, the line number and the text of the formula where the error occurred (see Error, Error method, Error line).

You can use the GET LAST ERROR STACK command to obtain the error sequence (i.e., the error "stack") at the origin of the interruption.

The error-handling method should manage the error in an appropriate way or present an error message to the user. Errors can be generated during processing performed by:

• The 4D database engine; for example, when saving a record causes the violation of a trigger rule.
• The 4D environment; for example, when you do not have enough memory for allocating an array.
• The operating system on which the database is run; for example, disk full or I/O errors.

The ABORT command can be used to terminate processing. If you don’t call ABORT in the error-handling method, 4D returns to the interrupted method and continues to execute the method. Use the ABORT command when an error cannot be recovered.

If an error occurs in the error-handling method itself, 4D takes over error handling. Therefore, you should make sure that the error-handling method cannot generate an error. Also, you cannot use ON ERR CALL inside the error-handling method.

The following project method tries to create a document whose name is received as parameter. If the document cannot be created, the project metod returns 0 (zero) or the error code:

The IO ERROR HANDLER project method is listed here:

Note the use of the gError process variable to get the error code result within the current executing method. Once these methods are present in your database, you can write:

See example in the Arrays and Memory section.

While implementing a complex set of operations, you may end up with various subroutines that require different error-handling methods. You can have only one error-handling method per process at a time, so you have two choices:
- Keep track of the current one each time you call ON ERR CALL, or
- Use a process array variable (in this case, asErrorMethod) to “pile up” the error-handling methods and a project method (in this case, ON ERROR CALL) to install and deinstall the error-handling methods.

You must initialize the array at the very beginning of the process execution:

Here is the custom ON ERROR CALL method:

Then, you can call it this way:

The following error-handling method ignores the user interruptions and displays the error text: