Handling Exceptions

In the absence of an exception handler, the default Unhandled Exception dialog is displayed when an exception is raised and the exception (including the method call stack history and the exception stack history) is written to the log file of your current application; for example, MyApp.log. This dialog provides details of the current exception, and buttons enabling you to:

Abort
Debug
Ignore (continue)

Pressing the Esc key is equivalent to clicking the Abort button.

The unhandled exception dialog and the logged unhandled exception details include the application and schema names. In addition, the logged exception details contain the computer name.

You can define an exception handler method to override the default exception handler.

When an invalid code is returned from an exception handler (for example, when resuming a non‑resumable exception or continuing a non-continuable exception), a 1238 (Exception Handler invalid return code) exception is raised.

When the maximum number of nested exceptions is reached (this limit is currently 20), an exception is raised. For this type of exception, no user exception handler is called but the defaultHandler method of the Exception class is invoked. This defaultHandler method is the "handler of the last resort", which is automatically invoked on the exception instance if no other exception handler consumes the exception. The exception, including the method call stack history and the exception stack history, is written to the log file of the current application.

Your exception handler should:

Test to see if an exception is continuable before attempting to return Ex_Continue.
Include checks to see if it is a nested exception situation.
Specifically check for the 1238 exception.

In client-side GUI applications, the defaultHandler method calls the Exception class showDialog method on self. If the showDialog method returns true, the defaultHandler method ignores the exception by returning the result of Ex_Continue.

It is not valid to ignore non-continuable exceptions. However, if the showDialog method returns false (indicating that the user clicked the Abort button), the defaultHandler method first aborts any current persistent or transient transaction and then terminates the current action by returning an Ex_Abort_Action result.

When the defaultHandler method is invoked for an exception raised in non‑GUI‑capable methods (including server methods, server application methods, and any non-GUI application methods), the defaultHandler method does not call the showDialog method but instead aborts any current persistent or transient transaction, logs the exception to the exception log file of the current application, and when invoked from a server method it returns Ex_Pass_Back; otherwise, it returns Ex_Abort_Action.

You can reimplement the defaultHandler method in your subclasses of the Exception class if you want different default behavior.

Your exception handlers that do not handle a specific exception should return Ex_Pass_Back rather than directly calling the defaultHandler method.

The Exception::showDialog method displays the default exception dialog. The showDialog method returns true if the user clicks the Ignore button in the default exception handler and the exception is continuable, otherwise this method returns false. The Ignore button is disabled if the exception is not continuable or if production mode is enabled for the database.

The showDialog method can be called from a user-defined exception handler and can be called by the defaultHandler method.

In situations where an Exception handler invalid return code exception is raised, the offending exception handler is not displayed because it has already finished its execution but the resumable and continuable properties of each exception on the exception stack is logged in the exception stack history section of the log file of your current application.

Each process can have up to 128 global exception handlers armed at any one time. However, there is no JADE-imposed restriction on the number of non-global exception handlers that can be armed at any time by any one process.

JADE does not allow resuming from global exception handlers, because there is no guarantee that the method that armed the exception handler is still in the call stack. Using Ex_Resume_Next in a global exception handler is equivalent to returning Ex_Abort_Action.

As the deletion of objects is atomic, transactions are aborted when exceptions are raised during automatic maintenance actions. If the attempt to commit a transaction after an exception occurs during a delete action (for example, user code in a delete, or destructor, method), the transaction is aborted if any user-defined exception handler does not do so. No objects are deleted after the exception.

When an exception occurs in a server method and no exception handler was armed on the server node for the exception, JADE performs the following actions.

The default exception handler is invoked for the exception. If this is a JADE exception handler, the application stack is written to the application log file but the corresponding dialog is not displayed.
An exception 1242 (A method executing in another node was aborted) is raised on the client node that invoked the server method execution. The extendedErrorText property of this exception contains the text that corresponds to the original server method exception.

To handle exceptions in server methods correctly, exception handlers can be armed in server methods themselves. These exception handlers can be local or global.

Global exception handlers armed in methods executing on the client node have effect on client exceptions only and global exception handlers armed in methods executing on the server node have effect only on the server node.

When an exception handler is invoked from a package method, the package context is switched to the context that was in effect when the exception handler was armed. When the exception handler finishes, the package context is adjusted back, if required.

See also "Default Exception Handler", later in this chapter. For a list of the global constants that you can use in your exception handlers, if required, see the JadeErrorCodesDatabase, JadeErrorCodesSDS, and JadeErrorCodesWebService global constants categories in Appendix A of your JADE Encyclopaedia of Classes.