ON ERR CALL

version 3

ON ERR CALL (errorMethod)

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, 4th Dimension 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 theme Error codes. For more information, see the section Syntax Errors or Database Engine Errors. 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.

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 4th Dimension database engine; for example, when saving a record tries to duplicate a unique index key.

• The 4th Dimension 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, 4th Dimension 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, 4th Dimension 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.

When an ON ERR CALL error-handling method is installed, it is not possible to trace a method by using Alt+Click (on Windows) or Option-Click (on Macintosh). This is because Alt+Click and Option-Click) generate an error (error code 1006) that immediately activates the ON ERR CALL error-handling method. However, you can test this error code by calling TRACE.

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
   

2. See example in the section Arrays and Memory.

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 ELEMENT(asErrorMethod;$vlElem)
      asErrorMethod{$vlElem}:=$1
      ON ERR CALL($1)
   Else 
      ON ERR CALL("")
      $vlElem:=Size of array(asErrorMethod)
      If ($vlElem>0)
         DELETE ELEMENT(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
      ` ...

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

ABORT, Method called on error.