Program Control

The ANYCONDITION keyword can be specified in an ON, REVERT, or SIGNAL statement. It designates an ON-unit established for all signaled conditions that are not handled by specific ON-units.

The ANYCONDITION keyword is not defined in the PL/I language. It is provided specifically for use in the OpenVMS operating system environment. For detailed information on OpenVMS condition handling, see the Endless PL/I for OpenVMS User Manual.

The AREA condition is raised when various operations fail in relation to areas. For example, it is raised if the extent of an area is not large enough to contain the variable or variables allocated to it, or if the area is incorrectly formatted.

For more information see the Endless PL/I for OpenVMS User Manual.

The CONDITION condition name is used for ON-units to handle programmer-defined conditions. The value returned by the ONCODE built-in function is PLI$_CONDITION. There is no way to distinguish between multiple programmer-defined conditions if they are specified in the same ON statement.

The format of the CONDITION condition name is:

CONDITION (cond-name)

The CONVERSION condition name can be specified in an ON, SIGNAL, or REVERT statement to designate a CONVERSION condition or ON-unit.

PL/I signals the CONVERSION condition when the source character data in a conversion to bit-string or arithmetic data contains characters that are not valid in the specified context. In particular, the CONVERSION condition is raised when a character string is being converted and one of the following conditions is true:

The CONVERSION condition can be raised either by a non-I/O conversion, such as an explicit conversion using a built-in function or an implicit conversion generated by the compiler, or by an I/O conversion in a GET statement. For example, A = BIT('1014') would cause the CONVERSION condition to be raised, because 4 is not a valid binary digit. Likewise, a GET statement with an arithmetic target would also cause the CONVERSION condition to be raised if the characters '12K45' appeared in the input field, because 'K' is not a valid numeric character.

You can use the ONSOURCE and ONCHAR built-in functions and pseudovariables inside an ON CONVERSION ON-unit. The ONSOURCE built-in function returns the source string that caused the CONVERSION condition to be raised. The ONCHAR built-in function returns the specific character that caused the conversion to fail. You can use the ONSOURCE pseudovariable to change the value of the conversion. Likewise, you can use the ONCHAR pseudovariable to modify only the single character in error.

If the CONVERSION condition was raised during a conversion required by the GET statement, the ONFILE built-in function returns the name of the file constant inside the CONVERSION ON-unit. If the CONVERSION condition was not raised during a conversion required by the GET statement, the ONFILE built-in function returns a null string.

/*
* Sample program that displays a 'quick-fix' CONVERSION
* ON-unit. At the end of this program, TARGET1 contains
* the value 14015, and TARGET2 contains the value '11100'B.
* Note that SOURCE1 and SOURCE2 are not modified.
*/
MAIN: PROCEDURE OPTIONS(MAIN);

    DCL SOURCE1 CHARACTER(5) VARYING INITIAL('14$15');
    DCL SOURCE2 CHARACTER(5) VARYING INITIAL('11q00');

    DCL TARGET1 FIXED BINARY(31);
    DCL TARGET2 BIT(5) ALIGNED;

    /*
    * Sample 'quick-fix' CONVERSION ON-unit that replaces
    * erroneous lowercase q's with 1's, and all other
    * erroneous characters with 0's.
    */
    ON CONVERSION BEGIN;

    PUT SKIP EDIT('"',ONSOURCE(),'" "',ONCHAR(),'"')((5)A);

    IF ONCHAR() = 'q'
    THEN
        ONCHAR() = '1';
    ELSE
        ONCHAR() = '0';

    END; /* ON */

    /*
    * Note that the CONVERSION condition is raised for all
    * 3 of the following statements.
    */
    TARGET1 = SOURCE1;
    TARGET1 = SOURCE1;
    TARGET2 = SOURCE2;

    PUT SKIP(2) EDIT(SOURCE1,SOURCE2)(A,X,A);
    PUT SKIP EDIT(TARGET1,TARGET2)(F(8),X,B(5));

    END MAIN;

"14$15" "$"
"14$15" "$"
"11q00" "q"

14$15 11q00
   14015 11100

The ENDFILE condition name can be specified in an ON, SIGNAL, or REVERT statement to designate an end-of-file condition or ON-unit for a specific file.

PL/I signals the ENDFILE condition when a GET or READ statement attempts an input operation on a file or device after the last data item has been input.

The format of the ENDFILE condition name is:

ENDFILE (file-reference)

An ENDFILE ON-unit can be established for any input file. For any particular file, the meaning of the end-of-file condition depends on the type of device. For example, end-of-file is signaled for a terminal device when the Ctrl/Z character is read.

For a stream file, an end-of-file condition is signaled whenever a GET statement attempts to access an empty file or attempts to access a file whose last input field has been read.

For a record file, an end-of-file condition is signaled when a READ statement is executed with the file at the end-of-file position or when a read is attempted beyond the last record in the file. For example:

ON ENDFILE (RECEIPTS) EOF = '1'B;
EOF = '0'B;
OPEN FILE (RECEIPTS) RECORD SEQUENTIAL;
READ FILE (RECEIPTS) INTO (RECORD);
DO WHILE (^EOF);
      .
      .
      .
    READ FILE (RECEIPTS) INTO (RECORD);
    END;

In this example, the ON statement establishes the default action to be taken when the last record in the input file has been processed: the flag EOF is set to '1'B.

An ON-unit established to handle end-of-file conditions can reference the ONFILE built-in function to determine the name of the file constant for which the condition was signaled.

The ENDPAGE condition name can be specified in an ON, SIGNAL, or REVERT statement to designate an end-of-page condition or ON-unit for a specific print file.

The format of the ENDPAGE condition name is:

ENDPAGE (file-reference)

The maximum number of lines that can be output on a single page is set by the PAGESIZE option of the OPEN statement. The maximum number of lines allowed on a single page is 32767. If not specified, PL/I determines a default page size using the formula LIB$LP_LINES minus 6.

PL/I signals the ENDPAGE condition when a PUT statement attempts to output a line beyond the last line specified for an output page. When the ENDPAGE condition is signaled, the current line number associated with the file is the page size plus 1. An ENDPAGE ON-unit allows you to provide special processing before output continues on a new page. For example:

ON ENDPAGE (PRINTFILE) BEGIN;
   PUT FILE (PRINTFILE) PAGE;
   PUT FILE (PRINTFILE) LIST(HEADER_LINE);
   PUT FILE (PRINTFILE) SKIP(2);
   END;

The ON-unit for the ENDPAGE condition for the file PRINTFILE outputs a page eject and a header line for the new output page.

To cause PL/I to ignore the ENDPAGE condition when a large amount of output is written to a terminal, you can use the following ON-unit, that contains only the null statement:

ON ENDPAGE(SYSPRINT);

This is optional because PL/I ignores the ENDPAGE condition on SYSPRINT by default. You cannot catch the ENDPAGE(SYSPRINT) condition.

An ON-unit established to handle end-of-page conditions can reference the ONFILE built-in function to determine the name of the file constant for which the condition was signaled.

The ERROR condition name can be specified in an ON, SIGNAL, or REVERT statement to designate an error condition or ON-unit.

PL/I signals the ERROR condition in the following contexts:

When any condition is signaled for which no specific ON-unit is established, the default PL/I action for all conditions except ENDPAGE is to signal the ERROR condition.

When any ON-unit is executed, the ON-unit can reference the built-in function ONCODE. This function returns the numeric condition value associated with the specific error that signaled the condition.

The FINISH condition name can be specified in an ON, SIGNAL, or REVERT statement to designate a FINISH condition or a FINISH ON-unit.

PL/I signals the FINISH condition in the following contexts:

The FIXEDOVERFLOW condition name can be specified in an ON, SIGNAL, or REVERT statement to designate a fixed overflow condition or ON-unit.

PL/I signals the FIXEDOVERFLOW condition in the following circumstances:

The value resulting from an operation that causes this condition is undefined.

ON FIXEDOVERFLOW BEGIN;
   IF ONCODE() = SS$_DECOVF THEN DO;   /* Decimal overflow handling */
   END;

   IF ONCODE() - SS$_INTOVF THEN DO;   /* Fixed binary overflow handling */
   END;
END;  /* ON */

ON VAXCONDITION (SS$_DECOVF) BEGIN;  /* Decimal overflow handling */
END;  /* ON */

The KEY condition name can be specified in an ON, SIGNAL, or REVERT statement to designate a key error condition or ON-unit for a specific file.

The format of the KEY condition name is:

KEY (file-reference)

PL/I signals the KEY condition during an operation on a keyed file when an error occurs in processing a key. Some examples of errors for which PL/I signals the KEY condition follow:

An ON-unit established to handle the KEY condition can obtain information about the condition by invoking the following built-in functions:

%INCLUDE $RMSDEF;

KEYTEST: PROCEDURE OPTIONS(MAIN);

DECLARE
  RECBUF CHAR(80),
  MYFILE FILE;

ON KEY(MYFILE) BEGIN;

  PUT SKIP LIST('Key condition raised');
  IF ONCODE()=RMS$_MRN THEN
    PUT SKIP LIST('You have exceeded the maximum record.');

  STOP;

END;

  OPEN FILE(MYFILE) TITLE('MYFILE.DAT') OUTPUT KEYED
                    ENVIRONMENT(FIXED_LENGTH_RECORDS,
                                MAXIMUM_RECORD_SIZE(80),
                                MAXIMUM_RECORD_NUMBER(20));

  RECBUF = 'This record will not ever make it into the file';

  WRITE FILE(MYFILE) FROM(RECBUF) KEYFROM(100);

END;

The OVERFLOW condition name can be specified in an ON, REVERT, or SIGNAL statement to designate an ON condition or ON-unit for floating-point overflow conditions.

The exponent of a floating-point value is adjusted, if possible, to represent the value with the specified precision. That is, the precision is maximized and the exponent is minimized. The maximum precisions allowed are:

PL/I signals the OVERFLOW condition when the result of an arithmetic operation on a floating-point value exceeds the maximum exponent size allowed by the hardware.

The value resulting from an operation that causes this condition is undefined.

The STORAGE condition is raised when an error has been detected during allocation of a controlled variable or a based variable other than to an area. The ONCODE value is the error returned by LIB$GET_VM. The most common cause is the exhaustion of virtual memory; another cause might be an erroneous attempt to allocate a negative amount of storage.

The STRINGRANGE condition is raised when a substring reference is beyond the length of the string. The error is detected either by compiled code or by a run-time library routine.

STRINGRANGE can be abbreviated STRG.

Any one of several subconditions can cause the STRINGRANGE condition to be raised. You can use the ONCODE built-in function to determine which one. Following are the possible values of the ONCODE built-in function for the STRINGRANGE condition:

Note that STRINGRANGE is always enabled in RTL code (which is currently used for more complex cases of INDEX, SEARCH, and VERIFY), but in-line checking is only performed if /CHECK=BOUNDS is used to compile the code in which the condition would be raised.

An example of the use of the STRINGRANGE condition and the ONCODE built-in function follows.

%INCLUDE $PLIDEF;
ON STRINGRANGE BEGIN;
            /*
             * The THEN clause below will be executed for all
             * SUBSTR starting-position range errors. All other
             * STRINGRANGE errors will be resignaled. Note that
             * SUBSTR is processed in-line, so the code must be
             * compiled with /CHECK=BOUNDS for this ON-unit to
             * be effective.
             */
            IF ONCODE() = PLI$_SUBSTR2
            THEN
                ⋮
            ELSE
                CALL RESIGNAL();
            END;

The SUBSCRIPTRANGE condition is raised in response to out-of-bounds subscripts in references to arrays. The value returned by the ONCODE built-in function for the SUBSCRIPTRANGE condition is PLI$_SUBRANGE or PLI$_SUBRANGEn, where n is the number of the subscript, in the range 1 through 8.

The UNDEFINEDFILE condition name can be specified in an ON, SIGNAL, or REVERT statement to designate an undefined file condition or ON-unit for a specific file.

The format of the UNDEFINEDFILE condition name is:

{ UNDEFINEDFILE } (file-reference)
{ UNDF          }

PL/I signals the UNDEFINEDFILE condition when a file cannot be opened. Following are some examples of errors that cause the UNDEFINEDFILE condition:

The UNDEFINEDFILE condition lets you establish an ON-unit to provide processing when a file cannot be opened, for example, to provide a default file if no file is specified at run time.

X: PROCEDURE (FILENAME);
DECLARE FILENAME CHARACTER (128) VARYING;
DECLARE INPUT_FILE FILE INPUT;
    ON UNDEFINEDFILE (INPUT_FILE)
           OPEN FILE (INPUT_FILE)
           TITLE ('SYS$INPUT');
    OPEN FILE (INPUT_FILE) TITLE (FILENAME);

In this example, the procedure X expects a file specification string to be passed as an argument. If no argument is passed, or if the argument is not a valid file specification, the OPEN statement fails. The UNDEFINEDFILE ON-unit provides a default OPEN statement with the file specification SYS$INPUT.

An ON-unit established to handle the UNDEFINEDFILE condition can obtain information about the condition by invoking the following built-in functions:

On Endless PL/I V3.9 for OpenVMS VAX you can specify the UNDERFLOW condition name (which can be abbreviated UFL) in an ON, REVERT, or SIGNAL statement to designate a floating-point underflow condition or ON-unit. The Alpha hardware does not support UNDERFLOW detection; therefore, the underflow condition is not raised on OpenVMS Alpha systems.

Endless PL/I V3.9 for OpenVMS VAX signals the UNDERFLOW condition when the absolute value of the result of an arithmetic operation on a floating-point value is smaller than the minimum value that can be represented by the VAX hardware.

The VAXCONDITION condition name can be specified in an ON, RESIGNAL, REVERT, or SIGNAL statement. The VAXCONDITION condition name provides a way to signal and handle operating-system or programmer-specified condition values. The format of the VAXCONDITION condition name is:

VAXCONDITION (expression)

The VAXCONDITION condition name is provided specifically for PL/I procedures that interact with operating system routines. For details on using the VAXCONDITION condition name and the meanings of system- and user-defined values that you can specify, see the Endless PL/I for OpenVMS User Manual.

The ZERODIVIDE condition name can be specified in an ON, REVERT, or SIGNAL statement to designate a divide-by-zero condition or ON-unit.

PL/I signals the ZERODIVIDE condition when the divisor in a division operation has a value of zero. The value resulting from such an operation is undefined.