Error Handling

A condition is assumed to be handled in PL/I when the ON-unit established for the condition completes execution without performing one of the following actions:

When the condition is handled, PL/I continues execution of the program at the point of interruption. Normal completion of any ON-unit (except ERROR signaled as the default action) results in return of control either to the statement that caused the condition or to the statement immediately following the statement that caused the condition. However, the effects of normal return from ERROR, FIXEDOVERFLOW, OVERFLOW, UNDERFLOW, and ZERODIVIDE are generally unpredictable. Exceptions are cases of ERROR that are specifically documented to allow normal return, and ON-units that execute as a result of a SIGNAL statement. Normal return from a CONVERSION condition that modifies ONCHAR or ONSOURCE pseudovariables causes the conversion to be retried.

In PL/I, an ON-unit can choose not to handle a condition and can request that, rather than returning control to the point of interruption, PL/I continue to search for another ON-unit to handle the condition. It does this by calling the RESIGNAL built-in subroutine as follows:

CALL RESIGNAL();

The RESIGNAL built-in subroutine has no arguments.

When an ON-unit calls RESIGNAL, PL/I resumes its search of the call stack starting at the call frame beneath the frame in which it located the current ON-unit. The next example and Figure 9.1, “Resignaling a Condition” illustrate the effect of the RESIGNAL built-in subroutine. The reverse numbers indicate the order of execution. Procedure B establishes an ANYCONDITION ON-unit that handles specific VAXCONDITION values. When the ON-unit is executed as a result of a signal in either procedure B or C, it tests the current value of ONCODE to see whether it is a value of interest. If not, procedure B calls RESIGNAL.

A: PROCEDURE OPTIONS(MAIN); ❶
       ON FIXEDOVERFLOW BEGIN;

       ⋮
       END;

       CALL B;
B: PROCEDURE (X,Y);  ❷
       ON ANYCONDITION BEGIN;
               IF (ONCODE() = SIGNAL_FOUND)!
                       (ONCODE() = SIGNAL_DONE) THEN
                       BEGIN;

               END; /*Begin block for IF statement */
               ELSE CALL RESIGNAL();
       END; /* ON-unit */
       CALL C;
C: PROCEDURE;  ❸

       ⋮/* FIXEDOVERFLOW signaled  ❹
       RETURN;
       END;

Figure 9.1, “Resignaling a Condition” illustrates the preceding example.

When the FIXEDOVERFLOW condition is signaled in procedure C, B calls RESIGNAL and PL/I continues its search of the call stack. It locates the ON-unit for handling the FIXEDOVERFLOW condition in procedure A and executes it.

Note that the default condition handling performed by PL/I uses the resignaling capability to continue signals that are not handled within the program. PL/I default condition handling is described in Section 9.5, “Search Path for ON-Units”.

An ON-unit in a PL/I procedure can execute a nonlocal GOTO statement that transfers control to a previous block. In this case, PL/I releases call frames, beginning with the call frame created for the ON-unit, until it reaches the block containing the label specified in the GOTO statement.

This removal of call frames from the call stack is called an unwind. The next example and Figure 9.2, “Unwinding the Call Stack” illustrates a situation in which an unwind occurs. The reverse numbers indicate the order of execution. The ERROR ON-unit established in procedure A receives control when the ERROR condition is signaled in procedure C. This ON-unit executes the GOTO PRINT_MSG statement. The label PRINT_MSG is in procedure A. Thus, the call stack is unwound and the call frames for the ON-unit, procedure C, and procedure B, in that order, are removed from the stack, and execution continues at the label PRINT_MSG.

A: PROCEDURE OPTIONS(MAIN); ❶
       ON ERROR GOTO PRINT_MSG;

       ⋮  ❹
       CALL B;
       PRINT_MSG;

       ⋮
B: PROCEDURE;  ❷

       CALL C;

       RETURN;
       END;
C: PROCEDURE;  ❸

       RETURN; /* ERROR signaled */
END;

Figure 9.2, “Unwinding the Call Stack” illustrates the preceding example.

When an unwind occurs in the UNIX environment, PL/I examines each call frame in the calling sequence to determine if a condition ON-unit exists for that frame. If so, PL/I calls the ON-unit with the condition value SS$_UNWIND, and the ON-unit has the chance to perform block- or procedure-specific cleanup operations.

You can use an ON-unit to terminate program execution. To do this, include a STOP statement in the ON-unit. For example:

ON UNDEFINEDFILE(INFILE) BEGIN;

       PUT EDIT('File ',ONFILE(),' undefined. Error ',ONCODE())
                       (A,X,A,X,A,X,F(10));
       STOP;
END;

The STOP statement performs the following actions:

Thus, when a FINISH ON-unit that has been executed as a result of a STOP statement handles the condition, control returns to the STOP statement, which then terminates the image.

If no FINISH or ANYCONDITION ON-unit exists, the program terminates.

Within a PL/I program the values for the UNIX signals are available in the following variables, each corresponding to one of the UNIX signals. For access to these variables, a program can GLOBALREF the variables. The standard include file, signaldef.in, contains the declarations for these variables. To include the signaldef.in file in your PL/I program, use the following statement:

%include $signaldef;

Table 9.1, “Corresponding Values” identifies the correspondence between UNIX signal numbers and the corresponding ONCODE value.

The numbers listed in Table 9.1, “Corresponding Values” for the ONCODE values are under program control. The values listed are the initial value for each of the signals. These numbers may be modified, if desired, by assigning a new value to the variable. Take care not to duplicate these signal numbers or they cannot be distinguished. These values should not be modified within a condition handler.

You may want to use your own number for the ONCODE value, if the numbers are used to identify a related error message.

The following program shows an example of how UNIX signals can be handled, and how the ONCODE values can be modified:

UNIXSIG: PROC OPTIONS( MAIN );

dcl sig$_usr1 fixed bin(31) globalref;
dcl sig$_int fixed bin(31) globalref;
dcl sig$_quit fixed bin(31) globalref;
/* set specific value for sig$_int */
sig$_int = 999999;

call mainloop();

/* set up anycondition handler to test for
* sig$_usr1, sig$_int and sig$_quit */
mainloop: proc;
on anycondition begin;
       if (oncode() = sig$_usr1) then
               PUT LIST ( 'mainloop: caught sigusr1 ',oncode());
       else if oncode() = sig$_int then
               PUT LIST ( 'mainloop: caught sigint ',oncode());
       else if oncode() = sig$_quit then
               PUT LIST ( 'mainloop: caught sigquit ',oncode());
       else call resignal();
       put skip;
end;

/* set up specific handler for sig$_usr2 */
on vaxcondition(sig$_usr2) begin;
       PUT LIST ( 'usr2: caught sigusr2 ',oncode());
       put skip;
end;

/* main loop processing starts here */
⋮
END;

In this example, specific handlers are set up for the UNIX signals SIGUSR1, SIGINT, SIGQUIT, and SIGUSR2. The first three are caught in the ANYCONDITION handler and the ONCODE is compared to the current values in the global variables sig$_usr1, sig$_int and sig$_quit. The signal SIGUSR2 is caught in a specific VAXCONDITION on units testing for sig$_usr2.

If PL/I entered a program at a procedure containing the MAIN option, PL/I searches for ON-units and performs default condition handling as follows:

If the call frame at which the program was entered did not specify the MAIN option, the default condition handling is:

The next example and Figure 9.4, “Search for an ON-Unit” illustrate a search for an ON-unit that will handle a decimal overflow condition. The reverse numbers indicate the sequence in which the search takes place.

A: PROCEDURE OPTIONS(MAIN);
       ON ERROR BEGIN;  ❹ /* ERROR signaled */

               ⋮ ❼ /* Execute ON-unit */
       END;
       CALL B;  ❸
       ⋮
B: PROCEDURE; ❻ /* Look for ERROR */
       ⋮
       CALL C;
       ⋮
       RETURN;  ❷
       END;

C: PROCEDURE; ❺ /* Look for ERROR */
       ⋮
       RETURN; ❶
       END;

Referring to the example above and Figure 9.4, “Search for an ON-Unit”, you can see that PL/I takes the following actions:

Searches the previous call frame (B)

If a second condition is signaled during the execution of an ON-unit, PL/I searches for an ON-unit that will handle the second condition, beginning in the call frame in which the second condition was signaled.

The next example and Figure 9.5, “Effect of Multiple Conditions” illustrate the search sequence followed when a second condition occurs during the execution of an ON-unit. The reverse numbers indicate the order of execution. The ERROR condition in procedure C is handled by the ON-unit established in procedure B. During the execution of this ON-unit, a FIXEDOVERFLOW condition is signaled. PL/I locates the ON-unit (shown in the Figure 9.5, “Effect of Multiple Conditions” as a box with dotted lines) established for FIXEDOVERFLOW conditions in procedure C and gives it control.

A: PROCEDURE OPTIONS(MAIN); ❶

       ⋮
       CALL B;

B: PROCEDURE;  ❷
       ON ERROR BEGIN;

       ⋮
       END;
       CALL C;

C: PROCEDURE;  ❸ /* Original ERROR signaled */  ❹
       ON FIXEDOVERFLOW BEGIN;

       ⋮
       END;

Figure 9.5, “Effect of Multiple Conditions” illustrates the preceding example.

Note that if the second condition is the same condition as the first, and the ON-unit does not establish another ON-unit, the same ON-unit will be executed repeatedly as the condition is signaled. A similar situation results when a STOP statement is executed within a FINISH or ANYCONDITION ON-unit; the program will enter an infinite loop when the STOP statement executes. The STOP statement signals FINISH, the current ON-unit is re-executed, the STOP statement is executed again, and so on.

In a PL/I program, an ANYCONDITION ON-unit or a VAXCONDITION ON-unit established specifically to handle the SS$_UNWIND condition is invoked during the unwind. The following example illustrates a VAXCONDITION ON-unit:

DECLARE SS$_UNWIND GLOBALREF VALUE FIXED BINARY(31);
ON VAXCONDITION(SS$_UNWIND) BEGIN;
       CLOSE FILE(DATA_REC_TEMP) ENVIRONMENT(DELETE('0'B));
       END;

Although it is not specifically resignaled, when an ON-unit that is handling the unwind condition completes execution, the unwind continues.

Note that when an ANYCONDITION ON-unit executes a nonlocal GOTO statement, the nonlocal GOTO causes an unwind, and the first ON-unit that is given control is the ANYCONDITION ON-unit itself. Thus, an infinite loop occurs. To avoid this situation, an ANYCONDITION ON-unit can contain the following lines:

ON ANYCONDITION BEGIN;
DECLARE SS$_UNWIND GLOBALREF VALUE FIXED;
IF ONCODE() = SS$_UNWIND THEN GOTO OKAY;
⋮
OKAY: END;

This check for the condition SS$_UNWIND ensures that if a nonlocal GOTO is executed in this ON-unit, it will not cause the ON-unit to be re-executed.

All UNIX-defined conditions have symbolic names associated with them. When thePL/I ONCODE built-in function is invoked in an ON-unit, it returns the value of the associated global symbol. This 32-bit status value describes the condition that was signaled. The low-order three bits of the status value contain the severity of the condition (success, warning, error, or fatal). Severity is important when no ON-unit exists for a condition, and default condition handling is performed by PL/I (see Section 9.5, “Search Path for ON-Units”). This number is program dependent.

All symbolic names associated with UNIX condition values are defined as system global symbols. Thus, you can declare the names for these values in a PL/I program using the GLOBALREF attribute, and refer to them symbolically. The linker will automatically locate the definitions of the symbols in the default system libraries when the procedure is linked. You can use the system global symbol names to refer to the values returned by the ONCODE built-in function in an condition-handling ON-unit.

Table 9.2, “ONCODE Values for PL/I ON Conditions” lists the PL/I keyword condition names and the UNIX global symbol names associated with each condition name.

The ONFILE built-in function returns the name of the file constant for which the current file-related condition was signaled. Its format is given in the Endless PL/I for POSIX Systems Reference Manual.

The ONFILE built-in function can be used in the following ON-units:

The returned value is a varying-length character string. If referenced outside an ON-unit or within an ON-unit that is executed as a result of a SIGNAL statement, the ONFILE function returns a null string.

The ONKEY built-in function returns the key value that caused the KEY condition to be signaled during an I/O operation to a file that is being accessed by key. Its format is given in the Endless PL/I for POSIX Systems Reference Manual.

This built-in function can be used in an ON-unit established for these conditions:

The returned key value is a varying-length character string. If referenced outside an ON-unit, or within an ON-unit executed as a result of the SIGNAL statement, the ONKEY built-in function returns a null string.