1 PLI The PLI command invokes the PL/I compiler to compile a PL/I source program. Format PLI file-spec[,...] 2 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,...)] 2 /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. 2 /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. 2 /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. 2 /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. 2 /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. 2 /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. 2 /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. 2 /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. 2 /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. 2 /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. 2 /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. 2 /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. 2 /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. 2 /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 2 /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. 2 /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. 2 /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. 2 /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. 2 /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. 2 /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. 2 /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 2 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. 3 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 3 ALIGNED Requests that a bit-string variable be aligned on a byte boundary in storage. Invalid for all other data type attributes. 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. 3 AREA Noncomputational data type attribute. Defines a unit of storage for the allocation of based variables. 3 AUTOMATIC Storage class attribute. Abbreviation: AUTO Requests dynamic allocation of storage for a variable. This is the default for internal variables. 3 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. 3 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 3 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. 3 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. 3 CONDITION Data type attribute. Abbreviation: COND Defines an identifier as a condition name. 3 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. 3 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. 3 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). 3 DEFINED Storage class attribute. Abbreviation: DEF Indicates that a variable will share the storage allocated for another variable. DEFINED (variable-reference) [ POSITION(expression) ] 3 DESCRIPTOR Argument passing attribute. Abbreviation: DESC Requests that an argument be passed to an external non-PL/I procedure by descriptor. 3 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. 3 DIRECT File description attribute. Specifies a record file that will be accessed randomly with READ, REWRITE, and DELETE statements. 3 ENTRY Attribute. Describes an external entry point and its parameters. ENTRY [ (parameter-descriptor,...) ] Type HELP PLI ATTRIBUTE PARAMETER DESCRIPTOR for more information. 3 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. 3 EXTERNAL Scope attribute. Abbreviation: EXT Identifies the name of a variable whose storage is referenced or defined in other procedures. 3 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. 3 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). 3 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. 3 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) ] 3 GLOBALREF Storage class attribute. Declares a global symbol defined in an external procedure. 3 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. 3 INPUT File description attribute. Specifies that a file will be accessed with GET or READ statements. 3 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. 3 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. 3 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. 3 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 3 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 3 LIST Argument passing attribute. Specifies that a parameter can accept a list of actual parameters, of arbitrary length. 3 MEMBER Member attribute. Specifies that an item is a member of a structure. 3 NONVARYING Computational data type attribute. Abbreviation: NONVAR Specifies that the length of a string is nonvarying. 3 OFFSET Storage class attribute. Defines an offset variable whose value represents the position of a variable within an area. OFFSET [ (area-reference) ] 3 OPTIONS Specifies options for various attributes or I/O statements. 3 OPTIONAL Argument passing attribute. Specifies, in the declaration of a formal parameter, that the actual parameter need not be specified in a call. 3 OUTPUT File description attribute. Specifies that a file will be accessed with PUT or WRITE statements. 3 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. 4 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. 3 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. 4 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. 3 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. 3 POSITION Specifies the character or bit position in a DEFINED variable's base variable at which the DEFINED variable begins. POSITION (expression) 3 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) 3 PRINT File description attribute. Specifies that an output file is to be formatted for printing. Implies STREAM OUTPUT. 3 READONLY Storage class attribute. Specifies that a static variable's value does not change during program execution. 3 RECORD File description attribute. Specifies that a file will be accessed by record I/O statements. 3 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. 3 REFERENCE Argument passing attribute. Abbreviation: REF Requests that an argument be passed to an external non-PL/I procedure by reference. 3 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. 3 SEQUENTIAL File description attribute. Abbreviation: SEQL Specifies that a file will be accessed by READ and WRITE statements. 3 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. 3 STREAM File description attribute. Specifies that a file will be accessed by GET or PUT statements. 3 STRUCTURE Specifies that a variable is a structure variable. 3 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 3 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. 3 UNALIGNED Abbreviation: UNAL Specifies nonalignment for a bit-string variable in storage. 3 UPDATE File description attribute. Specifies that a file will be accessed by READ, REWRITE, and DELETE statements. 3 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. 3 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); 3 VARYING Data type attribute. Abbreviation: VAR Defines a varying-length string. Can be specified only with CHARACTER. 2 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 2 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. 3 APPEND Places output for a file at the end of an existing file. 3 BACKUP_DATE Overrides the default backup date of a file. 3 BATCH Submits a copy of the file to the system batch job queue on close. Valid on the CLOSE statement. 3 BLOCK_BOUNDARY_FORMAT Indicates that records must not cross block boundaries. 3 BLOCK_IO Specifies a file will be read or written by blocks instead of records. Valid for sequential disk files and magnetic tape files. 3 BLOCK_SIZE Specifies the size of a block for a magnetic tape file. BLOCK_SIZE (integer-expression) 3 BUCKET_SIZE Defines the number of 512-byte blocks in a bucket for an indexed sequential or a relative file. BUCKET_SIZE (integer-expression) 3 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. 3 CONTIGUOUS Specifies that an output file must be placed in a physically contiguous extent on disk. 3 CONTIGUOUS_BEST_TRY Requests that if possible an output file be placed in a physically contiguous extent on disk. 3 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. 3 CURRENT_POSITION Leaves magnetic tape positioned at last close. 3 DEFAULT_FILE_NAME Defines a default file specification for a file. DEFAULT_FILE_NAME (string-expression) 3 DEFERRED_WRITE Requests file system optimization of output. 3 DELETE Specifies that the file be deleted when it is closed. Valid on the CLOSE statement. 3 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. 3 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. 3 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). 3 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). 3 FILE_SIZE Defines the initial number of 512-byte blocks to allocate for a file. FILE_SIZE (integer-expression) 3 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) 3 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. 3 FIXED_LENGTH_RECORDS Specifies a file with fixed-length records. 3 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. 3 IGNORE_LINE_MARKS Specifies that end-of-line indicators are not to be treated as field delimiters in GET LIST statements. 3 INDEX_NUMBER Specifies the alternate index to use in accessing records in an indexed sequential file. INDEX_NUMBER (integer-expression) 3 INDEXED Defines an indexed sequential file. 3 INITIAL_FILL Requests the file system to leave unused space in disk buckets when an indexed sequential file is initially loaded. 3 MAXIMUM_RECORD_NUMBER Specifies the largest record number that will be valid for records in a relative file. MAXIMUM_RECORD_NUMBER (integer-expression) 3 MAXIMUM_RECORD_SIZE Specifies the maximum size of records in the file. MAXIMUM_RECORD_SIZE (integer-expression) 3 MULTIBLOCK_COUNT Specifies the number of 512-byte blocks to allocate for file system buffering. MULTIBLOCK_COUNT (integer-expression) 3 MULTIBUFFER_COUNT Specifies the number of buffers to allocate for file system buffering. MULTIBUFFER_COUNT (integer-expression) 3 NO_SHARE Prohibits all type of shared access to the file. 3 OWNER_GROUP Specifies the group number in the user identification code (UIC) of the owner of the file. OWNER_GROUP (integer-expression) 3 OWNER_ID Specifies the entire 32-bit identifier of the owner of a file. Can be used instead of OWNER_GROUP and OWNER_MEMBER. 3 OWNER_MEMBER Specifies the member number in the user identification code (UIC) of the owner of the file. OWNER_MEMBER (integer-expression) 3 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. 3 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. 3 READ_AHEAD Requests file system optimization on read operations. 3 READ_CHECK Requests verification of read operations. 3 RECORD_ID_ACCESS Indicates that records will be accessed by internal file system identification. 3 RETRIEVAL_POINTERS Specifies the number of file system pointers to maintain for file access. RETRIEVAL_POINTERS (integer-expression) 3 REVISION_DATE Overrides the default revision date of a file. Valid on the CLOSE statement only. 3 REWIND_ON_CLOSE Requests that a magnetic tape volume be rewound when the file is closed. Valid on the CLOSE statement. 3 REWIND_ON_OPEN Requests that a magnetic tape volume be rewound when the file is opened. 3 SCALARVARYING Specifies that varying character strings will be read/written using the entire storage of the variable. 3 SHARED_READ Allows other users to read records in the file. 3 SHARED_WRITE Allows other users to write records in the file. 3 SPOOL Queues a copy of the file to the system printer when the file is closed. Valid on the CLOSE statement. 3 SUPERSEDE Replaces an existing file with the same file name, file type, and version number. 3 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. 3 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. 3 TRUNCATE Truncates a sequential file at its logical end-of-file when it is closed. Valid on the CLOSE statement. 3 USER_OPEN Specifies a user-written function to open a file. 3 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. 3 WRITE_BEHIND Requests file system optimization on output 3 WRITE_CHECK Requests verification of output operations. 2 Error_Messages VAX PL/I run-time error messages 3 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. 3 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. 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. 3 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. 3 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. 3 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. 3 AREA_FULL No room for variable allocation in area at address . 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 CONVFILE on file 'entity'. Informational. This displays the name of the file constant for which the conversion error occurred. User Action. None. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 ONSOURCE The conversion source is 'entity'. Informational. This displays the source string User Action. None. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 2 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. 3 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 3 ABS Arithmetic and preprocessor built-in function. Returns the absolute value of a given arithmetic expression. ABS(x) 3 ACOS Mathematical built-in function. Returns the floating-point arc cosine of a given angle expressed in radians. ACOS(x) 3 ACTUALCOUNT Miscellaneous built-in function. Returns the number of parameters the current procedure was called with. ACTUALCOUNT() 3 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]) 3 ADDR Storage-control built-in function. Returns a pointer to the storage location of a given variable. ADDR(variable-reference) 3 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) 3 ALLOCATION Storage-control built-in function. Abbreviation: ALLOCN Returns the number of existing generations of a CONTROLLED variable. ALLOCATION(x) 3 ASIN Mathematical built-in function. Returns the floating-point arc sine of a given expression. ASIN(x) 3 ATAN Mathematical built-in function. Returns the floating-point arc tangent of a given expression or of a computed expression. ATAN(y[,x]) 3 ATAND Mathematical built-in function. Returns the floating-point arc tangent of a given angle or of a computed expression. ATAND(y[,x]) 3 ATANH Mathematical built-in function. Returns the floating-point inverse hyperbolic tangent of an arithmetic expression. ATANH(x) 3 BINARY Conversion built-in function. Converts an arithmetic or string expression to its binary representation. BINARY (expression[,precision[,scale-factor]]) 3 BIT Conversion built-in function. Converts an arithmetic or string expression to a bit string and returns the bit-string value. BIT(expression[,length]) 3 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 3 BYTE Conversion and preprocessor built-in function. Returns the ASCII character whose decimal ASCII code is the integer specified. BYTE(x) 3 BYTESIZE Storage-control built-in function. Returns the number of bytes allocated to variable x. BYTESIZE(x) 3 CEIL Arithmetic built-in function. Returns the smallest integer that is greater than or equal to the specified arithmetic expression. CEIL(x) 3 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. 3 COLLATE String-handling built-in function. Returns a 256-character string consisting of the ASCII character set in ascending order. COLLATE() 3 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) 3 COS Mathematical built-in function. Returns a floating-point value representing the cosine of an angle whose value is expressed in radians. COS(x) 3 COSD Mathematical built-in function. Returns a floating-point value representing the cosine of an angle whose value is expressed in degrees. COSD(x) 3 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) 3 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. 3 DATETIME Timekeeping and preprocessor built-in function. Returns the system date and time in the form CCYYMMDDHHMMSSXX. DATETIME() 3 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]]) 3 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) 3 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) 3 DIMENSION Array-handling built-in function. Abbreviation: DIM Returns the number of elements in a specified dimension of an array. DIMENSION (reference[,dimension]) 3 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]) 3 EMPTY Storage-control built-in function. Returns an empty area value. EMPTY() 3 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) 3 ERROR Preprocessor built-in function. Returns a user-generated diagnostic error message. ERROR() 3 EVERY String-handling built-in function. Returns a Boolean value indicating whether every bit in the bit string s is '1'B. EVERY(s) 3 EXP Mathematical built-in function. Raises the base e to the power of the specified expression and returns the floating-point result. EXP(x) 3 FIXED Conversion built-in function. Converts an arithmetic or string expression to a fixed-point arithmetic value. FIXED(expression,precision[,scale-factor]) 3 FLOAT Conversion built-in function. Converts an arithmetic or string expression to floating-point. FLOAT(expression,precision) 3 FLOOR Arithmetic built-in function. Returns the largest integer that is less than or equal to a given expression. FLOOR(x) 3 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]) 3 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) 3 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]) 3 INFORM Preprocessor built-in function. Returns a user-generated diagnostic informational message. INFORM() 3 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 3 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]) 3 LENGTH String-handling and preprocessor built-in function. Returns the number of characters or the number of bits in a given string. LENGTH(string) 3 LINE Preprocessor built-in function. Returns the line number in a source program that contains the end of the specified preprocessor statement. LINE() 3 LINENO File-control built-in function. Returns the current line number value of a print file. LINENO(file-reference) 3 LOG Mathematical built-in function. Returns the floating-point logarithm of a given value to the base e. LOG(x) 3 LOG10 Mathematical built-in function. Return the floating-point logarithm of a given value to the base 10. LOG10(x) 3 LOG2 Mathematical built-in function. Returns the floating-point logarithm of a given value to the base 2. LOG2(x) 3 LOW String-handling built-in function. Returns string of length c of repeated occurrences of the lowest character in the collating sequence. LOW(c) 3 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]) 3 MAX Arithmetic and preprocessor built-in function. Returns the larger of two given values. MAX(x,y) 3 MAXLENGTH String-handling built-in function. Returns the maximum length of the varying string s. MAXLENGTH(s) 3 MIN Arithmetic and preprocessor built-in function. Compares two given values and returns the smaller. MIN(x,y) 3 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) 3 MULTIPLY Arithmetic built-in function. Returns the value of x*y, with precision and scale-factor. MULTIPLY(x,y,precision[,scale-factor]) 3 NULL Storage-control built-in function. Returns a null pointer value. NULL() 3 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) 3 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. 3 ONCHAR Condition-handling built-in function. Returns the character that caused the CONVERSION condition to be raised. ONCHAR() 3 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. 3 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. 3 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. 3 ONSOURCE Condition-handling built-in function. Returns the field containing the ONCHAR character when the CONVERSION condition was raised. ONSOURCE() 3 PAGENO File-control built-in function. Returns the current page number of a print file. PAGENO(file-reference) 3 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) 3 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) 3 PRESENT Miscellaneous built-in function. Returns a Boolean value indicating whether parameter p was specified in a call. PRESENT(p) 3 PROD Array-handling built-in function. Returns the arithmetic product of all the elements in the array x. PROD(x) 3 RANK Conversion and preprocessor built-in function. Returns the numeric ASCII code for a given character. RANK(character) 3 REFERENCE Miscellaneous built-in function. Forces its argument x to be passed by reference to a non-PL/I procedure. REFERENCE(x) 3 REVERSE String-handling and preprocessor built-in function. Returns the reverse of the source character string or bit string s. REVERSE(s) 3 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. 3 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]) 3 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]) 3 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) 3 SIN Mathematical built-in function. Returns the floating-point sine of a given angle expressed in radians. SIN(x) 3 SIND Mathematical built-in function. Returns the floating-point sine of a given angle expressed in degrees. SIND(x) 3 SINH Mathematical built-in function. Returns the floating-point hyperbolic sine of a given expression. SINH(x) 3 SIZE Storage-control built-in function. Returns the number of bytes allocated to variable x. SIZE(x) 3 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) 3 SQRT Mathematical built-in function. Returns the floating-point square root of a given value. SQRT(x) 3 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. 3 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 3 SUBTRACT Arithmetic built-in function. Returns the value of x-y, with precision p and scale factor q. SUBTRACT(x,y,p[,q]) 3 SUM Array-handling built-in function. Returns the arithmetic sum of all the elements in the array x. SUM(x) 3 TAN Mathematical built-in function. Returns the floating-point tangent of a given angle expressed in radians. TAN(x) 3 TAND Mathematical built-in function. Returns the floating-point tangent of a given angle expressed in degrees. TAND(x) 3 TANH Mathematical built-in function. Returns the floating-point hyperbolic tangent of a given expression. TANH(x) 3 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. 3 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]) 3 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]) 3 TRUNC Mathematical built-in function. Changes all digits to the right of a decimal to zeros and returns the resulting integer value. TRUNC(x) 3 UNSPEC Conversion built-in function. Returns a bit string representing the internal coded form of a scalar variable. UNSPEC(reference) 3 VALID Miscellaneous built-in function. Determines whether the value of a pictured variable is valid with respect to its picture. VALID(x) 3 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) 3 VARIANT Preprocessor built-in function. Returns the string result representing the value of the variant. VARIANT() 3 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]) 3 WARN Preprocessor built-in function. Returns the number of diagnostic warning messages issued during compilation up to this point in the program. WARN() 2 Miscellaneous 3 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 _. 3 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. 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 &: 8 > 5 |: 9 3 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. 3 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. 3 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. 3 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) 2 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. 3 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 3 ONCHAR Can be used to replace the single character in the ONSOURCE value that caused a CONVERSION condition to be raised. ONCHAR() 3 ONSOURCE Can be used to replace the entire ONSOURCE value that caused a CONVERSION condition to be raised. ONSOURCE() 3 PAGENO Sets the current page number of a print file. PAGENO(file-reference) = expression ; 3 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. 3 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. 3 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 3 UNSPEC Changes the internal representation of a specified variable to the bit string specified. UNSPEC(reference[,position[,length]]) = expression ; 2 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). 2 Statements Define the structure of a program and its variables and specify the executable instructions to be performed by the program. 3 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 3 %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. 3 %Assignment Evaluates a preprocessor expression and gives its value to a preprocessor identifier. %variable = expression ; 3 Assignment Evaluates an expression and gives its value to a variable or variables. target,... = expression ; 3 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. 3 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. 3 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. 3 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 3 %DEACTIVATE Abbreviation: %DEACT Makes the value of a declared preprocessor variable ineligible for replacement. %DEACTIVATE element,...; element: identifier|(identifier,...) 3 %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 3 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); 3 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) 3 %DICTIONARY Specifies records to be included from the Common Data Dictionary (CDD). %DICTIONARY cdd-path; cdd-path: Any preprocessor expression. 3 %DO Denotes the beginning of a group of preprocessor statements to be executed as a unit. Must be a simple DO-group. %DO ; . . . %END ; 3 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. 4 Simple DO Executes a DO-group a single time. DO ; 4 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. 4 UNTIL Executes a DO-group as long as a specified condition is not true. DO UNTIL (test-expression) ; 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. 4 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. 3 %END Denotes the end of a block or group of preprocessor statements that started with a %PROCEDURE or a %DO statement. %END ; 3 END Denotes the end of a block or group of statements started with either BEGIN or DO statements. END ; 3 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. 3 %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. 3 %FATAL Generates a user-defined fatal diagnostic message. %FATAL preprocessor-expression ; The preprocessor-expression becomes the text of the message. 3 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. 4 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. 4 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. 4 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. 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. 4 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. 4 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. 4 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. 4 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. 4 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 4 R Indicates that format items are to be acquired from the FORMAT statement at the specified label. R(label) 4 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. 4 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. 4 PAGE Valid for print files only. Specifies that output is to be continued at the top of the next page. 4 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. 4 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. 4 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. 3 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)] },... ; 3 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. 4 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 4 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. 4 SKIP GET SKIP advances the input stream to a new line before reading input data. GET SKIP [ (expression) ] [ FILE (file-reference) ] ; 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,...) ; 4 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. 4 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) ); 3 %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. 3 GOTO Also: GO [TO] Transfers control to a labeled statement. GOTO label-reference ; 3 %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. 3 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. 3 %Null Specifies no preprocessor operation %; 3 Null Specifies no operation. ; 3 %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. 3 %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. 3 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] 3 %LIST Specifies that a listing be printed from that point on in the source program. 4 %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 ; 4 %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 ; 4 %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 ; 4 %LIST_MACHINE Specifies that a machine code listing be included in the listing from that point on in the source program. %LIST_MACHINE ; 4 %LIST_SOURCE Specifies that source program statements are to be included in the listing from that point on in the source program. %LIST_SOURCE ; 3 %NOLIST Specifies that a listing is not to be printed from that point on in the program. 4 %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 ; 4 %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 4 %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 ; 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 ; 4 %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 ; 3 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. 3 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. 3 %PAGE Provides listing pagination without form feeds. %PAGE ; 3 %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. 3 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. 4 Options IDENT(character-string-constant) INLINE NOINLINE MAIN UNDERFLOW 3 PUT Moves data to an external source or to a character string variable. 4 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. 4 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) ] ; 4 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. 4 PAGE PUT PAGE advances a print file to the next page. PUT [ FILE (file-reference) ] PAGE [ OPTIONS (CANCEL_CONTROL_O) ] ; 4 SKIP PUT SKIP advances the output file a specified number of lines. PUT [ FILE (file-reference) ] SKIP [ (expression) ] [ OPTIONS (CANCEL_CONTROL_O) ] ; 4 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,...) ; 4 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. 3 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. 4 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 3 %REPLACE Replaces an identifier with a constant value for all subsequent appearances in the source file at compile time. %REPLACE identifier BY constant-value ; 3 %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. 3 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. 3 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. 3 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. 4 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) 3 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. 3 %SBTTL Allows specification of a listing subtitle line. %SBTTL preprocessor-expression ; The preprocessor-expression becomes the subtitle. 3 SIGNAL Causes a condition to be signaled. SIGNAL condition-name ; Type HELP PLI CONDITIONS for a list of condition names. 3 STOP Halts the execution of the current program and signals the FINISH condition. STOP ; 3 %TITLE Allows specification of a listing title line. %TITLE preprocessor-expression ; The preprocessor expression becomes the title. 3 %WARN Generates a user-defined warning diagnostic message. %WARN preprocessor-expression ; The preprocessor-expression becomes the text of the message. 3 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) 2 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. 3 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. 3 EXTEND Increases a disk file's allocation by a specified number of 512-byte disk blocks. CALL EXTEND (file-reference,integer-expression) ; 3 FLUSH Writes RMS buffers back to disk and checkpoints the file. CALL FLUSH (file-reference) ; 3 FREE Unlocks all the locked records in a specified file. CALL FREE (file-reference) ; 3 NEXT_VOLUME Advances a magnetic tape file to the next volume. CALL NEXT_VOLUME (file-reference) ; 3 RELEASE Unlocks a specified record in a file. CALL RELEASE (file-reference,variable-reference) ; 3 RESIGNAL Handles a signaled condition by continuing the signal and requesting PL/I to locate another ON-unit to handle the condition. CALL RESIGNAL (); 3 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); 3 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);