ON ERR CALL

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.

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.

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

Once an error-handling project is installed, 4D calls the method each time an error occurs.

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 more information, see the section Syntax Errors (1 -> 81) or QR GET TOTALS SPACING. 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 and Error line system variables which contain, respectively, the name of the method and the line number where the error occurred (see Error, Error method, Error line).

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

• The 4D database engine; for example, when saving a record tries to duplicate a unique index key.
• The 4D environment; for example, when you do not have enough memory for allocating an array.
• The operating system on which the database is runs; 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.

ON ERR CALL is usually placed in the startup database method of an application, in order to handle errors for this application. ON ERR CALL can also be placed at the start of a method in order to handle errors specific to this 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 section Arrays and Memory.

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: