Creating an Exception Handler

In most cases, you will want to take some action other than the default when a system exception occurs. To do this, you must define and arm an exception handler.

An exception handler is a method that can have the following signature.

method-name(e: Exception-class; [other-optional-parameters]): Integer;

In this signature, the e parameter refers to the exception object created and passed when the exception was raised.

You can optionally specify other parameters when you are creating or arming a method handler to suit your requirements, but you must specify the parameter that refers to the exception object as the first parameter.

The exception handler would normally use information saved in the Exception class object to decide the action to be taken. Within your method, you can use the isKindOf method to determine the class of the exception object.

An exception handler can also have the following signature.

method-name(exObj: any-exception-class; [other-parameters]): Integer;

In this signature, the exObj parameter indicates that this exception handler handles only exceptions that are instances of the specified exception class or its subclasses. You could specify o and i optional parameters, for example, to indicate the current object and an integer variable, respectively.

In these exception handler method signatures, the e or exObj parameter must be the first parameter that you specify in the exception handler method signature.

The contents of the parameter expressions passed to the exception handler method are evaluated as follows.

The return value indicates the action that the system then takes, as shown in the following table.

Return Value Constant Action
0 Ex_Continue Continues execution from the next expression after the expression that caused the exception.
   

Use this return mode only in circumstances when you are certain that continuing the code execution will still be correct after ignoring the exception

For lock exceptions, use this return mode only if the lock has been successfully retried. If the exception occurred while updating, ensure that the transaction has not been aborted by the exception handler.

1 Ex_Abort_Action Causes the current action to be aborted. The execution stack is stripped back and in most cases, the application reverts to an idle state in which it is waiting for user input or some other Windows event (see the note following this table).
2 Ex_Resume_Next Passes control back to the method that armed the exception handler. Execution resumes from the next statement after the evaluation of the method call or expression in which the exception occurred. If there were no messages on the execution stack when the handler was armed, the effect of the Ex_Resume_Next call is identical to that of the Ex_Abort_Action call.
   

If an exception occurs during evaluation of a return expression, when the exception handler returns, the executing method is terminated (in accordance with executing a return instruction) and the default value of the return type is returned.

3 Ex_Resume_Method_Epilog

Passes control back to the method that armed the exception handler. Execution resumes at the start of the method epilog or at the end of the method if there is no epilog section. Execution resumes at the next statement in the epilog if the exception was raised while executing the epilog. If there were no messages on the execution stack when the handler was armed, the effect of the Ex_Resume_Method_Epilog call is identical to that of the Ex_Abort_Action call.

If an exception occurs during evaluation of a return expression, when the exception handler returns, the executing method is terminated (in accordance with executing a return instruction) and the default value of the return type is returned.

-1 Ex_Pass_Back

Passes control back to the prior local exception handler for this type of exception or if a local handler is not found, a global exception handler for this type of exception.

If neither a local nor a global handler is found, the default exception handler is invoked on a client. On the server, it passes the exception back to the client node.

Trying to continue a non-continuable exception causes a further exception 1238 (Exception handler invalid return code) to be raised. If this exception is caught by an exception handler that then tries to continue the exception, an exception 1239 (Nested exceptions limit exceeded) is eventually raised, due to repeated 1238 exceptions. Your exception handlers should therefore test to see if an exception is continuable or not before attempting to return Ex_Continue. Your exception handler should also include checks to see if it is in a nested exception situation. It may also be beneficial to specifically check for the 1238 exception.

If an exception occurs and an exception handler method catches the exception and does an Ex_Resume_Next, the stack is cut back to the method that armed the exception handler and execution continues normally from this point.

However, if a second exception that is also handled by an exception handler that does an Ex_Resume_Next occurs while the stack is being cut back, after the stack has been cut back to the method that armed this (second) exception handler, the cutting back of the stack continues to the method that armed the first exception handler.

Any database transaction that is in progress is not aborted. You must explicitly code an abortTransaction instruction within the exception handler if the database transaction in progress is also to be aborted.

If an exception occurs while executing a server method and no user exception handlers are armed, the default handler is invoked on the server node. This aborts any current transaction on the server and passes a 1205 exception back to the client node.

You can use the methods listed in the following table in your exception handlers.

Class Method Description
Exception logExceptionHistory Enables you to log the exception stack history in an exception handler to the specified file
Exception logProcessHistory Enables you to log the call stack history in an exception handler to the specified file
Exception logSelf Appends a description of the exception object to the specified file
JadeMethod getSourceLine Returns the line of Jade code that contains the specified source position, to provide diagnostics during Jade development in your user exception handlers
MethodCallDesc logSelf Enables you to log diagnostic information from an exception handler

For details, see Chapter 1 of the Encyclopaedia of Classes.

The following is an example of a log file containing output from the exception logging methods.

                        thelibrary.log
 Unhandled SystemException on 2018/01/23 12:57:49 by [187.13] pid 0346c, tid 1684
Computer= WILBUR1A, Application= TheLibrary, Schema= TheLibrary
  SystemException: 1048 (not continuable, resumable)
*  Update outside transaction
  Error object: Address/3798.1
  Caused By:
     Receiver: Address/3798.1
     Method: Address::loadAddress(117) --  adrLine1  := ad1.trimBlanks ;
     // copy the values passed from the form
Call Stack History:
  <<Address/3798.1>> Address::loadAddress(117) --  adrLine1  := ad1.trimBlanks ;
  // copy the values passed from the form
  <<JadeScript/107.1 (t)>> editTester(396) --  adr.loadAddress
___________________________________________________________________________________
Exception:- Type: SystemException; Error Code: 1048 on 2018/01/23 12:57:49 
*** User ABORTED current action and database transaction ***
___________________________________________________________________________________