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 compatibility with the OpenVMS versions of PL/I.

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 POSIX Systems User's Manual.

The ATTENTION condition is raised during interactive processing when a user signals attention at the terminal or, during batch processing, by a SIGNAL ATTENTION statement.

When the ATTENTION condition is raised, an ATTENTION ON-unit is entered. PL/I ignores this condition if there is no ATTENTION ON-unit. On return from an ATTENTION ON-unit, execution resumes at a point in the program just following the point where the condition was raised.

The CHECK condition is used to display names and values of data items within the scope of a condition prefix. The format of the CHECK condition is:

CHECK [ (name [,name]...) ]

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;
       TARGET2 = SOURCE1;
       TARGET2 = SOURCE2;

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

"14$15" "$"
"14$15" "4"
"14$15" "$"
"14$15" "5"
"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)

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 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:

PL/I signals the ERROR condition when any condition (except ENDPAGE, see preceding section) is raised and no ON-unit exists for the 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)

%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;

You can specify the NAME condition name in an ON, SIGNAL, or REVERT statement to handle errors that happen during execution of GET statements with the FILE option. By default, when a NAME condition is raised PL/I ignores the invalid data field, displays a message, and continues.

The format of the NAME condition name is:

NAME (file-reference)

The OVERFLOW condition name can be specified in an ON, REVERT, or SIGNAL statement or, if you compile using the IBM dialect, in a condition prefix, 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.

You can specify the RECORD condition name in an ON, SIGNAL, or REVERT statement to handle errors that happen during execution of READ, WRITE, or REWRITE statements. By default, when a RECORD condition is raised, PL/I displays a message, and raises an ERROR condition.

The format of the RECORD condition name is:

RECORD (file-reference)

You can specify the SIZE condition name in an ON, SIGNAL, or REVERT statement to handle errors that happen high-order (left-most) digits are lost in an assignment statement, intermediate result, or I/O operation. By default, when a SIZE condition is raised, PL/I displays a message and raises an ERROR condition.

The SIZE condition is disabled by default. To enable the SIZE condition, specify it in a condition prefix. If you signal the SIZE condition in a SIGNAL statement and SIZE is not enabled, PL/I displays an error.

The format of the SIZE condition name is:

SIZE

PL/I signals the SIZE condition when the following occurs:

The SIZE condition is not equivalent to the FIXEDOVERFLOW condition, which is raised when a fixed-point value exceeds the implementation's maximum value.

The ONCODE built-in function returns the specific condition codes associated with the error. Table 8.3, “Values of ONCODE Raised by SIZE” lists the SIZE condition codes and their meanings.

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. Table 8.4, “Values of ONCODE Raised by STRINGRANGE” shows 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 the -k or --check compiler option 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 STRINGSIZE condition is raised when you try to assign a bit or character string to a target variable that is not long enough to hold the string. STRINGSIZE is disabled by default and must be enabled using a condition prefix.

If the STRINGSIZE condition is raised and not handled, the string is truncated from the right-hand end so that it will fit in the target variable. A message is displayed and processing continues.

The ONCODE built-in function returns the specific condition codes associated with the error. Table 8.3, “Values of ONCODE Raised by SIZE” lists the STRINGSIZE condition codes and their meanings.

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 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 most common cause is the exhaustion of virtual memory; another cause might be an erroneous attempt to allocate a negative amount of storage.

You can specify the TRANSMIT condition name in an ON, SIGNAL, or REVERT statement to handle errors that happen during execution of any I/O statement. By default, when a TRANSMIT condition is raised, PL/I displays a message, and raises an ERROR condition. This condition is always enabled.

The format of the TRANSMIT condition name is:

TRANSMIT (file-reference)

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          }

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.

PL/I 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 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 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.

A condition prefix affects only the statement or block to which it is attached. It does not affect procedures or ON-units invoked during execution of the statement or block.

Condition prefixes attached to DO or SELECT statements apply only to the DO or SELECT statement, not to the entire DO or SELECT group.

Condition prefixes attached to compound statements apply only to the statement to which they are attached, not to the statements contained in the compound statement.

Condition prefixes attached to PROCEDURE or BEGIN statements apply to all statements in the block, including the END statement and any other PROCEDURE or BEGIN statements nested inside the block. You can enable or disable a condition for an entire block and all the contained blocks by attaching a condition prefix to the PROCEDURE or BEGIN statement of the outermost block that you want to affect.

By default, some conditions are enabled unless explicitly disabled, others are disabled unless explicitly enabled, and some cannot be disabled. Table 8.7, “Conditions Enabled by Default”, Table 8.8, “Conditions Disabled by Default”, and Table 8.9, “Conditions That Cannot be Disabled” list the conditions in each of these three categories..