|
VMS Help PLI *Conan The Librarian |
The PLI command invokes the PL/I compiler to compile a PL/I source
program.
Format
PLI file-spec[,...]
| 1 - Parameters |
file-spec,...
Specifies one or more PL/I source files separated by plus signs
or commas. If plus signs are specified, the input files are
concatenated into a single input file. If commas are specified,
each file is compiled separately to create a separate object module.
If no file type is specified, PL/I uses the default file type .PLI.
library-file-spec
Specifies a text library containing INCLUDE file definitions
referenced in one or more of the specified source files.
A library file specification must be preceded with a plus sign
and qualified by /LIBRARY. If no file type is specified,
PL/I assumes the default file type of .TLB.
| 2 - Qualifiers |
Indicate special actions to be performed by the compiler or special input file properties. Compiler qualifiers can apply to either the PLI command or to the specification of the file being compiled. When a qualifier follows the PLI command, it applies to all the files listed. When a qualifier follows the file specification, it applies only to the file immediately preceding it. The following list shows all the qualifiers available with the PLI command: o /[NO]ALIGN (OpenVMS VAX only) o /[NO]ALIGN[=option] (OpenVMS AXP only) o /[NO]ANALYSIS_DATA[=file-spec] (OpenVMS VAX only) o /[NO]CHECK[=option] o /[NO]CROSS_REFERENCE o /DATA[=option] (OpenVMS AXP only) o /[NO]DEBUG[=(option,...)] o /[NO]DESIGN[=(option,...)] (OpenVMS VAX only) o /[NO]DIAGNOSTICS (OpenVMS VAX only) o /ERROR_LIMIT [=n] o /FIXED_BINARY[=(15,31)] o /FLOAT[=option] (OpenVMS AXP only) o /[NO]G_FLOAT o /GRANULARITY[=option] (OpenVMS AXP only) o /LIBRARY o /[NO]LIST[=file-spec] o /[NO]MACHINE_CODE[=option] o /[NO]OBJECT[=file-spec] o /[NO]OPTIMIZE[=(option,...)] o /SHOW=(option,...) o /VARIANT[=["]string["]] o /[NO]WARNINGS[=(option,...)]
3 - /ALIGN[=option]
/NOALIGN (D)
Controls alignment of data within structures and aligned bit
strings. If you specify /ALIGN on a VAX system, data is aligned on
the natural byte boundary of the specified data type. If you
specify /NOALIGN, the default, data is aligned on the next
available byte boundary.
(OpenVMS AXP only)
/[NO]ALIGN[=(PACKED|NATURAL)]
If you specify /ALIGN=NATURAL, data is aligned on the natural byte
boundary of the specified data type. If you specify /ALIGN=PACKED,
data is aligned on the next available byte boundary. On OpenVMS
AXP, /ALIGN=PACKED forces data to be aligned on the next available
byte boundary. Data structures will be aligned in the same manner
as on a OpenVMS VAX System. Requesting /DATA=VAX will cause
/ALIGN=PACKED to be selected. Specifying /ALIGN with no option is
equivalent to specifying /ALIGN=NATURAL.
4 - /ANALYSIS_DATA[=file-spec]
/NOANALYSIS_DATA (D) (OpenVMS VAX only) Controls whether the compiler generates a file of source code analysis information. The default file name is the file name of the primary source file. The default file type is .ANA.
5 - /CHECK[=option]
/NOCHECK (D)
Controls the checking of array subscripts and of positional
references in arguments to the SUBSTR built-in function. If you
specify /CHECK, the compiler checks for the following conditions:
o Whether each reference to the SUBSTR built-in function or
pseudovariable lies within the string's current length
o Whether each reference to an array specifies subscripts that
are within the bounds declared for the array
o Whether all string lengths are nonnegative and whether all
array extents are positive
The default is /NOCHECK. /CHECK is useful primarily during initial
program debugging; it results in the generation of additional code
and, consequently, a slower program.
Specifying /CHECK is equivalent to specifying /CHECK=ALL or
/CHECK=BOUNDS. Likewise, /NOCHECK is the equivalent of specifying
/CHECK=NONE or /CHECK=NOBOUNDS.
6 - /CROSS_REFERENCE
/NOCROSS_REFERENCE (D) Specifies whether the compiler is to generate cross references in the listing file. If you specify /CROSS_REFERENCE, the compiler lists, for each variable referenced in the procedure, the line numbers of the lines on which the variable is referenced. You must specify /LIST/SHOW=MAP with /CROSS_REFERENCE.
7 - /DATA[=option]
/DATA=VAX (D)
(OpenVMS AXP only)
Specifies the integer size and whether alignment is enabled. You
can select the following options:
NATIVE Sets the integer size to 32 and enables /ALIGNMENT;
equivalent to ALPHA_AXP32
VAX Sets the integer size to 32 and enables /NOALIGNMENT
ALPHA_AXP32 Sets the integer size to 32 and enables /ALIGNMENT
MIPS Sets the integer size to 32 and enables /ALIGNMENT
The default if /DATA is not given is /DATA=VAX. The default for
/DATA with no option is /DATA=NATIVE.
8 - /DEBUG[=(option,...)]
/DEBUG=TRACEBACK (D)
Requests that information be included in the object module for use
with the OpenVMS Debugger.
It is strongly recommended that you use the /NOOPTIMIZE qualifier
when you use the /DEBUG qualifier. Optimization can cause
confusing results during a debugging session.
When /DEBUG is specified, the compiler generates small routines
that are used only by the debugger. When the program is linked
with /NODEBUG, these routines will still be included in the program
but will not be used. For this reason it is recommended that final
versions of programs be recompiled with /NODEBUG (which is the
default).
You can select the following options:
ALL Includes symbol table records and traceback
records. /DEBUG is equivalent to /DEBUG=ALL.
SYMBOLS Includes the symbol definitions for all
identifiers in the compilation. This is the
default for symbols if the /DEBUG qualifier is
used.
NOSYMBOLS Does not include symbol definitions. Without
symbol definitions, traceback is done
according to virtual address.
TRACEBACK Includes only traceback records. This is the
default if the /DEBUG qualifier is not present
on the command.
NOTRACEBACK Does not include traceback records.
INLINE Generates debug information to cause a STEP
(OpenVMS command to STEP/INTO an inlined fuction call.
VAX only)
NOINLINE Generates debug information to cause a STEP
(OpenVMS command to STEP/OVER an inlined fuction call.
VAX only)
NONE Does not include any debugging information.
Use this option to exclude all debug
information from thoroughly debugged
program modules. /NODEBUG is equivalent to
/DEBUG=NONE.
If you omit the /DEBUG qualifier, the default is /DEBUG=TRACEBACK.
9 - /DESIGN[=(option,...)]
/NODESIGN (D)
(OpenVMS VAX only)
Controls whether the compiler processes the source file as a
detailed design, in conjunction with the DECset Program Design
Facility (PDF). The /DESIGN qualifier requires that the
/ANALYSIS_DATA also be specified.
If you specify the /DESIGN qualifier, the compiler modifies its
parsing and semantics according to the optional keywords you
supply. The design information is added to the DEC Source Code
Analyzer (SCA) Analysis Data File (.ANA).
You can select from the following options:
[NO]COMMENTS COMMENTS, the default, directs the
compiler to search inside comment
fields for program design information.
Specifying the option NOCOMMENTS omits
this searching.
[NO]PLACEHOLDERS PLACEHOLDERS, the default, directs the
compiler to treat DEC Language-Sensitive
Editor (LSE) placeholders in proper
contexts within the program as valid
syntax. Specifying NOPLACEHOLDERS causes
the compiler to treat all LSE placeholders
as invalid syntax.
The options are mutually independent. Specifying /DESIGN without
naming an option is equivalent to /DESIGN=(COMMENTS,PLACEHOLDERS).
You can exclude both options by specifying /NODESIGN or by omitting
the qualifier. To select one option and exclude the other, you
must specify /DESIGN=NOCOMMENTS or /DESIGN=NOPLACEHOLDERS.
10 - /DIAGNOSTICS
/NODIAGNOSTICS (D) Creates a diagnostic file for use by some Digital layered products, including the Language-Sensitive Editor. The diagnostic file (which is not human readable) contains compiler messages and diagnostic information. If you omit the qualifier, /NODIAGNOSTICS is the default. The file type is .DIA by default.
11 - /ERROR_LIMIT [=n]
/ERROR_LIMIT=100 (D) /NOERROR_LIMIT Allows you to to specify the number of errors (n) acceptable during program compilation. The /NOERROR_LIMIT qualifier changes the default error limit of 100 to 1000. All error messages are counted toward the error limit. A fatal message, however, immediately terminates the compilation.
12 - /FIXED_BINARY[=(15,31)]
/FIXED_BINARY=31 (D) Specifies the default precision for fixed binary variables. If the qualifier is omitted or specified without a value, the default precision is 31.
13 - /FLOAT[=option]
/FLOAT=D_FLOAT (D) /FLOAT=IEEE_FLOAT /FLOAT=G_FLOAT (OpenVMS AXP only) For AXP computers, specifies the default representation of floating-point variables. For floating-point variables with a precision in the range 1 through 24 (binary) or 1 through 7 (decimal), the default format is F. Use /FLOAT=IEEE_FLOAT to specify S_FLOAT as the format. For floating-point variables with a precision in the range 25 through 53 (binary) or 8 through 15 (decimal), the default format is D. Use /FLOAT=IEEE_FLOAT to specify T_FLOAT as the format, or use /FLOAT=G_FLOAT to specify G_FLOAT as the format. The qualifiers /FLOAT and /G_FLOAT are mutually exclusive and should not be used on the same command line.
14 - /G_FLOAT
/NOG_FLOAT (D) For VAX and AXP computers that are equipped with the appropriate hardware option, specifies the default representation of floating-point variables with a precision in the range 25 through 53 (binary) or 8 through 15 (decimal) to be G floating. By default, the compiler uses D floating point. Specify /G_FLOAT to override this default and to request the compiler to use the G-floating-point type for these variables. The default and maximum precisions for all floating-point formats are summarized in the PL/I for OpenVMS Systems Reference Manual. (OpenVMS AXP only) The qualifiers /G_FLOAT and /FLOAT are mutually exclusive and should not be used in the same command line.
15 - /GRANULARITY[=option]
/GRANULARITY=QUADWORD (D) (OpenVMS AXP only) Specifies the smallest unit of data that can be cached in a register. The following options are available: o BYTE o LONGWORD o QUADWORD For example, QUADWORD granularity means that the AXP system will cache quadword values in registers. The default granularity is QUADWORD.
16 - /LIBRARY
Indicates that the associated input file is a library containing source text modules specified in %INCLUDE statements. The compiler searches the specified library for all INCLUDE file references that are not enclosed in apostrophes. The name of the library must be preceded by a plus sign. Example: PLI APPLIC+DATAB/LIBRARY
17 - /LIST[=file-spec]
/NOLIST (Interactive default)
/LIST (Batch default)
Controls whether a listing file is produced.
When /LIST is in effect, the compiler gives a listing file the same
file name as the source file and a file type of .LIS.
If you specify a file specification with /LIST, the compiler uses
that file specification to override the default values applied.
The /LIST qualifier must be given if the /SHOW qualifier is to have
any effect.
18 - /MACHINE_CODE[=option]
/NOMACHINE_CODE (D)
Controls whether the listing file produced by the compiler includes
a listing of the machine code generated during the compilation.
You can select the following options:
AFTER Puts machine code after the source code (the
default if /MACHINE_CODE is specified on an
AXP machine)
BEFORE Puts machine code before the source code
INTERSPERSED Intersperses source and machine code (the
(OpenVMS VAX default if /MACHINE_CODE is specified on a
only) VAX machine)
No machine code is generated if /NOOBJECT is specified; thus, if
/NOOBJECT/MACHINE_CODE are specified together, no machine code
listing is generated.
19 - /OBJECT[=file-spec]
/OBJECT (D) /NOOBJECT Controls whether the compiler produces an output object module. The default output file type is .OBJ. Specify /NOOBJECT when you want to compile a program to obtain only a listing or when you want the compiler to check the source program only for errors and display diagnostic messages.
20 - /OPTIMIZE[=(option,...)]
/OPTIMIZE=ALL (D)
/NOOPTIMIZE
Controls the optimization performed by the compiler. You can
select the following options:
For OpenVMS VAX Systems:
Option Description
-------------------------- -----------------------------------------------
ALL Perform all optimizations. This is equivalent
to /OPTIMIZE and is the default.
[NO]COMMON_SUBEXPRESSIONS [Do not] Eliminate common subexpressions.
[NO]DISJOINT [Do not] Place local variables in multiple
registers.
[NO]INLINE [Do not] Automatically provide inline
expansion of procedures to provide optimized
code.
[NO]INVARIANT [Do not] Remove invariant expressions from
loops.
[NO]LOCALS_IN_REGISTERS [Do not] Place local variables in registers.
[NO]PEEPHOLE [Do not] Perform pattern replacement on the
generated machine code.
[NO]RESULT_INCORPORATION [Do not] Collapse binary arithmetic operations
into 3-operand intructions.
For OpenVMS AXP Systems:
Option Description
--------------------- ---------------------------------------------------
LEVEL=n Specifies the level of optimization based on a
value from 0 to 5. Zero (0) specifies no optimiza-
tion and is equivalent to /NOOPTIMIZE. The default
value for LEVEL is 4.
UNROLL=n Specifies the number of times to unroll loops, based
on a value from 1 to 16. If the /UNROLL option is
not specified, a default unroll amount of 4 is used.
/LEVEL must be specified as 3 or greater to enable
loop unrolling.
INLINE=NONE Suppresses all inlining.
INLINE=MANUAL Inlines the calls you explicitly request to be
inlined.
INLINE=AUTOMATIC Inlines the calls in the MANUAL category plus any
additional calls that improve performance.
INLINE=ALL Inlines every call that is possible while still
generating correct code.
Note that the value of n in LEVEL=n turns on the INLINE=option
qualifier as follows
Level Inlining mode
----- -------------
0 none
1 none
2 manual
3 manual
4 automatic
For levels other than LEVEL=0, the INLINE=option qualifier is
honored if explicitly given on the command line.
21 - /SHOW=(option,...)
/SHOW=(TERMINAL,SOURCE,HEADER) (D)
The /SHOW qualifier must be used in combination with the /LIST
qualifier to be effective. The /LIST qualifier specifies that a
source listing is to be made, and the /SHOW qualifier gives you
control over which portions of the source listing you want to see.
You can also control the content of the source listing by using
preprocessor statements to suppress preprocessor portions in the
program text. For example, if you previously specified
/SHOW=INCLUDE, you can suspend included files from the listing with
the %NOLIST_INCLUDE statement in your program. The following
options set or cancel specific listing options.
ALL Print all files and modules
NONE Do not include any files or modules
[NO]INCLUDE [Do not] Print contents of INCLUDE files
[NO]DICTIONARY [Do not] Print CDD record modules
[NO]HEADER [Do not] Print listing file headers
[NO]MAP [Do not] Print storage map
[NO]SOURCE [Do not] Print source file statements
[NO]STATISTICS [Do not] Print compiler performance statistics
[NO]TERMINAL [Do not] Display compilation messages to SYS$OUTPUT
[NO]TRACE [Do not] Print all preprocessor replacement values
[NO]EXPANSION [Do not] Print the final preprocessor replacement values
The default options are NOINCLUDE, NODICTIONARY, NOMAP, SOURCE,
NOTRACE, TERMINAL, NOEXPANSION, HEADER and NOSTATISTICS.
22 - /VARIANT[=["]string["]]
/VARIANT="" (D) Permits specification of compilation variants. The value specified for /VARIANT is available at compile time through the VARIANT() preprocessor built-in function.
23 - /WARNINGS[=(option,...)]
/WARNINGS (D)
/NOWARNINGS
Controls whether the compiler prints diagnostic warnings and
informational messages. There are two options:
NOINFORMATIONALS Suppress informational messages
NOWARNINGS Suppress warning messages
| 24 - Attributes |
Specify the characteristics of named identifiers. Must be specified in a DECLARE statement to define a variable. File description attributes may also be specified on an OPEN statement.
24.1 - Categories
Computational Data Type Attributes: BINARY FIXED [[PRECISION](precision[,scale])], BINARY FLOAT [[PRECISION](precision)], CHARACTER [(length)] [VARYING|NONVARYING], BIT [(length)] [ALIGNED|UNALIGNED], DECIMAL FIXED [[PRECISION](precision[,scale] )] DECIMAL FLOAT [[PRECISION](precision)], DIMENSION (extent,..), PICTURE 'picture' Noncomputational Data Types: AREA, CONDITION, DIMENSION, ENTRY [VARIABLE], FILE [VARIABLE], LABEL, OFFSET, POINTER. Storage Class Attributes: AUTOMATIC, BASED, CONTROLLED, DEFINED [POSITION], STATIC, INITIAL, READONLY, VALUE Scope Attributes: EXTERNAL, INTERNAL, GLOBALDEF, GLOBALREF File Description Attributes: DIRECT, ENVIRONMENT, INPUT, KEYED, OUTPUT, PRINT, RECORD, SEQUENTIAL, STREAM, UPDATE Entry Name Attributes: ENTRY, VARIABLE, BUILTIN, RETURNS, OPTIONS(VARIABLE) Member Attributes: LIKE, MEMBER, REFER, STRUCTURE, UNION Argument Passing Attributes: ANY, DESCRIPTOR, LIST, OPTIONAL, PARAMETER, REFERENCE, TRUNCATE, VALUE
24.2 - ALIGNED
Requests that a bit-string variable be aligned on a byte boundary in storage. Invalid for all other data type attributes.
24.3 - ANY
Argument passing attribute. Indicates that a parameter may have any data type. This attribute is valid only in a parameter descriptor for a non-PL/I external entry.
24.4 - AREA
Noncomputational data type attribute. Defines a unit of storage for the allocation of based variables.
24.5 - AUTOMATIC
Storage class attribute. Abbreviation: AUTO Requests dynamic allocation of storage for a variable. This is the default for internal variables.
24.6 - BASED
Storage class attribute. Indicates that a variable's storage is located by a pointer or offset. BASED [ (reference) ] If no pointer or offset reference is given, all references to the variable must specify a locator qualifier of the form: locator -> variable-reference where locator is a valid pointer or offset value.
24.7 - BINARY
Data type attribute. Abbreviation: BIN
Defines a binary base for arithmetic data with precision (p) and
scale-factor (q).
FIXED BINARY (p) max=31
(q) -31 to 31
default=31,0
FLOAT BINARY (p) max=113 (OpenVMS VAX)
max=53 (OpenVMS AXP)
default=24
24.8 - BIT
Data type attribute. Defines bit-string data. A bit is a data item that has one of the values 0 or 1. Bit-string constants must be enclosed in apostrophes. BIT [ (length) ] [ ALIGNED ] where length is in the range 0 to 32767. It defaults to 1.
24.9 - BUILTIN
Entry name attribute. Specifies that a name is a PL/I built-in function. Built-in functions need not be declared unless (1) you have used the name of a built-in function as a user-defined name and want to reference the built-in function, or (2) you want to reference a built-in function that has no parameters without having to specify an empty argument list.
24.10 - CONDITION
Data type attribute. Abbreviation: COND Defines an identifier as a condition name.
24.11 - CONTROLLED
Storage class attribute. Abbreviation: CTL Indicates that a variable's storage is allocated and freed dynamically during program execution. Only the most recent generation of the variable is accessible at a time.
24.12 - CHARACTER
Data type attribute. Abbreviation: CHAR Defines character string data. CHARACTER [ (length) ] [ VARYING ] where length is in the range 0 to 32767. It defaults to 1.
24.13 - DECIMAL
Data type attribute. Abbreviation: DEC
Defines a decimal base for arithmetic data with precision (p) and
scale-factor (q).
FIXED DECIMAL (p) max p=31
(q) 0 to 31
FLOAT DECIMAL (p) max p=34 (OpenVMS VAX)
p=15 (OpenVMS AXP)
default=7
If no other other data type attributes are specified, the variable
has the attributes FIXED DECIMAL (10,0).
24.14 - DEFINED
Storage class attribute. Abbreviation: DEF Indicates that a variable will share the storage allocated for another variable. DEFINED (variable-reference) [ POSITION(expression) ]
24.15 - DESCRIPTOR
Argument passing attribute. Abbreviation: DESC Requests that an argument be passed to an external non-PL/I procedure by descriptor.
24.16 - DIMENSION
Data type attribute. Abbreviation: DIM
Indicates that a variable is an array and defines the number and
extent of its dimensions.
[DIMENSION] (bound,...)
Bounds can be specified as:
n a single integer giving the high bound; the low
bound defaults to 1
n:m a range of integers giving the low and high bounds
* an asterisk (if the variable is a parameter)
A maximum of 8 bounds may be specified; the maximum extent of a
dimension is 500 million bytes.
If the array has the STATIC attribute, bounds can be expressed only
using restricted expressions. Otherwise, they can be expressed
using any expression that yields a valid integer value.
24.17 - DIRECT
File description attribute. Specifies a record file that will be accessed randomly with READ, REWRITE, and DELETE statements.
24.18 - ENTRY
Attribute. Describes an external entry point and its parameters. ENTRY [ (parameter-descriptor,...) ] Type HELP PLI ATTRIBUTE PARAMETER DESCRIPTOR for more information.
24.19 - Extent
An extent gives a length or dimension of a variable. The rules for
specifying extents apply to the length of a character-string or
bit-string variable and to the dimensions of an array. The length
of a character string or a bit string is the number of characters
or bits of its value. The dimensions of an array are expressed in
terms of bounds, and the rules for specifying extents apply to
those bounds. These rules are:
1. If an extent is specified in a static variable declaration,
the extent must be specified as an integer constant or an integer
constant expression. (An integer constant expression is an expression
consisting solely of integer constants, identifiers given values by
%REPLACE statements, and any of the operators +, -, or *.)
2. If an extent is specified in the declaration of a parameter,
in a parameter descriptor, or in a returns descriptor, the extent
may be specified as an integer constant, integer constant
expression, or as an asterisk (*). If one dimension of an array
is specified with an asterisk, all must be specified with asterisks.
3. If the extent is specified for an automatic, based, or
defined variable it may be specified as an integer constant or
as an expression.
4. The maximum value that can be specified for an extent
is 500 million bytes.
24.20 - EXTERNAL
Scope attribute. Abbreviation: EXT Identifies the name of a variable whose storage is referenced or defined in other procedures.
24.21 - FILE
Noncomputational data type attribute. Identifies a PL/I file constant or file variable. FILE [ VARIABLE ] A file reference can be an identifier declared as a file constant, a scalar reference to a variable with the FILE attribute, or a function that returns a file value.
24.22 - FIXED
Data type attribute.
Defines a fixed-point arithmetic variable with precision (p) and
scale-factor (q).
FIXED BINARY (p) max=31
(q) -31 to 31
default=31,0
FIXED DECIMAL (p) max=31
(q) 0 to 31
default=10,0
If FIXED is specified without any other data type attributes, the
variable has the attributes FIXED BINARY(31,0).
24.23 - FLOAT
Data type attribute. Defines a floating-point arithmetic variable. FLOAT BINARY(p) max=113 default=24 (OpenVMS VAX) FLOAT BINARY(p) max=53 default=24 (OpenVMS AXP) FLOAT DECIMAL(p) max=34 default=7 (OpenVMS VAX) FLOAT DECIMAL(p) max=15 default=7 (OpenVMS AXP) If FLOAT is specified without any other data type attributes, the variable has the attributes FLOAT BINARY(24). Floating-point binary data with precision in the range of 54-113 may be supported in software, depending on the processor type and hardware options.
24.24 - GLOBALDEF
Storage class attribute. Defines an external global symbol and optionally specifies the program section in which the symbol's storage will be allocated. GLOBALDEF [ (psect-name) ]
24.25 - GLOBALREF
Storage class attribute. Declares a global symbol defined in an external procedure.
24.26 - INITIAL
Storage class attribute. Abbreviation: INIT
Provides initial values for variables that have the STATIC,
AUTOMATIC, BASED, or CONTROLLED attributes.
INITIAL {(value,...) | ((*) valid-expression) }
The valid ways to specify value are:
string-constant
(replication-factor) string-constant
(iteration-factor) (string-constant)
(iteration-factor) ((replication-factor) string-constant)
[ (iteration-factor) ] arithmetic-constant
[ (iteration-factor) ] scalar-reference
[ (iteration-factor) ] (scalar-expression)
[ (iteration-factor) ] *
If the initialized variable is STATIC, only constants, restricted
expressions, and references to the NULL or EMPTY built-in functions
are allowed. These can be used with a constant iteration factor.
The (*) valid-expression construct initializes all elements of an
array to the same value. A valid-expression is one of the
following:
(string-constant)
((replication-factor) string-constant)
arithmetic-constant
scalar-reference
(scalar-expression)
*
You cannot specify the INITIAL attribute for a structure variable;
you must individually initialize the members of the structure. You
cannot specify the INITIAL attribute for a variable or member of a
structure that has any of the following attributes: DEFINED,
ENTRY, FILE, LABEL, PARAMETER, and UNION.
24.27 - INPUT
File description attribute. Specifies that a file will be accessed with GET or READ statements.
24.28 - INTERNAL
Scope attribute. Abbreviation: INT Limits the scope of a variable to the block in which it is declared and its contained blocks. This is the default.
24.29 - KEYED
File description attribute. Specifies that a file may be accessed randomly by key. Valid for indexed sequential and relative files and for sequential disk files with fixed-length records.
24.30 - LABEL
Noncomputational data type attribute. Defines a label variable. Only one label is permitted per statement. The following statements cannot have labels: DECLARE, %INCLUDE, or statements beginning ON-units. A label must be terminated with a colon (:). When a label is subscripted, for example: LABL(1): its appearance is the implicit declaration of an array of label constants.
24.31 - Length
Data type attribute. Specifies a length for a string variable or the number of elements in a dimension of an array. For more information, type HELP PLI ATTRIBUTE EXTENT
24.32 - LIKE
Member attribute Copies the member declarations contained within a major or minor structure declaration into the structure variable to which it is applied. level-number identifier [attributes] LIKE reference
24.33 - LIST
Argument passing attribute. Specifies that a parameter can accept a list of actual parameters, of arbitrary length.
24.34 - MEMBER
Member attribute. Specifies that an item is a member of a structure.
24.35 - NONVARYING
Computational data type attribute. Abbreviation: NONVAR Specifies that the length of a string is nonvarying.
24.36 - OFFSET
Storage class attribute. Defines an offset variable whose value represents the position of a variable within an area. OFFSET [ (area-reference) ]
24.37 - OPTIONS
Specifies options for various attributes or I/O statements.
24.38 - OPTIONAL
Argument passing attribute. Specifies, in the declaration of a formal parameter, that the actual parameter need not be specified in a call.
24.39 - OUTPUT
File description attribute. Specifies that a file will be accessed with PUT or WRITE statements.
24.40 - PARAMETER
Argument passing attribute. Abbreviation: PARM Indicates that a variable will be assigned a value when it is used as an argument to a procedure. Is applied by default to variables whose names are specified in a parenthesized list in a PROCEDURE or ENTRY statement. The parameter is assigned a value by means of an argument list when the procedure is invoked; it shares the storage of its associated argument.
24. 40.1 - Descriptor
Describes the data type of the parameters for an external
procedure. A parameter descriptor is specified following the ENTRY
attribute in the declaration of the external procedure. The data
type attributes of the parameters are matched with the attributes
of the arguments specified in the actual invocation of the
procedure.
Example: DCL X ENTRY (CHARACTER(30), FIXED BIN(31));
CALL X(A,B);
Where the PROCEDURE statement for X may be specified:
X: PROCEDURE (STRING,COUNT);
The parameters STRING and COUNT must be declared with data type
attributes within X.
Attributes for each parameter must be separated by commas.
24.41 - PICTURE
Data type attribute. Abbreviation: PIC Specifies the format of numeric data stored as a character string. PICTURE'picture-specification' where picture-specification consists of a string of picture characters that define the numeric and character representation of the variable.
24. 41.1 - Characters
9 The corresponding position contains a decimal digit.
Z Same as 9, except that the digit is replaced with a space
if it is a leading zero.
* Same as 9, except that the digit is replaced with an asterisk
if it is a leading zero.
Y Same as 9, except that all zeros are replaced by spaces.
T Position of digit and encoded plus or minus sign.
I Position of digit and encoded plus sign if number is not negative.
R Position of digit and encoded minus sign if number is negative.
V The position of the assumed decimal point (gives the scale
of the pictured value).
. The corresponding position contains a period.
, The corresponding position contains a comma.
/ The corresponding position contains a slash.
B The corresponding position is a space.
CR The corresponding positions contain the letters CR if the
number is less than 0 (otherwise, spaces). Must be to the right
of all digit characters.
DB The corresponding positions contain the letters DB if the
number is less than 0 (otherwise, spaces). Must be to the right
of all digit characters.
$ The corresponding position contains a dollar sign. If the
$ character is repeated, corresponding positions except the
first all contain digits, and a dollar sign precedes the first
significant digit.
S The corresponding position contains a plus sign or minus
sign, depending on the number's value. The S character can be
repeated with an effect similar to that of the dollar sign.
+ The corresponding position contains a plus sign if the number
is greater than or equal to 0. (Otherwise, the + character
can be repeated with an effect similar to the dollar sign.)
- The corresponding position contains a minus sign if the number
is less than 0. (Otherwise, the - character can be repeated
with an effect similar to the dollar sign.)
(n) Integer iteration factor for the subsequent character.
24.42 - POINTER
A pointer is a data item whose value is the address in memory of another data item. Storage class attribute. Abbreviation: PTR Defines a pointer variable.
24.43 - POSITION
Specifies the character or bit position in a DEFINED variable's base variable at which the DEFINED variable begins. POSITION (expression)
24.44 - PRECISION
Computational data type attribute. Abbreviation: PREC
Specifies the number of binary or decimal digits used to represent
an arithmetic value. Gives the number of digits in the mantissa of
a floating-point value and the total number of integral and
fractional digits in a fixed-point value. Ranges and defaults are:
BINARY FIXED range: 1 <= p <= 31 default: 31
BINARY FLOAT range: 1 <= p <= 113 default: 24 (OpenVMS VAX)
BINARY FLOAT range: 1 <= p <= 53 default: 24 (OpenVMS AXP)
DECIMAL FIXED
precision range: 1 <= p <= 31 default: 10
scale range: <= p
DECIMAL FLOAT range: 1 <= p <= 34 default: 7 (OpenVMS VAX)
DECIMAL FLOAT range: 1 <= p <= 15 default: 7 (OpenVMS AXP)
24.45 - PRINT
File description attribute. Specifies that an output file is to be formatted for printing. Implies STREAM OUTPUT.
24.46 - READONLY
Storage class attribute. Specifies that a static variable's value does not change during program execution.
24.47 - RECORD
File description attribute. Specifies that a file will be accessed by record I/O statements.
24.48 - REFER
Member attribute
Defines dynamically self-defining structures. It may be applied to
array, string, and area extents.
refer-element REFER (refer-object-reference)
for example:
DECLARE 1 STRUCTURE BASED (P),
2 I FIXED BINARY(31),
2 A CHARACTER (20 REFER(I)),
I is the refer object, 20 is the refer element, and I is the refer
object reference.
24.49 - REFERENCE
Argument passing attribute. Abbreviation: REF Requests that an argument be passed to an external non-PL/I procedure by reference.
24.50 - RETURNS
May be specified in two contexts (1) as an attribute in the declaration of an external entry or in a %PROCEDURE declaration, and (2) as an option on a PROCEDURE or ENTRY statement for a function. In either context, it describes the value returned by a function. RETURNS (returns-descriptor) where the returns-descriptor specifies the data type attributes of the return value, which must be scalar.
24.51 - SEQUENTIAL
File description attribute. Abbreviation: SEQL Specifies that a file will be accessed by READ and WRITE statements.
24.52 - STATIC
Storage class attribute. Requests static allocation of storage such that a variable's value is preserved when its declaring block is deactivated. A static variable may be initialized with the INITIAL attribute.
24.53 - STREAM
File description attribute. Specifies that a file will be accessed by GET or PUT statements.
24.54 - STRUCTURE
Specifies that a variable is a structure variable.
24.55 - UNION
Member attribute Allows minor structure members to be declared with their starting offsets identical relative to the containing structure, thus signifying that they occupy the same storage. level-number identifier [storage class] UNION
24.56 - TRUNCATE
Argument passing attribute. Specifies, in the declaration of a formal parameter, that the actual parameter list can be truncated at the point where this argument should occur.
24.57 - UNALIGNED
Abbreviation: UNAL Specifies nonalignment for a bit-string variable in storage.
24.58 - UPDATE
File description attribute. Specifies that a file will be accessed by READ, REWRITE, and DELETE statements.
24.59 - VALUE
(1) Storage class attribute. Requests that a global symbol be accessed by value rather than by reference. Must be declared with either GLOBALREF or GLOBALDEF. If declared with GLOBALDEF, INITIAL must be specified. VALUE can be applied only to the data types BIT (32) ALIGNED and FIXED BINARY. (2) Argument passing attribute. Specifies that an argument be passed to a non-PL/I procedure by immediate value. In this context, VALUE may only be specified in a parameter descriptor following the ENTRY attribute. The valid data types that can be passed this way are: POINTER, BIT (with a length of 32 or less), FIXED BINARY, and ENTRY.
24.60 - VARIABLE
Has two meanings (1) VARIABLE attribute (2) VARIABLE option The VARIABLE attribute may be applied to entry and file data. OPTIONS(VARIABLE) specifies that a non-PL/I external entry may be called with non-required arguments omitted from the argument list. Example: DCL E ENTRY(ANY) OPTIONS(VARIABLE);
24.61 - VARYING
Data type attribute. Abbreviation: VAR Defines a varying-length string. Can be specified only with CHARACTER.
| 25 - Conditions |
These condition names may be specified in an ON, SIGNAL, RESIGNAL, or REVERT statement. ANYCONDITION AREA CONDITION CONVERSION ENDFILE (file-reference) ENDPAGE (file-reference) ERROR FINISH FIXEDOVERFLOW KEY (file-reference) OVERFLOW STORAGE STRINGRANGE SUBSCRIPTRANGE UNDEFINEDFILE (file-reference) UNDERFLOW VAXCONDITION (integer-expression) ZERODIVIDE
| 26 - ENVIRONMENT Options |
ENVIRONMENT options may be specified on the ENVIRONMENT attribute in the declaration of a file or on the OPEN statement for the file. Some options may be specified on CLOSE.
26.1 - APPEND
Places output for a file at the end of an existing file.
26.2 - BACKUP_DATE
Overrides the default backup date of a file.
26.3 - BATCH
Submits a copy of the file to the system batch job queue on close. Valid on the CLOSE statement.
26.4 - BLOCK_BOUNDARY_FORMAT
Indicates that records must not cross block boundaries.
26.5 - BLOCK_IO
Specifies a file will be read or written by blocks instead of records. Valid for sequential disk files and magnetic tape files.
26.6 - BLOCK_SIZE
Specifies the size of a block for a magnetic tape file. BLOCK_SIZE (integer-expression)
26.7 - BUCKET_SIZE
Defines the number of 512-byte blocks in a bucket for an indexed sequential or a relative file. BUCKET_SIZE (integer-expression)
26.8 - CARRIAGE_RETURN_FORMAT
Indicates that records in the file will be output with default carriage control. Each record is preceded by a carriage return and followed by a line feed.
26.9 - CONTIGUOUS
Specifies that an output file must be placed in a physically contiguous extent on disk.
26.10 - CONTIGUOUS_BEST_TRY
Requests that if possible an output file be placed in a physically contiguous extent on disk.
26.11 - CREATION_DATE
Overrides default creation date of file. CREATION_DATE (variable-reference) The variable-reference must be to a BIT(64) ALIGNED variable containing a system time value.
26.12 - CURRENT_POSITION
Leaves magnetic tape positioned at last close.
26.13 - DEFAULT_FILE_NAME
Defines a default file specification for a file. DEFAULT_FILE_NAME (string-expression)
26.14 - DEFERRED_WRITE
Requests file system optimization of output.
26.15 - DELETE
Specifies that the file be deleted when it is closed. Valid on the CLOSE statement.
26.16 - EXPIRATION_DATE
Defines the expiration date for a file. EXPIRATION_DATE (variable-reference) The variable-reference must be to a BIT(64) ALIGNED variable containing a system time value.
26.17 - EXTENSION_SIZE
Specifies a default extension size for a disk file to be used for this open. EXTENSION_SIZE (integer-expression) The extension size is expressed in terms of 512-byte disk blocks.
26.18 - FILE_ID
Identifies a file by its internal file identification. FILE_ID (variable-reference) The variable-reference must indicate an array of (6) FIXED BIN(31).
26.19 - FILE_ID_TO
Obtains the file identification of a file when it is opened. FILE_ID_TO (variable-reference) The variable-reference must indicate an array of (6) FIXED BIN(31).
26.20 - FILE_SIZE
Defines the initial number of 512-byte blocks to allocate for a file. FILE_SIZE (integer-expression)
26.21 - FIXED_CONTROL_SIZE
Defines records as variable-length with a fixed-length control area and specifies the size of the fixed control area. FIXED_CONTROL_SIZE (integer-expression)
26.22 - FIXED_CONTROL_SIZE_TO
Obtains the size of the fixed-control area of a file with variable with fixed-length control records. FIXED_CONTROL_SIZE_TO (variable-reference) The variable-reference must indicate a FIXED BINARY(31) variable.
26.23 - FIXED_LENGTH_RECORDS
Specifies a file with fixed-length records.
26.24 - GROUP_PROTECTION
Defines the type of file access allowed to members of the owner's group. GROUP_PROTECTION (string-expression) The string-expression can be composed of up to four of the characters R, W, E, and D.
26.25 - IGNORE_LINE_MARKS
Specifies that end-of-line indicators are not to be treated as field delimiters in GET LIST statements.
26.26 - INDEX_NUMBER
Specifies the alternate index to use in accessing records in an indexed sequential file. INDEX_NUMBER (integer-expression)
26.27 - INDEXED
Defines an indexed sequential file.
26.28 - INITIAL_FILL
Requests the file system to leave unused space in disk buckets when an indexed sequential file is initially loaded.
26.29 - MAXIMUM_RECORD_NUMBER
Specifies the largest record number that will be valid for records in a relative file. MAXIMUM_RECORD_NUMBER (integer-expression)
26.30 - MAXIMUM_RECORD_SIZE
Specifies the maximum size of records in the file. MAXIMUM_RECORD_SIZE (integer-expression)
26.31 - MULTIBLOCK_COUNT
Specifies the number of 512-byte blocks to allocate for file system buffering. MULTIBLOCK_COUNT (integer-expression)
26.32 - MULTIBUFFER_COUNT
Specifies the number of buffers to allocate for file system buffering. MULTIBUFFER_COUNT (integer-expression)
26.33 - NO_SHARE
Prohibits all type of shared access to the file.
26.34 - OWNER_GROUP
Specifies the group number in the user identification code (UIC) of the owner of the file. OWNER_GROUP (integer-expression)
26.35 - OWNER_ID
Specifies the entire 32-bit identifier of the owner of a file. Can be used instead of OWNER_GROUP and OWNER_MEMBER.
26.36 - OWNER_MEMBER
Specifies the member number in the user identification code (UIC) of the owner of the file. OWNER_MEMBER (integer-expression)
26.37 - OWNER_PROTECTION
Specifies the type of file access allowed the owner of the file. OWNER_PROTECTION (string-expression) The string-expression can be composed of up to four of the characters R, W, E, and D.
26.38 - PRINTER_FORMAT
Specifies that records in the file will be printed using printer format carriage control embedded in the fixed control area of the records.
26.39 - READ_AHEAD
Requests file system optimization on read operations.
26.40 - READ_CHECK
Requests verification of read operations.
26.41 - RECORD_ID_ACCESS
Indicates that records will be accessed by internal file system identification.
26.42 - RETRIEVAL_POINTERS
Specifies the number of file system pointers to maintain for file access. RETRIEVAL_POINTERS (integer-expression)
26.43 - REVISION_DATE
Overrides the default revision date of a file. Valid on the CLOSE statement only.
26.44 - REWIND_ON_CLOSE
Requests that a magnetic tape volume be rewound when the file is closed. Valid on the CLOSE statement.
26.45 - REWIND_ON_OPEN
Requests that a magnetic tape volume be rewound when the file is opened.
26.46 - SCALARVARYING
Specifies that varying character strings will be read/written using the entire storage of the variable.
26.47 - SHARED_READ
Allows other users to read records in the file.
26.48 - SHARED_WRITE
Allows other users to write records in the file.
26.49 - SPOOL
Queues a copy of the file to the system printer when the file is closed. Valid on the CLOSE statement.
26.50 - SUPERSEDE
Replaces an existing file with the same file name, file type, and version number.
26.51 - SYSTEM_PROTECTION
Defines the type of file access allowed to users with system user identification codes. SYSTEM_PROTECTION (string-expression) The string-expression can be composed of up to four of the characters R, W, E, and D.
26.52 - TEMPORARY
Specifies a temporary file for which no directory entry is made. The file can be accessed later for deletion only if its file identification is saved. The file identification can be obtained by specifying the FILE_ID_TO option.
26.53 - TRUNCATE
Truncates a sequential file at its logical end-of-file when it is closed. Valid on the CLOSE statement.
26.54 - USER_OPEN
Specifies a user-written function to open a file.
26.55 - WORLD_PROTECTION
Specifies the type of file access allowed to general system users. WORLD_PROTECTION (string-expression) The string-expression can be composed of up to four of the characters R, W, E, and D.
26.56 - WRITE_BEHIND
Requests file system optimization on output
26.57 - WRITE_CHECK
Requests verification of output operations.
| 27 - Error Messages |
VAX PL/I run-time error messages
27.1 - ANYCOND
PL/I ANYCONDITION condition. Fatal. This error message is displayed when ANYCONDITION is specifically signaled and there is no ON-unit for ANYCONDITION. User Action. Write an ON-unit to handle ANYCONDITION, or do not signal ANYCONDITION. Correct the source program.
27.2 - AREA
PL/I AREA condition. Fatal. The PL/I AREA condition was raised either by a SIGNAL AREA statement, or by the PL/I run-time library. User Action. If the exception was raised by the RTL, see the secondary condition for more information.
27.3 - AREA_ACTIVE
Operation attempted on an already active area. Informational. The PL/I run-time library detected that an area it was about to perform an operation on is already active. If this condition occurs, it is typically because an operation is being attempted on an area from both AST level and non-AST level simultaneously, or because the area is in a shared memory environment and being modified by more than one processor at once. User Action. Rewrite the application to avoid simultaneous modification of an area. If that is not desirable, you may want to consider handling the condition with an ON-unit. See the PL/I for OpenVMS Systems User Manual for more information.
27.4 - AREA_ASSIGN
Target area in area assignment is too small. Informational. An assignment was attempted and the size of the target area was insufficient to hold the extent of the source area. User Action. Correct the situation that caused the problem to occur, or add an ON-unit to process the condition.
27.5 - AREA_FORMAT
Operation attempted on an incorrectly formatted area. Informational. The PL/I run-time library detected an area to be incorrectly formatted while attempting an allocation or deallocation in the area, or while performing an area assignment from the area. User Action. The area can be corrupt because it was never initialized with the EMPTY() built-in function, or because of invalid pointer references or data access.
27.6 - AREA_FREE
Error detected deallocating a variable in an area. Informational. The PL/I run-time library detected that a FREE operation in an area was not valid. For example, the variable being freed incorrectly extends beyond the end of the area, extends into a free section of the area, or is already in a free section of of the area. This problem normally arises when a variable of a different size than the one originally allocated is used for the free, or when the variable is freed more than one time. User Action. Correct the logic problem in the source program.
27.7 - AREA_FULL
No room for variable allocation in area at address <entity>. Informational. An allocation was attempted in an area that could not be performed because the area did not have enough contiguous space to allocate the variable requested. The address of the area is in hexadecimal. User Action. Handle the condition. See the PL/I for OpenVMS Systems User Manual more information.
27.8 - AREA_INACTIVE
Attempt to unlock an area failed. Informational. The PL/I run-time library detected an error while attempting to unlock the interlock bit on an area after performing an operation on the area. This error can be caused by assigning to the target area while another operation is active, since area assignment cannot be fully interlocked. User Action. Rewrite the application to avoid assignment to an area while another operation is in progress.
27.9 - AREA_SIZE
Impossible to allocate variable in area. Informational. An allocation was attempted in an area that could not be performed because the size requested was too large to be allocated from the area, even if the area was empty. User Action. Correct the situation that caused the problem to occur.
27.10 - AUTOINIT
Error in automatic initialization. Fatal. An automatic variable declared with the INITIAL attribute cannot be initialized. This error can be caused by a negative repetition factor in an initial list, or when too few or too many values are specified in the initialization of an array. PL/I also does not allow automatic initialization of automatic unconnected aggregates. User Action. Correct the initial list.
27.11 - BADATTR
File attributes conflict with request. Informational. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred, and submit an SPR.
27.12 - BADRTL
Invalid file control block or uninitialized FILE VARIABLE. Informational. A PL/I program was compiled with a field-test version of the PL/I compiler and linked with a later version of the run-time library. User Action. Determine what the correct run-time library is for your version of the compiler (ask your system manager or operator, if necessary). Recompile the program with the correct run-time library.
27.13 - BASECTLINIT
Error in BASED or CONTROLLED initialization. Fatal. A BASED or CONTROLLED variable declared with the INITIAL attribute cannot be initialized. This error can be caused by a negative repetition factor in an initial list, or when too few or too many values are specified in the initialization of an array. PL/I also does not allow automatic initialization of BASED or CONTROLLED unconnected aggregates. User Action. Correct the initial list.
27.14 - BIFSTAPOS
Starting position for a string built-in function is out of range. Informational. The third operand in a reference to an INDEX, SEARCH or VERIFY built-in function is beyond the range of the string. This condition is always signaled when strings are being processed by the PL/I run-time library, but it is raised for inline code only if the /CHECK qualifier was specified for the procedure containing the reference.
27.15 - CNVERR
Conversion error. Informational. An input or output value could not be converted as specified by the default conversion rules (for example, in list-directed stream I/O) or as specified by the corresponding format item (for edit-directed stream I/O). User Action. Examine the program logic and correct it if possible. If edit-directed stream I/O is being performed, check to ensure that the input or output value is matched to the correct format item.
27.16 - CONAPPSUP
APPEND and SUPERSEDE conflict. Informational. These ENVIRONMENT options conflict and must not be both specified for the same file. User Action. Determine whether you want to append new records to the existing file or to supersede it and write a new file. Correct the source program so that one of these options is not specified in the DECLARE or OPEN statement for the file.
27.17 - CONATTR
Conflicting attributes specified while opening file. Informational. A file was implicitly opened with an attribute that conflicts with an atttribute specified in the file's declaration. This error occurs when a file is declared with any of the following: the DIRECT and SEQUENTIAL attributes, the RECORD and STREAM attributes, or more than one of the attributes INPUT, OUTPUT, and UPDATE. User Action. Determine the correct set of attributes for the file, and correct the file's declaration.
27.18 - CONBLOKIO
BLOCK_IO conflicts with other attributes or options. Informational. The ENVIRONMENT option list for a file contains the BLOCK_IO option and one or more of the options that conflict with BLOCK_IO. User Action. Consult the description of the BLOCK_IO option in PL/I for OpenVMS Systems User Manual to determine the options that conflict, and examine the file's declaration and OPEN statement. Decide whether the file is to be opened for BLOCK_IO, and correct the program.
27.19 - CONDITION
PL/I CONDITION(entity) condition. Informational. A user-defined condition was signaled with the SIGNAL CONDITION(user-cond) statement. User Action. Do nothing, or add an ON-unit to handle the condition.
27.20 - CONENVOPT
DECLARED option conflicts with OPEN option. Informational. The value of an option specified in the ENVIRONMENT option list in the declaration of a file conflicts with the value specified on the OPEN statement for the file. User Action. Determine which value is the correct value for the option, and correct either the file's declaration or the OPEN statement.
27.21 - CONFIXLEN
FIXED_LENGTH_RECORDS conflicts with other attributes or options. Informational. The file's attribute list contains the FIXED_LENGTH_RECORDS option and an option that conflicts with it. User Action. Consult the option descriptions in the PL/I for OpenVMS Systems User Manual to determine the options in conflict, and correct the program.
27.22 - CONPRINTCR
CARRIAGE_RETURN_FORMAT conflicts with PRINT attribute. Informational. A PL/I file with the PRINT attribute has variable records with fixed-length control; the carriage control information is provided by PL/I. The CARRIAGE_RETURN_FORMAT option of ENVIRONMENT cannot be specified for it. User Action. Determine whether the file is to be a PL/I PRINT file or a file with OpenVMS carriage return format and correct the file's attribute list.
27.23 - CONPRTFRM
PRINTER_FORMAT conflicts with other attributes or options. Informational. The ENVIRONMENT option PRINTER_FORMAT conflicts with the CARRIAGE_RETURN_FORMAT option and with the PRINT and STREAM file description attributes. User Action. Correct the file's attribute list.
27.24 - CONVERSION
PL/I CONVERSION condition. Fatal. An invalid character was detected during the conversion of character data to another data type. (For example, the colon in '12:4' would cause conversion to be raised if this string was being converted to a FIXED value.) User Action. Correct the input data or add an ON-unit to handle the CONVERSION condition. Note that the ONSOURCE and ONCHAR built-in functions can be used to determine the source of the error, and that the corresponding pseudovariables can be used to correct the source string.
27.25 - CONVFILE
on file 'entity'. Informational. This displays the name of the file constant for which the conversion error occurred. User Action. None.
27.26 - CREINDEX
Attempting to create an indexed file. Use RMS Define. Informational. A file was opened with the OUTPUT attribute and with the ENVIRONMENT option INDEXED. You cannot create an indexed sequential file in a PL/I program. Indexed files can be opened only for UPDATE or INPUT. User Action. Use the RMS utility program FDL to create the file. Correct the program to open the file with the UPDATE attribute and write records to it.
27.27 - CVTPICERR
Error in picture conversion. Informational. A value could not be edited as specified by the corresponding picture. User Action. If the value is negative, be sure that the picture includes one of the sign characters.
27.28 - ENDFILE
PL/I ENDFILE condition on file 'entity'. Fatal. This message is displayed when a READ or GET statement attempts to access data that is beyond the end of the given file. The message is displayed only when no user-specified ON-unit exists to handle the end-of-file condition for the given file. User Action. Provide an ON-unit for the ENDFILE condition for the input file.
27.29 - ENDPAGE
PL/I ENDPAGE condition on file 'entity'. Warning. This message is displayed when a PUT statement causes the current line number to exceed the page size specified for a print file. The message is displayed only if there is no ON-unit within the file to handle the ENDPAGE condition for the given file. User Action. If your program is displaying lines on the terminal, you may want to include this statement: ON ENDPAGE(SYSPRINT); This null ON-unit causes PL/I to ignore the ENDPAGE condition when many lines are being written to the terminal. For other types of print files, you may want to take special action for the ENDPAGE condition and code an ON-unit to perform the action.
27.30 - ENDSTRING
End of string encountered during GET STRING or PUT STRING. Informational. A GET STRING statement attempted to read past the end of the source string variable, or a PUT STRING statement attempted to write past the end of the target string variable. This error occurs most frequently when a LIST option is specified on a GET STRING statement and the target string does not have either a trailing blank or a comma. User Action. Verify the length of the target or source string variable, the data types specified in the GET or PUT list, and correct the program.
27.31 - ENVPARM
PL/I compiler/run-time error. Please submit an SPR. Informational. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred and submit an SPR.
27.32 - ERROR
PL/I ERROR condition. Fatal. This message is displayed whenever the ERROR condition is signaled and not handled within the procedure. User Action. This message is usually followed by additional messages that indicate the specific error that occurred. Examine these messages to determine the corrective action required.
27.33 - FILEIDENT
PL/I compiler/run-time error. Please submit an SPR. Informational. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred and submit an SPR.
27.34 - FILENAME
File name: 'entity'. Informational. This message specifies the OpenVMS file specification of the file to which I/O was attempted. User Action. Examine this informational message to determine the full specification of the OpenVMS file on which the I/O that failed was attempted. From this name, you can verify whether the file was correctly specified in the TITLE option, whether the correct logical name assignments exist, whether the correct defaults are being applied, and so on.
27.35 - FINISH
PL/I Program FINISH condition. Success. This message is displayed when the FINISH condition is signaled and the program has no ON-unit for the FINISH condition. User Action. In many cases, this message is displayed when you have interrupted a program with Ctrl/C or Ctrl/Y and executed another program or a DCL command. In these cases, no action is required. Otherwise, you may want to write an ON-unit to respond specifically to the FINISH condition in a program. For a description of image exit, and the circumstances under which PL/I signals the FINISH condition, see the PL/I for OpenVMS Systems User Manual.
27.36 - FIXOVF
PL/I FIXEDOVERFLOW condition. Fatal. This message is displayed when the FIXEDOVERFLOW condition occurs or is signaled and no ON-unit exists for FIXEDOVERFLOW. User Action. Determine the variable whose value overflowed and give it a larger precision, or verify that the program logic is correct and is not trying to assign a value larger than it should to the variable. If the condition is expected, code an ON-unit in your program that handles this condition.
27.37 - FORMATOVFL
Too many iteration factors or remote formats. Informational. A format list is too complex to be interpreted. User Action. Simplify the stream I/O statement.
27.38 - FXCSIZ
FIXED_CONTROL_SIZE incorrect. Informational. The size of the variable specified in the FIXED_CONTROL_FROM or FIXED_CONTROL_TO option does not match the size of the file's fixed-control area. User Action. Determine the correct size of the fixed-control area, and correct the source program or verify that the correct file is being accessed.
27.39 - INCRETURN
RETURN statement is incompatible with ENTRY. Fatal. A procedure does not have the RETURNS attribute, but an entry within that procedure specifies the RETURNS option and attempts to execute a RETURN statement. User Action. Correct the source program by specifying the RETURNS attribute on the PROCEDURE statement or by removing it from the ENTRY statement.
27.40 - INTERNAL
PL/I compiler/run-time error. Please submit an SPR. Fatal. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred and submit an SPR.
27.41 - INVBKTSIZ
Invalid BUCKET_SIZE specified. Informational. The value specified in the BUCKET_SIZE ENVIRONMENT option is not in the range 0 through 32. The largest number of blocks allowed in a bucket by VAX RMS is 32. User Action. Select a bucket size that is in the correct range, and correct the source program.
27.42 - INVBLKSIZ
Invalid BLOCK_SIZE specified. Informational. The value specified in the BLOCK_SIZE ENVIRONMENT option is not in the range 20 through 65532 or is not 0. User Action. Select a block size that is in the valid range, and correct the program.
27.43 - INVDATYP
Invalid data type for record I/O. Informational. The data type of a variable in a record I/O statement is not a computational data type; or the data type is computational but is an unconnected array or structure, an unaligned bit string, or an aggregate of unaligned bit strings. User Action. Verify that the correct variable name was specified in the I/O statement. If the variable is an aggregate, you may have to redimension or restructure it so that the required array is connected.
27.44 - INVDFNAM
Invalid DEFAULT_FILE_NAME. Informational. The expression value specified in the DEFAULT_FILE_NAME ENVIRONMENT option is not a valid character-string expression, or it is longer than 128 characters. User Action. Verify that the expression is correctly specified, if a variable reference is specified, that the reference is correct. Correct the source program.
27.45 - INVEXTSIZ
Invalid EXTENSION_SIZE specified. Informational. The value specified in the EXTENSION_SIZE option of ENVIRONMENT is not in the range 0 through 65535 or is not a valid integer expression. User Action. Correct the expression.
27.46 - INVFMTPARM
Invalid format parameter specified. Informational. A value specified for a format item was not a positive integer, or the value was not in the valid range for the given format item. For example, this error occurs if a negative number is specified for the A or B format item, or if a value greater than 31 is specified for the F format item. User Action. Correct the value specified for the format item in the source program.
27.47 - INVFORGKEY
Invalid file organization for KEYED access. Informational. The KEYED attribute was specified for a file that cannot be accessed by key, for example, a magnetic tape file. User Action. Verify that the correct file is being opened by checking the TITLE and DEFAULT_FILE_NAME options, if any, logical name assignments, and file specification defaults. If the file is the expected file, correct the attribute list so that it does not specify the KEYED attribute.
27.48 - INVFORMAT
PL/I compiler/run-time error. Please submit an SPR. Informational. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred and submit an SPR.
27.49 - INVFXCSIZ
Invalid FIXED_CONTROL_SIZE specified. Informational. The value specified in the FIXED_CONTROL_SIZE ENVIRONMENT option is not in the range 0 through 255. User Action. Verify that the expression in the FIXED_CONTROL_SIZE option is correctly specified or that it refers to the correct variable. Or choose a fixed-control size that is within the valid range. Correct the program.
27.50 - INVINDNUM
Invalid INDEX_NUMBER specified. Informational. The value specified for the INDEX_NUMBER option does not have a corresponding index in the indexed sequential file. User Action. Verify that the expression specified in the option is correct or that it refers to the correct variable. Or specify an index number that is in the proper range, ensuring that the indexed sequential file was defined with the correct number of index keys. Correct the program.
27.51 - INVMAXREC
Invalid MAXIMUM_RECORD_SIZE specified. Informational. The value specified for the MAXIMUM_RECORD_SIZE option of ENVIRONMENT is not in the range 0 through 32767. User Action. Correct the value so that it is not larger than 32767.
27.52 - INVMLTBLK
Invalid MULTIBLOCK_COUNT specified. Informational. The value specified in the MULTIBLOCK_COUNT count of the ENVIRONMENT option is not in the range 0 through 127, or is not a valid integer expression. User Action. Verify that the expression in the MULTIBLOCK_COUNT option is correct, or that the correct variable reference is specified. Correct the program.
27.53 - INVMLTBUF
Invalid MULTIBUFFER_COUNT specified. Informational. The value specified in the MULTIBUFFER_COUNT count of the ENVIRONMENT option is not in the range -128 through 127, or is not a valid integer expression. User Action. Verify that the expression in the MULTIBUFFER_COUNT option is correct, or that the correct variable reference is specified. Correct the program.
27.54 - INVNUMOPT
PL/I compiler/run-time error. Please submit an SPR. Informational. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred and submit an SPR.
27.55 - INVOWNGRP
Invalid OWNER_GROUP specified. Informational. The value specified for the OWNER_GROUP ENVIRONMENT option is not in the range 0 through 16383, or is not a valid integer expression. User Action. Correct the program.
27.56 - INVOWNMEM
Invalid OWNER_MEMBER specified. Informational. The value specified for the OWNER_MEMBER ENVIRONMENT option is not in the range 0 through 65535, or is not a valid integer expression. User Action. Correct the program and recompile.
27.57 - INVPROT
Invalid protection string specified. Informational. The value specified for one of the ENVIRONMENT options GROUP_PROTECTION, OWNER_PROTECTION, SYSTEM_PROTECTION, or WORLD_PROTECTION is not a valid string expression; the string contains more than four characters; or the string contains characters other than the characters R, W, E, or D, or their lowercase equivalents. User Action. Correct the value specified in the option, and recompile the program.
27.58 - INVRADIX
An invalid radix was specified. Fatal. The radix specified for the ENCODE or DECODE built-in function was not a value between 2 and 16. User Action. Change the radix to a value between 2 and 16.
27.59 - INVRTVPTR
Invalid RETRIEVAL_POINTERS specified. Informational. The value specified for the ENVIRONMENT option RETRIEVAL_POINTERS is not in the range -1 through 127, or is not a valid integer expression. User Action. Verify that the expression specified in the RETRIEVAL_POINTERS option is a valid integer expression or, if a variable reference is specified, that it refers to the appropriate variable. Correct the program.
27.60 - INVSKIP
Invalid value for SKIP option specified. Informational. The value specified in a SKIP option is zero (on an input operation) or is negative (for either an input or an output operation). User Action. Determine the value of the SKIP option; if a variable reference is specified, verify that the variable contains the correct value.
27.61 - INVSTRFMT
Invalid format item for STRING I/O. Informational. One of the format items COL, SKIP, LINE, PAGE, or TAB was specified in a GET STRING or PUT STRING statement. These format items are not valid for these statements. User Action. Correct the format list for the statement that caused the error.
27.62 - INVSTRING
Invalid character encountered in string. Fatal. Invalid characters were specified for the string argument of the DECODE built-in function. User Action. Remove the invalid characters.
27.63 - INVTIME
Invalid timeout value specified. Fatal. An invalid timeout value has been specified. The number of seconds to wait must be less than 256. User Action. Correct the timeout value.
27.64 - INV_KEY
Invalid KEY data type. Informational. The data type of a key in an indexed sequential file is not a data type known to PL/I. User Action. Verify that the file has not been corrupted. Revert to an earlier version of the file, if possible.
27.65 - IOERROR
I/O error on file 'entity'. Informational. This informational message indicates that an error occurred during an I/O operation. User Action. Examine the accompanying messages to determine the error.
27.66 - KEY
PL/I KEY condition on file 'entity'. Fatal. This message is followed by one or more messages that indicate the specific error that occurred while processing the key on the given file. User Action. Determine the specific error that occurred by examining the accompanying RMS message. Verify in your program that the correct key value was specified in the I/O statement, that the data type of the key value can be converted to the data type of the given key, and so on. Also determine whether the file to which the I/O was attempted is the correct file. If appropriate, write an ON-unit to handle the KEY condition.
27.67 - LABELRANGE
Uninitialized label subscript used. Fatal. A label subscript is specified with a variable reference but the variable is not initialized. User Action. Correct the program's logic so that the variable has a valid value.
27.68 - LINESIZE
Invalid LINESIZE specified. Informational. The value specified in the LINESIZE option exceeds the implementation's limit of 32767 or the value is not a positive integer value. User Action. Correct the LINESIZE option.
27.69 - LINOVRFLO
Line number overflow. Informational. The number of lines on a stream file page exceeds the implementation's limit of 32767. User Action. Write an ON-unit using the VAXCONDITION or ANYCONDITION to handle the condition.
27.70 - NAME
PL/I compiler/run-time error. Please submit an SPR. Fatal. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred and submit an SPR.
27.71 - NOCURREC
No current record. Informational. A DELETE or REWRITE statement was specified for a file opened with the UPDATE attribute, but the KEY option was not specified. These statements may omit the KEY option only if the "current record" contains a valid value. User Action. Correct the statement in the source program and recompile.
27.72 - NOFROM
No FROM specified or buffer not allocated. Informational. A REWRITE statement was specified without the FROM option. The REWRITE statement is valid without the FROM option only if a previous READ statement on the file specified the SET option to allocate a buffer and set a pointer to the record read. User Action. Correct the previous READ statement for the file so that it specifies the SET option, or correct the REWRITE statement so that it specifies the FROM option.
27.73 - NOKEY
No KEY or KEYFROM specified. Informational. A keyed I/O statement must specify a KEY or KEYFROM option. User Action. Correct the statement and recompile the program. If you are attempting sequential access to a file, verify that you have also specified SEQUENTIAL in the file's attribute list.
27.74 - NOSELECT
No WHEN clause selected and no OTHERWISE specified. Fatal. It is possible to omit either the WHEN or OTHERWISE clause, but if no WHEN clause is selected, then an OTHERWISE clause must be present. User Action. Include an OTHERWISE clause in the SELECT-group.
27.75 - NOSHARE
SHARED_READ or SHARED_WRITE conflict with NO_SHARE. Informational. The ENVIRONMENT options SHARED_READ and SHARED_WRITE permit read or write sharing on a file, but the NO_SHARE option prohibits all sharing. User Action. Determine whether the file is to be accessed for sharing. If not, delete the option in error. If it is to be shared, delete the NO_SHARE option.
27.76 - NOTIMPL
The image being run requires a more recent version of PLIRTL. Fatal. This message is displayed when an image containing PL/I code is moved to a system with an older version of PLIRTL that does not support a function that is required to run the program. User Action. Upgrade the system to the necessary level to run the program.
27.77 - NOTINDEXED
Requested operation requires an INDEXED file. Informational. A keyed I/O statement specifies an operation that is valid only for a file with indexed sequential file organization. User Action. Determine from the information in the FILENAME message whether the operation was requested to the appropriate file. If the file is correctly specified but is not an indexed file, it may not have been properly created.
27.78 - NOTINPUT
Attempting to GET from an OUTPUT or UPDATE file. Informational. A GET statement is not valid on a file that is opened with the OUTPUT or UPDATE attributes. User Action. Correct the file's attribute list.
27.79 - NOTKEYD
Not a KEYED file. Informational. A KEY or KEYFROM option was specified in a record I/O statement for a file that does not have the KEYED attribute. User Action. Verify that the file is a keyed file, and if it is, correct the DECLARE or OPEN statement for the file so that it specifies the KEYED attribute.
27.80 - NOTOUT
Attempting to PUT to an INPUT or UPDATE file. Informational. The PUT statement is not valid for files that are opened with the INPUT or UPDATE attribute. User Action. Correct the file's attribute list.
27.81 - NOTPRINT
PAGE or LINE specified for non-PRINT file. Informational. The PAGE and LINE options of the PUT statement are valid only for files that are opened with the PRINT attribute. User Action. Verify that the file is a stream output file and if so, add PRINT to the file's attribute list and recompile.
27.82 - NOTREC
Not a RECORD file. Informational. A record I/O statement (READ, WRITE, DELETE, or REWRITE) was specified for a file that has the STREAM attribute. User Action. Correct the file's attribute list or use a stream I/O statement to process the file and recompile.
27.83 - NOTRELSQL
Not a RELATIVE or SEQUENTIAL file ) Fatal. The LOCK_NONEXISTENT record option may only be used with relative or sequential files. User Action. Remove the LOCK_NONEXISTENT option or use a different file organization.
27.84 - NOTSQL
Not a SEQUENTIAL file. Informational. A sequential READ or WRITE statement was specified for a file that has the DIRECT attribute. The I/O statement must specify a KEY or KEYFROM option. User Action. Decide whether the file was to be accessed sequentially or directly, and correct the I/O statement that caused the error.
27.85 - NOTSTREAM
Stream I/O attempted on RECORD file. Informational. A GET or PUT statement was used to process a file that has the RECORD attribute. User Action. Correct the file's attribute list, remembering that certain file description attributes imply the RECORD attribute, and recompile the program.
27.86 - NOTUPDATE
Attempting to REWRITE or DELETE an INPUT or OUTPUT file. Informational. The REWRITE and DELETE statements are not valid for files that are opened with either the INPUT or OUTPUT attributes; the file must have the UPDATE attribute. User Action. Correct the file's attribute list and recompile.
27.87 - NOVIRMEM
Virtual memory overflow. Informational. The run-time system attempted to allocate virtual memory for an I/O buffer in the program, but there was insufficient virtual memory available. User Action. Simplify the source program so that it requires less space.
27.88 - ONCNVPOS
The erroneous character is at position entity. Informational. This message displays an uparrow below the character in error in the ONSOURCE message. User Action. Use the information to correct the source field of the conversion.
27.89 - ONSNOTMOD
ONSOURCE value not modified. Informational. A normal return occurred from a CONVERSION condition, which would normally result in a retry of the conversion. However, the ONSOURCE value was not modified, so the ERROR condition was raised to prevent an infinite loop. User Action. Change the ON unit handling the condition to modify the ONSOURCE value using either the ONSOURCE or ONCHAR pseudovariables.
27.90 - ONSOURCE
The conversion source is 'entity'. Informational. This displays the source string User Action. None.
27.91 - OPEN
Open failure. Informational. An attempt was made to open a file implicitly by an I/O statement, but the file could not be opened. The UNDEFINEDFILE condition was signaled, but the ON-unit did not successfully open the file. User Action. Write an ON-unit to handle the UNDEFINEDFILE condition for the given file to ensure that the file will be opened.
27.92 - PAGESIZE
Invalid PAGESIZE specified. Informational. The value specified in the PAGESIZE option exceeds the implementation's limit of 32767 or the value is not a positive integer. User Action. Correct the value specified in the PAGESIZE option.
27.93 - PAGOVRFLO
Page number overflow. Informational. The number of pages in a stream file exceeds the implementation's limit of 32767. User Action. Write an ON-unit using the VAXCONDITION or ANYCONDITION to handle the condition.
27.94 - PARM
PL/I compiler/run-time error. Please submit an SPR. Informational. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred and submit an SPR.
27.95 - PROMPTOBIG
PROMPT option too long. Must be less than 254 characters. Informational. The string specified in the PROMPT option of the GET statements exceeds the maximum length of 253 characters. User Action. Shorten the prompting string.
27.96 - READOP
PL/I compiler/run-time error. Please submit an SPR. Informational. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred and submit an SPR.
27.97 - READOUT
Attempting to READ from an OUTPUT file. Informational. A file that is opened with the OUTPUT attribute cannot be accessed with a READ statement. If you are attempting to read a file that was just written, you must first close the file and reopen it with the INPUT attribute. User Action. Correct the source program and recompile.
27.98 - RECID
File not open for RECORD_ID_ACCESS. Informational. The RECORD_ID_TO and RECORD_ID_FROM options are valid only if the file's ENVIRONMENT option list specified RECORD_ID_ACCESS. User Action. Correct the ENVIRONMENT option list.
27.99 - RECIDKEY
RECORD_ID_FROM conflicts with KEY or KEYFROM. Informational. A record I/O statement may not specify the KEY or KEYFROM option and the RECORD_ID_FROM option at the same time. User Action. Correct the statement.
27.100 - RECLOCOPT
The record locking options 'entity' and 'entity' conflict. Informational. The specified record locking options conflict with each other. User Action. Remove some of the options.
27.101 - RECORD
Record length does not match target length. Informational. A fixed-length character string buffer is not the same length as a record being read by a READ statement or an area is too small to hold the extent of an area being read into it. User Action. Verify that the variable to which you are transferring data is the correct length for the records in the file. Correct the source program.
27.102 - RECORDCND
PL/I compiler/run-time error. Please submit an SPR. Fatal. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred and submit an SPR.
27.103 - RECURSIO
Illegal recursive I/O attempted. Informational. An input or output operation was attempted to a file on which another I/O operation is currently being performed. User Action. Correct the logic of the program.
27.104 - RMSF
PL/I internal FAB condition. Informational. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred and submit an SPR.
27.105 - RMSR
PL/I internal RAB condition. Informational. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred and submit an SPR.
27.106 - SIZE
PL/I compiler/run-time error. Please submit an SPR. Fatal. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred and submit an SPR.
27.107 - STORAGE
PL/I STORAGE condition. Fatal. A failure status was returned by LIB$GET_VM for an ALLOCATE statement. The secondary condition value indicates the reason for the failure. User Action. Correct the situation that caused the condition to be raised.
27.108 - STROVFL
Stream item too big. Must be less than 1000 characters. Informational. The run-time system cannot process a string longer than 1000 characters. User Action. Correct the input or output field width. If necessary, use more than one stream I/O statement.
27.109 - STRRANGE
PL/I STRINGRANGE condition. Fatal. The third operand in a reference to a SUBSTR built-in function or pseudovariable, or the third parameter in a reference to an INDEX, SEARCH or VERIFY built-in function is beyond the range of the string. This message is only issued for checks that fail in inline code if the procedure containing this reference was compiled with the /CHECK qualifier. This condition is always checked by PL/I run-time library routines. User Action. Correct the reference.
27.110 - STRSIZE
PL/I STRINGSIZE condition. Fatal. The second operand in a reference to a SUBSTR built-in function or pseudovariable is beyond the range of the string. This message is issued only if the procedure containing this reference was compiled with the /CHECK qualifier. User Action. Correct the reference.
27.111 - SUBRANGE
Subscript range check error. Informational. The compiler detected a value that is beyond the range specified for a variable. This message is issued only if the procedure containing the reference was compiled with the /CHECK qualifier. User Action. Correct the reference.
27.112 - SUBRANGE1
Subscript 1 range check error. Informational. The first subscript in an array reference specifies a value that is beyond the bounds of that dimension. This message is issued only if the procedure containing the reference was compiled with the /CHECK qualifier. User Action. Correct the reference.
27.113 - SUBRANGE2
Subscript 2 range check error. Informational. The second subscript in an array reference specifies a value that is beyond the bounds of that dimension. This message is issued only if the procedure containing the reference was compiled with the /CHECK qualifier. User Action. Correct the reference.
27.114 - SUBRANGE3
Subscript 3 range check error. Informational. The third subscript in an array reference specifies a value that is beyond the bounds of that dimension. This message is issued only if the procedure containing the reference was compiled with the /CHECK qualifier. User Action. Correct the reference.
27.115 - SUBRANGE4
Subscript 4 range check error. Informational. The fourth subscript in an array reference specifies a value that is beyond the bounds of that dimension. This message is issued only if the procedure containing the reference was compiled with the /CHECK qualifier. User Action. Correct the reference.
27.116 - SUBRANGE5
Subscript 5 range check error. Informational. The fifth subscript in an array reference specifies a value that is beyond the bounds of that dimension. This message is issued only if the procedure containing the reference was compiled with the /CHECK qualifier. User Action. Correct the reference.
27.117 - SUBRANGE6
Subscript 6 range check error. Informational. The sixth subscript in an array reference specifies a value that is beyond the bounds of that dimension. This message is issued only if the procedure containing the reference was compiled with the /CHECK qualifier. User Action. Correct the reference.
27.118 - SUBRANGE7
Subscript 7 range check error. Informational. The seventh subscript in an array reference specifies a value that is beyond the bounds of that dimension. This message is issued only if the procedure containing the reference was compiled with the /CHECK qualifier. User Action. Correct the reference.
27.119 - SUBRANGE8
Subscript 8 range check error. Informational. The eighth subscript in an array reference specifies a value that is beyond the bounds of that dimension. This message is issued only if the procedure containing the reference was compiled with the /CHECK qualifier. User Action. Correct the reference.
27.120 - SUBRG
PL/I SUBSCRIPTRANGE condition. Fatal. The compiler detected a value that is beyond the range specified for a variable. This message is issued only if the procedure containing the reference was compiled with the /CHECK qualifier. User Action. Correct the reference.
27.121 - SUBSTR2
Operand 2 of a SUBSTR is out of range. Informational. The second operand in a reference to a SUBSTR built-in function or pseudovariable is beyond the range of the string. This message is issued only if the procedure containing this reference was compiled with the /CHECK qualifier. User Action. Correct the reference.
27.122 - SUBSTR3
Operand 3 of a SUBSTR is out of range. Informational. The third operand in a reference to a SUBSTR built-in function or pseudovariable is beyond the range of the string. This message is issued only if the procedure containing this reference was compiled with the /CHECK qualifier. User Action. Correct the reference.
27.123 - TITLE
Invalid TITLE specified. Informational. The size of the character-string expression specified in the TITLE option exceeds the maximum size of 128 bytes. User Action. Select a smaller file title, and correct the program.
27.124 - TRANSMIT
PL/I compiler/run-time error. Please submit an SPR. Fatal. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred and submit an SPR.
27.125 - UNDFILE
PL/I UNDEFINEDFILE condition on file 'entity'. Fatal. This message is followed by one or more messages that indicate the specific error that occurred during opening of the given file. User Action. Determine the corrective action from the accompanying messages. Verify the file specification in the FILENAME message to determine whether the correct defaults are being applied, whether all required logical name assignments are in effect, and so on.
27.126 - VAXCOND
User defined condition, entity. Warning. This message is displayed when VAXCONDITION is signaled and no ON-unit exists to handle the specific numeric condition value. User Action. Verify that the condition value specified in the SIGNAL statement matches the condition value in a corresponding ON-unit. Correct the source program.
27.127 - VIRMEMDEAL
PL/I compiler/run-time error. Please submit an SPR. Informational. An error occurred in the execution of the PL/I compiler or a run-time module. User Action. Gather as much information as possible about the circumstances under which the error occurred and submit an SPR.
27.128 - WRITEIN
Attempting to WRITE to an INPUT file. Informational. A file that is opened with the INPUT attribute cannot be accessed with a WRITE statement. If you are attempting to write a file that was just read, you must first close the file and reopen it either with the UDPATE attribute or with the OUTPUT attribute and ENVIRONMENT(APPEND). User Action. Correct the source program.
27.129 - ZERODIV
PL/I ZERODIVIDE condition. Fatal. This message is displayed when the ZERODIVIDE condition occurs; that is, the divisor in a division operation has a value of zero. This message is displayed when the condition is not handled by an ON-unit within the PL/I program. User Action. Determine the statement that caused the error and correct the program logic, if possible. If practical, code an ON-unit to detect the condition and take appropriate action.
| 28 - Functions |
The PL/I built-in functions provide common routines. These routines need not be declared unless the name of a program variable corresponds to the name of a built-in function.
28.1 - Categories
Arithmetic: ABS, ADD, CEIL, DIVIDE, FLOOR, MAX, MIN, MOD, PRECISION, MULTIPLY, ROUND, SIGN, SUBTRACT, TRUNC Mathematical: ACOS, ASIN, ATAN, ATAND, ATANH, COS, COSD, COSH, EXP, LOG, LOG10, LOG2, SIN, SIND, SINH, SQRT, TAN, TAND, TANH String-handling: BOOL, COLLATE, COPY, EVERY, HIGH, INDEX, LENGTH, LOW, LTRIM, MAXLENGTH, REVERSE, RTRIM, SEARCH, SOME, STRING, SUBSTR, TRANSLATE, TRIM, VERIFY Conversion: BINARY, BIT, BYTE, CHARACTER, DECIMAL, DECODE, ENCODE, FIXED, FLOAT, INT, POSINT, RANK, UNSPEC Preprocessor: ABS, BYTE, COPY, DATE, DATETIME, DECODE, ENCODE, ERROR, INDEX, INFORM, LENGTH, LINE, LTRIM, MAX, MIN, MOD, RANK, REVERSE, RTRIM, SEARCH, SIGN, SUBSTR, TIME, TRANSLATE, TRIM, VARIANT, VERIFY, WARN Condition-handling: ONARGSLIST, ONCHAR, ONCODE, ONFILE, ONKEY, ONSOURCE Array-handling: DIMENSION, HBOUND, LBOUND, PROD, SUM Storage-control: ADDR, ADDREL, ALLOCATION, BYTESIZE, EMPTY, NULL, OFFSET, POINTER, SIZE Timekeeping: DATE, DATETIME, TIME File control: LINENO, PAGENO Miscellaneous: ACTUALCOUNT, DESCRIPTOR, PRESENT, REFERENCE, VALID, VALUE
28.2 - ABS
Arithmetic and preprocessor built-in function. Returns the absolute value of a given arithmetic expression. ABS(x)
28.3 - ACOS
Mathematical built-in function. Returns the floating-point arc cosine of a given angle expressed in radians. ACOS(x)
28.4 - ACTUALCOUNT
Miscellaneous built-in function. Returns the number of parameters the current procedure was called with. ACTUALCOUNT()
28.5 - ADD
Arithmetic built-in function. Returns the sum of x and y with a precision and a scale-factor. ADD(x,y,precision[,scale-factor])
28.6 - ADDR
Storage-control built-in function. Returns a pointer to the storage location of a given variable. ADDR(variable-reference)
28.7 - ADDREL
Storage-control built-in function. Returns a pointer that is the addition of the pointer value and integer expression. ADDREL(pointer-value,integer-expression)
28.8 - ALLOCATION
Storage-control built-in function. Abbreviation: ALLOCN Returns the number of existing generations of a CONTROLLED variable. ALLOCATION(x)
28.9 - ASIN
Mathematical built-in function. Returns the floating-point arc sine of a given expression. ASIN(x)
28.10 - ATAN
Mathematical built-in function. Returns the floating-point arc tangent of a given expression or of a computed expression. ATAN(y[,x])
28.11 - ATAND
Mathematical built-in function. Returns the floating-point arc tangent of a given angle or of a computed expression. ATAND(y[,x])
28.12 - ATANH
Mathematical built-in function. Returns the floating-point inverse hyperbolic tangent of an arithmetic expression. ATANH(x)
28.13 - BINARY
Conversion built-in function. Converts an arithmetic or string expression to its binary representation. BINARY (expression[,precision[,scale-factor]])
28.14 - BIT
Conversion built-in function. Converts an arithmetic or string expression to a bit string and returns the bit-string value. BIT(expression[,length])
28.15 - BOOL
String-handling built-in function.
Defines a Boolean operation to be performed on two bit strings and
returns the bit string representing the result of the operation.
BOOL(string-1,string-2,operation-string)
The operation string defines the results of comparing corresponding
bits in string-1 and string-2, as follows:
string-1-bit string-2-bit result
0 0 bit 1 of operation-string
0 1 bit 2 of operation-string
1 0 bit 3 of operation-string
1 1 bit 4 of operation-string
28.16 - BYTE
Conversion and preprocessor built-in function. Returns the ASCII character whose decimal ASCII code is the integer specified. BYTE(x)
28.17 - BYTESIZE
Storage-control built-in function. Returns the number of bytes allocated to variable x. BYTESIZE(x)
28.18 - CEIL
Arithmetic built-in function. Returns the smallest integer that is greater than or equal to the specified arithmetic expression. CEIL(x)
28.19 - CHARACTER
Conversion built-in function. Converts an arithmetic or string expression to a character string. CHARACTER(expression[,length]) where length is an integer constant specifying the desired length of the resulting character string.
28.20 - COLLATE
String-handling built-in function. Returns a 256-character string consisting of the ASCII character set in ascending order. COLLATE()
28.21 - COPY
String-handling and preprocessor built-in function. Copies a given string a specified number of times and concatenates the result into a single string. COPY(string,count)
28.22 - COS
Mathematical built-in function. Returns a floating-point value representing the cosine of an angle whose value is expressed in radians. COS(x)
28.23 - COSD
Mathematical built-in function. Returns a floating-point value representing the cosine of an angle whose value is expressed in degrees. COSD(x)
28.24 - COSH
Mathematical built-in function. Returns a floating-point value representing the hyperbolic cosine of a given angle whose value is expressed in radians. COSH(x)
28.25 - DATE
Timekeeping and preprocessor built-in function. Returns a six-character string in the form yymmdd, where: yy is the current year, mm is the current month, dd is the current day of month. DATE() When used as a preprocessor built-in function, the date at compile time is returned.
28.26 - DATETIME
Timekeeping and preprocessor built-in function. Returns the system date and time in the form CCYYMMDDHHMMSSXX. DATETIME()
28.27 - DECIMAL
Conversion built-in function. Abbreviation: DEC Converts an arithmetic or string expression to a decimal value of an optionally specified precision. DECIMAL (expression[,precision[,scale-factor]])
28.28 - DECODE
Conversion and preprocessor built-in function. Returns the fixed binary value of the character string c converted to a base r number. DECODE(c,r)
28.29 - DESCRIPTOR
Miscellaneous built-in function. Forces an argument to be passed by descriptor to a non-PL/I procedure, which overrides the parameter declaration. DESCRIPTOR(x)
28.30 - DIMENSION
Array-handling built-in function. Abbreviation: DIM Returns the number of elements in a specified dimension of an array. DIMENSION (reference[,dimension])
28.31 - DIVIDE
Arithmetic built-in function. Divides two values and returns the quotient with a specified precision and scale-factor. DIVIDE(x,y,precision[,scale-factor])
28.32 - EMPTY
Storage-control built-in function. Returns an empty area value. EMPTY()
28.33 - ENCODE
Conversion and preprocessor built-in function. Returns a character string representing the base r number that is equivalent to the fixed binary expression i. ENCODE(i,r)
28.34 - ERROR
Preprocessor built-in function. Returns a user-generated diagnostic error message. ERROR()
28.35 - EVERY
String-handling built-in function. Returns a Boolean value indicating whether every bit in the bit string s is '1'B. EVERY(s)
28.36 - EXP
Mathematical built-in function. Raises the base e to the power of the specified expression and returns the floating-point result. EXP(x)
28.37 - FIXED
Conversion built-in function. Converts an arithmetic or string expression to a fixed-point arithmetic value. FIXED(expression,precision[,scale-factor])
28.38 - FLOAT
Conversion built-in function. Converts an arithmetic or string expression to floating-point. FLOAT(expression,precision)
28.39 - FLOOR
Arithmetic built-in function. Returns the largest integer that is less than or equal to a given expression. FLOOR(x)
28.40 - HBOUND
Array-handling built-in function. Returns a fixed-point binary integer representing the upper bound of a specified dimension of an array. If the dimension is not specified, the dimension parameter defaults to 1. HBOUND(reference[,dimension])
28.41 - HIGH
String-handling built-in function. Returns a string of length c of repreated occurrences of the highest character in the collating sequence. HIGH(c)
28.42 - INDEX
String-handling and preprocessor built-in function. Returns the position, or offset, of a specified substring within another string, or 0 if the string is not found. The optional starting-position parameter specifies the leftmost position from which the search is to begin. INDEX(string,substring[,starting-position])
28.43 - INFORM
Preprocessor built-in function. Returns a user-generated diagnostic informational message. INFORM()
28.44 - INT
Conversion built-in function.
Returns the signed integer value of variable x, located at position
p with length l.
INT(expression[,position[,length]])
The expression is a scalar expression or a reference to connected
storage. This reference must not be an array, structure, or named
constant. If position and length are not specified, the length of
the referenced storage must not exceed 32 bits.
If specified, position must satisfy the condition
1 <= position <= size(expression)
If specified, length must satisfy the condition
0 <= length <= size(expression) - position
28.45 - LBOUND
Array-handling built-in function. Returns the lower bound of a array dimension. If the dimension is not specified, the dimension parameter defaults to 1. LBOUND(reference[,dimension])
28.46 - LENGTH
String-handling and preprocessor built-in function. Returns the number of characters or the number of bits in a given string. LENGTH(string)
28.47 - LINE
Preprocessor built-in function. Returns the line number in a source program that contains the end of the specified preprocessor statement. LINE()
28.48 - LINENO
File-control built-in function. Returns the current line number value of a print file. LINENO(file-reference)
28.49 - LOG
Mathematical built-in function. Returns the floating-point logarithm of a given value to the base e. LOG(x)
28.50 - LOG10
Mathematical built-in function. Return the floating-point logarithm of a given value to the base 10. LOG10(x)
28.51 - LOG2
Mathematical built-in function. Returns the floating-point logarithm of a given value to the base 2. LOG2(x)
28.52 - LOW
String-handling built-in function. Returns string of length c of repeated occurrences of the lowest character in the collating sequence. LOW(c)
28.53 - LTRIM
String-handling built-in function and preprocessor built-in function. Returns string s with all characters in e removed from the left. LTRIM(s[,e])
28.54 - MAX
Arithmetic and preprocessor built-in function. Returns the larger of two given values. MAX(x,y)
28.55 - MAXLENGTH
String-handling built-in function. Returns the maximum length of the varying string s. MAXLENGTH(s)
28.56 - MIN
Arithmetic and preprocessor built-in function. Compares two given values and returns the smaller. MIN(x,y)
28.57 - MOD
Arithmetic and preprocessor built-in function. Returns, for a value x and modulus y, the value r that equals x modulo y. That is, r is the smallest positive value that must be subtracted from x to make the remainder exactly divisible by y. MOD(x,y)
28.58 - MULTIPLY
Arithmetic built-in function. Returns the value of x*y, with precision and scale-factor. MULTIPLY(x,y,precision[,scale-factor])
28.59 - NULL
Storage-control built-in function. Returns a null pointer value. NULL()
28.60 - OFFSET
Storage-control built-in function. Converts a pointer value to an offset value and returns the storage location of a based variable within a designated area. OFFSET (pointer-value,area-reference)
28.61 - ONARGSLIST
Condition-handling built-in function. Returns a pointer to the virtual memory location of the argument lists for an exception condition. ONARGSLIST() The argument lists are described in the text module $CHFDEF in PLI$STARLET.TLB.
28.62 - ONCHAR
Condition-handling built-in function. Returns the character that caused the CONVERSION condition to be raised. ONCHAR()
28.63 - ONCODE
Condition-handling built-in function. Returns the fixed binary status value associated with the current ON condition. ONCODE() If the ONCODE built-in function is used within any context outside of an ON-unit, it returns a zero.
28.64 - ONFILE
Condition-handling built-in function. Returns the character-string name of the PL/I file constant for which the current file-related condition was signaled. ONFILE() If the ONFILE function is referenced outside of an ON-unit or from within an ON-unit that is executed as a result of a SIGNAL statement, it returns a null string.
28.65 - ONKEY
Condition-handling 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. ONKEY() If the ONKEY function is referenced outside of an ON-unit or from within an ON-unit that is executed as a result of a SIGNAL statement, it returns a null string.
28.66 - ONSOURCE
Condition-handling built-in function. Returns the field containing the ONCHAR character when the CONVERSION condition was raised. ONSOURCE()
28.67 - PAGENO
File-control built-in function. Returns the current page number of a print file. PAGENO(file-reference)
28.68 - POINTER
Storage-control built-in function. Accepts as arguments an area reference and an offset identifying a location in the area and returns a pointer to that location. POINTER (offset-reference,area-reference)
28.69 - POSINT
Conversion built-in function.
Returns the unsigned integer value of variable x, located at
position p with length l.
POSINT(expression[,position[,length]])
Expression is a scalar expression or reference to connected
storage. This reference must not be an array, structure, or named
constant. If position and length are not specified, the length of
the referenced storage must not exceed 32 bits.
If specified, position must satisfy the condition
1 <= position <= size(expression)
If specified, length must satisfy the condition
0 <= length <= size(expression)
28.70 - PRESENT
Miscellaneous built-in function. Returns a Boolean value indicating whether parameter p was specified in a call. PRESENT(p)
28.71 - PROD
Array-handling built-in function. Returns the arithmetic product of all the elements in the array x. PROD(x)
28.72 - RANK
Conversion and preprocessor built-in function. Returns the numeric ASCII code for a given character. RANK(character)
28.73 - REFERENCE
Miscellaneous built-in function. Forces its argument x to be passed by reference to a non-PL/I procedure. REFERENCE(x)
28.74 - REVERSE
String-handling and preprocessor built-in function. Returns the reverse of the source character string or bit string s. REVERSE(s)
28.75 - ROUND
Arithmetic built-in function Rounds a fixed-point decimal expression to a specified number of places and returns the result. ROUND(expression,position) where position is a nonnegative integer specifying the number of decimal places in the rounded result.
28.76 - RTRIM
String-handling built-in function and preprocessor built-in function. Returns string s with all characters in e removed from the right. RTRIM(s[,e])
28.77 - SEARCH
String-handling and preprocessor built-in function. Returns the position of the first character in s that is found in c, at starting position p, if specified. SEARCH(s,c[,p])
28.78 - SIGN
Arithmetic and preprocessor built-in function. Returns a 1, -1, or 0, indicating whether a given value is positive, negative, or zero, respectively. SIGN(x)
28.79 - SIN
Mathematical built-in function. Returns the floating-point sine of a given angle expressed in radians. SIN(x)
28.80 - SIND
Mathematical built-in function. Returns the floating-point sine of a given angle expressed in degrees. SIND(x)
28.81 - SINH
Mathematical built-in function. Returns the floating-point hyperbolic sine of a given expression. SINH(x)
28.82 - SIZE
Storage-control built-in function. Returns the number of bytes allocated to variable x. SIZE(x)
28.83 - SOME
String-handling built-in function. Returns a Boolean value indicating whether at least one bit in the bit string s is '1'B. SOME(s)
28.84 - SQRT
Mathematical built-in function. Returns the floating-point square root of a given value. SQRT(x)
28.85 - STRING
String-handling built-in function.
Concatenates the elements of an array or structure and returns the
result.
STRING(reference)
The reference must be to one of the following:
o A connected array of bit-string data
o A connected array of character-string data
o A connected array of picture data
o A connected structure all of whose members contain bit-string
data
o A connected structure all of whose members contain either
character-string data or picture data
Elements of a string array are concatenated with the array's last
subscript varying most rapidly. Members of a structure are
concatenated in the order in which they were declared.
28.86 - SUBSTR
String-handling and preprocessor built-in function. Extracts a specified portion from another string and returns the resulting string. SUBSTR(string,position[,length]) If not specified, length is the remainder of the string, that is: LENGTH(string)-position+1
28.87 - SUBTRACT
Arithmetic built-in function. Returns the value of x-y, with precision p and scale factor q. SUBTRACT(x,y,p[,q])
28.88 - SUM
Array-handling built-in function. Returns the arithmetic sum of all the elements in the array x. SUM(x)
28.89 - TAN
Mathematical built-in function. Returns the floating-point tangent of a given angle expressed in radians. TAN(x)
28.90 - TAND
Mathematical built-in function. Returns the floating-point tangent of a given angle expressed in degrees. TAND(x)
28.91 - TANH
Mathematical built-in function. Returns the floating-point hyperbolic tangent of a given expression. TANH(x)
28.92 - TIME
Timekeeping and preprocessor built-in function. Returns an eight-character string representing the current time of day in the form hhmmssxx, where: hh is the current hour (00-23) mm is the minutes (00-59) ss is the seconds (00-59) xx is hundredths of seconds (00-99) TIME() When used as a preprocessor built-in function, the time returned is the time at compile time.
28.93 - TRANSLATE
String-handling and preprocessor built-in function. Replaces occurrences of a given character in a string with another character and returns the resulting string. TRANSLATE(original-string,translation-string[,old-char])
28.94 - TRIM
String-handling built-in function and preprocessor built-in function. Returns string s with all characters in e removed from the left and all characters in f removed from the right. TRIM(s[,e,f])
28.95 - TRUNC
Mathematical built-in function. Changes all digits to the right of a decimal to zeros and returns the resulting integer value. TRUNC(x)
28.96 - UNSPEC
Conversion built-in function. Returns a bit string representing the internal coded form of a scalar variable. UNSPEC(reference)
28.97 - VALID
Miscellaneous built-in function. Determines whether the value of a pictured variable is valid with respect to its picture. VALID(x)
28.98 - VALUE
Miscellaneous built-in function. Abbreviation: VAL Forces a parameter to be passed by immediate value, rather than by whatever mechanism is specified by the declaration of the formal parameter. VALUE(expression)
28.99 - VARIANT
Preprocessor built-in function. Returns the string result representing the value of the variant. VARIANT()
28.100 - VERIFY
String-handling and preprocessor built-in function. Compares two character-string values and returns a zero if all characters in one string also appear in the other. If not, returns the position of the first character in the first string that is not present in the second. The optional starting-position parameter specifies the leftmost position in the first string to be compared. VERIFY(string,test-string[,starting-position])
28.101 - WARN
Preprocessor built-in function. Returns the number of diagnostic warning messages issued during compilation up to this point in the program. WARN()
| 29 - Miscellaneous |
29.1 - Names
All names must be declared. Identifiers may be up to 31 characters in length and can have any of the alphanumeric characters or $ or _.
29.2 - Input/Output
PL/I has two forms of I/O: stream I/O and record I/O. The stream I/O statements GET and PUT read and write ASCII data. By default, these statements operate on the files SYSIN and SYSPRINT. By default, these are both associated with the terminal. The record I/O statements READ, WRITE, DELETE, and REWRITE transfer data in terms of records. Any external file must be declared before it can be accessed. The OPEN statement opens a file and the CLOSE statement closes a file.
29.3 - Precedence
The precedence of operators in expressions is:
Operator Priority Operator Priority
** 1 < 5
+ (prefix) 1 ^> 5
- (prefix) 1 ^< 5
^ (prefix) 1 ^= 5
* 2 <= 5
/ 2 >= 5
+ (infix) 3 & 6
- (infix) 3 | 7
|| 4 ^ (infix) 7
> 5 |: 9
29.4 - Array
An array is an aggregate in which every element has the same data
type and size.
For rules for specifying the dimensions of an array, type
HELP PLI ATTRIBUTE DIMENSION
Assignment of arrays is limited to the case where arrays of
identical size and data type are being assigned.
29.5 - LINESIZE
Specifies, for a file with the STREAM and OUTPUT attributes, the width of each output line. LINESIZE(integer-expression) Valid only on the OPEN statement. If a program generates an integer-expression greater than 32767, a run-time error occurs.
29.6 - PAGESIZE
Specifies, for a file with the PRINT attribute, the number of lines on each output page. When the specified page number is reached during output operations on the file, the ENDPAGE condition is signaled. PAGESIZE(integer-expression) Valid only on the OPEN statement. If a program generates an integer-expression greater than 32767, a run-time error occurs.
29.7 - TITLE
Specifies, on an OPEN statement for a file, the OpenVMS file specification to be associated with the PL/I file constant. TITLE(string-expression)
| 30 - Pseudovariables |
Pseudovariables can substitute, in certain assignment contexts, for
an ordinary variable reference. Most frequently, pseudovariables
are used on the left side of an assignment statement or as the
input target of a GET statement. You can use a pseudovariable
wherever these conditions are true:
o The syntax specifies a variable reference.
o The context is one that explicitly assigns a value to the
variable.
o The context does not require the variable to be addressable.
30.1 - INT
Assigns a signed integer value to specified storage.
INT(reference [,position[,length]]) = expression
The reference is a reference to connected storage. It must not be
an array, structure, or named constant. It can be an array member
or an elementary structure member. If position and length are not
specified, the length of the referenced storage must not exceed 32
bits.
If specified, position must satisfy the condition
1 <= position <= size(reference)
If specified, length must satisfy the condition
0 <= length <= size(reference) - position
30.2 - ONCHAR
Can be used to replace the single character in the ONSOURCE value that caused a CONVERSION condition to be raised. ONCHAR()
30.3 - ONSOURCE
Can be used to replace the entire ONSOURCE value that caused a CONVERSION condition to be raised. ONSOURCE()
30.4 - PAGENO
Sets the current page number of a print file. PAGENO(file-reference) = expression ;
30.5 - POSINT
Assigns an unsigned integer value into specified storage.
POSINT (reference [,position[,length]]) = expression
Reference is a reference to connected storage. This reference must
not be an array, structure, or named constant. If position and
length are not specified, the length of the referenced storage must
not exceed 32 bits.
If specified, position must satisfy the condition
1 <= position <= size(reference)
If specified, length must satisfy the condtion
0 <= length <= size(reference) - position
The first element reference of POSINT must be a reference to a
scalar variable. It may be an array member or an elementary
structure member.
30.6 - STRING
The STRING pseudovariable assigns portions of a character or bit string to elements of an array or members of a structure. STRING(reference) = expression ; Portions of the string are assigned to the array elements or structure members until the end of the string is reached or all members or elements are filled. Assignments are made to elements of an array in row-major order, that is, with the last subscript varying most rapidly. Assignments are made to structure members in the order in which they appear in the DECLARE statement.
30.7 - SUBSTR
The SUBSTR pseudovariable replaces a specified substring within a given string with a new string value. SUBSTR(reference,position[,length]) = expression ; If not specified, length is the remainder of the string, that is: LENGTH(string)-position+1
30.8 - UNSPEC
Changes the internal representation of a specified variable to the bit string specified. UNSPEC(reference[,position[,length]]) = expression ;
| 31 - Release Notes |
The release notes contain information about changes and corrections in the most recent version of Kednos PL/I. The release notes are available in SYS$HELP:DPLI043.RELEASE_NOTES (OpenVMS AXP) or SYS$HELP:PLI$037.RELEASE_NOTES (OpenVMS VAX).
| 32 - Statements |
Define the structure of a program and its variables and specify the executable instructions to be performed by the program.
32.1 - Categories
Data definition and assignment statements: = (assignment), DECLARE
Input/output statements: OPEN, CLOSE
Record I/O: READ, WRITE, REWRITE, DELETE
Stream I/O: GET, PUT, FORMAT
Program structure: BEGIN, END, DO, ENTRY, PROCEDURE, Null
Flow control: CALL, GOTO, IF, LEAVE, ON, RETURN, REVERT, SELECT
SIGNAL, STOP
Storage allocation: ALLOCATE, FREE
Preprocessor: %ACTIVATE, %Assignment, %DEACTIVATE, %DECLARE,
%DICTIONARY, %DO, %END, %ERROR, %FATAL, %GOTO, %IF, %INCLUDE,
%INFORM, %LIST, %NOLIST, %Null, %PAGE, %PROCEDURE, %REPLACE,
%RETURN, %SBTTL, %TITLE, %WARN
32.2 - %ACTIVATE
Abbreviation: %ACT
Makes the value of a declared preprocessor variable eligible for
replacement.
%ACTIVATE element [RESCAN|NORESCAN],...;
element
A list of preprocessor identifiers.
element:
identifier|(identifier,...)
RESCAN|NORESCAN
Specifies whether or not the compiler is or is not to continue to
scan the source text for value replacement. RESCAN is the default.
32.3 - %Assignment
Evaluates a preprocessor expression and gives its value to a preprocessor identifier. %variable = expression ;
32.4 - Assignment
Evaluates an expression and gives its value to a variable or
variables.
target,... = expression ;
32.5 - ALLOCATE
Abbreviation: ALLOC Obtains a unit of system memory for a based or controlled variable or variables. The SET option specifies a pointer or offset variable to be set to the location of the memory obtained. The IN option specifies an area reference in which the storage is to be allocated. The SET and IN options are for use only with based variables. ALLOCATE allocate-item,... ; allocate-item: variable-reference [ SET (locator-reference) ] [IN (area-reference) ] The SET option is required if the based variable-reference was not declared with a pointer-reference.
32.6 - BEGIN
Denotes the beginning of a block of statements to be executed as a unit. BEGIN ; The statements following the BEGIN statement, up to the required END statement, constitute a begin block. A begin block is entered when control flows into it sequentially. Automatic variables declared within the block are allocated storage when the block is entered and released when the block is exited.
32.7 - CALL
Transfers control to an internal or external procedure and specifies arguments for the subroutine, if any. CALL entry-name [ (argument,...) ] ; The arguments correspond to the parameters of the procedure being invoked. External procedures must be declared with the ENTRY attribute.
32.8 - CLOSE
Terminates association of the program with an input or output file.
CLOSE FILE (file-reference) [ ENVIRONMENT (option,...) ]
[ ,FILE (file-reference) [ ENVIRONMENT (option,...) ]]... ;
The ENVIRONMENT options that are valid on the CLOSE statement are :
BATCH
DELETE
REVISION_DATE
REWIND_ON_CLOSE
SPOOL
TRUNCATE
32.9 - %DEACTIVATE
Abbreviation: %DEACT
Makes the value of a declared preprocessor variable ineligible for
replacement.
%DEACTIVATE element,...;
element:
identifier|(identifier,...)
32.10 - %DECLARE
Abbreviation: %DCL
Defines the preprocessor variable names and identifiers to be used
in a PL/I program and specifies the data attributes associated with
them.
%DECLARE element [attribute],...;
element:
identifier|(identifier,...)
attribute:
FIXED|CHARACTER|BIT
32.11 - DECLARE
Abbreviation: DCL
Defines the variable names and identifiers to be used in a PL/I
program and specifies the data attributes associated with the name.
DECLARE declaration,... ;
declaration:
[ level ] identifier [ dimension ] [ attribute ... ]
or
[ level ] (declaration,...) [ dimension ] [ attribute ... ]
dimension:
([lower-bound:]upper-bound)
or
(*)
Examples:
DECLARE A FIXED;
DECLARE (A,B) (10) FIXED;
DECLARE 1 A,
2 B FIXED,
2 (C,D) (20) CHAR(10);
32.12 - DELETE
Removes an existing record from an update file.
DELETE FILE (file-reference)
[ KEY (expression) ]
[ OPTIONS (option,...) ] ;
If the KEY option is not specified, the current record is deleted
from the file; the file must have the UPDATE attribute.
FAST_DELETE
INDEX_NUMBER(integer-expression)
MATCH_GREATER
MATCH_GREATER_EQUAL
MATCH_NEXT
MATCH_NEXT_EQUAL
RECORD_ID(variable-reference)
32.13 - %DICTIONARY
Specifies records to be included from the Common Data Dictionary
(CDD).
%DICTIONARY cdd-path;
cdd-path:
Any preprocessor expression.
32.14 - %DO
Denotes the beginning of a group of preprocessor statements to be
executed as a unit. Must be a simple DO-group.
%DO ;
.
.
.
%END ;
32.15 - DO
Denotes the beginning of a group of statements to be executed as a unit. The DO-group must be terminated by an END statement.
32. 15.1 - Simple DO
Executes a DO-group a single time. DO ;
32. 15.2 - WHILE
Executes a DO-group as long as a specified condition is met. DO WHILE (test-expression) ; The test-expression must be a bit-string expression. If any bit is 1, the test-expression is true.
32. 15.3 - UNTIL
Executes a DO-group as long as a specified condition is not true. DO UNTIL (test-expression) ;
32. 15.4 - Controlled DO
Executes a DO-group according to the specification and modification
of a control variable. The possible formats are:
DO control-variable = start-value TO end-value BY modify-value ;
DO control-variable = start-value BY modify-value ;
DO control-variable = start-value TO end-value ;
Any of these may also specify a WHILE and/or an UNTIL clause to
specify a condition that must be met in order for the DO-group to
execute.
control-variable, start-value, modify-value, and end-value must be
integer expressions.
32. 15.5 - REPEAT
Executes a DO-group for specified values of a control variable.
This form is commonly used in list processing:
DO control-variable = start-value REPEAT (expression)
[ WHILE (test-expression) ][ UNTIL (test-expression) ] ;
The expression in the REPEAT option is evaluated each time the DO
statement is executed and its value is assigned to the
control-variable.
32.16 - %END
Denotes the end of a block or group of preprocessor statements that started with a %PROCEDURE or a %DO statement. %END ;
32.17 - END
Denotes the end of a block or group of statements started with either BEGIN or DO statements. END ;
32.18 - ENTRY
Specifies an alternate statement at which the program can be
entered.
entry-name: ENTRY [ (parameter,...) ]
[ RECURSIVE|NONRECURSIVE ]
[ RETURNS (returns-descriptor) ] ;
An ENTRY statement can specify RETURNS only if the procedure to
which it is an entry also specifies RETURNS.
32.19 - %ERROR
Returns the number of diagnostic error messages issued during compilation up to this point in the program. %ERROR preprocessor-expression ; The preprocessor-expression becomes the text of the message.
32.20 - %FATAL
Generates a user-defined fatal diagnostic message. %FATAL preprocessor-expression ; The preprocessor-expression becomes the text of the message.
32.21 - FORMAT
The FORMAT statement specifies the format of data that is being read or written and defines conversion, if any, to be performed. label: FORMAT (format-specification,...) ; The FORMAT statement is generally used to define a format list that is referenced by more than one GET or PUT statement. A format-specification has any of the forms: o format-item o iteration-factor format-item o iteration-factor(format-specification,...) where iteration factor is an integer constant or integer expression.
32. 21.1 - A
With GET EDIT, reads 'w' characters from the input stream; with PUT EDIT, converts the value to be output to CHAR(w) and outputs the resulting string. A [ (w) ] w: A nonnegative integer or an expression capable of being converted to an integer value that specifies the width in characters of the field in the stream. If it is not included (PUT EDIT only), the field width equals the length of the converted output source.
32. 21.2 - B
With GET EDIT, reads a character string of length 'w' composed of the characters 0 and 1; with PUT EDIT, converts the corresponding value to a character string. The B format item is equivalent to B1. B1 [ (w) ] w: A nonnegative integer or an expression capable of being converted to an integer that specifies the width in characters of the field in the stream.
32. 21.3 - B1
With GET EDIT, reads a 'w'-character string composed of the characters 0 and 1; with PUT EDIT, converts the corresponding value to a character string. B1 [ (w) ] w: A nonnegative integer or an expression capable of being converted to an integer that specifies the width in characters of the field in the stream.
32. 21.4 - B2
With GET EDIT, reads a 'w'-character string composed of the characters 0, 1, 2, and 3 and converts it to a bit string; with PUT EDIT, converts 'w' 2-bit fields within the corresponding value to a string of the characters 0, 1, 2, or 3. B2 [ (w) ] w: A nonnegative integer or an expression capable of being converted to an integer that specifies the width in characters of the field in the stream.
32. 21.5 - B3
With GET EDIT, reads a 'w'-character string composed of the characters 0, 1, 2, 3, 4, 5, 6, 7 and converts it to a bit string; with PUT EDIT, converts 'w' 3-bit fields within the corresponding value to a string of the characters 0, 1, 2, 3, 4, 5, 6, or 7. B3 [ (w) ] w: A nonnegative integer or an expression capable of being converted to an integer that specifies the width in characters of the field in the stream.
32. 21.6 - B4
With GET EDIT, reads a 'w'-character string composed of the characters 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, or F; with PUT EDIT, converts 'w' 4-bit fields within the corresponding value to a string of the characters 0 through F. B4 [ (w) ] w: A nonnegative integer or an expression capable of being converted to an integer that specifies the width in characters of the field in the stream.
32. 21.7 - E
With GET EDIT, interprets an input character string as a floating- point value; with PUT EDIT, writes out a value in floating-point format. E(w,[d]) w and d must be integers.
32. 21.8 - F
With GET EDIT, interprets an input character string as a fixed- point value; with PUT EDIT, writes out a value in fixed-point decimal format. F(w[,d]) w: A nonnegative integer or an expression capable of being converted to an integer that specifies the width in characters of the field in the stream. d: An optional nonnegative integer or an expression capable of being converted to an integer value that specifies the number of fractional digits in the stream representation.
32. 21.9 - P
With GET EDIT, acquires a character string whose length and
characters are specified by a given picture specification; with PUT
EDIT, converts a value to a character string according to the
picture specification.
P'picture'
For more information type
HELP PLI ATTRIBUTE PICTURE
32. 21.10 - R
Indicates that format items are to be acquired from the FORMAT statement at the specified label. R(label)
32. 21.11 - COLUMN
Valid for files only; not valid with the STRING option. With GET EDIT, specifies the position at which reading of data is to proceed; with PUT EDIT, outputs spaces until the specified column position is reached. COLUMN (position) The position must be an integer or an expression capable of being converted to an integer value.
32. 21.12 - LINE
Valid for print files only. Specifies a line number, relative to the top of the page, at which output is to proceed. LINE (number) The number must be an integer or an expression capable of being converted to an integer value.
32. 21.13 - PAGE
Valid for print files only. Specifies that output is to be continued at the top of the next page.
32. 21.14 - SKIP
Valid for files only; not valid with the STRING option. With GET EDIT, continues reading after 'linecount' lines; with PUT EDIT, outputs 'linecount' blank lines and continues output. SKIP [ (linecount) ] linecount must be an integer or an expression capable of being converted to an integer value.
32. 21.15 - TAB
Valid for print files only. Continues output at the 'n'th tab stop relative to the current position. TAB [ (n) ] n must be an integer or an expression capable of being converted to an integer value.
32. 21.16 - X
With GET EDIT, ignores 'n' characters in the input stream; with PUT EDIT, places 'n' spaces in the output stream. X [ (n) ] n must be an integer or an expression capable of being converted to an integer value.
32.22 - FREE
Releases the storage that was allocated for a based or controlled
variable. The IN option specifies an area reference, for based
variables only.
FREE { variable-reference [IN(area-reference)] },... ;
32.23 - GET
Obtains data from a stream input file or from a character-string variable and assigns data items to variables specified in an input list.
32. 23.1 - EDIT
GET EDIT reads stream input data as specified in a format list.
GET EDIT (input-target,...) (format-specification,...)
[ FILE (file-reference) ]
[ OPTIONS (option,...) ]
[ SKIP (expression) ] ;
For more information, type:
HELP PLI STATEMENT GET INPUT TARGET,
HELP PLI STATEMENT FORMAT,
or HELP PLI STATEMENT GET OPTIONS
32. 23.2 - LIST
GET LIST reads data from a stream input file and assigns the values
read to variables specified in the input-target list.
GET LIST (input-target,...)
[ FILE (file-reference) ]
[ OPTIONS (option,...) ]
[ SKIP (expression) ] ;
For more information, type:
HELP PLI STATEMENT GET INPUT TARGET
or HELP PLI STATEMENT GET OPTIONS.
32. 23.3 - SKIP
GET SKIP advances the input stream to a new line before reading
input data.
GET SKIP [ (expression) ]
[ FILE (file-reference) ] ;
32. 23.4 - STRING
GET STRING acquires input data from a character-string variable and
assigns values to variables specified in an input list.
GET STRING (string-expression)
EDIT (input-target,...) (format-specification,...) ;
GET STRING (string-expression) LIST (input-target,...) ;
32. 23.5 - OPTIONS
NO_ECHO suppresses the display of terminal input. NO_FILTER treats Ctrl/R, Ctrl/U, and DEL as terminators. PROMPT (string-expression) displays a prompt before terminal input. PURGE_TYPE_AHEAD clears the type-ahead buffer before terminal input.
32. 23.6 - Input Target
The input targets of a GET statement are references to scalar variables, which are separated by commas. The input-target list of a GET statement may be specified with a DO specification in the format: (input-target,... DO do-spec) where do-spec may be a DO WHILE, DO UNTIL, controlled DO, or DO REPEAT (type HELP PLI STATEMENT DO for more information). Note that the parentheses surrounding this form of input target are in addition to those surrounding the entire input list. Example: GET LIST( (A(I) DO I = 1 TO 10) );
32.24 - %GOTO
Transfers control to a labeled preprocessor statement. %GOTO label-reference ; The format for a preprocessor label is %label: preprocessor-statement ; A %GOTO statement must not transfer control into or out of a preprocessor procedure. Movement can be either forward or backward in the program's text.
32.25 - GOTO
Also: GO [TO] Transfers control to a labeled statement. GOTO label-reference ;
32.26 - %IF
Tests a preprocessor expression, and establishes action to be performed based on the result of the test. %IF test-expression %THEN action [ %ELSE action ] ; where action is any preprocessor statement, DO-group, or begin block. The test-expression must yield a bit-string value; the test is true if any bit in the value is a 1.
32.27 - IF
Tests an expression and establishes actions to be performed based on the result of the test. IF test-expression THEN action [ ELSE action ] ; where action is any executable statement, DO-group or begin block. The test-expression must yield a bit-string value; the test is true if any bit in the value is a 1.
32.28 - %Null
Specifies no preprocessor operation %;
32.29 - Null
Specifies no operation. ;
32.30 - %INCLUDE
Copies the text of an external file into the source file at compilation time. %INCLUDE 'file-specification' ; %INCLUDE module-name ; %INCLUDE 'library-name(module-name)' If no apostrophes enclose the name specified, PL/I searches default text libraries and libraries specified on the PLI command line for the specified module-name.
32.31 - %INFORM
Returns the number of diagnostic informational messages issued during compilation up to this point in the program. %INFORM preprocessor-expression ; The preprocessor expression becomes the text of the message.
32.32 - LEAVE
Causes control to be transferred out of the immediately containing DO-group or out of the DO-group whose label is specified with the statement. LEAVE [label-reference]
32.33 - %LIST
Specifies that a listing be printed from that point on in the source program.
32. 33.1 - %LIST ALL
Specifies that the listing include Common Data Dictionary records , INCLUDE file contents, machine code, and source statements are to be included in the listing from that point on in the source program. %LIST_ALL ;
32. 33.2 - %LIST DICTIONARY
Specifies that a listing of included Common Data Dictionary records be included in the listing from that point on in the source program. %LIST_DICTIONARY ;
32. 33.3 - %LIST INCLUDE
Specifies that a listing of all INCLUDE files be included in the listing from that point on in the source program. %LIST_INCLUDE ;
32. 33.4 - %LIST MACHINE
Specifies that a machine code listing be included in the listing from that point on in the source program. %LIST_MACHINE ;
32. 33.5 - %LIST SOURCE
Specifies that source program statements are to be included in the listing from that point on in the source program. %LIST_SOURCE ;
32.34 - %NOLIST
Specifies that a listing is not to be printed from that point on in the program.
32. 34.1 - %NOLIST ALL
Specifies that the listing include Common Data Dictionary records , INCLUDE file contents, machine code, and source statements are not to be included in the listing from that point on in the source program. %NOLIST_ALL ;
32. 34.2 - %NOLIST DICTIONARY
Specifies that a listing of included Common Data Dictionary not to be included in the listing from that point on in the source program. %NOLIST_DICTIONARY
32. 34.3 - %NOLIST INCLUDE
Specifies that a listing of INCLUDE files is not to be included in the listing from that point on in the source program. %NOLIST_INCLUDE ;
32. 34.4 - %NOLIST MACHINE
Specifies that a machine code listing is not to be included in the listing from that point on in the source program. %NOLIST_MACHINE ;
32. 34.5 - %NOLIST SOURCE
Specifies that a source listing is not to be included in the listing from that point on in the source program. %NOLIST_SOURCE ;
32.35 - ON
Establishes action to be performed in case of signaled conditions
that occur during the execution of the program.
ON condition-name,... [ SNAP ] { on-unit|SYSTEM; }
The SNAP option invokes the debugger and causes a traceback of all
active routines to be displayed when the condition is raised. The
ON-unit is either an executable statement or a begin block. The
SYSTEM option invokes the default system condition handling for the
specified condition, overriding any existing ON-unit for the
condition.
Type HELP PLI CONDITIONS for a list of conditions.
32.36 - OPEN
Opens an external file and associates it with the referenced PL/I
file constant.
OPEN FILE (file-reference) [ file-description-attribute ... ]
[ ,FILE(file-reference) [file-description-attribute ... ]]... ;
Attributes specified for a file on OPEN must not conflict with
attributes specified in the declaration of the file. Attributes
and options that may be specified on OPEN are:
ENVIRONMENT (option,...)
RECORD or STREAM [ PRINT ]
INPUT, OUTPUT, or UPDATE
LINESIZE (expression)
PAGESIZE (expression)
SEQUENTIAL [ KEYED ] or DIRECT
TITLE (expression)
UPDATE
Type HELP PLI ENVIRONMENT for a list of ENVIRONMENT options.
If PRINT is specified, LINESIZE (integer-expression) and PAGESIZE
(integer-expression) may be specified.
32.37 - %PAGE
Provides listing pagination without form feeds. %PAGE ;
32.38 - %PROCEDURE
Abbreviation: %PROC
Specifies the name of an internal function procedure that is
executed by the embedded preprocessor
%label:PROCEDURE [(parameter-identifier,...)]
[STATEMENT]
RETURNS ({CHARACTER|FIXED|BIT});
.
.
.
%RETURN(preprocessor-expression);
.
.
.
%END;
Statements in a preprocessor procedure may only be preprocessor
statements. Within a preprocessor procedure, the leading
percent-symbol is optional.
32.39 - PROCEDURE
Abbreviation: PROC
Specifies the external name of the program
entry-name: PROCEDURE [ (parameter,...) ]
[ OPTIONS (option,...) ]
[ RETURNS (returns-descriptor) ]
[ RECURSIVE|NONRECURSIVE ] ;
parameter,... specifies a list of variables that will be assigned
values based on the actual arguments specified when the procedure
is invoked.
If RETURNS is specified, the procedure is a function and must
specify a value in a RETURN statement. If the procedure is invoked
with a CALL statement, the RETURNS attribute must not be specified.
32. 39.1 - Options
IDENT(character-string-constant) INLINE NOINLINE MAIN UNDERFLOW
32.40 - PUT
Moves data to an external source or to a character string variable.
32. 40.1 - EDIT
PUT EDIT transfers data items according to format specifications.
PUT EDIT (output-source,...) (format-specification,...)
[ FILE (file-reference) ]
[ LINE (expression) ]
[ OPTIONS (CANCEL_CONTROL_O) ]
[ PAGE ]
[ SKIP [(expression) ]] ;
For more information, type
HELP PLI STATEMENT PUT OUTPUT SOURCE
HELP PLI STATEMENT FORMAT.
32. 40.2 - LINE
Valid for print files only. Outputs blank lines until the
specified line number is reached.
PUT [ FILE (file-reference) ] LINE (expression)
[ OPTIONS (CANCEL_CONTROL_O) ] ;
32. 40.3 - LIST
PUT LIST transfers a list of output variables or expressions to the
output stream, converting them to character strings.
PUT [ FILE (file-reference) ] LIST (output-source,...)
[ LINE (expression) ]
[ OPTIONS (CANCEL_CONTROL_O) ]
[ PAGE ]
[ SKIP [(expression) ]] ;
For more information, type
HELP PLI STATEMENT PUT OUTPUT SOURCE.
32. 40.4 - PAGE
PUT PAGE advances a print file to the next page.
PUT [ FILE (file-reference) ] PAGE
[ OPTIONS (CANCEL_CONTROL_O) ] ;
32. 40.5 - SKIP
PUT SKIP advances the output file a specified number of lines.
PUT [ FILE (file-reference) ] SKIP [ (expression) ]
[ OPTIONS (CANCEL_CONTROL_O) ] ;
32. 40.6 - STRING
PUT STRING transfers data items in an output list to a specified
character-string variable.
PUT STRING (variable-reference)
EDIT (output-source,...) (format-specification,...) ;
PUT STRING (variable-reference) LIST (output-source,...) ;
32. 40.7 - Output Source
The output sources of a PUT statement may be any computational expressions, separated by commas. The output-source list of a PUT statement may be specified with a DO specification in the format: (output-source,... DO do-spec) where do-spec may be a DO WHILE, DO UNTIL, Controlled DO, or DO REPEAT (type HELP PLI STATEMENT DO for more information). Example: PUT LIST ((A(I) DO I = 1 TO 10)); Note that the output source that contains a DO specification must be enclosed in an extra set of parentheses.
32.41 - READ
Obtains a record from a file.
READ FILE (file-reference)
{ INTO (variable-reference) }
{ SET (pointer-variable) }
[ KEY (expression) ]
[ KEYTO (variable-reference) ]
[ OPTIONS (option,...) ] ;
Either the INTO or the SET option must be specified.
If KEY is not specified, the READ statement reads the next
sequential record in a record file.
32. 41.1 - Options
FIXED_CONTROL_TO(variable-reference) INDEX_NUMBER (expression) LOCK_ON_READ LOCK_ON_WRITE MANUAL_UNLOCKING MATCH_GREATER MATCH_GREATER_EQUAL MATCH_NEXT MATCH_NEXT_EQUAL NOLOCK NONEXISTENT_RECORD READ_REGARDLESS RECORD_ID (variable-reference) RECORD_ID_TO (variable-reference) TIMEOUT_PERIOD WAIT_FOR_RECORD
32.42 - %REPLACE
Replaces an identifier with a constant value for all subsequent appearances in the source file at compile time. %REPLACE identifier BY constant-value ;
32.43 - %RETURN
Terminates execution of a preprocessor procedure and returns the value of an evaluated preprocessor expression to the point of invocation. [%label:]RETURN(preprocessor-expression); The preprocessor-expression must evaluate to a CHARACTER, FIXED, or BIT data type.
32.44 - RETURN
Gives back control to the procedure from which the current procedure was invoked. RETURN [ (return-value) ] ; If the PROCEDURE statement for this procedure specified the RETURNS option, a return-value is required.
32.45 - REVERT
Cancels any ON-units in the current block for a given ON condition or conditions. REVERT condition-name,... ; Type HELP PLI CONDITIONS for a list of condition names.
32.46 - REWRITE
Replaces a record in an existing file.
REWRITE FILE (file-reference)
[ FROM (variable-reference) [ KEY (expression)] ]
[ OPTIONS (option,...) ] ;
If FROM is not specified, there must be a valid buffer from a
preceding READ statement with the SET option.
The file must have the UPDATE attribute.
32. 46.1 - Options
FIXED_CONTROL_FROM (variable-reference) INDEX_NUMBER (integer-expression) MATCH_GREATER MATCH_GREATER_EQUAL MATCH_NEXT MATCH_NEXT_EQUAL RECORD_ID (variable-reference) RECORD_ID_TO (variable-reference)
32.47 - SELECT
Tests a series of expressions and establishes actions to be
performed depending on the results of the tests.
SELECT[(select-expression)];
[WHEN [ANY|ALL] (expression,...) action;]
.
.
.
[OTHERWISE action;]
END;
where action is any executable statement, DO-group, or begin block.
If a select-expression is used, its value is compared with the
values of expressions listed after WHEN. If there is a match, the
corresponding action will be performed according to the following
scheme: If ANY (the default) is specified, the action is performed
if any single expression matches the select-expression in value.
If ALL is specified, all of the expressions must match the
select-expression in value for the corresponding action to be
performed.
If a select-expression is not used, the expressions in the
expression list must yield bit-string values. A bit string is
taken to signify true if it contains any bit with the value '1'B.
The action is performed if any, or all, of the expressions evaluate
to true, depending on whether ANY or ALL is specified.
Only one action can be performed. Any further expressions within
the SELECT statement will not be evaluated once an action is
performed.
If none of the tests of expressions in the WHEN clause(s) results
in an action's being performed, then the action specified in the
OTHERWISE clause is performed; if there is no OTHERWISE clause, an
error is signaled.
32.48 - %SBTTL
Allows specification of a listing subtitle line. %SBTTL preprocessor-expression ; The preprocessor-expression becomes the subtitle.
32.49 - SIGNAL
Causes a condition to be signaled. SIGNAL condition-name ; Type HELP PLI CONDITIONS for a list of condition names.
32.50 - STOP
Halts the execution of the current program and signals the FINISH condition. STOP ;
32.51 - %TITLE
Allows specification of a listing title line. %TITLE preprocessor-expression ; The preprocessor expression becomes the title.
32.52 - %WARN
Generates a user-defined warning diagnostic message. %WARN preprocessor-expression ; The preprocessor-expression becomes the text of the message.
32.53 - WRITE
Adds a new record to a record file.
WRITE FILE (file-reference) FROM (variable-reference)
[ KEYFROM (expression) ]
[ OPTIONS (option,...) ] ;
Options
FIXED_CONTROL_FROM (variable-reference)
RECORD_ID_TO (variable-reference)
| 33 - Subroutines |
In addition to the PL/I input and output statements and functions and features available through the options of the ENVIRONMENT attribute, there are several built-in subroutines. They are "built-in" because you do not need to declare them before using them in a PL/I program.
33.1 - DISPLAY
Obtains information about a given file. CALL DISPLAY (file-reference,variable-reference) ; The variable reference must have an identical structure as PLI_FILE_DISPLAY in PLI$STARLET.TLB. If PLI_FILE_DISPLAY is used, it must be allocated and associated with a pointer.
33.2 - EXTEND
Increases a disk file's allocation by a specified number of 512-byte disk blocks. CALL EXTEND (file-reference,integer-expression) ;
33.3 - FLUSH
Writes RMS buffers back to disk and checkpoints the file. CALL FLUSH (file-reference) ;
33.4 - FREE
Unlocks all the locked records in a specified file. CALL FREE (file-reference) ;
33.5 - NEXT_VOLUME
Advances a magnetic tape file to the next volume. CALL NEXT_VOLUME (file-reference) ;
33.6 - RELEASE
Unlocks a specified record in a file. CALL RELEASE (file-reference,variable-reference) ;
33.7 - RESIGNAL
Handles a signaled condition by continuing the signal and requesting PL/I to locate another ON-unit to handle the condition. CALL RESIGNAL ();
33.8 - REWIND
Rewinds a tape volume to its beginning or positions a disk file at the first record in the file or the first record in the key sequence. CALL REWIND (file-reference);
33.9 - SPACEBLOCK
Repositions a file that is opened for block I/O forward or backward by a specified number of blocks. CALL SPACEBLOCK (file-reference,integer-expression);
|
|