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. In the case of UNDERFLOW, return from the default PL/I condition handler continues execution unpredictably, with an undefined value as the result of the operation that caused the condition (the value is set to zero only if the UNDERFLOW option is not enabled).

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. Example 10.1, “Resignaling the Condition” and Figure 10.1, “Resignaling a Condition” illustrate the effect of the RESIGNAL built-in subroutine. The callout numbers in the example indicate the order of execution.

Procedure B establishes an ANYCONDITION ON-unit that handles specific 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 ANYCONDDITION 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;❸

    ❹

   RETURN;
   END;

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 10.4, “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.

The removal of call frames from the call stack is called an unwind. Example 10.2, “Unwinding the Call Stack” and Figure 10.2, “Unwinding the Call Stack” illustrate a situation in which an unwind occurs. The callout numbers in the example indicate the order of execution.

Procedure A establishes an ERROR ON-unit represented by the box drawn with broken lines in Figure 10.2, “Unwinding the Call Stack”. 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;

   ❺

   END;

B: PROCEDURE;❷

   CALL C;

   RETURN;
   END;

C: PROCEDURE;❸

   RETURN;
   END;

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

An ON-unit can specify that the program is to be terminated by executing a STOP statement. 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 is terminated.

Note that when a FINISH or ANYCONDITION ON-unit executes a STOP statement, the program enters an infinite loop.

If the program was entered at a procedure with 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 as follows:

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

PL/I takes the following actions:

A: PROCEDURE OPTIONS(MAIN);

   ❹


   ON ERROR BEGIN;  ❼

     PUT SKIP LIST ('Caught the ERROR condition - in main');
   END;

   CALL B;        ❸

B: PROCEDURE;
   CALL C;
   RETURN;       ❷  ❻
   END B;

C: PROCEDURE;
   SIGNAL FIXEDOVERFLOW;
   RETURN;                 ❶  ❺
   END C;


END A;

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. This handling of multiple conditions in PL/I differs from the standard behavior of the OpenVMS condition-handling facility (which skips the call frames that were searched for the current ON-unit). For information on OpenVMS condition handling, see the Introduction to the VMS Run-Time Library.

Example 10.5, “Multiple Conditions” and Figure 10.5, “Effect of Multiple Conditions” illustrate the search sequence followed when a second condition occurs during the execution of an ON-unit. The numbers in the example 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 established for FIXEDOVERFLOW conditions in procedure C and gives it control. The box drawn with broken lines represents the ERROR ON-unit established by procedure B.

A: PROCEDURE OPTIONS (MAIN);

   ❶

CALL B;

B: PROCEDURE; ❷
   ON ERROR BEGIN; ❹

   ❺

   END;
   CALL C;

C: PROCEDURE; ❸
   ON FIXEDOVERFLOW BEGIN;

   ❻

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-that is, the program will enter an infinite loop when the STOP statement executes. The STOP statement signals FINISH, the current ON-unit is reexecuted, 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(NO) );
     END;

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 reexecuted.

Within the context of the PL/I language, an ON-unit resembles a procedure that has no parameters. However, in the OpenVMS environment, a condition handler or ON-unit is called with an argument list. The argument list consists of two pointer values, each of which points to a structure containing values that provide information about the condition.

In PL/I, you can access these arguments with the ONARGSLIST built-in function; this built-in function returns a pointer to the argument list passed to the most recent ON-unit. Figure 10.6, “The Argument List Passed to an ON-UNIT on OpenVMS VAX” and Figure 10.7, “The Argument List Passed to an ON-Unit on OpenVMS Alpha” illustrate the argument list and the arguments that can be accessed through this list for Endless PL/I V3.9 for OpenVMS VAX and Endless PL/I V5.0 for OpenVMS Alpha respectively.

Example 10.6, “Definitions for VAX Signal Array and Mechanism Array Arguments” displays the text module $CHFDEF, which contains Endless PL/I V3.9 for OpenVMS VAX declarations of these structures:

/* Definitions for Signal Array and Mechanism Array arguments for VAX */
DECLARE CHF$ARGPTR POINTER;
DECLARE 1 CHF$ARGLIST BASED (CHF$ARGPTR),
    2 CHF$COUNT FIXED BINARY(31), /* always 2 */
    2 CHF$SIGARGLST POINTER,
    2 CHF$MCHARGLST POINTER;
DECLARE 1 CHF$SIGNAL_ARRAY BASED (CHF$SIGARGLST),
    2 CHF$SIG_ARGS FIXED BINARY(31),      /* argument count */
    2 CHF$SIG_NAME FIXED BINARY(31),      /* condition name */
    2 CHF$SIG_ARG (CHF$SIG_ARGS-3) FIXED BINARY(31),
    2 CHF$PC FIXED BINARY(31),
    2 CHF$PSL FIXED BINARY(31),
  1 CHF$MECH_ARRAY BASED (CHF$MCHARGLST),
    2 CHF$MCH_ARGS FIXED BINARY(31),      /* always 4 */
    2 CHF$MCH_FRAME FIXED BINARY(31),
    2 CHF$MCH_DEPTH FIXED BINARY(31),
    2 CHF$MCH_SAVR0 FIXED BINARY(31),
    2 CHF$MCH_SAVR1 FIXED BINARY(31);

This module is in the default PL/I text library PLI$STARLET.TLB. You can include this module in a PL/I program by specifying the following %INCLUDE statement:

%INCLUDE $CHFDEF;

The PL/I compiler locates this module in PLI$STARLET.TLB when it compiles the source program.

Table 10.1, “Contents of the OpenVMS Alpha Mechanism Array (MECH) Arguments” explains the contents of the OpenVMS Alpha mechanism array arguments shown in Figure 10.7, “The Argument List Passed to an ON-Unit on OpenVMS Alpha”. Example 10.7, “Definitions for OpenVMS Alpha Signal Array and Mechanism Array Arguments” shows the definitions for OpenVMS Alpha signal and mechanism array arguments.

1 chf$mech_array based (chf$mcharglst),
  2 CHF$R_MCH_ARGS_DESC union,
    3 CHF$IS_MCH_ARGS fixed bin(31),  /*NUMBER OF MECHANISM ARGUMENTS     */
  2 CHF$R_MCH_FLAGS_DESC union,
    3 CHF$IS_MCH_FLAGS fixed bin(31), /*Flags                             */
    3 CHF$R_MCH_FLAGS_BITS ,          /*Flags bits.                       */

      4 CHF$V_FPREGS_VALID bit(1),     /*FP registers stored in MCH.       */
      4 CHF$V_FILL_37 bit(7),
  2 CHF$R_MCH_FRAME_DESC union,
    3 CHF$PH_MCH_FRAME (2) pointer,   /*ESTABLISHER FRAME ADDRESS         */
  2 CHF$R_MCH_DEPTH_DESC union,
    3 CHF$IS_MCH_DEPTH fixed bin(31), /*FRAME DEPTH OF ESTABLISHER        */
    3 CHF$IH_MCH_DEPTH fixed binary(31), /*temp                           */
  2 CHF$IS_MCH_RESVD1 fixed bin(31), /*reserved, paired with DEPTH       */
  2 CHF$PH_MCH_DADDR (2) pointer,    /*ESTABLISHER HANDLER DATA CELL     */
  2 CHF$PH_MCH_ESF_ADDR (2) pointer, /*ESTABLISHER EXCEPTION STACK FRAME */
  2 CHF$PH_MCH_SIG_ADDR (2) pointer, /*ESTABLISHER EXCEPTION STACK FRAME */
  2 CHF$R_MCH_SAVR0_DESC union,
    3 CHF$R_FILL_33 union,
      4 CHF$IH_MCH_SAVR0 (2) fixed bin(31), /*SAVED REGISTER R0            */
      4 CHF$R_FILL_34 ,
5 CHF$IL_MCH_SAVR0_LOW fixed binary(31), /*LOW ORDER 32 BITS        */
5 CHF$IL_MCH_SAVR0_HIGH fixed binary(31), /*HIGH ORDER 32 BITS      */
  2 CHF$R_MCH_SAVR1_DESC union,
    3 CHF$R_FILL_35 union,
      4 CHF$IH_MCH_SAVR1 (2) fixed bin(31), /*SAVED REGISTER R1            */
      4 CHF$R_FILL_36 ,
5 CHF$IL_MCH_SAVR1_LOW fixed binary(31), /*LOW ORDER 32 BITS        */
5 CHF$IL_MCH_SAVR1_HIGH fixed binary(31), /*HIGH ORDER 32 BITS      */
  2 CHF$IH_MCH_SAVR16 (2) fixed bin(31), /*SAVED REGISTER R16            */
  2 CHF$IH_MCH_SAVR17 (2) fixed bin(31), /*SAVED REGISTER R17            */
  2 CHF$IH_MCH_SAVR18 (2) fixed bin(31), /*SAVED REGISTER R18            */
  2 CHF$IH_MCH_SAVR19 (2) fixed bin(31), /*SAVED REGISTER R19            */
  2 CHF$IH_MCH_SAVR20 (2) fixed bin(31), /*SAVED REGISTER R20            */
  2 CHF$IH_MCH_SAVR21 (2) fixed bin(31), /*SAVED REGISTER R21            */
  2 CHF$IH_MCH_SAVR22 (2) fixed bin(31), /*SAVED REGISTER R22            */
  2 CHF$IH_MCH_SAVR23 (2) fixed bin(31), /*SAVED REGISTER R23            */
  2 CHF$IH_MCH_SAVR24 (2) fixed bin(31), /*SAVED REGISTER R24            */
  2 CHF$IH_MCH_SAVR25 (2) fixed bin(31), /*SAVED REGISTER R25            */
  2 CHF$IH_MCH_SAVR26 (2) fixed bin(31), /*SAVED REGISTER R26            */
  2 CHF$IH_MCH_SAVR27 (2) fixed bin(31), /*SAVED REGISTER R27            */
  2 CHF$IH_MCH_SAVR28 (2) fixed bin(31), /*SAVED REGISTER R28            */
  2 CHF$FH_MCH_SAVF0 bit(64) aligned, /*SAVED REGISTER F0                */
  2 CHF$FH_MCH_SAVF1 bit(64) aligned, /*SAVED REGISTER F1                */
  2 CHF$FH_MCH_SAVF10 bit(64) aligned, /*SAVED REGISTER F10              */
  2 CHF$FH_MCH_SAVF11 bit(64) aligned, /*SAVED REGISTER F11              */
  2 CHF$FH_MCH_SAVF12 bit(64) aligned, /*SAVED REGISTER F12              */
  2 CHF$FH_MCH_SAVF13 bit(64) aligned, /*SAVED REGISTER F13              */
  2 CHF$FH_MCH_SAVF14 bit(64) aligned, /*SAVED REGISTER F14              */
  2 CHF$FH_MCH_SAVF15 bit(64) aligned, /*SAVED REGISTER F15              */
  2 CHF$FH_MCH_SAVF16 bit(64) aligned, /*SAVED REGISTER F16              */
  2 CHF$FH_MCH_SAVF17 bit(64) aligned, /*SAVED REGISTER F17              */
  2 CHF$FH_MCH_SAVF18 bit(64) aligned, /*SAVED REGISTER F18              */
  2 CHF$FH_MCH_SAVF19 bit(64) aligned, /*SAVED REGISTER F19              */
  2 CHF$FH_MCH_SAVF20 bit(64) aligned, /*SAVED REGISTER F20              */
  2 CHF$FH_MCH_SAVF21 bit(64) aligned, /*SAVED REGISTER F21              */
  2 CHF$FH_MCH_SAVF22 bit(64) aligned, /*SAVED REGISTER F22              */
  2 CHF$FH_MCH_SAVF23 bit(64) aligned, /*SAVED REGISTER F23              */
  2 CHF$FH_MCH_SAVF24 bit(64) aligned, /*SAVED REGISTER F24              */
  2 CHF$FH_MCH_SAVF25 bit(64) aligned, /*SAVED REGISTER F25              */
  2 CHF$FH_MCH_SAVF26 bit(64) aligned, /*SAVED REGISTER F26              */
  2 CHF$FH_MCH_SAVF27 bit(64) aligned, /*SAVED REGISTER F27              */
  2 CHF$FH_MCH_SAVF28 bit(64) aligned, /*SAVED REGISTER F28              */
  2 CHF$FH_MCH_SAVF29 bit(64) aligned, /*SAVED REGISTER F29              */
  2 CHF$FH_MCH_SAVF30 bit(64) aligned; /*SAVED REGISTER F30              */

Example 10.8, “Displaying Arguments Passed to a Condition Handler (VAX)” illustrates a procedure that displays values obtained from the signal array arguments and the mechanism array arguments.

%INCLUDE $CHFDEF;    ❶
DECLARE X FIXED;
            CHF$ARGPTR = ONARGSLIST();    ❷
/* Output number of signal arguments */
            PUT SKIP LIST('Signal Arg Count',CHF$SIG_ARGS);    ❸
/* Output condition name argument and rest of signal arguments */
            PUT SKIP LIST('Condition name', CHF$SIG_NAME);    ❹
            PUT SKIP LIST(DIM(CHF$SIG_ARG,1),
                         'additional arguments:');    ❺
                DO X = 1 TO DIM(CHF$SIG_ARG,1);
                    PUT SKIP LIST(CHF$SIG_ARG(X));
                    END;
/* Output RO and R1 */
            PUT SKIP(2) LIST('r0:',CHF$MCH_SAVR0);    ❻
            PUT SKIP(2) LIST('r1:',CHF$MCH_SAVR1);
END;

The following notes are keyed to Example 10.8, “Displaying Arguments Passed to a Condition Handler (VAX)”:

For more detailed information on the argument lists passed to a condition handler and for descriptions of the values in the signal array and mechanism array, see the OpenVMS System Services Reference Manual. Note that the PL/I run-time system signals conditions using the conventions for specifying signal arguments. Specifically, it passes arguments following the requirements described for the SYS$PUTMSG procedure. This procedure is described in the Introduction to the VMS Run-Time Library.

You can use the built-in function ONCODE to obtain the specific 32-bit status value that describes any condition that is signaled. The low-order three bits of this value contain the severity of the condition (success, warning, error, or fatal). The severity of a condition is important only when no ON-unit exists for a condition, and default condition handling is performed by either PL/I or the system (see Section 10.4, “Search Path for ON-Units”).

All OpenVMS-defined conditions have symbolic names associated with them. Table 10.2, “ONCODE Values for PL/I ON Conditions” lists the PL/I keyword condition names and the global symbol names for the OpenVMS condition values associated with them. If the ONCODE built-in function is invoked in an ON-unit for the related PL/I condition name, it returns the value of the indicated global symbol.

When you write an ON-unit to handle one or more conditions, you can refer specifically to the values returned by the ONCODE built-in function using system global symbol names. Table 10.2, “ONCODE Values for PL/I ON Conditions” lists, where appropriate, the specific system global symbol for a condition name.

All symbolic names associated with OpenVMS 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 and VALUE attributes, 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.

For example, the FIXEDOVERFLOW condition can be signaled for either of two conditions. An ON-unit can determine which condition was actually signaled by testing the value of ONCODE as follows:

DECLARE SS$_DECOVF GLOBALREF VALUE FIXED BINARY(31);
ON FIXEDOVERFLOW BEGIN;
     IF ONCODE() = SS$_DECOVF THEN
            PUT LIST ('Decimal overflow');
         ELSE
            PUT LIST ('Integer overflow');
     END;

In this example, the global symbol SS$_DECOVF is declared with the GLOBALREF and VALUE attributes. The ON-unit established for the FIXEDOVERFLOW condition determines, from the value returned by ONCODE, whether the condition was specifically a decimal overflow or an integer overflow.

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 OpenVMS Reference Manual.

This built-in function can be used in any of 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 OpenVMS 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.