This manual defines Kednos PL/I for UNIX. It includes the keywords
and the semantic and syntax rules of PL/I programming language
statements, attributes, built-in functions, and other language elements.
Operating System and Version: Digital UNIX Version 3.2 or
higher
Kednos Systems, Inc., makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.
Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Kednos or an authorized sublicensor.
No responsibility is assumed for the use or reliability of software on equipment that is not listed as supported in the Product Description.
Restricted Rights: Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013.
© Kednos Corporation, 1995, 1996, All Rights Reserved.
Kednos, Kednos PL/I, and Kednos VPO are trademarks of Kednos Corporation.
Alpha AXP, CDD, DEC,DEC 4000, DECwindows, Digital, OpenVMS AXP, ULTRIX, VAX, OpenVMS, VT102, VT220, VT240, VT320, VT330, VT340, and the DIGITAL logo are trademarks of Digital Equipment Corporation.
SAA and IBM are trademarks of International Business Machine Inc.
Stratus is a trademark of Stratus Computer Inc.
Kednos PL/I for UNIX includes the GNU readline and assembler software. See the Kednos PL/I for UNIX User's Manual for the entire text of the Free Software Foundation's GNU Copyleft.
Portions Copyright 1984-1990 FairCom Corporation. All Rights Reserved.
Kednos requests your critical evaluation to assist in preparing future documentation. Please send any comments to comments@Kednos.com or by physical mail to:
Condition Prefixes (IBM Dialect Only) 1-7
Summary of Statements by Function 1-9
Declarations Outside Procedures 2-3
Multiple Simple Declarations 2-4
Factored Simple Declarations 2-4
BUFFERED and UNBUFFERED Attributes (IBM Dialect Only) 2-20
OPTIONAL Attribute (Dec and Ansi Dialects Only) 2-45
Precision and Scale of Arithmetic Data Types 3-8
Internal Representation of Fixed-Point Binary Data 3-10
Fixed-Point Decimal Constants 3-11
Fixed-Point Decimal Variables 3-12
Internal Representation of Fixed-Point Decimal Data 3-13
Using Floating-Point Data in Expressions 3-15
Floating-Point Data Formats 3-15
Character Picture Characters 3-18
Examples of Character Picture Variable Definitions 3-18
Assigning Values to Pictured Variables 3-32
Extracting Values from Pictured Data 3-33
The Internal Representation of Pictured Variables 3-34
Character String Constants 3-36
Replication of String Constants 3-37
Character-String Variables 3-37
Fixed-Length Character String Variables 3-38
Internal Representation of Fixed-Length Character Data 3-39
Varying-Length Character String Variables 3-39
Internal Representation of Varying Character Data 3-40
Alignment of Character Strings 3-40
Replication Factor for Bit-String Constants 3-42
Alignment of Bit-String Data 3-44
Internal Representation of Bit Data 3-45
Pointer Variables in Expressions 3-50
Internal Representation of Pointer Data 3-50
Internal Representation of Label Variables 3-56
Internal Representation of Entry Variables 3-59
Area Variables in Expressions 3-63
Reading and Writing Areas 3-63
References to Individual Elements 4-5
Assigning Values to Array Variables 4-10
Order of Assignment and Output for Multidimensional Arrays 4-11
Using GET and PUT Statements with Array Variables 4-12
Passing Arrays as Arguments 4-12
Built-In Functions Providing Array Dimension Information 4-13
Structure Declarations and Attributes 4-14
Using The UNION Attribute On Structure Declarations 4-16
Using Structure Variables in Expressions 4-17
Passing Structure Variables as Arguments 4-18
Structure-Qualified References 4-27
Arrays of Structures that Contain Arrays 4-29
Data Types Used with Based Variables 5-6
Referring to Based Variables 5-8
Based Variables and Dynamic Storage Allocation 5-10
Using the ADDR Built-in Function 5-13
Data-Type Matching for Based Variables 5-14
Matching by Overlay Defining 5-14
Matching by Left-to-Right Equivalence 5-15
Nonmatching Based Variable References 5-16
Examples of Based Variables 5-16
Using the ALLOCATION Built-In Function 5-20
Using the ADDR Built-In Function 5-21
Dynamically Allocated Variables 5-22
Other Mechanisms for Dynamic Storage Allocation 5-25
Character-String Comparisons 6-13
Comparing Noncomputational Data 6-13
Precedence of Operators and Expression Evaluation 6-15
Data Type Conversion of Operands and Expressions 6-17
Contexts in which PL/I Converts Data 6-18
Derived Data Types for Arithmetic Operations 6-21
Conversion of Operands in Nonarithmetic Operations 6-22
Built-In Conversion Functions 6-23
Implicit Conversion During Assignment 6-24
Assignment to Arithmetic Variables 6-25
Arithmetic to Arithmetic Conversions 6-25
Pictured to Arithmetic Conversions 6-27
Bit-String to Arithmetic Conversions 6-27
Character-String to Arithmetic Conversions 6-29
Assignments to Bit-String Variables 6-30
Arithmetic to Bit-String Assignments 6-30
Pictured to Bit-String Conversions 6-32
Character-String to Bit-String Conversions 6-33
Assignments to Character-String Variables 6-33
Arithmetic to Character-String Conversions 6-34
Pictured to Character-String Conversion 6-37
Bit-String to Character-String Conversion 6-37
Functions and Function References 7-4
Rules for Specifying Parameters 7-13
Calling External and Internal Procedures 7-18
Passing Arguments to Non-PL/I Procedures 7-22
The Two Forms of the SELECT Statement 8-19
ATTENTION Condition (IBM Dialect Only) 8-37
CHECK Condition (IBM Dialect Only) 8-38
NAME Condition (IBM Dialect Only) 8-49
RECORD Condition (IBM Dialect Only) 8-50
SIZE Condition (IBM Dialect Only) 8-51
STRINGSIZE Condition (IBM Dialect Only) 8-55
TRANSMIT Condition (IBM Dialect Only) 8-56
Using Condition Prefixes (IBM Dialect Only) 8-61
Scope of Condition Prefixes 8-61
Establishing the File's Attributes 9-7
Determining the File Specification 9-8
Accessing an Existing File 9-9
File Description Attributes and Options 9-10
Processing and Positioning of Stream Files 9-14
Input by the GET Statement 9-16
Syntax Summary of the GET Statement 9-16
Execution of the GET Statement 9-23
Output by the PUT Statement 9-26
Syntax Summary of the PUT Statement 9-26
Execution of the PUT Statement 9-33
Processing and Positioning of Character Strings 9-67
Simple Input from a Terminal 9-68
Simple Output to a Terminal 9-69
File Positioning Following a READ Statement 9-77
File Positioning Following a WRITE Statement 9-80
File Positioning Following a DELETE Statement 9-84
File Positioning Following a REWRITE Statement 9-85
LOCATE Statement (IBM Dialect Only) 9-87
Built-In Function Arguments 11-1
Summary of Built-In Functions 11-2
Relation to the 1981 PL/I General-Purpose Subset B-1
Built-In Functions and Pseudovariables B-3
198x PL/I General-Purpose Subset Features Supported B-4
Built-In Functions and Pseudovariables B-5
Full PL/I Features Supported B-6
Built-In Functions and Pseudovariables B-7
Nonstandard Features from Other Implementations B-7
IBM Dialect I/O Features and Other IBM Dialect Features B-8
PL/I-Specific Extensions for the Digital Unix Platform B-8
Differences Between Kednos PL/I for UNIX Digital's PL/I and Other Digital-Compatible Versions of PL/I C-7
Default Values for Data Type Attributes C-7
Procedures and Entries Specified with the Returns Option C-8
Expressions and Data Conversions D-12
Figure 1-1. Relationship of Block Activations 1-18
Figure 3-1. Internal Representation of Fixed-Point Binary Data 3-11
Figure 3-2. Fixed-Point Decimal Data Representation 3-13
Figure 3-3. IEEE S_floating Data Representation 3-16
Figure 3-4. IEEE T_floating Data Representation 3-17
Figure 3-5. Internal Representation of a Pictured Variable 3-35
Figure 3-6. Internal Representation of a Pictured Variable 3-35
Figure 3-7. Unaligned Bit String Storage 3-46
Figure 3-8. Sample Unaligned Bit String Storage 3-46
Figure 3-9. Aligned Bit String Storage 3-47
Figure 3-10. Sample Aligned Bit String Storage 3-47
Figure 3-11. Variable Label Data Representation 3-56
Figure 3-12. Entry Variable Data Representation 3-59
Figure 4-1. Specifying Elements of an Array 4-8
Figure 4-2. Storage of Structure with REFER Option 4-25
Figure 4-3. Remapped Storage of Structure with REFER Option 4-26
Figure 4-4. Connected and Unconnected Arrays 4-31
Figure 5-1. External Variables 5-4
Figure 5-2. Using the ALLOCATE Statement 5-11
Figure 5-3. Using the READ Statement with a Based Variable 5-13
Figure 5-4. Using the ADDR Built-In Function 5-14
Figure 5-5. An Overlay Defined Variable 5-27
Figure 11-1. Example of the BOOL Built-In Function 11-17
Table Pref-1. Documentation Conventions Table xxiv
Table 1-1. Punctuation Marks Recognized by PL/I 1-3
Table 1-2. Summary of PL/I Statements 1-10
Table 2-1. Alphabetic Summary of PL/I Attributes 2-10
Table 2-2. Default Values for BINARY Attribute 2-19
Table 2-3. Default Values for the DECIMAL Attribute. 2-25
Table 2-4. Default Values for Unspecified FIXED Attributes 2-35
Table 2-5. Default Values for Unspecified FLOAT Attributes 2-36
Table 3-1. Implied Attributes for Computational Data 3-3
Table 3-2. Default Values for Precision 3-9
Table 3-3. Ranges of Floating-Point Formats 3-15
Table 3-4. Ranges of Precision for Floating-Point Types 3-16
Table 3-5. Floating-Point Types Used by PL/I 3-16
Table 3-6. Picture Characters 3-20
Table 3-7. ASCII Representation of Encoded-Sign Characters 3-24
Table 4-1. Specifying Array Dimensions 4-3
Table 4-2. Natural Alignment for Structure Members 4-33
Table 6-1. Data Types for Assignment Statement 6-2
Table 6-2. Infix Arithmetic Operators 6-5
Table 6-3. Logical Operators 6-6
Table 6-4. Precedence of Operators 6-15
Table 6-5. Contexts in Which PL/I Converts Data 6-20
Table 6-6. Derived Data Types 6-21
Table 6-7. Converted Precision as a Function of Target and Source Attributes 6-22
Table 6-8. Built-In Functions for Conversions Between Arithmetic and Nonarithmetic Types 6-23
Table 6-9. Conversion from Fixed Binary 6-26
Table 8-1. Summary of ON Conditions 8-36
Table 8-2. Values of ONCODE Raised by RECORD 8-51
Table 8-3. Values of ONCODE Raised by SIZE 8-52
Table 8-4. Values of ONCODE Raised by STRINGRANGE 8-53
Table 8-5. Values of ONCODE Raised by STRINGSIZE 8-55
Table 8-6. Values of ONCODE Raised by TRANSMIT 8-57
Table 8-7. Conditions Enabled by Default 8-62
Table 8-8. Conditions Disabled by Default 8-62
Table 8-9. Conditions That Cannot be Disabled 8-62
Table 9-1. File Description Attributes Implied when a File is Opened 9-7
Table 9-2. Summary of File Description Attributes 9-10
Table 9-3. Attributes and Access Modes for Stream Files 9-12
Table 9-4. Input String Formatting 9-36
Table 9-5. Output String Formatting 9-37
Table 9-6. Input with the B Format Item 9-40
Table 9-7. Output with the B Format Item 9-40
Table 9-8. Representation of Floating-Point Values 9-43
Table 9-9. Input with the E Format Item 9-45
Table 9-10. Output with the E Format Item 9-45
Table 9-11. Input with the F Format Item 9-48
Table 9-12. Output with the F Format Item 9-48
Table 9-13. Input with the P Format Item 9-51
Table 9-14. Output with the P Format Item 9-52
Table 9-15. Attributes and Access Modes for Record Files 9-73
Table 9-16. Position Information for a Record File 9-89
Table 10-1. Summary of PL/I Preprocessor Statements 10-4
Table 10-2. Implied Attributes for Variables 10-9
Table 10-3. Summary of PL/I Preprocessor Built-In Functions 10-29
Table 11-1. Summary of PL/I Built-In Functions 11-3
Table 11-2. Summary of PL/I Built-In Subroutines 11-75
Table 11-3. Pseudovariables by Dialect 11-77
Table D-1. PL/I Keywords Not Supported C-1
Table D-2. Summary of Unsupported IBM I/O Features C-5
Table D-3. Digital Default Values for Data Type Attribute C-7
Table E-2. Precedence of Operators D-13
Table E-3. Contexts in Which PL/I Converts Data D-14
Table 11-4. Summary of PL/I Built-In Subroutines D-16
Kednos PL/I for UNIX is a strict superset of the ANSI X3.74-1981 PL/I General Purpose Subset and provides most of the features of the new ANSI X3.74-1987 PL/I General Purpose Subset and many of the features of the ANSI X3.53-1976 (full) PL/I language standard.
This manual is intended for programmers using PL/I to design or implement applications on UNIX systems. A prerequisite for attaining optimal benefit from the manual is that its users understand the concepts of programming in PL/I and are familiar with the keywords and topics that will be searched for information.
The Kednos PL/I for UNIX User's Manual provides information on program development with the system-specific command language, the extensive I/O capabilities provided in PL/I, and programming techniques available to PL/I programs executing under the exclusive control of the operating system.
For information on installing PL/I, see the Kednos PL/I for UNIX Installation Guide.
All descriptions of the effects of executing statements and evaluating expressions assume that the initial procedure activation of the program is through an entry point with OPTIONS(MAIN).
It is further assumed that any non-PL/I procedures called by the program follow all PL/I calling conventions and all conventions of the PL/I run-time environment. Except as explicitly noted, descriptions of I/O statements do not cover the effects of system-specific options.
For details on mixed-language programming and system-specific options, see the Kednos PL/I for UNIX User's Manual.
Information in this manual applies to the use of Kednos PL/I for UNIX on the Digital UNIX Operating System unless otherwise indicated.
The term PL/I refers to Kednos PL/I for UNIX.
The terms "full PL/I" and "standard PL/I" refer to the ANSI standard PL/I, X3.53--1976.
This chapter introduces the following elements of a PL/I program:
Future chapters discuss these topics in more detail.
This section describes the following topics:
A keyword is a name that has a special meaning to PL/I when used in a specific context. In context, keywords identify statements, attributes, options, and other program elements. PL/I keywords are not reserved words, so it is possible to use them in a program in other than their keyword context.
PL/I has numerous keywords. See , See Alphabetic Summary of Keywords describes the PL/I keywords, including brief identifications of their uses and valid abbreviations for the keywords that can be abbreviated.
PL/I recognizes punctuation marks in statements. The punctuation marks serve the following two functions:
In this statement, the equal sign (=), the addition operator (+), and the semicolon (;) delimit the identifiers A, B, and C, as well as define the operation to be performed. ( See , See Expressions and Data Type Conversions describes the effect of the various operators in expressions.)
Whenever you use a punctuation mark in a PL/I statement, you can precede or follow the character with any number of spaces (except in the case of an operator consisting of two characters, like >= or **, which you must enter without a space between the two characters). For example, the following two statements are equivalent:
DECLARE ( A, B ) FIXED DECIMAL ( 7, 0 ) ;
DECLARE(A,B)FIXED DECIMAL(7,0);
In the second statement, all nonessential spaces are omitted; the parentheses and commas are sufficient to distinguish elements in the statement. The only space required in this statement is the space that separates the two keywords FIXED and DECIMAL.
See . Punctuation Marks Recognized by PL/I lists all the punctuation marks recognized by PL/I.
The tilde (~) is equivalent to the circumflex (^), and the exclamation point (!) is equivalent to the vertical bar (|).
In addition to punctuation marks, PL/I accepts spaces, tabs, and line-end characters between identifiers, constants, and keywords.
The rules for entering spaces are:
The line-end character is a valid punctuation mark between items in a PL/I statement except when it is embedded in a string constant. In a string constant, the line-end character is ignored. For example:
A = 'THIS IS A VERY LONG STRING THAT MUST BE CONTI
NUED ON MORE THAN ONE LINE IN THE SOURCE FILE';
This assignment statement gives the variable A the value of the specified character-string constant. (The line-end character in the constant is ignored.) Note that any tabs or spaces preceding NUED in the previous example will be included in the string.
An identifier is a user-supplied name for a procedure, a statement label, or a variable that represents a data item. The rules for forming identifiers are:
A comment is an informational tool for documenting a PL/I program. To insert a comment in a program, enclose it within the character pairs /* and */. For example:
Wherever the starting characters (/*) appear in a program, the compiler ignores all text until it encounters the ending characters (*/). A comment can span several lines.
The rules for entering comments are:
The following are examples of comments:
/* ********* START OF SECOND PHASE ********* */
DECLARE/*COUNTER*/A FIXED BINARY (7);
/* This module performs the following steps:
1. Initializes all arrays and data structures.
2. Establishes default condition handlers.
Although complete comments cannot be nested, you can comment out a statement such as the following:
DECLARE EOF BIT(1); /* end-of-file */
To do this, precede the DECLARE statement with another /* pair, as follows:
/* DECLARE EOF BIT(1); /* end-of-file */
The compiler will then ignore all text, including the DECLARE statement and the second /*, until it reaches the */.
A statement is the basic element of a PL/I procedure. Statements are used to do the following:
See . Summary of PL/I Statements and See . Summary of PL/I Preprocessor Statements provide summaries of PL/I statements. Detailed descriptions of these statements appear throughout this manual.
The general format of a PL/I statement consists of an optional condition prefix, an optional statement label, the body of the statement, and the required semicolon terminator. The format of a statement is:
[ ( condition-prefix [ ,condition-prefix ] ... ) : ] [ label: ] statement-body;
The optional condition prefix specifies a PL/I condition to enable or disable for the statement. If you disable a condition, no program interrupt results if the condition occurs during execution of the statement.
The condition prefix precedes the statement label, if you specify a label, and the statement body. It consists of any valid condition or list of conditions, or the negated version of the condition or conditions, enclosed in parentheses, terminated by a colon. For example:
(ERROR,NOENDFILE): NEWREC: READ FILE (INFILE) INTO (INREC);
Any statement except precompiler statements (statements beginning with the % character), and the DECLARE, DEFAULT, or ENTRY statements can have condition prefixes.
If you use a condition prefix on a FORMAT statement, it must be the same prefix used on the referring GET or PUT statement.
The optional statement label identifies a statement so that it can be referred to elsewhere in the program, for example, as the target of a GOTO statement. A label precedes a statement; it consists of any valid identifier terminated by a colon. For example:
READ_LOOP: READ FILE (TEXT) INTO (TEMP);
A statement cannot have more than one label. See See Identifiers for more information on identifier format.
A simple statement contains only one action to be performed. There are three types of simple statements:
Keyword statements are identified by the PL/I keyword that requests a specific action. Examples of keyword statements are:
DECLARE COUNTER FIXED BINARY (7);
In these examples, READ, GOTO, and DECLARE are keywords that identify these statements to PL/I.
A compound statement contains more than one PL/I statement within the statement body. It is terminated by the semicolon that terminates the final statement. The IF and ON statements are examples of compound statements.
Preprocessor statements start with a percent sign (%). They can be simple or compound, as described in the preceding sections. For a full description of preprocessor statements, see See , See Preprocessor .
You can group PL/I statements by function into the following categories.
These statements identify files and data formats and perform input and output operations:
These statements define the organization of the program into procedures, blocks, and groups:
These statements change or interrupt the normal sequential flow of execution in a PL/I program:
These statements acquire and control the use of storage in a PL/I program:
See . Summary of PL/I Statements gives a summary of the PL/I statements and their uses.
A PL/I program consists of a series of statements, which perform the following tasks:
A statement comprises user-specified identifiers, constants, and PL/I keywords, separated by blanks, comments, and punctuation marks. You can organize statements into structural sequences of groups or blocks. See . Structure of a PL/I Program shows the structure of a PL/I program.
SAMPLE: PROCEDURE OPTIONS (MAIN);
MESSAGE CHARACTER(80) INITIAL ('HELLO'),
CALC ENTRY (FLOAT) RETURNS (FLOAT),
DECLARE TEXT (5) CHARACTER (20);
Key to See . Structure of a PL/I Program :
A PROCEDURE is the basic executable program unit.
À The declarations of variables in a procedure are usually, but not necessarily, placed at the beginning of the procedure.
à Executable statements are placed following variable declarations.
Õ Internal procedures may be placed anywhere.
All procedures must terminate with END statements.
The source text of a PL/I program is freeform. As long as you terminate every statement with a semicolon (;), individual statements can begin in any column, be on additional lines, or be written with more than one statement to a line.
Individual keywords or identifiers of a statement, however, must be confined to one line. Only a character-string constant (which must be enclosed in apostrophes) can be on more than one line.
PL/I programs are easier to read and comprehend if you follow a standard pattern in formatting. For example:
PL/I is a block-structured language with each block composed of a sequence of PL/I statements. There are two types of blocks:
The scope of a declaration of a name is that region of the program in which the name has meaning. A name has meaning in the following locations:
Two or more declarations of the same name are not allowed in a single block unless one or more of the declarations are of structure members.
Two declarations of the same name in different blocks denote distinct objects unless both specify the EXTERNAL attribute. All EXTERNAL declarations of a particular name denote the same variable or constant, and all must agree as to the properties of the variable or constant, otherwise unpredictable results will occur. Note that EXTERNAL is the default for declarations of ENTRY and FILE constants. It must be specified explicitly for variables.
The following example shows the scope of internal names:
Declarations can appear outside procedures and, if contained within the same block, have meaning throughout all procedures contained in the block. However, if there are multiple blocks, declarations outside procedures must have the EXTERNAL attribute if they are to be recognized by all blocks and procedures in the program. For example:
