| Previous | Contents | Index |
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) |
file-reference
The name of the file constant or file variable for which the ENDPAGE ON-unit is to be established. If the name of a file variable is specified, the variable must be resolved to the name of a file constant when the condition is signaled. The file must have the PRINT attribute.
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.
If the ON-unit does not transfer control elsewhere in the program, the line number is set to 1 and the program continues execution of the PUT statement. If the ENDPAGE condition was signaled during data transmission, the data is written on the new current line. If the ENDPAGE condition was caused by a LINE or a SKIP option on the PUT statement, then the action specified by these options is ignored on return.
An ENDPAGE condition can occur only once per page of output. If the ON-unit specified does not specify a new page, then execution and output continue. The current line number can increase indefinitely; PL/I does not signal the ENDPAGE condition again. However, if a LINE option on a PUT statement specifies a line number that is less than that of the current line, a new page is output and the current line is set to 1.
If the ENDPAGE condition is signaled during file processing, PL/I
starts output on a new page and continues processing. An exception is
made for SYSPRINT which is to take no action. If the ENDPAGE condition
is signaled as a result of a SIGNAL statement, the statement following
the SIGNAL statement is executed and no page is output by default.
8.10.4.7 ERROR Condition Name
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.
If an ERROR ON-unit does not handle the condition, the program is
terminated.
8.10.4.8 FINISH Condition Name
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:
If a FINISH ON-unit that executes as a result of a SIGNAL FINISH
statement does not execute a nonlocal GOTO statement, control returns
to the statement following SIGNAL FINISH. If the FINISH ON-unit
executes as a result of any of the other three causes listed above, the
program terminates.
8.10.4.9 FIXEDOVERFLOW Condition Name
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.
Two hardware exceptions exist that result in the FIXEDOVERFLOW condition. These are SS$_DECOVF (for a fixed-point decimal overflow) and SS$_INTOVF (for a fixed-point binary integer overflow). An ON-unit that receives control when FIXEDOVERFLOW is signaled can reference the ONCODE built-in function to determine which condition is actually signaled.
To define an ON-unit to respond specifically to either of these errors, use the VAXCONDITION condition name.
To respond to a FIXEDOVERFLOW condition caused by either decimal or integer overflow, write an ON-unit as follows:
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 */ |
To respond to a decimal overflow only, write an ON-unit like the following:
ON VAXCONDITION (SS$_DECOVF) BEGIN; /* Decimal overflow handling */ END; /* ON */ |
If the ON-unit does not transfer control elsewhere in the program,
control returns to the point at which the condition was signaled.
8.10.4.10 KEY Condition Name
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) |
file-reference
A reference to the file constant or file variable for which the ON-unit is to be established. If the name of a file variable is specified, the variable must be resolved to the name of a file constant when the condition is signaled.
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:
The following example shows the key of a relative file exceeding the maximum record number specifed.
%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;
|
If the ON-unit does not execute a nonlocal GOTO, control returns to the
statement immediately following the statement that caused the KEY
condition.
8.10.4.11 OVERFLOW Condition Name
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.
Control returns to the point of the interruption.
8.10.4.12 STORAGE Condition Name
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.
8.10.4.13 STRINGRANGE Condition Name
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:
| ONCODE value | Raised by |
|---|---|
| PLI$_STRRANGE | SIGNAL STRINGRANGE |
| PLI$_SUBSTR2 | Out-of-range SUBSTR 2nd argument |
| PLI$_SUBSTR3 | Out-of-range SUBSTR 3rd argument |
| PLI$_BIFSTAPOS | Out-of-range starting position for an INDEX, SEARCH, or VERIFY built-in function |
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.
8.10.4.15 UNDEFINEDFILE Condition Name
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:
file-reference
A reference to a file constant or file variable for which the ON-unit is established.If the name of a file variable is specified, the variable must be resolved to the name of a file constant when the condition is signaled.
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:
The action taken on a normal return from the UNDEFINEDFILE condition depends on whether the file was opened explicitly or implicitly.
If the UNDEFINEDFILE condition was signaled following an explicit OPEN statement for a file, then the normal action following the ON-unit execution is for the program to continue. If the ON-unit does not transfer control elsewhere in the program, control returns to the statement following the OPEN statement that caused the condition to be signaled.
If the UNDEFINEDFILE condition was signaled during an implicit open attempt, the run-time system tests the state of the file. If the file is not open, the ERROR condition is signaled. If the file was opened by the ON-unit, execution of the I/O statement continues.
If an ON-unit receives control when an explicit OPEN results in the
UNDEFINEDFILE condition, and the ON-unit does not handle the condition
by opening the file or by transferring control elsewhere in the
program, control returns to the statement following the OPEN. Then, if
an attempt is made to access the file with an I/O statement, the
UNDEFINEDFILE condition is signaled again when PL/I attempts the
implicit open of the file. This time, PL/I signals the ERROR condition
on completion of the ON-unit.
8.10.4.16 UNDERFLOW Condition Name (Kednos PL/I for OpenVMS VAX only)
On Kednos PL/I 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.
Kednos PL/I 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.
On completion of the ON-unit, control is returned to the point of the interrupt. Continued execution is unpredictable.
This condition is signaled by Kednos PL/I for OpenVMS VAX only in procedures in which the UNDERFLOW option is enabled. The option is enabled when you specify UNDERFLOW in the procedure options. Kednos PL/I for OpenVMS Alpha ignores the UNDERFLOW option.
The value resulting from an operation that causes the UNDERFLOW
condition is undefined. (The value would be set to zero only if
UNDERFLOW were not specified in the procedure options.)
8.10.4.17 VAXCONDITION Condition Name
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) |
expression
An expression yielding a fixed binary value. The expression is evaluated when the ON statement is executed, not when the condition is signaled.
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 Kednos PL/I for OpenVMS Systems User Manual.
8.10.4.18 ZERODIVIDE Condition Name
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.
8.10.5 Default PL/I ON-Unit
PL/I defines a default ON-unit for the procedure that is designated as the main procedure. This is why there must be exactly one procedure with OPTIONS(MAIN) specified in any executable image. This default ON-unit performs the following actions depending on the condition signaled. Note that the severity of the signal is determined by the low three bits of the condition code.
| Previous | Next | Contents | Index |