ON ERR CALL

Home

4D v16.3

ON ERR CALL


ON ERR CALL ( errorMethod )

Parameter	Type	Description
errorMethod	String	Error method to be invoked, or Empty string to stop trapping errors

Description

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 64-bit 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.

Example 1

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:

  //Create doc project method

  //Create doc ( String ; Pointer ) -> LongInt

  //Create doc ( DocName ; ->DocRef ) -> Error code result

 

 gError:=0

 ON ERR CALL("IO ERROR HANDLER")

 $2->:=Create document($1)

 ON ERR CALL("")

 $0:=gError

The IO ERROR HANDLER project method is listed here:

  //IO ERROR HANDLER project method

 gError:=Error //just copy the error code to the process variable gError

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:

  // ...

 C_TIME(vhDocRef)

 $vlErrCode:=Create doc($vsDocumentName;->vhDocRef)

 If($vlErrCode=0)

  //...

    CLOSE DOCUMENT($vlErrCode)

 Else

    ALERT("The document could not be created, I/O error "+String($vlErrCode))

 End if

Example 2

See example in the Arrays and Memory section.

Example 3

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:

  ` Do NOT forget to initialize the array at the beginning

  ` of the process method (the project method that runs the process)

 ARRAY STRING(63;asErrorMethod;0)

Here is the custom ON ERROR CALL method:

  ` ON ERROR CALL project method

  ` ON ERROR CALL { ( String ) }

  ` ON ERROR CALL { ( Method Name ) }

 

 C_STRING(63;$1;$ErrorMethod)

 C_LONGINT($vlElem)

 

 If(Count parameters>0)

    $ErrorMethod:=$1

 Else

    $ErrorMethod:=""

 End if

 

 If($ErrorMethod#"")

    C_LONGINT(gError)

    gError:=0

    $vlElem:=1+Size of array(asErrorMethod)

    INSERT IN ARRAY(asErrorMethod;$vlElem)

    asErrorMethod{$vlElem}:=$1

    ON ERR CALL($1)

 Else

    ON ERR CALL("")

    $vlElem:=Size of array(asErrorMethod)

    If($vlElem>0)

       DELETE FROM ARRAY(asErrorMethod;$vlElem)

       If($vlElem>1)

          ON ERR CALL(asErrorMethod{$vlElem-1})

       End if

    End if

 End if

Then, you can call it this way:

 gError:=0

 ON ERROR CALL("IO ERRORS") ` Installs the IO ERRORS error-handling method

  ` ...

 ON ERROR CALL("ALL ERRORS") ` Installs the ALL ERRORS error-handling method

  ` ...

 ON ERROR CALL ` Deinstalls ALL ERRORS error-handling method and reinstalls IO ERRORS

  ` ...

 ON ERROR CALL ` Deinstalls the IO ERRORS error-handling method

  ` ...

Example 4

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

  //Show_errors_only 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