4D v14.3

ON ERR CALL

Home

 
4D v14.3
ON ERR CALL

ON ERR CALL 


 

ON ERR CALL ( errorMethod ) 
Parameter Type   Description
errorMethod  String in Error method to be invoked, or Empty string to stop trapping errors

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.

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

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:

  ` 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

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:

  ` 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
  ` ...

The following error-handling method ignores the user interruptions:

  ` SHOW ONLY ERRORS project method
 If(Error#1006)
    ALERT("The error "+String(Error)+" occurred.")
 End if

 
PROPERTIES 

Product: 4D
Theme: Interruptions
Number: 155

 
HISTORY 

Created: < 4D v6
Modified: 4D v12

 
SEE ALSO 

ABORT
Method called on error
System Variables

 
ARTICLE USAGE

4D Language Reference ( 4D v12.4)
4D Language Reference ( 4D v14 R3)
4D Language Reference ( 4D v14 R2)
4D Language Reference ( 4D v13.5)
4D Language Reference ( 4D v14.3)
4D Language Reference ( 4D v14 R4)

Parent of : ON ERR CALL ( 4D v11 SQL Release 6)