This tutorial shows you how to use the exception handling mechanism available in the COBOL Base Class Library.
This tutorial uses Micro Focus alternatives and extensions to the ISO 2002 OO COBOL syntax.
This tutorial contains the following sessions:
An object raises an exception when it has trapped an error. The objects in the supplied class libraries define approximately ninety exception conditions altogether.
The ExceptionManager class provides most of the logic for actually handling exceptions, including a default exception handler. The default exception handler displays an error message and shuts down the application when an object raises an exception, but an application can define its own exception handlers and attach them to individual classes or objects to redefine their behavior.
An object raises an exception by sending itself the "raiseException" message, passing an error number as a parameter. The Base class implements the "raiseException" method, so it is inherited by all objects.
The error number is used to identify a message from an error file; it is also passed to an exception handler for the object if one is registered.
We will use the Bank application introduced in the previous tutorial to show you how to raise and trap exceptions. When an account object traps an error, it responds by raising an exception. For example, attempting to open a high rate account with an initial balance of less than $1000 is an error condition.
To debug exception raising code:
Next you find the methods in the HighRateAccount class we want to step through, and set breakpoints on them.
Control passes from the Debugger to the application.
The execution point is on the first statement of the "openAccount" method.
The test succeeds. The HighRateAccount class has detected an exception condition.
The Account class registers a message file account.err the first time you create a new account (you can see the code which does this in the "setNextAccountNumber" method of the Account class). This contains error messages for the default exception handler to display. The registration allocates a range of error numbers to be used for account errors.
The "queryMessageFile" message returns a numeric offset, giving the start of the range of error numbers.
The actual error number is defined by the level-78 data item, insufficientFundsForAccount, which matches the error number in the error file. A real application is likely to consist of classes from many sources, each of which has its own set of error messages.
Adding the offset for the account error messages file (returned in the previous step) to the error number produces a unique error number from which the exception handler can identify both the error file and the message number.
This statement raises the exception.
When you send the "raiseException" message, the "raiseException" method in Base gets executed. This looks to see if this object has an exception handler registered.
In this case, there is an exception handler registered for HighRateAccount objects, which displays a message box flagging the error.
Execution halts at the breakpoint on the exit method statement at the end of "openAccount". Execution always resumes at the point following the statement which raised the excepton, unless your exception handler closes down the application with a Stop Run statement (this is what the default exception handler does).
In this case the exception handler sets the object reference returned to null; the part of the application which requests new accounts checks the reference for a null value so that it knows whether the "openAccount" was successful or not.
In the next session we will look at how you can register an exception handler to provide different behavior for handling exceptions.
In the previous session, you saw how to raise an exception. This session shows you how you can register an exception handler for an object. An exception handler is a method that receives the exception number and the object raising the exception as parameters.
You can register an exception handler for a class or an instance object. If you register an exception handler against a class, then it is invoked for exceptions raised by all instances of the class as well as by the class itself.
Exception handler registration is a two-step process:
Next you will debug the code which sets exception handlers for the Account classes in the Bank application.
To debug the exception registration code
Execution halts on the breakpoint.
This creates the Callback for the exception handling method, "onExceptionAccountError", which is a method of self (the BankApplication instance).
This registers accountErrorMethod (the Callback for "accountError" in the BankApplication class) as an exception handler for the Account class. Any exceptions raised by the Account class or instances of the Account class will be passed to this method.
These register the same exception handler for exceptions raised by the other account classes.
You have completed this section of the tutorial. Leave the Debugger in its current state as the next section carries on directly from this one.
This section of the tutorial shows you how to write an exception handler method to deal with exceptions raised by an object. We will look at the exception handler the Bank application uses for dealing with exceptions from the account classes.
In the case of a failure to open a High Rate Account, the exception handler returns a null object handle to the "openAccount" method. The "openAccount" method code in the HighRateAccount class then returns the null object handle from the exception handler in place of a valid handle to an account object. The exception handler could be designed to do something else; for example, failure to open a High Rate Acount because of an insufficient initial investment could return a Savings Account instead.
Next you will debug the account exception handler. The following instructions assume that you are continuing this session directly from the previous one:
You can remove the Find bar when you have finished by clicking View > Find bar
set nullReference to null
and set a breakpoint.
The effect is that execution stops whenver the account exception handler is invoked.
The HighRateAccount class raises an exception, and the Debugger stops on the first statement of the exception handler.
The parameter nullReference is ultimately returned as the object reference to the account the application is attempting to create. As you step through the execution you can see the path by which this parameter is returned.
The exception handler needs to verify that the error number it has received is of a type it knows how to deal with. It starts by getting the offset for account errors.
If the offset of this error matches the offset returned from the ExceptionManager, then the difference will be a number which corresponds to one of the error numbers for bank accounts.
This statement is part of the mechanism by which the business logic which deals with accounts signals the interface with information.
The exception handler must now determine what type of exception has been raised in order to take the appropriate action. If the exception type isn't one it knows how to deal with, it reraises the exception (see the code below the When Other statement).
This is the exception which has been raised. The error numbers are all defined as level-78 data items in the copybook accinfo.cpy.
The Bank application displays a message box warning the user of the failure to create a new account.
Execution returns to the Exit Method of the HighRateAccount "openAccount" method. You can see that the statement which raised the exception has lsAccount as a returning parameter; this has been set to null by the exception method we just executed.
The execution point is now on an End-Evaluate statement, back in the "onSignalOpenAccount" method of BankApplication. This code is aware of the possibility that an account may not have been created, and tests to see whether the object reference for the new account is null. If it is, execution jumps to the end of this method.
When you build exception handling into an application, you have to remember that if you trap an exception successfully, execution will eventually resume at the same point it would have done if there had been no exception. Consequently, at points where an exception is possible your code must be able to check whether or not an exception has occurred. Checking whether you have been returned a null reference is one technique you can use.
You have now completed the tutorial on exception handling. You can stop the Debugger at any time.
In this tutorial you learned how to:
Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.