BBj Custom Objects Tutorial: Program #4 - Error Handling

Example Programs

Here are some example BBj programs. Each example is designed to demonstrate some aspect of using Custom Object Classes in BBj.

The complete source code for each program is included in an appropriately named sub-folder in the zip file you can download here.

Program #4: Error Handling

Let’s take a look at a BBj program that demonstrates how to do error handling in class methods. In this example, we will use seterr both outside of the class as well as inside of a class method, and examine the differences in error handling behavior that result. We will also use the throw verb to throw a specific error. Here is the code:

Program 4. Handling Errors in the FileUtilities Class

As the developer, we need to define the FileUtilities class, which we do in the new ErrorHandling.src file above. For the sake of demonstration, in this example we leave the class definition in the same file as the running code. This helps to demonstrate the SETERR behavior.

Execution

Creating the BBj source file and then running Program 4 (the code in ErrorHandling.src) resulted in the following SysConsole output:

Figure 4. The Output from Program 4

Observations

There are some details worth noticing about this code.

  • Program 4 makes two attempts to open a file that does not exist (nonExistentFileName.txt, whose name is stored in the filename$ variable). On each pass, the FileUtilities.openFile() method fails, as expected. The difference between the two passes is whether or not fileOpenError, defined inside of that method, is set as an error handler.

  • When fileOpenError, defined inside of the FileUtilities.openFile() method, is set as an error handler, it handles the error when:

    • It throws an arbitrary error (in this case, #12) with custom text. This allows openFile() to return nearly any information it has available to the calling routine. By using throw, a program can cause an error to occur programmatically. This allows you to specify the error number as well as the error message that is returned to the caller.

    • That error is caught by the errorHandler code that exists outside of the class, in the calling code.

    • The errorHandler code “handles the error” (in this case, it merely prints out information about the problem), and then uses BBj’s retry verb to have it try the same code again.

      NOTE: If nothing has changed in the code or in the execution environment, using retry can cause an infinite loop. In this code, what changes is the #passNumber in the openFile() method. Because #passNumber has been incremented, openFile() will execute different code on the second pass.

  • On the second pass, when fileOpenError is NOT set as an error handler, the error:

    • Stops the program and “drops to a SysConsole”. This occurs by default when there is no error handler set inside the method itself.

    • You can change this default behavior by using the setopts verb to disable Byte 1, Bit $08$. This is true because invoking a custom object class method is essentially the same as calling a public program in BBj.

    • If Byte 1, Bit $08$ is not set, attempting to enter console mode from a public program results in an error. This error would be handled by the errorHandler, in the same manner as the arbitrary error #12 thrown in fileOpenError.

    • Notice that the first line of output in the SysConsole in Figure 4 shows that the $08$ bit in byte 1 of the opts variable is (by default) enabled.

    • The seterr verb is available within a custom object method. The effect of a seterr within a method is similar to the effect of a seterr in a called program. The seterr remains in effect until the method returns.

    • The seterr verb is available inside of custom object methods. The effect of using seterr within a method is similar to the effect of using seterr in a called program. In the case of a custom object class method, the seterr remains in effect until that method returns.

Next Step: Example Program #5

BBj Custom Objects Tutorial Contents

BBj Custom Objects Tutorial: Introduction

BBj Custom Objects Tutorial: Interfaces

BBj Custom Objects Tutorial: Classes

BBj Custom Objects Tutorial: Fields

BBj Custom Objects Tutorial: Methods

BBj Custom Objects Tutorial: Using Custom Objects

BBj Custom Objects Tutorial: Program #1 - Writing a Check

BBj Custom Objects Tutorial: Program #2 - Protected and Private Fields

BBj Custom Objects Tutorial: Program #3: The Static Keyword

BBj Custom Objects Tutorial: Program #4 - Error Handling

BBj Custom Objects Tutorial: Program #5 - Class Inheritance

BBj Custom Objects Tutorial: Program #6 - Callback Choices

BBj Custom Objects Tutorial: Program #7 - Constructors and Field Initialization