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.

When the exception is armed for global exception handlers, as shown in the following example.

exampleMethod;
vars
    obj   : Object;
    thing : String;
begin
    obj   := global;
    thing := "very first time";
    on Exception do ehWithParameters(exception, thing, obj) global;
    thing := "first time";
    /* if an exception is caused by the following line of code, the
       thing parameter contains the value "very first time" and the
       obj parameter refers to global */
    m2;
    obj   := app;
    thing := "second time";
    /* if an exception is caused by the following line of code, the
       thing parameter contains the value "very first time" and the
       obj parameter refers to global */
    m2;
end;

For local exception handlers, at the moment that the exception occurs, as shown in the following example.

exampleMethod;
vars
    obj   : Object;
    thing : String;
begin
    obj   := global;
    thing := "very first time";
    on Exception do ehWithParameters(exception, thing, obj);
    thing := "first time";
    /* if an exception is caused by the following line of code, the
       thing parameter contains the value "first time" and the obj
       parameter refers to global */
    m2;
    obj   := app;
    thing := "second time";
    /* if an exception is caused by the following line of code, the
       thing parameter contains the value "second time" and the obj
       parameter refers to app */
    m2;
end;

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

___________________________________________________________________________________