Types of Exception Handlers

Types of Exception Handlers

This topic provides an overview of the exception handler types provided for both OPM and ILE programs. As shown in Figure 1, this is the top layer of the exception message architecture. ILE provides additional exception-handling capabilities when compared to OPM.

For OPM programs, HLL-specific error handling provides one or more handling routines for each call stack entry. The appropriate routine is called by the system when an exception is sent to an OPM program.

HLL-specific error handling in ILE provides the same capabilities. ILE, however, has additional types of exception handlers. These types of handlers give you direct control of the exception message architecture and allow you to bypass HLL-specific error handling. The additional types of handlers for ILE are:

• Direct monitor handler
• ILE condition handler

To determine if these types of handlers are supported by your HLL, refer to your ILE HLL programmer’s guide.

Direct monitor handlers allow you to directly declare an exception monitor around limited HLL source statements. For ILE C, this capability is enabled through a #pragma directive. ILE COBOL does not directly declare an exception monitor around limited HLL source statements in the same sense that ILE C does. An ILE COBOL program cannot directly code the enablement and disablement of handlers around arbitrary source code. However, a statement such as

ADD a TO b ON SIZE ERROR imperative

is internally mapped to use the direct monitor mechanism despite being an HLL-specific handler. Thus, in terms of the priority of which handler gets control first, such a statement-scoped conditional imperative gets control before the ILE condition handler (registered through CEEHDLR). Control then proceeds to the USE declaratives in COBOL.

ILE condition handlers allow you to register an exception handler at runtime. ILE condition handlers are registered for a particular call stack entry. To register an ILE condition handler, use the Register a User-Written Condition Handler (CEEHDLR) bindable API. This API allows you to identify a procedure at runtime that should be given control when an exception occurs. The CEEHDLR API requires the ability to declare and set a procedure pointer within your language. CEEHDLR is implemented as a built-in function. Therefore, its address cannot be specified and it cannot be called through a procedure pointer. ILE condition handlers may be unregistered by calling the Unregister a User-Written Condition Handler (CEEHDLU) bindable API.

OPM and ILE support HLL-specific handlers. HLL-specific handlers are the language features defined for handling errors. For example, the ILE C signal function can be used to handle exception messages. HLL-specific error handling in RPG includes the ability to handle exceptions for a single statement (E extender), a group of statements (MONITOR), or an entire procedure (*PSSR and INFSR subroutines). HLL-specific error handling in COBOL includes USE declarative for I/O error handling and imperatives in statement-scoped condition phrases such as ON SIZE ERROR and AT INVALID KEY.

Exception handler priority becomes important if you use both HLL-specific error handling and additional ILE exception handler types.

Figure 1 shows a call stack entry for procedure P2. In this example, all three types of handlers have been defined for a single call stack entry. Though this may not be a typical example, it is possible to have all three types defined. Because all three types are defined, an exception handler priority is defined. The figure shows this priority. When an exception message is sent, the exception handlers are called in the following order:

1. Direct monitor handlers

   First the invocation is chosen, then the relative order of handlers in that invocation. Within an invocation, all direct monitor handlers; RPG (E), MONITOR, INFSR, and error indicators; and COBOL statement-scoped conditional imperatives get control before the ILE condition handlers. Similarly, the ILE condition handlers get control before other HLL-specific handlers.

   If direct monitor handlers have been declared around the statements that incurred the exception, these handlers are called before HLL-specific handlers. For example, if procedure P2 in Figure 1 has a HLL-specific handler and procedure P1 has a direct monitor handler, P2’s handler is considered before P1’s direct monitor handler.

   Direct monitors can be lexically nested. The handler specified in the most deeply nested direct monitor is chosen first within the multiply nested monitors that specify the same priority number.

2. ILE condition handler

   If an ILE condition handler has been registered for the call stack entry, this handler is called second. Multiple ILE condition handlers can be registered. In the example, procedure P5 and procedure P6 are ILE condition handlers. When multiple ILE condition handlers are registered for the same call stack entry, the system calls these handlers in last-in-first-out (LIFO) order. In general, HLL-specific handlers have the lowest priority, after direct monitor handlers and condition handlers. Exceptions are the HLL-specific handlers mentioned in the discussion of direct monitor handlers.

3. HLL-specific handler

   HLL-specific handlers are called last.

The system ends exception processing when an exception message is modified to show that it has been handled. If you are using direct monitor handlers or ILE condition handlers, modifying the exception message is your responsibility. Several control actions are available. For example, you can specify handle as a control action. As long as the exception message remains unhandled, the system continues to search for an exception handler using the priorities previously defined. If the exception is not handled within the current call stack entry, percolation to the previous call stack entry occurs. If you do not use HLL-specific error handling, your ILE HLL can choose to allow exception handling to continue at the previous call stack entry.

Figure 1. Exception Handler Priority