GC33-0009-4

File No. S360/S370-29

OS
PL/I Checkout and
Optimizing Compilers:
Program Product Language Reference Manual

Program Numbers 5734-PL 1

5734-PL2
5734-LM4
5734-LM5
(These program products are available
as composite package 5734-PL3)
Fifth Edition (October 1976)
This is a major revision of, and obsoletes, GC33-0009-3. This edition
applies to Version 1, Release 3, Modification 0 of the OS PL/I Checkout
Compiler, Program Product 5734-PL2; Version 1, Release 3, Modification 0
of the OS PLII Optimizing Compiler, Program Product 5734-PL1; and all
subsequent versions, releases, or modifications.
Information in this publication is subject to significant change.
Before using the publication, consult the latest IBM System/370
Bibliography, GC20-0001, and the technical newsletters that amend the
bibliography, to learn which edition and technical newsletters are
applicable and current.
Requests for copies of IBM publications should be made to the IBM branch
office that serves you.
Forms for readers' comments are provided at the back of this publication.
If the form has been removed, comments may be address to IBM
Corporation, P.O. Box 50020, Programming Publishing, San Jose,
California 95150, USA. All comments and suggestions become the property
of IBM.
e Copyright International Business Machines Corporation
1970,1971,1972,1973,1976
 Preface

This publication is planned for use as a Part II, "Rules and Syntactic
reference book by the PL/I programmer. It Descriptions," provides a quick reference
is not a tutorial publication, but is to specific intormation. It includes less
designed for the reader who already has a information about interrelationships, but
knowledge of the language and who requires i t is organized so that a particular
a source of reference material. question can be answered quickly. Part II
is organized purely from a reference point
The publication is in two parts. Part I of view; it is not intended for sequential
contains discussions of concepts of the reading.
language. Part II contains detailed rules
and syntactic descriptions.
For example, a programmer would read
Although implementation information is chapter 5, ·statement Classification" in
included, the book is not a complete Part I for information about the
description of any implementation interactions of different statements in a
environment. In general, it contains program; but he would look in section J,
information needed to write a program that "Statements" in Part II, to find all the
will be processed by the os PL/I Optimizing rules for the use of a specific statement,
Compiler or the as PL/I Checkout Compiler. its effect, options allowed, and the forma~
It does not contain all the information in which it is writ~en.
needed to execute programs. For further
information on executing a program refer to In the same manner, he would read
the appropriate programmer's guide (for chapter 4, "Expressions and Data
batch processing only) or the Time Sharing Conversions" in Part I for a discussion of
Option or CMS publications (for processing the concepts of data conversion, but he
in conversational mode). would use section F, "Data Conversion and
Expression Evaluation" in Part II, to
In order to execute programs processed determine the exact results of a particula~
by these compilers, subroutine libraries type of conversion.
are required. The subroutines are provided
by the OS PL/I resident library (optimizing An explanation of the syntax language
compiler only) and the OS PL/I transient used in this publication to describe
library (both compilers). elements of PL/I is contained in section A,
"Syntax Notation" in Part II.
Programs that have been compiled by the
PL/I Optimizing Compiler and which utilize
PL/I multitasking facilities can be
executed only under the MVT or VS2 version Requisite Publications
of the operating system.

For information necessary to compile, link

edit, and execute a program, the reader
Use of this Publication should be familiar with the appropriate one
of the following publications:

This publication is designed as a reference as PL/I Optimizing Compiler:

book for the PL/I programmer. Its two-part Programmer's Guide, Order No. SC33-0006
format allows a presentation of the
material in such a way that references can as PL/I Checkout Compiler: programmer's
be found quickly, in as much or as little Guide, Order No. SC33-0007
detail as the user needs.
as PL/I Optimizing Compiler: TSO User's
Part I, ·Concepts of PL/I,· is composed Guide, Order No. SC33-0029
of discussions and examples that explain
the different features of the language and as PL/I Checkout Compiler: TSO User's
their interrelationships. To reduce th~ Guide, Order No. SC33-0033
need for cross references and to allow each
chapter to stand alone as a complete as PL/I Optimizing Compiler: CMS User's
reference to its subject, some information Guide, order No. SC33-0037
is repeated from one chapter to another.
Fart I can, nevertheless, be read as PL/I Checkout Compiler: CMS User's
sequentially in its entirety. Guide, Order No. SC33-0047

iii
Recommended Publications Availability of Publications

The subjects covered in the following

publications include the compiler
facilities, the optimization or checkout
features (whichever are applicable), The availability of a publication is
methods of implementing the various indicated by its use key, the first letter
language features, and comparisons of the in the order number. The use keys for
language implemented by the OS PL/I publications referred to in this manual
Optimizing or Checkout Compilers with that are:
implemented by the PL/I(F) Compiler.

OS PL/I Optimizing Compiler: General G - General: available to users of

Information, Order No. GC33-0001 IBM systems, products, and
services without charge, in
OS PL/I Checkout Compiler: General quantities to meet their normal
Information, Order No. GC33-0003 requirements; can also be
purchased by anyone through IBM
OS PL/I Optimizing Compiler: Execution branch offices.
Logic, Order No. SC33-0025

OS PL/I Checkout Compiler: Execution S - Sell: can be purchased by anyone

Logic, Order No. SC33-0032 through IBM branch offices.

iv
 Contents

PART I: CONCEPTS OF PL/I • • • • 1 Structures • • • • • 29

other Attributes 29
CHAPTER 1: BASIC CHARACTERISTICS OF DEFINED Attribute 30
PL/I • 3 LIKE Attribute • • • 30
Machine Independence • • • • • 3 ALIGNED and UNALIGNED Attributes 31
Program structure • • • • • • • 3 INITIAL Attribute 32
Data Types and Data Description 3
Default Assumptions 3 CHAPTER 4: EXPRESSIONS AND DATA
Storage Allocation • • • • 4 CONVERSION 35
Expressions • • • • • • • • 4 Use of Expressions 35
Data Collections 4 Data Conversion • • 36
Input and Output 5 Operational Expressions 36
Multitasking 5 ASSignment • • • • • • • 36
Facilities of the Two Compilers • 6 Problem Data Conversion 36
Compile-time Operations • • 6 Locator Data Conversion 37
Execution-time Facilities • 6 Use of Built-in Functions 37
Interrupt Activities 7 Expression Operations • • • • 37
Operating System Facilities 7 Arithmetic Operations • • • • 38
Results of Arithmetic Operations 38
CHAPTER 2: PROGRAM ELEMENTS 9 Operations using Built-in
Character Sets 9 Functions • • • • • • • • • 38
60-character Set • • • • 9 Bit-string Operations • • • • 38
48-character Set • • • • 9 Boolean Built-in Function 39
Using the Character set 10 Comparison Operations 39
Identifiers 10 Concatenation Operations • • 40
Blanks • • • • • • 10 Combinations of Operations • 40
Comments • • • • • 11 Priority of Operators 41
Basic Program Structure • • 12 Function Reference Operands 42
Simple and compound statements 12 Attributes of Targets • 43
statement Prefixes 12 Array Expressions • • • • • 43
Groups and Blocks 13 Prefix Operators and Arrays 44
Infix Operators and Arrays • • 44
CHAPTER 3: DATA ELEMENTS. 15 Array-and-Element Operations • • 44
Data Types • • • • • • • • 15 Array-and-Array Operations • 44
Problem Data • • • • • • • 15 Array-and-structure Operations • 45
Arithmetic Data • • • • 15 Data Conversion in Array
Decimal Fixed-Point Data • 16 Expressions • • • • • • • • • • 45
Binary Fixed-Point Data • . • • 17 Structure Expressions • • • • • • • . 45
Decimal Floating-Point Data 18 Prefix Operators and Structures 45
Binary Floating-Point Data • 18 Infix Operators and Structures • • 46
Complex Arithmetic Data • • • . 19 Structure-and-Element Operations 46
Numeric Character Data 19 Structure-and-Structure
string Data 21 Operations • • • • • • • • 46
Character-String Data 21 structure Assignment BY NAME • • 46
Bit-string Data 22 Exceptional Conditions • • • • • 47
Uninitialized Variables 23
Program Control Data 23 CHAPTER 5: STATEMENT CLASSIFICATION 49
File Data 23 Classes of Statements • • • • • • 49
Label Data • 23 Descriptive Statements •• • • • 49
Entry Data 24 DECLARE and DEFAULT Statements 49
Event Data 24 other Descriptive Statements • 49
Task Data 24 Input/output statements • • • • • 50
Locator Data • 24 Record Transmission statements 50
Area Data 25 STREAM Transmission Statements 50
Data Organization • 25 Input/Output Control Statements 51
Arrays • • • • • 25 DISPLAY Statement • • • • • 51
Expressions as Subscripts 27 Data Movement and Computational
Cross-Sections of Arrays • 27 Statements • • • • • • • • • • • 51
Struct ures • • • • • • • 27 ASSignment Statement • • • • • 51
Qualified Names • • • • • 28 Program Organization Statements • 52
Arrays of Structures • • • • 29 PROCEDURE Statement 52
Cross-Sections of Arrays of ENTRY Statement • • • • • • 52

Contents v
 BEGIN Statement • • • • • • • 53 Programmer-defin~d Defaults for
END Statement • • • • • • • • 53 Parameter Descriptors • • 85
FETCH and RELEASE Statements 53 Programmer-defined Default for
Storage Control Statements ••••• 53 the RETURNS Option 85
ALLOCATE and FREE Statements 53 Restrictions of the Use of the
Control statements 54 DEFAULT Statement • • • • • • • 85
GO TO Statement • • • • 54
IF Statement • • 54 CHAPTER 8: STORAGE CONTROL • • 87
SELECT Statement • 55 Static storage • • • • 87
DO Statement • • 55 Automatic Storage • • • • • 87
Noniterative DO Statements . 58 Effect of Recursion on Automatic
LEAVE Statement . • • • • • 58 Variables • • • • •• • • • • 88
CALL, RETURN, and END Statements • 59 Controlled storage • • • • • • 88
STOP and EXIT Statements • 59 ALLOCATE Statement for Controlled
HALT statement • • • • • • • 59 Variables • • • • • • 89
Exception Control Statements 59 FREE Statement for Controlled
ON Statement • • • • 59 Variables • • • • • • • • • • 89
REVERT Statement • • • • • • • • • 60 Implicit Freeing • • • • • • • • 90
SIGNAL statement • • 60 Multiple Generations of Controlled
Preprocessor Statements 60 Variables • • • • • 90
Listing Control statements 60 Asterisk Notation • • • • 90
Diagnostic Statements • . • 61 Controlled Structures 91
CHECK and NOCHECK statements • 61 ALLOCATION Built-in Function 91
FLOW and NOFLOW statements • 61 Based storage • • . • . • . . • • • • 91
PUT Statements • • • • • • • 61 Based Variables 91
Locator Qualification 91
CHAPTER 6: PROGRAM ORGANIZATION 63 Pointer Variables • • • • 92
Blocks • • • • 63 Pointer Expression • • • • • • • 92
Procedure Blocks • • • • • • 63 Setting Pointer Variables 92
Begin Blocks • • • • • • • • 63 ADDR Built-in Function • • • 93
Internal and External Blocks • 64 Based Variables and Input/output • 93
Use of the END Stat.ement • 64 READ with SET Statement • • • • 94
Activation of Blocks 65 LOCATE Statement • • • • • • • • 94
Termination of Blocks • . • 67 self-defining Data (REFER Option) 95
Begin Block Termination 67 List Processing • • • • 96
Procedure Termination 68 ALLOCATE Statement for Based
Program Termination 69 Variables • • • • • • • • • • 97
Dynamic Loading of External FREE Statement for Based Variables 97
Procedure • • • • • • • • • • • 69 Multiple Generations of Based
storage Allocation • • • • • • 70 Variables • • • • • • . • • • • • 97
Reactivation of an Active Procedure NULL Built-in Function • 98
(Recursion) ••••• 71 Types of List • • • • 98
prologues and Epilogues 72 Areas • • • • • . • . . • . • 98
Prologues 72 Area Variables • • 99
Epilogues • • • • • 73 Offset Variables • • • •• 99
Locator Conversion • • • • • 99
CHAPTER 7: RECOGNITION OF NAMES 75 Offset Expressions • • 100
Explicit Declaration • • • • • • • • 75 ALLOCATE Statement with the IN
Scope of an Explicit Declaration • 76 Option • • • • • • • 100
Contextual Declaration • • • • • • • 76 FREE statement with the IN
Scope of a Contextual Declaration 76 Option • • • • • • 101
Implicit Declaration • • • • • • • • 77 EMPTY Built-In Function • 101
Examples of Declarations • • • • 77 Area Assignment • • • • •• 101
INTERNAL and EXTERNAL Attributes 78 AREA ON-Condition •• 101
scope of Member Names of Input/output of Areas •••• 102
External Structures • • • • 80 Multiple Locator Qualification • • 102
Multiple Declarations and Ambiguous Levels of Locator Qualification 102
References • • • • • • • • • • 80
Default Attributes • • • • • • 81 CHAPTER 9: SUBROUTINES AND FUNCTIONS 105
Processes in the Application of Entry points of Subroutines and
Attributes • • • • • • • • 81 Functions • • • • • • • • • 106
Application of Standard Defaults • 81 ENTRY Attribute • • • • • • 106
Problem Data • • • • • 82 Exit-points of Subroutines and
Program Control Data • • • • • • 82 Functions • • • • • • • • • 106
Default statement • • • • • • • • • • 83 RETURNS Attribute and RETURNS
Restoring standard Defaults 84 Option • • • • • 106
Scope of the DEFAULT Statement • 84 Subroutines • • • • • • 107
Factored Default Specification • 85 Functions • • •• • • • • • • • • 108

vi OS PL/I CKT AND OPT LRM PART II

 Attributes of Returned Values • • 109 List-Directed Data in the Stream 139
Generic Entry Names and References • 110 List-Directed Input Format • • • 139
Built-in Functions • • • • • 111 List-Directed Output Format 139
FORTRAN Library Functions • 112 Data-directed Data Specification lll0
Built-in Subroutines • 112 Data-Directed Data in the Stream 140
Relationship of Arguments and Data-Directed Data Specification
Parameters • • • • • • 113 for Input • • • • • • • • • • • 141
Dummy Arguments • 113 Data-Directed Data Specification
Entry Attribute • 114 for output • • • • • • • lll2
Parameter Descriptor Lists • 114 Length of Data-Directed output
Entry Expressions as Arguments • 115 Fields • • • • • • • • • • • • lll3
Allocation of Parameters. • • 117 Example • • • • • • • • • • • • 143
Parameter Attributes. • • • 117 Edit-directed Data Specification • • lll3
Parameter Bounds, Lengths, and Format Lists • • • • • lll4
Sizes • • • • • • • • • • • 117 PRINT Files • • • • • • • • • lll1
Simple Parameter Bounds, Standard File SYSPRINT • • lll8
Lengths, and Sizes • 118 ENVIRONMENT Attribute • • . 148
Controlled Parameter Bounds, Record Format Options • • • • lll9
Lengths, and Sizes • 118 Fixed-length Records • • • • • • lll9
Argument and Parameter Types • • • 119 variable-length Records • • • • 1119
Passing an Argument to the Main Undefined-length Records • 150
Procedure • • • • • • • • • • • 120 RECSIZE Option • • • • 150
BLKSIZE Opt.ion • • • • 150
CHAPTER 10: INPUT AND OUTPUT • • 121 Record Format Defaults • • 151
Data sets • • • • • • • • • • • • 121 Buffer Allocation 152
Information Interchange Codes 122 BUFFERS Option • • • . 152
Files • • • • • • • • • • • • 122 DCB Subparameter • • • • • 152
File Attribute • • • • • • • • • • 123 Data Set Organization • 152
Alternative Attributes • • • • • • 123 CONSECUTIVE Data Sets 152
STREAM and RECORD Attributes • • 124 Magnetic Tape Handling Options • • 153
INPUT, OUTPUT, and UPDATE LEAVE and REREAD options • • 153
Attributes • • • • • 124 ASCII Data Sets • • • • • • • • • 153
SEQUENTIAL, DIRECT and TRANSIENT ASCII Option • • • • • • • • • • 153
Attributes • • • • • 124 BUFOFF Option and Block Prefix
BUFFERED and UNBUFFERED Fields • • • • • • • • • • • • 153
Attributes • • • • • 12ll D-format and DB-format Records • 15ll
Additive Attributes • • • 125 Default Rules • • • • • • • • • 15ll
PRINT Attribute • • • • • • 125
BACKWARDS Attribute • 125 CHAPTER 12: RECORD-ORIENTED
KEYED Attribute •• 125 TRANSMISSION • • • • • 155
EXCLUSIVE Attribute 125 Data Transmitted • • • • • 155
ENVIRONMENT Attribute • 125 Data Aggregates 155
Opening and Closing Files • • 126 Unaligned Bit Strings 155
OPEN Statement • • • • • 126 Varying-Length Strings and Area
Implicit Opening • • • • 121 Variables • • • • • • • 155
Merging of Attributes • 127 Data Transmission Statements 155
Associating Data Sets with Files 128 READ Statement • • 156
CLOSE Statement • • • • • • 130 WRITE statement • • • • • • • • 156
Standard Files • • • • • • • 130 REWRITE Statement • • • • • 156
LOCATE Statement • • • 156
CHAPTER 11: STREAM-ORIENTED DELETE Statement • 156
TRANSMISSION • • • • • • • • • 133 UNLOCK Statement • • 156
List-directed Transmission • • 133 options of Transmission Statements • 156
Data-directed Transmission • • 133 FILE Option • • • • • 156
Edit-directed Transmission • • 13ll INTO Option 151
Data Transmission Statements • 134 FROM Option 151
Options of Transmission statements • 135 SET Option • • 151
FILE and STRING Options • 135 IGNORE Option • • • 151
COpy Option • 135 KEY Option • • • • • • • • • 158
SKIP Option • • • • • 135 KEY FROM and KEYTO Options 158
PAGE Option • • • • • • • • • • 135 EVENT Option • • • • • 158
LINE Option • 136 NOLOCK Option • 159
Data Specifications • • • • 136 processing Modes • • • • • 159
Data Lists • • • • • • • 136 Move Mode 159
Repetitive Specification • • 131 Locate Mode • • • • 161
Transmission of Data-List ENVIRONMENT Attribute • 162
Elements • • • • • • • • • 138 Record Format Options 162
List-directed Data Specification • • 138 Fixed-length Records • • 164

Contents vii
 Variable-length Records • 164 Direct Access • • • • • • • 190
Undefined-length Records • • 165 Regional(3) Organizatipn • • • • • 190
RECSIZE Option • • • • • • • 165 Dummy Records 190
BLKSIZE Option • • • • • • • 166 creating a Data set • • 190
Record Format Defaults • 167 sequential Access • 191
Buffer Allocation • 167 Direct Access • • • • • • • • • 191
BUFFERS Option • • • • • • 167 VSAM Organization • • • • • • • • 192
Data Set Organization • 168 Keys for VSAM data sets 192
CONSECUTIVE Data Sets • 168 Keys for Indexed VSAM Data Sets 192
INDEXED Data sets • 168 Relative Byte Addresses (RBA) • 192
REGIONAL Data Sets • • 168 Relative Record Numbers • 192
VSAM Data Sets • • • • 168 Entry-Sequenced Data Sets . • • • 193
PASSWORD Option • • • • • • • • • 169 Loading an ESDS • • • • • • 193
SKIP and SIS Options • • 169 Sequential Access • 193
BKWD Option • 170 Key-Sequenced Data sets • • 193
REUSE Option • • • • • • • • • • • 170 Loading a KSDS • • • • • 193
BUFND Option • • 170 sequential Access • • 193
BUFNI Option • • 170 Direct Access • • • • • 194
BUFSP Option • • • • • • • 170 Use of the SKIP option • 194
Optimization of Input/Output Use of the SIS option • • • 194
Operations • • • • • • • • • • • 1 70 SAMEKEY Built-In Function 194
Teleprocessing Data Sets • • • • 171 Relative Record Data Sets • • 194
Magnetic Tape Handling Options • • 171 Loading an RRDS • • 194
LEAVE and REREAD Options • 171 sequential Access . • • • 196
printer/punch Control Direct Access 199
(CTL360/CTLASA) • • • • • • • 172 Teleprocessing • • • • • • • 199
Data Interchange (COBOL) • • • 173 ENVIRONMENT Attribute 199
In-line Code Optimization (TOTAL) 174 TRANSIENT Attribute • • 202
Data Management Optimization Error Handling • • • • • • • • • 202
(INDEXAREA/NOWRIT /ADDBUFF) • • • 174 statements and Options • • • 203
Key Classification (GENKEY) • 174 Summary of Record-oriented
Number of Channel Programs lNCP) • 175 Transmission • • • • • • • • • • • • 204
Track Overflow (TRKOFL) • 175 Examples of Declarations for Record
Varying-length string Option Files • • • • • • • • • • • 205
(SCALARVARYING) • • • • • • • 175
Key Length Option (KEYLENGTH) 176 CHAPTER 13: EDITING AND STRING
Key Location Option (KEYLOC) • 176 HANDLING • • • • • • • • 207
DCB Subparameters • • • • • • • 176 Editing by ASSignment • • • • • 201
Device-associated Files (IBM 3525 Altering the Length of String Data 201
Card Punch) • • • • 176 Other Forms of ASSignment • • 208
ASCII Data Sets • • • • • • • 171 Input and output Operations 208
ASCII Option • • • • • • • • 171 STRING Option in GET and PUT
BUFOFF option and Block Prefix Statements • • • • • • • • • • 208
Fields • • • • • • • • • • • • 178 Picture Specification • • • • • • 209
D-format and DB-format Records • 178 Numeric Character Specifications 209
Default Rules • 178 Picture Character '9' in Numeric
Consecutive organization • 178 Character Specifications • • • 210
Sequential Update • 179 Picture Characters Z * . . . . . 210
Indexed Organization • 179 Picture Character V • • • • • • 211
Keys • • • • • • • Insertion Picture Characters B •
Embedded Keys
•
• • • • • •
179
180 , / ............ • • 211
Dummy Records • 183 Picture Character $ •• • • 211
Creating a Data set • 183 Sign SpeCification in Numeric
sequential Access • 183 Character Specifications • 212
Direct Access • • • • • 183 overpunched Sign Specification
Regional Organization • • 184 Characters, T I R • • • • • 212
Keys • • • • • • • • • 184 Other Numeric Character
Types of Regional organization • • 185 Facilities • • • • • • • • 212
Regional(l) Organization • • • • • 185 Character-String Picture
Dummy Records • • • • • • • • • 185 Specifications • 212
Creating a REGIONAL(l) Data set 185 Bit-string Handling • • • • • • • 213
sequential Access • 187 String Built-in Functions • • • • 214
Direct Access • • • • • 187
Regional(2) Organization • 188 CHAPTER 14: EXCEPTIONAL CONDITION
Source Keys • • • • • 188 HANDLING AND PROGRAM CHECKOUT • 217
Dummy Records • • • • • • 189 Enabled Conditions and Established
Creating a Data Set • 189 Action • • • • • • • • • • • 217
Sequential Access • 1.89 Condition Prefixes • • • • • • • 217

viii os PL/I CKT AND OPT LRM PART II

 scope of the Condition Prefix • 218 Variables • • • • • 256
ON statement • • • • • • 218 DELAY Statement • 251
Null On-Unit • • • • • • • • • • 219 Termination of Tasks • 251
Scope of the ON Statement • 219 programmdng Example • • • 258
Dynamically Descendant On-Units 219
On-units for File Parameters and CRAPTER 18: EFFICIENT PROGRAMMING • 261
File Variables • 219 Optimization Facilities • 261
REVERT Statement • • • 221 The Compiler • • • • • • • • • 261
SIGNAL Statement • • • • 221 The Libraries • • • • • • • • 262
CONDITION Condition • 221 The System Environment • 262
CHECK Condition • 221 Efficient performance • • 262
SIZE condition • • • • • 222 Tuning a PL/I Program - Stage 1 • 262
SUBSCRIPTRANGE Condition • • 222 Tuning a PL/I Program - Stage 2 • 263
STRINGRANGE Condition • 222 Tuning a PL/I Program - Stage 3 • 264
Condition Built-~n Functions and Tuning a Program for a Virtual
Condition Codes • • • • • • 223 Storage system • 268
Example of Use of ON-conditions • 223 Modular Programming • • • • 269
In-line Operations 211
CHAPTER 15: EXECUTION-TIME Data Conversion 271
FACILITIES OF THE CHECKOUT COMPILER 227 String Handling • 273
Tracing Facilities • • • • • • • • • 228 Global optimization Features • • • • 213
CHECK and NOCHECK statements • • 228 Common Expressions • • • • • • 273
FLOW Statement • • • • • • • 230 Interrupt Handling for Programs
NOFLOW Statement • ~ • 232 with Common Expression
Current status List • • 232 Elimination • • • • • • • • • • 214
PUT Variables • 232 Transfer of Invariant Expressions
PUT SNAP Statement • • 235 or Statements • • • • • • • 274
PUT FLOW Statement • • 235 ORDER and REORDER Options • • • • 275
PUT ALL· Statement • • • • • 236 ORDER Option • • • • • • • • 215
Program Amending • 237 REORDER Option • • • • • • • • • 215
Elimination of Redundant
CHAPTER 16: COMPILE-TIME FACILITIES 239 Expressions • • • • • • • • 276
Preprocessor Input and Output • • • • 239 Expression Simplification • • 276
Preprocessor Scan • • • • • • • • 239 Taking Advantage of Global
Rescanning and Replacement • • • 240 Optimization • • • • • • 276
Character Strings and Comments • 241 Common Expression Elimination • 276
Preprocessor Variables • • • • • 242 Transfer of Invariant
Preprocessor Expressions • • • • • • 242 Express ions • • • • • • • • • • 271
Preprocessor Procedures • • 243 Redundant Expression Elimination 278
Invocation of Preprocessor Other Optimization Features • • 218
Procedures • • • • • • • 243 Common Errors and Pitfalls • • • • • 278
Arguments and Parameters for Operating system and Job Control • 218
Preprocessor Functions • 244 Source Program and General Syntax 218
Returned Value • • • • • • 244 Program Control • • • • • • • • • 279
Example of Preprocessor Declarations and Attributes 219
Functions • • • • • • • • • 244 Assignments and Initialization • • 281
preprocessor Built-in Functions 246 Arithmetic and Logical Operations 282
Preprocessor DO-Group • • • • 247 DO-Groups 284
Inclusion of External Text • 247 Data Aggregates • • •• 285
Preprocessor Statements • • • 248 Strings • • • • • • •• 285
Listing Control statements • 249 Functions and Pseudovariables • • 285
ON-conditions and On-units 285
CHAPTER 17: MULTITASKING. • 251 Input/Output • • • • • • • • 286
Tasking and Reentrability • • • • • • 252
Creation of Tasks • • 253 CHAPTER 19: INTERLANGUAGE
Call Statement • • • 253 COMMUNICATION FACILITIES • 289
TASK Option • 253 Interlanguage Facilities • • • • 289
EVENT Option • • 253 PaSSing Arguments to a COBOL or
PRIORITY Option • 254 FORTRAN Routine • • • • • • 290
Priority of Tasks • 254 Invocation • • • • • • • • 291
PRIORITY Built-in Function and passing Arguments to a PL/I
pseudovariable • • • • • • 254 Procedure • • • • • • 292
Coordination and Synchronization of Invocation • • • • • • • • • 293
Tasks •• • • • • • • • • • • • 255 Using Common Storage • 293
Sharing Data Between Tasks • • 255 Interlanguage Environment • • • • 294
Sharing Files Between Tasks • 256 Establishing the PL/I
WAIT Statement • • • • • • 256 Environment •••••• 294
Testing and Setting Event Establishing the FORTRAN

Contents ix
 Environment • • • • • • • • • • 294 Tables for Comparison Operations •• 350
Interrupt Handling • • • • • • • 294
GO TO statement • • • • . 296 SECTION G: BUILT-IN FUNCTIONS AND
Termination of FORTRAN and COBOL PSEUDO VARIABLES • • • • • • . 353
Routines • • 296 Classification of Built-in
Multitasking • • • • 297 Functions • • • • • • • • 353
COBOL Interface 297 String-handling Built-in
FORTRAN Interface • 297 Functions • • • • • • • 353
Compile-Time Return Codes • 299 Arithmetic Built-In Functions • 353
Execution-Time Return Codes • 301 Mathematical Built-In Functions 353
Array-Handling Built-In
PART II: RULES AND SYNTACTIC Functions • • • • • • • • • 354
DESCRIPTIONS • •••• · 303 Condition-handling Built-In
Functions • • . • • • . • 354
SECTION A: SYNTAX NOTATION • 305 storage Control Built-In
FUnctions • • • • • • • • • 354
SECTION B: CHARACTER SETS WITH Multitasking Built-In Functions 354
EBCDIC AND CARD-PUNCH CODES • • • • 307 Input/Output Built-In Functions 354
60-character Set • 307 preprocessor Built-In Functions 354
48-character Set • • • • • • • • 308 Miscellaneous Built-in Functions 354
Conversion of Arguments • • 354
SECTION C: KEYWORDS AND KEYWORD String-handling Built-In
ABBREVIATIONS • • • • • • • • • 309 Functions • • • • • • • 355
Arithmetic Built-In Functions • 355
SECTION D: PICTURE SPECIFICATION Mathematical Built-In Functions 355
CHARACTERS • • • • • • • • • • • • • 315 Array-handling Built-In
Picture Characters for Character- Functions • • • • • • • • • 355
string Data • • • • • • • • • • • • 315 Accuracy of the Mathematical
Picture Characters for Numeric Functions • • • • • 355
Character Data • • • • • • • • • 316 Aggregate Arguments • • • • 356
Digit and Decimal-point Specifiers 317 Null Arguments • • • • • • • • 356
Zero suppression Characters • • • 317 Non-Preprocessor Built-in
Insertion Characters • • • • • • • 318 FUnctions • • • • • • • • • 356
Signs and Currency Symbol • 319 Preprocessor Built-in Functions 356
Credit, Debit, overpunched, and Pseudovariables • • • • 356
Zero Replacement Signs • • • 322
Exponent Specifiers • • • •• 324 SECTION H: ON-CONDITIONS. 383
scaling Factor • • • • • . 324 Condition Codes (ON-codes) 383
ERROR Condition Code • • • • • • 384
SECTION E: EDIT-DIRECTED FORMAT FINISH Condition Codes 384
ITEMS • • • • • · • • 325 ERROR Condition Code • • • • 384
Data Format Items • • 325 NAME Condition Codes • • 384
Control Format Items • 325 RECORD Condition Codes • 384
Remote Format Item • • • • • • 326 TRANSMIT Condition Codes • 384
Use of Format Items • • • 326 KEY Condition Codes • • • 384
Alphabetic List of Format Items • 326 ENDFILE Condition Code • • • • • 384
A-Format Item • • • • • • • • • 326 UNDEFINEDFILE Condition Codes • 384
B-Format Item • • • 326 ENDPAGE Condition Code • • • 385
C-Format Item • • • 327 PENDING Condition Code • • 385
COLUMN Format Item • • • 327 STRINGSIZE Condition Code • • • 385
E-Format Item • • • • • • • 328 OVERFLOW Condition Code • • • • 385
F-Format Item • 329 FIXEDOVERFLOW Condition Code • • 385
LINE Format Item • 330 ZERODIVIDE Condition Code • 385
P-Format Item • • • • • 330 UNDERFLOW Condition Code • • • • 385
PAGE Format Item • • • • 330 SIZE Condition Code 385
R-Format Item • • • • • • • 331 STRINGRANGE Condition Code • • • 386
SKIP Format Item • 331 AREA Condition Codes • • • 386
X~Format Item • • • • • 331 ATTENTION Condition Code • 386
Table of CEIL values 333 CONDITION Condition Code • • 386
CHECK Condition Codes • 386
SECTION F: DATA CONVERSION AND SUBSCRIPTRANGE Condition Code • 386
EXPRESSION EVALUATION • 335 CONVERSION Condition Codes • • • 386
Example of Use of the Conversion Multiple Interrupts • • • • • • • 391
Rules • 336 List of Conditions • • • • • • 392
Step 1 • • • 336 Classification of Conditions • • • • 392
Step 2 • • • 336
Step 3 • • 336 SECTION I: ATTRIBUTES • • 405
Tables for Arithmetic Operations • • 349 ALIGNED and UNALIGNED • 405

x OS PL/I CKT AND OPT LRM PART II

 AREA • • • • • • • • • • • • • • 408 Assignment Statement • • 441
AUTOMATIC, STATIC, CONTROLLED BEGIN • • • • • 443
and BASED • • 408 CALL • • • • 444
BACKWARDS • . • • • • • 410 CHECK • 445
BASED • • • • • • 410 CLOSE • • • • • • • • • • 446
BINARY and DECIMAL • • • 410 DECLARE • • • • • 446
BIT, CHARACTER, and VARYING 410 DEFAULT • • • • • • • • • • 447
BUFFERED and UNBUFFERED • 411 DELAY • • 450
BUILTIN • • • • • • • • • • 411 DELETE • 450
CHARACTER • 412 DISPLAY • 451
COMPLEX and REAL • • • 412 DO • • • • • • • •• • • 451
CONDITION • 412 END • • • • • 454
CONNECTED · 412 ENTRY • 455
CONTROLLED • • • 412 EXIT • • • • • • • • • • • • 456
DECIMAL • • •• • • 413 FETCH • • 456
DEFINED 413 FLOW • . • • 457
Simple Defining • • 414 FORMAT . • • • • • • •• 457
iSUB Defining • 415 FREE • • • • • • • • 458
String Overlay Defining • • 416 GET • • • • • 459
Dimension Attribute • 417 GO TO • • •• • • 460
DIRECT, SEQUENTIAL, and HALT • • • 461
TRANSIENT • • • • • • • • 417 IF • • • • • • • • 461
ENTRY • • • • • • • • • • 418 LEAVE • • • • • 462
Rules for Parameter Descriptor LOCATE • • • • • • • • • • • 462
lists • • • ••• • . 418 NOCHECK • 462
ENVIRONMENT • • • • . 421 NOFLOW . • 463
EVENT • • • • • 421 Null Statement • • 463
EXCLUSIVE 423 ON • • • • • • • 463
EXTERNAL and INTERNAL • • 423 OPEN • • • • • • 464
FILE • • • • • • 423 PROCEDURE • • • • • 466
FIXED and FLOAT • . • • •• 424 PUT • 468
FLOAT • • • • •• 424 READ • • • • • • • • • • 470
GENERIC • • • • • 425 RELEASE • 472
INITIAL • • • • • • • • • • 426 RETURN. • 472
INPUT, OUTPUT, and UPDATE • 428 REVERT • • • 473
INTERNAL • • • •• • • • • • 428 REWRITE 473
IRREDUCIBLE and REDUCIBLE • 428 SELECT • • 474
KEYED • • • • • . 429 SIGNAL • • 475
LABEL • • • • • • 429 STOP. • • 475
Length Attribute • • 430 UNLOCK • • • 475
LIKE • • 430 WAIT •• • • 476
OFFSET and POINTER • 431 WRITE • • 477
OPTIONS • • • • • • • 432 Preprocessor Statements • • 478
OUTPUT • • • • • • • 434 ~ACTIVATE • • • • • • 478
Parameter Attribute • 434 lassignment Statement . • • • • 479
PICTURE • • • • • • • 434 IDEACTIVATE • • • • • • • 479
POINTER • • • • • • 435 10 ECLARE • 479
POSITION • • • • • • • 435 "DO • • • • • • • • • • • • 480
Precision Attribute • 435 ~END • • • 480
PRINT • • • .• . • • • 436 ';GO TO • • 480
REAL • • • • • • • • • • • • • • 436 IIF 481
RECORD and STREAM • 436 II NCLUDE •••• • • 481
REDUCIBLE • • • • • 436 INOTE • • • • • 482
RETURNS • • • • • 437 Inull Statement • • 482
SEQUENTIAL . 437 IPROCEDURE . . • • • 482
Size Attribute • . 437 Preprocessor RETURN • 483
STATIC • • . . • •. . 437 Listing Control Statements • • 483
STREAM • • • • 437 ICONTROL • • • 483
TASK • • • 437 "NOPRINT • • 484
TRANSIENT • • 438 IPAGE • • 484
UNALIGNED . . • • . 438 "PRINT • • • 484
UNBUFFERED . • . 438 "SKIP • 485
UPDATE • • 438
VARIABLE • • • 438 SECTION K: DATA MAPPING • • 487
VARYING • • • • • 438 Structure Mapping • • • • • 487
Rules for Order of pairing • • • • 487
SECTION J: STATEMENTS • 439 Rules for Mapping One pair •• 48B
ALLOCATE • • . • • • • • 439 Effect of UNALIGNED Attribute • • 488

Contents xi
 Example of structure Mapping • • • 489
Record Alignment • • • • • • • • 502

SECTION L: COMPILER DIFFERENCES 505

GLOSSARY • 511

INDEX • • 525

xii OS PL/I CKT AND OPT LRM PART II

 Figures

Figure 2.1. Some functions of Figure 12.12 (Part 1 of 2).

special characters • • • • • • 11 Statements and options permitted for
Figure 3.1. Section of main storage loading and acceSSing VSAM entry-
showing alignment of fixed length sequenced data sets • • • • • • 1-95
fields • • • • • • • . • • 31 Figure 12.12 (Part 2 of 2).
Figure 7.1. Scopes of data Statements and options permitted for
declarations • • • • • • • • • • • • 78 loading and accessing VSAM entry-
Figure 7.2. Scopes of entry and sequenced data sets • • • • • • 196
label declarations •• • • 18 Figure 12.13 (Part 1 of 3).
Figure 8.1. Example of one- Statements and options permitted for
directional chain • • •• 98 creating and accessing VSAM data
Figure 10.1. Effect of operations on sets via prime or alternate in de 191
EXCLUSIVE files • • • •• 126 Figure 12.13 (Part 2 of 3).
Figure 11.1. General format for statements and options permitted for
repetitive specifications • • • • • 137 creating and acceSSing VSAM data
Figure 11.2. Example of data- sets via prime or alternate inde 198
directed transmission (both input Figure 12.13 (Part 3 of 3).
and output) •••••••••••• 143 Statements and options permitted for
Figure 11.3. options and format creating and acceSSing VSAM data
items for controlling layout of sets via prime or alternate inde 199
PRINT files •• . • • 148 Figure 12.14 (Part 1 of 3).
Figure 11.4. Effect of LEAVE and Statements and options permitted for
REREAD options • • •• • • • • • 153 creating and acceSSing VSAM relative-
Figure 12.1. Input and output: move record data sets . • • • • • • • 200
mode • • • • • • . • • • • • • • • • 160 Figure 12.14 (Part 2 of 3).
Figure 12.2. Locate mode input, move Statements and options permitted for
mode output • • • • • 163 creating and acceSSing VSAM relative-
Figure 12.3. Effect of LEAVE and record data sets • • • • • • • • 201
REREAD options. • • • • • • • • 112 Figure 12.14 (Part 3 of 3).
Figure 12.4. CTLASA and CTL360 print statements and options permitted for
control codes for the IBM 1403 creating and accessing VSAM relative-
Printer • • • • • • • • • • • 112 record data sets • • • • • • • • • • 202
Figure 12.5. CTLASA and CTL360 Figure 12.15 Statements and options
control codes for the IBM 2540 Card permitted for TRANSIENT files • 204
Read Punch • • • • • • • • • • • 113 Figure 14.1. A program checkout
Figure 12.6. CTLASA print control routine • • • • • • • • • • • • 224
codes for the IBM 3525 Card Punch • 113 Figure 15.1. Example of use of CHECK
Figure 12.1. CTL360 print control statement • • • • • • • • • • • • • 231
codes for the IBM 3525 Card Punch • 113 Figure 15.2. Flow comments produced
Figure 12.8. statements and options by various transfers of control 233
permitted for creating and accessing Figure 15.3. Program information
CONSECUTIVE data sets • • • • • 180 provided by the PUT statement
Figure 12.9 (Part 1 of 2). options • • • • • • • • • • • • 233
statements and options permitted for Figure 15.4. Information transmitted
creating and accessing INDEXED data by PUT ALL statement • • • • 235
sets • • • • • • • • • • • • •• 181 Figure 17.1. Synchronous and
Figure 12.9 (Part 2 of 2). asynchronous operation • • 251
statements and options permitted for Figure 11.2. Example of multitasking
creating and acceSSing INDEXED data as applied to a banking system • • • 259
sets • • • • • • • • • • • • • • • • 182 Figure 11.3. Flow diagram for
Figure 12.10. Effect of KEYLOC and programming example of multitasking 260
RKP values on establishing embedded Figure 18.1 (Part 1 of 2). Implicit
keys in record variables or data data conversion performed in-line • 210
sets .·············
Figure 12.11 (Part 1 of 2).
182 Figure 18.1 (Part 2 of 2). Implicit
data conversion performed in-line • 271
statements and options permitted for Figure 18.2. Conditions under which
creating and acceSSing REGIONAL data string operations are handled in-
sets .············· 186 line • • • • • • • • • • • • • • • • 212
Figure 12.11 (Part 2 of 2). Figure 18.3. Conditions under which
statements and options permitted for string functions are handled in-line 213
creating and acceSSing REGIONAL data Figure 19.1. Extent of PLiI
sets.
· · · · · · · · · · · · · . . 187 environment • • • • • • • • • • • • 29S

Figures xiii
Figure 19.2. COBOL-PL/I data built-in functions with extended-
equivalents • • • • • • • • • 298 preCision floating-point arguments • 363
Figure 19.3. Declaration of a data Figure H.1. Output for CHECK
aggregate in COBOL and PL/I • 298 condition • • • • • • • • • • • • • 395
Figure 19.4. FORTRAN-PL/I data Figure I.1. Classification of
equivalents • • • • • • • • • • 299 attributes according to data types • 406
Figure 19.5 (Part 1 of 2). Return Figure I.2. File declarations (files
codes produced by PL/I data types • 300 associated with non-VSAM data sets) 407
Figure 19.5 (Part 2 of 2). Return Figure I.3. Guide to types of
codes produced by PL/I data types • 301 defining • • • • • • • • • • •
Figure 0.1. Pictured character- Figure J.l. General formats of the
string examples • • • • • • 316 assignment statement • • . • . • 441
Figure 0.2. pictured numeric Figure J.2. General formats of the
character examples. • • • • • • 317 DEFAULT statement • • • • • • • 448
Figure 0.3. Examples of zero Figure J.3. General formats of the
suppression • • • • • • • • • • 319 DO statement • • • • • 452
Figure 0.4. Examples of insertion Figure J.4. Transfer and destination
characters • • • • • • • • • • • • • 320 statements • • • • • • • • • • 458
Figure 0.5. Examples of drifting Figure J.5. Format of option list
picture characters • • • • • • • • • 321 for READ statement • • • 470
Figure 0.6. Examples of CR, DB, T, Figure J.6. Effects of 'PAGE and
I, R, and Y picture characters • • • 323 ~SKIP ••• • • • • • • • • • 486
Figure 0.7. Examples of floating- Figure K.1 (Part 1 of 2). summary of
point picture specifications • • • . 323 alignment requirements for ALIGNED
Figure 0.8. Examples of scaling data • • • • • • • • • • • • • • • • 490
factor picture characters • • • • • 324 Figure K.l (Part 2 of 2). Summary of
Figure F.l. List of priority of alignment requirements for ALIGNED
operations and guide to conversion data • • • • • • • • • • • • • • • • 491
rules • • • • • • • • • • • • • • • 333 Figure K.2 (Part 1 of 2). Summary of
Figure F.2. Table of CEIL (n*3.32) alignment requirements for UNALIGNED
and CEIL (n/3.32) values • • • • • • 333 data • • • • • • • • • • • • • • • • 492
Figure F.3. Circumstances causing Figure K.2 (Part 2 of 2). Summary of
conversion • • • • • • • • • • • 333 alignment requirements for UNALIGNED
Figure F.4a. Master table for data • • • • • • • • • • • • • • 493
arithmetic operations • • • • • 349 Figure K.3. Mapping of minor
Figure F.4b. Key to conversions • • 349 structure G • • • • • • • • • 494
Figure F.4c. Result table for Figure K.4. Mapping of minor
ADDITION, SUBTRACTION, structure E • • • • • 495
MULTIPLICATION, and DIVISION • 349 Figure K.5. Mapping of minor
Figure F.4d. Result table for struct ure N • • • • • • • • • • 496
EXPONENTIATION • • • • • • • • • 349 Figure K.6. Mapping of minor
Figure F.5a. Master table for structure S • • • • • • • • • 497
comparison operations • • • • • 350 Figure K.7. Mapping of minor
Figure F.5b. Types of comparison struct ure C • • • • • • • • • 498
operation and targets • • • • • • • 351 Figure K.8. Mapping of minor
Figure G.l (Part 1 of 3). Performance structure M • • • • • 499
of the mathematical built-in Figure K.9. Mapping of major
functions with short and long structure A • • • • . • • . • 500
precision floating-point arguments • 358 Figure K.l0. Offsets in final
Figure G.l (part 2 of 3). Performance mapping of structure A • • • • • 501
of the mathematical built-in Figure K.11. Format of Structure S • 502
functions with short and long Figure K.12. Block created from
precision floating-point arguments . 359 structure s ............ 503
Figure G.l (part 3 of 3). Performance Figure K.13. Block created by
of the mathematical built-in structure S with correct alignment • 503
functions with short and long Figure K.14. Alignment of data in a
precision floating-point arguments • 360 buffer in locate mode input/output,
Figure G.2 (Part 1 of 3). for different formats and data set
performance of the mathematical organizations • • • • • • • • • • • 504
built-in functions with extended- Figure L.l. Differences resulting
precision floating-point arguments • 361 from differing compiler functions • 506
Figure G.2 (Part 2 of 3). Figure L.2 (Part 1 of 2). Differing
performance of the mathematical qualitative restrictions • • • • • • 507
built-in functions with extended- Figure L.2 (Part 2 of 2). Differing
precision floating-point arguments • 362 qualitative restrictions • • • • • . 508
Figure G.2 (part 3 of 3). Figure L.3. Differing quantitative
performance of the mathematical restrictions • • • • • • • • • • • • 509

xiv OS PL/I CRT AND OPT LRM PART II

Part I: Concepts of PL/I

Part I: concepts of PL/I 1

 Chapter 1: Basic Characteristics of PL/I

The modularity of PL/I, the ease with which level but the most elementary. These rules
subsets can be selected to meet different give the programmer considerable control
needs, becomes apparent when one examines over the degree of interaction between
the different features of the language. subroutines. They permit flexible
Such modularity is one of the most communication and storage allocation, at
important characteristics of PL/I. the same time allOWing the definition of
names and allocation of storage for private
This chapter contains brief discussions use within a procedure.
of most of the basic features to provide an
overall description of the language. Each By giving the programmer freedom to
is treated in more detail in subsequent determine the degree to which a subroutine
chapters. is self-contained, PLiI makes it possible
to write procedures which can freely be
used in other enVironments, while still
allowing interaction in procedures where
Machine Independence interaction is desirable.

No language can be completely machine

independent, but PL/I is much less machine Data Types and Data Description
dependent than most commonly used
programming languages. The methods used to
achieve this show in the form of The characteristic of PL/I that most
restrictions in the language. The most contributes to the range of applications
obvious example is that data with different for which it can be used is the variety of
characteristics cannot in general share the data types that can be represented and
same storage; to equate a floating-point manipulated. PL/I deals with arithmetic
number with a certain number of alphabetic data, string data (bit and character), and
characters would be to make assumptions program control data, such as labels.
about the representation of these data Arithmetic data may be represented in a
items which would not be true for all variety of ways; it can be binary or
machines. decimal, fixed-point or float.ing-point,
real or complex, and its precision may be
It is recognized that the price entailed specified.
by machine independence may sometimes be
too high. In the interest of efficiency, PL/I provides features to perform
certain features such as the UNSPEC built- arithmetic operations, comparisons, and
in function and record-oriented data operations and functions for assembling,
transmission are machine dependent. scanning, and subdividing strings.
The compiler must be able to determine,
for every name used in a program, the
Program Structure complete set of attributes associated with
that name. The programmer may specify
these attributes explicitly by means of a
A PL/I program consists of one or more DECLARE statement; the compiler may
blocks of statements called procedures. A determine all or some of the attributes by
procedure may be thought of as a context; or a partial or complete set of
subroutine. Procedures may invoke other attributes may be assumed by default. The
procedures, and these procedures or programmer can specify which attributes are
subroutines may be either compiled to be applied by default, or he can allow
separately, or nested within the calling the compiler to determine them.
procedure and compiled with it. Each
procedure may contain declarations that
define names and control allocation of
storage. Default Assumptions
The rules defining the use of
procedures, communication between An important feature of PL/I is its default
procedures. the meanings of names. and philosophy. If all the attributes
allocation of storage are fundamental to associated with a name, or all the options
the proper understanding of PL/I at any permitted in a statement. are not specified

Chapter 1: Basic Characteristics of PLII 3

by the programmer, attributes or options that the more dynamic the method of storage
will be assigned by the compiler. This allocation, the greater the execution time.
default action has two main consequences.
First, it reduces the amount of declaration
and other program writing required; second,
it makes it possible to teach and use Expressions
subsets of the language for which the
programmer need not know all possible
alternatives, or even that alternatives Calculations in PL/I are specified by
exist. expressions. An expression has a meaning
in PL/I that is similar to that of
The default attributes assumed by the elementary algebra. For example:
compiler are the standard default
attributes of the PL/I language and the A + B * C
implementation precision defaults.
However, the programmer can override these This specifies multiplication of the value
by use of the DEFAULT statement. of B by the value of C and adding the value
of A to the result. PL/I places few
The compiler optionally produces an restrictions on the kinds of data that can
attribute listing which contains the be used in an expression. For example, it
identifiers used in a PL/I source program is conceivable, though unlikely, that A
and a complete list of the attributes could be a floating-point number, B a
specified either by explicit, contextual, fixed-point number, and C a character
or implicit declarations, or by application string.
of default rules. The programmer can use
this listing to check that these attributes When such mixed expressions are
are consistent with his intentions. specified, the operands will be converted
so that the operation can be evaluated
meaningfully. Note, however, that the
rules for conversion must be considered
Storage Allocation carefully; converted data may not have the
same value as the original. And, of
course. any conversion increases execution
PL/I goes beyond most other languages in time.
the flexibility of storage allocation that
it provides. Dynamic storage allocation is The results of the evaluation of
comparatively difficult for an assembler expressions are aSSigned to variables by
language programmer to handle for himself; means of the assignment statement. An
yet it is automatically provided in PL/I. example of an assignment statement is:
There are four different storage classes:
AUTOMATIC, STATIC, CONTROLLED, and BASED. x = A + B * C;
In general, the default storage class in
PL/I is AUTOMATIC. This class of storage This means: evaluate the expression on the
is allocated whenever the block in which right and store the result in X. If the
the variables are declared is activated. attributes of X differ from the attributes
At that time the bounds of arrays and the of the result of the expression. conversion
lengths of strings are calculated. will again be performed.
AUTOMATIC storage is freed and is available
for re-use whenever control leaves the
block in which the storage is allocated.
Data Collections
storage may also be declared STATIC, in
which case it is allocated when the program
is loaded; it may be declared CONTROLLED, PL/I offers the programmer many ways of
in which case it is explicitly controlled describing and operating on collections of
by the programmer with ALLOCATE and FREE data, or data aggregates. Arrays are
statements, independent of the invocation collections of data elements, all of the
of blocks; or it may be declared BASED, same type, collected into lists or tables
which gives the programmer an even higher of one or more dimensions. Structures are
degree of control. hierarchical collections of data, not
necessarily all of the same type. Each
The existence of several storage classes level of the hierarchy may contain other
enables the programmer to determine for structures of deeper levels. An item that
himself the speed, storage space, or does not contain another structure must
programming economy that he needs for each represent an elementary data item or array.
application. The cost of a particular
facility will depend upon the An element of an array may be a
implementation, but it will usually be true structure; similarly, any level of a

4 OS PL/I CRT AND OPT LRM PART I

structure may be an array. Operations can Teleprocessing facilities are provided
be specified for arrays, structures, or by PL/I as part of the basic record-
parts of arrays or structures. For oriented transmission facilities.
example:
stream-oriented input and output usually
A = B + C: sacrifices efficiency for ease of handling.
Each data item is transmitted separately
In this assignment statement, A, B, and C and is examined to determine if data
could be arrays or structures. conversion is required. Record-oriented
input and output, on the other hand,
provides faster transmission, but generally
requires a greater programming effort.
Input and Output
Input and output operations for data
banks involving a number of interrelated
Facilities for input and output allow the data sets is simplified by the use of file
user to choose between factors such as variables. All input/output statements can
simplicity, machine independence, and use file variables with file values
efficiency. There are two broad classes of established and mOdified during execution
input/output in PL/I: stream-oriented and of the program.
record-oriented.
Stream-oriented input/output is almost
completely machine independent. On input, Multitasking
data items are selected one by one from
what is assumed to be a continuous stream
of characters that are converted to The operating system has facilities for
internal form and aSSigned to variables multiprogramming, that is, it allows a
specified in a list. Similarly, on output, number of programs to be active
data items are converted one by one to concurrently. In the same way, PL/I has
external character form and are added to a facilities to allow a number of procedures
conceptually continuous stream of within a PL/I program to be active
characters. Within the class of stream concurrently.
input/output, the programmer can choose
different levels of control over the way Any PL/I procedure may invoke another,
data items are edited and selected from or in other words initiate the execution of
added to the stream. another procedure. The programmer may
specify that the procedures are to be
For printing, the output stream may be tasks, which means that they may both be
considered to be divided into lines and active concurrently. The invoked procedure
pages. An output stream file may be is known as a subtask of the other, and is
declared to be a print file with a said to have been attached by it.
specified line size and page size. The
programmer has facilities to detect the end The advantage of multitasking is that
of a page and to specify the beginning of a CPU operations may be carried out in one
line or a page. These facilities may be task while an input/output operation (or
used in subroutines that can be developed other CPU operations, in the case of
into a report generating system suitable multiprocessing machines) is carried out
for a particular installation or concurrently in another. As soon as the
application. CPU or the input/output operations in one
task are completed, a search is made
In a system employing the Conversational amongst all the active tasks for another
Monitor system or the Time Sharing Option, one that requires the same resource. If
data may be fed into, and output may be more than one such task is found, the
obtained from, a PL/I program using a resource is assigned to the one having
terminal remote from the machine. highest priority. The PL/I programmer may
allow the system to allocate relative
Record-oriented input/output is machine priorities or he may assign priorities to
dependent. It deals with collections of his tasks when they are attached.
data, called records, and transmits these
one record at a time without any data A number of tasks may be dependent on
conversion: the external representation is each other at various pOints during their
generally an exact copy of the internal execution. For example, One task may
representation. Because the aggregate is require results obtained in another before
treated as a whole, and because no it can be completed. In PL/I, the
conversion is performed, this form of programme~ may synchronize tasks at various
input/output is more efficient than stream- points in their execution. An operation in
oriented input/output. one task may be made to await the

Chapter 1: Basic Characteristics of PL/I 5

completion of an operation in another task. Compile-Time Operations
The optimizing and checkout compilers
differ in their implementations of PL/I permits a compile-time level of
multitasking. Each task in a PLII program operation, in which preprocessor statements
compiled by the optimizing compiler forms a specify operations upon the text of the
system task to be scheduled by the source program itself. The simplest, and
operating system. The checkout compiler perhaps the commonest preprocessor
constitutes a single task, and the compiler statement is ~INCLUDE (in general,
itself schedules the tasks created within a preprocessor statements are preceded by a
PL/I program. percent symbol). This statement causes
text to be inserted into the program,
replaCing the ~INCLUDE statement itself. A
typical use could be to copy declarations
Facilities of the Two Compilers from an installation's standard set of
definitions into the program.

The optimizing and checkout compilers are Another function provided by compile-
complementary program products. The main time facilities is the selective
function of the optimizing compiler is to compilation of program text. For example,
generate highly efficient object code, i t might specify the inclusion or deletion
while that of the checkout compiler is to of debugging statements.
minimize the time a programmer needs to
spend in debugging. Since a simple but powerful part of the
PL/I language is available for compile-time
Both compilers may be used for batch activity, the generation, or replacement
processing, that is, processing in which a and deletion, of text can become more
program must be compiled, and possibly elaborate, and more subtle transformations
executed, in full before the programmer can be performed. Such transformations
obtains any result. The checkout compiler might then be considered to be
has the facility for conversational installation-defined extensions to the
processing. In this mode, the program's language.
execution is monitored from a keyboard
terminal and temporary amendments may be
made during execution as a result of
information so obtained; new PL/I code may Execution-Time Facilities
be temporarily included in the program, for
instance. The best use is made of PL/I
facilities when both compilers are PL/I includes statements and options that
employed. The program is compiled by the provide powerful facilities for debugging.
checkout compiler during the debugging Other features allow program amendment
stages, to allow the programmer to use his during execution; these require the use of
time most effiCiently; the debugged program the Conversational Monitor System or the
is then compiled by the optimizing Time Sharing option of the operating
compiler, to obtain object code that makes system, and of the checkout compiler. They
the most efficient use of the machine. allow the programmer to learn quickly about
the behaviour of his program while it is
The language implemented by the two being executed and also, in the appropriate
compilers is, in general, the same. There processing environment, to correct it.
are a few exceptions concerned with the Also, under the Conversational Monitor
different primary function of each System or the Time Sharing Option, stream
compiler. certain optimizing features are I/O can be performed from and toa
not implemented by the checkout compiler terminal, on programs compiled by either
and certain program checkout features are the checkout or the optimizing compiler.
not implemented by the optimizing compiler.
For instance, a number of statements The debugging facilities cause
instruct the checkout compiler to provide information to be written on the SYSPRINT
the programmer with information about the file (and, if desired, at the terminal when
flow of control through his program during the terminal is not defined as the SYSPRINT
execution. Since the optimizing compiler file) throughout execution or at designated
does not have these facilities, it merely pOints during execution. The programmer
checks the statements' syntax and oeherwise can, throughout execution, cause
ignores them. Similarly, there are intormation to be written every time a
statement options concerned with generating reference to a selected variable occurs in
the most efficient object code possible a pre-defined situation or when a transfer
that are used by the optimizing compiler of control takes place. Similarly, at
but which are syntax-checked and then designated paints in the program being
ignored by the checkout compiler. executed, the information to be written can

6 OS PL/I CKT AND OPT LRM PART I

include the values of selected variables, the action to be taken when an interrupt
the names of the procedures currently does occur. In Conversational processing,
active, or the numbers of the statements the programmer can deal with any error
involved in the latest transfers of condition immediately it occurs.
control.

The time at which this output is

available depends on the processing mode. Operating System Facilities
In batch processing, information written on
the SYSPRINT file is only available when
the SYSPRINT file is printed, which is A number of facilities provided by the
normally after execution has terminated. operating system can be called upon by the
In conversational processing, information PL/I programmer. The most prominent ones,
written on the SYSPRINT file can be namely interlanguage communication,
immediately printed at the terminal; sort/merge, and checkpoint/restart are
therefore the output provided by the outlined below. All relevant facilities
debugging facilities can be made available are described in the appropriate
immediately i t is produced. programmer's guide.

Program amendment during execution is It is possible for a PL/I program to

possible only with conversational communicate with COBOL and FORTRAN routines
processing under the checkout compiler. at execution time, provided that the latter
The programmer can enter instructions at were compiled by a compiler developed by
the terminal that cause program execution IBM for OS. A PL/I procedure may invoke a
to be suspended and control passed to the COBOL, FORTRAN, or assembler routine, and
terminal. He can then enter statements may be invoked by a COBOL or FORTRAN
that are executed during the current program or routine. In addition, a PLII
suspension of execution or during a further program may be used to create or access a
suspension; this future suspension will be COBOL or FORTRAN data set. All these
at a point specified by the programmer. facilities are provided by the
These statements can, for instance, implementation of the PL/I language.
initiate the debugging facilities described Further communication is possible between
above, change the value of a variable or PL/I and other languages if an assembler
insert extra statements in the program. language interface is provided. Such
Changes made to the existing program can be interfaces are fully described in the
temporary, or they can be incorporated appropriate programmer's guide.
automatically into the current source
program. The current source program can be provided the operating system has been
saved on an external data set and can be generated with the appropriate sort/merge
retranslated at any time without leaving program, the sort/merge facilities may be
the checkout compiler environment. utilized by the PL/I programmer. They may
be used on records on PL/I-created data
sets, on data passed by a PL/I program, and
On data being passed to a PL/I program.
Interrupt Activities
When a PL/I batch processing program
compiled by the optimizing compiler is to
Modern computing systems provide facilities run for an extended period, the operating
for interrupting the execution of a program system checkpoint/restart facility can be
whenever an exceptional condition arises. employed to minimize the losses caused by a
Further, they allow the program to deal machine or system failure. The programmer
with the exceptional condition and to selects checkpoints in his program at which
return to the point at which the interrupt processing is to be recommenced following a
occurred. failure. Only the processing carried out
between the checkpoint and the failure may
PL/I provides facilities for detecting a be lost. Results obtained up to the
variety of exceptional conditions. It checkpoint are preserved on auxiliary
allows the programmer to specify, by means storage, together with data (including a
of a condition prefix, that an interrupt copy of the program and its associated
will occur if the condition should arise. storage) necessary for continuation of the
By use of an ON statement, he can specify run.

Chapter 1: Basic Characteristics of PL/I 7

 Chapter 2: Program Elements

There are few restrictions in the format of Character

PL/I statements. Consequently, programs
can be written without consideration of Blank
special coding forms or checking to see Equal sign or assignment symbol
that each statement begins in a specific Plus sign +
column. As long as each statement is Minus sign
terminated by a semicolon, the format is Asterisk or multiply symbol *
completely free. Each statement may begin Slash or divide symbol /
in the next column or position after the Left parenthesis (
previous statement, or any number of blanks Right parenthesis )
may intervene. Comma
Point or period
Single quotation mark
or apostrophe
Percent symbol %
Semicolon
Colon
"Not" symbol
Character Sets "And" symbol &
·Or" symbol I
"Greater than" symbol >
One of two character sets may be used to "Less than" symbol <
write a source program; either a 60- Break character
character set or a 48-character set. For a Question mark ?
given external procedure, the choice
between the two sets is optional. In special characters are combined to
practice, this choice will depend upon the create other symbols. For example, <=
available equipment. means "less than or equal to", ~= means
"not equal to". The combination ** denotes
exponentiation (X**2 means X2). Blanks are
not permitted in such composite symbols.

The break character is the same as the

typewriter underline character. It can be
used in a name, such as GROSS PAY, to
60-CHARACTER SET improve readability. -

The 60-character set is composed of

alphabetic characters, digits, and special
characters.

There are 29 alphabetic characters 48-CHARACTER SET

beginning with the currency symbol ($), the
number sign (#), and the commercial "at"
sign Cal, which precede the 26 letters of The 48-character set is composed of 48
the English alphabet in the IBM System/360 characters of the 60-character set. In all
collating sequence Extended Binary Coded but tour cases, the characters of the
Decimal Interchange Code (EBCDIC). For use reduced set can be combined to represent
with languages other than English, other the missing characters from the larger set.
characters may be substituted for $, #, and For example, the percent symbol (I) is not
a. included in the 48-character set, but a
double slash (//) can be used to represent
There are ten digits. The decimal it. The four characters that are not
digits are the digits 0 through 9. A duplicated are the commercial "at" ~ign,
binary digit is either a 0 or a 1. the number sign, the break character, and
the question mark.
An alphameric character is either an
alphabetic character or a digit. The restrictions and changes for this
character set are described in sect-ion B,
There are 21 speCial characters. They "Character sets with EBCDIC and card-Punch
are as follows: Codes" •

Chapter 2: Program Elements 9

USING THE CHARACTER SET break characters, not contained in a
comment or constant, and preceded and
followed by a blank or some other
All the elements that make up a PL/I delimiter; the initial character of the
program are constructed from the PL/I string must be alphabetic. The length must
character sets. There are two exceptions: not exceed 31 characters.
character-string constants and comments may
contain any of the 256 characters Language keywords also are identifiers,
represented by an 8-bit code. possibly preceded by a percent symbol C%).
A keyword is an identifier that, when used
Certain characters perform specific in the proper context, has a specific
functions in a PL/I program. For example, meaning to the compiler. A keyword can
many characters function as operators. specify such things as the action to be
taken, the nature of data, the purpose of a
There are four types of operators: name. For example, READ, DECIMAL, and
arithmetic, comparison, bit-string, and ENDFILE are keywords. Some keywords can be
string. abbreviated. A complete list of keywords
and their abbreviations is contained in
The arithmetic operators are: section C, "Keywords and Keyword
Abbreviations".
+ denoting addition or prefix plus
denoting subtraction or prefix ~: PL/I keywords are not reserved
minus words. They are recognized as keywords by
* denoting multiplication the compiler only when they appear in their
/ denoting division proper context. In other contexts they may
** denoting exponentiation be used as programmer-defined identifiers.

The comparison operators are: Examples of identifiers that could be

used for names or labels:

> denoting "greater than" A

... > denoting "not greater than"
>= denoting "greater than or FILE2
equal to~
= denoting "equal to" LOOP 3
... = denoting "not equal to"
<= denoting "less than or equal to" RATE OF_PAY
< denoting "less than"
... < denoting "not less than" #32

Some identifiers, as discussed in later

The bit-string operators are: chapters, cannot exceed seven characters in
length and must not contain the break
denoting "not" character. This limitation is placed upon
& denoting "and" certain names, called external names, that
I denoting "or" may be referred to by the operating system
or by more than one separately compiled
The string operator is: procedure. If an external name of a PL/I
procedure contains more than seven
II denoting concatenation characters, it is truncated by the
compiler, which concatenates the first four
Figure 2.1 shows some of the functions characters with the last three characters.
of other special characters. The entry name of a COBOL or FORTAN routine
may have up to eight characters. If more
than eight characters are specified, the
leftmost eight are taken.
Identifiers

In a PL/I program, names or labels are Blanks

given to data, files, statements, and entry
points of different program areas. In
creating a name or label, a programmer must Blanks may be used freely throughout a PL/I
observe the syntax rules for creating an program. They may surround operators and
identifier. most other delimiters. In general, any
number of blanks may appear wherever one
An identifier is a single alphabetic blank is allowed, such as between words in
character or a string of alphameric and a statement.

10 OS PL/I CKT AND OPT LRM PART I

1r---------------------------------------------------------------------------------------,
Name Character Use
1---------------------------------------------------------------------------------------
1comma separates elements of a list: precedes
l BY NAME option.
l
1period Indicates decimal point or binary point:
connects elements of a qualified name

semicolon Terminates statements

assignment = Indicates assignment of values 1
symbol

colon Connects prefixes to statements: can be

used in specification for bounds of an
array; can be used in RANGE specification
of DEFAULT statement

blank separates elements of a statement

single quotation Encloses string constants and picture
mark specification
parentheses ( ) Enclose lists: specify information
associated with various keywords; in
I conjunction with operators and operands,
1 delimit portions of a computational
l expression
1
larrow -> Denotes locator qualification
I
l percent symbol I Indicates statements to be executed by the
I compile-time preprocessor or listing
l control statements
1---------------------------------------------------------------------------------------1
1 Note that the character = can be used as an equal sign and as an assignment symbol.
1 1
L-------------------------------------------__________ ----------------------------------J
Figure 2.1. Some functions of special characters

One or more blaDks must be used to Comments

separate identifiers and constants that are
not separated by some other delimiter or by
a comment. However, identifiers, constants Comments are permitted wherever blanks are
(except character-string constants) and allowed in a program, except within data
composite operators (for example, ~=) items, such as a character string. A
cannot contain blanks. comment is treated as a blank and can
therefore be used in place of a required
separating blank. Comments do not
otherwise affect execution of a program:
they are used only for documentation
other cases that require or permit purposes. Comments may be coded on the
blanks are noted in the text where the same line as statements, either inserted
feature of the language is discussed. Some between statements or in the Ddddle of
examples of the use of blanks are: them.
The general format of a comment is:

/* character-string
AB+BC is equivalent to AB + BC
The character pair /* indicates the
TABLE(10) is equivalent to TABLE (10) beginning of a cOlllllent. The same character
pair reversed, */, indicates its end. No
FIRST,SECOND is equivalent to FIRST, SECOND blanks or other characters can separate the
two characters of either composite pair;
ATOB is !!2!: equivalent to A TO B the slash and the asterisk must be

Chapter 2: Program Elements 11

immediately adjacent. The comment itself this semicolon. The IF statement can
may contain any characters except the */ contain two statements which may be simple
combination, which would be interpreted as or compound as shown in the following
terminating the comment. The initial /*. example:
must never be in columns 1 and 2 of a line.
IF A>B THEN A=B+C;
Example: ELSE GO TO LOOP_3;
/* THIS WHOLE SENTENCE COULD BE The follOWing is an example of the ON
INSERTED AS A COMMENT */ statement:
Any characters permitted for a ON OVERFLOW GO TO OVFIX;
particular machine configuration may be
used in comments.
statement Prefixes
Basic Program Structure
Both Simple and compound statements may
have one or more prefixes. There are two
A PL/I program is constructed from basic types of prefixes; the label prefix and the
program elements called statements. There condition prefix.
are two types of statements: simple and
compound. These statements make up larger A label prefix identifies a statement so
program elements called groups and blocks. that it can be referred to at some other
point in the program. A label prefix is an
identifier that precedes the statement and
is connected to the statement by a colon.
SIMPLE AND COMPOUND STATEMENTS lIn general, any statement may have ~ne or
more label prefixes. If more than one
label is specified, they may be used
There are three types of simple statements: interchangeably to refer to that statement.
keyword, assignment, and nUll, each of
which contains a statement body that is A condition prefix specifies whether the
terminated by a semicolon. named conditions are to be enabled.
Condition names are language keywords, each
A keYWord statement has a keyword to of which represents an exceptional
indicate the function of the statement; the condition that might arise during execution
statement body is the remainder of the of a program. Examples are OVERFLOW and
statement. SIZE. The OVERFLOW condition arises when
the exponent of a floating-point number
The assignment statement contains the exceeds the maximum allowed (representing a
assignment symbol (=) and does not have a maximum value of about 10 75 ). The SIZE
keyword. condition arises when a value is assigned
to a variable with loss of high-order
The null statement consists only of a digits or bits.
semicolon and indicates no operation; the
semicolon is the statement body. When the programmer does not expect the
condition to arise, he may disable it by
Examples of simple statements are: preceding the condition name in a prefix by
the word NO. If NO is used, there can be
GO TO LOOP_3; (keyword statement) no intervening blank between the NO and the
GO TO is a keyword; the condition name.
blank between GO and TO
is optional. The A condition prefix consists of a list of
statement body is one or more condition names, separated by
LOOP_3: cODlllas and enclos ed in parentheses. one or
more condition prefixes may be attached to
A = B + C; (aSSignment statement) a statement, and each parenthesized list
must be followed by a colon. Condition
A c0l!l?Ound statement is a statement that prefixes precede the entire statement,
contains one or more other statements as a including any possible labe1 prefixes for
part of its statement body. Th~e are two the statement. For example:
compound statements: the IF statement and
the .ON statement. The final statement of a (SIZE, NooVERPLOW) : COMPUTE: A=B*C**D;
compound statement is a Simple statement
that is terminated by a semicolon. Hence, The single condition prefix indicates that
the compound statement is terminated by an interrupt 1s to occur 1f the SIZE

12 OS PL/I CRT AND OPT LRM PART I

condition arises during execution of the Icorresponding END statement. A select-
assignment statement, but that no interrupt Igroup is a sequence of selection clauses
is to occur if the OVERFLOW condition Idelimited by a SELECT statement and a
arises. Note that the condition prefix Icorresponding END statement. Both types of
precedes the label prefix COMPUTE. Igroup are used for control purposes.

Since intervening blanks between a

prefix and its associated statement are A block is a sequence of statements that
ignored, it is often convenient, when using defines-an area of a program. It is used
card input, to punch the condition prefix to delimit the scope of a name and for
into a separate card that precedes the card control purposes. A program consists of
into which the statement is punched. Thus, one or more blocks. Every statement must
after debugging, the prefix can be easily appear within a block. There are two kinds
removed. For example: of blocks: begin blocks and procedure
blocks. A begin block is delimited by a
(NOCONVERSION): BEGIN statement and an END statement. A
(SIZE,NOOVERFLOW): procedure block is delimited by a PROCEDURE
COMPUTE: A*B*C**Oi statement and an END statement. Every
begin block must be contained within SOme
Note that there are two condition prefixes. p~ocedure block.
The first specifies that no interrupt is to
occur if an invalid character is Execution passes sequentially into and
encountered during an attempted data out of a begin block. However, a procedure
conversion. block, except the first, must be invoked by
execution of a statement in another block.
Condition prefixes are discussed in The first procedure in a program to be
chapter 14, -Exceptional Condition Handling executed is invoked automatically by the
and Program Checkout-. operating system. This first procedure
must be identified by specifying
OPTIONS(MAIN) in the PROCEDURE statement.

GROUPS AND BLOCKS A procedure block may be invoked as a

task, in which case it is executed
concurrently with the invoking procedure.
IA do-group is a sequence of statements Tasks are discussed in chapter 17,
Idelimited by a DO statement and a -Multitasking-.

Chapter 2: Program Elements 13

 Chapter 3: Data Elements

Data is generally defined as a GET LIST (B) ;

representation of information or of value. LOOP: A=2*B;
C=B+6 ;
In P~/I, reference to a data item,
arithmetic or string, is made by using The characteristics of a variable or a
either a variable or a constant (the terms symbolic constant are not immediately
are not exactly the same as in general apparent in the name. Since these
mathematical usage). characteristics, called attributes, must be
known, certain keywords and expressions may
A variable is a symbolic name having a be used to specify the attributes in a
value that may change during execution of a DECLARE statement. The attributes used to
program. describe each data type are discussed
briefly in this chapter. A complete
A constant (which can be a symbolic discussion of each attribute appears in
name) has a value that cannot change. section I, -Attributes-.

The following statement contains both In preparing a PL/I program, the

variables and constants: programmer must be familiar with the types
of data that are permitted, the ways in
AREA = RADIUS**2*3.1416; which data can be organized, and the
methods by which data can be referred to.
AREA and RADIUS are variables; the numbers The following paragraphs discuss these
2 and 3.1416 are constants. The value of features.
RADIUS is a data item, and the result of
the computation will be a data item that
will be assigned as the value of AREA. The
number 3.1416 in the statement is itself Data Types
the data item.

If the number 3.1416 is to be used in The types of data that may be used in a
more than one place in the program, it may PL/I program fall into two categories:
be convenient to represent it as a variable problem data and program control data.
to which the value 3.1416 has been Problem data is used to represent values to
assigned. Thus, t~e above statement could be processed by a program. It consists of
be written as: two data types, arithmetic and string.
Program control data is used by the
PI = 3.1416; programmer to control the execution of his
AREA = RADIUS**2*PI; program. Program control data consists of
the following seven types: label, event,
In the last statement, only the number 2 is file, entry, locator, task, and area.
a constant.

A constant does more than state a value;

it demonstrates various characteristics of Problem Data
the data item. For example, 3.1416 shows
that the data type is arithmetic and that
the data item is a decimal number of five The types of problem data are arithmetic
digits and that four of these digits are to and string.
the right of the decimal pOint.

A constant represented by a symbOlic

name has a value which is determdned by the ARITHMETIC DATA
compiler, and which the programmer does not
need to know. Such constants are normally
associated with the control of the program; An item of. arithmetic data is One with a
they represent addresses in main storage numeric value. Arithmetic data items have
rather than computational values. For the characteristics of base, scale,
instance the identifier -LOOP- in the precision, and mode. The characteristics
following example is a symbolic name which of data items represented by an arithmetic
represents a constant, namely the address variable are specified by attributes
of the machine code generated by the declared for the name, or assumed by
statement A=2*B as follows: default.

Chapter 3: Data Elements 15

 The base of an arithmetic data item is complex arithmetic variables must be
either decimal or binary. explicitly declared with the COMPLEX
attribute. Real arithmetic variables may
be explicitly declared to have the REAL
The scale of an arithmetic data item is attribute, but it is not generally
either fixed-point or floating-point. A necessary to do so, since an arithmetic
fixed-point data item is a number in which variable is generally assumed to be real
the position of the decimal or binary point unless it is explicitly declared complex.
is specified, either by its appearance in a
constant or by a scale factor declared for
a variable. A floating-point data item is
a number followed by an optionally signed
exponent. The exponent specifies the
assumed position of the decimal or binary
point, relative to the position in which it
appears.
Decimal Fixed-Point Data
The precision of an arithmetic data item
is the number of digits the data item may
contain, in the case of fixed-point, or the A decimal fixed-point constant consists of
minimum number of significant digits one or more decimal digits with an optional
(excluding the exponent) to be maintained, decimal pOint. If no decimal point
in the case of floating-point. For fixed- appears, the point is assumed to be
point data items, precision can also immediately to the right of the rightmost
specify the assumed position of the decimal digit. A sign may optionally precede a
or binary point, relative to the rightmost decimal fixed-point constant.
digit of the number.
Examples of decimal fixed-point
Whenever a data item is assigned to a constants as written in a program are:
fixed-point variable, the declared
precision is maintained. The assigned item 3.1416
is aligned on the decimal or binary pOint.
Leading zeros are inserted if the assigned 455.3
item contains fewer integer digits than
declared; trailing zeros are inserted if it 132
contains fewer fractional digits. A SIZE
error may occur if the assigned item 003
contains too many integer digits;
truncation on the right may occur, without -5280
rounding, if i t contains too many
fractional digits. .0012

The mode of an arithmetic data item is For expression evaluation, decimal

either real or complex. A real data item fixed-point constants have an apparent
is a number that expresses a real value. A precision (p,q), where p is the total
complex data item is a pair of numbers: number of digits in the-constant and q is
the first is real and the second is the number of digits specified to the righ~
imaginary. For a variable representing of the decimal point. For example:
complex data items, the base, scale, and
precision of the two parts must be 3.14 has the precision (3,2)
identical.
The keyword attributes for declaring
Base, scale, and mode of arithmetic decimal fixed-point variables are DECIMAL
variables are specified by keywords; and FIXED. Precision is stated by two
precision is specified by parenthesized decimal integers, separated by a comma and
decimal integer constants. The precision enclosed in parentheses. The first, which
of arithmetic variables and constants is must be unsigned, specifies the total
discussed in greater detail below. number of digits; the second, the scale
factor, may be signed and specifies the
In the following sections, the real number of digits to the right of the
arithmetic data types discussed are decimal decimal pOint. If the variable is to
fixed-point, binary fixed-point, deeimal represent integers, the scale factor and
floating-point, and binary floating-pOint. its preceding comma can be omitted. The
Any of these can be used as the real part attributes may appear in any order, but the
of a complex data item. The imaginary part precision specification must follow either
of a complex number is discussed in the DECIMAL or FIXED (or REAL or COMPLEX).
section "Complex Arithmetic Data," in this Following are examples of declarations of
chapter. decimal fixed-point variables:

16 OS PL/I CRT AND OPT LRM PART I

 DECLARE A FIXED DECIMAL (5,4); sign may optionally precede the constant.
DECLARE B FIXED (6,0) DECIMAL; Examples of binary fixed-point constants
as written in a program are:
DECLARE C FIXED (1,-2) DECIMAL;
10110B
DECLARE D DECIMAL FIXED REAL(3,2);
11111B
The first DECLARE statement specifies
that the identifier A is to represent 101B
decimal fixed-point items of not more than
five digits, four of which are to be -111.01B
treated as fractional, that is, to the
right of the assumed decimal point. Any 1011.111B
item assigned to A will be converted to
decimal fixed-point and aligned on the For expression evaluation, binary fixed-
decimal point. point constants have an apparent preciSion
(p,q), where p is the total number of
The second DECLARE statement specifies binary digits in the constant, and q is the
that B is to represent integers of no more number of binary digits specified to the
than 6 digits. Note that the comma and the right of the binary point. For example:
zero are unnecessary; i t could have been
specified B FIXED DECIMAL(6). 0000001B has the precision (7,0)

The third DECLARE statement specifies a The keyword attributes for declaring
negative scale factor of -2; this means binary fixed-point variables are BINARY and
that the assumed decimal pOint is two FIXED. Precision is specified by two
places to the right of the rightmost digit decimal integer constants, enclosed in
of the item. parentheses, to represent the maximum
number of binary digits and the number of
The fourth DECLARE statement specifies digits to the right of the binary pOint,
that D is to represent fixed-point items of respectively. If the variable is to
no more than three digits, two of which are represent integers, the second digit and
fractional. the comma can be omitted. The attributes
can appear in any order, but the precision
The maximum number of decimal digits specification must follOW either BINARY or
allowed is 15. Default preciSion, assumed FIXED (or REAL or COMPLEX).
when no specification is made, is (5,0).
The internal coded arithmetic form of Following is an example of declaration
decimal fixed-point data is packed decimal. of a binary fixed-point variable:
packed decimal is stored two digits to the
byte, with a sign indication in the DECLARE FACTOR BINARY FIXED (20,2);
rightmost four bits of the rightmost byte.
Consequently, a decimal fixed-point data FACTOR is declared to be a variable that
item is always stored as an odd number of can represent arithmetic data items as
digits, even though the declaration of the large as 20 binary digits, two of which are
variable may specify the number of digits fractional. The decimal eqUivalent of that
(p) as an even number. value range is from -262,144.00 through
+262,143.15.
When the declaration specifies an even
number of digits, the extra digit place is The maximum number of binary digits
in the high-order position, and i t allowed is 31. Default precision is
participates in any operations performed (15,0). The internal coded arithmetic form
upon the data item, such as in a comparison of binary fixed-point data can be either a
operation. Any arithmetic overflow or fixed-point binary halfword or fullword. A
assignment into an extra high-order digit halfword is 15 bits plus a sign bit, and a
place can be detected only if the SIZE fullword is 31 bits plus a sign bit. Any
condition is enabled. binary fixed-point data item with a
precision of (15,0) or less is stored as a
halfword, and with a precision greater than
(15,0), up to the maximum precision, is
Binary Fixed-Point Data stored as a full word. The declared number
of digits are considered to be in tht low-
order pOSitions, but the extra high-order
A binary fixed-point constant consists of digits participate in any operations
one or more binary digits with an optional performed upon the data item. Any
binary point, followed immediately by the arithmetic overflow into such extra high-
letter B, with no intervening blank. A order digit positions can be detected only

Chapter 3: Data Elements 17

if the SIZE condition is enabled. Following is an example of the
declaration of a decimal floating-point
When the standard default rules are in variable:
force, an identifier for which no
declaration is made is assumed to be a DECLARE LIGHT_YEARS DECIMAL FLOAT(5);
binary fixed-point variable, with default
precision, if its first letter is any of This statement specifies that LIGHT_YEARS
the letters I through N. is to represent decimal floating-paint data
items with an accuracy of at least five
significant digits.

The maximum preciSion allowed for

decimal floating-point data items is (33):
the default precision is (6). The exponent
cannot exceed two digits. A value range of
Decimal Floating-point Data approximately 10- 78 to 10 75 can be
expressed by a decimal floating-point data
item. The internal coded arithmetic form
A decimal floating-point constant is of decimal floating-point data is
written as a field of decimal digits normalized hexadecimal floating-point, with
followed by the letter E, followed by an the point assumed to the left of the first
optionally signed decimal integer exponent. hexadecimal digit. If the declared
The first field of digits may contain a precision is less than or equal to (6),
decimal point. The entire constant may be short floating-point form is used; if the
preceded by a plus or minus sign. Examples declared preCision is greater than (6) and
of decimal floating-paint constants as less than or equal to (16), long floating-
written in a program are: point form is used; if the declared
precision is greater than (16), extended
15E-23 floating-point form is used.

15E23 An identifier for which no declaration

is made is assumed to be a decimal
4E-3 floating-point variable if its first letter
is any of the letters A through H. 0
-48333E65 through Z, or one of the alphabetic
extenders, $, #, m, when the standard
438EO default rules are applied.

3141593E-6

.003141593E3 Binary Floating-Point Data

The last two examples represent the same

value. A binary floating-point constant consists
of a field of binary digits followed by the
For expression evaluation, decimal letter E, followed by an optionally signed
floating-point constants have an apparent decimal integer exponent followed by the
precision (p) where p is the number of letter B. The exponent is a decimal
digits of the constant to the left of the E integer and specifies a power of two. The
(the mantissa). For example: field of binary digits may contain a binary
pOint. The entire constant may be preceded
0.012E5 has the precision (4) by a plus or minus sign. Examples of
binary floating-point constants as written
The keyword attributes for declaring in a program are:
decimal floating-point variables are
DECIMAL and FLOAT. Precision is stated by 101101ESB
a decimal integer constant enclosed in
parentheses. It specifies the minimum 101.101E2B
number of significant digits to be
maintained. If an item assigned to a 11101E-28B
variable has a field width larger than the
declared precision of the variable, -10.01E99B
truncation may occur on the right. The
least significant digit is the first that For expression evaluation, binary
is lost. Attributes may appear in any floating-point constants have an apparent
order, but the precision specification must precision (p) where p is the number of
follow either DECIMAL or FLOAT (or REAL or binary digits to the left of the E (the
COMPLEX) • mantissa). For example:

18 OS PL/I CKT AND OPr LRM PART I

 O.0101E33B has the precision (5) [+1-] real constant {+I-}
imaginary-constant
The keyword attributes for declaring
binary floating-point variables are BINARY Thus a complex value could be written as
and FLOAT. Precision is expressed as a 38+271.
decimal integer constant, enclosed in
parentheses, to specify the minimum number The keyword attribute for declaring a
of significant digits to be maintained. complex variable is COMPLEX. A complex
The attributes can appear in any order, but variable can have any of the attributes
the precision specification must follow valid for the different types of real
either BINARY or FLOAT (or REAL or arithmetic data. Each of the base, scale,
COMPLEX). Following is an example of and precision attributes applies to both
declaration of a binary floating-poi~t fields.
variable:
Unless a variable is explicitly declared
DECLARE S BINARY FLOAT (16): to have the COMPLEX attribute, it is
assumed to represent real data items.
This specifies that the identifier S is to
represent binary floating-point data items
with 16 digits in the binary field.

The maximum precision allowed for binary Numeric Character Data

floating-point data items is (109); the
default precision is (21). The exponent
cannot exceed three decimal digits. A A numeric character data item (also known
value range of approximately 2_ 260 to 2 252 as a numeric field data item) is the value
can be expressed by a binary floating-point ot a variable that has been declared with
data item. The internal coded arithmetic the PICTURE attribute and a numeric picture
form of binary floating-point data is specification. The data item is the
normalized hexadecimal floating-point. If character representation of a decimal
the declared precision is less than or fixed-point or floating-point value.
equal to (21), short floating-point form is
used; if the declared precision is greater A numeric picture specification
than (21) and less than or equal to (53), describes a character string to which only
long floating-point form is used: if the data that has, or can be converted ~o, an
declared precision is greater than (53), arithmetic value is to be assigned. A
extended floating-point form is used. numeric picture specification canno~
contain either of the picture characters A
or X, which are used for non-numeric
picture-character strings. The basic form
Complex Arithmetic Data of a numeric picture specification is one
or more occurrences of the digit-specifying
picture character 9 and an optional
In the complex mode, an arithmetic data occurrence of the picture character V, to
item is considered to consist of two parts, indicate the assumed location of a decimal
the first a real part and the second a pOint. The picture spepification must be
signed imaginary part. There are no enclosed in Single quotation marks. For
complex constants in PL/I. A complex value example:
is obtained by a real constant and an
imaginary constant. '999V99'

An imaginary constant is written as a This numeric picture specification

real constant of any type immediately describes a data item conSisting of up to
followed h¥ the letter I. five decimal digits in character form, with
a decimal pOint assumed to precede the
Examples of imaginary constants as rightmost two digits.
written in a program are:
Repetition factors may be used in
271 numeric picture specifications. A
repetition factor is an unsigned decimal
3. 968E10I integer constant, enclosed in parentheses.
INo blanks are allowed within the
11011.01BI parentheses. The repetition factor
indicates the number of repetitions of the
Each of these is considered to have a real immediately following picture character.
part of zero. A complex value with a non- For example, the following picture
zero real part is represented in the specification would result in the same
following form: description as the example shown above:

Chapter 3: Data Elements 19

 '(3)9V(2)9' Consider the following example:
DECLARE PRICE PICTURE '$99V.99',
The format for declaring a numeric COST CHARACTER (6),
character variable is: VALUE FIXED DECIMAL (6,2);
PRICE = 12.28;
COST = '$12.28';
DECLARE identifier PICTURE
'numeric-picture-specification'i
In the picture specification for PRICE, the
currency symbol ($) and the decimal pOint
For example: C.) are editing characters. They are
stored as characters in the data item.
DECLARE PRICE PICTURE '999V99'; They are not, however, a part of its
arithmetic value. After execution of the
This specifies that any value assigned to second aSSignment statement, the actual
PRICE is to be maintained as a character internal character representation of PRICE
string of five decimal digits, with an and COST can be considered identical. If
assumed decimal pOint preceding the they were printed, they would print exactly
rightmost two digits. Data assigned to the same. They do not, however, always
PRICE will be aligned on the assumed point function the same. For example:
in the same way that pOint alignment is
maintained for fixed-point decimal data. VALUE PRICE;
The numeric picture specification COST = PRICE;
specifies arithmetic attributes of data in
much the same way that they are specified VALUE = COST;
by the appearance of a constant. Only
decimal data can be represented by picture PRICE = COST:
characters. Complex data can be declared
by specifying the COMPLEX attribute along After the first two aSSignment
with a single picture specification that statements are executed, the value of VALUE
describes either a fixed-point or a would be 0012.28 and the value of COST
floating-point data item. would be '$12.28'. In the assignment of
PRICE to VALUE, the currency symbol and the
The maximum number of decimal digits decimal point are considered to be editing
allowed in a numeric character item is 15. characters, and they are not part of the
aSSignment: the arithmetic value of PRICE
It is important to note that, although is converted to internal coded arithmetic
numeric character data has arithmetic form. In the assignment of PRICE to COST,
attributes, it is not stored in coded however, the assignment is to a character
arithmetic form. Numeric character data is string, and the editing characters of a
stored in zoned decimal format: before it numeric picture specification always
can be used in arithmetic computations, it participate in such an assignment. No
must be converted either to packed decimal conversion is necessary because PRICE is
or to hexadecimal floating-point format. stored in character form.
Such conversions are done automatically,
but they require extra execution time. The third and fourth assignment
statements would cause errors. The value
Although numeric character data is in of COST cannot be assigned to VALUE because
character form, like character strings, and the currency symbol in the string makes it
although it is aligned on the decimal pOint invalid as an arithmetic constant. The
like coded arithmetic data, it is processed value of COST cannot be assigned to PRICE
differently from the way either coded for exactly the same reason. Only values
arithmetic items or character strings are that are of arithmetic type, or that can be
processed. Editing characters can be converted to arithmetic type, can be
specified for insertion into a numeric aSSigned to a variable declared with a
character data item, and such characters numeric picture specification.
are actually stored within the data item.
consequently, when the item is printed or Note: A1 though the decimal point can be an
treated as a character string, the editing edItIng character or an actual character in
characters are included in the assignment. a character string, it will not cause an
If, however, a numeric character item is error in converting to arithmetic form,
assigned to another numeric character or since its appearance is valid in an
arithmetic variable, the editing characters arithmetic constant. The same would be
will not be included in the assignment: true of a valid plus or minus Sign, since
only the actual digits and the location of arithmetic constants can be preceded by
the assumed decimal pOint are assigned. Signs •

20 os PL/I CRT AND OPT LRM PART I

 other editing characters, including zero SHAKESPEARE'S' 'HAMLET" with a length of
suppression characters, drifting 24. In the last example, the parenthesized
characters, and insertion characters, can number is a repetition factor, which
be used in numeric picture specifications. indicates repetition of the characters that
For complete discussions of picture follow. This example specifies the
characters, see section D, "Picture constant 'WALLA WALLA ' (the blank is
Specification Characters" and the included as one of the characters to be
discussion of the PICTURE attribute in repeated). The repetition factor must be
section I, -Attributes". an unSigned decimal integer constant,
enclosed in parentheses. It has a maximum
permissible value of 32761.
STRING DATA A null character-string constant is
written as two quotation marks with no
intervening blank.
A string is a contiguous sequence of
characters (or binary digits) that is The keyword attribute for declaring a
treated as a single data item. The length character-string variable is CHARACTER.
of the string is the number of characters Length may be declared by an expression or
(or binary digits) it contains. a decimal integer constant, enclosed in
parentheses, which specifies the number of
There are two types of strings: characters in the string. The length
character strings and bit strings. specification must follow the keyword
CHARACTER. For example:
DECLARE NAME CHARACTER (15);
Character-String Data
This DECLARE statement specifies that the
identifier NAME is to represent character-
A character string can include any digit, string data items, 15 characters in length.
letter, or special character re~ognized as If a character string shorter than 15
a character by the particular machine characters were to be assigned to NAME, it
configuration. Any blank included in a would be left adjusted and padded on the
character string is an integral character right with blanks to a length of 15. If a
and is included in the count of length. A longer string were assigned, it would be
comment that is inserted within a character truncated on the right. (Note: If such
string will not be recognized as a comment. truncation occurs it can be detected by use
The comment, as well as the comment of the STRINGSIZE condition).
delimiters (/* and */), will be considered
to be part of the character-string data. When no length is specified, the
standard default assumption is a length of
Character-string constants, when written one.
in a program, must be enclosed in single
quotation marks. If a single quotation Character-string variables may also be
mark is a character in a string, it must be declared to have the VARYING attribute, as
written as two single quotation marks with follows:
no intervening blank. The length of a
character string is the number of DECLARE NAME CHARACTER (15) VARYING;
characters between the enclosing quotation
marks. If two single quotation marks are This DECLARE statement specifies that the
used within the string to represent a identifier NAME is to be used to represent
single quotation mark, they are counted as varying-length character-string data items
a single character. with a maximum length of 15. The actual
length attribute for NAME at any particular
Examples of character-string constants time is the length of the data item
are: assigned to it at that time. The
programmer need not keep track of the
'LOGARITHM TABLE' length of a varying-length character
string; this is done automatically. The
'PAGE 5' length at any given time can be determined
by the programmer, however, by use of the
, SHAKESPEARE' 'S " " HAMLET' , , , , LENGTH built-in function, as discussed in
chapter 13, "Editing and string Handling".
'AC438-19'
Character-string data is maintained
(2) '·WALLA ' internally in character format, that is,
each character occupies one byte of
The third example actually indicates storage. The maximum length allowed for

Chapter 3: Data Elements 21

variables declared with the CHARACTER Bit-string Data
attribute is 32,767. The maximum length
allowed for a character-string constant
before application of repetition factors A bit-string constant is written in a
varies according to the amount of storage program as a series of binary dig~ts (bits)
available to the compiler, but it will enclosed in single quotation marks and
never be less than 512. The minimum length followed immediately by the letter B.
for a character string is zero. The
storage allocated for varying-length A null bit-string constant is written as
strings is two bytes longer than the two quotation marks with nO intervening
declared maximum length. The initial two blank, followed immediately by the letter
bytes hold the string's current length, in B.
bytes.
Examples of bit-string constants as
Character-string variables also can be written in a program are:
declared using the PICTURE attribute of the
form: 'l'B
PICTURE 'character-picture-specification' '11111010110001'B

The character picture specification is a (64)'0'B

string composed of the picture
specification characters A, X, and 9. The • 'B
string of picture characters must be
enclosed in single quotation marks, and it The parenthesized number in the third
must contain at least one A or X and no example is a repetition factor which
other picture characters except 9. The specifies that the following series of
character A specifies that the digit~ is to be repeated the specified
corresponding po~ition in the described number of times. The example shown would
field will contain an alphabetic character result in a string of 64 binary zeros.
or blank. The character X specifies that
any character may appear in the A bit-string variable is declared with
corresponding position in the field. The the BIT keyword attribute. Length may be
picture character 9 specifies that the declared by an expression or a decimal
corresponding position will contain a integer constant, enclosed in parentheses,
numeric character or blank. For example: to specify the number of binary digits in
the string. The letter B is not included
DECLARE PART_NO PICTURE 'AA9999X999'; in the length specification since it is not
part of the string. The length
This DECLARE statement specifies that the specification must follow the keyword BIT.
identifier PART_NO will represent Following is an example of declaration of a
character-string data items consisting of bit-string variable:
two alphabetic characters, four numeric
characters, one character that may be any DECLARE SYMPTOMS BIT (64);
character, and three numeric characters.
Like character strings, bit strings are
Repetition factors are used in picture assigned to variables from left to right.
specifications differently from the way If a string is longer than the length
they are used in string constants. declared for the variable, the rightmost
Repetition factors must be placed inside digits are truncated; if shorter, padding,
the quotation marks. The repetition factor on the right, is with zeros.
specifies repetition of the immediately
following picture character. For example, If no length is specified, a length of
the above picture specification could be one is assumed.
written:
A bit-string variable may be given the
, (2)A(4) 9X(3) 9' VARYING attribute to indicate it is to be
used to represent varying-length bit
The maximum length allowed for a picture strings. Its application is the same as
specification is the same as that allowed that described for character-string
for character-string constants, as variables in the preceding section.
discussed above.
Bit strings are stored eight bits to a
Note that, for character picture byte. The maximum length allowed for a
specifications, the picture character 9 bit-string variable is 32,767. The maximum
specifies a digit or a blank, while, for length allowed for a bit-string constant
numeric picture specifications, the same before application of repetition factors
character specifies only a digit. depends upon the amount of storage

22 OS PL/I eXT AND OPr LRM PART I

available to the compiler, but it will label, entry, event, task, locator, and
never be less than 4096 (512 bytes). The area.
minimum length for a bit string is zero.
The storage allocated for varying-length
strings is two bytes longer than that
required by the declared maximum length. FILE DATA
The initial two bytes hold the current
length of the string, in bits.
A file data item repres~nts information
about a PL/I file. It may be a file
constant, or the value of a file variable.
UNINITIALIZED VARIABLES A file constant can be assigned to a file
variable: a reference to the file variable
is a reference to the assigned file
When the programmer makes a reference to an constant.
arithmetic or string variable such that the
variable should contain a valid value -
assigns the value to another variable for
instance - errors can occur if this is the LABEL DATA
first reference to the variable. The
programmer must ensure that a variable has
been assigned a value before trying to A label data item is a label constant or
access it. The checkout compiler checks the value of a label variable.
whether this has been done.
A label constant is an identifier
To facilitate this checking, the written as a prefix to a statement so that,
compiler assigns a special value to each during execution, program control can be
variable as soon as storage is allocated to transferred to that statement through a
it~ An attempt to use a variable having reference to its label. A colon connects
this value will result in interruption of the label to the statement.
execution. The special value is one which
the variable would not normally have. For ABCDE: MILES = SPEED*HOURS;
instance, with a varying-length character
string, the compiler assigns the variable a In this example, ABCDE is the statement
length of -1. Certain of these special label. The statement can be executed
values, however, might occasionally be used either by normal sequential execution of
by the programmer. These are as follows. instructions or by transferring control to
this statement from some other point in the
Fixed length character strings: program by means of a GO TO statement.

X'FE' in each byte As used above, ABCDE can be classified

turther as a statement-label constant. A
PiG:ture data: statement-label variable is an identifier
that refers to statement-label constants.
X'FE' in each byte Consider the following example:

Fixed-point binary data: statement;

half word X'8001', i.e. -2 15 +1(-32161)

fullword X'80000001', i.e. -2 31 +1 statement;

(-2,141,483,647)

If it is essential that one of the above

values is used in a program to be run under
the checkout compiler, the compiler options
should specify that no checking for
unin1tialized variables is to be carried
out. The optimizing compiler does not
check for uninitialized variables during
I execution.

LBL A and LBL B are statement-label

Program Control Data constants because they are prefixed to
statements. LBL X is a statement-label
variable. By assigning LBL_A to LBL_X, the
The types of program control data are file, statement GO TO LBL_X causes a transfer to

Chapter 3: Data Elements 23

the LBL A statement. Elsewhere, the EV is declared an entry variable by means
program-may contain a statement assigning of the VARIABLE attribute. The first CALL
LBL_B to LBL_X. Then, any reference to statement invokes an entry point
LBL X would be the same as a reference to represented by the entry constant E1. The
LBL-B. This value of LBL X is retained second CALL invokes the entry point E2.
untIl another value is assigned to it.

A statement-label variable must be

d~clared with the LABEL attribute, as EVENT DATA
follows:

DECLARE LBL_X LABEL; Event variables are used to coordinate the

concurrent execution of a number of
procedures, or to allow a degree of overlap
between a record-oriented input/output
ENTRY DATA operation (or the execution of a DISPLAY
statement) and the execution of other
statem6nts in the procedure that initiated
Entry data is used only in connection with the operation.
entry names, and has values which permit
references to be made to entry points of A variable is given the EVENT attribute
procedures. Entry data may be an entry by its appearance in an EVENT option or a
constant or the value of an entry variable. WAIT statement, or by explicit declaration,
as in the following example:
An entry constant is an identifier that
appears in the program as an entry name DECLARE ENDEVT EVENT;
written as a prefix to a PROCEDURE or ENTRY
statement. It permits references to be For detailed information, see chapter
made to an entry point of a procedure. 11, -Multitasking," chapter 12, "Record-
Oriented Transmission", or "DISPLAY" in
Example: section J, -statements".

P: PROCEDURE;
CALL Pl;
TASK DATA

CALL P1A; Task variables are used to control the

relative priorities of different tasks
(i.e., concurrent separate executions of a
procedure or procedures).
Pl: PROCEDURE;
A variable is given the TASK attribute
by its appearance in a TASK option, or by
explicit declaration, as in the following
P1A:ENTRY; example:

P1 and P1A are declared as entry constants. DECLARE ADTASK TASK;

Control is transferred to the procedure
entry points designated by Pl or P1A when a For detailed information, see chapter
reference is made to either entry constant. 11, "Multitasking."

An entry variable is an identifier that

refers to an entry constant. Consider the
following example: LOCATOR DATA

DECLARE EV ENTRY VARIABLE,

(E1,E2) ENTRY; There are two types of locator data:
pOinter and offset.

The value ot a pointer variable is

EV = El; effectively an address of a location in
CALL EVi storage, and so it can be used to qualify a
EV = E2; reference to a variable that may have been
CALL EVi allocated storage in several different
locations.

The value of an oftset variable

24 OS PL/I CKT AND OPT LRM PART I

specifies a location relative to the start structures. A variable that represents a
of. a reserved area of storage and remains single element is an element variable (also
valid when the address of the area itsel~ called a scalar variable). A variable that
changes. represents a collection of data elements is
either an array variable or a structure
Locator variables can be declared as in variable.
the following example:
Any type of problem data or program
DECLARE HEADPTR POINTER, control data can be collected into arrays
FIRST OFFSET (AREAl): or structures.

In this example, AREA1 is the name of the

reserved area of storage that will contain
the location specified by FIRST. ARRAYS

A variable can also be given the POINTER

attribute by its appearanc.e in the BASED Data elements having the same
attribute, by its appearance on the left- characteristics, that is, of the same data
hand side of a locator qualification type and of the same precision or length,
symbol, or by its appearance in a SET may be grouped together to form an array.
option. An array is an n-dimensional collection of
elements, all of which have identical
For detailed information, see chapter 8, attributes. Only the array itself is given
ftStorage Control ft • a name. An individual item of an array is
referred to by giving its relative position
within the array.

AREA DATA

Consider the following two declarations:

Area variables are used to describe areas
of storage that are to be reserved for the DECLARE LIST (8) FIXED DECIMAL (3):
allocation of based variables. An area can
be assigned or transmitted complete with DECLARE TABLE (4,2) FIXED DECIMAL (3);
its contained allocations; thus, a set of
based allocations can be treated as one In the first example, LIST is declared to
unit for assignment and input/output while be a one-dimensional array of eight
each allocation retains its individual elements, each of which is a fixed-point
identity. decimal item of three digits. In the
second example, TABLE is declared to be a
A variable is given the AREA attribute two-dimensional array, also of eight fixed-
either by its appearance in the OFFSET pOint decimal elements.
attribute or an IN option, or by explicit
declaration, as in the following example: The parenthesized number or numbers
following the array name in a DECLARE
DECLARE AREAl AREA(2000), statement is the dimension attribute
AREA2 AREA; specification. It must follow the array
name, with or without an intervening blank.
The number of bytes of storage to be It specifies the number of dimensions of
reserved can be stated explicitly, as it the array and the bounds, or extent, of
has been for AREAl in the example: each dimension. Since only one bounds
otherwise a default size is assumed. The specification appears for LIST, i t is a
default size is 1000 bytes; the theoretical one-dimensional array. Two bounds
maximum size is 16,777,200 bytes but in specifications, separated by a comma, are
practice the maximum depends on the amount listed for TABLE: consequently, it is
of storage available to the program. declared to be a two-dimensional array.

For detailed information, see chapter 8, The bounds of a dimension are the
·Storage Control-. beginning and the end of that dimension.
The extent is the number of integers
between, and including, the lower and upper
bounds. If only one integer appears in the
Data Organization bounds specification tor a dimension, the
lower bound is assumed to be 1. The one
dimension of LIST has bounds of 1 and 8;
In PL/I, data items may be single data its extent is 8. The two dimensions of
elements, or they may be grouped together TABLE have bounds of 1 and 4 and 1 and 2;
to form data collections called arrays and the extents are 4 and 2.

Chapter 3: Data Elements 25

 If the lower bound of a dimension is not in an array. Subscripts are used in other
1, both the upper bound and the lower bound references to identify specific elements
must be stated explicitly, with the two within the array.
numbers connected with a colon. For
example: The same data could be assigned to
LIST A and LIST B, as declared above
DECLARE LIST_A (4:11): (though not by direct assignment from
LIST). In this case it would be would be
DECLARE LIST_B (-4:3); referred to as follows:

In the first example, the bounds are 4 and

11: in the second they are -4 and 3. Note Reference Element Reference
that the extents are the same: in each
case, there are 8 integers from the lower LIST_A (4) 20 LIST_B (-4)
bound through the upper bound. It is
important to note the difference between LIST_A (5) 5 LIST_B (-3)
the bounds and the extent of an array. In
the manipulation of array data (discussed LIST_A (6) 10 LIST_B (-2)
in chapter 4, "Expressions and Data
Conversions·) involving more than one LIST_A (7), 30 LIST_B (-1)
array, the bounds -- not merely the extents
-- must be identical. Although LIST, LIST_A (8) 630 LIST_B (0)
LIST A, and LIST B all have the same
extent, the bounds are not identical. LIST_A (9) 150 LIST B (1)

The bounds of an array determine the way LIST_A (10) 310 LIST_B (2)
elements of the array can be referred to.
For example, assume that the following data LIST_A (11) 70 LIST_B (3)
items are assigned to the array LIST, as
declared above: Assume that the same data were assigned
to TABLE, which is declared as a two-
20 5 10 30 630 150 310 70 dimensional array (though note again that
assignment could not be direct from LIST to
The different elements would be referred TABLE). TABLE can be illustrated as a
to as follows: matrix of four rows and two columns, as
follows:
Reference Element
LIST (1) 20
TABLE(m,n)
LIST (2) 5
(l,n) 20 5
LIST (3) 10
(2,n) 10 30
LIST (4) 30
(3,n) 630 150
LIST (5) 630
(4,n) 310 70
LIST (6) 150
An element of TABLE is referred to by a
LIST (7) 310 subscripted name with two parenthesized
subscripts, separated by a comma. For
LIST (8) 70 example, TABLE (2,1) would specify the
first item in the second row, in this case,
Each of the numbers following the name the data item 10.
LIST is a subscript. A parenthesized
subscript following an array name, with or Note: The use of a matrix to illustrate
without an intervening blank, identifies a TABLE is purely conceptual. It has no
particular data item within the array. A relationship to the way in which the items
subscripted name, such as LIST(4), refers are actually organized in storage. Data
to a single element and is an element items are aSSigned to an array in row major
variable. The entire array can be referred order, that is, with the right-most
to by the unsubscripted name of the array, subscript varying most rapidly. For
for example, LIST. In this case, LIST is example, aSSignment to TABLE would be to
an array variable. Note the difference TABLE(l,l), TABLE(1,2), TABLE(2,1),
between a subscript and the dimension TABLE(2~2) and so forth.
attribute specification. The latter, which
appears in a declaration, specifies the Arrays are not limited to two
dimensionality and the number of elements dimensions; up to 15 dimensions can be

26 OS PL/I CRT AND OPr LRM PART I

declared for an array. In a reference to for example, a record variable (that is, a
an element of any array, a subscripted name variable to or from which data is
must contain as many subscripts as there transmitted by a record-oriented
are dimensions in the array. transmission statement) must represent data
in connected storage (that is, data items
Examples of arrays in this chapter have which are adjacent in storage).
shown arrays of arithmetic data. All data
types may be collected into arrays. String
arrays, either character or bit, are valid,
as are arrays of label, entry, event, file, STRUCTURES
area, task, or locator data.

Data items that need not have identical

characteristics, but that possess a logical
Expressions as Subscripts relationship to on~ another, can be grouped
into aggregates called structures.

The subscripts of a subscripted name need Like an array, the entire structure is
not be constants. Any expression that given a name that can be used to refer to
yields a valid arithmetic value can be the entire collection of data. Unlike an
used. If the evaluation of such an array, however, each element of a structure
expression yields a value that is not a also has a name.
fixed-point binary integer, it is converted
to FIXED BINARY(15,O), since subscripts are A structure is a hierarchical collection
maintained internally as binary integers. of names. At the bottom of the hierarchy
is a collection of elements, each ot which
Subscripts are frequently expressed as represents a single data item or an array.
variables or other expressions. Thus, At the top of the hierarchy is the
TABLE(I,J*K) could be used to refer to the structure name, which represents the entire
different elements of TABLE by varying the collection of element variables. For
values of I, J, and K. example, the following is a collection of
element variables that might be used to
compute a weekly payroll:

Cross-Sections of Arrays LAST NAME

FIRST NAME
REGULAR HOURS
Cross-sections of arrays can be referred to OVERTIME HOURS
by substituting an asterisk for a subscript REGULAR RATE
in a subscripted name. The asterisk then OVERTIME_RATE
specifies that the entire extent is to be
used. For example, TABLE(*,l) refers to These variables could be collected into
all of the elements in the first column of a structure and given a single structure
TABLE. It specifies the cross-section name, PAYROLL, which would refer to the
consisting of TABLE(l,l), TABLE(2,1), entire collection.
TABLE(3,1), and TABLE(4,1). The
subscripted name TABLEC2,*) refers to all
of the data items in the second row of PAYROLL
TABLE. TABLE(.,.) refers to the entire
array.

Note that a subscripted name containing

asterisk subscripts represents, not a
single data element, but an array with as Any reference to PAYROLL would be a
many dimensions as there are asterisks. reference to all of the element variables.
consequently, such a name is not an element For example:
expression, but an array expression.
GET DATA (PAYROLL);
A reference to a cross-section of an
array may be a reference to two or more This input statement could cause data to
elements of that array which may not be be assigned to each of the element
adjacent in storage, the elements specified variables of the structure PAYROLL.
by such a reference being separated by
other elements which are not part of the It often is convenient to SUbdivide the
cross-section. The storage represented by entire collection into smaller logical
such a cross-section is known as non- collections. In the above examples,
connected storage. Certain restrictions LAST_NAME and FIRST_NAME might make a
apply to the use of non-connected storage; logical subcollection, as might

Chapter 3: Data Elements 21

REGULAR HOURS and OVERTIME HOURS, as well Note that in the declaration, each level
as REGULAR RATE and OVERTIME RATE. In a number precedes its associated name and is
structure,-such subcollections also are separated from the name by a blank. The
given names. numbers chosen for successively deeper
levels need not be the immediately
PAYROLL succeeding integers. They are used merely
to specify the relative level of a name. A
NAME HOURS RATE minor structure at level n contains all the
names with level numbers greater than n
FIRST REGULAR REGULAR that lie between tha~ minor structure name
LAST OVERTIME OVERTIME and the next name with a level number less
than or equal to n. PAYROLL might have
Note that the hierarchy of names can be been declared as follows:
considered to have different levels. At
the first level is the structure name DECLARE 1 PAYROLL,
(called a major structure name): at a 4 NAME,
deeper level are the names of substructures 5 LAST,
(called minor structure names): and at the 5 FIRST,
deepest are the element names (called 2 HOURS,
elementary names). An elementary name in a 6 REGULAR,
structure can represent an array, in which 5 OVERTIME,
case it is not an element variable, but an 2 RATE,
array variable. 3 REGULAR,
3 OVERTIME:
The organization of a structure is
specified in a DECLARE statement through This declaration would result in exactly
the use of level numbers. A major the same structuring as the previous
structure name must be declared with the declaration. The maximum permissible
level number 1. Minor structures and number of levels is 15, and the highest
elementary names must be declared with permissible level number is 255.
level numbers arithmetically greater than
1; they must be decimal integer constants. The description of a major structure
A blank must separate the level number and name is terminated by the declaration of
its associated name. For example, the another item with a level number 1, by the
items of a weekly payroll could be declared declaration of another item with no level
as follows: number, or by a semicolon terminating the
DECLARE statement.
DECLARE 1 PAYROLL,
2 NAME, Level numbers are specified with
3 LAST, structure names only in DECLARE statements
3 FIRST, and, in the case of controlled structures,
2 HOURS, ALLOCATE statements. In references to the
3 REGULAR, structure or its elements, no level numbers
3 OVERTIME, are used.
2 RATE,
3 REGULAR,
3 OVERTIME:
Quali.fied Names
Note: In an actual declaration of the
structure PAYROLL, attributes would be
specified for each of the elementary names A minor structure or a structure element
LAST and FIRST, and the two pairs REGULAR can be referred to by the minor structure
and OVERTIME. The pattern of indentation name or the elementary name alone if there
in this example is used only for is no ambiguity. Note, however, that each
readability. The statement could be of the names REGULAR and OVERTIME appears
written in a continuous string as DECLARE 1 twice in the structure declaration for
PAYROLL, 2 NAME, 3 LAST, etc. PAYROLL. A reference to either name would
be ambiguous without some qualifi.cation to
PAYROLL is declared as a major structure make the name unique.
containing the minor structures NAME,
HOURS, and RATE. Each minor structure PL/I allows the use of qualified names
contains two elementary names. A to avoid this ambiguity. A qualified name
programmer can refer to the entire is an elementary name or a minor structure
structure by the name PAYROLL, or he can name that is made unique by qualifying it
refer to portions of the structure by with one or more names at a hi.gher level.
referring to the minor structure names. He In the PAYROLL example, REGULAR and
can refer to an element by referring to an OVERTIME could be made unique through use
elementary name. of the qualified names HOORS.REGULAR,

28 OS PL/I CRT AND OPr LRM PART I

HOURS. OVERTIME, RATE. REGULAR, and to the high temperature in March, is a
RATE. OVERTIME. subscripted qualified name.
The different names of a qualified name The need for subscripted qualified names
are connected by periods. Blanks may becomes more apparent when an array of
appear surrounding the period. structures contains minor structures that
Qualification is in the order of levels; are arrays. For example, consider the
that is, the name at the highest level must following array of structures:
appear first, with the name at the deepest
level appearing last. DECIARE 1 A (6,6),
2 B (5),
Any of the names in a structure, except 3 C,
the major structure name itself, need not 3 D,
be unique within the procedure in which it 2 E;
is declared. For example, the qualified
name PAYROLL. HOURS. REGULAR might be Both A and B are arrays of structures. To
required to make the reference unique identify a data item, it may be necessary
(another structure, say WORK, might also to use as many as three names and three
have the name REGULAR in a minor structure subscripts. For example, A(1,1).B(2).C
HOURS; it could be made unique with the identifies a particular C that is an
name WORK.BOURS.REGULAR). All of the element of B in a structure in A.
qualifying names need not be used, although
they may be, if desired. Qualification So long as the order of subscripts
need go only so far as necessary to make remains unchanged, subscripts in such
the name unique. Intermediate qualifying references may be moved to the right or
names can be omitted. The name left and attached to names at a lower or
PAYROLL.LAST is a valid reference to the higher level. For example, A.B.C(1,1,2)
name PAYROLL. NAME. LAST. and A(1,1,2).B.C have the same meaning as
A(l,1).B(2).C for the above array of
structures. Unless all of the subscripts
are moved to the lowest or highest level,
ARRAYS OF STRUCTURES the qualified name is said to have
interleaved subscripts; thus, A.B(1,1,2).C
has interleaved subscripts.
A structure name, either major or minor,
can be given a dimension attribute in a An array declared within an array of
DECLARE statement to declare an array of structures inherits dimensions declared in
structures. An array of structures is an the containing structure. For example, in
array whose elements are structures having the above declaration for the array of
identical names, levels, and elements. For structures A, the array B is a three-
example, if a structure, WEATHER, were used dimensional structure, because it inherits
to process meteorological information for the two dimensions declared for A. If B is
each month of a year, it might be declared unique and requires no qualification, any
as follows: reference to a particular B would require
three subscripts, two to identify the
specific A and one to identify the specific
DECLARE 1 WEATBER(12), B within that A.
2 TEMPERATURE,
3 HIGH DECIMAL FIXED(4,1),
3 LOW DECIMAL FIXED(3,1),
2 WIND VELOCITY, Cross-Sections of Arrays of Structures
3 HIGH DECIMAL FIXED(3),
3 LOW DECIMAL FlXED(2),
2 PRECIPITATION, A reference to a cross-section of an array
3 TOTAL DECIMAL FIXED(3,1), of structures is not permitted, that is,
3 AVERAGE DECIMAL FlXED(3,1); the asterisk notation cannot be used in a
reference.
Thus, when such an array represents the
weather for a whole year, a programmer
could refer to the weather data for the
month of July by specifying WEATHER(1). Other Attributes
Portions of the July weather could be
referred to by TEMPERATURE(1),
WIND VELOCITY(7), and PRECIPITATION(1), but Keyword attributes for data variables such
TOTAL(1) would refer to the total as BINARY and DECIMAL are discussed briefly
precipitation during the month of July. in the preceding sections of this chapter.
Other attributes that are not peculiar to
TEMPERATURE.HIGH(3), which would refer one data type may also be applicable. A

Chapter 3: Data Elements 29

complete discussion of these attributes is arrays creates the possibility that array
contained in section I, "Attributes". Some expressions can refer to array elements in
that are especially applicable to a non-connected storage (that is , array
discussion of data type and data elements which are not adjacent in
organization are DEFINED, LIKE, ALIGNED, storage). It is possible for an array
UNALIGNEB, and INITIAL. expression involving consecutive elements
to refer to non-connected storage in the
two following cases:

DEFINED Attribute 1. Where an array is declared with iSUB

defining. An array expression which
refers to adjacent elements in an
The DEFINED attribute specifies that the array declared with iSUB defining can
named data element, structure, or array is be a reference to non-connected
to occupy the same storage area as that storage (that is, a reference to
assigned to other data. For example, elements of an overlayed array which
are not adjacent in storage).
DECLARE LIST (100,100),
LIST_ITEM (100,100) DEFINED LIST r 2. Where a string array is defined on a
string array which has elements of
LIST is a 100 by 100 two-dimensional array. greater length. Consecutive elements
LIST ITEM is an identical array defined on in the defined array are separated by
LIST~ A reference to an element in the difference between the lengths of
LIST ITEM is the same as a reference to the the elements of the base and defined
corresponding element in LIST. arrays, and are considered to be held
in non-connected storage.
'The DEFINED attribute with the POSITION
attribute can be used to subdivide or
overlay a data item. For example:
LIKE Attribute

DECLARE LIST CHARACTER (50),

LISTA CHARACTER(10) DEFINED LIST, The LIKE attribute is used to indicate that
LISTB CHARACTER(10) DEFINED LIST the name being declared is to be given the
POSITION(11) , same structuring as the major structure or
LISTC CHARACTER(30) DEFINED LIST minor structure name following the
POSITION (21) ; attribute LIKE. For example:

LISTA refers to the first ten characters of DECLARE 1 BUDGET,

LIST. LISTB refers to the second ten 2 RENT,
characters of LIST. LISTC refers to the 2 FOOD,
last thirty characters of LIST. 3 MEAT,
3 EGGS,
The DEFINED attribute may also be used 3 BUTTER,
to specify parts of an array through use of 2 TRANSPORTATION,
iSUB variables, in order to constitute a 3 WORK,
new array. The iSUB variables are dummy 3 OTHER,
variables where i can be specified as any 2 ENTERTAINMENT,
decimal integer constant from 1 through n 1 COST_OF_LIVING LIKE BUDGET:
(where n represents the number of
dimensions for the defined item). The
value of the iSUB variable ranges from the This declaration for COST OF LIVING is the
lower bound to the upper bound of the ith same as if it had been declared:
dimension of the defined array. For
example: DECLARE 1 COST OF LIVING,
2 RENT,-
DECLARE A(20,20), 2 FOOD,
B(lO) DEFINED A(2*lSUB,2*lSUB)r 3 MEAT,
3 EGGS,
3 BUTTER,
B is a subset of A consisting of every even 2 TRANSPORTATION,
element in the diagonal of the array, A. 3 WORK,
In other words, B(l) corresponds to A(2,2), 3 OTHER,
B(2) corresponds to A(4,4). 2 ENTERTAINMENT r

Non-connected storage: The use of the Note: The LIKE attribute copies
DEFINED attribute to overlay arrays with StrUCturing, names, and attributes of the

30 OS PL/I CKT AND OPT LRM PART I

r---------------------------------------------------------------------------------------,
Address of Byte

50000 150001 150002 150003 150004 150005 150006 150007 150008

I I I I I I I I
byte I byte I byte I byte I byte 1byte 1byte 1byte I byte
I I I I I 1 I I
---------------------------------------------------------------------------------------
I I 1 I
halfword Ihalfword Ihalfword Ihalfword Ihalfword
I 1 1 1
1 I
I word I word I word
I I I
1---------------------------------------------------------------------------------------
I I double
I doubleword I word
I I
L---------------------------------------------------------------------------------------J
Figure 3.1. Section of main storage showing alignment of fixed length fields

structure below the level of the specified storage on an integral boundary for that
name only. No dimensionality of the unit of intormation. A boundary is called
specified name is copied. For example, if integral for a unit of information when its
BUDGET were declared as 1 BUDGET(12), the address is a multiple of the length of ~he
declaration of COST OF LIVING LIKE BUDGET unit in bytes. For example, a word (four
would not give the dimension attribute to bytes) must be located in storage so that
COST_OF_LIVING. To achieve dimensionality its address is a multiple of the number 4.
of COST OF LIVING, the declaration would A halfword (two bytes) must have an address
have to-be-DECLARE 1 COST_OF_LIVING(12) that is a multiple of the number 2, and· a
LIKE BUDGET. doubleword (eight bytes) must have an
address that is a multiple of the number 8
A minor structure name can be declared (see figure 3.1).
LIKE a major structure or LIKE another
minor structure. A major structure name
can be declared LIKE a minor structure or Halfwords, words, and doublewords may be
LIKE another major structure. accessed more readily than a field of the
same length that is not aligned on an
integral boundary. For this reason, it is
a system requirement that data to be used
ALIGNED and UNALIGNED Attributes in certain operations is aligned on one of
the three integral boundaries.

In System/360 and System/370, information It is possible in PL/I to align data on

is held in units of eight bits, or a boundaries that will give the fastest
multiple of eight bits. Each eight-bit possible execution. This is not always
unit of information is called a~. When desirable, however, since there may be
PL/I data is stored in character form, each unused bytes between successive data
character occupies one byte. elements, which increases use of storage.
This is likely to be particularly important
Bytes may be handled separately or when the data items are members of
grouped together in fields. A halfword is aggregates that are to be used to create a
a group of two consecutive bytes. A word data set: the unused bytes can greatly
is a group of four consec~tive bytes. A increase the amount of external storage
double word is a field consisting of two required. The ALIGNED and UNALIGNED
words. Byte locations in storage are attributes allow the programmer to choose
consecutively numbered starting with 0: whether or not data is to be stored on the
each number is considered the address of appropriate integral boundary.
the corresponding byte. A group of bytes
in storage is addressed by the leftmost ALIGNED specifies that the data element
byte of the group. is to be aligned on the storage boundary
corresponding to its data type requirement.
Fixed-length fields, such as halfwords These requirements are specified in section
and double words, must be located in main K, -Data Mapping-.

Chapter 3: Data Elements 31

 UNALIGNED specifies that each data it. When PI is allocated, it will be
element, with one exception, is mapped on initialized to the value 3.1416. Either
the next byte boundary. The exception is value may be retained throughout the
for fixed-length bit strings, which are program, or it may be changed during
mapped on the next bit. execution.

When the UNALIGNED attribute is The third example illustrates the CALL
specified, the compiler generates code that option. It indicates that the procedure
moves the data to an appropriate integral SUBR is to be invoked to perform the
boundary before an operation is performed, initialization. The required values are
if the operation requires data alignment. assigned to TABLE during the execution of
Consequently, although the UNALIGNED SUER.
attribute may reduce storage requirements,
it may increase execution time. The fourth example shows an INITIAL
attribute which contains an expression. It
Defaults are applied at element level. specifies that A is to be initialized with
The default for bit-string data, character- the value of the product of Band C.
string data, and numeric character data is
UNALIGNED: for all other types of data, the The fifth example illustrates the use of
default is ALIGNED. a fUnction reference to initialize a data
item.
ALIGNED or UNALIGNED can be specified
for element, array, or structure variables. For a variable that is allocated when
The application of either attribute to a the program is loaded, that is, a static
structure is equivalent to applying the variable, which remains allocated
attribute to all contained elements that throughout execution of the program, any
are not explicitly declared ALIGNED or value specified in an INITIAL attribute is
UNALIGNED. assigned only once. For automatic
variables, which are allocated at each
The following example illustrates the activation of the declaring block, any
effect of ALIGNED and UNALIGNED specified initial value is assigned with
declarations for a structure and its each allocation. For based and controlled
elements: variables, which are allocated at the
execution of ALLOCATE statements (also
DECLARE 1 S, LOCATE statements for based variables), any
2 X BIT(2), /*UNALIGNED BY DEFAULT*/ specified initial value is assigned with
2 A ALIGNED, /*ALIGNED EXPLICITLY */ each allocation. Note, however, that this
3 B, /*ALIGNED FROM A */ initialization of controlled variables can
3 C UNALIGNED, /*UNALIGNED EXPLICITLY*/ be overridden in the ALLOCATE statement.
4 D, /*UNALIGNED FROM C */
4 E ALIGNED, /*ALIGNED EXPLICITLY */ The INITIAL attribute cannot be given
4 F, /*UNALIGNED FROM C */ for entry constants, file constants,
3 G, /*ALIGNED FROM A */ DEFINED data, entire structures, or
2 H; /*ALIGNED BY DEFAULT */ parameters (except CONTROLLED parameters).

Note: The CALL option or an expression

containing one or more variables cannot be
INITIAL Attribute used with the INITIAL attribute for static
data.

The INITIAL attribute specifies an initial An area variable is automatically

value to be assigned to a variable at the initialized with the value of the EMPTY
time storage is allocated for it. For built-in function, on allocation, after
example: which any specified INITIAL is applied. An
area can be initialized by assignment ·of
DECLARE NAME CHAR(10) INIT('JOHN DOE'): another area, using the INITIAL attribute
with or without the CALL option.
DECLARE PI FIXED DEC(S,4) INIT(3.1416);
The INITIAL attribute can be specified
DECLARE TABLE(100,100) INIT CALL SUBR; for arrays, as well as for element
variables. In a structure declaration,
DECLARE A INIT«B*C»; only elementary names can be given the
INITIAL attribute.
DECLARE X INIT(SQRT(Z»:
An array or an array of structures can
When storage is allocated for NAME, the be partly initialized or fully initialized.
character string 'JOHN DOE' (padded on the Uninitialized elements are specified by
right to 10 characters) will be assigned to either omitting to put a value in the

32 OS PL/I CKT AND OPT LRM PART I

INITIAL attribute or by using an asterisk. In this example, only J(l).H and J(l).I are
Far example: initialized in the array of structures.

DECLARE A(15) CHARACTER (13) INITIAL

('JOHN DOE', *, For STATIC arrays, iteration factors
'RICHARD ROW', must be decimal integer constants: for
'MARY SMITH'), arrays of other storage classes, iteration
B (10,10) DECIMAL FIXED(5) factors may be constants, variables, or
INITIAL«25)0,(25)1,(50)0), expressions.
1 C(8),
2 D INITIAL (0), The iteration factor should not be
2 E INITIAL«8)0); confused with the string repetition factor
discussed earlier in this chapter.
In this example, only the first, third, Consider the following example:
and fourth elements of A are initialized:
the rest of the array is uninitialized. DECLARE TABLE (50) CHARACTER (10)
The array B is fully init~alized, with the INITIAL «10)'A',(25)(10)'B',
first 25 elements initialized to 0, the (24)(1)'C'):
next 25 to 1, and the last 50 to O. The
parenthesized numbers (25, 25, and 50) are This INITIAL attribute specification
iteration factors, that specity the number contains both iteration factors and
of elements to be initialized. In the repetition factors. It specifies that the
structure C, where the dimension (8) has first element of TABLE is to be initialized
been inherited by D, only the first element with a string consisting of 10 A's, each of
of D is initialized; where the dimension the next 2~ elements is to be initialized
(8) has been inherited by E, all the with a string conSisting of 10 B's, and
elements of E are initialized. each of the last 24 elements is to be
initialized with the single character C.
When an array of structures is declared In the INITIAL attribute specification for
with the LIKE attribute to obtain the same a string array, a single parenthesized
structuring as a structure whose elements factor preceding a string constant is
have been initialized, it should be noted assumed to be a string repetition factor
that only the first structure in this array (as in (10)'A'). If more than one appears,
of structures will be initialized. For the first is assumed to be an iteration
example: factor, and the second a string repetition
factor. For this reason (as in
DECLARE 1 G, (24)(1)'C'), a string repetition factor of
2 H INITIAL(O), 1 must be inserted if a single string
2 I INITIAL(O), constant is to be used to initialize more
1 J(8) LIKE G; than one element.

Chapter 3: Data Elements 33

 Chapter 4: Expressions and Data Con version

An expression is a representation of a Examples of element expressions are:

value. A single constant or a variable is
an expression. combinations of constants C * D
and/or variables, along with operators
and/or parentheses, are expressions. An A(3,2) + B(4,8)
expression that contains operators is an
operational expression. The constants and RATE. PRIMARY - COST. PRIMARY(1)
variables of an operational expression are
called operands. A(4,4) * C

RATE. SECONDARY / 4
Examples of expressions are:
A(4,6) * COST.SECONDARY(2)

27 All of these expressions are element

expressions because each operand is an
element variable or constant (even though
LOSS some may be elements of arrays or
elementary names of structures); hence,
A+B each expression represents an element
value.
(SQTY-QTY)*SPRICE
Examples of array expressions are:
Any expression can be classified as an
element expression (also called a scalar A + B
expression), an array expression, or a
structure expression. Element variables,
array variables, and structure variables
can appear in the same expression. B / lOB

An element expression is one that RATE + COST

represents an element value. This
definition includes an elementary name All of these expressions are array
within a structure or a subscripted name expressions because at least one operand of
that specifies a single element of an each is an array variable; hence, each
array. expression represents an array value. Note
that the third example contains the binary
An array expression is one that fixed-point constant lOB. The last example
represents an array of values. This represents an array of structures.
definition includes a structure, or part of
a structure (a minor structure or element) Examples of structure expressions are:
that is given the dimension attribute.
RATE * COST(2)
A structure expression is one that
represents a structured set of values. RATE / 2
None of its operands are arrays, but an
operand can be subscripted. Both of these expressions are structure
expressions because at least one operand of
In the examples that follow, assume that each is a structure variable and no operand
the variables have attributes declared as is an array; hence, each expression
follows: represents a structure value.

DeL A(10,10) BIN FIXED(31),

B(10,10) BIN FIXED(31),
1 RATE, Use of Ex pressions
2 PRIMARY DEC FIXED(4,2),
2 SECONDARY DEC FIXEO(4,2),
1 COST(2), Expressions that are Single constants or
2 PRIMARY DEC FIXED(4,2), Single variables may appear freely
2 SECONDARY DEC FIXEO(4,2), throughout a program. However, the syntax
C BIN FIXED(15), of many PL/I statements allows the
D BIN FIXED(15); appearance of operational expressions,

Chapter 4: Expressions and Data Conversion 35

provided the result of the expression use of more than one representation in an
conforms with the syntax rules. expression. It must be realized, however,
that such mixtures imply conversions. If
In syntactic descriptions used in this conversions take place at execution time,
publication, the unqualified term they will slow down execution. A1so,
-expression" refers to an element unless care is taken, conversion can result
expression, an array expression, or a in loss of precision and can produce
structure expression. For cases in which unexpected results. Mixed-representation
the kind of expression is restricted, the expressions should, therefore, be avoided
type of restriction is noted; for example, as far as poSSible, and when they are used
the term "element-expression" in a the relevant conversion rules should be
syntactic description indicates that thoroughly understood by the programmer.
neither an array expression nor a structure
expression is valid.
~ Although operational expressions can ASSIGNMENT
appear in a number of different PL/I
statements, their most common occurrences
are in assignment statements of the form: In addition to conversion performed in the
evaluation of an expression, conversion
A = B + C; will also occur when a data item (or the
result of an expression evaluation) is
The assignment statement has no PL/I aSSigned to a variable whose attributes
keyword. The assignment symbol (=) differ from the attributes of the item
indicates that the value of the expression assigned. The rules for such conversions
on the right (B + C) is to be aSSigned to are, with a few exceptions, the same as
the variable on the left (A). For purposes those for conversion in the eva1uation of
of illustration in this chapter, some operational expressions.
examples of expressions are shown in
assignment statements. Conversion also takes place during
stream-oriented input/output (see chapter
11), and there are a number of other
circumstances that cause conversion; a
Data Conversion complete list is given in SectionF.

OPERATIONAL EXPRESSIONS
PROBLEM DATA CONVERSION
An operational expression consists of one
or more single operations. A sing1e Two classes of conversion can be performed
operation is either a prefix operation (an on problem data: type conversion and
operator preceding a single operand) or an arithmetic conversion.
infix operation (an operator between two
operands). The two operands of any infix Type conversions are those that take
operation, when the operation is performed, p1ace between the different types of
usually must be of the same data type. problem data, namely:
The operands of an operation in a PL/I character-string - data with the CHARACTER
expression are automatically converted, if attribute
necessary, to a common representation
before the operation is performed. General bit-string - data with the BIT
principles concerning these conversions are attribute
given in -Attributes of Targets" later in
this chapter. Detailed rules for specific numeric character- data with a PICTURE
cases, including rules for computing the attribute that contains
precision or length of a converted item, neither of the picture
can be found in section F, "Data Conversion characters A and X.
and Expression Evaluation."
coded arithmetic - data with FIXED or
Data conversion is mainly confined to FLOAT, DECIMAL or BINARY,
problem data. The only conversion possible REAL or COMPLEX, and
with program control data is between offset precision attributes.
and pointer types (except that conversion
to character strings takes place under the (Strictly, numeric character data is merely
checkout compiler during stream output). a particular case of arithmetic data, but
for the purpose of presenting the
There are very few restrictions on the conversion rules, it is regarded as a

36 OS PL/I CKT AND OPr LRM PART I

separate type of representation.) of a built-in function is explained in
chapter 9, "Subroutines and Functions," and
Arithmetic conversions are those that detailed descriptions of the functions are
occur within the coded arithmetic form - given in section G, "Built-in Functions and
conversions between fixed-point and pseudovariables.") ,
floating-point scales, decimal and binary
bases, and real and complex modes, and The functions are:
conversions of precision.
CHAR
example of type conversion is a bit
An BIT
string being converted to coded arithmetic FIXED
representation during the evaluation of an FLOAT
arithmetic expression. The bit string is DECIMAL
interpreted as an unsigned binary integer, BINARY
as if it had the attributes FIXED
BINARY(31,O) REAL, with a value equal to Each function converts data to the
the positive binary value represented by attribute implied by its name. It will
the bit pattern in the string. If the perform any type and arithmetic conversions
current length of the string is greater that may be required. In addition to these
than 31, excess bits on the left-hand end functions, there are the COMPLEX built-in
of the string are ignored. function, which converts two real arguments
to a single complex value, and the function
An example of arithmetic conversion is REAL, which extracts the real part of a
an item being converted from fixed-point complex value.
decimal representation to floating-point
binary representation, both in real mode, In the case of BIT and CHAR built-in
during the evaluation of an arithmetic functions, the programmer may specify the
expression. The item retains the same length attribute of the resultant string,
value but the base on which it is and in the case of FIXED, FLOAT, DECIMAL,
represented is changed from decimal to and BINARY, he may specify the precision of
binary and its scale is changed from fixed- the result.
point to floating-point. Also, the value
of the precision attribute is increased by The precision of a data item may be
a factor of 3.32, because 3.32 times as controlled by means of the PRECISION built-
many binary integers are required to in function.
represent a given value as decimal
integers. The precision is rounded up to Conversion between pOinter and offset
an integer after being multiplied by 3.32. types may be initiated by the programmer
using the OFFSET and POINTER built-in
functions.
LOCATOR DATA CONVERSION Most of the conversions performed by
these built-in functions could equally
readily be achieved by assignment to a PL/I
The only type of program control data that variable baving the required attributes
may be converted during evaluation of (with the exception of the conversions
expressions, and execution of assignment performed by the COMPLEX built-in
statements, is locator data, that is, data fUnction). The programmer may, however,
with the OFFSET or POINTER attributes. find the use of a built-in function more
During the evaluation of an expression convenient than the creation of a variable
(locator data may be included in comparison solely for the purpose of carrying out a
operations using th~ = and ~= comparison conversion.
operators), only offset to pOinter
conversion may occur. During an
assignment, conversion from offset to
pointer and from pointer to offset may
occur.
Expression Operations
USE OF BUILT-IN FUNCTIONS
An operational expression can specify one
or more single operations. The class of
As well as allowing conversions to take operation is dependent upon the class of
place during expression evaluation and on operator specified for the operation.
assignment, the programmer may initiate There are four classes of operations -
conversions when he requires them by means arithmetic, bit-string, comparison, and
of PL/I built-in functions. (The concept concatenation.

Chapter 'h Expressions and Data Conversion 37

ARITHMETIC OPERATIONS chapter.

An intermediate result may undergo

An arithmetic operation is one that is conversion if a further operation is to be
specified by combining operands with one of performed, and the value of an expression
the following operators: may be converted if it is assigned. These
conversions follow exactly the same rules
+ * / ** as the conversion of programmer-defined
data.
The plus sign and the minus sign can appear
either as prefix operators (associated with
and preceding a single operand, such as +A
or -A) or as infix operators (associated Operations using Built-in Functions
with and between two operands, such as A+B
or A-B). All other arithmetic operators
can appear only as infix operators. There are three built-in functions in PLII
that allow the programmer to override the
An expression of greater complexity can implementation preciSion rules for
be composed of a set of such arithmetic addition, subtraction, multiplication, and
operations. Note that prefix operators can division operations. (The concept of a
precede and be associated with any of the built-in function is explained in chapter
operands of an infix operation. For 9, "SUbroutines and Functions," and the
example, in the expression A*-B, the minus functions are described in detail in
sign preceding the variable B indicates section G, "Built-in functions and
that the value of A is to be multiplied by Pseudovariables.")
-1 times the value of B.
The functions are ADD, MULTIPLY, and
More thah one prefix operator can DIVIDE. ADD may be used for subtraction
precede and be associated with a single simply by prefixing the operand to be
variable. More than one positive prefix subtracted with a minus sign. In using
operator will have no cumulative effect, these functions, two operands are
but two consecutive negative prefix specified, together with the precision of
operators will have the same effect as a the result. The base, scale, and mode of
single positive prefix operator. the result are as defined by the rules for
conversion in the evaluation of
expressions.

Results of Arithmetic Operations

After any necessary conversion of the BIT-STRING OPERATIONS

operands in an expression has been carried
out, the arithmetic operation is performed
and a result is obtained. This result may A bit-string operation is one that is
be the value of the expression or it may be specified by combining operands with one of
an intermediate result upon which turther the following operators:
operations are to be performed.
&
Consider the expression
The first operator, the "not" symbol, can
A * B + C be used as a prefix operator only. The
second and third operators, the "and"
The operation A * B is performed first, to symbol and the "or" symbol, can be used as
give an intermediate result. Then the infix operators only. (The operators have
value of the expression is obtained by the same function as in Boolean algebra.)
performing the operation (intermediate
result) + C. Operands of a bit-string operation are,
if necessary, converted to bit strings
The intermediate result is held in a before the operation is performed. If the
temporary location deSignated by the operands of an infix operation are of
compiler. It has attributes in the same unequal current length, the shorter is
way as any variable in a PL/I program. extended on the right with zeros.
What attributes the result has depends on
the attributes of the two operands (or the The result of a bit-string operation is
single operand in the case of a prefix a bit string equal in length to the current
operation) and on the operator involved. length of the operands (the two operands,
This dependence is further explained under after conversion, are always the same
"Attributes of Targets· later in this length).

38 OS PL/I CKT AND OPT LRM PART I

 Bit-string operations are performed on a COMPARISON OPERATIONS
bit-by-bit basis. The effect of the "not-
operation is bit reversal; that is, the
result of ~1 is 0; the result of ~O is 1. A comparison operation is one that is
The result of an "and" operation is 1 only specified by combining operands with one of
if both corresponding bits are 1; the following operators.
otherwise, the result is O. The result of
an 'or' operation is 1 unless both operands < -.< <= = ~= >= > ~>
are zero, in which case it is O. The
following table illustrates the result for These operators specify "less than", "not
each bit position for each of the less than", "less than or equal to", "equal
operators: to", "not equal to·, "greater than or equal
to", "greater than", and "not greater
r-----------------------------------------~ than" •
A I B II -.A I ~B I A& B I A IB
----------------------------------------- There are four types of comparisons:
I II
1 I 1 II 0 o 1 1 1. Algebraic, which involves the
----------------------------------------- comparison of signed arithmetic values
I II I in internal coded arithmetic form. If
1 I 0 II o I 1 o 1 operands differ in base, scale,
----------------------------------------- precision, or mode, they are converted
II I according to the rules for arithmetic
o 1 II 1 I 0 o 1 operations. Numeric character data is
converted to coded arithmetic before
I II comparison. Only the operators = and
o I 0 II 1 I 1 I 0 I 0 ~= are valid for comparison of complex
L-----------------------------------------J operands.

More than one bit-string operation can 2. Character, which involves left-to-
be combined in a single expression that right, character-by-character
yields a bit-string value. comparisons of characters according to
the collating sequence.
In the following examples, if the value
of operand A is '010111'B, the value of 3. Bit, which involves left-to-right,
operand B is '111111'B, and the value of bit-by-bit comparison of binary
operand C is '110'B, then: digits.

~ A yields '101000'B 4. Program control data, which involves

comparison of the internal coded forms
C yields 'OOl'B of the operands. Only the comparison
operators = and , : are permitted; area
C , B yields 'l10000'B variables cannot be compared. The
only conversion that can take place is
A B yields '111111'B offset to pointer; all other type
differences between operands for
C B yields '111111'B program control data comparisons are
in error.
A I (~C) yields '011111'B
If the operands of a problem data
~«~C)I(~B» yields 'l10111'B comparison are.not immediately compatible
(that is, if their data types are
appropriate to different types of
comparison), the operand of the lower
precedence is converted to conform to the
comparison type of the other. The
Boolean Built-in Function precedence of comparison types is (1)
algebraic (highest), (2) character, (3)
bit. Thus,. for example, if a bit string
In addition to the "not", "and" and "or" were to be compared with a fixed decimal
operations using the operators ~,& and I, value, the bit string would be converted to
Boolean operations may be performed using fixed binary for algebraic comparison with
the BOOL built-in function. The concept of the decimal value (which would also be
a built-in function is described in chapter converted to fixed binary). In the
9, "Subroutines and Functions," and the comparison of strings of unequal lengths,
function is described in detail in section the shorter string is padded on the right
G, "Built-in Functions and with blanks (in a character comparison) or
Pseudovariables." 'O'B (in a bit comparison).

Chapter 4: Expressions and Data Convers ion 39

 The result of a comparison operation result. Otherwise if the operands are bit
always is a bit string of length one; the and binary, or both binary, conversions are
value is 'l'B if the relationship is true, performed to produce a bit-string result.
or 'O'B if the relationship is false.
The results of concatenation operations
The most common occurrences of are as follows:
comparison operations are in the IF
statement, of the following format: Bit String: A bit string whose length as
equal to the sum of the lengths of the two
IF A = B bit-string operands.

THEN action-if-true Character String: A character string whose

length is equal to the sum of the lengths
ELSE action-if-false of the two character-string operands.

The evaluation of the expression A = B If an operand requires conversion for

yields either 'l'B or 'O'B. Depending upon the concatenation operation, the result is
the value, either the THEN portion or the dependent upon the length of the character
ELSE portion of the IF statement is string to Which the operand is converted.
executed. For example, if A has the attributes and
value of the constant '010111'B, B of the
Comparison operations need not be constant '101'B, C of the constant 'XY,Z',
limited to IF statements, however. The and 0 of the constant 'AA/BB', then
following assignment statement could be
valid: AIIB yields '010111101'B

x =A < Bi AIIAIIB yields '010111010111101'B

In this example, the value 'l'B would be CliO yields 'XY,ZAAlBB'

assigned to X if A is less than Bi
otherwise, the value 'O'B would be OIIC yields 'AAlBBXY,Z'
assigned. In the same way, the following
assignment statement could be valid: BIID yields '101AA/BB'

X = A = B; Note that, in the last example, the bit

string '101'B is converted to the character
The first symbol (=) is the assignment string '101' before the concatenation is
symbol; the second (=) is the comparison performed. The result is a character
operator. If A is equal to B, the value of string conSisting of eight characters.
X will be 'l'B; if A is not equal to B, the
value of X will be 'O'B.

COMBINATIONS OF OPERATIONS

CONCATENATION OPERATIONS
Different types of operations can be
combined within the same operational
A concatenation operation is one that is expression. Any combination can be used.
specified by combining operands with the For example, the expression shown in the
concatenation symbol: following assignment statement is valid:

II RESULT = A + B < C , Di

It signifies that the operands are to be Each operation within the expression is
joined in such a way that the last evaluated according to the rules for that
character or bit of the operand to the left kind of operation, with necessary data
will immediately precede the first conversions taking place before the
character or bit of the operand to the operation is performed.
right, with no intervening bits or
characters. Assume that the variables given above
are declared as follows:
The concatenation operator can cause
conversion to string type since DECLARE RESULT BIT(3), A FIXED
concatenation can be performed only upon DECIMAL(l), B FIXED BINARY
strings, either character strings or bit (3), C CBARACTER(2), D BIT(4);
strings. If either operand is character or
decimal, any necessary conversions are • The decimal value of A would be
performed to produce a character-string converted to binary base.

40 OS PLII CRT AND OPT LRM PART I

• The binary addition would be performed, as follows:
adding A and B.
(A)+ (B)
• The binary result would be compared with (A+ B) < (C)
the converted binary value of C. «A + B) < C) & (D)

• The bit-string result of the comparison The order of evaluation (and,

would be extended to the length of the consequently, the result) of an expression
bit string 0, and the "and" operation can be changed through the use of
would be performed. parentheses. The above expression, for
example, might be changed as follows:
• The result of the "and" operation, a bit
string of length 4, would be assigned to (A + B) < (C & D)
RESULT without conversion, but with
truncation on the right. The order of evaluation of this
expression would yield a bit string of
The expression in this example is length one, the result of the comparison
described as being evaluated operation-by- operation. In such an expression, those
operation, from left to right. Such would expressions enclosed in parentheses are
be the case for this particular expression. evaluated first, to be reduced to a single
The order of evaluation, however, depends value, before they are considered in
upon the priority of the operators relation to surrounding operators. Within
appearing in the expression. the language, however, no rules specify
which of two parenthesized expressions,
such as those in the above example, would
be evaluated first.
Priority of Operators
The value of A would be converted to
fixed-point binary, and the addition would
In the evaluation of expressions, priority be performed, yielding a fixed-point binary
of the operators is as follows: result (result 1). The value of C would be
converted to a-bit string (if valid for
prefix+ prefix- (highest) such conversion) and the "and" operation
** would be performed.
* / At this point, the expression would have
infix+ infix- been reduced to:

II
result 2 would be converted to binary, and
the algebraic comparison would be
v performed, yielding the bit-string result
of the entire expression.
(lowest)
The priority of operators is defined
If two or more operators of the highest only within operands (or sub-operands). It
priority appear in the same expression, the does not necessarily hold true for an
order of evaluation of those operators is entire expression. Consider the following
from right to left; that is, the rightmost example:
exponentiation or prefix operator is
evaluated first. Each succeeding
exponentiation or prefix operator to the
A + (B < C) & (0 II E *. F)

left has the next highest priority. The priority of the operators specifies, in
this case, only that the exponentiation
For all other operators, if two or more will occur before the concatenation. It
operators of the same priority appear in does not specify the order of the operation
the same expression, the order or priority in relation to the evaluation of the other
of those operators is from left to right. operand (A + (B < e».

Note that the order of evaluation of the Any operational expression (except a
expression in the assignment statement: prefix expression) must eventually be
reduced to a single infix operation. The
RESULT =A + B < C & Di operands and operator of that operation
determine the attributes of the result of
is the result of the priority of the the entire expression. For instance, in
operators. It is as if various elements of the first example of combining operations
the expression were enclosed in parentheses (which contains no parentheses), the "and"

Chapter 4: Expressions and Data Conversion 41

operator is the operator of the final infix A =B * 4;
operation; in this case, the result of
evaluation of the expression is a bit
string of length 4. In the second example The code represented by the name in the
(because of the use of parentheses), the function reference is called a function.
operator of the final infix operation is The function SQRT is one of the PL/I
the comparison operator, and the evaluation built-in functions. Built-in functions,
yields a bit string of length 1. which provide a number of different
operations, are a part of the PL/I
In general, unless parentheses are used language. A complete discussion of each
within the expression, the operator of appears in section G, "Built-in Functions
lowest priority determines the operands of and pseudovariables." In addition, a
the final operation. For example: programmer may write functions for other
purposes (as described in chapter 9,
A + B ** 3 II C * 0 - E "Subroutines and Functions"), and the names
of those functions can be used in function
In this case, the concatenation operator references.
indicates that the final operation will be:

(A + B *. 3) II (C * D - E) The use of a function reference is not

limited to operands of operational
The evaluation will yield a character- expressions. A function reference is, in
string result. itself, an expression and can be used
wherever an expression is .allowed. In
Subexpressions can be analyzed in the general, it cannot be used in those cases
same way. The two operands of the where a variable represents a receiving
expression can be defined as follows: field, such as to the left of an assignmen~

A + (B *. 3)
symbol.

(C * D) - E There are, however, several built-in

functions that can be used as
pseudovariables. A pseudovariable is a
built-in function name that is us·ed in a
Function Reference Operands receiving field. Consider the following
example:

An operand of an expression can be a DECLARE A CHARACTER(10),

constant, an element variable, an array B CHARACTER(30);
variable, or a structure variable. An
operand can also be an expression that SUBSTR(A,6,S) = SUBSTR(B,20,S);
represents a value that is the result of a
computation, as shown in the following In this assignment statement, the SUBSTR
assignment statement: built-in function name is used both in a
normal function reference and as a
A = B * SQRT (C) ; pseudovariable.

In this example, the exp~ession SQRT(C) The SUBSTR built-in fUnction extracts a
represents a value that is equal to the substring of specified length from the
square root of the value of C. Such an named string. As a pseudovariable, i t
expression is called a function reference. indicates the location, within a named
string, that is the receiving field.
A function reference consists of a name
and, usually, a parenthesized list of one In the above example, a substring five
or more variables, constants, or other characters in length, beginning with
expressions. The name is the name of a character 20 of the string B, is to be
block of code written to perform specific assigned to the last five characters of the
computations upon the data represented by string A. That is, the last five
the list and to substitute the computed characters of A are to be replaced by
value in place of the function reference. characters 20 through 24 of B. The first
five characters of A remain unchanged, as
Assume, in the above example, that C has do all of the characters of B.
the value 16. The function reference
SQRT(C> causes execution of the code that All the built-in functions that can be
would compute the square root of 16 and used as pseudovariables are discussed in
replace the function reference with the section G, "Built-in Functions and
value 4. In effect, the assignment Pseudovariables." NO programmer-written
statement would become: function can be used as a pseudovariable.

42 OS PL/I CKT AND OPT LRM PART I

Attributes of Targets second target) and in part from the
attributes of the eventual target (A).
(The only attribute determined from the
The target of a conversion or expression eventual target is DECIMAL, since a binary
operation is the receiving field to which arithmetic representation must be converted
the result of the conversion or operation to decimal repres entation before it can be
is assigned. This section deals with the converted to a character string.) The
principles of determining attributes of attributes of the fourth target (A) are
such targets. Detailed rules are given in known from the DECLARE statement.
section F, WData Conversion and Expression
Evaluation. w When an expression is evaluated, the
target attributes usually are partly
In the case of a direct assignment, such derived from the source, partly from the
as the statement operation being performed, and partly from
the attributes of a second operand. Some
A = B; assumptions may be made, and some
implementation restrictions (for example,
in which conversion must take place, then maximum precision) and conventions exist.
the target is the variable on the left of After an expression is evaluated, the
the assignment symbol (in this case A). result may be further converted. In this
However, during the evaluation of an case, the target attributes usually are
expression, targets are frequently independent of the source.
temporary storage locations created by the
compiler. A conversion always involves a source
data item and a target data item, that is,
Consider the following example: the original representation of the value
and the converted representation of the
DECLARE A CHARACTER(S), value. All of the attributes of both the
B FIXED DECIMAL(3,2), source data item and the target data item
C FIXED BINARY(10); are known, or supplied by default, at
A = B + C; compile time.

During the evaluation of the expression B+C It is possible for a conversion to

and during the assignment of that result, involve intermediate results whose
there are four different targets, as attributes may depend upon the source
follows: value. For example, conversion from
character string to arithmetic may require
1. The compiler-created temporary to an intermediate conversion and, thus, an
which the converted binary equivalent intermediate result, before final
of B is assigned. conversion is completed. The final target
attributes in such cases, however, are
2. The compiler-created temporary to always determined from the source data item
which the binary result of the and are independent of the values of
addition is assigned. variables.

3. The compiler-created temporary to It should be realized that constants

which the converted decimal fixed- also have attributes; the constant 1.0 is
point equivalent of the binary result different from the constants 1, 'l'B, '1',
is assigned. 1B, or lEO. Under the optimizing compiler,
constants may be converted at compile time
4. A, the final destination of the as well as at execution time, but in all
result, to which the converted cases, the rules are the same.
character-string equivalent of the
decimal fixed-point representation of
the value is assigned.
Arr ay Expressions
The attributes of the first target are
determined from the attributes of the
source (B), from the operator, and from the An array expression is a single array
attributes of the other operand (if one variable or an expression that includes at
operand of an arithmetic infix operator is least one array operand. Array expressions
binary, the other is converted to binary may also include operators (both prefix and
before evaluation). The attributes of the infix), element variables, and constants.
second target are determined from the
attributes of the source (C and the Evaluation of an array expression yields
converted representation of B). The an array result. All operations performed
attributes of the third target are on arrays are performed on an element-by-
determined in part from the source (the element basis, in row-major order.

Chapter 4: ExpreSSions and Data Conversion 43

Therefore, all arrays referred to in an identical to the original array, each
array expression must have the same number element of which is the result of the
of dimensions,- and each dimension must be operation performed upon the corresponding
of identical bounds. element of the original array and the
single element. For example:
Although comparison operators are valid
for use with array operands, an array If A is the array 5 10 8
operand cannot appear in the IF clause of
an IF statement. Only an element 12 11 3
expression is valid in the IF clause, since
the IF statement tests a Single true or then A*3 is the array 15 30 24
false result. However, the equality of two
arrays of string data can be tested py 36 33 9
using the STRING built-in function and
pseudovariable to produce two element The element of an array-element
values. For example: operation can be an element of the same
array. For example, the expression
DECLARE (A,B) (10) CHAR(5); A*A(2,3) would give the same result in the
case of the array A above, since the value
of A (2,3) is 3.

IF STRING(A) = STRING(B) THEN ••• Consider the following assignment

statement:
~ Array expressions are not generally
expressions of conventional matrix algebra. A = A * A(l,2);

Again, using the above values for A, the

newly aSSigned value of A would be:
PREFIX OPERATORS AND ARRAYS
50 100 800

The resu1t of the operation of a prefix 1200 1100 300

operator on an array is an array of
identical bounds, each element of which is Note that the original value for A(1,2),
the result of the operation having been which is 10, is used in the evaluation for
performed upon each element of the original only the first two elements of A. Since
array. For example: the result of the expression is assigned to
A, Changing the value of A, the new value
If A is the array 5 3 -9 of A(1,2) is used for all subsequent
operations. The first two elements are
1 2 1 multiplied by 10, the original value of
A(1,2); all other elements are multiplied
6 3 -4 by 100, the new value of A(1,2).

then -A is the array -5 -3 9

-1 -2 -1

-6 -3 4 Array·and-Array Operations

If two arrays are connected by an infix

INFIX OPERATORS AND ARRAYS operator, the two arrays must be of
identical bounds. The result is an array
with bounds identical to those of the
Infix operations that include an array original arrays; the operation is performed
variable as one operand may have an . upon the corresponding elements of the two
element, another array, or a structure as original arrays.
the other operand.
Note that the arrays must have the same
number of dimensions, and corresponding
dimensions must have identical lower bounds
Array-and-Element Operations and identical upper bounds. For example,
the bounds of an array declared X(10,6) are
not identical to the bounds of an array
The result of an operation in which an declared Y(2:11,3:8) although the extents
element and an array are connected by an are the same for corresponding dimensions,
infix operator is an array with bounds and the number of elements is the same.

44 OS PL/I CRT AND OPT LRM PART I

 Examples of array infix expressions are: Data Conversion in Array ExEressions
If A is the array 2 4 3
The examples in this discussion of array
6 1 1 expressions have shown only single
arithmetic operations. The rules for
4 8 2 combining operations and for data
conversion of operands are the same as
and if B is the array 1 5 1 those for element operations.
8 3 4
6 3 1 Structur e Expressions
then A+B is the array 3 9 10
A structure expression is a single
14 4 11 structure variable or an expression that
includes at least one structure operand and
10 11 3 does not contain an array operand. Element
variables and constants can be operands of
and A*B is the array 2 20 21 a structure expression. EValuation of a
structure expression yields a structure
48 3 28 result. A structure operand can be a major
structure name or a minor structure name.
24 24 2
Although comparison operators are valid
for use with structure operands, a
structure operand cannot appear in the IF
clause of an IF statement. Only an element
expression is valid in the IF clause, since
the IF statement tests a single true or
false result.
All operations performed on struct ures
Array-and-Structure 0Eerations are performed on an element-by-element
basis. Except in a BY NAME assignment (see
below), all structure variables appearing
The result of an operation in which an in a structure expression must have
array and structure are connected by an identical structuring.
infix operator is an array of structures
with bounds identical to the array and Identical structuring means that the
structuring identical to the structure. structures must have the same minor
structuring and the same number of
For example, given the follOwing contained elements and arrays and that the
declaration: poSitioning of the elements and arrays
within the structure (and within the minor
DECLARE 1 A, 2 B, 2 c, structures if any) must be the same.
X(2), Arrays in corresponding positions must have
Y(2) LIKE Ai identical bounds. Names do not have to be
the same. Data types of corresponding
the assignment statement: elements do not have to be the same, so
long as valid conversion can be performed.
Y =X + Ai

is valid. This is equivalent to:

PREFIX OPERATORS AND STRUCTURES
Y.B(l) = X(l) + A.B;
Y.C(l) = X(l) + A.C;
Y.B(2) = X(2) + A.B; The result of the operation of a prefix
Y.C(2) = X(2) + A.C; operator on a structure is a structure of
identical structuring, each element of
If the structure has a dimension attribute which is the result of the operation baving
on the level 1 name, the operation becomes been performed upon each element of the
an array-and-array operation. If the array original structure.
elements are structures, the rules about
identical structuring given under ~ Since structures may contain
·Structure Expressions· apply to the array elements of many different data types, a
elements and the structure. prefix operation in a structure expression

Chapter q: Expressions and Data Conversion ~5

would be meaningless unless the operation previous example and if M is the following
can be validly performed upon every element structure:
represented by the structure variable,
which is either a major structure name or a 1 M,
minor structure name. 2 N,
3 0,
3 P,
3 Q,
INFIX OPERATORS AND STRUCTURES 2 R,
3 S,
3 T,
Infix operations that include a structure 3 U:
variable as one operand may have an element
or another structure as the other operand. then A II M is equivalent to:
Structure operands in a structure A.C II M.O
expression need not be major structure A.D II M.P
names. A minor structure name, at any A.E II M.Q
level, is a structure variable. Thus, if A.G II M.S
M.N is a minor structure in the major A.H II M.T
structure M, the following is a structure A.I II M.U
expression:
M.N , '10i0'B
Structure Assignment BY NAME

structure-and-Element Operations One exception to the rule that operands of

a structure expression must have the same
structuring is the case in which the
When an operation has one structure and one structure expression appears in an
element operand, it is the same as a series assignment statement with the BY NAME
of operations, one for each element in the option.
structure. Each sub-operation involves a
structure element and the single element. The BY NAME appears at the end of a
structure assignment statement and is
Consider the following structure: preceded by a comma. Examples are shown
below.
1 A,
2 B, Consider the following structures and
3 C, assignment statements:
3 0,
3 E, lONE, 1 TWO, 1 THREE,
2F, 2 PARTi, 2 PARTi, 2 PARTi,
3 G, 3 RED, 3 BLUE, 3 RED,
3 H, 3 ORANGE, 3 GREEN, 3 BLUE,
3 I: 2 PART2, 3 RED, 3 BROWN,
3 YELLOW, 2 PART2, 2 PART2,
If X is an element variable, then A * X is 3 BLUE, 3 BROWN, 3 YELLOW,
equivalent to: 3 GREEN: 3 YELLOW: 3 GREEN:

A.C * X ONE = TWO, BY NAME:

A.D X ONE.PARTi = THREE.PARTi, BY NAME:
A.E * X ONE = TWO + THREE, BY NAME:
A.G * X
A.H * X The first assignment statement would be the
A.I ** X same as the following:
ONE.PARTi.RED = TWO.PART1.RED:
structure-and-structure Operations ONE.PART2.YELLOW = TWO.PART2.YELLOW:
The second assignment statement would be
When an operation has two structure the same as the following:
operands, it is the same as a series of
element operations, one for each ONE. PARTl • RED = THREE. PARTi • RED:
corresponding pair of elements. For
example, if A is the structure shown in the The third assignment statement would be the

46 OS PL/I CRT AND OPT LRM PART I

same as the following: specified will not hold the converted value
of the list item. The SIZE condition is
ONE.PART1.RED = TWO.PART1.RED normally disabled, so an interrupt will
+ THREE.PART1.RED; occur only if the condition is raised
within the scope of a SIZE prefix (except
ONE.PART2.YELLOW = TWO.PART2.YELLOW that, under the checkout compiler, standard
+ THREE.PART2.YELLOW; system action takes place whether or not
the condition is enabled).
The BY NAME option can appear in an
assignment statement only. It indicates
that assignment of elements of a structure The CONVERSION condition is raised when
is to be made only for those elements whose th~ source field contains a character that
names are common to both structures. is invalid for the conversion being
Except for the highest-level qualifier performed. For example, CONVERSION would
specified in the assignment statement, all be raised if a character string being
qualifying names must be identical. converted to arithmetic contains any
character other than those allowed in
If an operational expression appears in arithmetic constants, or if a character
an assignment statement with the BY NAME string that is being converted to bit
option, operation and assignment are contains any character other than 0 and 1.
performed only upon those elements whose Each invalid character raises the
names have been declared in each of the CONVERSION condition once, so a single
structures. In the third assignment conversion operation causes several
statement above, no operation is performed interrupts if more than one invalid
upon ONE.PART2.GREEN and THREE.PART2.GREEN, character is encountered. The CONVERSION
because GREEN does not appear as an condition is normally enabled, so when the
elementary name in PART2 of TWO. condition is raised, an interrupt will
occur. It can be disabled by a
NOCONVERSION prefix, in which case an
interrupt will not occur when the condition
Exceptional Conditions is raised.

The STRINGSIZE condition is raised when

Three PL/I exceptional conditions may be a character or bit string is assigned to a
raised during conversion of data: SIZE, target that is too small to accommodate it.
CONVERSION, and STRINGSIZE. (The concept Characters or bits are truncated from the
of a condition is explained in chapter 14, right-hand end of the string so as to match
-Exceptional Condition Handling and program the length of the target. The STRINGSIZE
Checkout,- and the conditions are described condition is normally disabled, so that an
in detail in section H, -On-Conditions.-) interrupt will occur only within the scope
of a STRINGSIZE condition prefix.
The SIZE condition is raised when
significant digits are lost from the left- These three conditions may be raised
hand side of an arithmetic value. This can also during the evaluation of an
occur during conversion within an expression,. In addition, four other
expression, or upon assigning the result of conditions may be raised: FIXEDOVERFLOW,
an expression. It is not raised in OVERFLOW, UNDERFLOW, and ZERODIVIDE. Note
conversion to character string or bit that FIXEDOVERFLOW and OVERFLOW are raised
string even if the value is truncated. It when the implementation-defined maximum
is raised on conversion to E or F format in precisions are exceeded,. not when the
edit-directed output if the field width declared precision of a target is exceeded.

Chapter 4: Expressions and Data Conversion 41

 Chapter 5: Statement Classification

This chapter classifies statements strings, area sizes, initial values, and
according to their functions. Statements some file attributes may be determined
in each functional class are listed, the during execution of the program.
purpose of each statement is described, and
examples of their use are shown.

A detailed description of each statement DECLARE AND DEFAULT STATEMENTS

is not included in this chapter but may be
found in section J, "Statements."
The DECLARE statement is the principal
means of specifying the attributes of a
name. A name used in a program need not
Classes of Statements always appear in a DECLARE statement; its
attributes often can be determined by
context. If the attributes are not
statements can be grouped into the explicitly declared and cannot be
following classes: determined by context, default rules are
applied. Default rules are either the
Descriptive standard default rules defined for the
compilers or those defined by the
Input/Output programmer for a particular program using
the DEFAULT statement. The combination of
Data Movement and computational default rules and context determination can
make it unnecessary, in some cases, to use
Program Organization a DECLARE statement.

storage Control The DEFAULT statement gives the

programmer control over attributes which
control are applied by default, for the following:

Exception Control explicitly declared identifiers

Preprocessor contextually declared identifiers

Listing Control implicitly declared identifiers

Diagnostic descriptors in the ENTRY attribute

The names of the classes have been chosen values returned by internal procedures
for descriptive purposes only; apart from
preprocessor and listing control statements DECLARE statements may also be an
they have no fundamental significance in important part of the documentation of a
the language. A statement may be included program; consequently, programmers may make
in more than one class, since it can have liberal use of declarations, even when
more than one function. default attributes apply or when a
contextual declaration is possible.
Because there are no restrictions on the
number of DECLARE statements, different
Descriptive Statements DECLARE statements can be used for
different groups of names. This can make
modification easier and the interpretation
When a PL/I program is executed, it may of diagnostics clearer.
manipulate many different kinds of data.
Each data item, except an arithmetic or
string constant, is referred to in the
program by a name. The PL/I language OTHER DESCRIPTIVE STATEMENTS
requires that the properties (or
attributes) of data items referred to must
be known at the time the program is The OPEN statement allows certain
compiled. There are a few exceptions to attributes to be specified for a file
this rule; for non-STATIC items, the bounds constant and may, therefore, also be
of the dimensions of arrays, the lengths of classified as a descriptive statement.

Chapter 5: Statement Classification 49

'Certain attributes can be specified in an whole. In STREAM transmission, each item
ALLOCATE statement for a controlled may be edited and converted as i t is
variable. The FORMAT statement may be transmitted: in RECORD transmission, the
thought of as describing the layout of data record on the external medium is generally
on an external medium, such as on a page or an exact copy of the record as it exists in
an input card. internal storage, with no editing or
conversion performed.

As a result of these differences, record

Input/Output Statements transmission is particularly applicable for
processing large files that are ~ritten in
an internal representation, such as in
The principal statements of the binary or decimal. Stream transmission may
input/output class are those that actually be used for processing keypunched data and
cause a transfer of data between internal for producing readable output, where
storage and an external medium. Other editing is required.
input/output statements, which affect such
transfers, may be considered input/output
control statements.
RECORD TRANSMISSION STATEMENTS
Each of the input/output statements is
used with an associated FILE option to
identify a file. The file option specifies The READ statement transmits records
a file expression which can be either a directly into internal storage and makes
file constant, a file variable, or a them available for processing. The WRITE
function reference which returns a file statement causes records to be transmitted
value. to the output device. The LOCATE statement
allocates storage for a variable within an
In the following list, the statements output buffer, setting a pointer to
used when transferring data are grouped indicate the location in the buffer, having
into two subclasses, RECORD I/O and STREAM previously caused any record already
I/O: located in a buffer for this file to be
written out.
RECORD I/O statements
The REWRITE statement alters existing
READ records in an UPDATE tile. The DELETE
statement deletes records in an UPDATE
WRITE file.

REWRITE

LOCATE STREAM TRANSMISSION STATEMENTS

DELETE
Only sequential files can be processed with
STREAM I/O Statements the GET and PUT statements. Record
boundaries generally are ignored: data is
GET considered to be a stream of indiVidual
data items, either coming from (GET) or
PUT going to (PUT) the external medium.

I/O Control Statements The GET and PUT statements may transmit
a list of items in one of three modes:
OPEN data-directed, list-directed, or edit-
directed. In data-directed transmission,
CLOSE the names of the data items, as well as
their values, are recorded on the external
UNLOCK medium. In list-directed transmission, the
data is recorded externally as a list of
An allied statement, discussed with constants, separated by blanks or commas.
these statements, is the DISPLAY statement. In edit-directed transmission, the data is
recorded externally as a string of
There are two important differences characters to be treated character by
between STREAM transmission and RECORD character according to a format list.
transmission. In STREAM transmission, each
data item is treated individually, whereas Data-directed transmission is most
RECORD transmission is concerned with useful for reading a relatively small
collections of data items (records) as a number of values and for producing self-

50 as PL/I CKT AND OPT LRM PART I

annotated debugging output. List-directed communicate with the program by typing in a
input is suitable for reading in larger code or a message. The REPLY option may be
volumes of data punched in free form. used merely as a means of suspending
Edit-directed transmission is used wherever program execution until the operator
format must be strictly controlled, for acknowledges the message.
example, in producing reports and for
reading cards punched in a fixed format.

Note: The GET and PUT statements can also

~ed for internal data movement, by Data Movement and Computational
specifying a string name in the STRING Statements
option instead of specifying the FILE
option. Although the facility may be used
for moving data to and from a buffer, it is Internal data movement involves the
not actually a part of the input/output assignment of the value of an expression to
operation. a specified variable. The expression may
be a constant or a variable, or i t may be
an expression that specifies computations
to be made.
INPUT/OUTPUT CONTROL STATEMENTS
The most commonly used statement for
internal data movement, as well as for
The OPEN statement associates a file name specifying computations, is the assignment
with a data set and prepares the data set statement. The GET and PUT statements with
for processing. It may also specify the STRING option can also be used for
additional attributes for the file. internal data movement. The PUT statement
can, in addition, specify computations ~o
An OPEN statement need not always be be made.
written. Execution of any input or output
transmission statement that specifies the
name of an unopened file will result in an
automatic opening of the file before the ASSIGNMENT STATEMENT
data transmission takes place.

The OPEN statement may be used to The assignment statement, which has no
specify any fi1~ attribute except the keyword, is identified by the assignment
ENVIRONMENT ~ttribute. For a PRINT file, symbOl (=). It generally takes one of the
the length" of each printed line and the two forms illustrated by the following
number of lines per page can be specified examples:
only in an OPEN statement by the PAGESIZE
and LINESIZE options. The .LINESIZE option NTOT=TOT:
can be specified for a non-PRINT OUTPUT
file to determine the length of the AV=(AV*NUM+TAV*TNUM)/(NUM+TNUM)i
phYSical blocks transmitted to a device.
The OPEN statement can also be used to The first form can be used purely for
specify a name (in the TITLE option) other internal data movement. The value of the
than a file name, as a link between the variable (or constant) to the right of the
data set and the file. aSSignment symbol is to be assigned to the
variable to the left. The second form
The CLOSE statement dissociates a data includes an operational expression whose
set from a file. All files are closed at value is to be assigned to the variable to
termination of a program, so a CLOSE the left of the aSSignment symbol. The
statement is not always required. second form specifies computations to be
made, as well as data movement.
The UNLOCK statement releases, for use
by other tasks, a record which has Since the attributes of the variable on
restricted access because i t is associated the left may differ from the attributes of
with an EXCLUSIVE file. the result of the expression (or of the
variable or constant), the assignment
statement can also be used for conversion
and editing.
DISPLAY STATEMENT
The variable on the left may be the name
of an array or a structure: the expression
The DISPLAY statement is used to write on the right may yield an array or
messages on the console, usually to the structure value. Thus the assignment
operator. It may also be used, with the statement can be used to mOve aggregates of
REPLY option, to allow the operator to data, as well as single items.

Chapter 5: statement Classification 51

Multiple Assignment: The values of the internal procedures may contain
expression in an assignment statement can declarations that are treated (unless
be assigned to more than one variable in a otherwise specified) as local definitions
statement of the following form: of names. Such definitions are not known
outSide their own block, and the names
A,X =B + C; cannot be referred to in the containing
procedure. Storage associated with these
Such a statement is executed in exactly the names is generally allocated upon entry to
same way as a single assignment, except the block in which such a name is defined,
that the value of B + C is assigned to both and it is freed upon exit from the block.
A and X. In general, i t has the same
effect as if the following two statements The sequence of statements defined by a
had been written: procedure can be executed at any pOint at
which the procedure name is known. This
A = B + C; execution can be either synchronous (that
is, the execution of the invoking procedure
x = B + C; is suspended until control is returned to
it) or asynchronous (that is, execution of
Note: If multiple assignment is used for a the invoking procedure proceeds
structure assignment BY NAME, the concurrently with that of the invoked
elementary names affected will be only procedure); for details of asynchronous
those that are common to all of the operation, see chapter 17, "Multitasking."
structures referred to in the statement. A procedure is invoked either by a CALL
statement or by the appearance of its name
in an expression, in which case the
procedure is called a function reference.
Program Organization Statements A function reference causes a value to be
calculated and returned to the function
reference for use in the evaluation of the
The program organization statements are expression. A function procedure cannot be
those statements used to delimit sections executed asynchronously with the invoking
of a program into blocks and to manipulate procedure.
these blocks. These statements are the
PROCEDURE statement, the END statement, the Communication between two procedures is
ENTRY statement, the BEGIN statement, the by means of arguments passed from an
FETCH statement, and the RELEASE statement. invoking procedure to the invoked
procedure, by a value returned from an
Proper division of a program into blocks invoked procedure, and by names known
simplifies the writing and testing of the within both procedures. A procedure may
program, particularly when a number of therefore operate upon different data when
programmers are co-operating in writing a i t is invoked from different points. A
single program. It may also result in more value is returned from a function procedure
efficient use of storage, since dynamic to a function reference by means of the
storage of the automatic class is allocated RETURN statement.
on entry to the block in which it is
declared.

PROCEDURE STATEMENT

The principal function of a procedure

block, which is delimited by a PROCEDURE ENTRY STATEMENT
statement and an associated END statement,
is to define a sequence of operations to be
performed upon specified data. This The ENTRY statement is used to provide
sequence of operations is given a name (the another possible entry point to a procedure
label of the PROCEDURE statement) and can and, possibly, another parameter list to
be invoked from any point at which the name which arguments can be passed,
is known. corresponding to that entry pOint.

Every program must have at least one ~ It is important to distinguish

PROCEDURE statement and one END statement. between the ENTRY statement, which
A program may consist of a number of specifies an entry to the procedure in
separately written procedures linked which i t occurs, and the ENTRY attribute.
together. A procedure may also contain The ENTRY attribute is considered in
other procedures nested within it. These chapter 9, in ·Subroutines and Functions.·

52 OS PL/I CKT AND OPT LRM PART I

BEGIN STATEMENT Idelimits the group to enable i t to be
Itreated as a single unit in the logiC of
Ithe program. (See ·Control statements".>
Local definitions of names can also be made
within begin blocks, which are delimited by
a BEGIN statement and an associated END
statement. The BEGIN and END statements
specify that the statements contained FETCH AND RELEASE STATEMENTS
between them are to be considered as an
entity for the purpose of flow of control.
Begin blocks are executed in the normal The FETCH statement copies a procedure from
f low of a program. One of the most common auxiliary storage into main storage so that
uses of a begin block is as the on-unit of i t may be invoked, for instance by a CALL
an ON statement, in which case it is not statement later in the program. The
executed through normal flow of control, RELEASE statement frees main storage thus
but only upon occurrence of the specified allocated. If a procedure's entry name
condition. It is also useful for appears in a FETCH statement, then, even if
delimiting a section of a program in which this FETCH statement is never executed, the
some automatic storage is to be allocated. invoking statement will load the procedure
before attempting to initiate its
Each begin block must be nested within a execution. Also, if the procedure's name
procedure or another begin block. appears in a RELEASE statement, but there
is no FETCH statement in the invoking
procedure, invocation will cause the
loading of the invoked procedure.
END STATEMENT

The END statement is used to signify the

lend of a block, a do-group, or a select- Storage Control Statements
I group. Every block, do-group, or select-
group must have an END statement.
However, the END statement may be explicit AS with many other conventions in PLlI, the
or implicit; a single END statement can be conventions concerning storage allocation
applied to a number of nested blocks, do- may be overridden by the programmer.
I groups, and select-groups by the inclusion Storage for variables is generally given
of the label of the containing block, do- the storage class AUTOMATIC by default,
I group, or select-group after the keyword which means that the storage remains
END. The other END statements are then allocated from the time the procedure is
implied by the one containing the label, activated until it is terminated.
and need not be given explicitly. If no Alternatives to the AUTOMATIC attribute
label follows END, the statement applies to that may be chosen by the programmer are
lonly one block, do-group, or select-group. STATIC, in which case storage is allocated
for the duration of the entire program, and
Execution of an END statement for a CONTROLLED or BASED, in which case the
block terminates the block. However, i t is storage can be allocated to the variable
not the only means of terminating a block, and freed under the control of the
even though each block must have an END programmer, using the ALLOCATE and FREE
statement. For example, a procedure can be statements.
terminated by execution of a RETURN
statement (see "Control Statements").

The effect of execution of an END

statement for a do-group depends on whether ALLOCATE AND FREE STATEMENTS
or not the do-group is iterative (see
"Control Statements·). If the do-group is
iterative, execution of the END statement The ALLOCATE statement is used to assign
causes control to return to the beginning storage to controlled and based data,
of the do-group until all iterations are independent of procedure block boundaries.
complete, unless control is passed out of The bounds of controlled arrays, the
the do-group before then. If the do-group lengths of controlled strings, and the size
is noniterative, the END statement merely of controlled areas, as well as their
delimits the group (to enable i t to be initial values, may also be specified at
treated as a Single unit in the logic of the time the ALLOCATE statement is
the program), and control passes to the executed. The FREE statement is used to
next statement. free previously-allocated controlled and
based storage when it is no longer
The END statement of a select-group required.

Chapter 5: statement Classification 53

Control Statements IF A =B
THEN action-if-true
statements in a PL/I program, in general,
are executed sequentially unless the flow ELSE action-it-false
of control is modified by the occurrence of
an interrupt or the execution of one of the A THEN or an ELSE clause consists of
following control statements: either a single or compound statement, a
do-group (see -DO Statement- below),
GO TO la select-group (see ·SELECT Statement"
below), or a begin block. If the
IF comparison is true, the THEN clause is
executed. After execution of the THEN
SELECT clause, the ELSE clause is not executed,
and execution continues with the next
DO statement. Note that the THEN clause can
contain a GO TO statement or some other
LEAVE control statement that would result in a
different transfer of control.
CALL
If the comparison is false, only the
RETURN ELSE clause is executed. control then
continues normally.
END
The IF statement might be as follows:
STOP
IF A =B
EXIT
THEN C = D:
HALT
ELSE C = Ei
If A is equal to B, the value of 0 is
GO TO STATEMENT aSSigned to C, and the ELSE clause is not
executed. If A is not equal to B, the THEN
clause is not executed, and the value of E
The GO TO statement is used as an is aSSigned to C.
unconditional branch. If the destination
of the GO TO is specified by a label Either the THEN clause or the ELSE
variable, it may then be used as a switch clause can contain a control statement that
by assigning label constants, as values, to causes a branch, either conditional or
the label variable. unconditional. If the THEN clause contains
a GO TO statement, for example, there is no
If the label variable is subscripted, need to specify an ELSE clause. Consider
the switch may be controlled by varying the the follOWing example:
subscript. The destination of a GO TO
statement can also be specified by a IF A =B
function reference that returns a label
value. By using label variables or
function references, quite subtle switching
can be effected. It is usually true, next-statement
however, that simple control statements are
the most efficient. If A is equal to B, the GO TO statement of
the THEN clause causes an unconditional
The keyword of the GO TO statement may branch to LABEL_i. If A is not equal to B,
pe written either as two words separated by the THEN cl~use is not executed and control
a blank or blanks, or as a single word, passes to the next statement, whether or
GOTO. not it is an ELSE clause associated with
the IF statement.
Note: If the THEN clause does not cause a
IF STATEMENT tranSfer of control and if it is not
followed by an ELSE clause, the next
statement will be executed whether Or not
The IF statement provides the most common the THEN clause is executed.
conditional branch and is usually used with
a simple comparison expression follOwing The expression following the IF keyword
the word IF. For example: can be only an element expression; i t

54 OS PL/J: cn AND OPr LRM PART I

 cannot be an array or structure expression. The 'action' after a WHEN or OTHERWISE
It can, however, be a logical expression clause may be a single or compound
with more than one operator. For example: statement, a do-group, a select-group, or a
begin block. After the 'action' has been
IF A = B , C = D performed, control passes to the first
THEN GO TO Ri executable statement tollowing the select-
group, unless the normal flow is changed by
The same kind of test could be made with the specified action.
nested IF statements. The following three
examples are equivalent: If the expression in the SELECT
statement is omitted, each WHEN clause
Example 1: expression is evaluated and converted, if
necessary, to a bit string. The action
IF A = B , C = D after the WHEN clause is performed if any
THEN GO TO Ri bit in the resulting bit string is a 'l'B.
B = B + 1;
For example:
Example 2:
SELECT:
IF A = B WHEN CA>B) CALL BIGGER;
THEN IF C = D WHEN (A=B) CALL SAMEi
THEN GO TO R: OTHERWISE CALL SMALLER;
B = B + 1: END;

Example 3: If a select-group contains no WHEN

clauses, the action in the OTHERWISE clause
IF A .,= B THEN GO TO Si is executed unconditionally. If the
OTHERWISE clause is omitted, and execution
IF C .,= D THEN GO TO S: of the select-group does not result in the
GO TO R: selection of a WHEN clause, the ERROR
condition is raised.
S: B = B + 1:
The following example shows nested
select-groups used to set a variable to the
number of days in a specified month.
ISELECT STATEMENT
I DECLARE MONTH CHAR(3),
I YEAR PIC'99',
IThe SELECT statement heads a select-group. NO_DAYS FIXED BINARY;
A select-group provides a multi-way
conditional branch and has the following
form: SELECTCMONTH) ;
WHENC'FEB') SELECT (MODCYEAR,4»;
SELECT CE); WHENCO) NO DAYS = 29:
WHEN CE1,E2,E3) action-l: OTHERWISE NO_DAYS = 28;
WHEN CE4,E5) action-2i END:
WHENC'APR','JUN','SEP','NOV')
NO_DAYS = 30;
OTHERWISE action-n; OTHERWISE NO_DAYS = 31;
END: END;
NL: next statement;
In this example, the MOD built-in
In this example, E, El, etc.; are function returns the remainder when YEAR is
expressions. When control reaches the divided by 4. (The algorithm is incorrect
ISELECT statement, the expression E is for century years.)
levaluated and its value is saved. The
lexpressions in the WHEN clauses are then
levaluated in turn (in the order in which
Ithey appear), and each value is compared 100 STATEMENT
Iwith the value of E. If a value is found I
Ithat is equal to the value of E, the action I
Ifollowing the corresponding WHEN clause is IThe DO statement, and its corresponding END
I performed; no further WHEN clause I statement, delimit a group of statements
lexpressions are evaluated. If none of the Icollectively called a do-group.
lexpressions in the WHEN clauses is equal to I
Ithe expression in the SELECT statement, the I A common use of the DO statement is to
laction specified after the OTHERWISE clause Ispecify that a group of statements is to be
lis executed unconditionally. lexecuted a stated number of times while a

Chapter 5: Statement Classification 55

Icontrol variable is incremented each time the group. For succeeding executions, the
Ithrough the loop. Such a group might take express~on in the REPEAT option (in this
Ithe form: example, 2*1) is evaluated and assigned to
I the control variable. The group is thus
I DO I = 1 TO 10; executed with I equal to 1, 2, 4, 8" 16,
I and so on.
I
I The effect of the preceding example is
I END; the same as the following:
I
• In this example, the group of statements 1=1:
will be executed ten times, while the value A:
of the control variable I ranges from 1
through 10. The effect of the DO and END 1=2*1 :
statements would be the same as the GOTO A:
following:
Note that the REPEAT option does not
I = 1; specify a terminal condition, and execution
A: IF I > 10 THEN GO TO B; of the group will continue indefinitely
unless it is halted by a WHILE or UNTIL
option (see following paragraphs) or
control is transferred to a point outside
I =
I +1: Ithe group.
GO TO A: I
B: next statement I The WHILE and UNTIL options provide a
Imethod of making successive executions of
Note that the increment is made before Ithe do-group dependent upon a specified
the control variable is tested and that, in I condition. Their basic format is:
general, control goes to the statement I
following the group only when the value of I DO WHILE (A=B):
the control variable exceeds the limit set I
in the DO statement. If a reference is I DO UNTIL (A=B);
made to a control variable after the last I
iteration is completed, the value of the I In the DO WHILE statement, the
variable will be one increment beyond the lexpression in the WHILE option is evaluated
specified limit. Ibefore each execution of the do-group. If
Ithe expression is 'true', the do-group is
The increment applied to the control I executed; if it is not, control passes to
variable is assumed to be one unless some the first executable statement follOWing
other value is stated, as follows: the do-group. It is thus equivalent to the
following:
DO I =2 TO 10 BY 2;
S: IF A=B THEN;
This specifies that the loop is to be ELSE GOTO R;
executed five times, with the value of I
equal to 2, 4, 6, 8, and 10.
GOTO S;
If negative increments of the control R: next statement
variable are required, the BY option must
be used. For example: In the DO UNTIL statement, the
expression in the UNTIL option is evaluated
DO I = 10 TO 1 BY -1; after each execution of the group. If the
expression is 'true', control passes to the
The TO and BY options enable the control first executable statement follOWing the
Ivari~ble to be varied in fixed positive or do-group; otherwise, the group is executed
Inegative increments. In contrast, the again. It is thus equivalent to the
IREPEAT option, which is an alternative to following:
Ithe TO and BY options, enables the control
Ivariable to be varied non-linearly. It is S:
lused in the following way: .
'--
I
I DO I =1 REPEAT 2*1; IF (A=B) THEN GOTO R:
I GOTO S:
I R: next statement
I END:
I Note that (in the absence of other
I In this example, the control variable I loptions) a do-group headed by a DO UNTIL
Ihas the value 1 for the first execution of Istatement is executed at least once, but a

56 OS PL/I CKT AND OPT LRM PART I

Ido-group headed by a DO WHILE statement may Example 4:
Inot be executed at all. That is, the
Istatements DO WHILE (A=B) and DO UNTIL DO P=PHEAD REPEAT P->FWD
,
I(A~=B) are not equivalent. WBILE(P~=NULL(»i

This example shows a DO statement used

I
I The WHILE and UNTIL options may be to step along a chained list. The value
Icombined with one another and with control PHEAD is assigned to P for the first
Ivariable specifications. The following iteration of the group. Before each
lexamples show some of the possibilities: subsequent iteration, the value P->FWD
I is assigned to P. The value of P is
I tested before the first and each
subsequent execution of the grouPi if it
I is NULL, no further iterations are
I Example 1: performed.

I
I DO WHILE(A=B) UNTIL(X=10);
The effect of executing a do-group may
be summarized as follows:
In this example, the expression in the
WHILE option is tested before each 1. If a control variable is specified,
execution of the group, and the assign the initial value to the
expression in the UNTIL option is tested control variable.
at the end of each execution of the
group. If, when the DO statement is 2. If the TO option is present, test the
first encountered, A~=B, the group is value of the control variable against
not executed at all. If, however, A=B, the expression in the TO option. If
the group is executed at least once. the control variable is out of range,
leave the group.
If, after an execution of the group,
X=10, no further iterations are 3. If the WHILE option is specified, test
performed. Otherwise, a further the expression in the WHILE option.
iteration is performed provided that A If it is • false', leave the group.
is still equal to B.
4. Execute the statements in the group.
Example 2: 5. If the UNTIL option is specified, test
the expression in the UNTIL option.
DO I=l TO 10 UNTIL(Y=l): If it is 'true', leave the group.
In this example, the group is executed 6. If there is a control variable:
a~ least once, with I equal to 1.
a. If the TO or BY option is
If, after an execution of the group, specified, add the increment to
Y=l, no further iterations are the control variable.
performed. Otherwise, the implied
increment (BY 1) is added to I, and the b. If the REPEAT option is specified,
new value of I is compared with 10. If evaluate the expression in the
I is greater than 10, no further REPEAT option and assign it to the
iterations are performed. Otherwise, a control variable.
new iteration commences.
c. If the TO, BY, and REPEAT options
are all absent, leave the group.
Example 3:
7. Go to 2.
DO 1=1 REPEAT 2*1 UNTIL(I=256)i
A more formal expansion of the iterative
Here, the first execution of the group do-group is given in ·section J:
is performed with 1=1. statements·.
After this and each subsequent If a DO statement specifies a control
execution of the group, the UNTIL Ivariable (DO I = •• • i), the part of the
expression is tested. If I=256, nO Istatement after the equals sign is called a
further iterations are performed. I specification. More than one specification
otherwise, the REPEAT expression is lean be included in a Single DO statement.
evaluated and assigned to I, and a new Iconsider each of the following DO
iteration commences. I statements:

Chapter 5: statement Classification 57

 DO I J,K,L;

DO I 1 TO 10, 13 TO·15;

DO I 1 TO 10, 11 WHILE (A = B); The use of the DO statement in this

manner merely indicates that the do-group
DO I 1 TO 9, 10 REPEAT 2*1 is to be treated logically as a single
UNTIL (1)10000); statement. It can be used to specify a
number of statements to be executed in the
The first statement specifies that the THEN clause or the ELSE clause of an IF
do-group is to be executed once only with I statement, or after the WHEN clause or the
the value of I set equal to the value of J, 10THERWISE clause of a select-group, thus
once only with the value of I set equal to maintaining sequential control without the
the value of K, and once only with the use of a begin block.
value of I set equal to the value of L.

The second statement specifies that the

do-group is to be executed a total of
thirteen times, ten times with the value of
I equal to 1 through 10, and three times
with the value of I equal to 13 through 15.

The third DO statement specifies that LEAVE STATEMENT

the group is to be executed at least ten
times, and then (provided that A is equal
to B) once more; if "BY 0" were inserted The LEAVE statement is used to transfer
after "11", execution would continue with I control from within a do-group to the first
set to 11 as long as A remained equal to B. executable statement tollowing the END
statement that delimits the group. For
I The fourth DO statement specifies that example,
Ithe group is to be executed nine times,
with the value of I equal to 1 through 9, DO
and then successively with the value of I
equal to 10, 20, 40, and so on. Iteration
ceases when the group has been executed LEAVE;
with a value of I greater than 10000.
END;
Note that, in all the above statements, next statement;
a comma is used to separate the
specifications. This indicates that a In this example, the LEAVE statement
succeeding specification is to be causes control to be transferred to the
considered only after the preceding "next statement".
specification has been terminated.
If the LEAVE statement contains a
The control variable of a DO statement reference to a statement label (for
can be used as a subscript in statements example, LEAVE A), control is transferred
within the do-group, so that each iteration to the statement following the END
deals with successive elements of a table statement that closes the do-group whose DO
or array. For example: statement has the specified label. For
example:
DO I = 1 TO 10;
A(I) = I; A: DO I = 1 TO 10;
E~; DO J = 1 TO 5;
IF X(I,J)=O THEN LEAVE A;
In this example, the first ten elements ELSE • • • • •
of A are set to 1,2, ••• ,10, respectively. END;
statement within group A;
END;
statement after group A;
NONITERATIVE DO STATEMENTS
Here the statement LEAVE A causes
control to be transferred to the "statement
The DO statement need not specify repeated after group A"
execution of the statements of a do-group.
It can be used as follows: If the do-group does not have an
explicit END statement, control is
DO; transferred exactly as though all the END
statements were present. For example, in:

58 OS PL/I CKT AND OPT LRM PART I

I A: DO I = 1 TO 10; processing it is a null operation. When
I B: DO J = 1 TO 5; included in a source program, i t causes
I IF X(I,J)=O THEN LEAVE; program execution to be suspended and
I ELSE • • • • • ; control passed to the terminal.
I END A;
I
I the LEAVE statement causes control to
Ileave group B; the next iteration of group Exception Control Statements
lA, if there is one, then commences.
I
, A LEAVE statement cannot cause control
Ito leave a block. The control statements, discussed in the
preceding section, alter the flow of
control whenever they are executed.
Another way in which the sequence of
CALL, RETURN, AND END STATEMENTS execution can be altered is by the
occurrence of a program interrupt caused by
an exceptional condition that arises.
A subroutine may be invoked by a CALL
statement that names an entry pOint of the
subroutine. When the multitasking In general, an exceptional condition is
facilities are not in use, control is the occurrence of an unexpected action,
returned to the activating, or invoking, such as an overflow error, or of an
procedure when a RETURN statement is expected action, such as an end of file,
executed in the subroutine or when that occurs at an unpredictable time. A
execution of the END statement terminates detailed discussion of the handling of
the subroutine. If the CALL statement these conditions appears in chapter 14,
contains one of the multitasking options, "Exceptional Condition Handling and Program
TASK, EVENT, or PRIORITY, the subroutine is Checkout."
executed as a subtask with its own separate
flow of control: in this case, the RETURN
or END statement merely terminates th~ The three exception control statements
separate flow of control established for are the ON statement, the REVERT statement,
the subtask. (See chapter 17, and the SIGNAL statement.
-Multitasking. W)

The RETURN statement with a

parenthesized expression is used in a ON STATEMENT
function procedure to return a value to a
function reference.
The ON statement is used to specify action
Normal termination of a program occurs to be taken when any subsequent occurrence
as the result of normal execution of the of a specified condition causes a program
final END statement of the main procedure interrupt. ON statements may specify
or of a RETURN statement in the main particular action for any of a number of
procedure, either of which returns control different conditions. For all of these
to the calling program, which may be the conditions, a standard system action exists
operating system. Termination of a program as a part of PL/I, and if no ON statement
by any other method is abnormal. is in force at the time an interrupt
occurs, the standard system action will
take place. For most conditions, the
standard system action is to print a
STOP AND EXIT STATEMENTS message and take action which usually leads
to termination of execution.

The STOP and EXIT statements are both used The ON statement takes the form:
to cause abnormal termination. The STOP
statement terminates execution of the ON condition[SNAP] {SYSTEMilon-unit}
entire program, including all concurrent
tasks. The EXIT statement terminates only The "condition" is one of those listed in
the task that executes it, together with section H, "On-Conditions." The "on-unit"
any attached tasks. (See chapter 11, is a single statement or a begin block that
WMultitasking. W) specifies action to be taken when that
condition arises and an interrupt occurs.
For example:

HALT STATEMENT ON ENDFILE(DETAIL) GO TO NEXT_MASTER;

This statement specifies that when an

The HALT statement is effective only in interrupt occurs as the result of trying to
conversational processing: in batch read beyond the end of the file named

Chapter 5: Statement Classification 59

DETAIL, control is to be transferred to the Preprocessor St atements
statement labeled NEXT_MASTER.
When execution of an on-unit is PL/I allows a degree of control over the
successfully completed, control will contents of the source program during the
normally return to the pOint of the compilation. The programmer can specify,
interrupt or to a pOint immediately for example, that any identifier appearing
following it, depending upon the condition in the source program will be changed: he
that caused the interrupt. can select parts of the program to be
compiled without the rest: he can include
The effect of an ON statement, the text from an external source. These
establishment of the on-unit, can be operations are performed by the
changed within a block (1) by execution of preprocessor stage of the compiler, and are
another ON statement naming the same specified by preprocessor statements that
condition with either another on-unit or appear among the other statements within
the word SYSTEM, which re-establishes the source program itself.
standard system action, or (2) by the
execution of a REVERT statement naming that
condition. On-units in effect at the time In general, preprocessor statements are
another block is activated remain in effect identified by a leading percent symbol
in the activated block, and in other blocks before the keyword: several of them have
activated by it, unless another ON the same keywords as standard PL/I
statement for the same condition is statements, and these have a similar effect
executed. When control returns to an at compile time to that of their
activating block, on-units are re- counterparts at execution time.
established as they existed.
The complete list of preprocessor
statements is as follows:
REVERT STATEMENT ~ACTIVATE IIF
lassignment II NCLUDE
The REVERT statement is used to cancel the
effect of all ON statements for the same IDEACTIVATE INOTE
condition that have been executed in the
block in which the REVERT statement IDECLARE INULL
appears.
100 I PROCEDURE
The REVERT statement, which must specify
the condition name, re-establishes the on- lEND preprocessor RETURN
unit that was in effect in the activating
block at the time the current block was IGO TO
invoked.
These statements are discussed in chapter
16, ·Compile-Time Facilities· and in
section J, ·Statements."
SIGNAL STATEMENT

Listing Control Statements

The SIGNAL statement simulates the
occurrence of an interrupt for a named
condition. It can be used to test tHe IThere are five statements that allow the
coding of the on-unit established by Iprogrammer to control the format of the
execution of an ON statement. For example: Ilisting of his program, and to specify
Iwhich parts of the listings are to be
SIGNAL OVERFLOW: I printed. The statements are:
I
This statement would simulate the I ICONTROL
odcurrence of an overflow interrupt and
would cause execution of the on-unit
established for the OVERFLOW condition. If ,
I
I INOPRINT
an on-unit has not been established,
standard system action for the condition is ,
I I PAGE
performed. In most cases, the standard
system action is the same as for when the
on-unit is entered following an interrupt.
,
I
I
IPRINT
ISKIP

60 OS PL/I CRT AND OPT LRM PART I

They are described in chapter 16, ·Compile- The execution of a CHECK statement that
time Facilities. w specifies or assumes a particular
identifier has the same result as if the
Although they have the initial percent CHECK condition has been enabled for every
symbol, these statements do not require the blOCK in which the identifier is known.
use of the preprocessor. This applies to all such blocks in the
current compilation and to all separately
compiled blocks in which the identifier is
known and which are active at the same time
as the current block.
Diagnostic Statements
Information is put out for label and
entry constants and for all variables. It
A program processed by the PL/I checkout comprises:
compiler can include statements that
provide a considerable amount of diagnostic 1. Problem variables:
information during execution. These
statements: Name and value

1. Control a continuing output of 2. Constants and program-control

diagnostic information throughout variables:
execution:
Name, and, under the checkout
CHECKINOCHECK statement compiler, details of the current
FLOWINOFLOW statement situation of the constant or
variable. For example, the
2. Produce diagnostic information at details for a file variable
specific points during execution: include whether the file is open
or closed.
PUT statement with one of the
options: The NOCHECK statement prevents output of
CHECK information for the specified or
LIST assumed variables.
DATA
EDIT
SNAP
FLOW FLOW AND NOFLOW STATEMENTS
ALL
With the exception of a PUT statement with Execution of a FLOW statement results in
the LIST, DATA, or EDIT option, none of information being put out at every transfer
these statements provide diagnostic of control within the current task during
information when processed by the PL/I I execution. This continues until the task
optimizing compiler. This compiler checks Iterminates or until a NOFLOW statement is
these statements for syntax and then executed.
ignores them; there is no output. In
addition, the implementation of a PUT If FLOW is active, and the task attaches
statement with the LIST or DATA option by la subtask, FLOW is also active for the
the optimizing compiler is different from Isubtask until the subtask executes a NOFLOW
that of the checkout compiler. The I statement.
checkout compiler implements such a
statement by producing information about At each transfer of control, the
problem and program-control "variables; the information put out comprises the statement
optimizing compiler produces information number of the statement that caused the
about problem variables only. transfer of control, and the statement
number of the statement that received
control at that transfer.

CHECK AND NOCHECK STATEMENTS The NOFLOW statement prevents the output
of FLOW information at a transfer of
control.
When a CHECK statement is executed,
information about the variables specified
or assumed is put out whenever these
variables occur in pre-defined situations. PUT STATEMENTS
This continues to the end of program
execution or until the CHECK statement is
overridden by a NOCHECK statement. When a PUT statement is executed, the

Chapter 5: Statement Classification 61

output comprises: FLOW

LIST, DATA or EDIT

The same information as for the FLOW
The name of the variable appears if DATA statement, for the last n transfers of
is used. The remaining output is: control. The value of ~-iS specified in
a compiler option.
Problem variables: Value

Program-control variables (LIST and ~L

DATA only): Current situation of the
variable Information about all the variables in
the program, together with the
SNAP information provided by the SNAP and
FLOW options, and the values of the ON
The current statement number and a list bUilt-in functions. Options may be
of the procedures currently active. specified to limit the output.

62 OS PL/I CRT AND OPT LRM PART I

 Chapter 6: Program Organization

This chapter discusses how statements can A: READIN: PROCEDURE;

be organized into blocks to form a PL/I statement-l
program, how control flows within a program statement-2
from one block of statements to another,
and how storage may be allocated for data
within a block of statements. The
discussion in this chapter does not statement-n
completely cover multitasking, which is END READIN;
discussed in detail later. However, the
discussion generally applies to all blocks, In general, control is transferred to a
whether or not they are executed procedure through a reference to the name
concurrently. (or one of the names) of the procedure.
Thus, the procedure in the above example
would be given control by a reference to
either of its names, A or READIN.
A PL/I program consists of one or more
Blocks such procedures, each of which may contain
other procedures and/or begin blocks.
A block is a delimited sequence of
statements that constitutes a section of a
program. It localizes names declared BEGIN BLOCKS
within the block and limits the allocation
of variables. There are two kinds of
blocks: procedure blocks and begiri blocks. A begin block is a set of statements headed
The optimizing compiler will accept a by a BEGIN statement and ended by an END
maximum of 255 blocks in one compilation. statement, as follows:
There is no limit for the checkout
compiler. [label:] ••• BEGIN;

END [label];
PROCEDURE BLOCKS
Unlike a procedure block, a label is
optional for a begin block. If one or more
A procedure block, simply called a labels are prefixed to a BEGI~ statement,
procedure, is a sequence of statements they serve only to identify the starting
headed by a PROCEDURE statement and ended point of the block. (Control may pass to a
by an END statement, as follows: begin block without reference to the name
of that block through normal sequential
label: [label:] ••• PROCEDURE; execution, although control can be
transferred to a labeled BEGIN statement by
execution of a GO TO statement.) The label
following END is optional. However, a
END[labell; label can appear after END, matching a
label of the corresponding BEGIN statement.
All procedures must be named because the (There are exceptions; see ·use of the END
procedure name is the primary point of statement-, later in this chapter.) An
entry through which control can be example of a begin block follows:
transferred to a procedure. Hence, a
PROCEDURE statement must have at least one B: CONTROL: BEGIN;
label. A label need not appear after the statement-1
keyword END in the END statement, but if statement-2
one does appear, it must match the label
(or one of the labels) of the PROCEDURE
statement to which the END statement
corresponds. (There are exceptions; see statement-n
·use of the' END statement·, later in this END B.
chapter.) An example of a procedure
follows: Unlike procedures, begin blocks

Chapter 6: Program organization 63

generally are not given control through A: PROCEDURE;
special references to them. The normal statement-al
sequence of control governing ordinary statement-a2
statement execution also governs the statement-a 3
execution of begin blocks. Control passes B: BEGIN;
into a begin block sequentially, following statement-bl
execution of the preceding statement. The statement-b2
only exception is a begin block used as the statement-b3
on-unit in an ON statement. In this case, END B;
the block is executed only upon occurrence statement-a 4
of the specified condition. statement-aS
C: PROCEDURE;
Begin blocks are not essential to the statement-cl
construction of a PL/I program. However, statement-c2
there are times when it is advantageous to D: BEGIN;
use begin blocks to delimit certain areas statement-dl
of a program. These advantages are statement-d2
discussed in this chapter and in chapter 7, statement-d3
"Recognition of Names." E: PROCEDURE;
statement-el
statement-e2
END E;
statement-d4
END D;
END C;
statement-a6
statement-a7
END A;

In the above example, procedure block A

is an external procedure because it is not
contained in any other block. Block B is a
begin block that is contained in A; it
contains no other blocks. Block C is an
internal procedure; it contains begin block
D, which, in turn, contains internal
INTERNAL AND EXTERNAL BLOCKS procedure E. This example contains three
levels of nesting relative to Ai Band C
are at the first level, D is at the second
Any block can contain one or more blocks. level (but the first level relative to C)
That is, a procedure, as well as a begin and E is at the third level (the second
block, can contain other procedures and level relative to C, and the first level
begin blocks. However, there can be no relative to D).
overlapping of blocks; a block that
contains another block must totally Under the optimizing compiler, the
encompass that block. maximum permissible depth of nesting is 50.
There is no limit under the checkout
A procedure block that is contained compiler.
within another block is called an internal
procedure. A procedure block that is not
contained within another block is called an
external procedure. There must always be Us e of the END Stat ement
at least one external procedure in a PL/I
program. (Note: Each external procedure is
compiled separately. Entry names of The use of the END statement with a
external procedures cannot exceed seven procedure, begin block, do-group, or
characters. ) Iselect-group is governed by the. following
rules:
Begin blocks are always internal; they
must always be contained within another 1. If a label is not used after END, the
block. END statement closes (that is, ends)
that unclosed block headed by the
Internal procedure and begin blocks can BEGIN or PROCEDURE statement, or that
also be referred to as nested blocks. unclosed do-group headed by the DO
Nested blocks, in turn, may have blocks statement, or that unclosed select-
nested within them, and so on. The group headed by a SELECT statement,
outermost block must always be a procedure. that physically precedes, and appears
Consider the following example: closest to, the. END statement.

64 OS PL/I CRT AND OPT LRM PART I

 2. If the optional label is used after FRST: PROCEDURE;
END, the END statement closes that statement-fl
unclosed block, do-group, or select- statement-f2
group headed by the BEGIN, PROCEDURE, ABLK: BEGIN;
DO, or SELECT statement that has a statement-al
matching label, and that physically statement-a2
precedes, and appears closest to, the SeND: PROCEDURE;
END statement. Any unclosed blocks, statement-sl
do-groups, or select-groups nested statement-s2
within such a block, do-group, or- BBLK: BEGIN;
select-group are automatically closed statement-bl
by this END statement; this is known statement-b2
as multiple closure. END SCND;
statement-a3
END FRST;

Note that a label prefix attached to an END

Multiple closure is a shorthand method statement specifying multiple closure is
of specifying a number of consecutive END assumed to apply to the last END statement.
statements. In effect, the compiler Therefore all intervening groups and blocks
inserts the required number of END will be terminated if control passes to
statements immediately preceding the END such a statement. For example:
statement specifying multiple closure. For
example, assume that the following external CBLK: PROCEDURE;
procedure has been defined: statement-cl
statement-c2
DGP: DO I = 1 TO 10;
statement-dl
GO TO LBL;
FRST: PROCEDURE; statement-d2
statement-fl LBL: END CBLK:
statement-f2
ABLK: BEGIN; In this example, the END CBLK statement
statement-al closes the block CBLK and the iterative do-
statement-a2 group DGP. The effect is as if an
SCND: PROCEDURE; unlabeled END statement for DGP appeared
statement-sl immediately after statement-d2, so that the
statement-s2 transfer to LBL would prevent all but the
BBLK: BEGIN; first iteration of DGP from taking place,
statement-bl and statement-d2 would not be executed.
statement-b2
END;
END;
statement-a3 Activation of Blocks
END ABLK;
END FRST;
Although the begin block and the procedure
have a physical resemblance and play the
same role in the allocation and freeing of
In this example, begin block BBLK and storage, as well as in delimiting the scope
internal procedure SCND effectively end in of names, they differ in the way they are
the same place; that is, there are no activated and executed. A begin block,
statements between the END statements for like a Single statement, is activated and
each. This is also true for begin block executed in the course of normal sequential
ABLK and external procedure FRST. In such program flow (except when specified as an
cases, it is not necessary to use an END on-unit) and, in general, can appear
statement for each block, as shown; rather, wherever a single statement can appear.
one END statement can be used to end BBLK For a procedure, however, normal sequential
and SCND, and another END can be used to program flow passes around the procedure,
end ABLK and FRST. In the first case, the from the statement before the PROCEDURE
statement would be END SCND, because one statement to the statement after the END
END statement with no following label would statement of that procedure. The only way
close only the begin block BBLK (see the in which a procedure can be activated is by
first rule above). In the second case, a procedure reference.
only the statement END FRST is required;
the statement END ABLK is superfluous. A procedure reference is the appearance
Thus, the example could be specified as of an entry expression in o~e of the
follows: following contexts:

Chapter 6: Program Organization 65

 '1. After the keyword CALL in a CALL DECLARE ENTl ENTRY VARIABLE;
statement.

2. After the keyword CALL in the CALL ENTl = ERRT;

option of the INITIAL attribute.

3. As a function reference. CALL ENT1:

This chapter uses examples of the first

of these; the material, however, is CALL ERRT:
relevant to the other two forms as well.
For further information, refer to the
discussion of the INITIAL attribute in
section I,' "Attributes," and to chapter 9,
"Subroutines and Functions." When a procedure reference is executed,
the procedure containing the specified
entry pOint is activated and is said to be
The simplest form of the CALL statement invoked; control is transferred to the
is: specified entry pOint. (This statement
does not apply when the CALL statement
specifies one of the multitasking options.
CALL entry-constant; see "Multitasking.") The pOint at which
the procedure reference appears is called
the point of invocation and the block in
If the entry constant is a label of a which the reference is made is called the
PROCEDURE statement it represents the invoking block. An invoking block remains
primary entry point to the procedure; if it active even though control is transferred
is a label of an ENTRY statement it from it to the block it invokes.
represents a secondary entry point. The
following is an example of a procedure
containing secondary entry pOints. Whenever a procedure is invoked at its
primary entry point, execution begins with
A: PROCEDURE; the first executable statement in the
statement-l invoked procedure. However, when a
statement-2 procedure is ~nvoked at a secondary entry
ERRT: ENTRY; pOint, execution begins with the first
statement-3 executable statement following the ENTRY
statement-4 statement that defines that secondary entry
statement-5 point. Therefore, if all of the numbered
NEXT: RETR: ENTRY; statements in the last example are
statement-6 executable, the statement CALL A would
statement-1 invoke procedure A at its primary entry
statement-8 pOint, and execution would begin with
END A; statement-l: the statement CALL ERRT would
invoke procedure A at the secondary entry
In this example, A is the primary entry point ERRT, and execution would begin with
point to the procedure, and ERRT, NEXT, and statement-3; either of the statements CALL
RETR specify secondary entry points. NEXT or CALL RETR would inVOke procedure A
Actually, since they are both names for the at its other secondary entry point, and
same ENTRY statement, NEXT and RETR specify execution would begin with statement-6.
the same secondary entry point. The Note that any ENTRY statements encountered
procedure may be activated by one of the during sequential flow are never executed;
following statements: control flows around the ENTRY statement as
though the statement were a comment.
CALL A;
CALL ERRT;
CALL NEXT; Any procedure, whether external or
CALL RETR; internal, can always invoke an external
procedure, but it cannot always invoke an
Alternatively, the appropriate entry internal procedure that is contained in
name value could be assigned to an entry some other procedure. Those internal
variable, and this entry variable could be procedures that are at the first level of
used in the procedure reference. In the nesting relative to a containing procedure
following example, the two CALL statements can always be invoked by that containing
have the same effect. procedure, or by each other. For example:

66 OS PL/I CRT AND OPT LRM PART I

 PRMAIN: PROCEDURE: • The initial procedure remains active for
statement-l the duration of the program.
statement-2
statement-3 • All activated blocks remain active until
A: PROCEDURE: they are terminated (see below).
statement-a1
statement-a 2
B: PROCEDURE;
statement-b1 Termination of Blocks
statement-b2
END Ai
statement-4 In general, a procedure block is terminated
statement-5 when, by some means other than a procedure
C: PROCEDURE; reference, control passes back to the
statement-c1 invoking block or to some other active
statement-c2 block. Similarly, a begin block is
END C: terminated when, by some means other than a
statement-6 procedure reference, control passes to
statement-1 another active block.- There are a number
END PRMAIN; of ways by which such transfers of control
can be accomplished, and their
interpretations differ according to the
In this example, PRMAIN can invoke type of block being terminated.
procedures A and C, but not B: procedure A
can invoke procedures Band C: procedure B Note that when a block is terminated,
can invoke procedure C; and procedure C can any task attached by that block is
invoke procedure A but not B. terminated (see chapter 17,
-Multitasking-).
The foregoing discussion about the
activation of blocks presupposes that a
program has already been activated. A PL/I
program becomes active when a calling BEGIN BLOCK TERMINATION
program invokes the initial procedure.
This calling program usually is the
operating system, although it could be A begin block is terminated when any of the
another program. The initial procedure, following occurs:
called the main procedure, must be an
external procedure whose PROCEDURE 1. Control reaches the END statement for
statement has the OPTIONS(MAIN) the block. When this occurs, con~rol
specification, as shown in the following moves to the statement physically
example: following the END, except when the
block is an on-unit.
CONTRL: PROCEDURE OPTIONS (MAIN) ;
CALL Ai 2. The execution of a GO TO statement
CALL B: within the begin block (or any block
CALL C: activated from within that begin
END CONTRLi block) transfers control to a point
not contained within the block.
In this example, CONTRL is the initial
procedure and it invokes other procedures 3. A STOP or EXIT statement is executed
in the program. (thereby terminating execution of the
current task and all its subtasks).
The following is a summary of what has
been stated or implied about the activation 4. Control reaches a RETURN statement
of blocks: that transfers control out of the
begin block and out of its containing
• A program becomes active when the procedure as well.
initial procedure is activated by the
operating system. 5. A procedure within which the begin
block is contained has -been attached
• Except for the initial procedure, as a task, and the attaching block
external and internal procedures terminat es •
contained in a proqram are activated
only when they are invoked by a A GO TO statement of the type described
procedure reference. in item 2 can also cause the termination of
other blocks as follows:
• Begin blocks are activated through
normal sequential flow or as on-units. If the transfer point is contained in a

Chapter 6: Program organization 61

block that did not directly activate the 2. Control reaches the END statement of
block being terminated, all intervening the procedure. Effectively, this is
blocks in the activation sequence are equivalent to the execution of a
terminated. RETURN statement.
For example, if begin block B is 3. The execution of a GO TO statement
contained in begin block A, then a GO TO within the procedure (or any block
statement in B that transfers control to a activated from within that procedure)
point contained in neither A nor B transfers control to a point not
effectively terminates both A and B. This contained within the procedure.
case is illustrated below:
4. A STOP or EXIT statement is executed
FRST: PROCEDURE OPTIONS(MAIN): (thereby terminating execution of the
statement-1 current task and all its subtasks).
statement-2
statement-3 5. The procedure or a containing
A: BEGIN: procedure has been attached as a task
statement-a1 and the attaching block is terminated.
statement-a2
B: BEGIN: Items 1 and 2 are normal procedure
statement-b1 terminations; items 3, 4, and 5 are
statement-b2 abnormal procedure terminations.
GO TO LAB:
statement-b3 As with a begin block, the type of
END B: termination described in item 3 can
statement-a]' sometimes result in the termination of
END A: several procedures and/or begin blocks.
statement-4 SpeCifically, if the transfer point
statement-5 specified by the GO TO statement is
LAB: statement-6 contained in a block that did not directly
statement-7 activate the block being terminated, all
END FRST; intervening blocks in the activation
sequence are terminated. Consider the
After FRST is invoked, the first three following example:
statements are executed and then begin
block A is activated. The first two A: PROCEDURE OPTIONS(MAIN):
statements in A are executed and then begin statement-1
block B is activated (A remaining active). statement-2
When the GO TO statement in B is executed, B: BEGIN:
control passes to statement-6 in FRST. statement-bl
Since statement-6 is contained in neither A statement-b2
nor B, both A and B are terminated. Thus, CALL C:
the transfer of control out of begin block statement-b3
B results in the termination of intervening END B;
block A as well as termination of block B. statement-3
statement-4
C: PROCEDURE:
statement-c1
PROCEDURE TERMINATION statement-c2
statement-c3
D: BEGIN:
A procedure is terminated when one of the statement-dl
following occurs: statement-d2
GO TO LAB:
1. Control reaches a RETURN statement. statement-d3
within the procedure. The execution END D:
of a RETURN statement causes control statement-c4
to be returned to the point of END C:
invocation in the invoking procedure. statement-5
If the point of invocation is a CALL LAB: statement-6
statement, execution in the invoking statement-7
procedure resumes with the statement END A:
following the CALL. If the point of
invocation is one of the other forms In the above example, A activates B, which
of procedure references (that is, a activates C, Which activates D. In D, the
CALL option or a function reference), statement GO TO LAB transfers control to
execution of the statement containing statement-6 in A. Since this statement is
the reference will be resumed. not contained in D, C, or B, all three

68 OS PL/I CKT AND OPT LRM PART I

blocks are terminated; A remains active. ·Subroutines and Functions·, is generally
Thus, the transfer of control out of D resident in main storage throughout the
results in the termination of intervening execution of the entire program. If
blocks Band C as well as the termination required, however, a procedure may be
of block D. brought into main storage for only as long
as it is required: the invoked procedure
is dynamically loaded into, and dynamically
deleted from, main storage during execution
PROGRAM TERMINATION of the calling procedure.

A program is terminated when anyone of the Dynamic loading and deletion of

following occurs: procedures is particularly useful when a
called procedure is not necessarily invoked
1. Control for the program reaches an every time the calling procedure is
EXIT statement in the major task. executed, and when conservation of main
This is abnormal termination. storage is more important than a short
execution time.
2. Control for the program reaches a STOP
statement. (When multitasking is in The PL/I statements that initiate the
operation, the program, that is, the loading and deletion of a procedure are
major task, is terminated when any FETCH and RELEASE. The appearance of an
task reaches a STOP statement. See entry name in a FETCH or RELEASE statement
chapter 11, "Multitasking.") This is indicates to the compiler that the
abnormal termination. procedure containing an entry pOint with
that name will need to be fetched into main
3. Control reaches a RETURN statement or storage before it can be executed. When a
the final END statement in the main FETCH statement is executed, the procedure
procedure. This is normal is copied from auxiliary storage into main
termination. storage, unless a copy already exists in
main storage. In addition, when a CALL
4. The ERROR condition is raised in the statement or option or a function reference
major task and there is no established is executed, the procedure is copied into
on-unit for ERROR and FINISH, or, if main storage, unless a copy exists already.
one or both of the conditions has an Thus, a procedure may be loaded from
established on-unit, on-unit exit is auxiliary storage by:
by normal return, rather than by GO TO
branching. This is abnormal 1. execution of a FETCH statement;
termination. The program is not
terminated if ERROR is raised by a
SIGNAL ERROR statement inserted by the
checkout compiler in place of a 2. execution of a CALL statement or
statement in which an error had been option or a function reference,
detected. In conversational provided that the name of the entry
processing, the ERROR and FINISH point of the procedure appears,
conditions cause control to be passed somewhere in the calling procedure,. in
to the terminal, and this is regarded a FETCH or RELEASE statement.
as equivalent to an on-unit being
entered; any statements then entered In neither case is it an error if the
in immediate mode are processed as if procedure has. already been fetched into
in an ERROR or FINISH on-unit. main storage. In case 2, it is not
necessary that control should pass through
On termination of a program, whether the FETCH or RELEASE statement, either
normal or abnormal, control is returned to before or after execution of the CALL or
the calling program (this is usually the function reference.
operating system control program).
Whichever statement caused the loading
of the fetched procedure, execution of the
CALL statement or option or the function
Dynamic Loading of an External reference invokes the procedure in the
Procedure normal way.
The fetched procedure may be allowed to
A procedure invoked by a CALL statement or remain in main storage until execution of
a CALL option of an INITIAL attribute, as the whole program is completed.
described in "Activation of Blocks", Alternatively, the storage it occupies may
earlier in this chapter, or by a function be freed for other purposes at any time by
reference, as described in chapter 9, means of the RELEASE statement.

Chapter 6: Program Organization 69

 Consider the following example, in which print file SYSPRINT, identifiers with
PROGA and PROGB are entry names of the FILE attribute are not permitted
procedures resident on auxiliary storage. in a fetched procedure unless they are
parameters. This means any other file
PROG: PROCEDURE; used in the fetched procedure,
including the standard stream-oriented
input file SYSIN, must be passed from
the calling procedure.
FETCH PROGA;
The following additional rules
CALL PROGA; apply to the use of files in fetched
procedures:
RELEASE PROGA;
a. A file that is explicitly opened
in a fetched procedure must be
explicitly closed in that
CALL PROGB; procedure before the procedure
GO TO FIN; ends •
FETCH PROGB;
b. A file that is implicitly opened
in a fetched procedure must be
closed only in the fetching
FIN: END PROG; procedure.
PROGA will be loaded into main storage h¥ c. A file that is open when it is
the first FETCH statement, and will be passed to a fetched procedure must
executed when the first CALL statement is not be closed in the fetched
reached; its storage is released when the procedure.
RELEASE statement is executed. PROGB will
be fetched when the second CALL statement I 5. Storage for STATIC variables in the
is reached, even though the FETCH statement fetched procedure is allocated when
referring to this procedure is never the FETCH statement is executed, and
executed, and the same CALL statement will is freed when a correSpOnding RELEASE
initiate execution of PROGB. Note that the statement is executed. Each time a
same results would be achieved if the procedure is fetched into main
statement FETCH PROGA; were omitted; the storage, a STATIC variable either is
appearance of PROGA in a RELEASE statement given the value specified in an
will cause the stat~ent CALL PROGA; to INITIAL attribute, or, if there is no
fetch the procedure, as well as invoke it. INITIAL attribute, is uninitialized.
The fetched procedure is compiled and I 6. The FETCH, RELEASE, and CALL
link-edited separately from the ca1ling statements must specify entry
procedure. The programmer must ensure that constants. Entry variables are not
the entry name specified in FETCH, RELEASE, permitted. Note that an entry
and CALL statements and options, and in constant may have no more than seven
function references, is known in auxiliary characters.
storage. The job control statements
necessary to achieve this are discussed in I 1. Fetched procedures may not fetch
OS PL/I Checkout compiler: programmer's further procedures.
Guide and OS PL/I Optimizing compiler:
Programmer's Guide I~: Violation of rules 3, 4, or 6 will
Icause random errors; neither the optimizing
Rules concerning the use of dynamically- Inor the checkout compiler is able to detect
loaded procedures are: Ithe violation.
1. Only external procedures may be
fetched.
Storage Allocation
2. Identifiers with the EXTERNAL
attribute are not permitted in a
fetched procedure. Storage allocation is the process of
associating an area of storage with a
3. Identifiers with the CONTROLLED variable so that the data item(s) to be
attribute are not permitted in a represented by the variable may be recorded
fetched procedure unless they are internally. When storage has been
parameters. associated with a variable, the variable is
said to be allocated. Allocation for a
4. With the exception of the standard given variable may take place statically.

10 OS PL/I eXT AND OPr LRM PART I

that is, before the execution of the recursive invocation, and ·popped up· at
program, or dynamically, during execution. the termination of that invocation. Note
A variable that is allocated statically that a label constant in the current block
remains allocated for the duration of the always contains information identifying the
program. A variable that is allocated current invocation of the block that
dynamically will relinquish its storage contains the label. Consider the following
either upon the termination of the block example:
containing that variable or at the request
of the programmer, depending upon its RECURS: PROCEDURE RECURSIVE;
storage class. DECLARE X STATIC EXTERNAL INITIAL (0);
The manner in which storage is allocated
for a variable is determined by the storage
class of that variable. There are four X=X+I;
storage classes: static, automatic, PUT DATA (X) :
controlled, and based. Each storage class IF X=5 THEN GO TO LAB:
is specified by its corresponding storage CALL AGN;
class attribute: STATIC, AUTOMATIC, X=X-I;
CONTROLLED, and BASED, respectively. The PUT DATA (X) ;
last three define dynamic storage
allocation.
Storage class attributes may be declared LAB: END RECURS;
explicitly for element, array, and major
structure variables. If a variable is an AGN: PROCEDURE RECURSIVE;
array or a major structure variable, the DECLARE X STATIC EXTERNAL INITIAL (0);
storage class declared for that variable
applies to all of the elements in the array
or structure.
X=X+I:
All variables that have not been PUT DATA (X) ;
explicitly declared with a storage class
attribute are given the AUTOMATIC
attribute, with one exception: any
variable that has the EXTERNAL attribute is CALL RECURS;
given the STATIC attribute. X=X-I;
PUT DATA (X) ;
Chapter 8, ·Storage Control· discusses END AGN:
how the various storage classes may be
used. In the above example, RECURS and AGN are
both recursive procedures. Since X is
static and has the INITIAL attribute, it is
allocated and initialized before execution
Reactivation of an Active Procedure of the program begins.
(Recursion) The first time that RECURS is invoked, X
is incremented by I and X=l is transmitted
An active procedure that can be reactivated by the PUT statement. Since X is less than
from within itself or from within another 5, AGN is invoked. In AGN, X is
active procedure is said to be a recursive incremented by I and X=2 is transmitted
procedure: such reactivation is called (also by a PUT statement). AGN then
recursion. reinvokes RECURS.
A procedure can be invoked recursive~y This second invocation of RECURS is a
only if the RECURSIVE option has been recursive invocation, because RECURS is
specified in its PROCEDURE statement. This still active. X is incremented as before,
option also applies to the names of any and then X=3 is transmitted. X is still
secondary entry points that the procedure ~ess than 5, so AGN is invoked again.
might have. SinceAGN is active when invoked, tbis
invocation of AGN is also recursive. X is
The environment (that is, values of incremented once again, X=4 is tranSmitted,
automatic variables, etc.) of every and RECURS is invoked for the third time.
invocation of a recursive procedure is
preserved in a manner analogous to the The third invocation of RECURS results
stacking of allocations of a contro~~ed in the transmission of X=5. But, since X
variable (see chapter 8, ·Storage is no longer less than 5, GO TO LAB is
Allocation·). An environment can thus be executed, and then RECURS is terminated.
thought of as being ·pushed down· at a However, only the third invocation of

Chapter 6: Program Organization 71

RECURS is terminated, with the result that can reach the first executable statement in
control returns to the procedure that the block. This set of activities is
invoked RECURS for the third time; that is, called a prologue. Similarly, when a block
control returns to the statement following is terminated, certain activities must be
CALL RECURS in the second invocation of performed before control can be transferred
AGN. At this point X is decremented by 1 out of the block; this set of activities is
and X=4 is transmitted. Then the second called an epilogue.
invocation of AGN is terminated, and
control returns to the procedure that Prologues and epilogues are the
invoked AGN for the second time; that is, responsibility of the compiler and not of
control returns to the statement following the programmer. They are discussed here
CALL AGN in the second invocation of because knowledge of them may assist the
RECURS. Here X is decremented again and programmer in improving the performance of
X=3 is transmitted, after which the second his program.
invocation of RECURS is terminated and
control returns to the first invocation of
AGN. X is decremented again, X=2 is
transmitted, the first invocation of AGN is PROLOGUES
terminated, and control returns to the
first invocation of RECURS. X is
decremented, X=l is transmitted, and the A prologue is code that is executed as the
first invocation of RECURS is terminated. first step in the activation of a block.
control then returns to the procedure that In general, activities performed by a
invoked RECURS in the first place. prologue are as follows:
Note that if a label constant is • computing dimension bounds and string
assigned to a label variable in a lengths for automatic and DEFINED
particular invocation, a GO TO statement variables.
naming that variable in another invocation
would restore the environment that existed
when the assignment was performed. • Allocating storage for automatic
variables and initialization, if
Note also that the environment of a specified.
procedure invoked from within a recursive
procedure by means of an entry variable is • Determining which currently active
the one that was current when the entry blocks are known to the procedure, so
constant was aSSigned to the variable. that the correct generations of
Consider the following example: automatic storage are accessible, and
the correct on-units may be entered.
1=1;
CALL A; /*FIRST INVOCATION OF A*/ • Allocating storage for dummy arguments
A:PROC RECURSIVE; that may be passed from this block.
DECLARE EV ENTRY VARIABLE STATIC;
IF 1=1 THEN DO; The prologue may need to evaluate
1=2; expressions for initial values (including
EV=B; iteration factors), and for array bounds,
CALL A; /*SECOND INVOCATION OF A*/ string lengths, and area sizes.
END;
ELSE CALL EV; /*INVOKES B WITH Note that errors may occur during the
ENVIRONMENT OF FIRST prologue, and the ERR9R condition (or other
INVOCATION OF A*/ exceptional condition) may be raised. If
B:PROC; this happens, the environment of the block
GO TO OUT; may be incomplete, in particular some
END; automatic variables may not yet be
OUT:END A; allocated. Statements executed after the
ERROR condition has been raised should not,
The GO TO statement in the procedure B will therefore, reference AUTOMATIC variables
transfer control to the END A; statement in declared in that block. PUT ALL and PUT
the first invocation of A, and will thus DATA statements in on-units established
termi-nite B and ~ invocations of A. prior to block entry, or entered at the
terminal, imply reference to automatic
variables in all active blocks and are
particularly vuLnerable to this situation.
Prologues and Epilogues The results of referring to unallocated
storage are unpredictable.
Each time a block is activated, certain For each block in the program, the
activities must be performed before control optimizing compiler aSSigns these values in

72 OS PL/I CKT AND OPT LRM PART I

the following order: example, the following declaration is
invalid:
1. Values that are independent of other
declarations in the block. (Values DCL A(B(l», B(A(l»;
may be inherited from an outer block.)
Note that interdependency can occur with
2. Values that are dependent On other more than two data items. For example, the
declarations in the block. If a value following declaration is also invalid:
depends on more than one other
declaration in the block, correct DCL A(B(l», B(C(l», C(A(l»;
initialization is not guaranteed. For
example:
DCL I INIT(lO), J INIT(I), K INIT(J);
EPILOGUES
Correct initialization of K is not
guaranteed.
An epilogue is code that is executed as the
The checkout compiler has no restriction final step in the termination of a block.
on the number of dependencies; it evaluates In general, the activities performed by an
the expressions in the order required by epilogue are as follows:
the dependencies (provided the dependencies
can be determined from inspection of the • Re-establishing the on-unit environment
DECLARE statement alone.) existing before the block was activated.
Note that declarations of data items • Releasing storage for all automatic
must not be mutually interdependent. For variables allocated in the block.

Chapter 6: Program organization 73

 Chapter 7: Recognition of Names

A PL/I program consists of a collection of In order to understand the rules for the
identifiers, constants, and special scope of a name, it is necessary to
characters used as operators or delimiters. understand the terms "contained in" and
Identifiers themselves may be either "internal to."
keywords or names with a meaning specified
by the programmer. The PL/I language is Contained In:
constructed so that the compiler can
determine from context whether or not an All of the text of a block, from the
identifier is a keyword, so there is no PROCEDURE or BEGIN statement through
list of reserved words that must not be the corresponding END statement, is
used for programmer-defined names. (Though said to be contained in that block.
the uses of the 48-character set composite Note, however, that the labels of the
symbols, and, under the checkout compiler, BEGIN or PROCEDURE statement heading
of the file SYSPRINT, are restricted.) Any the block, as well as the labels of
identifier may he used as a name; the only any ENTRY statements that apply to the
restriction is that at any point in a block, are not contained in that
program a name can have one and only one block. Nested blocks are contained in
meaning. For example, the same name cannot the block in which they appear.
be used for both a file and a floating-
point variable. Internal To:

Text that is contained in a block, but

Note: The above is true so long as the 60- not contained in any other block
character set is used. Certain identifiers nested within it, is said to be
of the 48-character set cannot be used as internal to that block. Note that
programmer-defined identifiers in a program entry names of a procedure (and labels
written using the 48-character set;' these of a BEGIN statement) are not
identifiers are: GT, GE, NE, LT, NG, LE, contained in that block.
NL, CAT, OR, AND, NOT, and PT. Consequently, they are internal to the
containing block. Entry names of an
It is not necessary, however, for a name external procedure are treated as if
to have the same meaning throughout a they were external to the external
program. A name declared within a block procedure.
has a meaning only within that block.
outside the block i t is unknown unless the In addition to these terms, the
same name has also been declared in the different types of declaration are
outer block. In this case, the name in the important. The three different types
outer block refers to a different data explicit declaration, contextual
item. This enables programmers to specify declaration, and implicit declaration
local definitions and, hence, to write are discussed in the tollowing sections.
procedures or begin blocks without knowing
all the names being used by other
programmers writing other parts of the
program. Explicit Declaration
Since it is possible for a name to have
more than one meaning, it is important to A name is explicitly declared if it
define which part of the program a appears:
particular meaning applies to. In PL/I a
name is given attributes and a meaning by a 1. In a DECLARE statement.
declaration (not necessarily explicit).
The part of the program for which the 2. In a parameter list.
meaning applies is called the scope of the
declaration of that name. In most cases, 3. As a statement label.
the scope of a name is determined entirely
by the position at which the name is 4. As a label of a PROCEDURE or ENTRY
declared within the program (or assumed to statement.
be declared if the declaration is not
explicit). There are cases in which more The appearance of a name in a parameter
than one generation of data may exist with list is the same as if a DECLARE statement
the same name (such as in recursion); such for that name appeared immediately
cases are considered separately. following the PROCEDURE or ENTRY statement

Chapter 1: Recognition of Names 15

in which the parameter list occurs (though contextually in the following cases:
the same name may also appear in a DECLARE
statement internal to the same block). 1. A name that appears in a CALL
statement, in a CALL option, or
The appearance of a name as the label of followed by an argument list is given
either a PROCEDURE or ENTRY statement the BUILTIN and INTERNAL attributes.
constitutes a declaration within the Built-in functions and pseudovariables
procedure containing the one to which i t without arguments, such as ONCHAR,
refers. ONSOURCE, DATE and DATAFIELD, should
be declared explicitly with the
The appearance of a label prefix on a BUILTIN attribute, contextually using
statement constitutes explicit declaration a null argument list, for example,
of the label. ONCHAR(), or implicitly by using a
DEFAULT statement, for example,

DEFAULT RANGE (ON,DAT) BUILTIN;

SCOPE OF AN EXPLICIT DECLARATION
2. A name that appears in a FILE or COpy
option, or a name that appears in an
The scope of an explici't declaration of a ON, SIGNAL, or REVERT statement for a
name is that block to which the declaration condition that requires a file name,
is internal, including all contained blocks is given the FILE attribute.
except those blocks (and any blocks
contained within them) to which another 3. A name that appears in an ON
explicit declaration of the same identifier CONDITION, SIGNAL CONDITION, or REVER'],
is internal. CONDITION statement is recognized as a
programmer-defined condition name.
For example:
4. A name that appears in an EVENT option
P A B B' C C' D Q R or in a WAIT statement is given the
P: PROCEDURE;

DECLARE A, B: ] 5.
EVENT attribute.

A name that appears in a TASK option

is given the TASK attribute.
Q: PROCEDURE;

DECLARE B, C; ] 6• A name that appears in the BASED

attribute, in a SET option, or on the
left-hand side o~ a pointer
R: PROCEDURE; qualification symbol is given the
POINTER attribute.
DECLARE C,D;

END Ri

END Q: ]
11 7. A name that appears in an IN option,
or in the OFFSET attribute, is given
the AREA attribute.

Examples of contextual declaration are:

END P: ]
READ FILE (PREQ> INTO (Q);
The lines to the right indicate the
scope of the names. Band B' indicate the ALLOCATE X IN (S);
two distinct uses of the name B: C and C'
indicate the two uses of the name C. In these statements, PREQ is given the FILE
attribute, and S is given the AREA
attribute.

Contextual Declaration
SCOPE OF A CONTEXTUAL DECLARATION
When a name appears in certain contexts,
some of its attributes can be determined
without explicit declaration. In such a The scope of a contextual declaration is
case, if the appearance of a name does not determined as if the declaration were made
lie within the scope of an explicit in a DECLARE statement immediately
declaration for the same name, the name is following the PROCEDURE statement of the
said to be contextually declared. external procedure in which the name
appears.
A name that has not been declared
explicitly will be recognized and declared Note that contextual declaration has the

76 OS PL/I CKT AND OPT LRM PART I

same effect as if the name were declared in Examples of Declarations
the external procedure, even when the
statement that causes the contextual
declarations is internal to a block (called Scopes of data declarations are illustrated
B, for example) that is contained in the in figure 7.1. The brackets to the left
external procedure. Consequently, the name indicate the block structure; the brackets
is known throughout the entire external to the right show the scope of each
procedure, except for any blocks in which declaration of a name. In the diagram, the
the name is explicitly declared. It is as scopes of the two declarations of Q and R
if block B has inherited the declaration are shown as Q and Q' and Rand R'.
from the containing external procedure.
P is declared in the block A and known
Since a contextual declaration cannot throughout A since it is not redeclared.
exist within the scope of an explicit
declaration, it is impossible for the Q is declared in A, and redeclared in B.
context of a name to add to the attributes The scope of the first declaration is all
established for that name in an explicit of A except Bi the scope of the second
declaration. For example, the following declaration is block B only.
procedure is invalid:
R is declared in block C, but a
P: PROC (F); reference to R is also made in block B.
The reference to R in block B results in an
implicit declaration of R in A, the
external procedure. Two separate names
READ FILECF) INTO(X); with different scopes exist, therefore.
The scope of the explicitly declared R is
C; the scope of the implicitly declared R
is all of A except block C.
END P;
I is referred to in block C. This
The identifier F is in a parameter list and results in an implicit declaration in the
is, therefore, explicitly declared. The external procedure A. As a result, this
standard default attributes REAL DECIMAL declaration applies to all of A, including
FLOAT conflict with the attributes that the contained procedures B, C, and D.
would normally be given to F by its
appearance in the FILE option. Such use of S is explicitly declared in procedure D
the identifier is in error. and is known only within D.

scopes of entry constant and statemen~

label declarations are illustrated in
figure 7.2. The example shows two external
procedures. The names of these procedures,
Implicit Declaration A and E, are assumed to be explicitly
declared with the EXTERNAL attribute within
the procedures to which they apply. In
If a name appears in a program and is not addition, E is explicitly declared in A as
explicitly or contextually declared, it is an external entry constant. The explicit
said to be implicitly declared. The scope declaration of E applies throughout block
of an implicit declaration is determined as A. It is not linked to the explicit
if the name were declared in a DECLARE declaration of E that applies throughout
statement immediately following the block E. The scope of the name E is all of
PROCEDURE statement of the external block A and all of block E. The scope of
procedure in which the name is used. A the name A is only all of the block A, and
name used only in a contained procedure not E.
will be known in the containing procedure.
However, i t could appear in an external
Unless the DEFAULT statement causes entry declaration in E, which would then
programmer-defined defaults to override the result in the scope ot A being all of A and
standard defaults, an implicit declaration all of E.
causes standard default attributes to be
applied, depending upon the first letter of The label L1 appears with statements
the name. If the name begins with any of internal to A and to C. Two separate
the letters I through N it is given the declarations are therefore established; the
attributes REAL FIXED BINARY (15,0). If first applies to all of block A except
the name begins with any other letter block C, the second applies to block C
including one of the alphabetic extenders only. Therefore, when the GO TO statement
$, #, or i, it is given the attributes REAL in block B is executed, control is
FLOAT DECIMAL (6). transferred to L1 in block A, and block B

Chapter 7: Recognition of Names 77

 A: PROCEDURE;
DECLARE P, Q:
B: PROCEDURE:
DECLARE Q:
] Q' i
r---------------------------------------------------------------------------------------,
P R' S I

R = Q:
C: BEGIN:

[ DECLARE R:
DO I = 1 TO 10:
ENDi
END Ci
END B:
1
]
D: PROCEDURE: ]
DECLARE S;
[ END D:
END A: 1
L---------------------------------------------------------------------------------------J
Figure 1.1. Scopes of data declarations

r---------------------------------------------------------------------------------------,
L1 L1' L2 ABC D E
A: PROCEDURE:
DECLARE E ENTRY:
L1: P = Qi
B: PROCEDURE:
L2: CALL C:
C: PROCEDURE:

[ L1: X=Yi

GO TO L1:
CALL E;
END C:

END Bi
D:
[ PROCEDURE:
END D:

rE:
CALL Bi
END Ai
PROCEDURE:
1 ]
L END Ei
L---------------------------------------------------------------------------------------J
Figure 1.2. scopes of entry and label declarations

is terminated. INTERNAL and EXTERNAL Attributes

D and B are explicitly declared in block The scope of a name with the INTERNAL
A and can be referred to anywhere within Ai attribute is the same as the scope of its
but since they are INTERNAL, they cannot be declaration. Any other explicit
referred to in block E (unless passed as an declaration of that name refers to a new
argument to E). object with a different, non-overlapping
scope.

A name with the EXTERNAL attribute may

be declared more than once in the same
C is explicitly declared in B and can be program, either in different external
referred to from within B, but not from procedures or within blocks contained in
outside B. external procedures. Each declaration of
the name establishes a scope. These
declarations are linked together and,
L2 is declared in B and can be referred within a program, all declarations of the
to in block B, including C, which is same identifier with the EXTERNAL attribute
contained in B, but not from outside B. refer to the same name. The scope of the

78 OS PL/I CKT AND OPT LRM PART I

name is the sum of the scopes of all the OUT: PROCEDURE (R);
declarations of that name within the DECLARE R LABEL,
program. (M,L) STATIC INTERNAL
INITIAL (0),
S BINARY FIXED EXTERNAL,
Z FIXED DECIMAL(l);
M M+l; S=O;
Note: External names of PL/I data cannot IF M<L THEN STOP; ELSE GO TO R;
be more than seven characters long and must SET: ENTRY (Z);
not contain the (break) character. This L=Z;
restriction on the break character is a job RETURN;
scheduler restriction. If a PL/I procedure END OUT;
name, containing a break character, is
invoked by an EXEC statement, the job
scheduler will produce a diagnostic A is an external procedure name; its
message. A similar problem occurs with scope is all of block A, plus any other
PL/I file names in a DO statement. blocks where A is declared as external.

S is explicitly declared in block A and

block C. The character string declaration
applies to all of block A except block C;
Since these declarations all refer to the fixed binary declaration applies only
the same thing, they must all result in the within block C. Notice that although D is
same set of attributes. It may be called from within block C, the reference
impossible for the compiler to check all to S in the PUT statement in D is to the
declarations, particularly if the names are character string S, and not to the S
declared in different procedures, so care declared in block C.
should be taken to ensure that different
declarations of the same name with the N appears as a parameter in block D, but
EXTERNAL attribute do have matching is also used outside the block. Its
attributes. The attribute listing, which apearance as a parameter establishes an
is available as optional output from these explicit declaration of N within D since
compilers, helps to check the use of names. there is no other declaration Of N within
The following example illustrates the above D; the references outside D cause an
points in a program: impliCit declaration of N in block A.
These two declarations of the name N refer
to different Objects, although in this
case, the objects have the same data
attributes, which are, by standard default,
A: PROCEDURE; FIXED (15,0), BINARY, and INTERNAL.
DECLARE S CHARACTER (20);
DCL SET ENTRY(FIXED DEClMAL(l», X and Yare known throughout B and could
OUT ENTRY(LABEL); be referred to in block C or D within B,
CALL SET (3); but not ~n that part of A outside B.
E: GET LIST (S,M,N);
B: BEGIN; P and Q are parameters, and therefore if
DECLARE X(M,N), Y(M)i there were no other declaration of these
GET LIST (X,Y); names within the block, their appearance in
CALL C(X,Y); the parameter list would be sufficient to
C: PROCEDURE (P,Q); constitute an explicit declaration.
DECLARE P( ••• ), Q(.), However, a separate DECLARE statement is
S BINARY FIXED EXTERNAL; required in order to specify that P and Q
S = 0; are arrays and it is this that is the
DO I = 1 TO M; explicit declaration. Note that although
IF SUM (P(I,.» = Q(I) the arguments X and Yare declared as
THEN GO TO B; arrays and are known in block C, it is
S = S+l; still necessary to declare P and Q in a
IF S = 3 THEN CALL OUT (E); DECLARE statement to establish that they,
CALL 0(1); too, are arrays. (The asterisk notation
B: END; indicates that the bounds of the parameters
END C; are the same as the bounds of the
D: PROCEDURE (N); arguments. )
PUT LIST ('ERROR IN ROW "
N, 'TABLE NAME " S); I and M are not explicitly declared in
END 0; the external procedure Ai they are
END B; therefore impliCitly declared and are known
GO TO Ei throughout A, even though I appears only
END A; within block C.

Chapter 1: Recognition of Names 19

 The second external procedure in the attribute. However, a reference to a
example has two entry names, SET and OUT. member of an external structure, using the
These are considered to be explicitly member name known to the block containing
declared with the ENTRY and EXTERNAL the reference, is effectively a reference
attributes. They must also be declared to that member in all blocks in which the
explicitly with the ENTRY attribute in external name is known, regardless of
procedure A. Since ENTRY implies EXTERNAL, whether the corresponding member names are
the two entry constants SET and OUT are identical. For example:
known throughout the two external
procedures. PROCA: PROCEDURE:
DECLARE 1 A EXTERNAL,
The label B appears twice in the 2 B,
program, once as the label of a begin 2 C:
block, which is an explicit declaration, as
a label in A. It is redeclared as a label
within block C by its appearance as a
prefix to the END statement. The reference END PROCA:
to B in the GO TO statement within block C
therefore refers to the label of the END PROCB: PROCEDURE;
statement within block c. Outside block C, DECLARE 1 A EXTERNAL,
any reference to B would be to the label of 2 B,
the begin block. 2 D;

Note that C and D can be called from any

point within B but not from that part of A
outside B, nor from another external END PROCB;
procedure. Similarly, since E is known
throughout the external procedure A, a In this example, if A.B is changed in
transfer to E may be made from any point PROCA, it is also changed for PROCB, and
within A. The label B within block C, vice versa: if A.C is changed in PROCA, A.D
however, can only be referred to from is changed for PROCB, and vice versa.
within C. Transfers out of a block by a GO
TO statement can be made; but such
transfers into a nested block generally
cannot. An exception is shown in the Multiple Declarations and Ambiguous
external procedure OUT, where the label E References
from block A is passed as an argument to
the label parameter R.
Two or more declarations of the same
The statement GO TO R causes control to identifier internal to the same block
pass to the label E, even though E is constitute a multiple declaration, unless
declared within A, and not known within at least one of the identifiers is declared
OUT. within a structure in such a way that name
qualification can be used to make the names
The variables M and L are declared unique.
within the block OUT to be STATIC; their
values are preserved between calls to OUT. Two or more declarations anywhere in a
program of the same identifier as EXTERNAL
In order to identify the S in the names with different attributes constitute
procedure OUT as the same S in the a multiple declaration.
procedure C, both have been declared with
the attribute EXTERNAL. Multiple declarations are in error.

A name need have only enough

qualification to make the name unique.
scope of Member Names of External Reference to a name is always taken to
Structures apply to the identifier declared in the
innermost block containing the reference.
An ambiguous reference is a name with
When a major structure name is declared insufficient qualification to make the name
with the EXTERNAL attribute in more than unique.
one block, the attributes of the
corresponding structure members must be the The following examples illustrate both
same in each case, although the mUltiple declarations and ambiguous
corresponding member ~ need not be references:
identical. Names of members of structures
always have the INTERNAL attribute, and DECLARE 1 A, 2 C, 2 D, 3 E;
cannot be declared with any scope BEGIN:

80 OS PL/I CKT AND OPT LRM PART I

 DECLARE 1 A, 2 B, 3 C, 3 E; PROCESSES IN THE APPLICATION OF
A.C = D.E; ATTRIBUTES
In this example, A.C refers to C in the
inner block; D.E refers to E in the outer Attribute processing by the compiler takes
block. place in the following order:
DECLARE 1 A, 2 B, 2 B, 2 C, 3 D, 2 D; 1. Defactoring of attributes.
In this example, B has been multiply 2. Application of the LIKE attribute.
declared. A.D refers to the second D,
since A.D is a complete qualification of 3. Application of ALIGNED or UNALIGNED
only the second D; the first D would have attributes to structure members.
to be referred to as A.C.D.
q. Establishment and application of
DECLARE 1 A, 2 B, 3 C, 2 D, 3 C; explicit declarations.
In this example, A.C is ambiguous because 5. Establishment and application of
neither C is completely qualified by this contextual declarations.
reference.
6. Establishment of implicit
DECLARE 1 A, 2 A, 3 A: declarations.
In this example, A refers to the first A, 7. Application of attributes specified in
A.A refers to the second A, and A.A.A the DEFAULT statements (if present),
refers to the third A. for explicitly, contextually, and
implicitly declared identifiers; then
DECLARE X; application of standard default
attributes.
DECLARE 1 Y, 2 X, 3 Z, 3 A,
2 Y, 3 Z, 3 A; 8. Resolution of identical identifiers,
including identifiers used in
In this example, X refers to the first attributes, or declared in different
DECLARE statement. A reference to Y.Z is blocks of a procedure.
ambiguous; Y.Y.Z refers to the second Z;
and Y.X.Z refers to the first Z. From this it should be seen that
attributes applied by default cannot
override attributes of the same class
applied to an identifier by explicit or
contextual declaration. Further, any
attributes applied by default are largely
dependent on attributes already applied.
This is fundamental to understanding the
Default Attributes use of the DEFAULT statement.

Every identifier in a PL/I source program

requires a complete set of attributes.
However, the attributes specified in a
DECLARE statement need rarely be the
complete set of attributes for the
identifier. Moreover, contextual
declaration can resUlt in only a partial APPLICATION OF STANDARD DEFAULTS
declaration of an identifier. For each
partially declared identifier the set of
attributes is completed implicitly by the Standard default rules are applied for a
compiler by application of default rules. class of a~tributes when an attribute of a
particular class, such as scope, scale,
Default rules which are determined for base, or mode, etc., has not been applied
the implementations are termed standard either by explicit or contextual
default rules: alternative default rules declaration. A summary of the standard
can be defined by the programmer who wishes defaults for file attributes appears in
either to modify the standard default chapter 10, -Input and output.- A summary
rules, or develop a completely new set of of standard default assumptions for both
default rules. The DEFAULT statement is problem and program control data are given
used for this purpose. Its use is below. A complete description of standard
described in a later section of this default assumptions is given in section I,
chapter. -Attributes.-

Chapter 7: Recognition of Names 81

Problem Data Default
Initial attributes
letter assumed

$,#,',A - H REAL FLOAT DECIMAL

If the problem data is not known to be
either of character or of arithmetic type, I - N REAL FIXED BINARY
arithmetic type is assumed.
o - Z REAL FLOAT DECIMAL

Arithmetic Data: The standard defaults A value returned from a function

vary according to the information specified reference can have default rules applied to
for the data: determine its base, scale, and mode.
Default attributes for a returned value are
obtained by applying default rules to the
1. If an arithmetic data item is function name as if it were an arithmetic
partially specified in an explicit identifier.

Precision of arithmetic data: Standard

declaration, the attributes assumed by default precisions for arithmetic data are:
default are:
Attributes Precision
Default
Explicit attributes FIXED BINARY (15,0)
declarations asswned
FIXED DECIMAL (5,0)
BINARY REAL, FLOAT
DECIMAL REAL, FLOAT FLOAT BINARY (21)
FIXED REAL, DECIMAL
FLOAT REAL, DECIMAL FLOAT DECIMAL (6)
REAL FLOAT, DECIMAL
Other attributes of arithmetic data: The
FIXED BINARY REAL assumed attributes are ALIGNED, and
FIXED DECIMAL REAL AUTOMATIC if INTERNAL, or STATIC if
FLOAT BINARY REAL EXTERNAL.
FLOAT DECIMAL REAL
String data: If the length of a character
REAL FIXED DECIMAL or bit string is undefined, a length of 1
REAL FLOAT DECIMAL is assumed. The attributes UNALIGNED, and
REAL BINARY FLOAT AUTOMATIC if INTERNAL, or STATIC if
REAL DECIMAL FLOAT EXTERNAL, are assumed.

Note that if COMPLEX is declared Structures and structure members: Level-

instead of REAL, the attributes are one structures are assumed AUTOMATIC if
the same as for REAL, and are applied INTERNAL, and STATIC if EXTERNAL. Minor
to each of the two parts. structures and structure members cannot be
declared to have storage or scope
attributes.
2. If a base but not a scale is
specified, the scale assumed depends Arrays and data elements: UNALIGNED is
on the presence of a scale factor in assumed for data elements of string or
the precision attribute. If there is picture type. ALIGNED is assumed for all
a scale factor, FIXED is assumed, if other data types. Scope and storage depend
there is not, FLOAT is assumed. on the data type.

For example:

DCL A BINARY(S), Program Control Data

B BINARY(S,2):

The assumed attributes for A are REAL ENTRY: An entry constant declared in a
FLOAT: for B, they are REAL FIXED. DECLARE statement, or as a statement prefix
on a PROCEDURE or ENTRY statement, is
3. If mode, scale, and base are not assumed EXTERNAL. An entry variable is
specified by a DECLARE or DEFAULT assumed INTERNAL.
statement, the attributes assumed
depend on the initial letter of the LABEL, POINTER, OFFSET, AREA, EVENT, TASK:
identifier. Identifiers declared with anyone of these

82 OS PL/I CKT AND OPr LRM PART I

attributes are assumed ALIGNED, and DESCRIPTORS Option: The DESCRIPTORS option
AUTOMATIC if INTERNAL, STATIC if EXTERNAL. specifies that the associated default rules
If the size is not specified for an area are to be applied to non-null parameter
variable, the default size of 1000 bytes is descriptors.
applied.

Attribute Specification: The attribute

specification is a list of attributes from
DEFAULT Statement which selected attributes are applied to
identifiers in the specified range.
Attributes in the list may appear in any
The function of the DEFAULT statement is to order and must be separated by blanks.
give the programmer control over the
default attributes assigned to identifiers.
The DEFAULT statement cannot be used to Only those attributes that are necessary
override the attributes assigned to to complete the declaration of a data item
identifiers by explicit or contextual are taken from the list of attributes. If
declarations. the list does not supply all the required
attributes, then standard default
The DEFAULT statement can be used to attributes are applied. Therefore,
modify the standard default rules or to specification of any attribute that is a
specify a complete set of programmer- standard de~ault is unnecessary. For
defined default rules. It can specify example:
attributes for identifiers whose attribute
sets are not complete after explicit, DEFAULT RANGE(T) POINTER;
implicit, or contextual declaration, for
the descriptors in entry declarations, and This means that any identifier that begins
for the attributes in the RETURNS option of with the letter T is a pointer. The
PROCEDURE and ENTRY statements. Standard complete list of attributes that apply to
default rules can be restored after these identifiers is POINTER, AUTOMATIC,
programmer-defined default rules have been INTERNAL, and ALIGNED.
established in a program.
Attributes that conflict when applied to
A simplified general form of the DEFAULT a data item do not necessarily conflict
statement is as follows: when they appear in an attribute
specification. For example:
DEFAULT
RANGE({identifier} I {letter:letterl l {*})} DEFAULT RANGE(S) BINARY VARYING:
{ DESCRIPTORS
[attribute-specification]; This means that any identifier that begins
with the letter S and is declared
RANGE Option: The RANGE option specifies explicitly with the BIT or CHARACTER
the identifiers to which the associated attribute will receive the VARYING
default rules are to be applied. The range attribute; all others (that are not
can be specified as either two letters declared explicitly or contextually as
separated by a colon, or as a single other than arithmetic data) will receive
identifier. For example, the option: the BINARY attribute.

RANGE (A:J) ••. The VALUE option is used within the

attribute speCification to specify
applies to all identifiers with initial attributes that are represented by a
letters in the range A through J. The decimal integer constant or an expression.
option: These are the attributes length, size, and
precision. For example:
RANGE (ABC) •••
DEFAULT RANGE(*) VALUE(AREA(2000»;
applies to all identifiers with the initial
three letters 'ABC' such as ABC, ABCD, and This statement gives a default size of 2000
ABCDE. to all area variables. The dimension
attribute can be specified directly in an
The RANGE option can also be specified attribute specification provided it appears
as: first in the list.

RANGE (*) Example 1:

whereby all possible initial alphabetic Assume that the following ranges of
characters, from A through Z, and the initial letters are to correspond to the
characters $, ~, and # are specified. attributes given:

Chapter 7: Recognition of Names 83

 Initial letters Attributes required string length, and area size. Other
attributes in the option, such as CHARACTER
A - D REAL FLOAT DECIMAL and FIXED BINARY in the above examples,
merely indicate which attributes the value
E - B REAL FLOAT BINARY is to be associated with. Consider the
following example.
I - N REAL FIXED BINARY
DEFAULT RANGE(I) VALUE(FIXED
o - Z REAL FIXED DECIMAL DEClMAL(8,3»;

The precisions to be assumed are the I = 1;

default precisions for these
implementations. A DEFAULT statement to If it is not declared explicitly, I will be
establish these additional default rules given the standard default attributes FIXED
is: BINARY(15,O). It will ~ be influenced by
the default statement, because this
DEFAULT RANGE(E:B) BINARY, statement specifies only that the default
RANGE(O:Z)FIXED; precision for FIXED DECIMAL identifiers is
to be (8,3).
In this statement additional default
rules for two ranges of initial letters are
specified. The standard default rules for
identifiers with initial letters outside Restoring standard Defaults
the ranges E - Band 0 - Z are unchanged.

Example 2: The following statement:

A DEFAULT statement can specify that all DEFAULT RANGE(*), DESCRIPTORS;

implicitly-declared data has the same
attribute. overrides, for all identifiers, any
programmer-defined default rules
DEFAULT RANGE (*) PICTURE '99999'; established in a containing block. It can
be used to restore standard defaults for
This statement causes all implicitly- contained blocks.
declared identifiers to be assumed numeric
character type with the attributes REAL To restore standard defaults to a
PICTURE '99999'. particular identifier, the keyword SYSTEM
can be specified in its DECLARE statement.
If values other than the standard
defaults are required, the argument of the
VALUE option should always contain an
attribute to qualify the precision, string scope of the DEFAULT Statement
length, or area size for a particular
default attribute. For example:
The scope of a DEFAULT statement is the
a. DEFAULT RANGE (S:T) CHARACTER block in which it is specified, and any
VALUE (CHARACTER (10»; blocks contained in that block, except that
if a DEFAULT statement in a contained block
b. DEFAULT RANGE (*) VALUE (FIXED specifies all or part of the range
BINARY(31),FLOAT DECIMAL(33), specified in a DEFAULT statement in a
FLOAT BINARY(109), FIXED containing block, the statement in the
DECIMAL(lS»; contained block overrides the other for the
range that they have in common. For
The first example specifies that all example:
implicitly-declared identifiers with the
initial letters Sand T are to receive the A: PROC;
default attribute CHARACTER and a default DEFAULT RANGE(A:I) FIXED BINARY;
string length of ten characters. The
second example specifies that all
identifiers of arithmetic type with
undefined precisions will have the B: PROC;
precisions as defined in the argument to DEFAULT RANGE(I) DECIMAL;
the keyword VALUE. (In this instance the
precisions specified are the maximum
precisions permitted.)
END A;
Note that the only attributes which the
VALUE option can influence are precision, In procedure B, DECIMAL overrides BINARY

84 OS PL/I CKT AND OPT LRM PART I

for identifiers beginning with I, and FIXED must therefore match those of the
is not inherited. standard defaults will corresponding arguments.
be applied for alignment, scope, storage
class, mode, and precision.
A DEFAULT statement in an internal block
affects only explicitly declared Programmer-defined Default for the
identifie~s. This is because the scope of RETURNS Option
contextually and implicitly declared
identifiers is determined as if their
declaration were made in a DECLARE The default attributes of implicitly
statement immediately following the declared values returned from function
PROCEDURE statement of the external procedures are dependent on the entry name
procedure in which the name appears. used to invoke the procedure. The DEFAULT
statement can be used to specify such
attributes when the entry name, or the
initial letter of the entry name, is
Factored Default Specification specified in the DEFAULT statement.
For example, the following statements:
A default specification can be factored.
For example, the following statement: DEFAULT RANGE (X) FIXED BINARY;
X PROC(Y);
DEFAULT (RANGE(A:C) FIXED, RANGE(D:F)
FLOAT) DECIMAL; would be interpreted as:
specifies that arithmetic identifiers with X PROC(Y) RETURNS (FIXED BINARY);
the initial letters A to C receive the
attributes FIXED DECIMAL, and those with
the initial letters D to F receive the
attributes FLOAT DECIMAL. Restrictions of the Use of the DEFAULT
Statement

Programmer-defined Defaults for The DEFAULT statement~must not specify the

Parameter Descriptors attributes ENTRY, ENVIRONMENT, RETURNS,
LIKE, VARIABLE, or any file attributes
other than FILE. It cannot be used to
The DEFAULT statement can be used to specify structuring, although structure
specify attributes for parameter elements can have defaults applied
descriptors. The keyword DESCRIPTORS according to a RANGE specification.
designates the list of attributes which
follows it as an attribute specification Although the DEFAULT statement may
for parameter descriptors. For example: specify the dimension attribute for
identifiers that have not been declared
DEFAULT DESCRIPTORS BINARY; explicitly, ~ subscripted identifier would
DCL X ENTRY (FIXED, FLOAT); be contextually declared with the attribute
BUILTIN. Therefore the dimension attribute
the attribute BINARY is added to each can be applied by default only to
parameter descriptor in the list, producing explicitly declared identifiers. For
the equivalent list: example:
(FIXED BINARY, FLOAT BINARY) DEFAULT RANGE (ARRAY) (10,10) FIXED BIN;
DeL ARRAY1, ARRAY2;
The DESCRIPTORS default attributes are
not applied to parameters having null Both ARRAYl and ARRAY2 are explicitly
descriptors, that is, parameters for which declared two-dimensional arrays of 100
no attributes are specified in the elements, each with the attributes FIXED
parameter descriptor, and whose attributes and BINARY.

Chapter 7: Recognition of, Names 85

86 OS PL/I CRT AND OPT LRM PART I
 Chapter 8: Storage Control

The purpose of this chapter is to describe variables during execution •. Programs often
how the PL/I programmer can control the need data that is used whenever the program
allocation of storage. Allocation is the is executed. For example, all arithmetic
process of obtaining storage for a constants specified in a program are stored
variable. A generation of a variable in a manner similar to variables declared
refers to a particular allocation of it. STATIC. The difference is that constants
The four storage classes STATIC, AUTOMATIC, cannot be changed during program execution
CONTROLLED, and BASED allow the programmer whereas the values of static variables can.
to exercise as 'much control as he requires Although static variables can be declared
for a particular program. at any point in a program, they are all
allocated prior to execution. But it is
All variables require storage: this important to note that static variables
applies both to problem data, such as follow normal scope rules for the validity
string and arithmetic variables, and to of references to them. For example:
program control data such as label
variables, entry variables, and file A:PROC OPTIONSCMAIN):
variables. The declaration of a variable
must include a storage class attribute even
if only by default. The name of a variable
is effectively the address of the variable, B:PROC:
and the attributes specified for a variable DECLARE X STATIC INTERNAL:
describe the amount of storage required and
how it is to be interpreted. For example:
DECLARE X FIXED BlNARY(31,O) AUTOMATIC: END B;
END A:
The name X addresses a fullword, i.e., four
bytes, that contains a value to be Although the variable X is allocated
interpreted as a fixed-point binary throughout the program, it can be
integer. For static and automatic referenced only within procedure B or any
variables, this concept is not very block contained in B.
important, but when considering controlled
and, particularly, based variables it is If static variables are initialized
relevant. using the INITIAL attribute, the initial
values must be specified as constants with
It should be understood that at no point the exception of pointer variables as noted
in a PL/I program does the programmer have below. And any specification of extenis,
access to the absolute address of a for instance array bounds, must also be
variable within main storage, because the constants. Thus if static storage is used,
allocation of storage for variables is it must be borne in mind that whatever
managed by the compiler. The programmer allocation has been specified when the
does not specify where in main storage the program was written will be retained
allocation is to be made. He can, however, throughout the execution of the program.
specify where it is to be allocated static storage should be used for all data
relative to storage already. allocated for that may be referred to by the programmer
instance by allocating based variables in at any point in a program~ A STATIC
an area variable. pOinter or offset variable may be
initialized only by using the NULL built-in
The degree of storage control that can function.
be exercised depends on the class of
storage used. All other forms of storage allocation
are dynamic, that is, the storage is
obtained during the execution of the
program. Because. of this, the programmer
Static Storage can exert more control.

Variables declared with the STATIC

attribute are allocated prior to the Automatic Storage
execution of a program and remain allocated
until the program terminates. The program
has no control on the allocation of static Automatic variables are allocated on entry

Chapter 8: storage Control 87

to the block in which they have been EFFECT OF RECURSION ON AUTOMATIC
declared. They can be reallocated many VARIABLES
times during the execution of a program.
The programmer controls their allocation by
his design of the block structure of his A procedure that can be invoked when it is
program. For example: already active in the same task is said to
be recursive. The values of variables
allocated in one activation of such a
A:PROC; procedure must be protected from change by
other activations. This is arranged by
stacking the variables. A stack operates
on a last-in first-out basis; the most
CALL B; recent generation of an automatic variable
B:PROC; is the only one that can be referenced.
DECLARE X, Y AUTO; Note that static variables are not affected
by recursion. Thus they are useful for
communication across recursive invocations.
This also applies to automatic variables
END B; that are declared in a procedure that
contains a recursive procedure and to
controlled and based variables. For
example:
CALL B;
A:PROC;
DCL X;
Each time procedure B is invoked, the
variables X and Yare allocated storage,
and when B terminates the storage is
released; consequently, the values they B:PROC RECURSIVE;
contained are lost. The storage that has DeL Z,
been freed is available for reallocation to Y STATIC;
other variables. Thus, whenever a block CALL B;
(procedure or begin) is active, storage is
allocated for all variables declared
automatic within that block, and whenever a
block is inactive no storage is allocated END B;
for the automatic variables in that block. END A;
Only one allocation of a particular
automatic variable can exist, except for A single generation of the variable X
those procedures that are called exists throughout invocations of procedure
recursively or by more than one task. B. The variable Z will have a different
generation for each invocation of procedure
B. The variable Y can be referred to only
Array bounds, string lengths, and area in procedure B and will not be reallocated
sizes for automatic variables can be at each invocation. (The concept of
specified as expressions. This means not stacking of variables is also of importance
only that storage can be allocated when it in the discussion of controlled variables.)
is required but also. that the required
amount of storage can be allocated. For
example:
Controlled Storage
A:PROC;
DECLARE N FIXED BIN;
Variables declared as CONTROLLED are
allocated only when they are specified in
an ALLOCATE statement. The programmer has
B:PROC; individua1 control over each controlled
DECLARE STR CHAR(N); variable. Effectively, they are
independent of the program block structure,
but not compl ete1y • The scope of a
The character string STR will have a length controlled variable. when declared
defined by the value of the variable N that internal. is the block in which it is
existed when procedure B was invoked. declared anq any contained blocks. The
However, storage is conserved at the declaration of a controlled variable
possible expense of speed of execution describes only how much storage will be
because of the extra operations required to required when the variable.is allocated and
evaluate such expressions. how it is to be interpreted. For example:

88 OS PL/I CRT AND OPT LRM PART I

 A:PROCi ALLOCATE STATEMENT FOR CONTROLLED
DCL x CONTROLLEDi VARIABLES

A controlled variable can be allocated only

CALL Bi by an ALLOCATE statement. The general form
of the ALLOCATE statement for controlled
v.ariables is:
B:PROCi ALLOCATE [level] identifier [dimension
ALLOCATE Xi attribute] [attribute]
[,[level] identifier [dimension
attributel [attribute]] •••
[INITIAL attribute];
END B;
END Ai The "identifier" is any variable that has
the CONTROLLED attribute. It can be an
element. array, or structure, but cannot be
The variable X can be validly referred to subscripted or qualified. Permitted
within procedure B and that part of at~ributes are those that specify
procedure A that follows the CALL dimensions, the length of strings, and the
statement. Any reference to the value of size of areas. (Areas are discussed later
the variable before execution of the CALL in this chapter but in this context they
statement is in error. once a controlled are simply variables whose storage is
variable has been allocated, it remains adjustable.) This enables the programmer
allocated either until a FREE statement to alter the amourit of storage for a
that names the variable is encountered or particular generation of a variable. These
until the end of the program. Note that attributes are:
the scope of a controlled variable may not
be the whole programi this creates a dimension
situation analogous to that for the STATIC CHARACTER (length)
INTERNAL variable described under "Static BIT (length)
Storage- earlier, i.e., it exists but AREA(size)
cannot be referenced.
The dimension attribute can appear with
The FREE statement frees the storage any of the others. For example:
allocated for a controlled variable. The
storage can then be re-used for other DCL X( 20) CHAR (5) CONTROLLED;
allocations.
Generally, controlled variables are
useful when large data aggregates with ALLOCATE X(25) CHAR(6);
adjustable extents are required in a
program. For example:
DCL A(M,N) CTLi
The attribute values specified in an
ALLOCATE statement always override those
given in the DECLARE statement for the same
GET LIST(M,N)i variable. However, the~ttributes
ALLOCATE Ai themselves must agree. Thus the dimens ion
GET LIST(A) i attribute must specify the same number of
dimensions. As in a DECLARE statement,
element expressions can be used to specify
bounds, lengths, and sizes.
FREE Ai
The INITIAL attribute can also be
specified in an ALLOCATE statement.
Initial values given in an ALLOCATE
statement override those, if any, given in
This program sequence allocates the exact a DECLARE statement.
storage.required depending on the input
data and discards the data (and frees its
storage) when no longer required. This
method can be more efficient than the FREE STATEMENT FOR CONTROLLED VARIABLES
alternative of setting up a begin block,
because no prologue or epilogue is
required. Storage for a controlled variable is freed,

Chapter 8: storage Control 89

and therefore its value is lost, when a In the first allocation of X the upper
FREE statement is executed that names the bound is specified by the DECLARE
variable. The form of the FREE statement statement, i.e., 20. In the second
is: allocation the upper bound is specified by
the value of the first element of the first
FREE identifier[,identifier] ••• i generation of X.
rhe "identifier" has the same restrictions
as in the ALLOCATE statement.
If the FREE statement names a variable
that has not been allocated, no action is
taken.
Asterisk Notation

Implicit Freeing If, in an ALLOCATE statement, dimensions,

lengths, or sizes are indicated by
asterisks, values are inherited from the
If a controlled variable is to remain most recent previous generation. For
allocated until the end of a task, it need arrays, the asterisk must be used for every
not be explicitly freed by a FREE dimension of the array, not just one of
statement. All controlled storage is them. For example:
automatically freed at the termination of
the task in which it was allocated. DCL X(10,20) CHAR(S) CTLi

ALLOCATE X;
MULTIPLE GENERATIONS OF CONTROLLED
VARIABLES
ALLOCATE X(10,10);
If storage for a controlled variable is
reallocated before being freed the first
generation is preserved, i.e., stacked.
The second generation becomes the current ALLOCATE X ( • , .) i
generation; the first generation cannot be
directly accessed until the current In this example. the first generation of X
generation has been freed. This is similar has bounds (10,20); the second and third
to the process described for automatic generations have bounds (10,10). The
variables in a recursive procedure. For elements of each generation of X are all
cont~olled variables, however, stacking and character strings of length five.
unstacking of variables occur at ALLOCATE
and FREE statements rather than at block The asterisk notation can also be used
boundaries and are independent of in a DECLARE statement, but has a different
invocation of procedures within a task. meaning. For example:
Although values of successive DCL Y CHAR(.) CTL,
generations of a controlled variable are N FIXED BINi
stacked, values can be obtained from the N=20:
most recent generation to help create a new
generation. If, in an ALLOCATE or DECLARE
statement, a bound, length, or size is
specified by an expression that contains ALLOCATE Yi
references to the vatiabl&, the value is
taken from the most recent previous
generation. For example:
ALLOCATE Y CHAR (N) ;
DCL X(20) FIXED BIN CTL;
This simply means that the length of the
character string Y is to be taken from the
previous generation unless it is specified
ALLOCATE X; in an ALLOCATE statement, in which case Y
is given the specified length. This allows
the programmer to defer the specification
of the string length until the actual
ALLOCATE X(X(l»i allocation of storage.

90 OS PL/I CXT AND OPr LRM PART I

CONTROLLED STRUCTURES Based Storage

When a structure is controlled, any arrays, A based variable is fundamentally different

strings, or areas it contains can be from all other storage classes in that the
adjustable. For this reason, it is name of a based variable does not identify
permissible to describe the relative the location of a generation in main
structuring in an ALLOCATE statement. For storage; a declaration of a based variable
example: is only a description of the generation,
i.e., the amount of storage required and
DCL 1 A CTL, how that storage is to be interpreted. The
2 B(-10:10), location of the generation is identified by
2 C CHAR(*) VARYING; a separate variable called a locator
variable. A locator variable is either a
pOinter variable or an offset variable.
Offset variables are discussed later in
ALLOCATE 1 A, this chapter in conjunction with area
2 B, variables.
2 C CHAR(S);
Although a declaration for a controlled
variable is also only a description of the
storage, once an ALLOCATE statement has
FREE A; been executed for the variable, its name
also identifies the location of the
When the structure is allocated, A.B has variable. For this reason, it is
the extent -10 to +10 and A.C is a VARYING impossible to refer to more than one
character string with maximum length 5 and generation of a controlled variable at a
the value null. When the structure is particular point in a program. In fac~,
freed, only the major structure name is the ALLOCATE statement can also be used for
given. All of a controlled structure must a based variable, but because the location
be freed or allocated; it is an error to of any generation is identified by an
attempt to obtain storage for part of a independent locator variable, it is
structure. possible to refer at any point in a program
to any generation of a based variable by
using an appropriate locator value.

BASED VARIABLES
ALLOCATION BUILT-IN FUNCTION
A declaration of a based variable has the
Where the allocation and freeing of a keyword BASED and, optionally, the name of
variable depend on flow of control, it is a locator variable that can be assumed to
useful to be able to determine if the be associated with the based variable. For
variable has been allocated. The example:
ALLOCATION built-in function returns a
binary integer value indicating the number DeL x FIXED BIN BASED(P);
of generations that can be accessed in the
current task for a given controlled For this declaration the value of the
variable. If the variable is not variable P will identify the location of
allocated, the value zero is returned. The the variable X, except when the reference
function reference has the form: is otherwise explicitly qualified, as
described below.
ALLOCATION (a)
The association of a pointer variable in
where a must be a controlled variable. this way is not a special relationship. P
can be used to identify locations of other
Besides the ALLOCATION built-in based variables and other locators can be
function, other built-in functions that may used to identify other generations of the
be useful are the array-handling functions variable X.
DIM, which determines the extent of a
specified dimension of an array, and LBOUND
and HBOUND, which determine the lower and
upper bound respectively of a specified LOCATOR QUALIFICATION
dimension of a given array. Similarly for
strings, the built-in function LENGTH,
returns the current length of the string. Because a reference to the value of a based

Chapter 8: Storage Control 91

variable consists of two parts, it is a statement. It can also be declared
q~alified reference and to distinguish this explicitly as in the following example:
from a reference to a member of a
structure, it is called a locator-qualified DeL Q POINTER;
reference. The composite symbol -> (a
minus sign immediately followed by a Because Q is a variable i t must have a
greater than sign) represents 'qualified storage class; in this case, AUTOMATIC is
by' or 'points to'. For example: applied by default. Note that a pOinter
variable is a program control variable and
P -> X therefore cannot be manipulated in the same
way as arithmetic values. Pointer
X must be a based variable and P must be a variables can be collected in arrays and
locator expression. The reference means: structures.
that generation of X identified by the
value of the locator P. X is said to be
explicitly locator-qualified.

When a based variable is associated with Pointer Expression

a locator variable in a declaration, the
programmer need specify only the name of
the based variable in a reference. For A pOinter expression is either a pOinter
example: variable, which can be qualified or
subscripted, or a function reference that
DCL X FIXED BIN BASED{P); returns a pOinter value.

A pointer expression can be used in the

following ways:
ALLOCATE X;
1. As a locator qualifier, in association
with a declaration of a based
variable.
X X + 1;
2. In a comparison operation, for example
The ALLOCATE statement sets a value in in a IF statement (pointer values can
the pointer variable P so that the be compared whether equal or not
reference X applies to allocated storage. equal) •
The references to X in the assignment
statement are implicitly locator-qualified 3. As an argument in a procedure
by P. References are explicitly locator- reference.
qualified as follows:

Q->X = Q->X + 1~
Setting Pointer Variables
This assignment statement has the same
,~
effect as that of the previous example. A
based variable can be declared without Before a reference is made to a pointer-
naming a pointer variable; in this case any qualified variable, the pOinter must have a
reference to the based v~riable must always value. A pointer value is obtained from
be explicitly locator-qualified. any of the following:

(Note that PL/I allOWS a more general 1. The NULL built-in function.
form of locator qualification than is
described here; see "Multip1e Locator 2. The ADDR built-in function.
Qualification" at the end of this chapter.
However, the general form is not essential 3. A READ or LOCATE statement.
to an understanding of the remainder of
this chapter.) 4. An ALLOCATE statement.

All pOinter values are originally derived

from one of these three methods. Such
POINTER VARIABLES values can then be manipulated by
assignment that copies a pOinter value to a
pOinter variable: by locator conversion
A pointer variable is declared contextually that converts an offset value to a pOinter
if i t appears in the declaration of a based value, or vice versa; by passing the
variable, if i t appears as a locator pOinter value as an argument in a procedure
qualifier, or if it appears in the SET reference; and by returning a painter value
option of an ALLOCATE, LOCATE, or READ from a function procedure.

92 OS PL/I CKT AND OPT LRM PART I

ADDR BUILT-IN FUNCTION will be detected only when running
under the checkout compiler with the
NOCOMPATIBLE option.
The ADDR built-in function returns a
pOinter value that identifies the first The ADDR built-in function does not
byte of a variable. The variable can have supply any information on the organization
any data type or organization and any of a variable. Therefore, if the variable
storage class. For example: is an aggregate, it should be in connected
storage if it is to be referenced as an
P = ADDR(X); entity. For example, if the variable is a
cross-section of an array, the elements
where P is a pointer variable and X is any must not be interleaved. Furthermore, in
connected variable. The argument to the this implementation, if the variable is a
built-in function can be a subscripted varying-length string or an area, control
qualified reference. For example: information is an integral part of the
variable. A varying-length string is
DCL A(3,2) CHARACTER(S) BASED(P), prefixed by a two-byte length field, and an
B CHAR(S) BASED(Q), area is prefixed by 16 bytes of control
C(3,2) CHARACTER(S); intormation. Thus if the ADDR function is
performed on these types of variable, the
pOinter value identifies the start of the
control information.
P = ADDR(C);
Q ADDR(A(2,1»; Other rules that apply to the use of the
ADDR function are given in section G,
In this example, the arrays A and C refer "Built-in Functions".
to the same storage. The elements Band
C(2,1} also refer to the same storage.

Notice that when a based variable is BASED VARIABLES AND INPUT/OUTPUT

overlaid in this way no new storage is
allocated - the based variable uses the
same storage as the variable on which it is Based variables can be transmitted using
overlaid (A(3,2) in the example). either stream-oriented or record-oriented
transmission.
This overlay technique can be achieved
by use of the DEFINED attribute, but an In the list-directed form of stream-
important difference is that for DEFINED oriented transmission, provided the based
the overlay is permanent. When based variables are locator-qualified (implici~ly
variables are overlaid, the association can or explicitly), they are treated in the
be changed at any time in the program by same way as other types of variable. For
assigning a new value to the pointer example:
variable. Note that although PLII does not
permit the overlay of variables with GET LIST (P->X);
different data types, for example,
overlaying an integer with a bit string or For data-directed transmission, however,
overlaying a character string with a bit only a based variable that has been
string, it is possible in this associated with a locator expression in a
implementation. declaration can be transmitted. For
example:
However, it should be understood that
this type of programming is invalid use of DCL Y BASED(Q), Z BASED;
PL/I, and the following points should be
noted:

1. Unless the length of the bit string is PUT DATA(Y);

a multiple of eight, data in the base
variable may be corrupted when an The variable Z cannot be transmitted in a
assignment is made to the based PUT DATA or GET DATA (that is, data-
variable when running under the directed I/O) statement. Chapter 11
optimizing compiler since this discusses the techniques and facilities of
compiler produces optimum code from stream-oriented transmission.
valid language.
Record-oriented transmission provides
2. Incompatibilities between the two processing modes: move mode, which
attributes of the BASED variable and moves data into or out of an allocated
the attributes of the base variable, generation of a variable either directly or
that is the variable being overlaid, indirectly via a buffer; or, locate mode,

Chapter 8: Storage Control 93

which only moves the data into or out of a FILE (file-expression)
buffer and identifies the storage allocated [SET (element-pointer-variable)]:
within the buffer. Although based
variables can be transmitted using either This statement allocates storage in a
mode, they are designed to be used with buffer for a specified based variable. The
locate mode. Based variables are used in SET option need only be specified if the
locate mode to describe the contents of a based variable has not been associated with
buffer, and therefore allow data to be a pointer variable in a declaration.
processed while i t is in the buffer. Note
that locate mode applies only to BUFFERED The LOCATE statement operates
files: also, the files must be SEQUENTIAL, differently from all other transmission
except for INPUT and UPDATE files statements. Because the statement sets a
associated with key-sequenced VSAM d~ta pOinter to a storage address, there is
sets. Chapter 12, "Record-Oriented nothing to transmit until values have been
Transmission," discusses the two modes more assigned to that storage. The LOCATE
fully. statement transmits the previous record
(i.e., the contents of storage obtained by
a previous LOCATE statement), frees the
storage for that record, and allocates
READ with SET Statement storage for the next record. The current
record is also transmitted if a WRITE or
CLOSE statement is executed for the same
In locate mode, the READ statement has the fi1e. The following example shows the use
form: of the LOCATE statement:

READ FILE(file-expression) DCL 1 STR BASED(P),

SET(element-pointer-variable): 2 NAME CHAR(20),
2 RATE FIXED(5,2):
This statement places a record in a buffer
and identifies its location by setting the
specified pointer variable. Any based OUTPUT:LOCATE STR FILE(OUT):
variable qualified by this pOinter variable
describes the contents of the buffer. For /*ASSIGN VALUES TO STR*/
example:
GO TO OUTPUT:
DCL X CHAR(20) BASED(P),
Y(20) CHAR (1) BASEDCP); Note: Because of the method of operation of
the LOCATE statement, some care is
necessary when using it with device-
READ FILE(IN) SET(P): associated files, where a number of files
are grouped together; no transmission can
take place after anyone of the group has
been closed. (See "Device-associated
In this program segment, a record is read Fi1es," in chapter 12.)
into a buffer and the pOinter variable P
identifies its location. The record in the By using locate mode the programmer can
buffer is treated simultaneously by the specify that a number of different forms of
based variable X as a fixed-length record be held in the same file. For
character string and by the based variable example:
Y as an array of single characters. Note
that P is declared contextually as a DCL 1 STR1 BASED(Q),
pointer variable and that a reference to X 2 CODE CHAR (1 ) ,
or Y is implicitly qualified by P. 2 X CHAR(30).
1 STR2 BASED(Q),
The next I/O operation on the file 2 CODE CHAR(l),
(including closing the file) frees the 2 XeS) FIXED BIN:
buffer.

READ FILE(IN) SET(Q):

LOCATE statement IF STR1.CODE= '2' THEN DO:
I=Q->STR2.X(1):
END;
The LOCATE statement complements the READ
with SET statement and is used for output In this program segment each based
from a buffer. The form is: structure has an element CODE that
identifies the structure. A record is read
LOCATE based-variable and its location is set in Q. Depending on

94 OS PL/I CKT AND OPT LRM PART I

the value of CODE, the record can be that sets P, the bound value is taken from
interpreted as STR1 or STR2. x.
If an element varying-length string is
transmitted using locate mode, the Any number of REFER options may be used
SCALARVARYING option of the ENVIRONMENT in the declaration of a structure provided
attribute must be specified for the file that at least one of the following
(see chapter 12, -Record-Oriented restrictions is satisfied:
Transmission-). The records will include a
two-byte length prefix.
1. All objects of REFER options are
declared at logical level two, that
is, not declared within a minor
SELF-DEFINING DATA (REFER OPTION) structure. For example:

A self-defining record is one which DECLARE 1 STR BASED,

contains information about its own fields, 2 (M,N),
such as the length of a string. A based 2 ARR(I REFER (M),
structure can be declared so that such data J REFER(N»,
can be manipulated. string lengths, array 2 X:
bounds, and area sizes can all be defined
by variables declared within the structure.
When the structure is allocated (by either When this structure is allocated, the
an ALLOCATE statement or a LOCATE values assigned to I and J will set
statement), the value of an expression is the bounds of the two-dimensional
assigned to a variable that defines a array ARR.
leagth, bound, or size. For any other
reference to the structure, the value of
the defining variable is used. 2. The structure is declared so that nO
padding between members Qf the
The REFER option is used in the structure can occur. Section K, -Data
declaration of a based structure to specify Mapping,- describes the rules by which
that, on allocation of the structure, the structures are mapped. For example:
value of an expression is to be assigned to
a variable in the structure and is to
represent the length, bound, or size of DECLARE 1 STR UNALIGNED BASED (P),
another variable in the structure. The 2 B FIXED BINARY,
REFER option has the following general 2 C,
format: 3 D FLOAT DECIMAL,
3 E (I REFER (D»
element-expression REFER CHAR(J REFER (B»,
(element-variable) 2 G FIXED DECIMAL;
The value of the element-expression must be Because this structure has the
capable of being converted to an integer. UNALIGNED attribute, all items require
Any variables used as operands in the only byte alignment. Therefore
expression must not belong to the structure regardless of the values of Band D
c~ntaining the REFER option. (the REFER objects) no padding will
occur. Note that D is declared within
The element-variable, known as the a minor structure.
ggjept of the REFER option, must be the
name of a member of the structure being 3. If the REFER option is used only once
aeclared. It must not be locator-qualified in a structure declaration,
or subscripted and it must precede the restrictions 1 and 2 can be ignored
member it defines. For example: provided that:
DECLARE 1 STR BASED(P), a. For a string length or area Size,
2 X FIXED BINARY, the option is applied to the last
2 Y (L REFER (X», element of the structure.
L FIXED BINARY INITIAL(1000)~
b. For an array bound, the option is
~his 4eclaration specifies that the based applied either to the last element
structure STR will consist of an array Y of the structure or to a minOr
aDd an element X. When STR is allocated, structure that contains the last
the upper bound is set to the current value element. The array bemd must be
of L which is assigned to X. For any other the upper bound of the leading
reference to Y, such as a READ statement dimension. For example:

Chapter 8: storage Control 95

 DCL 1 STR BASED (P), When the value of a refer object has
2 X FIXED BINARY, been changed, the next reference to the
2 Y, structure causes remapping. For example:
3 Z FLOAT DECIMAL,
3 M FIXED DECIMAL, DCL 1 A BASED(P),
2 D (L REFER (M», 2 B,
3 E (50), 2 C (I REFER(B»,
3 F (20); 2 D,
I INIT(10);
Note that the leading dimension of ALLOCATE A;
an array can be inherited from a
higher level. For example, if we
had declared STR(4) in the above
example, the leading dimension B = 5;
would have been inherited from
STR(4) and so it would not have The next reference to A after the
been possible to use the REFER aSSignment to B will cause the structure to
option in D. be remapped to reduce the upper bound of C
from 10 to 5, and to allocate to D storage
This declaration does not satisfy immediately following the new last element
restrictions 1 or 2; the REFER of C. Although the structure is remapped,
object M is declared within a no data is reaSSigned - the contents of the
minor structure and padding will part of storage originally occupied by the
occur. However, restriction 3 is structure A are unchanged. If the
satisfied as the REFER option is programmer does not take account of
applied to a minor structure that remapping, errors can occur. Consider the
contains the last element. following example, in which there are two
REFER options in the one structure:
If the value of the object of a REFER
option varies during the program then: DCL 1 A BASED (P),
2 B FIXED BINARY (15,0),
1. The structure must not be freed until 2 C CHAR (11 REFER (B»,
the object is restored to the value it 2 D FIXED BINARY (15,0),
had when allocated. 2 E CHAR (12 REFER (D»,
(11,12) INIT (10);
2. The structure must not be written out ALLOCATE A;
while the object has a value greater
than the value with which it was
allocated.
B = 5;
3. The structure may be written out when
the object has a value equal to or The mapping of A with the original and new
less than the value it has when values of B is as follows:
allocated. The number of elements,
the string length, or area size
actually written will be that B C D E B=10
indicated by the current value of the
object. For example: B C 0 E B=5
DCL 1 REC BASED (P),
2 N, D now refers to data that was originally
2 A (M REFER(N», part of that assigned to the character-
M INITIAL (100); string variable C. This data will be
interpreted according to the attributes of
D - that is, as a fixed-point decimal
number - and the value obtained will be
ALLOCATE REC; taken to be the length of E. Hence, the
N = 86; length of E is unpredictable.
WRITE FILE (X) FROM (REC);
In this example, 86 elements of REC
are written. It would be an error to LIST PROCESSING
attempt to free REC at this point
since N must be restored to the value
it has when allocated (i.e., 100). If List processing is the name for a number of
N was assigned a value greater than techniques to help manipulate collections
100, an error would occur when the of data. Although arrays and structures in
WRITE statement was encountered. PL/I are also used for manipulating

96 as PL/I CRT AND OPr LRM PART I

collections of data, list processing Both based and controlled variables can
techniques are more flexible in that they be freed in the same statement.
allow collections of data to be
indefinitely reordered and extended during
program execution. It is not the purpose
here to illustrate these techniques but MULTIPLE GENERATIONS OF BASED VARIABLES
simply to show how based variables and
locator variables serve as a basis for this
type of processing. All current generations of a based variable
can be referred to by speqifying
A list that has at least one pointer appropriate pointer variables. In list
within each member that identifies the processing, a number of based variables
location of another member in the list is with many generations can be included in a
called a chained or threaded list. The list. Members of the list are chained
primary application of the ALLOCATE and together by a pOinter in one member
FREE statements is to build these lists. identifying the location of another member.
Note that the allocation of a based
variable cannot specify where in main
storage the variable is to be allocated.
In practice a chain of items may be
ALLOCATE STATEMENT FOR BASED VARIABLES scattered throughout main storage. But by
accessing each pointer the next member is
found. A member of a list is usually a
The form of the ALLOCATE statement is: structure that includes a pOinter variable.
For example:
ALLOCATE based-variable
[IN(area-variable)] DCL 1 STR BASED(H),
[SET(locator-variable)] 2 P POINTER,
[,based-variable 2 DATA,
[IN(area-variable)] T POINTER;
[SET(locator-variable)]] ••• ;
The based variable can be any data type or
organization. The SET option is needed if ALLOCATE STR;
the based variable was declared without an T=H;
associated pointer variable or if it is
required to leave the pointer that w~
declared with the based variable unchanged,
and to set a different pointer to the NEXT:ALLOCATE STR SET(T->P);
generation of the based variable that is T=T->P;
being allocated.
Both based and controlled variables can
be allocated in the same statement. GO TO NEXT;
In this program segment, a list of
structures is created. The structures are
FREE STATEMENT FOR BASED VARIABLES generations of STR and are linked by the
pOinter variable P in each generation. The
independent poin~er variable T identifies
The form of the FREE statement is: the previous generation during the creation
of the list. The first ALLOCATE statement
FREE [locator-qualifier->] sets the pointer H to identify it.
based-variable [IN (area.-variablel 1 Ultimately the pointer H identifies the
[,[locator-qualifier->l start, or head, of the list. The second
based-variable [IN(area-variable)]] ••• ; ALLOCATE statement sets the pointer P in
the previous generation to identify the
A particular generation of a based variable location of this new generation. The
is freed ~ specifying a pOinter qualifier aSSignment statement T=T->P; updates
in the statement. If a qualifier is pOinter T to identify the location of the
omitted, the pointer variable associated new generation.
with the based variable in its declaration
is used; it is an error in this case if a Figure 8.1 shows ·a diagrammatic
pointer variable has not been associated representation of a one-directional chain.
with the based variable.
Note that, unless the value of P in each
A FREE statement cannot be used to free generation is aSSigned to a separate
a locate-mode I/O buffer. pOinter variable for each generation, the

Chapter 8: storage Control 97

 ITEM 1 r-------->ITEM 2 r--------> ITEM 3 r----
r-------------~----, I r------------------, 1 r------------------, 1
1
I Forwards Pointer
1----.1
1
1
1 Forwards Pointer
1----.1
1
I
I Forwards Pointer
1----.1
I
1------------------1 1------------------1 1------------------1
1 I 1 1 I I
1 Data 1 1 1 Data 2 I I Data 3 1
I 1 1 I 1 1
L------------------.1 L------------------J L------------------J
Figure 8.1. Example of one-directional chain

generations of STR can be accessed only in unallocated controlled variable). The

the order in which the list was created. Value of a pOinter variable that no longer
For the above example, the following identifies a generation of a based
statements can be used to access each variable, for example, when a based
generation in turn: variable has been freed, is undefined.

T=H;
NXT: T->DATA=X;
TYPES OF LIST

T=T->P; The foregoing examples showed a Simple list

GO TO NXT; processing technique, the creation of a
unidirectional list. More complex lists
can be formed by adding other painter
variables into the structure. If a second
NULL BUILT-IN FUNCTION pOinter were added, i t could be made to
pOint to the previous generation. The list
would then be bidirectional; from any item
When a list is created in the way in the list, the previous and next items
described, i t is necessary to indicate the could be accessed by using the appropriate
end of the list. The NULL built-in pointer value. Instead of the last pOinter
function returns a pointer value that value being set to the value of NOLL, i t
cannot identify a location in storage. can be set to point to the first item in
Thus by setting the pOinter in the last the list, thus creating a ring or circular
generation in a list to the value of NULL a list.
positive indication of the end of the list
is given. For example: A list need not consist only of
generations of a single based variable.
T=H; Generations of different based structures
NXT: IF T-.=NULL THEN can be included in a list by setting the
DO; appropriate painter values. Items can be
T->DATA=X; added and deleted from a list by
manipulating the values of painters. A
list can be restructured by manipulating
the pOinters, so that the processing of
T=T->P; data in the list may be simplified.
GO TO NXT;
END; By reducing the amount of movement of
data within main storage, the programmer
This program segment can be used ins.tead of can generally achieve· a considerable saving
the previous example to scan the list; it on processing tim~. Note, however, that
. is assumed that the pointer P in the final each painter requires four bytes of storage
generation of STR has -been set to the value and any allocated based variable requires
of NULL. at least eight bytes of storage, even if i t
is a bit string of length one.
In general, the value of a NULL built-in
function is used whenever a pointer (or
offset) variable should not identify a
location in storage. Note that the only AREAS
way a pointer can acquire the null value is
by assignment of the NULL built-in function
(apart from one special case, namely the When a based variable is allocated, the.
assignment of the value returned by the storage is obtained from wherever it is
ADDR built-in function when passed an available. Consequently, a list of

98 OS PL/I CRT AND opr LRM PART I

allocated based variables could be available for other allocations. In fact
scattered widely throughout main storage. the implementation maintains a chain of
For internal operations on the list, this available storage wi~in an area; the head
is not significant, because items are of the chain is held within the 16 bytes of
readily accessed using the pointers. control information. Inevitably, as based
However, if th~ list is to be transmitted variables with different storage
to a data set, the items would have to be requirements are allocated and freed, gaps
collected together. Items allocated within will occur in the area when allocations do
an area variable are already collected and not fit available spaces. Thus the extent
can be transmitted or assigned as a unit of an area may contain allocations that
while still retaining their separate have been freed but are still significant.
identities. A Significant allocation is one that has
not been freed or that has been freed but
It is desirable to identify the has at least one unfreed allocation
locations of based variables within an area following it. When an area has no
variable relative to the start of the area significant allocations, the extent is
variable. Offset variables are defined for zero.
this,purpose. If pOinter variables were
used they would be unlikely to be valid Note that based variables are always
when the area variable were transmitted allocated in multiples of eight bytes.
back to main'storage.
No operators, not even comparison, can
be applied to area variables.

Area variables

Offset Variables
The AREA attribute defines an area of
stgrage that is to be reserved for the
allocation of based variables. The Offset variables are a special form of
declaration of an area variable has the pOinter used exclusively with area
form: variables. The value of an offset variable
indicates the location of a based variable
DCL identifier AREA [(size)]; within an area variable relative to the
start of the area. Because the based
The amount of storage to be reserved is variables are identified relatively, if the
given in bytes; i.e. the integral value of area variable is assigned to a different
·size". If size is not given, a default of part of main storage, the offset values are
1000 bytes is assumed. not invalidated. Note that offset,
variables do not preclude the use of
The size of an area is adjustable in th~ pOinter variables within an area. An
same way as a string length or an array offset variable is declared as follows:
bound and therefore i t can be specified by
an expression or an asterisk (for a DCL identifier
controlled area or parameter) or by a REFER OFFSET[(element-area-variable)]:
option (for a based area). The maximum
size of an area is limited only by the The association of an area variable with
amount of main storage available to the an offset variable is not a special
program. relationship; an offset variable can be
associated with any area variable by means
In addition to the declared size, an of the POINTER built-in function (see
extra 16 bytes of control information, "Locator Conversion" below). The advantage
which contains such details as the amount of making such an association in
of storage in use, precedes the reserved declaration is that a reference to the
size of an area. offset variable implies reference to the
associated area variable.
The amount of reserved storage that is
actually in use is known as the extent of Note that the appearance of an area
the area. The maximum extent is variable in the declaration of an offset is
represented by the area size. Based a contextual declaration of the area
variables can be allocated and freed within variable.
an area at any time during execution. This
means that the extent of an area varies as
storage is used. Because any based
variable can be allocated within an area, Locator Conversion
they could require different amounts of
storage. When a based variable is freed,
the storage i t occupied is marked as When an offset variable is used in a

Chapter 8: Storage Control 99

reference, it is implicitly converted to a This statement allocates storage for a
pQinter value; the address value of an based variable within the specified area.
associated area variable is added to the
offset value. Explicit conversion of an The variable has an offset relative to
offset to a pOinter value is accomplished the start of the area, and this offset
using the POINTER built-in function. For value is assigned to the locator variable
example: specified in the SET option. Conversion
takes place if the locator variable is of
DCL P POINTER, 0 OFFSET(A),B AREA; pointer type. Either or both of the
options IN and SET can be implied. For
example:
P = POINTER(O,B); DeL x BASED(O),
Y BASED(P),
This statement assigns a pointer value to A AREA,
P, giving the location of a based variable, o OFFSET (A) ;
identified by offset 0 in area B. Because
the area variable is different from that
associated with the offset variable, the
programmer must ensure that the offset ALLOCATE X;
value is valid for the different area. It ALLOCATE Y INCA);
would be valid, for example, if area A had
been assigned to area B prior to the The storage class of area A and offset 0 is
invocation of the function. AUTOMATIC by default. The first ALLOCATE
statement is equivalent to:
The OFFSET built-in function complements
the POINTER built-in function and returns ALLOCATE X IN(A) SET(O);
an offset value derived from a given
pOinter and area. The given pOinter value The second ALLOCATE statement is eqUivalent
must identify the location of a based to:
variable in the given area.
ALLOCATE Y IN(A) SET(P);
In practice, these functions need rarely
be used as most conversions are carried out The programmer must ensure that all
implicitly. implications can be resolved. If, for
example, the offset 0 had not been
associated with the based variable X, the
SET option would be required.
Offset Expressions When the IN and SET options are
specified rather than implied, it is
permissible to use an offset variable that
Because an offset is implicitly converted has been declared with no associated area.
to a pointer value, offset expressions can The area in the SET option may also be
be used interchangeably with pOinter different from the one in the DECLARE
expressions. An offset expression can be statement, provided it is contained within
used as a locator qualifier, in association that area. For example:
with a declaration of a based variable, in
a comparison operation, or as an argument DCL 01 OFFSET(Al),
in a procedure reference. Note, however, 02 OFFSET,
that an offset variable cannot be specified A2 AREA BASED(P);
in the SET option of a READ or LOCATE ALLOCATE A2 IN(Al) SET(P);
statement.

ALLOCATE X IN(A2) SET{Ol);

ALLOCATE Statement with the IN Option ALLOCATE Y IN(A2) SET(02);
The offset variables 01 and 02 have the
An offset value is originally obtained values of the offsets of the variables X
either by conversion of a pointer value or and Y, in, respectively, the areas A1 and
by the SET option of the ALLOCATE A2.
statement. This form of the ALLOCATE
statement is as follows: The following example shows how a list
can be built in an area variable using
ALLOCATE based-variable offset variables. This example is a
[IN(element-area-variable)] rewrite of the example given in "Multiple
[SET(locator-variable)]; Generations of Based Variables" earlier in

100 OS PL/I CRT AND OPr LRM PART I

this chapter. AREA ASSIGNMENT

DCL A AREA,
(T,H) OFFSET(A), The ,value of an area expression can be
1 STR BASED(H), assigned to one or more area variables by
2 P OFFSET (A) , an assignment statement. Area-to-area
2 DATA: assignment has the effect of freeing all
allocations in the target area and then
assigning the extent of the source area to
ALLOCATE STR IN(A); the target area, in such a way that all
T=H: otfsets for the source area are valid for
the target area. For example:

NEXT:ALLOCATE STR SET(T->P); DECLARE X BASED (0(1»,

T=T->P: 0(2) OFFSET (A),
(A,B) AREA;

GO TO NEXT;
ALLOCATE X IN (A) ;
X = 1:
ALLOCATE X IN CA) SET (O(2}) ;
FREE statement with the IN Option 0(2) -> X = 2;
B = A;

A based variable allocated within an area Given this program segment and using the
variable can be freed by specifying the POINTER built-in function, the references
area variable by the IN option: POINTER (O(2),B)->X and 0(2)->X will
represent the same value allocated in areas
FREE based-variable B and A respectively.
[IN(element-area-variable»);
If a source area containing no
Multiple freeing of both based and allocations is assigned to a target area,
controlled variables can be made by the the effect is merely to free all
same FREE statement. When all the current allocations in the target area.
allocations of variables within an area
variable are to be freed, the EMPTY built- A possible use for area aSSignment is to
in function is the most convenient method. allow for expansion of a list of based
variables beyond the bounds of its original
area. When an attempt is made to allocate
a based variable within an area that
EMPTY Built-In Function contains insufficient free storage to
accommodate it, the AREA condition is
raised (see below). The on-unit for this
When an area variable is allocated, it condition could be to change the value of a
automatically has the empty state, i.e., pOinter qualifying the reference to the
the area extent is zero. The value of the inadequate area, so that it pOinted to a
EMPTY built-in function can be assigned to different area; on return from the on-unit,
an area variable to free all allocations in the allocation would be attempted again,
the variable. The function reference does within the new area. Alternatively, the
not require arguments but must be given a on-unit could write out the area and reset
null argument list if the name has not been it to EMPTY.
declared BUILTIN. For example:

DECLARE A AREA,
I BASED (P), AREA ON-Condition
J BASED (Q);

The AREA condition is raised in any of the

ALLOCATE I IN(A), J IN (A); following circumstances:

1. When an attempt is made to allocate a

A = EMPTY(); based variable within an area that
/*EQUIVALENT TO: contains insufficient free storage for
FREE I IN (A), J IN (A); */ the allocation to be made.

Note that the area variable itself is not 2. When an attempt is made to perform an
freed, its storage is retained for further area assignment, and the target area
allocations of based variabies. is too small to accommodate the extent

Chapter 8: Storage Control 101

 of the source area. qualification:

3. When a SIGNAL AREA statement is 1. Locator qualification is used to

executed. indicate the generation of a based
variable to which the associated
The ONCODE built-in function can be used reference applies.
to determine whether the condition was
raised by an allocation, an assignment, or 2. If an offset exp!ession or an offset
a SIGNAL statement. On normal return from variable is used as a locator
the on-unit, the action is as follows: qualifier, its value is implicitly
converted to a pOinter value on each
1. If the condition was raised by an reference to the based variable.
allocation, the allocation is r~­
attempted. If the on-unit has changed 3. When more than one locator qualifier
the value of a pOinter qualifying the is used in a reference, only the
reference to the inadequate area so first, or leftmost, can be a function
that i t points to another area, the reference; all other locator
allocation is re-attempted with~n the qualifiers must themselves be based
new area. Note that if the on-unit variables. Note, however, that an
does not effectively correct the entry variable can be based and can
fault, a loop may result. represent a function that returns a
locator value.
2. If the condition was raised by an area
assignment, or by a SIGNAL statement, 4. When more than one locator qualifier
execution continues at the point of is used, they are evaluated from left
interrupt. to right.

If no on-unit is specified, the system will Reference to a based variable can also
comment and raise the ERROR condition. be implicitly qualified. The locator value
used to determine the generation of a based
variable that is implicitly qualified is
the one declared with the based variable.
INPUT/OUTPUT OF AREAS Because the locator declared with a based
variable can also be based, a chain of
locator qualifiers can be implied. For
The area facility is designed to allow easy example:
input and output of complete lists of based
variables as one unit, to and from RECORD DECLARE (P(lO),Q) POINTER,
files. On output, only the area extent, R POINTER BASED (Q),
together with the 16 bytes of control V BASED (P(3»,
information, is transmitted (although the W BASED (R),
extent does include freed allocations which Y BASED;
are still significant). Thus the unused ALLOCATE R,V,W;
part of an area does not take up space on
the data set. Because the extents of areas Given this declaration and allocation, the
may vary, V-format or U-format records following are valid references:
should be used. The maximum record length
required is governed by the area length 1. P(3) -> V
(i.e., area size + 16).
2. V

3. Q -> R -> W
MULTIPLE LOCATOR QUALIFICATION
4. R -> W

Locator qualification is the association of 5. W

one or more locator values with a based
variable to identify a particular References 1 and 2 are equivalent as are
generation of the based variable. references 3, 4 and 5. Note that any
Reference to a based variable can be reference to Y must include a qualifying
explicitly qualified as follows: locator variable.

element-Iocator-expression->
[based-Iocator-variable-> ••• 1
based-variable Levels of Locator Qualification

A number of general rules can be stated

concerning the use of locator A pOinter that qualifies a based variable

102 OS PL/I CRT AND OPT LRM PART I

represents one level of locator ten: there is no limit under the checkout
qualification: an offset represents two compiler. For example:
levels because it is implicitly qualified
within an area. The number of levels is DECLARE X BASED (P),
not affected by a locator being subscripted P POINTER BASED (Q),
and/or an element of a structure. Under Q OFFSET (A):
the optimizing compiler, the maximum number
of levels of locator qualification allowed Given this declaration the references: X,
in a reference depends on the available P -> X, and Q -> P -> X all represent three
storage, but it will never be less than levels of locator qualification.

Chapter 8: storage COntrol 103

 Chapter 9: Subroutines and Functions

The block structure of PL/I permits the use appears.

of subroutines and programmer-defined
functions. Subroutines and functions are Both subroutines and functions can make
groups of statements that can: use of data known in the invoking block.
There are two methods by which data can be
1. be invoked from different points in a made available:
program to perform the same
frequently-used process. 1. Data represented by names which are
known in both the invoking block and
2. process data passed from different the invoked procedure. For
points of invocation. information about the rules for
deciding where a name is known see
3. return control, and in the case of chapter 1, -Recognition of Names·.
functions, return a value derived from
the execution of the function, to a 2. Arguments and Parameters: values from
point immediately following the point the invoking block can be passed to
of invocation. the invoked procedure by writing
arguments in an argument list
Subroutines and functions may be either associated with a CALL statement or
internal or external to the invoking block. option, or function reference; these
Built-in functions are always external values are made available by
procedures which are permanently maintained parameters in the invoked procedure.
in a PL/I system environment, and are an
integral part of the PL/I language. Parameters are identifiers which
appear in the parameter list of an
The rules given in this chapter for the invoked entry point. The number of
use of subroutines and functions depend on arguments and parameters must be the
whether the subroutine or function is an same; the maximum number permitted for
external or internal procedure: this is a particular entry pOint is 64.
because the compiler can determine the
relationship between two procedures from A parameter has no storage associated
the procedures themselves when the invoked with it: it is simply a means of
procedure is internal to the invoking allowing the invoked procedure to
procedure. When the invoked procedure is access storage allocated in the
external the relationship must be given invoking procedure. A reference to a
explicitly in the invoking procedure. parameter in a procedure is
Consequently it is necessary to supply more effectively a reference to the
information about an external subroutine or corresponding argument. Any change to
procedure in the invoking procedure to the value of the parameter is made to
enable the compiler to produce the required the value of the argument. However in
object program. certain circumstances a dummy argument
is created and the value of the
A subroutine is a procedure invoked by a original argument is not changed.
CALL statement or CALL option of an INITIAL These are:
attribute.
a. When the attributes of an argument
A function, either programmer-defined or differ from those of the
built-in, is invoked by the presence of a corresponding parameter. The
'function reference' in an expression. A value of the original argument is
function reference is an entry expression converted and assigned to a dummy.
which represents an entry name of a
fanction. (An entry name is an identifier b. When only a value is passed as an
which represents a particular entry point argument. For example, when an
of a procedure.) argument is a constant.
The definitive difference between a c. When the argument is an iS08-
subroutine and a function in PL/I is that a defined array.
Subroutine does not return data values to
the point of invocation, whereas a function In these cases, a reference to the
procedure returns a value to replace the parameter is effectively a reference
function reference in the evaluation of the to the dummy. The dummy and the
expression in which the function reference parameter initially have the same

Chapter "9: Subroutines and Functions 105

 value as the original argument, but constant value.
subsequent changes to the parameter do
not affect the original argument's
value. storage for dummy arguments is
within that belonging to the invoking ENTRY Attribute
procedure.
Both internal and external subroutines The general form of the ENTRY attribute is:
and functions are normally link-edited, and
loaded into main storage at the same time identifier ENTRY
as the calling procedure. An external [(parameter descriptor list)]
subroutine or function may, however, be [VARIABLE]
compiled, link-edited, and loaded [RETURNS (attribute list)]
separately from the calling procedure. By [OPTIONS (options list)]
the use of FETCH and RELEASE statements in
the calling procedure, the subroutine or The parameter descriptor list is used to
function is allowed to remain on auxiliary specify the attributes of the parameters
storage until required in the calling associated with the entry pOint represented
procedure, at which time it is fetched into by the identifier. The parameter
main storage; and it may be deleted from descriptor must provide accurate
main storage when it is no longer required. information about the attributes of the
This dynamic loading of external procedures parameters so that the compiler can create
is described in chapter 6, "Program the correct dummy arguments. If the
Organization". parameter descriptor list is omitted from
an external entry declaration, the compiler
must assume that the attributes of any
arguments match those of the corresponding
Entry points of Subroutines and parameters. No conversions are performed.
Functions Further information is given under the
heading "Parameter Descriptor List" in this
chapter.
A subroutine or function procedure may have
one or more entry points. The RETURNS attribute may be given to
specify the attributes of the value
PROCEDURE Statement: The primary entry returned by the function procedure.
pOint to a procedure is established by the
PROCEDURE statement. The OPTIONS attribute is required if the
entry pOint is in an external function or
ENTRY Statement: Secondary entry points to subroutine that has been compiled by a
a procedure are established by the ENTRY COBOL or FORTRAN compiler. Further
statement. information is given in chapter 19,
ftInterlanguage communications".
Each PROCEDURE and subsidiary ENTRY
statement can specify its own parameters
and, in the case of function procedures,
returned value attributes. However, the Exit-POints of Subroutines and
environment established on entry to a block Functions
at a PROCEDURE statement is identical to
the environment established when the same
block is invoked at a secondary entry The RETURN statement is used to return
point. Each entry point has an associated control to the point immediately following
entry name. The length of the name for an the point of invocation; the GOTO statement
external entry-point to a PL/I procedure is is used to transfer control to some other
limited to seven characters. pOint; and the END statement can also be
used to return control from a subroutine
Entry names are explicitly declared in procedure in the same way as a RETURN
the invoking block as entry constants for statement. For a function procedure, the
internal procedures by their presence as RETURN statement must specify an element
prefixes to PROCEDURE or ENTRY statements; expression whose value is given to the
it is an error to declare an internal entry function reference in the expression in
name in a DECLARE statement. External which it appears.
entry names must be declared explicitly as
entry constants with the ENTRY attribute.
Entry variables are identifiers with the
attributes ENTRY and VARIABLE which RETURNS Attribute and RETURNS Option
represent entry constants assigned to them.
A reference to an entry variable is a
reference to its latest aSSigned entry The RETURNS attribute specifies for the

106 OS PL/I CKT AND OPT LRM PART I

invoking block the attributes of the value associated with the parameters of the entry
to be received from the function procedure. pOint, and control is then passed to that
The RETURNS option specifies for the entry pOint. The subroutine is thus
function procedure the attributes that a activated, and execution of the subroutine
value to be returned should have. If the procedure can begin.
value does not have these attributes, the
appropriate conversion is performed before
the function relinquishes control and
returns the value.
Upon termination of a subroutine,
If th~ RETURNS option is not specified, control is usually returned to the invoking
the attributes of the returned value are block. A subroutine can be terminated by
assumed by default according to the initial any of the following statements.
letters of the entry-point name. The
standard default assumptions are: REAL
FIXED BINARY (15,0) for initial letters in
the range (I:N) and REAL FLOAT DECIMAL (6)
for the ranges (A:B) and (O:Z) and the END Statement: Control reaches the final
characters $, I, i. END statement of the subroutine. Execution
of this statement causes control to be
The RETURNS attribute must not be returned to the CALL statement from which
specified for an internal entry name the SUbroutine was invoked (unless control
because the compiler can determine the passes to another task).
attributes of the returned value from the
function procedure itself. If it is not
specified for an external entry name or an
entry variable, the compiler assumes
default attributes (determined from the RETURN Statement: Control reaches a RETURN
name of the entry pOint) for the value statement in the subroutine. This causes
returned from the function. Consequently the same normal return caused by the END
the RETURNS attribute and the RETURNS statement.
option must both be given in the situation
when an external function procedure must
return a value with attributes which cannot
be determined correctly by default. The
attributes in both the RETURNS attribute GO TO Statement: Control reaches a GO TO
and the RETURNS option should agree, since statement that transfers control out of the
the value returned by the function will subroutine. (This is not permitted if the
have the attributes specified in the subroutin~ is invoked by the CALL option of
option, whereas the invoking procedure the INITIAL attribute.) The GO TO
always assumes that the value will have the statement may specify a label in a
attributes specified in the RETURNS containing block (the label must be known
attribute. within the subroutine), or it may specify a
parameter that has been associated with a
label argument passed to the subroutine.
Although this is a valid termination of the
Subroutines subroutine, it is not normal return of
control, as effected by an END or RETURN
statement.
The PL/I statements associated with the use
of subroutine procedures are discussed
below. EXIT Statement: The EXIT statement
encountered in a subroutine abnormally
A subroutine is a procedure that usually terminates execution of that subroutine and
requires arguments to be passed to it in an of the task associated with the procedure
invoking CALL statement. It can be either that invoked it.
an external or an internal procedure. A
reference to such a procedure is known as a
subroutine reference. The general format STOP Statement: The STOP statement
of a subroutine reference in a CALL encountered in a subroutine abnormally
statement or CALL option of an INITIAL terminates execution of that subroutine and
attribute is as follows: of the entire program associated with the
procedure that invoked it.
CALL entry-expression
[(argument[,argumentl ••• »);
Use of Subroutines: The following examples
Whenever a subroutine is invoked, the illustrate how a subroutine interacts with
arguments of the invoking statement are the procedure that invokes it.

Chapter 9: Subroutines and Functions 107

 PRMAIN: PROCEDURE; A: PROCEDURE;
DECLARE NAME CHARACTER (20), DECLARE RATE FLOAT (10), TIME FLOAT(S),
ITEM BIT(S), OUTSUB ENTRY; DISTANCE FLOAT(lS), MASTER FILE;

CALL OUT SUB (NAME, ITEM); CALL READCM (RATE, TIME, DISTANCE,
MASTER) ;

END PRMAIN;
OUTSUB: PROCEDURE (A,B); READCM: PROCEDURE (W,X,Y,Z);
DECLARE A CHARACTER (20), DECLARE W FLOAT (10), X FLOAT(S),
B BITeS); Y FLOAT(lS), Z FILE;

PUT LIST (A,B); GET FILE (Z) LIST (W,X,Y);

Y = W*X;
IF Y > 0 THEN RETURN;
ELSE PUT LIST('ERROR READCM');
END OUTSUB; END READCM;
END A;

The arguments RATE, TIME, DISTANCE, and

MASTER are passed to the parameters W, X,
In procedure PRMAIN, NAME is declared as a Y, and Z. Consequently, in the subroutine,
character string, and ITEM as a bit string. a reference to W is the same as a reference
The CALL statement in PRMAIN invokes the to RATE, X the same as TIME, Y the same as
procedure called OUTSUB, and the DISTANCE, and Z the same as MASTER.
parenthesized list included in this
procedure reference contains the two
arguments being passed to OUTSUB. 'The
PROCEDURE statement defining OUTSUB Functions
declares two parameters, A and B. When
OUTSUB is invoked, NAME is associated with
A and ITEM is associated with B. Each Unlike a subroutine, which is invoked by a
reference to A in OUTSUB is treated as a CALL statement or a CALL option, a function
reference to NAME and each reference to B is invoked by the appearance of the
is treated as a reference to ITEM. function name (and associated arguments) in.
Therefore, the PUT LIST (A,B) statement an expression. Such an appearance is
causes the values of NAME and ITEM to be called a function reference. Like a
written into the standard system output subroutine, a function can operate upon the
file, SYSPRINT. Note that in the arguments passed to it and upon other known
declaration of OUTSUB within PRMAIN, no data. But unlike a subroutine, a function
parameter descriptor need be associated is written to compute a single va1ue which
with the ENTRY attribute, since the is returned, with control, to the point of
attributes of NAME and ITEM match those of, invocation. This single value can be of
respectively, A and B. any data type except entry. An example of
a function reference is contained in the
following procedure:

MAINP: PROCEDURE;
A name is explicitly declared to be a
parameter by its appearance in the
parameter list of a PROCEDURE or ENTRY
statement. However, its attributes, unless GET LIST (A, B, C, Y);
defaults apply, must be explicitly stated
within that procedure in a DECLARE
statement.
x = Y**3+SPROD(A,B,C);
It can be seen that the use of arguments In the above procedure, the assignment
and parameters provides the means for statement
generalizing procedures so that data whose
names may not be known within such x = Y*.3+SPROD(A,B,C);
procedures can, nevertheless, be operated
upon. contains a reference to a function called

108 OS PL/I CKT AND OPT LRM PART I

SPROD. The parenthesized list following example, assume that MAINP and SPROD have
t~e function name contains the arguments been defined as follOWS:
that are being passed to SPROD. Assume
that SPROD has been defined as follows: MAINP: PROCEDURE;

SPROD: PROCEDURE (U,V,W);

GET LIST (A,B,C,Y);

X Y**3+SPRODCA,B,C,LAB1):
IF U > V+ W
THEN RETURN (0);
ELSE RETURN (U*V*W);
LAB1 : CALL ERRT;

END SPROD;
END MAINP;
When SPROD is invoked by MAINP, the
arguments A, B, and C are associated with SPROD: PROCEDURE CU,V,W,Z);
the parameters U, V, and W, respectively. DECLARE Z LABEL;
Since attributes have not been explicitly
declared for the arguments and parameters,
default attributes of FLOAT DECIMAL (6) are
applied to each argument and parameter. IF U > V+ W
THEN GO TO Z;
During the execution of SPROD, the IF ELSE RETURN CU*V*W)i
statement is encountered and a test is
made. If U is greater than V + W, the
statement associated with the THEN clause
is executed; otherwise, the statement END SPROD;
associated with the ELSE clause is
executed. In either case, the executed In MAINP, LABl is explicitly declared to be
statement is a RETURN statement. a statement label constant by its
appearance as a label for the CALL ERRT
RETURN Statement: The RETURN statement is statement. When SPROD is invoked, LABl is
the usual way by which a function is associated with parameter Z. Since the
terminated and control is returned to the attributes of Z must agree with those of
invoking procedure. Its use in a function LABl, Z is declared to have the LABEL
differs somewhat from its use in a attribute. When the IF statement in SPROD
subroutine; in a function, not only does it is executed, a test is made. If U is
retu~n control but it also returns a value greater than V + w, the THEN clause is
to the point of invocation. The general executed, control returns to MAINP at the
form of the RETURN statement, when it is statement labeled LABl, and evaluation of
used in a function, is as follows: the expression that invoked SPROD is
discontinued. If U is not greater than V +
RETURN (element-expression); W, the ELSE clause is executed and a return
to MAINP is made in the normal fashion.
The value of the element expression is Additional information about the use of
returned to the invoking 'procedure at the label arguments and label parameters is
point of invocation. Thus, for the above contained in the section -Relationship of
example, SPROD returns either 0 or the Arguments and Parameters- in this chapter.
value represented by U*V*W, along with
control to the invoking expression in ~: In some instances, a fUnction may be
MAINP. The returned value is taken as the so defined that it does not require an
value of the function reference, and argument list. In such cases, the
evaluation of the invoking expression appearance of an external function name
continues. within an expression will be recognized as
a function reference only if the function
GO TO Statement: A function can also be name has been explicitly declared to be an
terminated by execution of a GO TO entry name. See -ENTRY Attribute- in this
statement. If this method is used, chapter for additional information.
evaluation of the expression that invoked
the function will not be completed, and
control will go to the designated
statement. As in a subroutine, the ATTRIBUTES OF RETURNED VALUES
transfer point specified in a GO TO
statement may be a parameter that has been
associated with a label argument. For RETURNS Attribute: The RETURNS attribute

Chapter 9: Subroutines and Functions 109

is specified in a DECLARE statement for an generiC name GENERIC (entry-expression
external entry name. It specifies for the WHEN (generic-descriptor-list)
invoking block the attributes of the value [,entry-expression
returned by that function. It further WHEN(generic-descriptor-list)] ••• );
specifies, by implication, the ENTRY
attribute for the name. Unless attributes where generic-descriptor-list is:
for the returned value can be determined
correctly by default, any invocation of an ([descriptor£,descriptor] ••• ])
external function must appear within the
scope of a declaration with the RETURNS Each entry-expression corresponds to one
attribute for the entry name. procedure entry point in the family. The
entry expression can be an entry name or an
The general format of the RETURNS expression which represents an entry name.
attribute is: Each descriptor in the generic-descriptor
list corresponds to a single argument, and
RETURNS (attribute-list) may specify attributes that the
corresponding argument must have in order
A RETURNS attribute specifies that within that the associated entry name can be
the invoking procedure the value returned selected. Where no descriptor is required,
from an external function procedure is to i t may be either omitted or indicated by an
be treated as though it had the attributes asterisk. The asterisk form is essential
given in the attribute list. The word if the missing descriptor is the only
treated is used because no conversion is descriptor. For example, whereas (,)
performed in an invoking block upon any represents two descriptors (*) represents
value returned to it. The attributes given one. The generic descriptor list which is
in a RETURNS attribute must agree with the to represent the absence of any argument
data attributes given in the corresponding takes the form:
RETURNS option, since the value returned
will have attributes determined from the •••• ENTRYl WHEN( ) •••
RETURNS option.
An entry expression is chosen from those
The RETURNS attribute cannot be given specified in a generic declaration by a
for an internal procedure. The attributes process known as generic selection.
of the returned value are determined from Generic selection is performed by comparing
the RETURNS option at the entry point, if arguments specified in a function reference
given; otherwise according to default rules or CALL statement with the contents of the
as applied to the identifier of the entry generiC descriptor list supplied with each
constant. entry expression in the GENERIC
declaration. Firstly, each generic
RETURNS Option: The RETURNS option is descriptor list is checked, in order of
specified in a PROCEDURE or ENTRY statement appearance in the declaration to determine
of a function procedure. It specifies the whether it contains the same number of
attributes to which the value returned by descriptors as there are arguments in the
the function will be converted before reference to the generic name.
return.
When a generic descriptor list with the
same number of descriptors as arguments is
found, each descriptor is tested with the
corresponding argument to determine whether
Generic Entry Names and References attributes given in the descriptor are
attributes of the argument. For example,
if a generic descriptor list contains:
A generic entry name represents a family of
procedure entry pOints, each member of ••••• (FLOAT,FIXED)
which can be invoked by a generic
reference, that is, a procedure reference and the corresponding two arguments have
using the generic name in place of the attributes such as DECIMAL FLOAT(6) and
actual entry name. The member invoked is BINARY FIXED(15,0) either explicitly,
determined according to the number and contextually, implicitly, or by default,
attributes of the arguments specified in then each attribute in the generic-
the generic reference; the member that is descriptor list is an attribute of the
invoked is the first one whose generic corresponding argument and the selection is
descriptor list matches the arguments both successful. However, if either argument
in number and attributes. did not have the attributes in the
corresponding descriptor, the selection
A generic name must be declared with the process would consider the next generic
GENERIC attribute. The general format of member with just two descriptors. For
this attribute is as follows: example consider the following statement:

110 OS PL/I CKT AND OPT LRM PART I

 DECLARE CALC GENERIC whereas a programmer-defined function can
(FXDCAL WHEN (FIXED,FIXED), return only an element value.
FLOCAL WHEN (FLOAT, FLOAT) ,
MIXED WHEN (FLOAT,FIXED»; Note: Some built-in functions will
actually be compiled as in-line code rather
This statement defines CALC as a generic than as procedure invocations.
name having three members, FXDCAL, FLOCAL,
and MIXED. One of these three function The use of a built-in function with a
procedures will be invoked by a generic list, such as SUBSTR <X,Y,Z) or
reference to CALC, depending on the INDEX(A,'B ' ), is recognized without further
characteristics of the two arguments in identification being necessary to establish
that reference. For example, consider the the identifier as a built-in function.
following statement: However, any built-in function or
pseudovariable which does not have a
Z=X+CALC(X,Y); parenthesized argument list, such as
ONCHAR, ONSOURCE, TIME, must be either
If X and Yare floating-point and fixed- declared explicitly with the attribute
point, respectively, MIXED will be invoked. BUILTIN, or specified with a null argument
list (for example TIME(» in the block in
In a similar manner, an entry pOint to a which the identifier is used as a built-in
procedure can be selected by means of function.
dimensionality. For example,
Built-in function names can be used as
DCL D GENERIC (Dl WHEN«.», programmer-defined names. Consequently,
D2 WHEN ( (.,.» ) , ambiguity may occur if a built-in function
A(2) , reference is used in a block that is
B(3,5); contained in another block in which the
CALL D(A); same identifier is declared for some other
CALL D(B) ; purpose. To avoid this ambiguity, the
BUILTIN attribute can be declared for a
When the first call statement is executed, built-in fUnction name in any block that
the procedure entry pOint D1 will be has inherited, from a containing block,
invoked. When the second call statement is some other declaration of the identifier.
executed, the procedure entry pOint 02 will Consider the tollowing example.
be invoked.
A: PROCEDURE;
If all the descriptors are omitted or
consist of an asterisk, the first entry
name with the correct number of descriptors
is selected. B: BEGIN;
DECLARE SQRT FLOAT BINARY;
The program is in error if no generic
descriptor list is found to match the
attributes of the arguments to a particular
generic function reference. C: BEGIN;
DECLARE SQRT BUILTIN;

Built-in Functions
END C;

Besides function references to procedures

written by the programmer, a function
reference may invoke one of a comprehensive END B;
set of pre-defined functions called
built-in functions.

Built-in functions are an intrinsic part END A;

of PL/I. They include not only the
commonly used arithmetic functions but also Assume that in external procedure A, SQRT
other necessary or useful functions related is contextually declared with the attribute
to language facilities, such as functions BUILTIN. consequently, any reference to
for manipulating strings and arrays. SQRT would refer to the built-in function
of that name. In B, however, SQRT is
Built-in functions are invoked in the declared to be a floating-point binary
same way that programmer-defined functions variable, and it cannot be used in any
are invoked. However, many built-in other way. Finally, in C, SQRT is declared
functions can return an array of values, with the BUILTIN attribute so that any

Chapter 9: Subroutines and Functions 111

reference to sQRT will be recognized as a The use of sQRT as the label of the second
reference to the built-in function and not PROCEDURE statement is an explicit
to the floating-point binary variable declaration of the identifier as an entry
declared in B. name. The function reference in the
aSSignment statement in A thus refers to
Note that a variable having the same the programmer-written sQRT function. In
identifier as a built-in function can be the begin block B, the identifier sQRT is
implicitly declared as an arithmetic declared with the BUILTIN attribute.
variable by, for instance, its appearance consequently, the function reference in the
on the left-hand side of an assignment assignment statement in B refers to the
symbol (in an assignment statement, a DO built-in sQRT function.
statement, or a repetitive specification)
or in the data list of a GET statement, For a programmer-written internal
provided that it is neither enclosed within function using the name of a built-in
nor immediately followed by an argument function any reference 'to the identifier in
list. (This also applies to the names the containing block would be a reference
ONCHAR, ONSOURCE, and PRIORITY which are to the programmer-written function. In the
pseudovariables that do not require above example the attributes of the
arguments.) For example, if the statement returned value are specified in the RETURNS
sQRT = 1 had appeared in begin block B option of the procedure statement for sQRT.
instead of the DECLARE statement, sQRT Since the function procedure is internal,
would have been implicitly declared as a these attributes are known to the calling
floating-point decimal variable. procedure.
A programmer can even use a built-in In the case of a programmer-written
function name as the entry name of a external function procedure using as an
programmer-defined function and, in the entry name the name of a built-in function,
same program, use both the built-in any procedure containing a reference to
function and the programmer-defined that function procedure name must also
function. This can be accomplished by use contain an entry declaration of that name;
of the BUILTIN attribute when the otherwise a reference to the identifier
programmer-defined function is an internal would be a reference to the built-in
procedure, and by use of the BUILTIN and function. In the above example, if the
ENTRY attributes when the programmer- begin block B were not contained in A,
defined function is an external procedure. there would be no need to specify the
BUILTIN attribute; unless the identifier
The following example illustrates use of sQRT is given attributes other than BUILTIN
the BUILTIN attribute in conjunction with (by explicit or contextual declaration), it
an internal function procedure. refers to the built-in function. If the
procedure sQRT were an external procedure,
A: PROCEDURE; procedure A would need the following
sQRT: PROC(PARAM) RETURNs(FIXED(6,2»; statement to declare explicitly sQRT as an
DECLARE PARAM FIXED (12): entry name, and to specify the attributes
of the values passed to and returned from
the programmer-written function procedure.
END sQRT: DCL sQRT ENTRY (FIXED (12» RETURNS
(FIXED(6,2»;

x = sQRT(Y):
FORTRAN Library Functions

B: BEGIN; Library functions, analagous to PL/I built-

DECLARE SQRT BUILTIN; in functions, are associated with FORTRAN
compilers. These functions may be invoked
from a PL/I program by means of PL/I
interlanguage communication facilities.
Z = sQRT (P): The facilities are described in chapter 19.

END B: Built-in Subroutines

A PL/I programmer can avail himself of

END A; certain operating system facilities by

112 05 PL/I CRT AND OPT LRM PART I

using built-in subroutines. These have the value of the dummy argument and not in
entry names that are defined by the the value of the original argument from
implementation and are invoked by means of which it was constructed.
the CALL statement. The operating system
facilities and the corresponding entry
names are as follows. A dummy argument is always created when
the original argument is any of the
Checkpoint/restart (implemented by the following:
optimizing compiler only): PLICKPT,
PLIREST, PLICANC 1. A constant.
A CALL statement specifying PLICKPT, 2. An expression involving operators.
PLIREST, or PLICANC is treated as a null
statement by the checkout compiler. 3. An expression in parentheses.

Sort/merge: PLISRTA, PLISRTB, PLISRTC, 4. A variable whose data attributes are

PLISRTD different from the data attributes
declared for the parameter. This does
In addition, there is a subroutine, not apply when an expression other
PLIDUMP, that provides an edited dump of than a decimal integer constant is
main storage, and another, PLIRETC, that used to define the bounds, length or
allows the user to set the return code of size of a controlled parameter: the
his program. compiler assumes that the argument and
parameter bounds, length or size
The entry names are known as built-in match. (In the case of arguments and
~, and can be explicitly or parameters with the PICTURE attribute,
contextually declared to have the BUILTIN a dummy argument will be created
attribute. They are not reserved words. unless the picture specifications
match exactly, after any repetition
The use of these subroutines is factors have been applied. The only
described in the following publications: exception is that an argument or
OS PL/I Optimizing Compiler: programmer's parameter with a + sign in a scaling
Guide and OS PL/I Checkout Compiler: factor matches a parameter or argument
Programmer's Guide. without the + sign.)
5. A function reference with an argument
list.
Relationship of Arguments and
Parameters 6. A controlled string or area, or a
string or area with an adjustable
length or size, associated with a nOn-
When a function or subroutine is invoked, a controlled parameter whose length or
relationship is established between the Size is a constant.
arguments of the invoking statement or
expression and the parameters of the 1. An iSUB-defined array.
invoked entry point. This relationship is
dependent upon whether or not dummy The attributes of a dummy argument
arguments are created. created for an argument to be passed to an
internal procedure are derived as follows:
1. From the attributes declared for the
DUMMY ARGUMENTS aSSOCiated parameter in the internal
procedure.
In the preceding discussions of arguments 2. For the bounds of an array, the length
and parameters, it is pointed out that the of a string or the size of an area, if
name of an argument, not its value, is specified by asterisk notation in the
passed to a subroutine or function. parameter declaration, from the bound,
However, this is not always possible. A length or size of the argument itself.
constant, for example, has no name; nor
does an operational expression. Therefore, In all other cases, a reference to the
the compiler provides storage for such argument is passed directly (in effect, the
values and associates the name of the storage address of the argument is passed).
corresponding parameter with each. These The parameter becomes identical with the
storage locations are called dummy passed argument; thus, changes to the value
arguments. The PL/I programmer should be of a parameter will be reflected in the
aware of their existence because any change value of the original argument only if a
to a parameter wi1l be reflected only in dummy argument is not passed.

Chapter 9: Subroutines and FUnctions 113

ENTRY ATTRIBUTE subroutine or function must be accounted
for. When the attributes of the argument
and parameter match, the descriptor may be
The ENTRY attribute is used to identify the either omitted or indicated by an asterisk,
entry name of an external procedure. The but commas delimiting the descriptors must
use of the ENTRY attribute to identify the not be omitted. For example, the
entry constant of an internal procedure is statement:
invalid; its use to identify each entry
point of an external procedure is
mandatory. The general form of the ENTRY
attribute is described in ·use of the ENTRY
Attribute·, earlier in this chapter. DECLARE SUBR ENTRY CFIXED"FLOAT);
Note that the format allows the keyword
ENTRY to be specified without an
accompanying parameter descriptor list when
used to identify a function entry name that specifies that sUBR is an entry point that
does not require arguments, or when the has three parameters: the first and third
arguments and parameters match. The have the attributes FIXED and FLOAT,
parameter descriptor list must be specified respectively, while the attributes of the
with an ENTRY attribute that identifies the second are assumed to be the same as those
entry name of an external procedure if of the argument being passed. Since the
arguments do not match parameters. The use attributes of the second parameter are not
of the attribute VARIABLE in an entry stated, no assumptions are made.
declaration establishes the identifier as
an entry variable. An entry variable
represents an entry constant after As mentioned earlier, the ENTRY
assignment of the entry constant to the attribute may be specified without a
entry variable. If an entry variable is parameter descriptor list. It is used in
used in a function reference or CALL this way to indicate that the associated
statement to invoke an entry point to which identifier is an entry name. Such an
arguments are to be passed, the entry indication is necessary if an identifier is
variable should be declared with a not otherwise recognizable as an entry
parameter descriptor list which specifies name, that is, if it is not explicitly
the attributes of the parameters of the declared to be an entry name by its
entry point, otherwise erroneous arguments appearance as a label of a PROCEDURE or
may be passed. ENTRY statement.

Therefore, if a reference is made to an

Parameter Descriptor Lists entry name in a block in which it does not
appear in this way, the identifier must be
given the ENTRY attribute explicitly. For
Each set of attributes, or descriptor, in example, assume that the following has been
the parameter descriptor list in the ENTRY specified:
attribute specification corresponds to one
parameter of the subroutine or fUnction
invoked, and if given, specifies the A: PROCEDURE;
attributes of that parameter. The
attributes of an individual parameter are
separated by blanks to form a parameter
descriptor for each parameter; parameter PUT LIST (RANDOM);
descriptors in a parameter descriptor list
are separated by commas. In general, if
the attributes of an argument do not agree
i
:,

with those of its corresponding parameter END A;

(as specified in a parameter descriptor
list), a dummy argument is constructed for
that argument if conversion is possible. Assume also that A is an external procedure
The dummy argument contains the value of and RANDOM is an external function that
the original argument converted to conform requires no arguments and returns a random
with the attributes of the corresponding number. As the procedure is shown above,
parameter. Thus, when the subroutine or RANDOM is not recognizable within A as an
function is invoked, it is the dummy entry name, and the result of the PUT
argument that is passed to it. statement therefore is undefined. In order
for RANDOM to be recognized within A as an
When a descriptor list is given with the entry name, it must be declared to have the
ENTRY attribute, each parameter of the ENTRY attribute. For example:

114 OS PL/I CKT AND OPT LRM PART I

 A: PROCEDURE; procedure A, the value of the entry
DECLARE RANDOM ENTRY; name B.

3. When a built-in function name or an

PUT LIST (RANDOM); entry expression is used without an
argument list as an argument to a
built-in function, the function
specified by the argument is not
END A; invoked provided that the built-in
fUnction will accept an argument of
Now, RANDOM is recognized as an entry name, type ENTRY. If the built-in function
and the appearance of RANDOM in the PUT will not accept an entry argument, the
statement cannot be interpreted as anything argument is assumed to be a reference
but a function reference. Therefore, the to the value of the function. For
PUT statement results in the output example:
transmission of the random number returned
by RANDOM.
DCL DATE BUILTIN, Z CHAR(2);
~ The ENTRY attribute is implied --
and therefore need not be stated explicitly
-- for an identifier that is declared in a Z SUBSTR (DATE, 5 , 2 ) :.
DECLARE statement to have one of the entry
name attributes RETURNS, OPTIONS,
REDUCIBLE, or IRREDUCIBLE. The days field is extracted from the
value returned by the DATE built-in
function
Entry Expressions as Arguments
4. If the entry expression argument to a
user-defined function appears without
When an entry name is specified as an an argument list and neither within an
argument of a function or subroutine operational expression nor within
reference, one of the following applies: parentheses, the entry expression
itself is passed to the function or
1. If the entry expression argument, call subroutine being invoked. In such
it M, is specified with an argument cases, the entry expression is not
list of its own, it is recognized as a taken to be a function reference, even
function reference: M is invoked, and if it is the name of a function that
the value returned by M effectively does not require arguments. For
replaces M and its argument list in example:
the containing argument list. For
example:
CALL A(B);
CALL A (M(B»:
This passes the entry expression B as
This passes the value returned by the an argument to procedure A. If the
function procedure M. corresponding parameter in A has been
declared with the attribute ENTRY, it
If the entry expression argument will be given the attribute VARIABLE
appears with a null argument list, it by default. If B is an entry
is taken to be a fUnction reference variable, it will be passed to the
with no arguments. For example: parameter in the same way as for any
argument whose attributes match those
CALL A(BO); of the parameter. If B is an entry
constant a dummy is created and
This passes, as the argument 'to passed, as for any constant argument.
procedure A, the value returned by the
function procedure B. If an identifier is known as an entry
name and appears as an argument and if
2. If the entry expression argument has 'the parameter descriptor for that
no argument list and appears within argument specifies an attribute other
parenthesiS, a dummy entry variable is than ENTRY, the entry name will be
created. For example: invoked and its returned value passed.
If the value returned has different
CALL A((B»: attributes from those specified in the
parameter descriptor, conversion is
This passes, as the argument to performed. For example:

Chapter 9: Subroutines and Functions 115

 A: PROCEDURE; Therefore, since RREAD is recognized
DECLARE B ENTRY, as an entry name and not as a £unction
C ENTRY(FLOAT); reference, the entry name is passed at
invocation. Since NAME is an entry
parameter, it is given the attribute
VARIABLE by default. Since RREAD is a
x = C(B); constant, a dummy entry argument is
created, and this is passed to NAME.

2. The second argument, SQRT(R), is

END A; recognized as a built-in function
reference because of the argument list
In this case, B is invoked and its accompanying the entry name. SQRT is
returned value is passed to C. invoked, and the value returned by
SQRT is aSSigned to a dummy argument,
Consider the following example: which will be passed to the subroutine
SUBR. The attributes of the dummy
CALLP: PROCEDURE; argument agree with those of the
DECLARE RREAD ENTRY, second parameter, as specified in the
SUBR ENTRY (ENTRY, FLOAT, parameter attribute list declaration.
FIXED BINARY, LABEL); When SUBR is invoked, the dummy
argument is passed to it.

3. The third argument, S, is simply a

GET LIST (R,S); decimal floating-point element
variable. However, since its
attributes do not agree with those of
the third parameter, a dummy argument
CALL SUBR (RREAD, SQRT(R), 5, is created containing the value of 5
LABl) ; converted to the attributes of the
third parameter. When SUBR is
invoked, the dummy argument is passed.
LABl: CALL ERRT (5) ; 4. The fourth argument, LABl, is a
statement-label constant. Its
attributes agree with those of the
fourth parameter. But since i t is a
END CALLP; constant, a dummy argument is created
for it. When SUBR is invoked, the
SUBR: PROCEDURE (NAME, X, J, TRANPT); dummy argument is passed.
DECLARE NAME ENTRY, TRANPT LABEL;
In SUBR, four parameters are explicitly
declared in the PROCEDURE statement. If no
further explicit declarations were given
IF X > J THEN CALL NAME(J); for these parameters, arithmetic default
ELSE GO TO TRANPT; attributes would be supp~ied for each.
Therefore, since NAME must represent an
entry name, it is explicitly declared with
the ENTRY attribute, and since TRANPT must
END SUBR; represent a statement label, it is
explicitly declared with the LABEL
In this example, assume that CALLP, SUBR, attribute. X and J are arithmetic, so the
and RREAD are external. In CALLP, both defaults are allowed to apply.
RREAD and SUBR are explicitly declared to
have the ENTRY attribute. The explicit Note that the appearance of NAME in the
declaration for SUBR is used to provide CALL statement does not constitute a
information about the characteristics of contextual declaration of NAME as a built-
the parameters of SUBR. Four arguments are in procedure. Such a contextual
specified in the CALL SUBR statement. declaration is made if no explicit
These arguments are interpreted as follows: declaration applies. However the
appearance of NAME in the PROCEDURE
1. The first argument, ~READ, is statement of SUBR constitutes an explicit
recognized as an entry name (because declaration of NAME as a parameter. If the
of the ENTRY attribute declaration). attributes of a parameter are not
This argument is not in conflict with explicitly declared in a complementary
the first parameter descriptor DECLARE statement, arithmetic defaults
specified in the ENTRY attribute apply. Consequently, NAME must be
declaration for SUBR in CALLP. explicitly declared to have the ENTRY

116 OS PL/I CKT AND OPT LRM PART I

 attribute: otherwise, i t would be assumed I storage. If such a variable is a parameter
tQ be a binary fixed-point variable, and land an aggregate, it should have the
its use in the CALL statement would result ICONNECTED attribute, both in its
in an error. Ideclaration in the subroutine, and, where
applicable, in the descriptor list of the
subroutine entry declaration.

ALLOCATION OF PARAMETERS In the subroutine, the CONNECTED

attribute specifies that the parameter
represents connected storage. In the entry
Since a parameter has no associated storage declaration, it specifies that, if the
within the invoked procedure. i t cannot be argument is in non-connected storage, a
declared to have any of the storage class dummy argument in connected storage is to
attributes STATIC, AUTOMATIC, or BASED. It be created.
can, however, be declared to have the
CONTROLLED attribute. ThUS, there are two Note that elements, arrays, and major
classes of parameters, as far as storage structures are always allocated in
allocation is concerned: those that have connected storage. References to non-
no storage class, i.e., simple parameters, connected storage arise only when the
and those that have the CONTROLLED programmer refers to an aggregate that is
attribute, i.e., controlled parameters. Imade up of non-contiguous items from a
Ilarger aggregate. For example, in the
A simple parameter may be associated I structure:
with an argument of any storage class. I
However, if more than one generation of the I 1 A(10),
argument exists, the parameter is I 2 B,
associated only with that generation I 2 C;
existing at the time of invocation. I
Ithe interleaved arrays A.B and A.C are both
A controlled parameter must always have lin non-connected storage.
a corresponding controlled argument. Such I
an argument cannot be subscripted, cannot I For array cross-sections, the rule is as
be an element of a structure, and cannot I follows: if a non-asterisk bound appears
cause a dummy to be created. If more than Ito the right of the left-most asterisk
one generation of the argument exists at I bound, the array cross-section is in non-
the time of invocation, the parameter Iconnected storage. Thus A(4,*,*) is in
corresponds to the entire stack of these Iconnected storage; A(*,2,.) is not. iSUB-
generations. Thus, at the time of Idefined variables are always regarded as
invocation, a controlled parameter Ibeing in non-connected storage.
represents the current generation of the
corresponding argument. A controlled
parameter may be allocated and freed in the
invoked procedure, thus allowing the
manipulation of the allocation stack of the
associated argument. A simple parameter
cannot be specified in an ALLOCATE or FREE
statement. Parameter Bounds, Lengths, and Sizes

When no parameter descriptor is given,

the entire stack is passed. In this case, If an argument is an array, a string, or an
the parameter may be Simple or controlled area, the bounds of the array, the length
and be correspondingly associated with of the string, or the size of the area must
either the latest generation or the entire be declared for the corresponding
stack. parameter. The number of dimensions and
the bounds of an array parameter, or the
length and size of an area or string
parameter, must be the same as the current
Parameter Attributes generation of the corresponding argument.
Usually, this can be assured simply by
specifying actual numbers for the bounds,
IParameters cannot be declared with the length, or size of the parameter.
lattributes DEFINED or BASED. A parameter
lalways has the attribute INTERNAL. It must If the bounds, length, or size are not
lbe a level-one identifier. known at the time the subroutine or
I function is written, they may be specified
I Variables that are used in record- by asterisks, for simple parameters, or
loriented input/output, or as the base for asterisks or expressions for controlled
IDEFINED items, must be in connected parameters.

Chapter 9: Subroutines and Functions 117

Simple Parameter Bounds, Lengths, and MAIN: PROCEDURE OPTIONS (MAIN) ;
Sizes DECLARE (A(20), B(30), C(100),
D(100»CONTROLLED,
NAME CHARACTER (20),
When the actual length, bounds, or size of I FIXED(3,0);
a simple parameter may be different for
different invocations, they can be
specified in a DECLARE statement by ALLOCATE A,B;
asterisks. When an asterisk is used, the CALL SUB1 (A, B):
length, bounds, or size are taken from the
current generation of the corresponding
argument. FREE A,B:
An asterisk is not allowed as the length
specification of a character or bit string FREE A,B:
that is an element of an aggregate, if the GET LIST (NAME,I);
corresponding argument is such that a dummy CALL 5UB2 (C,D,NAME,I);
is created. The string length must be
specified as a decimal integer constant.
FREE C,D:

END MAIN:
5UB1: PROCEDURE (U,V):
DECLARE (U(*), V(*» CONTROLLED;

ALLOCATE U(30), V(40):

Controlled Parameter Bounds, Lengths,
and sizes
RETURN:
END SUBl:
The bounds, length, or size of a controlled
parameter can be represented in a DECLARE SUB2: PROCEDURE (X, Y, NAMEA, N) :
statement either by asterisks or by element DECLARE (X(N),Y(N»CONTROLLED,
expressions. NAMEA CHARACTER (*),
N FIXED(3,O);
Asterisk Notation: When asterisks are
used, length, bounds, or size of the
controlled parameter are taken from the ALLOCATE X, Y;
current generation of the corresponding
argument. Any subsequent allocation of the
controlled parameter uses these same RETURN:
bounds, length, or size, unless they are END SUB2:
overridden by a different length , bounds,
or size specification in the ALLOCATE In the procedure MAIN, the arrays A, B, C,
statement. If no current generation of the and D are declared with the CONTROLLED
argument exists, the asterisks only storage class attribute: NAME and I are
determine the dimensionality of the AUTOMATIC by default.
parameter, and an ALLOCATE statement in the
invoked procedure must specify bounds, When SUBl is invoked, A and B, which
length, or size for the controlled have been allocated as declared, are
parameter before other references to the passed. SUBl declares its parameters with
parameter can be made. the asterisk notation. The ALLOCATE
statement, however, specifies bounds for
Expression Notation: The bounds, length, the arrays; consequently, the allocated
or size of a controlled parameter can also arrays, which are actually a second
be specified by element expressions. These generation of A and B, have bounds
expressions are evaluated at the time of different from the first generation. If ne
allocation. Each time the parameter is bounds were specified in the ALLOCATE
allocated, the expressions are re-evaluated statement, the bounds of the first and the
to give current bounds , length, or size new generation would be identical.
for the new allocation. However, such
expressions in a DECLARE statement can be On return to MAIN, the first FREE
overridden by a bounds , length, or Size statement frees the second generation of A
specification in the ALLOCATE statement and B (allocated in SUBl as parameters),
itself. For example: and the second FREE statement frees the

118 OS PL/I CKT AND OPT LRM PART I

first ~eneration (allocated in MAIN). structure argument, whose description
matches that of the structure parameter.
When SUB2 is invoked, C and D are passed The value of the element expression then
to X and Y, NAME is passed to NAMEA, and I becomes the value of each element of the
is passed to N. In S082, X and Yare dummy structure argument. The relative
declared with bounds that depend upon the structuring of the argument and the
value of I (passed to N). When X and Yare parameter must be the same; the level
allocated, this value determines the bounds numbers need not be identical. The element
a£ the allocated array. value must be one that can be converted to
conform with the attributes of all the
Although NAME (corresponding to NAMEA) elementary names of the structure.
is Bot controlled, the asterisk notation
fer the length of NAMEA indicates th~t the If the parameter is an array of
len~th is to be picked up from the argument structures, the argument can be the
(NAME). expression representing an element, an
array, a structure or an array of
structures.
ARGUMENT AND PARAMETER TYPES If a parameter is a label, the argument
must be either a label variable or a label
constant. If the argument is a label
In genera l, an argument and its constant, a dummy argument is constructed.
~rresponding parameter may be of any data
&r9anization and type. However, not all If the parameter is an entry , the
parameter/argument relationships are so argument must be an entry name or a generiC
clear-cut. Some need further definition name. If the argument is a generic name
and clarification; these are given below. the parameter descriptor (or paramet.er
declaration, if the invoked procedure is
If a parameter is an element, i.e., a internal) must give parameter descriptions
va'riahle that is neither a structure nor an to enable generic selection to be made
array, the argument must be an element before passing an entry. Under the
e~ession. If the argument is a optimizing compiler, entry variables passed
suBscripted variable, the subscripts are as arguments are assumed to be aligned, so
evaluated before the subroutine or function that no dummy argument is created when only
is invoked and the name of the specified the alignments of argument and parameter
element is passed. If the argument passed differ. Note that the name of a
to an external procedure is a constant, the mathematical built-in function can be
attributes of the corresponding parameter passed as an argument but no other built-in
mast agree with the attributes indicated by function name can be passed.
the constant, unless there is a
corresponding parameter descriptor in the If a parameter is a file, the argument
entry declaration. must be a file variable or file constant.
If a parameter is an array, the argument For example:
may be an array expression or an element
empress ion. If the argument is an element E: PROCEDURE ;
expression, the corresponding parameter DECLARE Fi FILE;
4escriptor or declaration must specify the CALL El(Fl);
beunds of the array parameter. The bounds
mast be specified as decimal integer
eonstants. This causes the construction of
a dummy array argument, whose bounds are El: PROCEDURE(F2);
those of the array parameter. The value of DECLARE F2 FILE;
tBe element expression is then aSSigned to CALL E2(F2);
the value of each element of the dummy
array arqument.
If a parameter is a structure, the E2: PROCEDURE (F3):
argument must be a structure expression or DECLARE F3 FILE;
an element expression. If the argument is
an element expreSSion, the corresponding
parameter descriptor for an external entry
poiBt must specify the structure END E;
des·cription of the structure parameter
(anly level numbers need be used -- see the The file parameters Fl, F2, and F3 all
«iscussion of the ENTRY attribute in refer to the same file. Input/output on-
section I, "Attributes", for details). units for file parameters are discussed in
Tais causes the construction of a dummy chapter 14, "Execution Condition Handling

Chapter 9: Subroutines and Functions 119

and Program Checkout·. Passing an Argument to the Main
If the parameter is a fixed length Procedure
string, and if a dummy argument is not to
be created, then the argument must also be
a fixed length string. Similarly, if a
dummy is not to be created when the A Single argument can be passed using the
parameter is a varying length string, the PARM field in the statement for the step
argument must be a varying length string. executing the PL/I program. See OS PL/I
Whenever a varying-length element string Optimizing Compiler: Programmer's Guide
argument is passed to a non-varying element and OS PL/I Checkout Compiler:
string parameter whose length is undefined programmer's Guide. If this facility is
(i.e. specified by an asterisk), the used, the parameter must be declared as a
current length of the argument is passed to VARYING character string; the maximum
the invoked procedure. When the argument length is 100, and the current length is
is a varying-length string array passed to set equal to the argument length at obj ect
a non-varying undefined-length parameter, time. For example:
only one length is passed, namely the
maximum length.
TOM: PROC (PARAM) OPTIONS (MAIN);
If a parameter is a locator of either DCL PARAM CHAR(100) VARYING;
pOinter or offset type, the argument must
be a locator expression of either type. If
the types differ, a dummy argument is The value in the PARM field of the EXEC
created. The parameter descriptor of an statement for the execution job step will
offset parameter must not specify an be passed to TOM.
associated area.
storage is allocated only for the
If the parameter is an ~ , the current length of the argument; the source
argument must be an area expression. If program will overwrite adjacent information
th~ sizes differ, a dummy argument is if a value greater than the current length
created. is assigned to the parameter.

120 OS PL/I eKT AND OPT LRM PART I

 Chapter 10: Input and Output

PL/I includes input and o~tput statements with record-oriented transmission, stream-
that enable data to be transmitted between oriented tranSmission is less efficient in
the internal and external storage devices terms of execution time because of the data
of a computer. A collection of data conversion it involves, and more space is
external to a program is called a data set. required on external storage devices
Transmission of data from a data set to a because all data is in character form.
program is termed input, and transmission
of data from a program to a data set is Record-oriented transmission is more
called output. versatile than stream-oriented
transmission, with regard to both the
PL/I input and output statements are manner in which data can be processed and
concerned with the logical organization of the types of data set that it can process.
a data set and not with its physical Since data is recorded in a data set
characteristics: a program can be designed exactly as it appears in main storage, any
without specific knowledge of the data format is acceptable: no conversion
input/output devices that will be used when problems will arise, but the programmer
the program is executed. To a1low a source must have a greater awareness of the
program to deal primarily with the logical structure of his data.
aspects of data rather than with its
physical organization in a data set, PL/I This chapter discusses those aspects of
employs a symbolic representation of a data PL/I input and output that are common to
set called a file. A file can be stream-oriented and record-oriented
associated with different data sets at transmission, including files and t~eir
different times during the execution of a attributes, and the relationship of files
program. to data sets. The next two chapters
describe the input and output statements
TWO types of data transmission can be that can be used in a PL/I program, and the
used by a PL/I program. In stream-oriented various data set organizations that are
transmission, the organization of the data recognized in PL/I.
in the data set is ignored within the
program, and the data is treated as though
it actually were a continuous stream of
individual data items in character form: Data Sets
data is converted from character form to
internal form on input, and from internal
form to character form on output. In oata sets are stored on a variety of
record-oriented transmission, the data set auxiliary storage media, such as punched
is considered to be a collection of cards, reels of magnetic tape, magnetic
discrete records. No data conversion takes disks, and magnetic drums. oespite their
place during record transmission: on input variety, these media have many common
the data is transmitted exactly as it is characteristics that permit standard
recorded in the data set, and on output it methods of collecting, storing, and
is transmitted exactly as it is recorded transmi tting data. For convenience, the
internally. (This is not strictly true for general term volume is used to refer to a
ASCII data sets - see -Information unit of aUXiliary storage, such as a reel
Interchange Codes- in this chapter.) It is of magnetic tape or a disk pack, without
possible for the same data set to be regard to its specific physical
processed at different times by either composition.
stream transmission or record transmission:
however, all items in the data set would I In datasets other those with Virtual
have to be in character form. IStorage Access Method (VSAM) organization,
the data items are arranged in distinct
stream-oriented transmission is ideal physical groupings called blocks. (This
for simple jobs, particularly those that discussion has to be s1ight1y modified for
use punched card input and have limited teleprocessing applications, where the data
output: a ~nimum of coding is required of set is in fact a queue of messages and the
the programmer, especially for punched card term -block- is not strictly app1icable.
input and printed output. Stream-oriented However, a message is similar to a block in
transmission also a1lows communication with that it may consist of one or more records.
the program at execution time from a Teleprocessing is d1SCUSSed in chapter 12.
termina1, if the program is being run under -Record-Oriented Transmission.-) These
the Time Sharing Option. However, compared blocks allow the data set to be transmitted

Chapter 10: Input and output 121

and processed in portions rather than being Translation between the two codes is
transmitted in its entirety before any performed by the operating system. Apart
processing is carried out. For processing
purposes, each block may consist of logical from the options specified in the
subdivisions called records, each of which ENVIRONMENT attribute, the same PL/I
contains one or more data items. A block program may be used to handle an ASCII data
can comprise part of a record, a single set as would be used for a standard EBCDIC
record, or several records. (Sometimes a data set. On output, translation from
block is called a physical record, because EBCDIC to ASCII is performed immediately
it is the unit of data that is physically before data is written from a buffer to
transmitted to and from a volume, and its external storage. On input, translation is
logical subdivisions are called logical pe~formed from ASCII to EBCDIC as soon as a
records.) buffer is filled with data.

When a block contains two or more records, In PL/I, only CHARACTER data may be
the records are said to be blocked. written onto an ASCII data set. Each
Blocked records permit more compact and character in the ASCII code is represented
efficient use of auxiliary storage. The by a seven-bit pattern and there are 128
use of blocked records can also improve the such patterns. In EBCDIC, each character
throughput of a program where a large has an eight-bit pattern, and there are 256
number of short records are to be possibilities. The ASCII set includes a
processed, by reducing the number of substitute character (the SUB control
physical input/output operations. character) that is used to represent EBCDIC
characters having no valid ASCII code. (In
In data sets with VSAM organization, the the American National Standards Institute
data items are arranged in control table, this is the character having the
intervals, which are in turn arranged in column 1, row 10 position.) Upon reading
control areas. For processing purposes, this data, the character would be
the data items within a control interval translated to the EBCDIC SUB character,
are arranged in logical records. A control which has the bit pattern 00111111.
interval may contain one or more logical
records, and a logical record may span two
or more control intervals. Further
information on the structure of VSAM data Files
sets is given in the Programmer's Guide for
the relevant compiler.
To allow a source program to deal primarily
Most data processing applications are with the logical aspects of data rather
concerned with logical records rather than than with its physical organization in a
Iblocks or control intervals. Therefore, data set, PL/I employs a symbolic
the input and output statements of PL/I representation of a data set called a file.
generally refer to logical records; this This symbolic representation determines how
allows the programmer to concentrate on the input and output statements access and
data to be processed, without being process the associated data set. Unlike a
directly concerned about its physical data set, however, a file has significance
organization in external storage. only within the source program and does not
exist as a physical entity external to the
program.

PL/I requires that an identifier which

INFORMATION INTERCHANGE CODES represents a file be declared with the FILE
attribute. Such an identifier may either
be a file constant or a file variable. A
In system/360 and System/310, the standard file variable is a data item to which a
code used to represent data, both in main file constant can be assigned. After
storage and on auxiliary storage, is EBCDIC assignment, a reference to the file
(extended binary-coded-decimal interchange variable has the same significance as a
code). In general, PL/I programs compiled reference to the assigned file constant.
by the optimizing or checkout compiler use Each data set processed by a PL/I program
EBCDIC to record all character data. The must be associated with a file constant
operating system does, however, support the identifier.
use of an alternative code, namely ASCII
(American Standard code for Information File constants: The individual
Interchange), to represent data on characteristics of eacb file are described
auxiliary storage, and such data sets may with keywords called file description
be read or created using PL/I. The support attributes. The following lists show the
is limited to data sets held on magnetic attributes that apply to each type of data
tape. transmission:

122 OS PL/I CKT AND OPT LRM PART I

 stream-oriented Transmission ACCTl FILE,
ACCT2 FILE,
FILE
STREAM
INPUT
OUTPUT
PRINT The following example shows how the
ENVIRONMENT VARIABLE attribute may be implied.

Record-Oriented Transmission DECLARE PAYREC(10) FILE;

FILE PAYREC(I), where I has a value from 1 to

RECORD 10, has the attribute FILE by explicit
INPUT declaration and the attribute VARIABLE by
OUTPUT implication of the dimension attribute (10)
UPDATE in the DECLARE statement.
SEQUENTIAL
DIRECT The attributes associated with a file
TRANSIENT constant fall into two categories:
BUFFERED alternative attributes and additive
UNBUFFERED attributes. An alternative attribute is
BACKWARDS one that is chosen from a group of
KEYED attributes. If no explicit or implicit
EXCLUSIVE declaration is given for one of the
ENVIRONMENT alternative attributes in a group and if
one of the alternatives is required, a
File variables: A file variable is an default attribute is assumed.
identifier that has the attributes FILE and
VARIABLE; i t cannot have any of the file An additive attribute is one that must
description attributes (except FILE). File be stated explicitly or is implied by
variables can be collected into arrays or another explicitly stated attribute. The
structures. Note that the VARIABLE additive attribute KEYED is implied by the
attribute can be implied by, for example, DIRECT attribute. The additive attribute
the dimension attribute. PRINT can be implied by the standard output
file name SYSPRINT. An additive attribute
File expressions.: A file expression can be can never be implied by default.
a reference to a file constant, a file
variable, or a function reference which ~ With the exception of the INTERNAL
returns a value with the FILE attribute. and EXTERNAL scope attributes, all the
alternative and additive attributes imply
A detailed description of each of these the FILE attribute. Therefore, the FILE
attributes appears in section I, attribute need not be specified for a file
·At~ributes.· The discussions below give a that has at least one of the alternative or
brief description of each of the file additive attributes already specified
description attributes and show how these explicitly.
attributes are declared for a file.

FILE ATTRIBUTE

The FILE attribute indicates that the

associated identifier is a file constant or
variable. For example, the identifier
MASTER is declared to be a file constant in
the following statement:

DECLARE MASTER FILE;

In the following statement, the ALTERNATIVE ATTRIBUTES

identifier ACCOUNT is declared to be a file
variable, and ACCT1, ACCT2, ••• are
declared to be file constants; the file PL/I provides five groups of alternative
constants may subsequently be assigned to file attributes. Each group (except scope,
the file variable. which is discussed in section I,
"Attributes") is discussed individually.
DECLARE ACCOUNT FILE VARIABLE, Following is a list of the groups.

Chapter 10: Input and Output 123

~\.
 Group Alternative Default SEQUENTIAL, DIRECT and TRANSIENT
~ Attributes Attribute Attributes

Osage STREAM I RECORD STREAM

The access attributes apply only to a file
Function INPUT I OUTPUT I UPDATE INPUT with the RECORD attribute, and describe how
the records in the file are to be accessed.
Access SEQUENTIAL I DIRECT I SEQUENTIAL
TRANSIENT The SEQUENTIAL attribute specifies that
records in the data set are to be accessed
Buffering BUFFERED I UNBUFFERED BUFFERED in physical sequence or in key sequence
(for I order. For certain data set organizations,
SEQUENTIAL la file with the SEQUENTIAL attribute can
and lalso be used for random access or for a
TRANSIENT Imixture of random and sequential access.
files); lIn this case, the file must have the
UNBUFFERED ladditive attribute KEYED.
(for
DIRECT The DIRECT attribute specifies that
files) records in a data set may be accessed in
any order. The location of the record in
Scope EXTERNAL I INTERNAL EXTERNAL the data set is determined by a character-
string "key": therefore, the DIRECT
The scope attributes are discussed in attribute implies the KEYED attribute. The
detail in section I, "Attributes." associated data set must be in a direct-
access volume.

The TRANSIENT attribute applies to files

used for teleprocessing applications. A
TRANSIENT file is associated with a data
STREAM and RECORD Attributes set which consists of a queue of messages.
The message queue data set contains
messages originating from and destined for
The STREAM and RECORD attributes describe remote terminals while in transit between a
the type of data transmission (stream- message control program and the PL/I
oriented or record-oriented) to be used in message processing program. The action of
input and output operations for the file. reading a record removes that record from
the data set. Access is sequential, but
The STREAM attribute causes a file to be the file must have the KEYED attribute
treated as a continuous stream of data since a key is used to identity the
items recorded only in character form. terminal concerned; a buffer is always
used, and so the file must also have the
The RECORD attribute causes a file to be BUFFERED attribute. Teleprocessing is
treated as a sequence of records, each discussed in chapter 12, "Record-Oriented
record consisting of one or more data items Transmission."
recorded in any internal form.

DECLARE MASTER FILE RECORD,

DETAIL FILE STREAM; BUFFERED and UNBUFFERED Attributes

The buffering attributes apply only to

RECORD files. The BUFFERED attribute
INPUT, OUTPUT, and UPDATE Attributes indicates that records transmitted to and
from a file must pass through an
intermediate internal-storage area. If
The function attributes determine the BUFFERED is specified, data transmission
direction of data transmission permitted is, in most cases, overlapped automatically
for a file. The INPUT attribute applies to with processing.
files that are to be read only. The OUTPUT
attribute applies to files that are to The UNBUFFERED attribute indicates that
create or, in some cases, extend data sets. a record in a data set need not pass
The UPDATE attribute (which applies only to through a buffer but may be transmitted
RECORD files) describes a file that is to directly to and from the main storage
be used for both input and output; i t associated with a variable. A file with
allows records to be inserted into an the UNBUFFERED attribute must not be
existing data set and other records already blocked. When UNBUFFERED is specified,
in that data set to be altered. data transmission is not overlapped

124 OS PL/I CKT AND OPT LRM PART I

automatically with processing; the with the RECORD attribute. It indicates
p,rogrammer must use the EVENT option to that records in the file can be accessed
achieve such overlapping. using one of the key options (KEY, KEYTO,
or KEYFROM) of data transmission statements
The UNBUFFERED attribute is assumed for or of the DELETE statement. Note that the
DIRECT files unless BUFFERED is specified KEYED attribute does not necessarily
explicitly. The UNBUFFERED attribute is indicate that the actual keys exist on, or
not allowed for TRANSIENT files. are to be written in, or are to be read
from the data set: consequently, it need
Note: Specification of UNBUFFERED does not not be specified unless one of the key
preclude the use of buffers. In nearly all options is to be used. The nature and use
cases, "hidden buffers" are required. of keys is discussed in detail in chapter
These cases are listed in the discussion of 12, "Record-Oriented Transmission."
the BUFFERED and UNBUFFERED attributes in
section I, "Attributes."

EXCLUSIVE Attribute

ADDITIVE ATTRIBUTES
When access to a record is restricted to
one task, the record is said to be locked
The additive attributes are: by that task. The EXCLUSIVE attribute,
which can be specified for DIRECT UPDATE
PRINT files only, provides a temporary locking
mechanism to prevent one task from
BACKWARDS interfering with an operation by another
task. It can be suppressed by the NOLOCK
KEYED option on the READ statement. Figure 10.1
shows the effects of various operations on
EXCLUSIVE an EXCLUSIVE file.

ENVIRONMENT (option-list) The EXCLUSIVE attribute will also lock a

record on a data set that is shared between
two PLiI jobs in a multi-programming
environment. The effect is as for sharing
PRINT Attribute between two tasks.

I The EXCLUSIVE attribute, the UNLOCK

The PRINT attribute applies only to files I statement, and the NOLOCK option of the
with the STREAM and OUTPUT attributes. It IREAD statement have no effect for a file
indicates that the file is eventually to be lassociated with a VSAM data set.
printed, that is, the data associated with
the file is to appear on printed pages,
although it may first be written on some
other medium. The PRINT attribute causes ENVIRONMENT Attribute
the initial byte of each record of the
associated data set to be reserved for a
printer control character. The ENVIRONMENT attribute provides
information that allows the compiler to
determine the method of accessing the data
associated with a file. It specifies the
BACKWARDS Attribute phySical organization of the data set that
will be associated with the file, and
indicates how the data set is to be
The BACKWARDS attribute applies only to handled.
SEQUENTIAL RECORD INPUT files and only to
data sets on magnetic tape. It indicates The general format of the ENVIRONMENT
that a file is to be accessed in reverse attribute is
order, beginning with the last record and
proceeding through the file until the first ENVIRONMENT (option-list)
record is accessed.
The ENVIRONMENT attribute can be given in a
file declaration or as an option of the
CLOSE statement. When ENVIRONMENT is
KEYED Attribute specified in a CLOSE statement, the only
option allowed is LEAVE or REREAD.

The KEYED attribute applies only to files The options appropriate to the two types of

Chapter 10: Input and output 125

r---------------------------------------------------------------------------------------,
Attempted I current state of Addressed Record

Operation
1---------------------------------------------------------------------
I Unlocked I Locked by this task I Locked by another task
~----------------------------------------------------- ---------------------------------
READ NOLOCK Proceed Proceed Wait for unlock

READ 11. Lock record Proceed Wait for unlock

12. Proceed

DELETE/REWRITE 11. Lock record 11. Proceed Wait for unlock

12. Proceed 12. Unlock1 record
13. Unlock 1 record I
UNLOCK No effect Unlock record No effect

CLOSE FILE IRaise ERROR if there are records locked by another task. Otherwise,
lunlock all records locked in this task, and proceed with closing.

Terminate Task IUnlock all records locked by task. Close file, if opened in this taskl
---------------------------------------------------------------------------------------1
1The unlocking occurs at the end of the operation, on completion of anyon-units I
entered because of the operation (that is, at the corresponding WAIT statement when I
the EVENT option has been specified). If the EVENT option has been specified with a I
READ statement, the operation is not completed until the corresponding WAIT statement I
is reached; in the meantime, no attempt to delete or rewrite the record should be I
made. I
L---------------------------------------------------------------------------------------J
Figure 10.1. Effect of operations on EXCLUSIVE files

data transmission are described in chapter file has not been closed before completion
11, ·Stream-Oriented Transmission,· and of the task in which the file was opened,
chapter 12, wRecord-Oriented Transmission,· the file is closed automatically upon
both in Part I. completion of the task.

When a file for stream input, sequential

input, or sequential update is opened, the
Opening and Closing Files associated data set is positioned at the
first record. When a BACKWARDS file is
opened, the associated data set is
Before the data associated with a file can positioned at the last record.
be transmitted by input or output
statements, certain file preparation
activities must occur, such as checking for
the availability of external storage media, OPEN Statement
positioning the media, and allocating
appropriate operating system support. Such
activity is known as opening a file. Also, Execution of an OPEN statement causes one
when processing is completed, the file must or more files to be opened explicitly. The
be closed. Closing a file involves .oPEN statement has the following basic
releasing the facilities that were format:
established during the opening of the file.
OPEN FILE (file-expression) (option group]
PL/I provides two statements, OPEN and [,FILE(file-expression) [option
CLOSE, to perform these functions. These group]] ••• ;
statements, however, are optional. If an
OPEN statement is not executed for a file, The option.list of the OPEN statement can
the file is opened automatically before the specify any of the alternative and additive
first data transmission statement for that attributes, except ENVIRONMENT, INTERNAL,
file is executed: in this case, the and EXTERNAL. Attributes included as
automatic file preparation consists of options in the OPEN statement are merged
standard system procedures that use with those stated in a DECLARE statement.
information about the file as specified in The same attributes need not be listed in
a DECLARE statement (or assumed from a both an OPEN statement and a DECLARE
contextual declaration derived from the statement for the same file, and, of
transmission statement). Similarly, if a course, there must be no conflict. other

126 OS PL/I CKT AND OPT LRM PART I

options that can only appear in the OPEN Notes:
statement are the TITLE option, used to
associate the file with the data set, and 1. INPUT and OUTPUT are deduced from READ
the PAGESIZE and LINESIZE options, used to and WRITE only if UPDATE has not been
specify the layout of a data set. The explicitly declared.
TITLE option is discussed below under
"Associating Data Sets with Files,· and the 2. If a GET statement contains a COPY
PAGESIZE and LINESIZE options, which apply option, execution of the GET statement
only to STREAM files, in chapter 11, causes implicit opening of either the
"Stream-oriented Transmission.- The option specified file as a STREAM OUTPUT file
list may precede the FILE (file expression) or the standard output file SYSPRINT.
specification.
An implicit opening caused by one of the
The OPEN statement is executed by above statements is equivalent to preceding
library routines that are loaded the statement with an OPEN statement that
dynamically at the time the OPEN statement specifies the deduced attributes.
is executed. Consequently, execution time
can be reduced if more than one file is
specified in the same OPEN statement, since
the routines need be loaded only once, Merging of Attributes
regardless of the number of files being
opened. Note, however, that such multiple
opening may require temporarily more There must be no conflict between t. he
internal storage than might otherwise be attributes specified in a file declaration
needed. and the attributes merged as the result of
opening the file. For example, the
For a file to be opened explicitly, the attributes INPUT and UPDATE are in
OPEN statement must be executed before any conflict, as are the attributes UPDATE and
of the input and output statements listed STREAM.
below in -Implicit Opening" are executed
for the file. After the attributes are merged, the
attribute implications listed below are
applied prior to the application of the
default attributes discussed eariier.
Implicit Opening Implied attributes can also cause a
conflict. If a conflict in attributes
exists after the application of default
An implicit opening of a file occurs when attributes, the UNDEFINEDFILE condition is
one of the statements listed below is raised.
executed for a file for which an OPEN
statement has not already been executed. Following is a list of merged attributes
The type of statement determines which and attributes that each implies after
unspecified alternatives are applied to the merging:
file when it is opened.
Merged Attributes Implied Attributes
The following list.contains the
statement identifiers and the attributes UPDATE RECORD
deduced from each:
SEQUENTIAL RECORD
statement Identifier Attributes Deduced
DIRECT RECORD, KEYED
GET STREAM, INPUT
BUFFERED RECORD
POT STREAM, OUTPUT
UNBUFFERED RECORD
READ RECORD, INPUT
PRINT OUTPUT, STREAM
WRITE RECORD, OUTPUT
BACKWARDS RECORD,
LOCATE RECORD, OUTPUT, SEQUENTIAL,
SEQUENTIAL, BUFFERED INPUT

REWRITE RECORD, UPDATE KEYED RECORD

DELETE RECORD, UPDATE EXCLUSIVE RECORD

UNLOCK RECORD, DIREC'I', The following two examples illustrate

UPDATE, EXCLUSIVE attribute merging for an explicit opening

Chapter 10: Input and output 127

using a file constant and a file variable. set is accomplished using job control
language, outside the PLII program. At the
File constant: time a file is opened, the PL/I file name
is aSSOCiated with the name (ddname) of a
DECLARE LISTING FILE STREAM; data definition statement (DD statement),
Which is, in turn, associated with the name
of a specific data set (dsname). Notethat
the direct association is with the n~me of
OPEN FILE (LISTING) PRINT; a DD statement, not with the name of the
data set itself.
Attributes after merge due to execution of
the OPEN statement are STREAM and PRINT.
Attributes after implication are STREAM, A ddname can be associated with a PL/I
PRINT, and OUTPUT. Attributes after file either through the file name or
default application are STREAM, PRINT, through the character-string value of the
OUTPUT, and EXTERNAL. expression in the TITLE option of the
associated OPEN statement.
File variable:
If a file is opened implicitly, or if no
DECLARE ACCOUNT FILE VARIABLE, TITLE option is included in the OPEN
(ACCT1,ACCT2, ••• ) FILE statement that causes explicit opening of
OUTPUT: the file, the ddname is assumed to be the
same as the file name. If the file name is
longer than eight characters, the ddname is
assumed to be composed of the first eight
ACCOUNT = ACCT1: characters of the file name.
OPEN FILE (ACCOUNT) PRINT;
~ Since external names are limited to
seven characters, an external file name of
more than seven characters is shortened
ACCOUNT = ACCT2: into a concatenation of the first four and
OPEN FILE (ACCOUNT) RECORD UNBUFFERED: the last three characters of the file name.
Such a shortened name is not, however, the
The file ACCT1 has been opened with name used as the ddname in-the associated
attributes (by explicit and implicit DO statement.
declaration) STREAM, EXTERNAL, PRINT, and
OUTPUT. The file ACCT2 has been opened Consider the following statements:
with attributes RECORD, EXTERNAL, OUTPUT,
SEQUENTIAL, and UNBUFFERED. 1. OPEN FILECMASTER):
The following example illustrates implicit 2. OPEN FILE(OLDMASTER):
opening.
3. READ FILECDETAIL) ••• :
DECLARE MASTER FILE KEYED INTERNAL
ENVIRONMENT (INDEXED F When statement number 1 is executed, the
RECSIZE(120) KEYLEN(S»: file name MASTER is taken to be the same as
the ddname of a DD statement in the current
job step. When statement number 2 is
executed, the name OLDMASTE is taken to be
READ FILE (MASTER) INTO the same as the ddname of a DD statement in
(MASTER_RECORD) KEYTO(MASTER_KEY): the current job step. (The first eight
characters of a file name form the ddname.
Attributes after merge due to the opening Note, that if OLDMASTER is an external
caused by execution of the READ statement name, it will be shortened by the compiler
are KEYED, INTERNAL, RECORD, and INPUT. to OLDMTER for use within the program.) If
Attributes after implication are KEYED, statement number 3 causes implicit opening
INTERNAL, RECORD, and INPUT (no additional of the file DETAIL, the name DETAIL is
attributes are implied). Attributes after taken to be the same as the ddname of a DD
default application are KEYED, INTERNAL, statement in the current job step.
RECORD, INPUT, SEQUENTIAL, and BUFFERED.
In each of the above cases, a
corresponding DO statement must appear in
the job stream: otherwise, the
Associating Data Sets with Files ONDEFINEDFILE condition would be raised.
The three DO statements would appear, in
part, as follows:
With batch processing under the OS, the
association of a file with a specific data 1. //MASTER DD DSNAME= •••

128 OS PL/I CRT AND OPT LRM PART I

 2. / /OLDMASTE DD DSNAME= ••• Use of the TITLE option allows a
programmer to choose dynamically, at open
3. //DETAIL DD DSNAME= ••• time, one among several data sets to be
associated with a particular file name.
If a file is opened explicitly by an Consider the following example:
OPEN statement that includes a TITLE
option, the ddname is taken from the TITLE DECLARE 1 INREC, 2 FIELD 1 ••• ,
option, and the file constant is not used 2 FILE_IOENT CHARACTER(8),
outside the program. The TITLE option DETAIL FILE INPUT ••• ,
appears in an OPEN statement in the MASTER FILE INPUT ••• :
following format:
OPEN FILECDETAIL):
OPEN FILECfile-expr) TITLECexpression):
READ FILE (DETAIL) INTO CINREC):
The expression in the TITLE option is
evaluated and, if necessary, converted to a OPEN FILE (MASTER) TITLE(FILE_IDENT):
character string, which is assumed to be
the ddname identifying the appropriate data Assume that the program containing these
set. If the character string is longer statements is used to process several
than eight characters, only the first eight different detail data sets, each of which
characters are used. The following OPEN has a different corresponding master data
statement illustrates how the TITLE option set. Assume, further, that the first
might be used: record of each detail data set contains, as
its last data item, a character string that
OPEN FILECDETAIL) TITLEC'DETAIL1'): identifies the appropriate master data set.
The following DD statements might appear in
If this statement were executed, there must the current job step:
be a DD statement in the current job step
with DETAILl as its ddname. It might //DETAIL DD DSNAME= •••
appear, in part, as follows:
/ /MASTERIA DO OSNAME=MASTERIA •••
//DETAILl DD DSNAME=DETAILA, •••
//MASTERIB DD OSNAME=MASTERlB •••
Thus, the data set DETAILA is associated
with the file DETAIL through the ddname / /MASTERlC 00 OSNAME=MASTERlC •••
DETAIL1.
In this case, MASTERlA, MASTERlB, and
Although a data set name represents a MASTER1C represent three different master
specific collection of data, the file name files. The first record of DETAIL would
can, at different times, represent entirely contain as its last item, either
different data sets. In the above example 'MASTERIA I , 'MASTERIB', or 'MASTER1C',
of the OPEN statement, the file DETAIL! is which is aSSigned to the character-string
associated with the data set named in the variable FILE IDENT. When the OPEN
DSNAME parameter of the DD statement statement is executed to open the file
DETAIL1. If the file were closed and MASTER, the current value of FILE IDENT
reopened, a TITLE option specifying a would be taken to be the ddname, and the
different ddname coUld be used, and then appropriate data set identified by that
the file could be associated with a ddname would be associated with the file
different data set. name MASTER.
If the file expression in the statement Another similar use of the TITLE option
which explicitly or implicitly opens the is illustrated in the follOWing statements:
file is not a file constant, then the DD
statement name must be the same as the DeL IDENT(3) CHAR(1)
!:!l!!! of the file expression. The INIT ( I A', I B " I C' ) :
following example illustrates how a DO DO I = 1 TO 3;
statement should be associated with the OPEN FILECMASTER)
value of a file variable. TITLEC'MASTERI I IIIDENTCI»:
PRICES = RPRICE:
OPEN FILECPRICES): CLOSE FILE (MASTER) ;
END:
The DO card should associate the data set
with the file constant RPRICE, which is the In this exampie, IDENT is declared as a
value of the file variable PRIC!S, thus: character-string array with three elements
having as values the specific character
//RPRICE DD DSNAME= ••• strings lA', IBI, and IC'. When MASTER is

Chapter 10: Input and output 129

opened during the first iteration of the CLOSE Statement
DO-group, the character constant 'MASTER1'
is concatenated with the value of the first
element of IDENT, and the associated ddname The basic torm of the CLOSE statement is:
is taken to be MASTER1A. After processing,
the file is closed, dissociating the file CLOSE FILE (file-expr) (ENVIRONMENT
name and the ddname. During the second ({LEAVEIREREAD})]
iteration of the group, MASTER is opened (,FILE (file-expr) (ENVIRONMENT
again. This time, however, the value of ({LEAVEIREREAD})]] ••• :
the second element of IDENT is taken, and
MASTER is associated with the ddname Executing a CLOSE statement dissociates the
MASTER1B. Similarly, during the final specified file from the data set with which
iteration of the group, MASTER is i t became associated when the file was
associated with the ddname MASTER1C. opened. The CLOSE statement also
dissociates from the file all attributes
established for it by the impliCit or
Note: The character set of the job control explicit opening process. If desired, new
language does not contain the break attributes may be specified for the file
character (_). Consequently, this constant in a subsequent OPEN statement.
character cannot appear in ddnames. Care Howe~er, all attributes expliCitly given to
should thus be taken to avoid using break the file constant in a DECLARE statement
characters among the first eight characters remain in effect.
of file names, unless the file is to be
opened with a TITLE option with a valid AS with the OPEN statement, closing more
ddname as its expression. The alphabetic than one file with a Single CLOSE statement
extender characters $, a, and #, however, can save execution time, but i t may require
are valid for ddnames, but the first the temporary use of more internal storage
character must be one of the letters A than would otherwise be needed.
through z.
The LEAVE and REREAD options are used to
control the disposition of magnetic tapes.
Use of a file variable also allows a
number of files to be manipulated at Note: Closing an already closed file or
various times by a Single statement. For opening an already opened file has no
example: effect apart fram increaSing the execution
time of the pro9ram.
DECLARE F FILE VARIABLE,
A FILE,
B FILE,
C FILE: STANDARD FILES

F=A: TWo standard files are provided that can be

LAB: READ FILE (F) ..... , used by any PL/I program. One is the
standard input file SYSIN, and the other is
the standard output file SYSPRINT. These
F=B: files need not be declared or opened
GO TO LAB: explicitly: a standard set of attributes is
applied automatically. For SYSIN, the
attributes are STREAM INPQT, and for
F=C: SYSPRINT they are STREAM OUTPUT PRINT.
GO TO LAB; Both file names, SYSIN and SYSPRINT, are
assumed to have the EXTERNAL attribute,
The statement labeled LAB is used to read even though SYSPRINT contains more than
the three files A, B, and C, each of which seven characters.
may be associated with a different data
set. Note that the files A, B, and C The FILE option need not be specified in
remain open after the READ statement bas GET and PUT statements when these files are
been executed in each instance. When a to be used. GET and PUT statements that do
number of data sets is to be accessed by a not name a file are equivalent to:
single statement, use of a file variable
rather than the TITLE option may improve GET FILE(SYSIN) ••• :
program efficiency by allowing a file for
each data set to remain open for as long as PUT FILE (SYSPRINT) •••. ;
i t is required by the program. Using the
TITLE option could necessitate closin9 and Any other references to SYSIN and SYSPRINT
reopening a file whenever i t is to be (such as in ON statements or in record-
associated with a new data set. oriented statements) must be stated

130 OS PL/I CKT AND OPT LRM PART I

explicitly. Even under the optimizing compiler, care
must be taken when SYSIN or SYSPRINT is
declared as anything other than a STREAM
Under the optimizing compiler, the file. The compiler causes, in effect, the
identifiers SYSIN and SYSPRINT are not identifier SYSIN to be inserted into each
reserved for the specific purposes GET statement in which no file constant is
described above. They can be used for explicitly stated and the identifier
other purposes besides identifying standard SYSPRINT to be inserted into each PUT
files. other attributes can be applied to statement in which nO file constant is
them, either explicitly or contextually, explicitly stated. consequently, the
but the PRINT attribute is applied following would be in error:
automatically to SYSPRINT when it is
declared or opened as a STREAM OUTPUT file
unless the INTERNAL attribute is declared DECLARE (SYSIN,SYSPRINT) FIXED
for it. DECIMAL (4,2);

Under the checkout compiler, the file

SYSPRINT is used for diagnostic messages,
and the file SYSIN may be used to hold the GET LIST (A,B,C);
source program. When the compiler uses one PUT LIST (D,E,F);
of the files, the file is opened with
certain attributes that may not be altered; The identifier SYSIN would be inserted into
the programmer consequently needs to the GET statement, and SYSPRINT in the PUT
exercise care if he declares SYSPRINT or statement. In this case, however, they
SYSIN explicitly. Full details of the would not refer to the standard files, but
restrictions are given in the programmer's to the fixed-point variables declared in
guide for the checkout compiler. the block.

Chapter 10: Input and output 131

 Chapter 11: Stream-Oriented Transmission

This chapter describes the input and output constants. The variables to which the data
statements used in stream-oriented items are to be assigned are specified by a
transmission. Those features that apply data list. Items are separated by a comma
equally to stream-oriented and record- and/or one or more blanks.
oriented transmission, including files,
file attributes, and opening and closing output: The data values to be transmitted
files, are described in chapter 10, "Input are specified by a variable, a constant, or
and Output". an expression that represents a data item.
Each data item placed in the stream is a
In stream-oriented transmission, a data character-string representation that
set is treated as a continuous stream of reflects the attributes of the variable.
data items in character form; within a Items are separated by one or more blanks.
program, block and record boundaries are Leading zeros of arithmetic data are
ignored. However, a data set is considered suppressed. Binary items are expressed in
to consist of a series of lines of data, decimal representation.
and each data set that is created or
accessed by stream-oriented transmission For PRINT files, data items are
has a line size associated with it. In automatically aligned on implementation-
general, a line is equivalent to a record defined preset tab positions. These
in the data set; however, the line size positions are 1, 25, 49, 73, 97, and 121,
does not necessarily equal the record size. but provision is made for the programmer to
alter these values.
There are three modes of stream~oriented
transmission: list-directed, data-
directed, and edit-directed. The
transmission statements used in all three DATA-DIRECTED TRANSMISSION
modes require the following information:

1. The name of the file associated with Data-directed transmission permits the user
the data set from which data is to De to transmit self-identifying data.
obtained or to which data is to be
assigned. Input: Each data item in the stream is in
the form of an assignment that specifies
2. A list of program variables to which both the value and the variable to which it
data items are to be assigned during is to be assigned. In general, values are
input or from which data items are to in the form of constants. Items are
be obtained during output. This list separated by a comma and/or one or more
is called a data list. On output in blanks. A semicolon must end ~ach group of
list- and edit-directed modes, the items to be accessed by a single GET
data list can also include statement. A data list in the GET
expressions. statement is optional, since the semicolon
determines the number of items to be
3. For edit-directed mode, the format of obtained from.the stream. (These rules are
each data item in the stream. slightly amended when the program is
initiated and data entered from a terminal
Under certain conditions some of this under TSO. Details are given in the
required information can be implied. following OS publications: Time
Sharing Option: PL/I Optimizing Compiler
and Time Sharing Option: PL/I Checkout
Compiler. )
LIST-DIRECTED TRANSMISSION
output: The data values to be transmitted
may be specified by an optional data list.
List-directed transmission permits the user Each data item placed in the stream has the
to read and write out data without having form of an assignment statement without a
to specify the format of the items in the semicolon. Items are separated by one or
stream. more blanks. The last item transmitted by
each PUT statement is followed by a
Input: In general, the data items in the semicolon. Leading zeros of arithmetic
stream are character strings in the form of data are suppressed. The character
optionally signed valid constants or in the representation of each value reflects the
form of expressions that represent complex attributes of the variable, except for

Chapter 11: Stream-oriented Transmission 133

binary items, which appear as values The following is a summary of the
expressed in decimal notation. stream-oriented data transmission
statements and their options:
If the data list is omitted, i t is
assumed to specify all variables that are STREAM INPUT:
known within the block containing the
statement and are permitted in data- GET ({FILE (file-expression)} I{STRING
directed output. (character-string-expression)}]
(data-specification]
For PRINT files, data items are (COPY(file-expression)]]
automatically aligned on the [SKIP (expression)]];
implementation-defined preset tab positions
referred to under "List-Directed Note that neither the COpy option nor SKIP
Transmission". option can be used with the STRING option
in a GET statement.

STREAM OUTPUT:
EDIT-DIRECTED TRANSMISSION
PUT ({FILE (file-expression)} I{STRING
(character-string-variable)}]
Edit-directed transmission permits the user (data-specification]
to specify the variables to which data is [SKIP (expression)]];
to be assigned or to specify data to be
transmitted, and to specify the format for Note that the SKIP option cannot be used
each item on the external medium. with the STRING option in a PUT statement.

Input: Data in the stream is a continuous STREAM OUTPUT PRINT:

string of characters; different data items
are not separated. The variables to which PUT [FILE (file-expression) ]
the data is to be assigned are specified by [data-specification]
a data list. Format items in a format list PAGE(LINE(eXpreSSiOn)]]
specify the number of characters that SKIP(expression)]
contain the value to be assigned to each [ LINE (expression) ;
variable and describe characteristics of
the data (for example, the assumed location The options may appear in any order. The
of a decimal point). (These rules are data specification can have one of the
slightly amended when the program is following forms:
initiated and data entered from a terminal
under TSO. Details are given in the [LIST] (data-list)
following OS publications: OS Time
Sharing Option: PL/I Optimizing Compiler DA'IA [(data-list)]
and OS Time Sharing Option: PL/I Checkout
Compiler. ) EDIT {(data-list) (format-list)} ••.

output: The data values to be transmitted SNAP

are defined by a data list. The format
that the data is to have in the stream is FLOW
defined by a format list.
ALL [(character-string-expression)]

If a GET or PUT statement includes a data

Data Transmission Statements list that is not preceded by one of the
keywords LIST, DATA, or EDIT, then LIST is
assumed. In such a statement, the data
Stream-oriented transmission uses only one list must immediately follow the GET or PUT
input statement, GET, and one output keyword; any options required must be
statement, PUT. A GET statement gets the specified after the data list.
next series of data items from the stream,
and a PUT statement puts a specified set of The SNAP, FLOW and ALL options in the data
data items into the stream. The variables specification cause information about the
to which data items are aSSigned, and the program to be put into the stream. These
variables or expressions from which they options can only be used in a PUT
are transmitted, are generally specified in statement. The information is provided
a data list with each GET or PUT statement. only if the PUT statement is processed by
The statements may also include options the PL/I checkout compiler; if such a PUT
that specify the origin or destination of statement is included in a program that is
the data or indicate where it appears in processed by the PL/I optimizing compiler,
the stream relative to the preceding data. these options are checked for syntax errors

134 OS PL/I CKT AND OPr LRM PART I

and then ignored. The use of the options in the input stream, On the file DPL. If
is described in chapter 15, "Execution-Time they were written, by default, on the
Facilities of the PL/I Checkout compiler". SYSPRINT file, they would appear in data-
directed format. Data items that are
The data specification can be omitted only Skipped on input, and not transmitted to
if one of the control options (PAGE, SKIP, internal variables, are copied intact into
or LINE) appears. Format lists may use any the output stream.
of the following format items:

A,B,C,E,F, which may be used with

P,R,X any STREAM or
STRING option
SKIP [(w)] which may be used with SKIP Option
COLUMN (w) any STREAM file

PAGE which may be used with The SKIP option specifies a new current
LINE (w) STREAM OUTPUT PRINT line (or record) within the data set. The
files parenthesized expression is converted to an
integer~. The data set is positioned to
The statements are discussed individually the start of the wth line (record) relative
in detail in section J, "Statements". to the current line (record).

For non-PRINT files, if the expression

is omitted or if w is not greater than
Options of Transmission Statements zero, a value of 1 is assumed. For PRINT
files, if ~ is less than or equal to zero,
the effect is that of a carriage return
FILE and STRING options with the same current line; if the
expression is omitted, 1 is assumed.

The FILE option specifies the file upon The SKIP option takes effect before the
which the operation is to take place. The transmission of any values defined by the
STRING option allows GET and PUT statements data specification, even if it appears
to be used to transmit data between after the data specification. Thus, the
internal storage locations rather than statement:
between internal and external storage. If
neither the FILE option nor the STRING PUT LIST(X,Y,Z) SKIP(3);
option appears in a GET statement, the
standard input file SYSIN is assumed; if causes the values of the variables X, Y,
neither option appears in a PUT statement, and Z to be printed on the standard output
the standard output file SYSPRINT is file SYSPRINT commencing on the third line
assumed. after the current line.

Examples of the use of the FILE option When printing at a terminal in

are given in some of the statements below. conversational mode, SKIP(w) with ~ greater
Chapter 13, "Editing and String Handling", than 3 is equivalent to SKIP(3). In other
illustrates the use of the STRING option. words, no more than three lines may be
skipped.

COpy Option

The COpy option may appear only in a GET PAGE Option

FILE statement. It specifies that the
stream is to be written, exactly as read,
onto the file named in the COpy The PAGE option can be specified only for
specification. If no file name is given, PRINT files. It causes a new current page
the default is the standard output file to be defined within the data set. The
SYSPRINT. For example, the statement: PAGE option takes effect before the
transmission of any values defined by the
GET FILE(SYSIN) DATA(A,B,C) COPY(DPL); data specification (if any>, even if it
appears after the data specification.
not only transmits the values assigned to
A, B, and C in the input stream to the When printing at a termdnal in
variables with these names, but also causes conversational mode, the PAGE option causes
them to be written, exactly as they appear three lines to be skipped.

Chapter 11: Stream-oriented Transmission 135

LINE option specification of a DO group) involving
any of these elements. For a data-
directed data specification, a data-
The LINE option can be specified only for list element can be an element, array,
PRINT files. It causes blank lines to be or structure variable. None of the
inserted so that the next line will be the names in a data-directed data list can
wth line of the current page, where w is be subscripted, locator-qualified, or
the va1ue of the parenthesized expression iSUB-defined, but qualified (that is,
when converted to an integer. The LINE structure-member), simple-defined, or
option takes effect before the transmission string-overlay-defined names are
of any values defined by the data allowed.
specification (if any), even if i t follows
the data specification. If both the PAGE 2. On output, a data-list element for
option and the LINE option appear in the edit-directed and list-directed data
same statement, the PAGE option is applied specifications can be one of the
first. For example, the statement following: an element expression, an
array expression, a structure
PUT FILE(LIST) DATA(P,Q,R) LINE(34) PAGE; expression, or a repetitive
specification involving any of these
causes the values of the variables P, Q, elements. For a data-directed data
and R to printed in data-directed format on specification, a data-list element can
a new page, commencing at line 34. be an element, array, Or structure
variable, or a repetitive
When printing at a terminal in specification involving any of these
conversational mode, the LINE option always elements. It must not be locator-
causes three lines to be skipped. qualified or iSUB-defined, but may be
qualified (that is, a member of a
structure), or simple-defined or
string-overlay-defined. Subscripts
Data Specifications are allowed for data-directed output.

3. The elements of a data list can be:

Data specifications are given in GET and
PUT 'statements to identify the data to be Input: Problem data: Arithmetic
transmitted. string

Output: Problem data: Arithmetic

String
DATA LISTS
Program control
data: Area
List-directed and edit-directed data Entry
specifications require a data list to Event
specify the data items to be transmitted. File
A data list is optional for a data-directed Label
data specification. Offset
Pointer
General format: Task
(data-list) Entry and label constants may not be
specified.
where -data list- is defined as:
A data list that specifies program-
element [,element] ••• control data can only be used in PUT
DATA or PUT LIST statements that are
Syntax .rules: to be processed by the checkout
compiler or PUT DATA statements that
The nature of the elements depends upon are to be processed under the
whether the data list is used for input or optimizing compiler. In the latter
for output. The rules are as follows: case, the name of the variable is
transmitted, but not its value.
1. On input, a data-list element for
edit-directed and list-directed 4. A data list must always be enclosed in
transmission can be one of the parentheses.
following: an element, array, or
structure variable, a pseudovariable 5. On output, a data list must not
other than STRING, or a repetitive contain more than 60 data items that
specification (similar to a repetitive are expressions.

136 OS PL/I CKT AND OPT LRM PART I

 r---------------------------------------------------------------------------------------,
I {Variable }
I(element (,elementl ••• DO = specificationl, specificationl ••• )
I pseudovariable
I
I
IA ·specification· has the following format:
II
II r- -,
II ITO expression2lBY expression3] I
II I I
II expression1 IBY expression3(TO expression2JI [WHILE(expression4)]1(UNTIL(expressionS)]
II I I
II I REPEAT expression6 I
L_ _J
II
II
111 The WHILE and UNTIL options may appear in either order
L------------------------------------------------_____ ----------------------------------J
Figure 11.1. General format for repetitive specifications

Repetitive Specification 3. Each repetitive specification must be

enclosed in parentheses, as shown in
the general format. Note that if a
repetitive.specification is the only
The general format of a repetitive element in a data list, two sets of
specification is shown in figure 11.1. outer parentheses are required, since
the data list must have one set of
Syntax rules: parentheses and the repetitive
specification must have a separate
1. An element in the element list of the set.
repetitive specification can be any of
those allowed as data-list elements as 4. As figure 11.1 shows, the
listed above. ·specification· portion of a
repetitive specification can be
2. The expressions in tbe specification, repeated a number of times, as in the
which are the same as those in a DO followi:ng form:
statement, are described as follows:
DO I =1 TO 4, 6 TO 10;
a. Each expression in the
specification is an element Repetitive specifications can be
expression. nested; that is, an element of a
,I.

repetitive specification can itself be

b. In the specification, expression1 a repetitive specification. Each DO
represents the starting value of portion must be delimited on the right
the control variable or with a right parenthesis (with its
pseudovariable. Expression3 matching left parenthesis added to the
represents the increment to be beginning of the entire repetitive
added to the control variable specification) •
after each repetition of data-list
elements in the repetitive When DO portions are nested, the
specification. Expression2 rightmost DO is at the outer level of
represents the terminating value nesting. For example, consider the
of the control variable. follOWing statement:
Expression6 is an expression that
is to be evaluated and assigned to GET LIST «(A(I,J) DO I = 1 TO 2)
the control variable after each DO J = 3 TO 4»;
repetition. Expression4 and
expressionS represent further Note the three sets of parentheses, in
conditions to control the number addition to the s~t used to delimit
of repetitions. The exact meaning the subscript. The outermost set is
of the specification is identical the set required by the data list~ the
to that of a DO statement with the next is that required by the outer
same specification. When the last repetitive specification. The third
specification is completed, set of parentheses is that required by
control passes to the next element the inner repetitive specification.
in the data list. This statement is equivalent to the

Chapter 11: Stream-oriented Transmission 131

 following nested DO-groups: directed transmission, a variable is
aSSigned a value, this new value is used if
DO J = 3 TO 4; the variable appears in a later reference
DO I = 1 TO 2; in the data list. For example:
GET LIST CA CI,J»;
END; GET LIST (N,(XCI) DO 1=1 TO N), J, K,
END; SUBSTR (NAME, J,K»;
It gives values to the elements of the When this statement is executed, data is
array A in the following order: transmitted and assigned in the following
order:
AC1,3), AC2,3), AC1,4), A(2,Q)
1. A new value is aSSigned to N.
Under the optimizing compiler, the
maximum permissible level of nesting 2. Elements are aSSigned to the array X
is 50. There is no such limdt under as specified in the repetitive
the checkout compiler. specification in the order
X(1),X(2), ••• XCN), with the new value
Note: Although the DO keyword is used in of N used to specify the number of
the repetitive specification, a items to be assigned.
corresponding END statement is not allowed.
3. A new value is assigned to J.
4. A new value is assigned to K.
Transmission of Data-List Elements
5. A substring of length K is assigned to
the string variable NAME, beqinning at
If a data-list element is of complex mode, the Jth character.
the real part is transmitted before the
imaginary part.
If a data-list element is an array
variable, the elements of the array are
transmitted in row-major order, that is,
with the rightmost subscript of the array
varying most frequently.
If a data-list element is a structure List-Directed Data Specification
variable, the elements of the structure are
transmitted in the order specified in the
structure declaration. General format for a list-directed data
specification, either input or output is as
For example, if a declaration is: follows:
DECLARE 1 A (10), 2 B, 2 C; (LIST] (data-list)
then the statement: The data list is described under -Data
Lists", above. The keyword LIST specifies
PUT FILE(X) LIST(A); the list-directed mode of transmission.
would result in the output being ordered as Examples of list-directed data
follows: specifications:
A.B(l) A.C(l) A.B(2) A.C(2) A.B(3) LIST (CARD, RATE, DYNAMIC_FLOW)
A.C(3) ••• etc.
LIST «TBICKNESS(DISTANCE)
If, however, the declaration had been: DO DISTANCE = 1 TO 1000»
DECLARE 1 A, 2 B(lO), 2 CCIO); LIST CP, Z, N, R)
then the same PUT statement would result in LIST CA*B/C, (X+Y)**2)
the output being ordered as follows:
The specification in the last example can
A.B(l) A.B(2) A.B(3) ••• A.B(10) be used only for output, since it contains
A.C(l) A.C(2) A.C(3) ••• A.C(10) values specified by expressions. Such
expressions are evaluated when the
If, within a data list used in an input statement is executed, and the result is
statement for list-directed or edit- placed in the stream.

138 OS PL/I CRT AND OPr LRM PART I

 ,,
List-Directed Data in the stream Ithe one immediately following the comma:
Xbb,bbbXX
Problem data in the stream, either input or
output, is of character data type and has
one of the following general forms:
,I
I t

If the items are separated by blanks

,only, the first item scanned will be the
[+1-] arithmetic-constant
character-string-constant
,,
Inext non-blank character:
XbbbbXXX
I t
bit-string-constant 1
, unless the end of the record is
[+1-] real-constant{+I-limaginary-constant I encountered, in which case the file is
positioned at the end of the record:
A string constant must be one of the two
permitted forms listed above; iteration and Xbb-bbXXX
string repetition factors are not allowed. t
A blank must not follow a sign preceding a
real constant, and must not precede or However, if the end of the record
follow the central + or - in complex immediately follows a non-blank character
expressions. (other than a comma), and the following
record begins with blanks, the file is
The format of program control data is positioned at the first non-blank character
described in chapter 15, RExecution-time in the following record:
Facilities of the Checkout Compiler-.
X-bbbXXX
t

List-Directed Input Format If the record does terminate with a

comma, the succeeding record is not read in
until the next GET statement requires it.
When the data named is an array, the data
consists of constants, the first of which If the data is a character-string
is assigned to the first element of the constant, the surrounding quotation marks
array, the second constant to the second are removed, and the enclosed characters
element, etc., in row-major order. are interpreted as a character string.
A structure name in the data list If the data is a bit-string constant,
represents a list of the contained element enclosing quotation marks and the trailing
variables and arrays in the order specified character B are removed, and the enclosed
in the structure description. characters are interpreted as a bit string.
On input, data items in the stream must If the data is an arithmetic constant or
be separated either by a blank or by a complex expression, it is interpreted as
comma. This separator may be surrounded by coded arithmetic data with the base, scale,
an arbitary number of blanks. A null field mode, and precision implied by the
in the stream is indicated either by the constant.
first non-blank character in the data
stream being a comma, or by two commas
separated by an arbitrary number of blanks.
A null field specifies that the value of List-Directed output Format
the associated item in the data list is to
remain unchanged.
The values of the element variables and
The transmission of the list of expressions in the data list are converted
constants on input is terminated by to character representations and
expiration of the list or at the end of the transmitted to the data stream. The
file. In the former case, the file is conversions follow the normal rules for
pqsitioned in the stream ready for the next arithmetic to character conversions, except
GET statement. More than one blank can that floating-point items are not rounded.
separate two data items, and a comma
separator may be preceded or followed by A blank separabes successive data items
one or more blanks. transmitted. (For PRINT files, items are
separated according to program tab
I If the items are separated by a comma, settings.)
,then the first character to be scanned when
Ithe next GET statement is executed will be The length of the data field placed in

Chapter 11: stream-oriented Transmission 139

the stream is a function of the attributes On input, if the stream contains an
of the data item, including precision and unrecognisable element-variable or an
length. Detailed discussions of the unknown name, the NAME condition is
conversion rules and their effect upon raised. If the assumed data list
precision are listed in the descriptions of contains a name that is not included
conversion to character type in section F, in the stream, the value of the
-Data Conversion and Expression associated variable remains unchanged.
Evaluation".
On output, all items in the assumed
Binary data items are converted to data list are transmitted. Where two
decimal notation before being placed in the or more blocks containing the PUT
stream. statement each have declarations of
items which have the same name, all
For numeric character values, the the items will be transmitted, the
character-string value is transmitted. known item appearing first.

Bit strings are converted to character 3. Recognition of a semicolon or an end-

representation of bit-string constants, of-file in an input stream causes
consisting of the characters 0 and 1, transmission to cease, whether or not
enclosed in quotation marks, and followed a data list is specified. On output,
by the letter B. a semicolon is written into the stream
after the last data item transmitted
Character strings are written out as by each PUT statement.
follows. If the file does not have the
attribute PRINT, enclosing quotation marks
are supplied, and contained single
quotation marks or apostrophes are replaced Data-Directed Data in the Stream
by two quotation marks. The field width is
the current length of the string plus the
number of added quotation marks. If the The data in the stream associated with
file has the attribute PRINT, enclosing data-directed transmission is in the form
quotation marks are not supplied, and of a list of element assignments. For
contained single quotation marks or problem data, they have the following
apostrophes are unrnodi~ied. The field general format (the optionally signed
width is the current length of the string. constants, like the variable names and the
equal signs, are in character form):

element-variable = data value

[{bl,Jelement-variable = data
Data-Directed Data Specification value] ••• ;

General rules for problem data:

General format for a data-directed data
specification, either for input or output, 1. The element variable may be a
is as follows: subscripted name. Subscripts must be
optionally signed decimal integer
DATA[(data-list)] constants.

General rules: 2. On input, the element assignments may

be separated by either a blank (~ in
1. The data list is described in "Data the above format) or a comma.
Lists" in this chapter. For input, Redundant blanks are ignored. On
the data list cannot contain output, the assignments are separated
subscripted names. Names of structure by a blank. (For PRINT files, items
elements in the data list need only are separated according to program tab
have enough qualification to resolve settings.)
any ambiguity; full qualification is
not required. On input, if the stream 3. Each data value in the stream has One
contains an unrecognisable element- of the forms described for list-
variable or a name that does not have directed transmission.
a counterpart in the data list, the
NAME condition is raised. 4. On input a semi-colon following an
element assignment terminates the list
2. Omission of the data list implies that of element assignments to be
a data list is assumed. This assumed transmitted by the execution of a
data list contains all the names that single GET DATA statement, and thereby
are known to the block and to any determines the number of element
containing blocks. aSSignments that are actually

140 as PL/I CKT AND OPT LRM PART I

 transmitted by a particular statement. list, where A, B, C, and D are names
On output a semi-colon is transmitted of element variables:
on completion of a PUT DATA statement.

5. Locator qualifiers cannot appear in DATA (B, A, c, D)

the stream. The locator qualifier
declared with the based variable is This data list may be associated with
used to establish the generation. the following input data stream:
Based variables that have not been
declared with a locator qualifier A= 2.5, B= .0047, D= 125, Z= 'ABC';
cannot be transmitted.
Note: C appears in the data list but
Under the optimizing compiler, the not in the stream: its value remains
following restrictions apply to based unaltered. Z, which is not in the
variables in the data list: data list, raises the NAME condition.

a. The variable must not be based on 3. If the data list includes the name of
an OFFSET variable. an array, subscripted references to
that array may appear in the stream
b. The variable must not be a member although subscripted names cannot
of a structure declared with the appear in the data list. The entir~
REFER option. array need not appear in the stream;
only those elements that actually
c. The pointer on which the variable appear in the stream will be assigned.
is based must not be based, If a subscript is out of range, or is
defined, or a parameter, and i t missing, the NAME condition is raised.
must not be a member of an array
or structure. Let X be the name of a two-dimensional
array declared as follows:
6. Under the optimizing compiler, defined
variables in the data list must not DECLARE X (2,3);
have been defined:
Consider the following data list and
a. On a controlled variable. input data stream:

b. On an array with one or more Data Specification Input Data Stream

adjustable bounds.
DATA (X) X(l,l)= 7.95,
c. With a POSITION attribute that X(1,2)= 8085,
specifies other than a constant. X(1,3)= 73:

Although the data list has only the

name of the array, the associated
Data-Directed Data Specification for input stream may contain values for
Input individual elements of the array. In
this case, only three elements are
assigned: the remainder of the array
General rules for data-directed input: is unchanged.

1. If the data specification does not 4. If the data list includes the names of
include a data list, the names in the structure elements, then fully
stream may be any names known at the qualified names must appear in the
point of transmission. Qualified stream, although full qualification is
names in the input stream must be not required in the data list.
fully qualified. The name must not Consider the following structures:
contain mOre than 256 characters.
DECLARE 1 CARDIN, 2 PARTNO, 2 DESCRP,
2. If a data list is used, each element 2 PRICE, 3 RETAIL, 3 WHSL;
of the data list must be an element,
array, or structure variable. Names If i t is desired to read a value for
cannot be subscripted, but qualified CARDIN. PRICE. RETAIL, the data
names are allowed in the data list. specification and input data stream
All names in the stream should appear could have the following forms:
in the data list; however, the order
of the names need not be the same, and Data Specification Input Data Stream
the data list may include names that
do not appear in the stream. For DATA (CARDIN.RETAIL) CARDIN. PRICE.
example, consider the following data RETAIL = 4.28;

Chapter 11: Stream-oriented Transmission 141

 5. Interleaved subscripts cannot appear blank would follow the equal sign. In
in qualified names in the stream. All conversion from coded arithmetic to
subscripts must be moved all the way character, leading zeros are converted
to the right, following the last name to blanks, and up to three additional
of the qualified name. For example, blanks may appear at the beginning of
assume that Y is declared as follows: the field.

DECLARE 1 Y{5,5),2 A(10),3 B,

3 C, 3 D; 3. Subscript expressions that appear in a
data list are evaluated and replaced
An element name would have to appear by their values.
in the stream as follows:

Y.A.B(2,3,8)= 8.72 4. Items that are part of a structure

appearing in the data list are
The name in the data list could not transmitted with the full
contain the subscript. qualification, but subscripts follow
the qualified names rather than being
interleaved. For example, if ada~a
list is specified for a structur"e
Data-Directed Data Specification for element transmitted under data-
Output directed output as follows:

DATA (Y(1,-3).Q)
General rules for data-directed output:
the associated data field in the
1. An element of the data list may be an output stream is of the form:
element, array, or structure variable,
or a repetitive specification Y.Q{1,-3)= 3.756;
involving any of these elements or
further repetitive specifications. 5. Structure names in the data list are
Subscripted names can appear. For interpreted as a list of the contained
problem data, the names appearing in element or elements, and any contained
the data list, together with their arrays are treated as above.
values, are transmitted in the form of
a list of element assignments For example, consider the follOWing
separated by blanks and terminated by structure:
a semicolon. (For PRINT files, items
are separated according to program tab 1 A, 2 B, 2 C, 3 D
settings.)
If a data list for data-directed
The rules applying to program control output is as follows:
data are given in chapter 15,
"Execution-time Facilities of the DATA (A)
Checkout Compiler."
and the values of Band Dare 2 and
2. Array variables in the data list are 17, respectively, the associated data
treated as a list of the contained fields in the output stream would be
subscripted elements in row-major as follows:
order.
A.B= 2 A.C.D= 17;
Consider an array declared as follows:
6. In the following cases, data-directed
DECLARE X (2,4) FIXED; output is not valid for subsequent
data-directed input:
If X appears in a data list as
follows: a. When the character-string value of
a riumeric character variable does
DATA (X) not represent a valid optionally
Signed arithmetic constant. For
on output, the output data stream example, this is always true for
would have the form: complex numeric character
variables.
X(l,l)= 1 X(1,2)= 2 X(1,3)= 3
X{1,4)= 4 X(2,1)= 5 X,(2,2)= 6 b. When a program control variable is
X(2,3)= 7 X(2,4)= 8; transmitted such a variable must
not be specified in an input data
~ In actual output, more than one list.

142 OS PL/I CRT AND OPTLRM PART I

r---------------------------------------------------------------------------------------,
AB: PROCEDURE:
Input Stream
DECLARE (A(6), B(7» FIXED;
B(l)=l, B(2)=2, B(3)=3,
GET FILE (X) DATA (B):
B(4)=1, BlS)=2, B(6)=3, B(1)=4;
00 I = 1 TO 6:
A (I) = B (1+1) + B (I):
output Stream
END:
A(l)= 3 A(2)= S A(3)= 4 A(4)= 3
PUT FILE (Y) DATA (A):
A(S)= S A(6)= 1:
END AB;
L---------------------------------------------------------------------------------------J
Figure 11.2. Example of data-directed transmission (both input and output)

Length of Data-Directed output Fields 1. The data list, which must be enclosed
in parentheses, is described in "Data
Lists", above. The format list, which
The length of the data field on the also must be enclosed in parentheses,
external medium is a function of the contains one or more format items.
attributes declared for the variable and, There are three types of format items:
since the name is also included, the length data format items, which describe data
of the fully qualified subscripted name. in the stream: control format items,
The field length for output items converted which describe page, line, and spacing
from coded arithmetic data, numeric operations; and remote format items,
character data, and bit-string data is the which specify the label of a separate
same as that for list-directed output data, statement that contains the format
and is governed by the rules for data list to be used. Format lists and
conversion to character type as described format items are discussed in more
in section F, "Data Conversion and detail in "Format Lists", below.
Expression Evaluation".
~ Program-control variables
For character-string data, the contents cannot be specified in data lists for
of the character string are written out edit-directed transmission.
enclosed in quotation marks. Each
quotation mark contained within the 2. For input, data in the stream is
character string is represented by two considered to be a continuous string
successive quotation marks. of characters not separated into
indiVidual data items. The number of
characters for each data item is
specified by a format item in the
Example format list. The characters are
treated according to the associated
format item.
In the example shown in figure 11.2, A is
declared as a one-dimensional array of six 3. For output, the value of each item in
elements: B is a one-dimensional array of the data list is converted to a format
seven elements. The procedure calculates specified by the associated format
and writes out values for All) = B(I+1) + item and placed in the stream in a
B(l). field whose width also is specified by
the format item.

4. For either input or output, the first

Edit-Directed Data Specification data format item is associated with
the first item in the data list, the
second data format item with the
General format for an edit-directed data second item in the data list, and so
specification, either for input or output, forth. If a format list contains
is as follows: fewer format items than there are
items in the associated data list, the
EDIT {(data-list) (format-list)} format list is re-used; if there are
[(data-list) (format-list)] ••• excessive format items, they are

Chapter 11: Stream-oriented Transmission 143

 ignored. Suppose a format list characters may be blanks). Note that
contains five data format items and values represented by expressions and
its associated data list specifies ten constants can appear in output data lists
items to be transmitted. Then the only.
sixth item in the data list will be
associated with the first data format
item, and so forth. suppose a format
list contains ten data format items Format Lists
and its associated data list specifies
only five items. Then the sixth
through the tenth format items will be Each edit-directed data specification must
ignored. be associated with a format list.

5. An array or structure variable in a General format:

data list is equivalent to n items in
the data list, where n is the number (format-list)
of element items in the array or
structure, each of which will be where "format list" is defined as:

6.
associated with a separate use of a
data format item.

If a control format item is

item

n item
item
n item
1 •••
encountered, the control action is
executed, and the data list item is n (format-list) [: n (format-list)
paired with the next format item.

7. The specified transmission is complete Syntax rules:

when the last item in the data list
has been processed using its 1. Each "item" represents a format item
corresponding format item. Subsequent as described below.
format items, including control format
items, are ignored. 2. The letter n represents an iteration
factor, which is either an expression
8. On output, data items are not enclosed in parentheses or an unsigned
automatically separated, but decimal integer constant. If it is
arithmetic data items generally the latter, a blank must separate the
include leading blanks because of data constant and the following format
conversion rules and zero suppression. item. The iteration factor specifies
that the associated format item or
Examples: format list is to be used n successive
times. A zero iteration factor
GET EDIT (NAME, DATA, SALARY) specifies that the associated format
(A(N), X(2), A(6), F(6,2»; item or format list is to be skipped
and not used (the data list item will
PUT EDIT ('INVENTORY=' IIINUM,INVCODE) be associated with the next data
(A,F(5»; format item). If an expression is
used to represent the iteration
The first example specifies that the first factor, it is evaluated and converted
N characters in the stream are to be to an integer, which must be non-
treated as a character string and aSSigned negative, once for each set of
to NAME; the next two characters are to be iterations. The associated format
skipped: the next six are to be aSSigned to item or format list is that item or
DATA in character format: and the next six list of items immediately to the right
characters are to be considered as an of the iteration factor.
optionally signed decimal fixed-point
constant and aSSigned to SALARY. General rule:

The second example specifies that the There are three types of format items:
character string 'INVENTORY=' is to be data format items, control format items,
concatenated with the value of INUM and and the remote format item. Data format
placed in the stream in a field whose width items specify the external forms that data
is the length of the resultant string. fields are to take.' Control format items
Then the value of INVCODE is to be specify the page, line, column, and spacing
converted to character to represent an operations. The remote format item allows
optionally signed decimal fixed-point format items to be specified in a separate
integer constant and is then to be placed FORMAT statement elsewhere in the block.
in the stream right-adjusted in a field
with a width of five characters (leading Detailed discussions of the various

144 OS PL/I CRT AND OPT LRM PART I

types of format items appear in section E, values expressed in decimal digits. The F
-Edit-Directed Format Items-. The and E format items may then be used to
following discussions show how the format access them, and the values will be
items are used in edit-directed data converted to binary representation upon
specifications. assignment. On output, binary items are
converted to decimal values and the
Data Format Items associated F or E format items must state
the field width and pOint placement in
On input, each data format item terms of the converted decimal number.
specifies the number of characters to be
associated with the data item and how to The following examples illustrate the
interpret the external data. The data item use of format items:
is assigned to the associated variable
named in the data list, with necessary 1. GET FILE (INFILE) EDIT (ITEM) (A(20»:
conversion to conform to the attributes of
the variable. On output, the value of the This statement causes the next 20
associated element in the data list is characters in the file called INFILE
converted to the character representation to be assigned to ITEM. The value is
specified by the format item and is automatically transformed from its
inserted into the data stream. character representation specified by
the format item A(20), to the
There are six data format items: fixed- representation specified by the
point (F), floating-point (E), complex (C), attributes declared for ITEM.
picture (P), character-string (A), and bit-
string (B). They are, in general, Note: If the data list and format list
specified as follows: were-used for output, the length of a
string item need not be specified in
F (w[,d[,p]]) the format item if the field width is
to be the same as the length of the
E (w,d[,s]) string, that is, if no blanks are to
follOW the string.
C (real-format-item [,real-format-item])
2. PUT FILE (MASKFLE) EDIT (MASK) (B);
P 'picture-specification'
Assume MASK has the attribute BIT
A lew)] (25); then the above statement writes
the value of MASK in the file called
B lew)] MASKFLE as a string of 25 characters
consisting of O's and l's. A field
In this list, the letter ~ represents an width specification can be given in
expression that specifies the number of the B format item. It must be stated
characters in the field. The letter d for input. ----
specifies the number of digits to the-right
of a decimal point: i t may be omitted for 3. PUT EDIT (TOTAL) (F(6,2»;
fixed-point integers. The real format item
of the complex format item represents the Assume TOTAL has the attributes FIXED
appearance of either an F, E or P format (4,2); then the above statement
item. The picture specification of the P specifies that the value of TOTAL is
format item can be either a numeric to be converted to the character
character specification or a character- representation of a fixed-point number
string specification~ On output, data and written into the standard output
associated with E and F format items is file SYSPRINT. A decimal point is to
rounded if the internal precision exceeds be inserted before the last two
the external precision. numeric characters, and the number
will be right-adjusted in a field of
A third specification (E) is allowed in six characters. Leading zeros will be
the F format item: it is a scaling factor. changed to blanks, and, if neces~ary,
A third specification (!) is allowed in the a minus sign will be placed to the
E format item to specify the number of left of the first numeric character.
digits that must be maintained in the first
subfield of the floating-point number. The conversion from internal decimal
These specifications are discussed in fixed-point type to character type is
detail in section E, -Edit-Directed Format performed according to the normal
Items-. rules for conversion. Extra
characters may appear as blanks
~ Fixed-point binary and floating-pOint preceding the number in the converted
binary data items must always be string. And, since leading zeros are
represented in the input stream with their converted to blanks, additional blanks

Chapter 11: Stream-oriented Transmission 145

 may precede the number. If a decimal 1. GET EDIT (NUMBER, REBATE)
point or a minus sign appears, either (A(S), xeS), A(S»;
will cause one leading blank to be
replaced. This statement treats the next 15
characters from the standard input
file, SYSIN, as follows: the first
In edit-directed output, the field five characters are assigned to
width specification in the format item NUMBER, the next five characters are
(in this case, the 6 in the F(6,2) spaced over and ignored, and the
format item) can be used to truncate remaining five characters are assigned
leading zeros. In this specification, to REBATE.
one zero is truncated. TOTAL would be
converted to a character string of 2. GET FILE(IN) EDIT (MAN, OVERTIME)
length seven. If all four digits of (SKIP(l), A(6), COLUMN(60), F(4,2»;
the converted number are greater than
zero, the number, with its inserted This statement positions the data set
decimal point, will require five digit aSSOCiated with file IN to a new line;
positions; if the number is negative, the first six characters on the line
another digit position will be are assigned to MAN, and the four
required for the minus Sign. characters beginning at character
Consequently, the F(6,2) specification position 60 are assigned to OVERTIME.
will always allow all digits, the
point, and a possible sign to appear, 3. PUT FILE (OUT) EDIT (PART, COUNT)
but will remove the extra blank by (A(4), X(2), F(S»;
truncation.
This statement places in the file
4. GET FILE(A) EDIT (ESTIMATE) (E(10,6»; named OUT four characters that
represent the value of PART, then two
This statement obtains the next ten blank characters, and finally five
characters from the file called A and characters that represent the fixed-
interprets them as a floating-point point value of COUNT.
decimal number. A decimal point is
assumed before the rightmost six 4. The'following examples show the use of
digits of the mantissa. An actual the COLUMN, LINE, PAGE, and SKIP
point within the data can override format items in combination with one
this assumption. The value of the another.
number is converted to the attributes
of ESTIMATE and assigned to this PUT EDIT ('QUARTERLY STATEMENT')
variable. (PAGE, LINE(2), A(19»;
PUT EDIT
5. GET EDIT (NAME, TOTAL) CACCT#, BOUGHT, SOLD,
(P'AAAAA',P'9999'); PAYMENT, BALANCE)
(SKIP(3), A(6), COLUMN(14),
When this statement is executed, the F(1,2), COLUMN(30), F(1,2),
standard input file SYSIN is assumed. COLUMN(45), F(1,2),
The first five characters must be COLUMN(60), F(1,2»;
alphabetic or blank and they are
assigned to NAME. The next four The first PUT statement specifies that
characters must be nonblank numeric the heading QUARTERLY STATEMENT is to
characters and they are assigned to be written on line two of a new page
TOTAL. in the standard output file SYSPRINT.
The second statement specifies that
Control Format Items two lines are to be skipped (that is,
wskip to the third following line W )
The control format items are the spacing and the value of ACCT# is to be
format item (X), and the COLUMN, LINE, written, beginning at the first
PAGE, and SKIP format items. The spacing character of the fifth line; the value
format item specifies relative spacing in of BOUGHT, beginning at character
the data stream. The PAGE and LINE format position 14; the value of SOLD,
items can be used only with PRINT files beginning at character position 30;
and, consequently, can only appear in POT the value of PAYMENT, beginning at
statements. All but PAGE generally include character position 45; and the value
expressions. LINE, PAGE, and SKIP can also of BALANCE at character position 60.
appear separately as options in the PUT
statement; SKIP can appear as an option in Note: Control format items are executed at
the GET statement. The following examples ~ime they are encountered in the format
illustrate the use of the control format list. Any control format list that appears
items: after the data list is exhausted will have

146 OS PL/I CRT AND OPT LRM PART I

no effect. PRINT Files

Remote Format Item The PRINT attribute can be applied only to

a STREAM OUTPUT file. It indicates that
the data in the file is ultimately intended
The remote format item (R) specifies the to be printed (although it may first be
label of a FORMAT statement (or a label written on a medium other than the printed
expression whose value is the label of a page). The first data byte of each record
FORMAT statement) located elsewhere; the of a PRINT file is reserved for an American
FORMAT statement and the GET or PUT National Standard (ANS) printer control
statement specifying the remote format item cha~acter; the compiler causes the control
must be internal to the same block. The characters to be inserted automatically
FORMAT statement contains the remotely when statements containing the control
situated format items. This facility options and format items PAGE, SKIP, and
permits the choice of different format LINE are executed.
specifications at execution time, as
illustrated by the following example: The layout of a PRINT file can be
controlled by the use of the options and
DECLARE SWITCH LABEL; format items listed in figure 11.3. (Note
GET FILE(IN) LIST(CODE); that LINESIZE, SKIP, and COLUMN can also be
IF CODE = 1 used for non-PRINT files.) LINESIZE and
THEN SWITCH = Ll; PAGESIZE establish the dimensions of the
ELSE SWITCH = L2; printed area of the page, excluding
GET FILE(IN) EDIT (W,X,Y,Z) footings. The LINESIZE option specifies
(R(SWITCH»; the maximum number of characters to be
Ll: FORMAT (4 F(S,3»; included in each printed line; if it is not
L2: FORMAT (4 E(12,6»; specified for a PRINT file, a default value
of 120 characters is assumed (but there is
SWITCH has been declared to be a label no default for a non-PRINT file). The
variable; the second GET statement can be PAGESIZE option specifies the maximum
made to operate with either of the two number of lines to appear in each printed
FORMAT statements. page; if it is not specified, a default
value ot 60 lines is assumed. Consider the
Expressions in Format Items following example:
The ~, E, ~, and ~ specifications in OPEN FILE(REPORT) OUTPUT STREAM PRINT
data format items, as well as the PAGESIZE(5S) LINESIZE(110);
specifications in control format items,
need not be decimal integer constants. This statement opens the file REPORT as a
Expressions are allowed. They may be PRINT file. The specification PAGESIZE(55)
variables or other expressions. indicates that each page should contain a
maximum of 55 lines. An attempt to write
A value read into a variable can be used on a page after 55 lines have already been
in a format item associated with another written (or skipped) will raise the ENDPAGE
variable later in the data list. condition. The standard system action for
the ENDPAGE condition is to skip to a new
PUT EDIT (NAME,NUMBER,CITY) page, but the programmer can establish his
(A(N),A(N-4),A(10»; own action through use of the ON statement.
GET EDIT (M,STRING A,I,STRING B) The ENDPAGE condition is raised only
(F(2),A(M),X(M),F(2),A(I»; once per page. consequently, printing can
be continued beyond the specified PAGESIZE
In the first example, the value of NAME is after the ENDPAGE condition has been raised
inserted in the stream as a character the first time. This can be useful, for
string left-adjusted in a field of N example, if a footing is to be written at
characters; NUMBER is left-adjusted in a the bottom of each page. For example:
field of N-4 characters; and CITY is left-
adjusted in a field of 10 characters. In ON ENDPAGE(REPORT) BEGIN;
the second example, the first two PUT FILE (REPORT) SKIP LIST
characters are assigned to M. The value of (FOOTING);
M is then taken to specify the number of N =N + 1;
characters to be assigned to STRING_A and PUT FILE (REPORT) PAGE LIST
also to specify the number of characters to (-PAGE 'liN);
be ignored before two characters are PUT FILE(REPORT) SKIP (3);
assigned to I, whose value then is used to END;
specify the number of characters to be
assigned to STRING_B. Assume that REPORT has been opened with

Chapter 11: Stream-oriented Transmission 147

r---------------------------------------------------------------------------------------,
I Edit-directed I statement in I I
Option I format item I whic).'l option I Effect I
I I or format I I
I litem appears I I

LINESIZE(w)1. OPEN Establishes line width

PAGESIZE(w) OPEN Establishes page width

PAGE PAGE PUT Skip to new page

LINE(w) LlNE(w) PUT Skip to specified line

SKIP [(x)] 1. SKIP [(x) ] 1. PUT Skip specified number of lines

COLUMN(w)1. PUT Skip to specified character

position in line

1.Can also be used with non-PRINT files: see ·Options of Transmission statements·,
earlier in this chapter, and "ENVIRONMENT Attribute" on this page.
L---------------------------------------------------------------------------------------J
Figure 11.3. Options and format items for controlling layout of PRINT files

PAGESIZE(55), as shown in the previous compiler, a new page is initiated

example. When an attempt is made to write automatically when the file is opened. If
on line 56 (or to skip beyond line 55), the the first PUT statement that refers to the
ENDPAGE condition will arise, and the begin file has the PAGE option, or if the first
block shown here will be executed. The PUT statement includes a format list with
first PUT statement specifies that a line PAGE as the first item, a blank page will
is to be skipped, and the value of FOOTING, appear. Under the checkout compiler, nO
presumably a character string, is to be new page is started when an explicit or
printed on line 51 (when ENDPAGE arises, implicit OPEN is executed for SYSPRINT,
the current line is always PAGESIZE+1). because the file is used by the compiler to
The page number is incremented, the file transmit diagnostic messages. SYSPRINT is
REPORT is set to the next page, and the always open under the checkout compiler.
character string 'PAGE' is concatenated
with the new page number and printed. The
final PUT statement causes three lines to
be skipped. so that the next printing will ENVIRONMENT Attribute
be on line 4. Control returns from the
begin block to the PUT statement that
caused the ENDPAGE condition, and the data The ENVIRONMENT attribute specifies
is printed. Any SKIP option specified in information about the physical organization
that statement will have no further effect, of the data set associated with a file.
however. The information is contained in a
parentheSized option list; the general
Note that SIGNAL END PAGE is ignored if format is:
there is no ENDPAGE on-unit.
ENVIRONMENT (option-list)
The specification LlNESIZE(110)
indicates that each line on the page can The options applicable to stream-
contain a maximum of 110 characters. An oriented transmission are:
attempt to write a line greater than 110
characters will cause the excess characters FIFBIFSIFBSIVIVBtDIDBIU
to be placed on the next line. RECSIZE(record-length)
BLKSIZECblock-size)

BUFFERS(n)
Standard File SYSPRINT
CONSECUTIVE

unless the standard file SYSPRINT is LEAVE

declared explicitly. it is always given the REREAD
attribute PRINT. Under the optimizing ASCII

148 OS PL/I CKT AND OPT LRM PART I

 BUFOFF[(n)] default character).
The options may appear in any order and
are separated by blanks, The options
themselves cannot contain blanks. Fixed-length Records
The options are discussed below.
All records in the data set are the same
length.
RECORD FORMAT OPTIONS F-format: The records are unblocked: each
record constitutes a single
block.
Although record boundaries are ignored in
stream-oriented transmission, record format FB-format: The records are blocked, some
is important when a data set is being of the blocks may be shorter
created, riot only because it affects the blocks, that is they may be
amount of storage space occupied by the shorter than the specified
data set and the efficiency of the program block size.
that processes the data, but also because
the data set may later be processed by FS-format: The records are unblocked: each
record-oriented transmission. Having record constitutes a single
specified the record format, the programmer block. For direct-access
need not concern himself with records and storage, every track except the
blocks as long as he uses only stream- last one is filled to capacity.
oriented transmission; he can consider his
data set as a series of characters arranged FBS-format: The records are blocked. Only
in lines, and can use the SKIP option or the last block can be a short
format item (and, for a PRINT file, the block.
PAGE and LINE options and format items) to
select a new line. A sequential data set is said to contain
FBS-format records if:
Records can have one of the following
formats: 1. All records in the data set are FB-
format.
Fixed-length F unblocked
FB blocked 2. For direct-access storage, every track
FBS blocked, standard except the last one is filled to
FS unblocked, standard capacity.
variable-length V unblocked 3. No blocks except the last one are
VB blocked truncated.
D unblocked (see
"ASCII Data Sets") Data sets with FBS-format can be read more
DB blocked (see efficiently from direct-access storage than
"ASCII Data Sets·) data sets with truncated blocks.
Undefined-length U (cannot be blocked)
Blocking and deblocking of records is Variable-length Records
performed automatically.
Note that spanned records (VBS and VS) Each record can be a different length.
cannot be used with stream-oriented
input/output. V-format: The records are unblocked:' each
record constitutes a single
All records, whatever the format, block. Each record consists
consist of data bytes and, optionally, of:
control or prefix bytes. Variable-length
records include control and prefix bytes to Four control bytes
specify record and block lengths; the use Data bytes
of these bytes is described later in this
section. In addition, any record (whatever The four control bytes contain
the format) associated with a PRINT file the record length (that is,
has the first data byte interpreted as a the length of the current
printer control character. The compiler record): this value is
analyzes the relevant PUT statement and inserted automatically, and
inserts the appropriate character (or a requires nO action by the

Chapter 11: Stream-oriented Transmission 149

 programmer. Zero value: A search for a valid value is
made in (in the following
In addition, four extra order) :
control bytes are placed at
the beginning of the block DO statement for the
(that is, the record). These data set associated with
bytes contain the block size; the file
the value is inserted in the
same way as the record length. Data set label

VB-format: The records are blocked. Each If neither of these can

record consists of: provide a value, default
action is taken (see "Record
Four control bytes Format Defaults·, later in
Data bytes this section).

The four control bytes have Negative value: The UNDEFINEDFILE

the same purpose as in V- condition is raised.
format records. The block has
four extra control bytes for A value implied by the LINESIZE option
the block size in the same way overrides a value specified in the RECSIZE
as V-format records. option.

0- and DB-format: see "ASCII Data Sets".

Undefined-length Records

All processing is the responsibility of the

programmer. If a length specification is
required in the record, the programmer must BLKSIZE Option
provide one and also interpret it.

The BLKSIZE option specifies the block

size. This is the sum of:
RECSIZE option
1. The lengths of all the records in the
block. For variable length records,
The RECSIZE option specifies the record the length of each record includes the
length. This is the sum of: four control bytes for the record
length.
1. The length required for data. For
variable-length and undefined records, 2. Any control bytes required. Variable-
this is the maximum length. length blocked records require four
for the blocksize; fixed-length and
2. Any control bytes required. Variable- undefined-length records do not
length records require four, for the require any.
record length; fixed-length and
undefined-length records do not
require any.
Any block prefix bytes (ASCII data
The record length can be specified as a sets)
decimal integer constant, or as a variable
with the attributes FIXED BINARY(31,0) The block size can be specified as a
STATIC. decimal integer constant, or as a variable
with the attributes FIXED BINARY(31,0)
The value is subject to the following STATIC.
conventions:
The value is subject to the following
Maximum: Fixed-length, and conventions:
undefined-length (except ASCII
data sets): 32,760 bytes. Maximum: 32,760 bytes (or 9999 for an
Variable-length (except ASCII ASCII data set for which
data sets): 32,756 bytes BOFOFF is specified without a
ASCII data sets: 9999 bytes prefix-length value)

150 OS PL/I CKT AND OPT LRM PART I

Zero value: A search for a valid value is records, the block Size equals the
made in (in the fOllowing record length, the records are assumed
order): to be unblocked and the record format
is set to F.
DO statement for the
data set associated with
the file

Data set label

If neither of these can Record Format Defaults

provide a value, default
action is taken (see "Record
Format Defaults·, later in If any of the record format options is not
this section). specified in the ENVIRONMENT attribute, or
in the associated DD statement or data set
Negative value: the UNDEFINEDFILE label, the following action is taken:
condition is raised.
INPUT files:
The relationship of the block size to
the record length depends on the record Record format: The UNDEFINEDFILE condition
format: is raised, except for files
associated with dummy data sets or
FB-format or FBS-format: The block size the foreground terminal, in which
must be a multiple of record case U-format is assumed.
length
Block size or record length: If one of
VB-format: The block size must be equal to these is specified, a search is
or greater than the sum of: made for the other in the
associated DD statement or data
The lengths of all the records set label. If the search provides
in the block a value, the UNDEFINEDFILE
condition is raised if this value
Four control bytes for the is imcompatible with the value in
block size the specified option. If the
search is unsuccessful, a value is
DB-format: The blocksize must be equal to derived from the value for the
or greater than the sum of: specified option (with the
addition or subtraction of any
The lengths of all the records control or prefix bytes).
in the block
If neither is specified, the
Length of the block prefix (if UNDEFINEDFILE condition is raised,
block is prefixed) except for files associated with
dummy data sets, in which case a
Note: block size of 121 is assumed for
F-format or U-format records and
1. The BLKSIZE option can be used with 129 for V-format records. For
unblocked (F-,V-, or D-format) records files associated with the
as follows: foreground terminal a record size
of 120 is assumed.
a. The BLKSIZE option, but not the
RECSIZE option, is specified. The OUTPUT files:
record length is set equal to the
block size (minus any control or Record format: Set to VB-format, or if
prefix bytes) and the record ASCII option specified, to DB-
format is unchanged. format

b. Both the BLKSIZE and the RECSIZE Record length: The specified or default
options are specified, and the LINESIZE value is used:
relationship of the two values is
compatible with blocking for the PRINT files:
record format used. The records F, FB, FBS, or U: LINESIZE + 1
are assumed to be blocked and the V, VB, D, or DB: LINESIZE + 5
record format is set to FB, VB, or
DB whichever is appropriate. Non-PRINT files:
F, FB, FBS, or U: LINESIZE
2. If, for FB-format or FBS-format V, VB, D, or DB: LINESIZE + 4

Chapter 11: Stream-oriented Transmission 151

Block size: F, FB, or FBS: record length The number of buffers can be specified
V or VB: record length + q in the BUFNO subparameter of a DD statement
D or DB: record length + block instead of in the ENVIRONMENT attribute.
prefix (see note 3)

BUFFER offset: F, FB, or U: 0

D, or DB: q
Note: DCB Subparameter

1. The standard default for LINESIZE is

120. Some of the information that can be
specified in the options of the ENVIRONMENT
2. If the default block size as attribute can also be specified in the DCB
calculated above is greater than sUbparameter of a DO statement. The table
32,760 the block size is set equal to gives a list of equivalents.
(record length + q), and the records
are set to V-format, except when the ENV Option DCB Subparameter
ASCII option is specified. With ASCII
data sets, if the default blocksize is Record format RECFM
greater than 32,760, or 9999 if BUFOFF RECSIZE LRECL
is specified without a prefix-length BLKSIZE BLKSIZE
value, then the block size is set BUFFERS BUFNO
equal to (record length + length of ASCII ASCII
block prefix) and the record format is BUFOFF BUFOFF
set to D.

3. with DB-format records on output

files, the length of the block prefix
(that is, the buffer offset) must
always be either 0 or q.

q. The optimizing and checkout compilers DATA SET ORGANIZATION

will also accept the form of record
format specification used for the
PL/I(F) compiler. In this form, the The organization of a data set determines
record length and block size are how data is recorded in the data set, and
included in the format specification. how the data is subsequently retrieved so
that it can be transmitted to the program.
This implementation recognizes four data
set organizations, CONSECUTIVE, INDEXED,
IREGIONAL, and VSAM. A data set that is to
BUFFER ALLOCATION be accessed by stream-oriented transmission
must have CONSECUTIVE organization; since
this is the default for data set
A buffer is a main storage area that is organization, it need not be specified at
used for the intermediate storage of data all for a STREAM file.
transmitted to and from a data set. The
use of buffers allows transmission and
computing time to be overlapped. Buffers
are essential for the automatic blocking
and deblocking of records.
CONSECUTIVE Data Sets

BUFFERS option The records in a CONSECUTIVE data set are

arranged sequentially in the order in which
they were written; they can be retrieved
The option BUFFERS(n) in the ENVIRONMENT only in the same order. After the data set
attribute specifies the number(n) of has been created, the associated file can
buffers to be allocated for a data set; be opened for input (to read the data), or
this number must not exceed 255 (or such for output (to extend the data set by
other maximum as was established at system adding records at the end, or to replace
generation). If the number of buffers is the contents of the data set by new data:
not specified or is specified as zero, two the effect of using an OUTPUT file to .
buffers are assumed for the optimizing process an existing data set depends on the
compiler, and one buffer is assumed for the DISP parameter of the associated DO
checkout compiler. statement) •

152 OS PL/I CKT AND OPT LRM PART I

r---------------------------------------------------------------------------------------,
ENVIRONMENT I DISP I Action I
Option I Parameter I I
---------------------------------------------------------------------------------------1
REREAD I I Positions the current volume to reprocess the
I I data set. Repositioning for a BACKWARDS file
I I is at the physical end of the data set.
LEAVE Positions the current volume at the logical
end of the data set. POSitioning for a
BACKWARDS file is at the physical beginning
of the data set.
Neither PASS I Positions the volume at the end of the data
REREAD nor I set
LEAVE I
I
DELETE I Rewinds the current volume
I
KEEP, CATLG, I Rewinds and unloads the current volume
I ONCATLG I
L---------------------------------------------------------------------------------------J
Figure 11.4. Effect of LEAVE and REREAD options

MAGNETIC TAPE HANDLING OPTIONS ASCII Option

This option specifies that the code used to

represent data on the data set is ASCII.
LEAVE and REREAD Options

The volume disposition options allow the BUFOFF Option and Block Prefix Fields
programmer to specify the action to be
taken when the end of a magnetic tape
volume is reached, or when a data set on a At the beginning of each block in an ASCII
magnetic tape volume is closed. The LEAVE data set, there may be a field known as the
option prevents the tape from being block prefix field. It may be from one to
rewound. The REREAD option rewinds the 99 bytes long. The buffer offset option
tape to permit reprocessing of the volume indicates the length of this field to data
or data set. If neither of these is management, so that the accessing or
specified, the action at end of volume or creation of data is started at this offset
on closing of a data set is controlled by from the beginning of each phYSical block.
the DISP parameter of the associated DD PL/I does not support access to this field,
statement. The effects of the options are and in general it does not contain
summarized in figure 11.4. information which is used in OS
implementations. There is one situation in
which data management does use information
in the block prefix: with unblocked or
blocked variable length records (that is,
D- or DB-format records), the block prefix
ASCII DATA SETS field may be used to record the length of
the block. In this case, it is four bytes
long and contains a right-aligned, decimal
Data sets on magnetic tape using ASCII may character value that gives the lengtn of
be created and accessed in PL/I. The the block in bytes, including the block
implementation supports F, U, and D record prefix field itself. It is then exactly
formats. F and U formats are treated in equivalent to a block length field.
the same way as with other data setsJ D and
DB formats, which correspond to V and VB The format of the buffer offset option
formats with other data sets, are described is BOFOFF (n»). A numerical value equal
below. to the length of the prefix can be
specified for wnw. It may be specified as
In addition to the record format, two either a decimal integer constant or as a
other ENVIRONMENT options may be specified: variable with the attributes FIXED
ASCII, and the buffer offset option BUFOFF. BINARY(31,O) STATIC. Its minimum value is

Chapter 11: Stream-oriented Transmission 153

zero and its maximum is 99. The absence of record constitutes a single
a prefix length specification indicates block. Each record consists of:
that the block prefix is to be used as a
block length field; it implies that the Four control bytes
fie1d is four bytes long. The length of Data bytes
the block is inserted in the prefix by data
management. The four control bytes contain
the length of the record; this
On input, any ASCII data set may be value is inserted by data
accessed if it has a block prefix field of management and requires no
length one to 99 bytes, or no block prefix action from the programmer. In
field at all; and it may be accessed addition, there may be, at the
whether or not the block prefix field is start of the block, a block
used as a block length field. On output, a prefix field, which may contain
data set using anyone of the three valid the length of the block.
record formats may be created without a
block prefix, but the only situation in DB-format: The records are blocked. All
which the creation of a block prefix is other information given for
supported by PL/I is when it is used as a D-format applies to DB-format.
block length field.
The BUFOFF option may be used with ASCII
data sets only. Oefault Rules

In addition to the rules given under

D-format and DB-format Records -Record Format Defaults·, the following
rule applies:
Each record may be of a different length. If ASCII is not specified in either the
The two different formats are: ENVIRONMENT option or the DO statement, but
one of BUFOFF, D, or DB is specified, then
D-format: The records are unblocked; each ASCII is assumed.

is. OS PL/I CRT AND OPT LRM PART I

 Chapter 12: Record-Oriented Transmission

This chapter describes the input and output Unaligned Bit Strings
statements used in record-oriented
transmission. Those features of PL/I that
apply equally to record-oriented and The following may not be transmitted.
stream-oriented transmission, including
files, file attributes, and opening and 1. BASED, DEFINED, parameter,
closing files, are described in chapter 10, subscripted, or structure-base-element
-Input and Output". variables that are unaligned fixed-
length bit strings.
In record-oriented transmission, data in
a data set is considered to be a collection 2. Minor structures whose first or last
of records recorded in any format base elements are unaligned fixed-
acceptable to the operating system. No length bit strings (except where they
data conversion is performed during record- are also the first or last elements of
oriented transmission: on input, the READ the containing major structure).
statement either causes a single record to
be transmitted to a program variable 3. Major structures that have the DEFINED
exactly as it is recorded in the data set, attribute or are parameters, and that
or else sets a pointer to the record in a have unaligned fixed-length bit
buffer: on output, the WRITE, REWRITE, or strings as their first or last
LOCATE statement causes a single record to elements.
be transmitted from a program variable
exactly as it is recorded internally.
I Although, for non-VSAM data sets, data is
actually transmitted to and from a data set Varying-Length Strings and Area
in blocks, the statements used in record- Variables
oriented transmission are concerned only
with records: the records are blocked and
deblocked automatically. A locate mode output statement (see "LOCATE
Statement-, later in this Chapter)
specifying a varying-length string causes
the transmission of a field having a length
equal to the maximum length of the string,
plus a two-byte prefix denoting the current
length of the string. The SCALARVARYING
Data Transmitted option must be specified for the file. A
locate mode output statement specifying an
area variable causes the transmission of a
Most variables, including parameters and field as long as the declared size of the
DEFINED variables, can be transmitted by area, plus a 16-byte prefix containing
record-oriented transmission statements, control information.
and in general, the information given in
this chapter may be applied equally to all A move mode output statement (see -WRITE
variables. There are certain special Statement" and "REWRITE statement" later in
considerations for a few types of data, and this chapter) specifying a varying-length
these are given below. string variable transmits only the current
length of the string. A two-byte prefix is
included only if the SCALARVARYING option
is specified for the file. A move mode
statement specifying an element area
Data Aggregates variable or a structure whose last element
is an area variable transmits only the
current extent of the area plus a 16-byte
The following restrictions apply to data prefix.
aggregates:
1. An aggregate must be in connected
storage. (An aggregate parameter must Data Transmission Statements
have the CONNECTED attribute).
2. For the LOCATE statement, the variable The follOWing is a general description of
must be a level 1 based variable. the record-oriented data transmission

Chapter 12: Record-oriented Transmission 155

statements; they are described in detail in LOCATE Statement
section J, ·Statements·.
There are four statements that actually The LOCATE statement can be used only with
cause transmission of records to or from an OUTPUT SEQUENTIAL BUFFERED file. It
auxiliary storage. They are READ, WRITE, allocates storage within an output buffer
LOCATE, and REWRITE. A fifth statement, for a based variable, setting a pOinter to
the DELETE statement, is used to delete the location in the buffer as it does so.
records from an UPDATE file. The This pointer can then be used to refer to
attributes of the file determine which the allocation so that data can be moved
statements can be used. into the buffer. When a complete block of
logical records is present in a buffer, the
block is transmitted to an output device.

READ statement
DELETE Statement
The READ statement can be used with any
INPUT or UPDATE file. It causes a record The DELETE statement specifies that a
to be transmitted from the data set to the record in an UPDATE file be deleted.
program, either directly to a variable or
to a buffer. In the case of blocked
records, a READ statement with the
appropriate option causes a record to be UNLOCK Statement
transferred from a buffer to the variable
or sets a pointer to the record in a
buffer; consequently, not every READ The UNLOCK statement is used in association
statement causes transmission of data from with a READ statement that refers to an
an input device. EXCLUSIVE file. The UNLOCK statement makes
the specified record available to other
tasks in addition to that for which the
READ statement was issued.
WRITE statement

The WRITE statement can be used with any Options of Transmission Statements
OUTPUT file or DIRECT UPDATE file, and also
Iwith SEQUENTIAL UPDATE files associated
Iwith VSAM data sets. It causes a record Options that are allowed for record-
to be transmitted from the program to the oriented data transmission statements
data set. For unblocked records, differ according to the attributes of the
transmission may be directly from a file and the characteristics of the
variable or from a buffer. For blocked associated data set. Lists of all of the
records, the WRITE statement causes a allowed combinations for each type of file
logical record to be placed into a buffer; are given in figures 12.8 through 12.15,
only when the blocking of the records is later in this chapter.
complete is there actual transmission of
data to an output device. Each option consists of a keyword
followed by a value, which is a file
expression, a variable, or an expression,
enclosed in parentheses. In any statement,
the options may appear in any order.
REWRITE statement

The REWRITE statement causes a record to be FILE Option

replaced in an UPDATE file. For SEQUENTIAL
UPDATE files, the REWRITE statement
specifies that the last record read from The FILE option must appear in every
the file is to be rewritten; consequently a record-oriented statement. It specifies
record must be read before it can be the file upon which the operation is to
rewritten. For DIRECT UPDATE files, and take place. It consists of the keyword
Ifor KEYED SEQUENTIAL UPDATE files FILE followed by a file expression enclosed
lassociated with VSAM data sets, any record in parentheses. An example of the FILE
can be rewritten whether or not it has option is shown in each of the statements
first been read. in this section.

156 OS PL/I CRT AND OPT LaM PART I

INTO option REWRITE without FROM has nO effect on the
record in the data set~ but if the last
record was read by a READ statement with
The INTO option can be used in the READ the SET option, the record will be updated,
statement for any INPUT or UPDATE file. in the buffer, by whatever aSSignments were
The INTO option specifies a variable into made and copied back onto the ~ata set.
which the logical record is to be read.
WRITE FILE (MASTER) FROM (MAS_REC);
READ FILE (DETAIL) INTO (RECORD_1) ~
REWRITE FILE (MASTER) FROM (MAS_REC);
This specifies that the next sequential
record is to be read into the variable Both statements specify that the value of
RECORD_1. the variable MAS REC is to be written into
the file MASTER.- In the case of the WRITE
Note that the INTO option can name an statement, it specifies a new record in a
element string variable of varying length. SEQUENTIAL OUTPUT file. The REWRITE
If the SCALARVARYING option of the statement specifies that MAS REC is to
ENVIRONMENT attribute is specified for the replace the last record read-from a
file, then each record is assumed to SEQUENTIAL UPDATE file.
contain a two-byte prefix that specifies
the length of the string data. (See -FROM
Option- below).
SET Option
If SCALARVARYING was not declared then,
on input, the implementation calculates the
string length from the record length and The SET option can be used with a READ
attaches it as a two-byte prefix. For statement or a LOCATE statement. It
varying-length bit strings, this specifies that a named pointer variable is
calculation rounds up the length to a to be set to point to the location in the
multiple of 8 and therefore the calculated buffer into which data has been moved
length may be greater than the maximum during the READ operation, or which has
declared length. been allocated by the LOCATE statement.

READ FILE (X) SET (P);

FROM Option This statement specifies that the value of

the pointer variable P is to be set to the
location in the buffer of the next
The FROM option must be used in the WRITE sequential record. If the SET option is
statement for any OUTPUT or DIRECT UPDATE omitted, the pointer declared with the
file. It can also be used in the REWRITE record variable will be set.
statement for any UPDATE file. The FROM
option specifies the variable from which Note that if an element string variable
the record is to be written. of varying-length is transmitted, the
SCALARVARYING option must be specified for
Note that the FROM option can name an the file.
element string variable of varying length.
When using a WRITE statement with the FROM
option, only the current length of a
varying-length string is transmitted to a IGNORE Option
data set, and a two-byte prefix specifying
the length may be attached~ it is attached
only if the SCALARVARYING option of the The IGNORE option can be used in a READ
ENVIRONMENT attribute is specified for the statement for any SEQUENTIAL INPUT or
file. SEQUENTIAL UPDATE file. It includes an
expression whose integral value specifies a
Records are transmitted as an integral number of records to be skipped over and
number of bytes. Therefore, if a bit ignored. If the value of the expression is
string (or a structure that starts or ends negative or zero, no records are skipped.
with a bit string) that is not aligned on a
byte boundary, is transmitted, the record READ FILE (IN) IGNORE (3)~
will contain bits at the start or end that
are not part of the string. This statement specifies that the next
three records in the file are to be
The FROM option can be omitted from a skipped.
REWRITE statement for SEQUENTIAL BUFFERED
UPDATE files. If the last record was read If a READ statement has none of the
by a READ statement with the INTO option, options INTO, SET, and IGNORE, IGNORE (1) is

Chapter 12: Record-oriented Transmission 157

assumed. The KEYFROM option specifies a key that
identifies the record on the data set, or
(for TRANSIENT files) the terminal to which
the message or record is to be transmitted.
It can be used in a WRITE statement for a
KEY Option SEQUENTIAL OUTPUT or DIRECT UPDATE file or
a DIRECT OUTPUT file that has REGIONAL
organization, or in a LOCATE statement.
The KEY option applies only to KEYED files lIt can also be used in a WRITE statement
associated with data sets of INDEXED, Ifor a KEYED SEQUENTIAL UPDATE file
I REGIONAL, or VSAM organization. (The types I associated with a VSAM data set.
of data set organization applicable to
record-oriented transmission are discu~sed WRITE FILE (LOANS) FROM (LOANREC)
under -Data Set Organization-, later in KEYFROM (LOANNO);
this chapter.) The option consists of the
keyword KEY followed by a parenthesized This statement specifies that the value of
expression, which may be a character-string LOANREC is to be written as a record in the
constant, a variable, or any other element file LOANS, and that the character string
expression: if necessary, the expression is value of LOANNO is to be used as the key
evaluated and converted to a character with which it can subsequently be
string. The rules governing the length of retrieved.
the character string and what i t represents
are discussed under "INDEXED Organization", The KEYTO option specifies the name of
I "REGIONAL Organization" , and "VSAM the variable into which the key (or
Organization- later in this chapter. terminal identifier, if the file is
TRANSIENT) of a record is to be read. It
The KEY option identifies a particular can be used in a READ statement for a
record. It can be used in a READ statement SEQUENTIAL INPUT, SEQUENTIAL UPDATE, or
for an INPUT or UPDATE file, or in a TRANSIENT INPUT file.
REWRITE statement for a DIRECT UPDATE file. lIt can also be used in a WRITE statement
(The KEY option can be used in a READ Ifor a SEQUENTIAL OUTPUT or SEQUENTIAL
statement for a SEQUENTIAL file only if the IUPDATE file associated with a VSAM entry-
associated data set has INDEXED or VSAM Isequenced or relative-record data set.
organi zation. )
READ FILE (DETAIL) INTO (INVTRY)
READ FILE (STOCK) INTO (ITEM) KEYTO (KEYFLD);
KEY (STKEY);
This statement specifies that the next
This statement specifies that the record record in the file DETAIL is to be read
identified by the character-string value of into the variable INVTRY, and that the key
the variable STKEY is to be read into of the record is be read into the variable
the variable ITEM. KEYFLD.

KEYFROM and KEYTO Options

EVENT Option

The KEYFROM and KEYTO options apply only to

KEYED files associated with data sets of The EVENT option consists of the keyword
IINDEXED, REGIONAL, or VSAM organization, or EVENT followed by the name of an event
to TRANSIENT files. Each option consists variable in parentheses. (The appearance
of the keyword KEYFROM or KEYTO followed by of a name in the EVENT option constitutes a
an expression in parentheses. For KEYFROM, contextual declaration of an event
the expression may be a character-string variable.) The option can appear in any
constant, or any other element expression; READ, WRITE, REWRITE, or DELETE statement
if necessary, the expression is evaluated for an UNBUFFERED file with CONSECUTIVE or
and converted to a character string. For REGIONAL organization or for any DIRECT
KEYTO, the expression must be a character- file.
string variable or pseudovariable whose
value is less than 256 bytes long. The The EVENT option specifies that the
rules governing the lengths of the input or output operation is to take place
character strings and what they represent asynchronously (i.e., while other
are discussed below, under -INDEXED processing continues) and that no I/O
Organization-, "REGIONAL Organization", conditions (except for UNDEFINEDFILE) are
land ·VSAM Organization- (except for raised until a WAIT statement, specifying
TRANSIENT files, which are discussed under the same event variable, is executed by the
-Teleprocessing-). same task. For example:

158 OS PL/I CKT AND OPT LRM PART I

 READ FILE (MASTER) INTO (REC_VAR) NOLOCK Option
EVENT (RECORD_i);

The NOLOCK option can be used in a READ

statement that refers to an EXCLUSIVE file.
WAIT (RECORD_i); It specifies that the record accessed by
the READ statement will not be locked
between completion of a READ statement and
When any expressions in the options of the commencement of the corresponding REWRITE;
READ statement have been evaluated, the the record will continue to be available to
input operation is started. As soon as other tasks in addition to that which
this has happened, the statements following issued the READ statement.
are executed. Any RECORD, TRANSMIT, KEY,
or ENDFILE condition will not be raised
until control reaches the WAIT statement.
If, when the WAIT statement is executed, Processing Modes
the input operation is not complete, and if
none of the four conditions is raised,
execution of further statements is Record-oriented transmission offers the
suspended until the operation is complete. programmer two methods of handling his
When the operation is successfully data. He can process data within a
completed, processing continues with the declared storage area; this is termed the
next statement following the WAIT move mode because the data is actually
statement. If any of the four conditions moved into or out of main storage either
arise owing to execution of the READ directly or via a buffer. Alternatively,
statement, the condition(s) will be raised the programmer can process his data while
when the WAIT statement is executed. For it remains in a buffer (that is, without
this implementation, only the conditions moving it into a declared storage area);
TRANSMIT and RECORD can occur together; this is termed the locate mode, because the
TRANSMIT is always processed first. Then, execution of a data transmission statement
upon normal return from anyon-units merely identifies the location of the
entered, processing continues with the next storage allocated to a record in the
statement following the WAIT statement. buffer. The locate mode is applicable only
Although the EVENT option specifies to SEQUENTIAL BUFFERED files. Which mode
asynchronous processing, none of the four is used is determined by the data
conditions can cause an interrupt until transmission statements and options used by
they are synchronized with processing by the programmer.
the WAIT statement.

Note that for consecutive and regional MOVE MODE

sequential files only one outstanding
input/output operation is allowed for a
file unless a higher number is specified in In the move mode, a READ statement causes a
the NCP option of the environment attribute record to be transferred from external
or DCB subparameter. The ERROR condition storage to the variable named in the INTO
is raised if an attempt is made to initiate option (via an input buffer if a BUFFERED
an input/output operation on a file in file is used); a WRITE or REWRITE statement
excess of the number allowed, while a causes a record to be transferred from the
previous input/output operation has not variable named in the FROM option to
been waited for. external storage (perhaps via an output
buffer). The variables named in the INTO
and FROM options can be of any storage
Once a statement containing an EVENT class.
option has been executed, the event
variable named in the option is considered Consider the following example, which is
to be active: while it is active, the same illustrated in figure 12.1:
event variable cannot be specified again in
an EVENT option. The event variable NEXT: READ FILE(IN) INTO(DATA);
becomes inactive again only after execution
of the corresponding WAIT statement or when
the file is closed.
WRITE FILE (OUT) FROM (DATA);
The EVENT option can also be used with GO TO NEXT:
the CALL statement to specify asynchronous
execution of procedures (see chapter 11, The first time the READ statement is
"Multitasking"), and with the DISPLAY executed, a block is transmitted from the
statement with the REPLY option. data set associated with the file IN to an

Chapter 12: Record-oriented Transmission 159

DATA
SET

1ST
READ

INPUT
IUFFER

1ST 2ND 3RD

READ READ READ

VARIAIU
(DATA)
D
1ST 2ND 3RD
WRITE WRITE WRITE

! I
OUTPUT
IUFFER
I

r
A
,
.'A
lit
I
Piqure 12.1.
I I I
Input and output: move mode

160 OS PL/I CKT AND opr LRM PART I

input buffer, and the first record in the A READ statement causes a block of data
block is assigned to the variable DATA: to be transferred from the data set to an
further executions of the READ statement input buffer if necessary, and then sets a
assign successive records from the buffer pointer variable named in the SET option to
to DATA. When all the records in the point to the location in the buf~er of the
buffer have been processed, the next READ next record; the data in the record can
statement causes a new block to be then be processed by reference to the based
transmitted from the data set although this variable associated with the pointer
READ statement will probably access a new variable. The record is available only
record in an alternative buffer, thus until the execution of the next READ
permitting overlapped data transmission and statement that refers to the same file.
processing. The WRITE state~ent is
executed in a similar manner, building A LOCATE statement causes storage for a
physical records in an output buffer and based variable to be allocated in an output
transmitting them to the data set buffer, and sets a pOinter variable to
associated with the file OUT each time the identify the allocated storage. The based
buffer is filled. variable can now have values aSSigned to
it. The next LOCATE, WRITE, or CLOSE
The move mode may be simpler to use than statement for the same file will, if
the locate mode since there are no buffer necessary, transmit the data in the output
alignment problems. Furthermore, it can buffer to the data set. After transmission
result in faster execution when there are the storage used for the buffer is freed;
numerous references to the contents of the hence, only the latest one can be accessed.
same record, because of the overhead
incurred by the indirect addressing Locate mode frequently provides faster
technique used in locate mode. execution than move mode since there is
less movement of data, and less storage may
It is possible to use the move mode be required. But it must be used
access technique and avoid internal carefully; in particular, the programmer
movement of data in the following cases: must be aware of how his data will be
aligned in the buffer and how structured
1. SEQUENTIAL UNBUFFERED files with: data will be mapped; structure mapping and
CONSECUTIVE organization with either data alignment are discussed in section K,
U-format records, or F-format records "Data Mapping".
which are not larger than the variable
specified in either the INTO or FROM Figure 12.2 illustrates the following
option; and REGIONAL(l) organization example, which uses locate mode for input
with F-format records which are not and move mode. for output:
larger than the variable specified in
the FROM or INTO option. DCL DATA BASED(P);
2. DIRECT files with REGIONAL(l) or
REGIONAL(2) organization and F-format NEXT: READ FILE(IN) SET(P):
records; and REGIONAL(3) organization
with F-format or U-format records.
WRITE FILE(OUT) FROM(DATA);
GO TO NEXT;
The first time the READ statement is
LOCATE MODE executed, a block is transmitted from the
data set associated with the file IN to an
input buffer, and the pointer variable P is
Locate mode requires the use of based set to point to the first record in the
variables. A based variable is effectively buffer; any reference to the variable DATA
overlaid an the data in the buffer, and or to any other based variable qualified by
different based variables can be used to the pointer P will then in effect be a
access the same data by associating the reference to this first record. Further
same pointer with each one; thus the same executions of the READ statement set the
data can be interpreted in different ways. pOinter variable P to point to succeeding
Locate mode can also be used to read self- records in the buffer. When all the
defining records, in which information in records in the buffer have been processed,
one part of the record is used to indicate the next READ statement causes a new block
the structure of the rest of the record; to be transmitt~ from the data set.
for example, this information could be a
count of the number of repetitions of a It is doubtful whether the use of locate
subfield, or a code identifying which one mode for both input and output in the above
of a class of structures should be used to example would result in increased
interpret the record. efficiency. An alternative would be to use

Chapter 12: Record-oriented Transmission 161

move mode for input and locate mode for CONSECUTIVE
output, for example: INDEXED
VSAM
DCL DATA BASED(P): REGIONAL({11213})
TP({MIR})
NEXT: LOCATE DATA FILE(OUT): LEAVE
READ FILE (IN) INTO (DATA) : REREAD
SIS
GO TO NEXT: SKIP
Each execution of the LOCATE statement BKWD
reserves storage in an output buffer for a
new allocation of the based variable DATA REUSE
and sets the pointer variable P to point to
this storage. The first execution of the TOTAL
READ statement causes a block to be
transmitted from the data set associated CTLASA
with the file IN to an input buffer, and CTL360
the first record in the block to be
assigned to the first allocation of DATA: COBOL
subsequent executions of the READ statement
assign successive logical records to the INDEXAREA (index-area-size)]
current allocation of DATA. When all the NOWRITE
records in the buffer have been processed, ADDBUFF
the next READ statement causes a new block
to be transmitted from the data set. Each GENKEY
record is available for processing during
the period between the execution of the NCP(n)
READ statement and the next execution of
the LOCATE statement. When no further TRKOFL
space is available in the output buffer,
the next execQtion of the LOCATE statement SCALARVARYING
causes a block to be transmitted to the
data set associated with the file OUT, and KEYLENGTH(n)
a new buffer to be allocated.
KEYLOC(n)
Note that if the READ statement raises
the ENDFlLE condition, the file OUT will ASCII
have been allocated a buffer which will be BUFOFF ( (n) ]
transmitted when the file is closed.
PASSWORD (password-specification)
ENVIRONMENT Attribute A constant or variable can be used with
those ENVIRONMENT options that require
decimal integer arguments, such as block
The ENVIRONMENT attribute specifies Sizes and record lengths. The variable
information about the physical organization must be unsubscripted and unqualified with
of the data set associated with a file. the attributes FIXED BINARY(31,O) and
The information is contained in a STATIC.
parenthesized option list: the general
format is: The options may appear in any order, and
are separated by blanks. The options
ENVIRONMENT (option-list) themselves cannot contain blanks.
The options applicable to record- The options are discussed below.
oriented transmission are:
FIFBIFSIFBSIVIVBIVSIVBSIDIDBIU
RECSIZE(record-length) RECORD FORMAT OPTIONS
BLKSIZE(block-size)
BUFFERS (n)
1The follOWing discussion of the record
BUFND(n) I format options does not apply to VSAN data
BUFNI(n) I sets. If a record format option is
BUFSP(n) Ispecified for a file associated with a VSAM

162 OS PL/I CRT AND OPT LRM PART I

DATA
SET

1ST
READ

INPUT
BUFFER
I I I
pl pt Pt
1ST 2ND lRD
READ READ READ

1ST 2 NO lRD
WRITE WRITE WRITE

OUTPUT
BUFFER
I I I

lRD
WRITE

__------------~)l,---------------
( '\
DATA
SET
I
Figure 12.2. Locate mode input, move mode output
I
Chapter 12: Record-oriented Transmission 163
Idata set, the option is ignored. capacity.
Recor.ds can have one of the following
formats: FBS-format: The records are blocked. Only
the last block can be a short block.
Fixed-length F unblocked
FB blocked A consecutive data set is said to contain
FS unblocked, standard FBS-format records if:
FBS blocked, standard
1. All records in the data set are FB-
Variable ~length v unblocked format
VB blocked
VS spanned 2. For direct-access storage, every track
VBS blocked, spanned except the last one is filled to
D unblocked (see "ASCII capacity.
Data Sets")
DB blocked (see ASCII 3. No blocks except the last one are
Data Sets") truncated.

undeffned-Iength U (cannot be blocked) Data sets with standard format (FS or FBS)
records can be read from direct-access
Blocking and deblocking of records is storage more efficiently than data sets
performed automatically. with truncated blocks or embedded unfilled
tracks.
All records, whatever the format, consist
of data bytes and, optionally, control or
prefix bytes. variable-length records
include control or prefi::: bytes to specify variable-length Records
record and block lengtbs; the use of these
bytes is described later in this section.
In addition, any record (whatever the Each record can be a different length.
format) can have an optional printer or
machine control character in the first data V-format: The records are unblocked; each
byte. The programmer must insert the record constitutes a single block. Each
character himself, and must indicate the record consists of:
presence of such a character by means of
the CTLASA or CTL360 options of the Four control bytes
ENVIRONMENT attribute, or by means of the
equivalent field of the DCB subparameter in Data bytes
the associated DD statement.
The four control bytes contain the
The SCALARVARYING option (described later record length (that is, the length of
in this section) can be specified with the current record including the four
records of any format. This option cannot control bytes); this value is inserted
be specified if the first data byte automatically and requires nO action by
contains a printer or a machine control the programmer. In addition, four extra
character, as this would lead to an control bytes are placed at the
ambiguous interpretation of this byte. beginning of the block. Thes~ bytes
contain the block size including all
control bytes; the value is inserted in
the same way in the record length.
Fixed-length Records
VB-format: The records are blocked. Each
record consists of:
All records in the data set are the same
length. Four control bytes

F-format: The records are unblocked; each Data bytes

record constitutes a single block
The four control bytes have the same
FB-format: The records are blocked. Some purpose as in V-format records. The
of the blocks may be short blocks, that block has four extra control bytes for
is, they may be shorter than the the block size, in the same way as for
specified block size. V-format records.

FS-format: The records are unblocked. each VS-format: Each record constitutes at
record constitutes a single block. For least one block. On CONSECUTIVE data
direct-access storage, every track sets, record length can be greater than
except the last one is filled to block size; if it is, the record can

164 OS PL/I CRT AND OPT LRM PART I

 'span' several blocks. A spanned record programmer.
is divided into segments, and each
segment occupies a block. Therefore a
block consists of:
Undefined-length Records
Four block control bytes
Four record or segment control bytes All processing is the responsibility of the
programmer; if a length specification is
Data Bytes required in the record, the programmer must
provide it, and must interpret it.
The block control bytes contain the
length of the block; the record (or
segment) control bytes contain the
length of the record (or segment). RECSIZE OPTION
These values are inserted automatically
and require no action by the programmer.
The RECSIZE Option specifies the record
VS-format records can be specified for length. For files other than transient
data sets with CONSECUTIVE or Ifiles and files associated with VSAM data
REGIONAL (3) organization only. The VS Isets, this is the sum of:
record format option must be specified
as an option of ENVIRONMENT, not in the 1. The length required for data. For
DCB subparameter of the DD card. variable-length and undefined-length
records, this is the maximum length.
CONSECUTIVE: Record length can be equal
to or greater than block size; 2. Any control bytes required. Variable-
each block contains one record or length records require four, for the
record segment. record length; fixed-length and
undefined-length records do not
REGIONAL(3): Record length cannot be require any.
greater than block size. A record
can only be segmented across track For a transient file, it is the sum of:
boundaries, when a complete record
will not fit into the space 1. The four V-format control bytes.
remaining on the current track.
Each such segment constitutes a 2. One flag byte.
block.
3. Eight bytes for the key.
VBS-format: Each record constitutes part
of a block, a block or several blocks. 4. The maximum length required for the
Each block consists of: data.
Four block control bytes IFor VSAM data sets, the maximum and average
One of the following: Ilengths of the records are specified when
Ithe data set is defined (see the
One or more complete records IProgrammer's Guide for the compiler). If
One or more complete records, and Ithe RECSIZE option is included in the file
either one or two record segments. Ideclaration for checking purposes, the
Two record segments Imaximum record size should be specified.
A single record segment
The record length can be specified as a
Each complete record or each record decimal integer constant or as a variable
segment consists of: with the attributes FIXED BINARY (31,0)
STATIC.
Four record or segment control bytes
Data bytes The value is subject to the following
conventions:
The control bytes have the same purpose
as in VB-format records. VBS-format Maximum: Fixed-length, and undefined
records can be specified for data sets (except ASCII data sets):
with CONSECUTIVE organization only. 32,160 bytes
D- and DB-format: see ·ASCII Data sets· V-format, and VS- and
VBS-format with UPDATE files:
segmentation and reassembly of records, 32,756 bytes
like blOCking and deblocking, take place
automatically, and require no action by the VS-and VBS-format with INPUT

Chapter 12: Record-oriented Transmission 165

 and OUTPUT files: no limit record segments options: fixed- or
variable-length blocked or unblocked w
ASCII data sets: 9999 spanned or non-spanned. When
specifying a block size for spanned
VSAM data sets: 32,161 for records, the programmer must be aware
non-spanned records. For that each record and each record
spanned records, the maximum is segment will require four control
the size of the control area. bytes for the record length, and that
these quantitites are in addition to
For VS- and VBS-format records longer than the four control bytes required for
32,156 bytes, the length must be specified each block.
in the RECSIZE option of ENVIRONMENT, and
the DCB subparameter of the DD card mus~ 2. Any further control bytes required.
specify LRECL=X. Variable-length blocked records
require four, for the block size;
Zero value: A search for a valid value is fixed-length and undefined-length
made in (in the following order): records do not require any.
DD statement for the data
set associated with
the file Any block prefix bytes required (ASCII
data sets only).
Data set label
The value can be specified as a decimal
If neither of these can provide a value, integer constant, or as a variable with the
default action is taken (see -Record Format attributes FIXED BINARY (31,0) STATIC.
Defaults-, later in this section).
The value is subject to the following
Negative value: The UNDEFINEDFILE conventions:
condition is raised
Maximum: 32,160 bytes (or 9999 for an ASCII
data set for which BUFOFF without
a prefix-length value has been
BLKSIZE option specified)
Zero value: A search for a valid value is
IThe BLKSIZE option does not apply to VSAM made in (in the following order):
Idata sets, and is ignored if it is
I specified. DD statement for the data set
The BLKSIZE option specifies the maximum associated with the file
block size on the data set. The length of
a block is the sum of: Data set label
1. The total length(s) of one of the If neither of these can provide a
following: value, default action is taken
(see -Record Format Defaults·)
A single record
Negative value: The UNDEFINEDFILE
A single record and either one or two condition is raised
record segments
The relationship of the block size to the
several records record length depends on the record format:
Several records and either one or two FB-format or FBS format: The block size
record segments must be a multiple of the record
length
Two record segments
A single record segment VB-format: The block size must be equal to
or greater than the sum of:
For variable length records; the
length of each record or record The maximum length of any
segment includes the four control record
bytes for the record or segment
length. Four control bytes
The above list summarizes all the VS-format or VBS-format: The block size
possible combinations of records and can be less than, equal to, or

166 OS PL/I CKT AND OPT LRM PART I

 greater than the record length. set label. If the search provides
a value, the UNDEFINEDFILE
DB-format: The blocksize must be equal to condition is raised if this value
or greater than the sum of: is incompatible with the value in
the specified option. If the
The maximum length of any record search is unsuccessful, a value is
deri ved from the speci'fied option
The length of the block prefix (if (with the addition or subtraction
block is prefixed) of any control or prefix bytes).
If neither is specified, the
Notes: UNDEFINEDFILE condition is raised,
except for files associated with
1. The BLKSIZE option can be used with dummy data sets, in which case a
unblocked (F-, V-, or D-format) block size ot 121 is assumed for
records, as follows: F-format or U-format records and
129 for V-format records. For
a. The BLKSIZE option, but not the files associated with the
RECSIZE option, is specified. The foreground terminal a record size
record length is set equal to the of 120 is assumed.
block size, (minus any control or
prefix bytes) and the record ~: The optimizing and checkout
format is unchanged. compilers will also accept the form of
record format specification used for the
b. Both the BLKSIZE and the RECSIZE PL/ICF) compiler. In this form, the record
options are specified, and the length and block size are included in the
relationship of the two values is format specification.
compatible with blocking for the
record format used. The records
are assumed to be blocked and the
record format is set to FB VB, or BUFFER ALLOCATION
DB whichever is appropriate.
2. If, for FB-format or FBS-format A buffer is an internal storage area that
records, the block size equals the is used for the intermediate storage of
record length, the records are assumed data transmitted to and from a data set.
to be unblocked and the record format The use of buffers can speed up processing
is set to F. of SEQUENTIAL files. Buffers are essential
for the automatic blocking and deblocking
3. For files associated with VSAM data of reco~ds and for locate-mode
sets (described later in this transmission.
chapter), the only record format
option that applies is RECSIZE (which
must match the actual record size of
the data set). The others (that is, BUFFERS option
the BLKSIZE option and the various
letter combinations indicating the
blocking types) are ignored if The option BUFFERS(n) in the ENVIRONMENT
specified. attribute specifies, for CONSECUTIVE and
INDEXED data sets, the number (n) of
buffers to be allocated for a data set;
this number must not exceed 255 (or such
Reeord Format Defaults other maximum as was established at system
generation). If the number of buffers is
not specified for a BUFFERED file or is
IIf, for a non-VSAM data set, any of the speCified as zero, two buffers are assumed
record format options is not specified, the for the optimizing compiler, and one buffer
following action is taken. is assumed for the checkout compiler. A
REGIONAL data set is always allocated two
Record format: The UNDEFINEDFILE condition buffers.
is raised, except for files
associated with'dummy data sets or In teleprocessing, the BUFFERS option
the foreground terminal, in which specifies the number of buffers available
case U-format is assumed. for a particular message queue, that is,
for a particular TRANSIENT file. The
Block size or record length: If one of buffer size is specified in the message
these is specified, a search is control program for tbe installation. The
made for the other in the number of buffers specified should, if
associated DO statement or data poSSible, be sufficient to provide for the

Chapter 12: Record-oriented Transmission 161

 longest message to be transmitted. IINDEXED Data sets
I
~ The BUFFERS option is inadequate for I
files associated with VSAM data sets, since IThe records of an INDEXED data set are
the numbers of index and data buffers are larranged in logical sequence according to
specified separately. Instead, the BUFND Ikeys associated with each record; the
and BUFNI subparameters of the AMP Irecords are arranged in ascending key
parameter of the DD statement can be used, Isequence, and indexes are maintained in the
and the BUFFERS option is ignored. The Idata sets and are used for retrieval of
default is two data buffers and, if the I records.
data set is key-sequenced, one index I
buffer. I Although an INDEXED data set must be
Icreated sequentially, once it exists
Irecords can be retrieved, updated, added,
lor deleted at random. sequential
Iprocessing of an INDEXED data set is slower
than that of a corresponding CONSECUTIVE
data set, because the records it contains
DATA SET ORGANIZATION are not necessarily retrieved in physical
sequence; turthermore, random access is
less efficient for an INDEXED data set than
The organization of a data set determines for a REGIONAL data set, because the
how data is recorded in a data set volume, indexes must be searched to locate a
and how the data is subsequently retrieved record. other disadvantages of an INDEXED
so that it can be transmitted to the data set are that it requires more external
program. Records are stored in and storage space than a CONSECUTIVE data set,
retrieved from a data set either and that all volumes of a mUlti-volume data
sequentially on the basis of successive set must be mounted even for sequential
physical or logical positions, or directly Iprocessing.
by the use of keys specified in data I
transmission statements. These storage and I
retrieval methods provide PL/I with five I
general data set organizations: IREGIONAL Data sets
CONSECUTIVE, INDEXED, REGIONAL, 'TP, and I
VSAM. If the data set organization is not I
specified, a default is obtained thus: IA data set with REGIONAL organization is
Idivided into regions, each of which is
1. If the merged attribute from the lidentified by a region number and contains
DECLARE and OPEN statements do not lone or more records; for retrieval, the key
include TRANSIENT: the default is Isupplied gives the region number or track
CONSECUTIVE. lat which the search for the record is to
I commence.
2. If the attributes include TRANSIENT: I
the default is TP(M). I
I Direct access of REGIONAL data sets is
Iquicker than that of INDEXED data sets, but
Ithey have the disadvantage that sequential
Iprocessing may present records in random
Isequence; the order of sequential retrieval
lis not necessarily that in which the
ICONSECUTIVE Data sets Irecords were presented, nor need it be
I Irelated to the relative key values.
I IBlocked records are not permitted in a
lIn a data set with CONSECUTIVE IREGIONAL data set.
I organization, records are organized solely I
Ion the basis of their successive physical I
I positions; records are retrieved only in I
Isequential order, and keys are not used. IVSAM Data Sets
I I
I CONSECUTIVE data sets are the simplest I
lof the five types to create and use, and IVSAM data sets have either entry-sequenced
Ithey have the advantage that less external I(ESOS), key-sequenced (KSDS), or .relative-
Istorage is required. However, records in a Irecord (RRDS) organization. These
ICONSECUTIVE data set can be updated only in lorganizations correspond roughly to the
Itheir existing sequence, and if records are Inon-VSAM organizations CONSECUTIVE,
Ito be inserted a new data set must be I INDEXED, and REGIONAL (1 ).. In general,
(created. Updating is not supported for Ihowever, VSAM offers a wider range of data
lmagnetic tape. Iset operations than non-VSAM access

168 OS PL/I CRT AND OPT LRM PART I

I methods, and this is reflected in the 1 Further information on the structure of
Igreater flexibility of input/output IVSAM data sets and the ways in which they
Istatements for files associated with VSAM Ican be accessed are given under "VSAM
Idata sets. IOrganization" later in this chapter. Fu11
I Idetails on the structure of VSAM data sets
I Although only key-sequenced data sets land indexes, the way in which they are
have keys as part of their logical records, Idefined by Access Method Services, and the
keyed access is also possible for entry- Irequired JCL statements are either given or
sequenced data sets (using relative-byte Ireferenced in the programmer's Guide for
addresses) and relative-record data sets the compiler.
(using relative record numbers).
It is also possible to define a1ternate
indexes on a KSDS or an ESOS. An alternate
index on an ESOS enables it to be treated,
in general, as a KSDS. An alternate index PASSWORD OPTION
on a KSOS enables a field in the logical
record different from that used in the
prime index to be used as the key field. The PASSWORD option is applicable only to
Alternate indexes may be either non-unique, files associated with VSAM data sets. When
in which duplicate keys are allowed, or a VSAM data set is defined to the system
unique, in which they are not. The prime (using the DEFINE command of Access Method
index can never have duplicate keys. Iservices), READ and UPDATE passwords can be
I associated with it. Thenceforward, the
Before a VSAM data set is used for the lappropriate password must be included in
first time, its structure is defined to the Ithe declaration of any PL/I file used to
system by the DEFINE command of Access laccess the data set. The format of the
Method Services. consequently, many of the loption is:
options of the ENVIRONMENT attribute I .
affecting data set structure are I PASSWORD (password-specification)
superfluous for VSAM data sets. If they I
are specified, they are either ignored, or where the password specification is a
used for checking purposes. If those that character-string constant or character-
are checked conflict with the values string variable. If the specification is a
defined for the data set, the UNDEFINEDFILE constant, it must not contain a repetition
condition is raised when an attempt is made factor; if it is a variable, it must be
to open the file. level-l, element, static, and
unsubscri~ed. The character string is
The options that are checked for a VSAM padded or truncated to eight characters and
data set are RECSIZE and, for a key- passed to VSAM for inspection. The system
sequenced data set, KEYLEN and KEYLOC. The operator is given a number of chances to
options GENKEY, SCALARVARYING, and COBOL specify the correct password. The number
have the same effect as fornon-VSAM data of chances to be allowed is specified when
sets. The foregoing options, together with the data set is defined. After this number
the VSAM-only options BKWD, BUFND, BUFNI, of unsuccessful tries, the UNDEFINEDFILE
BUFSP, PASSWORD, REUSE, SIS, and SKIP, are condition is raised.
the only options applicable to a file
declared with ENVIRONMENT(VSAM). The VSAM-
only options are described later in this
section.
SKIP ANO SIS OPTIONS
In most circumstances, existing PL/I
programs using files declared with
ENVIRONMENT (CONSECUTIVE) or The SKIP and SIS options specify the form
ENVIRONMENT (INDEXED) are able to access of access that is to be used for VSAM data
IVSAM data sets without alteration. PL/I sets. SKIP is applicable to key-sequenced
Ican detect that a VSAM data set is being data sets accessed by means of a SEQUENTIAL
I opened, and can provide the correct access, file; SIS is applicable to key-sequenced
leither directly or by use of a Idata sets accessed by means of a DIRECT
Icompatibility interface. This support is Ifile.
Inot provided when the data set is accessed I
lunder TSO and the DD information is I Although it is never an error to omit
Isupplied by the ALLOCATE command; in this Ithese options, specifying one or the other
Icase the program is abnormally ter.minated Ican sometimes result in improved
Iwhen the fi1e is opened. Note that I performance, depending upon how the file is
,existing PL/I programs that use REGIONAL(l) Ibeing used. Guidance on the use of these
Ifiles cannot be used unaltered to access loptions is given under "Key-Sequenced Data
IVSAM relative-record data sets. ISets" later in this chapter.

Chapter 12: Record-oriented Transmission 169

 BKWD OPTION BUFND(n)
where wnw is a decimal integer constant, or
The BKWD option specifies backwards a variable with the attributes FIXED
processing for a SEQUENTIAL INPUT or BINARY(31,O) STATIC.
SEQUENTIAL UPDATE file associated with a
VSM data set.
The effect of the option is to cause BUFNI OPTION
sequential reads (that is, reads Without
the KEY option) to retrieve the previous
record in sequence. For indexed data sets, The BUFNI option specifies the number of
the previous record is, in general, the index buffers required for a VSM data set.
record with the next lower key. However, The format of the option is:
if the data set is being accessed via a
non-unique alternate index, records with BUFNI(n)
the same key are recovered in their normal
sequence. For example, if the records are: Iwhere WnW is a decimal integer constant, or
la variable with the attributes FIXED
A B Cl C2 C3 D E IBINARY(31,O) STATIC.
I
where Cl, C2, and C3 have the same key, I
they are recovered in the sequence: I
IBUFSP OPTION
E D Cl C2 C3 B A I
I
When a file with the BKWD option is IThe BUFSP option specifies, in bytes, the
opened, the data set is positioned at the Itotal buffer space required for a VSAM data
last record. ENDFILE is raised in the Iset. The format of the option is:
normal way when the start of the data set I
is reached. I BUE-SP(n)
I
The BKWD option must not be specified Iwhere wnw is a decimal integer constant, or
with either the REUSE option or the GENKEY la variable with the attributes FIXED
option. Also, the WRITE statement is not IBINARY(31,O) STATIC.
allowed for files declared with the BKWD
option.
OPTIMIZATION OF INPUT/OUTPUT OPERATIONS

REUSE OPTION In general, I/O operations are performed by

library subroutines called from compiled
code. Under certain conditions, however,
The REUSE option specifies that an OUTPUT Ithe optimizing compiler can, when
file associated with a VSAM data set is to ,requested, provide in-line code to carry
be used as a workfile. out these operations, thus saving the
overheads of library calls. This gives
The effect of the option is to cause the considerably faster execution of the I/O
data set to be treated as an empty data set statements.
each time the file is opened. Any
secondary allocations for the data set are I It should be noted that the use.of in-
released, and the data set is treated Iline input/output code may result in
exactly as if it were being opened for the I reduced error-handling capability. In
first time. I particular, if a program-check interrupt or
Ian ABEND occurs during in-line
A file with the REUSE option must not be linput/output, the error message produced
associated with a data set that. has lmay contain incorrect offset and statement
lalternate indexes. Inumber information. Also, execution of a
I IGOTO statement in an ERRORon-ttnit for such
,f
I BUFND OPTION
Ian interrupt may cause a further program
I check.

I For an I/O statement to be executed in-

I line, the data set being accessed or
IThe BUFND option specifies the number of created must be CONSECUTIVE, and the file
Idata buffers required for a VSAM data set. used must be a non-parameter file constant
IThe format of the option is: with the attributes SEQUENTIAL, BUFfERED,

1 70 OS PL/I CKT AND OPr LRM PART I

and 'either INPUT or OUTPUT. Record improved by specifying the INDEXAREA,
variables in the data set must not be NOWRITE, and ADDBUFF options. Details are
subscripted structures. The ENVIRONMENT given under -Data Management optimization-
attribute must specify the following later in this chapter.
options: TOTAL and either F, FB, FS, FBS,
D, DB, V, VB, or U record format. If
varying-length strings are to be
transmitted, and the file is not an output Teleprocessing Data Sets
file with V or VB record format, the
SCALARVARYING option is also needed. The
file declaration would therefore be as A teleprocessing data set comprises a queue
follows: of messages that constitute the input to a
PL/I message processing program. The
DCL F FILE RECORD SEQUENTIAL BUFFERED messages are retrieved sequentially: keys
INPUTIOUTPUT ENV(CONSECUTIVE are used to identify the terminal
FIFBIFSIFBSIDIDBIVIVBIU associated with the message.
TOTAL (SCALARVARYING]
[RECSIZE(n)] (BLKSIZE(n)]): The TP(M) option specifies that the file
is a teleprocessing file and can only be
The standard default attributes and option associated with a teleprocessing data set.
are underlined. At least one of the Each I/O operation in the PL/I program
underlined attributes must be specified, causes a complete message to be transmitted
otherwise the file would be given the to or from the data set. The message can
attribute STREAM by default. If the file consist of one logical record, or several
is to be printed, one or other of the logical records, on the data set.
printer-punch control options CTLASA and
CTL360 must also be specified in the The TP(R) option is the same except that
ENVIRONMENT attribute: this information each I/O operation applies to one logical
cannot be supplied via the DD statement record only in the data set. This record
when the record format is specified in the can be a message or part of a complete
ENVIRONMENT attribute. message.

Note: The TOTAL option cannot be specified A teleprocessing file can be declared
for files associated with VSAM data sets or with the following attributes only:
for device-associated files (described
later in this chapter), or for files FILE
reading Optical Mark Read data. RECORD
INPUT or OUTPUT
The statement READ SET will always be BUFFERED or UNBUFFERED
implemented by in-line code if it specifies TRANSIENT
a file declared or indicated as above, KEYED
except when a file with the attribute ENVIRONMENT
BACKWARDS is used to transmit U-format
records. The other record I/O statements, For teleprocessing applications, the
namely READ INTO, WRITE FROM, and LOCATE, only environment options that can be
generate in-line code provided: specified are:

1. the record variable declaration does TP({MIR} )

not include an expression as a string RECSIZE(record-length)
length, an array bound, or an area BUFFERS(n)
size;
Record format must not be specified for
and teleprocessing programs.

2. the ENVIRONMENT attribute specifies

record size for F-, FB-, FS-, FBS-, or
V-format records, or the block size MAGNETIC TAPE HANDLING OPTIONS
for U-format records.

I/O statements compiled by the checkout LEAVE and REREAD Options

compiler always generate a library call.
The volume disposition options allow the
When in-line code is employed to programmer to specify the action to be
implement an I/O statement, the compiler taken when the end of a magnetic tape
gives an informatory message. volume is reached, or when a data set on a
magnetic tape volume is closed. The LEAVE
The speed of I/O operations when option prevents the tape from being
accessing an INDEXED data set can be rewound. The REREAD option rewinds the

Chapter 12: Record-oriented Transmission 171

r---------------------------------------------------------------------------------------,
ENVIRONMENT 1 DISP I Action 1
Option 1 Parameter. 1 I
---------------------------------------------------------------------------------------1
REREAD 1 1 Positions the current volume to reprocess the,
I I data set. Repositioning for a BACKWARDS file ,
I 1 is at the physical end of the data set. ,
---------------------------------------------------------------------------------------1
LEAVE 1 I Positions the current volume at the logical ,
I 1 end of the data set. Repositioning for a I
1 I BACKWARDS file is at the physical beginning I
, 1 of the data set. 1
---------------------------------------------------------------------------------------1
Neither 1 PASS I Positions the volume at the end of the data I
REREAD nor I I set I
I LEAVE I I ,
I I I ,
I I DELETE I Rewinds the current volume ,
I I I ,
I I REEP, CATLG, 1 Rewinds and unloads the current volume ,
1 I UNCATLG , I
L---------------------------------------------------------------------------------------J
Figure 12.3. Effect of LEAVE and REREAD options

r---------------------------------------------------------------------------------------,
CTLASA code I CTL360 code bytes I ,
-----------------------------------------------------------------1
action before I action after I action without, Action
I
I
printing 1 printing I printing I I
+ 00000001 print only (no space)
b 00001001 00001011 Space 1 line
'0 00010001 00010011 Space 2 lines
00011001 00011011 Space 3 lines
1 10001001 10001011 Skip to channel 1
2 10010001 10010011 Skip to channel 2
3 10011001 10011011 Skip to channel 3
4 10100001 10100011 Skip to channel 4
5 10101001 10101011 Skip to channel 5
6 10110001 10110011 Skip to channel 6
7 10111001 10111011 Skip to channel 7
8 11000001 11000011 Skip to channel 8
9 11001001 11001011 Skip to channel 9
A 11010001 11010011 Skip to channel 10
B 11011001 11011011 Skip to channel 11
C 11100001 11100011 Skip to channel 12
L---------------------------------------------------------------------------------------J
Figure 12.4. CTLASA and CTL360 print control codes for the IBM 1403 Printer

tape to permit reprocessing of the data associated with CONSECUTIVE data sets.
set. If neither of these is specified, the They specify that the first character of a
action at end of volume or on closing of a record is to be interpreted as a control
data set is controlled by the DISP character.
parameter of the associated DD statement.
The effects of the options are summarized
in figure 12.3. 1. The CTLASA option specifies ANSI
standard control characters.

2. The CTL360 option specifies IBM

PRINTER/PUNCH CONTROL (CTL360/CTLASA) machine code control characters.

The codes that can be used with these

The printer/punch control options CTLASA options are listed with their actions in
and CTL360 apply only to OUTPUT files figures 12.4 and 12.5.

172 OS PL/I CKT AND OPT LRM PART I

DATA INTERCHANGE (COBOL) FROM statements. The file name cannot be
passed as an argument or assigned to a file
variable. The variable to be transmitted
The COBOL option facilitates the must not be subscripted.
interchange of data between programs
written in PL/I and programs written in
COBOL. It specifies that structures in the
data set associated with the file will be
mapped as they would be in American
r-----------------------------------------,
CTL360 code I Action
National Standard COBOL. The COBOL bytes I
structures can be SYNCHRONIZED or
unsynchronized; it is the programmer's 00001101 Print on line 1
responsibility to ensure that the 00010101 Print on line 2
associated PL/I structure has the 00011101 Print on line 3
equivalent alignment stringency, that is, 00100101 . Print on line 4
it must be ALIGNED or UNALIGNED, 00101101 Print on line 5
respectively. 00110101 Print on line 6
00111101 Print on line 7
The restrictions noted below apply to 01000101 Print on line 8
the handling of a file with the COBOL 01001101 Print on line 9
option. The PL/I equivalents of COBOL data 01010101 Print on line 10
types are given in chapter 19, 01011101 Print on line 11
-Interlanguage Communication Facilities". 01100101 Print on line 12
01101101 Print on line 13
r-----------------------------------------,
ICTLASA codelcTL360 codel Action 1
01110101
01111101
Print
Print
on
on
line
line
14
15
I I bytes I I 10000101 Print on line 16
1-----------------------------------------1
I V I 00000001 Iselect stacker 1 I
10001101
10010101
Print
Print
on
on
line
line
17
18
I W I 01000001 Iselect stacker 2 I 10011101 Print on line 19
I I 10000001 ISelect stacker 3 1 10100101 Print on line 20
L-----------------------------------------J 10101101
10110101
Print
Print
on
on
line
line
21
22
Figure 12.5. CTLASA and CTL360 control 10111101 Print on line 23
codes for the IBM 2540 11000101 Print on line 24
Card Read Punch 11001101 Print on line 25
L-----------------------------------------J
r-----------------------------------------,
ICTLASA code I Action
Figure 12.7. CTL360 print control
codes for the IBM 3525
Card Punch
b ISpace 1 line and print
o ISpace 2 lines and print
ISpace 3 lines and print
1 ISkip to channel 1 and print
2 I Skip to channel 2 and print
3 ISkip to channel 3 and print
4 ISkip to channel 4 and print If an ON-condition is raised during the
5 ISkip to channel 5 and print execution of a READ statement, the variable
6 ISkip to channel 6 and print named in the INTO option cannot be used in
7 I Skip to channel 7 and print the on-unit. If the completed INTO
8 I Skip to channel 8 and print variable is required, there must be a
9 ISkip to channel 9 and print normal return from the on-unit.
A ISkip to channel 10 and print
B ISkip to channel 11 and print
C ISkip to channel 12 and print The EVENT option can be used only if the
compiler can determine that the PL/I and
INote: Use of the '+' control character COBOL structure mappings are identical
Iwould result in abnormal termination of (i.e., all elementary items have identical
Ithe program. boundaries). If the mappings are not
L-----------------------------------------J identical, or if the compiler cannot tell
whether they are identical, an intermediate
Figure 12.6. CTLASA print control variable is created to represent the level
codes for the IBM 3525 1 item as mapped by the COBOL algorithm.
Card Punch The PL/I variable is assigned to the
intermediate variable before a WRITE
A file with the COBOL option can be used statement is executed, or aSSigned from it
only for READ INTO, WRITE FROM, and REWRITE after a READ statement has been executed~

Chapter 12: Record-oriented Transmission 173

IN-LINE CODE OPTIMIZATION (TOTAL) Ithan zero or greater than 64,000,
lunpredictable results will occur.

The purpose of this option is to aid the The NOWRITE option is used for DIRECT
optimizing compiler in the production of UPDATE files. It informs the compiler that
efficient compiled code. In particular, i t no records are to be added to the data set
allows the compiler to use in-line code for and that data management modules concerned
certain I/O operations (see "Optimization solely with adding records are not
of Input/Output Operations" earlier in this required; i t thus allows the size of the
chapter). It specifies that no attributes object program to be reduced.
will be merged from the OPEN statement or
the I/O statement. In other words, the The ADDBUFF option can be specified for
complete set of attributes is to be built a DIRECT INPUT or DIRECT UPDATE file with
up at compile time from explicitly declared INDEXED data set organization and F-format
and default attributes. records to indicate that an area of
internal storage is to be used as a
The UNDEFINEDFILE condition is raised if workspace in which records on the data set
any attribute that was not explicitly can be rearranged when new records are
declared appears on the OPEN statement, or added. The size of the workspace is
if the I/O statement implies a file assumed to be equivalent to one track of
attribute that conflicts with a declared or the direct device used. The option need
default attribute. not be specified for DIRECT INDEXED files
with V-format records, as the workspace is
The checkout compiler accepts and checks automatically allocated for such files.
the TOTAL option but does not perform any
optimization.

Notes: (1) The TOTAL option cannot be KEY CLASSIFICATION (GENKEY)

specified for files associated with VSAM
data sets or for device-associated files
(described later in this chapter), or files The GENKEY (generic key) option applies
reading Optical Mark Read data. only to INDEXED and VSAM key-sequenced data
1(2) The use of the TOTAL option may result sets. It enables the programmer to
lin reduced error-handling capability. See classify keys recorded in a data set and to
I "Optimization of Input/Output Operations" use a SEQUENTIAL KEYED INPUT or SEQUENTIAL
learlier in this chapter. KEYED UPDATE file to access records
according to their key classes.

A generic key is a character string tha~

DATA MANAGEMENT OPTIMIZATION identifies a class of keys: all keys that
(INDEXAREA/NOWRITE/ADDBUFF) begin with the string are members of that
class. For example, the recorded keys
'ABCO', 'ABCE', and 'ABDF' are all members
The data management optimization options in of the classes identified by the generic
the ENVIRONMENT attribute increase program keys 'A' and 'AB', and the first two are
efficiency, in certain circumstances, when also members of the class 'ABC'; and the
DIRECT files are used to access INDEXED three recorded keys can be considered to be
data sets. unique members of the classes 'ABCD',
'ABCE', and 'ABDF', respectively.
The INDEXAREA option improves the
input/output speed of a DIRECT INPUT or The GENKEY option allows the programmer
DIRECT UPDATE file with INDEXED data set to start sequential reading or updating of
organization, by having the highest level an INDEXED data set from the first non-
of index placed in main storage. The dummy record that has a key in a .particular
"index area size" enables the programmer to class; the class is identified by the
limit the amount of main storage he is inclusion of its generic key in the KEY
prepared to allow for an index area. The option of a READ statement. Subsequent
size, when specified, must be a decimal records can be read by READ statements
integer constant or a variable with without the KEY option. No indication is
attributes FIXED BINARY (31,0) STATIC whose given when the end of a key class is
Ivalue lies within the range zero through reached.
164,000. If the "index area size" is not
specified, the highest level index is moved Note that, although the first record
unconditionally into main storage. If an having a key in a particular class can be
index area size is specified, the highest retrieved by READ KEY, the actual key
level index is held in main storage, cannot be obtained unless the records have
provided that its size does not exceed that embedded keys, since the KEYTO option
specified. If the specified size is less cannot be used in the same statement as the

174 OS PL/I CKT AND OPT LRM PART I

KEY option. identifies a specific record (whose key can
be considered to be the only member of its
In the following example, a key length class) •
of more than three bytes is assumed.

DCL IND FILE RECORD SEQUENTIAL KEYED

UPDATE ENV (INDEXED GENKEY); NUMBER OF CHANNEL PROGRAMS (NCP)

The NCP option specifies the number of

incomplete input/output operations with the
READ FILE(IND) INTO (INFIELD) KEY ('ABC'); EVENT option that can be handled for the
file at anyone time. For consecutive and
regional sequential files, it is an error
to allow more than the specified number of
NEXT: READ FILE (IND) INTO (INFIELD); events to be outstanding.

For indexed files, any excess operations

are queued, and no exceptional condition is
GO TO NEXT; raised. However, specification of the
number of channel programs required may aid
The first READ statement causes the first optimization of I/O with an indexed file.
non-dummy record in the data set whose key The NCP option has no effect with a
begins with 'ABC' to be read into INFIELD; regional direct file.
each time the second READ statement is
executed, the non-dummy record with the The decimal integer constant specified
next higher key will be retrieved. with NCP must have a value in the range 1
Repeated execution of the second READ through 99: otherwise, 1 is assumed.
statement could result in reading records
from higher key classes since no indication This option is eqUivalent to the NCP
is given when the end of a key class is subparameter of the DCB parameter of the DD
reached. It is the responsibility of the statement.
programmer to check each key if he does not
wish to read beyond the key class. Any I A file declared with ENVIRONMENT(VSAM)
subsequent execution of the first READ Ican never have more than one incomplete
statement would reposition the file to the linput/output operation at anyone time. If
first record of the key class 'ABC'. Ithe NCP option is specified for such a
Ifile, i t is ignored.
If the data set contains no records with
keys in the specified class, or if all the
records with keys in the specified class
are dummy records, the KEY condition is TRACK OVERFLOW (TRKOFL)
raised. The data set is then positioned
either at the next record that has a higher
key or at the end of the file. Track overflow is a feature of the
operating system which can be incorporated
Note how the presence or absence of the at system generation time: i t requires the
GENKEY option affects the execution of a record overflow feature on the direct
READ statement that supplies a source key access storage control unit. Track
that is shorter than the key length overflow allows a record to overflow from
specified in the KEYLEN SUbparameter of the one track to another. It is useful in
DD statement that defines the data set. achieving a greater data packing
GENKEY causes the key to be interpreted as efficiency, and allows the size of a record
a generic key, and the data set is to exceed the capacity of a track.
positioned to the first non-dummy record in
the data set whose key begins with the
source key. If the GENKEY option is not Note: Track overflow is not available for
specified, a short source key is padded on REGIONAL(3) or INDEXED data sets.
the right with blanks to the specified key
length, and the data set is positioned to
the record that has this padded key (if such
a record exists). VARYING-LENGTH STRING OPTION
(SCALARVARYING)
The use of the GENKEY option does not
affect the result of supplying a source key
whose length is greater than or equal to The SCALARVARYING option is used in the
the specified key length. The source key, input/output of varying-length strings.
truncated on the right if necessary, The transmission of element varying-length

Chapter 12: Record-oriented Transmission 115

strings using locate mode is possible only 1 S n S recordsize - keylength +1
when this option is specified. This is
achieved by the inclusion or recognition of That is, the key cannot be larger than the
a two-byte length prefix to an element record, and must be contained completely
varying-length string when the string is within the record.
transmi tted.
If KEYLOC is not specified, the value of
When storage is allocated for a varying- the RKP subparameter of the DCB parameter
length string, the compiler includes a two- of the DO statement is used. If this
byte prefix that specifies the current sUbparameter is not specified, then RKP=O
length of the string. For an element is assumed.
varying-length string, this prefix is
included on output, or recognized on input, ~
only if SCALARVARYING is specified for the
file. 1. The RKP value for a particular byte
always differs from the KEYLOC value.
When locate mode statements (LOCATE and See "Embedded Key·, in ·INDEXED
READ SET) are used to create and read a ORGANIZATION", later in this chapter.
data set with element varying-length
strings, SCALARVARYING must be specified to 2. When KEYLOC is specified, the key is
indicate that a length 'prefix is present, always part of the variable. When RKP
since the pointer that locates the buffer is specified, the key is part of the
will always be assumed to pOint to the variable only when RKP~
start of the length prefix.
3. If SCALARVARYING is specified, the
emabedded key must not immediately
precede or follow the first byte:
1. When SCALARVARYING is specified and hence, KEYLOC must specify greater
element varying-length strings are than 2.
transmitted, the programmer must allow
two bytes in the record length to
include the length prefix.
DCB Subparameters
2. A data set created using SCALARVARYING
should be accessed only by a file that
also specifies SCALARVARYING. Some of the information that can be
specified in the options of the ENVIRONMENT
3. SCALARVARYING and CTLASA/CTL360 must attribute can also be specified in the
not be specified for the same file, as subparameters of the DCB parameter of a DO
this causes the first data byte to be statement. The table gives a list of
ambiguous. equivalents:
4. SCALARVARYING must not be used with ENV Option DCB Subparameter
data sets created by the PL/I (F)
compiler; this compiler neither Record format RECFM
creates nor recognizes a length RECSIZE LRECL
prefix. BLKSIZE BLKSIZE
BUFFERS BUFNO
CTLASA/CTL360 RECFM
NCP NCP
KEY LENGTH OPTION (KEYLENGTH) TRKOFL RECFM
KEYLENGTH KEYLEN
KEYLOC RKP
The KEYLENGTH option specifies the length ASCII ASCII
of the recorded key for KEYED files. BOFOFF BUFOFF
KEYLENGTH must be specified for INDEXED or
REGIONAL(3) files.
DEVICE-ASSOCIATED FILES (IBM 3525 CARD
PUNCH)
KEY LOCATION OPTION (KEYLOC)
The IBM 3525 device is an 80-column card
The KEYLOC option can be used with INDEXED punch, available to IBM System/370 users,
data sets, when the data set is created, to that can also read cards and print on them.
specify the start poSition of an embedded The CTLAsA and CTL360 control characters
key in a record. The position given must for the device are given in figures 12.13
be within the limits: and 12.14 respectively.

176 OS PL/I CKT AND OPT LRM PART I

 Advantage can be taken of the multiple statement for the file. If the LOCATE
capabilities of the device by associating statement is used on both print and
two or three files together with the device punch associated files, a multiple
so that more than one of the operations CLOSE statement must be used,
read, punch, and print can be performed on specifying the punch file before the
the same card during one pass through the print file. For example:
device. Details of the use of the device,
together with the IBM 3505 card reader, a~e LOCATE A FILE(PUNCHOUT);
given in the programmer's guide for the LOCATE B FlLE(PRINTOUT);
compiler; however, certain restrictions CLOSE FILE(PUNCHOUT),FILE(PRINTOUT);
have to be considered at the time of
writing the program. These restrictions 9. The ANS print control character '+'
are as follows: (or SKIP(O» is not allowed with the
IBM 3525.
1. Device-associated files must have the
RECORD attribute and must be either 10. Files associated with column binary or
all BUFFERED or all UNBUFFERED. Optical Mark Read data sets must be
RECORD files.
2. The records must be F-format. The
maximum record size is 80 for read and
punch files and 64 for print files,
plus one byte for punch/print control
characters.
3. ENVIRONMENT (TOTAL) cannot be used. ASCII DATA SETS
4. When a read or punch associated file
is opened, the value of the BUFFERS Data sets on magnetiC tape using ASCII may
option (for BUFFERED files) or of NCP be created and accessed in PL/I. The
(for UNBUFFERED files) will be set to implementation supports F, FB, U, D, and DB
one. record formats. F, FB, and U formats are
treated in the same way as with other data
5. Device-associated files may be opened sets; D and DB formats, which correspond to
in any order, but all of the files V and VB formats with other data sets, are
must be open before any transmission described below.
takes place to or from anyone of
them. In addition to the record format, two
other ENVIRONMENT options may be specified:
6. Depending on the files associated, the ASCII, and the buffer offset option BUFOFF.
appropriate input/output operations on
each card must strictly follow the Only character data may be written onto
order read-punch-print. If the an ASCII data set: when the data set is
sequence rules are not followed, the created, transmission must be from a
ERROR condition is raised. Only the character string variable. This variable
print operation can be omitted or may have the attribute VARYING as well as
repeated. CHARACTER, but the two length bytes of a
varying-length character string can not be
1. A print-associated file that uses transmi tted; in other words, varying-length
control characters for line character strings can not be transmitted to
poSitioning must not attempt to feed a an ASCII data set using a SCALARVARYING
card. Such an attempt would occur if file. Also, data aggregates containing
an instruction to print beyond the varying~length strings may not be
maximum line number (2 or 25) for the transmitted.
card were issued, or if a control
character that implied a new record Since an ASCII data set must be on
were used. For example, the control magnetic tape, it must be of CONSECUTIVE
character '1' specifies printing on organization. The associated file must be
the first line of the next card. BUFFERED.
8. Device-associated files can normally
be closed in any order, but no
transmdssion can take place after any
one of the files has been closed. As
a result, care is needed if the LOCATE ASCII Option
statement is used for BUFFERED OUTPUT
files. The output from a LOCATE
statement does not actually take place This option specifies that the code used to
until the next LOCATE, WRITE, or CLOSE represent data on the data set is ASCII.

Chapter 12: Record-oriented Transmission 177

BUFOFF Option and Block Prefix Fields D-format: The records are unblocked: each
record constitutes a Single
block. Each record consists of:
At the beginning of each block in an ASCII
data set, there may be a field known as the Four control bytes
block prefix field. It may be from one to Data bytes
99 bytes long. The buffer offset option
indicates the length of this field to data The four control bytes contain
management, so that the accessing or the length of the record: this
creation of data is started at th1s offset value is inserted by data
from the beginning of each physical block. management and requires no
PL/I does not support access to this field, action from the programmer.
and in general it does not contain In addition, there may be, at
information Which is used in these the start of the block, a block
implementations. There is one situation in prefix field, which may contain
which data management does use information the length of the block.
in the block prefix: with variable length
records (that is, D- or DB-format records), DB-format: The records are blocked. All
the block prefix field may be used to other information given for
record the length of the block. In this D-format applies to DB-format.
case, it is four bytes long and contains a
right-aligned, decimal character value that
gives the length of the block in bytes,
including the block prefix field itself. Default Rules
It is then exactly equivalent to a block
length field.
In addition to the rules given under
The format of the buffer offset option "Record Format Defaults", the following
is BUFOFF[(n»). A numerical value equal to rule applies:
the length of the prefix may be specified
for wnw. It may be specified as either a If ASCII is not specified in either the
decimal integer constant or as a variable ENVIRONMENT option or the DD statement, but
with the attributes FIXED BINARY(31,O) one of BUFOFF, Dr or DB is specified, then
STATIC. Its minimum value is zero and its ASCII is assumed.
maximum is 99. The absence of a prefix
length specification indicates that the
block prefix is to be used as a block
length field: it implies that the field is Consecutive Organization
four bytes long. The length of the block
is inserted in the prefix by data
management. In a data set with CONSECUTIVE
organizationl the records have no keys.
On input, any ASCII data set may be When the data set is created, records are
accessed if i t has a block prefix field of written consecutively in the order in which
length one to 99 bytes, or no block prefix they are presented. The records can be
field at all: and i t may be accessed retrieved only in the order in which they
wh~her or not the block prefix field is were written or in the reverse order when
used as a block length field. On output, a using the BACKWARDS attribute: therefore
data set using anyone of the valid record the associated file must have the
formats may be created without a block SEQUENTIAL attribute. A CONSECUTIVE data
prefix, but the only situation in which the set can have F-format, FB-format, FBS-
creation of a block prefix is supported by format, V-format, VB-format, VS-format,
PL/I is when it is used as a block length VBS-format, D-format, DB-format, or U-
field. The only permissible buffer offset format records. The BACKWARDS attribute
specification on output is therefore cannot be specified when a data set has V-,
BUFOFF, with no prefix length VB-, VS-, VBS-, 0-, or DB-format records.
specification.
Note the difference between the
The BUFOFF option may be used with ASCII CONSECUTIVE option of the ENVIRONMENT
data sets only. attribute and the SEQUENTIAL attribute.
CONSECUTIVE specifies the physical
organization of a data set: SEQUENTIAL
specifies how a file is to be processed. A
D-format and DB-format Records data set with CONSECUTIVE organization must
be associated with a SEQUENTIAL file; but a
data set with INDEXED or REGIONAL
Each record may be of a different length. organization can be associated with either
The two formats are: a SEQUENTIAL or DIRECT file.

178 OS PL/I CRT AND OPT LRM PART I

 A CONSECUTIVE data set on magnetic tape in logical sequence according to keys that
can be read forwards or backwards. If the are associated with each record. A key is
data set is to be read backwards, the a character string that can identify each
associated file must have the BACKWARDS record uniquely. Logical records are
attribute. If a data set is first read or arranged in the data set in ascending key
written forwards and then read backwards in sequence according to the Systeml360 and
the same program, the LEAVE option should System/370 collating sequence. Indexes
be specified in the ENVIRONMENT attribute associated with the data set are used by
to prevent normal rewind when the file is the operating system data-management
closed (or, with a multi-volume data set, routines to locate a record when the key is
when volume-switching occurs). Variable- supplied.
length record data sets cannot be read
backwards. Unlike CONSECUTIVE organization, INDEXED
organization does not require every record
Once a CONSECUTIVE data set has been to be accessed in sequential fashion. An
created, the file that accesses it can be INDEXED data set must be created
opened for SEQUENTIAL INPUT, OUTPUT or, for sequentially; but, once i t has been
direct access data sets, UPDATE. If it is created, the associated file may have the
opened for OUTPUT, DISP=MOO must be attribute SEQUENTIAL or DIRECT as well as
specified in the DO statement; records can INPUT or UPDATE. When the file has the
then be added to the end of the data set. DIRECT attribute, records may be retrieved,
(If DISP=MOD is not specified, the data set added, deleted, and replaced at random.
will be overwritten.) Figure 12.12 lists
the data transmission statements and Figure 12.9 lists the data-transmission
options that can be used to create and statements and options that can be used to
access a CONSECUTIVE data set. create and access an INDEXED data set.

SEQUENTIAL UPDATE KEYS

When a CONSECUTIVE data set is accessed by There are two kinds of keys, recorded keys
a SEQUENTIAL UPDATE file, a record must be and source keys. A recorded key is a
retrieved with a READ statement before it character string that actually appears with
can be updated by a REWRITE statement; each record in the data set to identify
however, every record that is retrieved that record; its length cannot exceed 255
need not be rewritten. A REWRITE statement characters. A source key is the character-
will always update the last record read. string value of the expression that appears
in the KEY or KEYFROM option of a data
Consider the following: transmission statement to identify the
record to which the statement refers; for
READ FILE(F) INTO(A); direct access of an INDEXED data set, each
transmission statement must include a
source key.

READ FILE(F) INTO(B); The length of the recorded keys in an

INDEXED data set is defined by the
KEYLENGTH environment option or the KEYLEN
sUbparameter of the DD statement that
REWRITE FILE(F) FROM(A); defines the data set. If the length of a
source key is greater than the specified
The REWRITE statement updates the record length of the recorded keys, the source key
which was read by the second READ is truncated on the right. If the source
statement. The record that was read by the key is shorter than the specified key
first statement cannot be rewritten after length, and GENKEY has not been specified,
the second READ statement has been the source key is padded with blanks on the
executed. right to the specified length.

The recorded keys in an INDEXED data set

may be separate from, or embedded within,
Indexed Organization the logical records. If the keys are
embedded within the records, either the
KEYLOC(n) environment option should be
A data set with INDEXED organization must specified when the data set is created, or
be on a direct-access device. Its records, the sUbparameter RKP must be included in
which can be either F-format or V-format the DD statement for the associated data
records, blocked or unblocked, are arranged set (in the job step in which the data set

Chapter 12: Record-oriented Transmission 179

 r---------------------------------------------------------------------------------------,
IFile deciaration 1 1Vaiid statements a , with options that must10ther options that can I
1 I appear lalso be used 1
1---------------------------------------------------------------------------------------1
1SEQUENTIAL OUTPUTIWRITE FILE(file-expr) FROM(variable): I 1
I BUFFERED 1 I 1
I ILOCATE variable FILE(file-expr): 1SET (pointer-variable) I
1---------------------------------------------------------------------------------------1
'SEQUENTIAL OUTPUTIWRITE FILE(file-expr) FROM(variable): I EVENT (event-variable) ,
I UNBUFFERED 1 I '
,---------------------------------~-----------------------------------------------------1
ISEQUENTIAL INPUT IREAD FILE(file-expr) INTO(variable): I I
1BUFFERED I I 1
I IREAD FILE(file-expr) SET(pointer-variable): I ,
1 IREAD FILE(file-expr) IGNORE(expression): I I
I~--------------------------------------------------------------------------------------
1SEQUENTIAL INPUT IREAD FILE(file-expr) INTO(variable): I EVENT (event-variable)
UNBUFFERED 1 I
IREAD FILE(file-expr) IGNORE(expression): I EVENT (event-variable)
---------------------------------------------------------------------------------------
SEQUENTIAL UPDATEIREAD FILE(file-expr) INTo(variable): I
BUFFERED I I
IREAD FILE(file-expr) SET(pointer-variable): I
IREAD FILE(file-expr) IGNORE(expression): I
IREWRITE FILE(file-expr): I FROM (variable)
SEQUENTIAL UPDATEIREAD FILE(file-expr) INTO(variable): I EVENT (event-variable)
UNBUFFERED I I
IREAD FILE(file-expr) IGNORE(expression): I EVENT (event-variable)
IREWRITE FILE(file-expr) FROM(variable): I EVENT (event-variable)
---------------------------------------------------------------------------------------1
1The complete file declaration would include the attributes FILE, RECORD, and I
ENVIRONMENT I
I
aThe statement READ FILE (file-expression) : is a valid statement and is equivalent to:1
READ FILE (file-expression) IGNORE (1): I
L---------------------------------------------------------------------------------------J
Figure 12.8. Statements and options permitted for creating and accessing CONSECUTIVE
I data sets

is created), to give the location of the 2. The record format

key within the record.
For example, if the embedded key begins
Note: All VSAM key-sequenced data sets have at the tenth byte of a record variable,
embedded keys, even if they have been then the specifications are:
converted from ISAM data se~s with non-
embedded keys. Fixed length: KEYLOC(10)
RKP=9
variable-length: KEYLOC(10)
Embedded Keys RKP=13

If KEYLOC is specified with a value

The KEYLOC option specifies the absolute equal to or greater than one, embedded kEYS
position of an embedded key from the start exist in the record variable and on the
of the data in a record, while the RKP data set. If KEYLOC is equal to zero, or
suhparameter specifies the position of an is not specified, the RKP value is used: as
embedded key relative to the start of the a result, embedded keys may not always be
record. present in the record variable or the data
set. If KEYLOC(l) is specified, it must be
Thus the equivalent KEYLOC and RKP values specified for every file that accesses the
for a particular byte are affected by the data set. This is necessary because
following: KEYLOC (1) cannot be converted to an
unambiguous RKP value. (Its equivalent is
1. The KEYLOC byte count starts at 1: the RKP=O for fixed format, which in turn
RKP count starts at 0 implies non-embedded keys.) The effect of

180 OS PL/I CKT AND OPT LRM PART I

r---------------------------------------------------------------------------------------,
IFi1e declaration~lvalid
statements 2 ,
with options that must IOther options that can
I I appear lalso be used
SEQUENTIAL OUTPUTIWRITE FILE(file-expr) FROM (variable) I
I KEYFROM(expression): I
I I
ILOCATE variable FILE(file-expr) I SET (pointer-variable)
I KEYFROM(expression); I
SEQUENTIAL INPUT I READ FILE (file-expr) INTO(variable): I KEY (expression) or KEYTO
I I (character-string-
I I variable)
I READ FILE(file-expr) SET(pointer-variable);IKEY(expression) or KEYTO
I I (character-string-
I I variable)
I READ FILE (file-expr) IGNORE(expression): I

SEQUENTIAL UPDATEIREAD FILE(file-expr) INTO(variable); KEY (expression) or KEYTO

I (character-string-
I variable)
IREAD FILE(file-expr) SET(pointer-variable): KEY(expression) or KEYTO
I (character-string-
I variable)
IREAD FILE(file-expr) IGNORE(expression):
I
IREWRITE FILE(file-expr): FROM (variable)
I
IDELETE FILE(file-expr): KEY(expression)

DIRECT INPUT IREAD FILE(file-expr) INTO(variable) I EVENT (event-variable)

I KEY(expression): I
I DIRECT UPDATE IREAD FILE(file-expr) INTO (variable) I EVENT (event-variable)
I I KEY(expression)i I
I I I
I IREWRITE FILE(file-expr) FROM(variable) IEVENT(event-variable)
I I KEY(expression); I
I I I
I IWRITE FILE(file-expr) FROM(variable) IEVENT(event-variable)
I I KEYFROM(expression)i I
I I I
I IDELETE FILE(file-expr) KEY(expression): I EVENT (event-variable)
L---------------------------------------------------------------------------------------J
Figure 12.9 (Part 1 of 2). Statements and options permitted for creating and
accessing INDEXED data sets

the use of either option is shown in figure each record, even when there is already an
12.10. embedded key. If the records are blocked,
the key of only the last record in each
Programs written for the PL/I F Compiler block is recorded separately in front of
which use records with embedded keys can be the block.
compiled without alteration to the
ENVIRONMENT attribute for the inclusion of During the execution of a WRITE
the KEYLOC option, if the original RKP statement that adds a record to a data set
subparameter is specified when the with embedded keys, the value of the
recompiled program is executed. expression in the KEYFROM option is
assigned to the embedded key position in
The use of embedded keys avoids the need the record variable. Note that a record
for the KEYTO option during sequential variable can be declared as a structure
input, but the KEYFROM option is still with an embedded key declared as a
required for output. (However, the data structure member, but that such an embedded
specified by the KEYFROM option may be the key must not be declared as a VARYING
embedded key portion of the record variable string.
itself.) In a data set with unblocked
records, a separate recorded key precedes For a LOCATE statement, the KEYFROM

Chapter 12: Record-oriented Transmission 181

r-----------------
DIRECT UPDATE READ FILE(file-expr) INTO (variable)
-------------------------,
EVENT (event-variable)
EXCLUSIVE KEY(expression); and/or NOLOCK

REWRITE FILE(file-expr) FROM (variable) EVENT (event-variable)

KEY(expression):

WRITE FILE(file-expr) FROM (variable) EVENT (event-variable)

KEYFROM(expression);

DELETE FILE(file-expr) KEY(expression): EVENT(event-variable)

UNLOCK FILE(file-expr) KEY(expression);

~The complete file declaration would include the attributes FILE, RECORD, and
ENVIRONMENT: if any of the options KEY, KEYFROM, and KEYTO is used, i t must
also include the attribute KEYED.

2The statement: READ FILE (file-expression); is equivalent to the statement:

READ FILE (file-expression) IGNORE (1):

Notes: The attribute UNBUFFERED is ignored and BUFFERED is assumed for INDEXED
SEQUENTIAL and SEQUENTIAL files.

Use of the DELETE statement is invalid if OPTCD=L (DCB subparameter) was not
specified when the data set was created or if the RKP subparameter is zero for
FB records, or four for V and VB records.
L---------------------------------------------------------------------------------------J
Figure 12.9 (part 2 of 2). Statements and options permitted for creating and
accessing INDEXED data sets

r---------------------------------------------------------------------------------------1
I I I Data Set
KEYLOC
II RKP
I
I Record Variable
1-----------------------
I Unblocked I Blocked
(n) I I I records I records
---------------------------------------------------------------------------------------
n>l I RKP equivalent = Key Key I Key
I n-1+C~ I
---------------------------------------------------------------------------------------
n=l I No equivalent Key Key2 I Key

I RKP=C~ I No key I No key I Key3

n=O
or not
1---------------------------------------------------------------
1 I I I
specified I RKP>C1 I Key I Key I Key

1 C = number of control bytes, if any: C=O for fixed-length records

C=4 for variable-length records
2 In this instance the key is not recognized by data management.
3 Each logical record in the block has a key.
L---------------------------------------------------------------------------------------J
Figure 12.10. Effect of KEYLOC and RKP values on establishing embedded keys in
record variables or data sets

182 OS PL/I CKT AND OPT LRM PART I

string is assigned to the embedded key when subparameter OPTCD=L.
the next operation on the file is
encountered. Except that the EVENT option cannot be
used, rules governing the relationship
between the READ and REWRITE statements for
a SEQUENTIAL UPDATE file that accesses an
DUMMY RECORDS INDEXED data set are identical to those for
a CONSECUTIVE data set (described above).

Records within an INDEXED data set are Embedded keys in a record to be updated
either actual records containing valid data must not be altered. The modified record
or dummy records. A dummy record is must always overwrite the updated record in
identified by the constant (8)'1'B in its the data set.
first byte. Dummy records can be inserted
by the programmer, or can be created by Additionally, records can be effectively
deleting records. They can be replaced by deleted from the data set; a DELETE
valid data records having the same keys as statement marks a record as a dummy by
the dummy records. The sUbparameter putting (8)'1'B in the first byte. The
OPTCD=L must be included in the DD DELETE statement should not be used to
statement that defines the data set when it process a data set with F-format blocked
is created, so that dummy records are records and either KEYLOC=l or RKP=O, or V-
recognized and not retrieved by READ or VB-format records and either KEYLOC=l or
statements. RKP=4. (The code (8) 'l'B would overwrite
the first byte of the recorded key.) Note
that the EVENT option is not supported for
SEQUENTIAL access of INDEXED data sets.
CREATING A DATA SET
During sequential access of an INDEXED
data set, i t is possible to read a
When an INDEXED data set is being created, particular record by supplying a source key
the associated file must be opened for in the KEY option of a READ. statement, and
SEQUENTIAL OUTPUT, and the records must be to continue sequential reading from that
presented in the order of ascending key pOint in the data set. (The associated
values. (If ther~ is an error in the key file must have the KEYED attribute.) Thus,
sequence, the KEY condition will be a READ statement that includes the KEY
raised.) A DIRECT file cannot be used for option will cause the record, whose key is
the creation of an INDEXED data set. supplied, to be read; a subsequent READ
statement without the KEY option will cause
Once an INDEXED data set has been the record with the next higher recorded
created, the file that accesses i t can be key to be read (even if the keyed record
opened for SEQUENTIAL INPUT or UPDATE, or has not been found).
for DIRECT INPUT or UPDATE. In the case of
F-format records, it can also be opened for The effect of supplying a source key
OUTPUT to add records at the end of the that is shorter than the recorded keys in
data set. The keys for these records must the data set differs according to whether
have higher values than the existing keys or not the GENKEY option is specified in
for that data set and must be in ascending the ENVIRONMENT attribute. In the absence
order. The storage allocated for a data of the GENKEY option, the source key is
set can be increased when it is required padded on the right with blanks to the
for output. length specified in the KEYLENGTB option of
the ENVIRONMENT attribute, and the record
with this padded key is read (if such a
record exists). If the GENKEY option is
SEQUENTIAL ACCESS specified, the source key is interpreted as
a generic key, and the first record with a
key in the class identified by this generic
A SEQUENTIAL file that is used to access an key is read. (Refer to -Key
INDEXED data set may be opened with either Classification,- above.)
the INPUT or the UPDATE attribute. The
data transmission statements need not
include source keys, nor need the file have
the KEYED attribute. Sequential access is DIRECT ACCESS
in order of ascending recorded-key values;
records are retrieved in this order, and
not necessarily in the order in which they A DIRECT file that is used to access an
were added to the data set. Dummy records INDEXED data set may be opened with either
are not retrieved if the DO statement that the INPUT or the UPDATE attribute. All
defined the data set included the data transmission statements must include

Chapter 12: Record-oriented Transmission 183

source keys; the DIRECT attribute implies identified by a region number, and each of
the KEYED attribute. which may contain one record or more than
one record, depending on the type of
A DIRECT UPDATE file can be used to REGIONAL organization. The regions are
retrieve, add, delete, or replace records numbered in succession, beginning with
in an INDEXED data set according to the zero, and a record may be accessed by
following conventions: specifying its region number, and perhaps a
key, in a data transmission statement.
1. Retrieval: If the DD statement that
defined the data set included the REGIONAL organization of a data set
subparameter OPTCD=L, dummy records permits the programmer to control the
are not made available by a READ physical placement of records in the data
statement. (The KEY condition is set, and enables him to optimize the access
raised. ) time for a particular application. Such
optimization is not available with
2. Addition: A WRITE statement that CONSECUTIVE or INDEXED organization, in
includes a unique key causes a record which successive records are written either
to be inserted into the data set. If in strict phySical sequence or in logical
the key is the same as the recorded sequence depending on ascending key values;
key of a dummy record, the new record neither of these methods takes full
replaces the dummy record. If the key advantage of the characteristics of direct-
is the same as the recorded key of a access storage devices. REGIONAL data sets
record that is not marked as deleted, are confined to direct-access devices.
or if there is no space in the data
set for the record, the KEY condition A REGIONAL data set can be created in a
is raised. similar manner to a CONSECUTIVE or INDEXED
data set, records being presented in the
3. Deletion: The record specified by the order of ascending region numbers;
source.key in a DELETE statement is alternatively, direct access can be used,
retrieved, marked as deleted, and in which records can be presented in random
rewritten into the data set. The sequence and inserted directly into
effect of the DELETE statement is to preformatted regions. Once a REGIONAL data
insert the value (8) 'l'B in the first set has been created, it can be accessed by
byte of the data in a record. a file with the attributes SEQUENTIAL or
Deletion is possible only if OPTCD=L DIRECT as well as INPUT or UPDATE. Note
was specified in the DD statement that that neither a region number nor a key need
defined the data set when it was be specified if the data set is associated
created. If the data set has F-format with a SEQUENTIAL INPUT or SEQUENTIAL
blocked records with RKP=O or UPDATE file. When the file has the DIRECT
KEYLOC=l, or V-format records with attribute, records can be retrieved, added,
RKP=4 or KEYLOC=l, records cannot be deleted, and replaced at random.
deleted. (The code (8)'1'B would
overwrite the embedded keys.) Records within a REGIONAL data set are
either actual records containing valid data
4. Replacement: The record specified by a or dummy records. The nature of the dummy
source key in a REWRITE statement 1S records depends on the type of REGIONAL
replaced by the new record. If the organization; the three types of REGIONAL
data set contains F-format blocked organization are described below.
records, a record replaced with a
REWRITE statement causes an implicit Figure 12.11 lists the data transmission
READ statement to be executed unless statements and options that can be used to
the.previous I/O statement was a READ create and access a REGIONAL data set.
statement that obtained the record to
be replaced. If the data set contains
V-format records and the updated
record has a length different from KEYS
that of the record read, the whole of
the remainder of the track will be
moved, and may cause data to be moved There are two kinds of keys, recorded keys
to an overflow track. and source keys. A recorded key is a
character string that immediately precedes
each record in the data set to identify
that record; its length cannot exceed 255
Regional Organization characters. A source key is the character-
string value of the expression that appears
in the KEY or KEYFROM option of a data
A data set with REGIONAL organization is transmission statement to identify the
divided into regions, each of which is record to Which the statement refers. When

184 OS PL/I CRT AND OPT LRM PART I

a record in a REGIONAL data set is REGIONAL(l) ORGANIZATION
accessed, the source key gives a region
number, and may also give a recorded key.
In a REGIONAL(l) data set, since there are
The length of the recorded keys in a no recorded keys, the region number serves
REGIONAL data set is defined by the as the sole identification of a particular
KEYLENGTB option of the ENVIRONMENT record. The character-string value of the
attribute, or the KEYLEN subparameter on source key should represent an unsigned
the DD statement. Unlike the keys for decimal integer that should not exceed
INDEXED data sets, recorded keys in a 16777215. If the region number exceeds
REGIONAL data set are never embedded within this figure, it is treated as modulo
the record. 16771216: 16717226, for instance, is
treated as 10. Only the characters 0
through 9 and the blank character are valid
in the source key; leading blanks are
interpreted as zeros; embedded blanks are
not permitted in the number; the first
embedded blank, if any, will terminate the
region number. I f more than eight
characters appear in the source key, only
the rightmost eight are used as the region
TYPES OF REGIONAL ORGANIZATION number; if there are fewer than eight
characters, blanks (interpreted as zeros)
are assumed on the left.
There are three types of REGIONAL
organization:
1. A REGIONAL(l) data set contains F-
format records that do not have
recorded keys. Each region in the Dummy Records
data set contains only one record;
therefore, each region number
corresponds with a relative record Records in a REGIONAL(l) data set are
position within the data set. either actual records containing valid data
or dummy records. A dummy record in a
2. ~ REGIONAL(2) data set contains F- REGIONAL (1) data set is identified by the
format records that have recorded constant (8)'1'B in its first byte.
keys. Each region in the data set Although such dummy records are
contains only one record. Direct automatically inserted in the data set
access to a REGIONAL(2) data set either when it is created or when a record
employs the region number specified in is deleted, they are not ignored when the
a source key to locate the required data set is read~ the PL/I program must be
region. REGIONAL (2) differs from prepared to recognize them. Dummy records
REGIONAL(l) in that records are not can be replaced by valid data. Note that
necessarily in the specified regions. if the programmer inserts (8)'1'B in the
The specified region identifies a first byte, the record will be lost if the
starting-point; a search is then made file is copied onto a data set whose dummy
for a record with the given recorded records are not retreived.
key starting at the beginning of the
track containing the region specified.
3. A REGIONAL(3) data set contains F- Creating a REGIONAL(l) Data Set
format, V-format, VS-format or U-
format records with recorded keys.
Each region in the data set A REGIONAL(1) data set can be created
corresponds with a track on a direct- either sequentially or by direct access.
access device, and can normally
contain one or more records. Direct When a SEQUENTIAL OUTPUT file is used to
access of a REGIONAL(3) data set create the data set, the opening of the
employs the region number specified in file causes all tracks on the data set to
a source key to locate the required be cleared, and a capacity record to be
region. Once the region has been written at the beginning of each track to
located, a sequential search for space record the amoant of space available on
to add a record~ or for a record that that track. Records must be presented in
has a recorded key identical with that ascending order of region numbers; any
supplied in the source key, can be region that is omitted from the sequence is
made. VS-format records may span more filled with a dummy record. If there is an
than one region. error in the sequence, or if a duplicate

Chapter 12: Record-oriented Transmission 185

r---------------------------------------------------------------------------------------,
File declaration 1Valid statements, with options that must
1 lother options that can 1
'appear lalso be used I
SEQUENTIAL OUTPUTIWRITE FILE (file-expr) FROM (variable)
BUFFERED 1 KEYFROM(expression):
,LOCATE variable FILE(file-expr)
,II SET (pointer-variable)
, KEYFROM(expression): 1
SEQUENTIAL OUTPUTIWRITE FILE(file-expr) FROM(variable) I
UNBUFFERED 1 KEYFROM(expression) : 1EVENT (event-variable)
SEQUENTIAL INPUT I READ FILE (file-expr) INTO (variable): IKEYTO
BUFFERED 1 I (character-string-
I , variable)
1READ FILE(file-expr) SET(pointer-variable):IKEYTO
,
1
I READ FILE (file-expr) IGNORE(expression):
I (character-string-
I variable)
1
SEQUENTIAL INPUT IREAD FILE(file-expr) INTO(variable): 1EVENT (event-variable)
UNBUFFERED I 1and/ or KEYTO
I I (character-string-
1 I variable)
'READ FILE (file-expr) IGNORE(expression): 1EVENT (event-variafile)

SEQUENTIAL UPDATEIREAD FILE(file-expr) INTO(variable). 'KEYTO

BUFFERED 1 1(character-string-
, I variable)
IREAD FILE(file-expr) SET(pointer-variable):IKEYTO
, I (character-string-
I , variable)
IREAD FILE(file-expr) IGNORE(expression). I
I I
,REWRITE FILE(file-expr): I FROM (variable)

SEQUENTIAL UPDATEIREAD FILE(file-expr) INTO(variable); IEVENT (event-variable)

UNBUFFERED , ,
, ,and/or KEYTO
1 , (character-string-
I I variable)
IREAD FILE(file-expr) IGNORE(expression): IEVENT(event-variable)
i l l
, IREWRITE FILE(file-expr) FROM(variable); ,EVENT(event-variable)
1---------------------------------------------------------------------------------------
IDIRECT OUTPUT IWRITE FILE(file-expr) FROM (variable) 'EVENT (event-variable)
I , KEYFROM(expression): 1
1---------------------------------------------------------------------------------------
IDIRECT INPUT IREAD FILE(file-expr) INTO(variable) 1EVENT (event-variable)
, 1 KEY(expression). 1
1---------------------------------------------------------------------------------------
IDIRECT UPDATE IREAD FILE(file-expr) INTO (variable) I EVENT (event-variable)
I I KEY (expression) : I
1 I ,
1 IREWRITE FILE(file-expr) FROM(variable) I EVENT (event-variable)
, , KEY(expression): ,
I 1 ,
1 ,WRITE FILE(file-expr) FROM(variable) ,EVENT(event-variable)
1 , KEYFROM(expression): I
", IDELETE FILE(file-expr) KEY(expression); ,
IEVENT(event-variable)
L---------------------------------------------------------------------------------------J
Figure 12.11 (Part 1 of 2). Statements and options permitted for creating and
accessing REGIONAL data sets

186 OS PL/I CRT AND OPT LRM PART I

r---------------------------------------------------------------------------------------,
IFile deciaration 1 1Valid statements, with options that must I Other options that can
I I appear lalso be used
1---------------------------------------------------------------------------------------
IDIRECT INPUT IREAD FILE(file-expr) INTO(variable) I EVENT (event-variable)
I EXCLUSIVE I KEY(expression); land/or NOLOCK
1---------------------------------------------------------------------------------------
IDIRECT UPDATE READ FILE(file-expr) INTO (variable) IEVENT(event-variable)
EXCLUSIVE KEY(expression)i land/or NOLOCK
I
REWRITE FILE(file-expr) FROM(variable) I EVENT (event-variable)
KEY(expression); I
I
WRITE FILE(file-expr) FROM (variable) I EVENT (event-variable)
KEYFROM(expression): I
I
DELETE FILE(file-expr) KEY(expression); I EVENT (event-variable)
I
UNLOCK FILE(file-expr) KEY(expression)i I
1The complete file declaration would include the attributes FILE, RECORD, and
ENVIRONMENT: if any of the options KEY, KEYFROM, and KEYTO is used, it must also
include the attribute KEYED.
IThe statement: READ FILE (file-expression): is equivalent to the statement:
I READ FILE (file-expression) IGNORE(l):
L---------------------------------------------------------------------------------------J
Figure 12.11 (Part 2 of 2). statements and options permitted for creating and
accessing REGIONAL data sets.

key is presented, the KEY condition will be string variable specified in the KEYTO
raised. When the file is closed, any space option has more than eight characters, the
remaining at the end of the current extent value returned (the region number) is
is filled with dummy records. padded on the left with blanks: if it has
fewer than eight characters, it is
If a data set is created using a truncated on the left.
buffered file, and the last WRITE or LOCATE
statement before the file is closed sequential access is in the order of
attempts to transmit a record beyond the ascending region numbers. All records are
limits of the data set, the CLOSE statement retrieved, whether dummy or actual, and the
may raise the ERROR condition. PL/I program should be prepared to
recognize dummy records.
If a DIRECT OUTPUT file is used to
create the data set, the whole of the The rules governing the relationship
primary extent allocated to the data set is between READ and REWRITE statements for a
filled with dummy records when the file is SEQUENTIAL UPDATE file that accesses a
opened. REGIONAL (1) data set are identical to those
for a CONSECUTIVE data set (described
Once a REGIONAL(l) data set has been above).
created, the file that accesses it can be
opened for SEQUENTIAL INPUT or UPDATE, or
for DIRECT INPUT or UPDATE. It can be
opened for OUTPUT only if the existing data
set is to be overwritten. Direct Access

A DIRECT file that is used to process a

Sequential Access REGIONAL (1) data set may be opened with
either the INPUT, or the UPDATE attribute.
All data transmission statements must
A SEQUENTIAL file that is used to process a include source keys; the DIRECT attribute
REGIONAL (1) data set may be opened with implies the KEYED attribute.
either the INPUT or UPDATE attribute. The
data transmission statements must not A DIRECT UPDATE file can be used to
include the KEY option: but the file may retrieve, add, delete, or replace records
have the KEYED attribute, since the KEYTO in a REGIONAL(l) data set according to the
option can be used. If the character- following conventions:

Chapter 12: Record-oriented Transmission 181

 1. Retrieval: All records, whether dummy does not exceed 16777215. If the region
or actual, are retrieved. The program number exceeds this figure, it is treated
must be prepared to recognize dummy as modulo 16777216: 16777226 is treated as
records. 10. The region specification can include
only the characters 0 through 9 and the
2. Addition: A WRITE statement blank character: leading blanks are
substitutes a new record for the interpreted as zeros: embedded blanks are
existing record (actual or dummy) in not permitted in the number; the first
the region specified by the source embedded blank, if any, will terminate the
key. region number. The comparison key is a
character string which occupies the left
3. Deletion: The record specified by the hand side of the source key, and may
source key in a DELETE statement is overlap or be distinct from the region
converted to a dummy record. number, from which it can be separated by
other, non-significant, characters. The
4. Replacement: The record specified by length of the comparison key is specified
the source key in a REWRITE statement, by either the KEYLEN subparameter of the DD
whether dummy or actual, is replaced. statement for the data set or the KEYLENGTH
option of the ENVIRONMENT attribute. If
the source key is shorter than the
specified key length, it is extended on the
REGIONAL(2) ORGANIZATION right with blanks. To retrieve a record,
the comparison key must exactly match the
recorded key of the record. The comparison
In a REGIONAL(2) data set, each record is key can include the region number, in which
identified by a recorded key that case the source key and the comparison key
immediately precedes the record. The are identical; alternatively, part of the
actual position of a record in the data set source key may not be used. The length of
relative to other records is determined not the comparison key is always equal to
by its recorded key, but by the region KEY LENGTH or KEYLEN; if the source key is
number that is supplied in the source key longer then KEYLEN+8, the characters in the
of the WRITE statement that adds the record source key between the comparison key and
to the data set. the region number are ignored.

When a record is added to the data set Consider the following examples of
by direct access, it is written with its source keys (the character "b W represents a
recorded key in the first available space blank):
after the beginning of the track that
contains the region specified. When a KEY ('JOHNbDOEbbbbbb12363251')
record is read by direct access, the search
for a record with the appropriate recorded The rightmost eight characters make up the
key begins at the start of the track that region specification, the relative number
contains the region specified. Unless it of the record. Assume that the associated
is limited by the LIMCT subparameter of the DO statement has the subparameter
DO statement that defines the data set, the KEYLEN=14. In retrieving a record, the
search for a record or for space to add a search will begin with the beginning of the
record continues right through to the end track which contains the region number
of the data set and then from the beginning 12363251, until the record is found having
until the whole of the data set has been the recorded key of JOHNbDOEbbbbbb.
covered. The closer a record is to the
specified region, the more quickly it can If the subparameter were KEYLEN=22, the
be accessed. search still would begin at the same place,
but SinCE the comparison and the source key
are the same length, the search would be
for a record having the recorded key
Source Keys 'JOHNbDOEbbbbbb12363251'.

KEY C'JOHNbDOEbbbbbbDIVISIONb423bbbb34627')
The character-string value of the source
key can be thought of as having two logical In this example, the rightmost eight
parts, the region number and a comparison characters contain leading blanks, which
key. On output, the comparison key is are interpreted as zeros. The search will
written as the recorded key: for input, it begin at region number 00034627. If
is compared with the recorded key. KEYLEN=14 is specified, the characters
DIVISIONb423b will be ignored.
The rightmost eight characters of the
source key make up the region number, which Assume that COUNTER is declared FIXED
must be an unsigned decimal integer that BINARY (21) and NAME is declared

188 OS PL/I CKT AND OPT LRM PART I

CHARACTER(15). The key might be specified buffered file, and the last WRITE or LOCATE
as : statement before the file is closed
attempts to transmdt a record beyond the
KEY (NAME II COUNTER) limits of the data set, the CLOSE statement
may raise the ERROR condition.
The value of COUNTER will be converted to a
character string of eleven characters. If a DIRECT OUTPUT file is used to
(The rules for conversion specify that a create the current extent of a data set,
binary value of this length, when converted the whole of the primary extent allocated
to character, will result in a string of to the data set is filled with dummy
length 11, three blanks followed by eight records when the file is opened. Records
decimal digits.) The value of the can be presented in random order, and no
rightmost eight characters of the converted condition is raised by duplicate keys.
string will be taken to be the region Each record is substituted for the first
specification. Then if the keylength dummy record on the track that contains the
specification is KEYLEN=15, the value of region specified in the source key; if
NAME will be taken to be the comparison there are no dummy records on the track,
specification. the record is substituted for the first
dummy record encountered on a subsequent
tracK, unless the LIMCT subparameter
specifies that the search cannot reach
Dummy Records beyond this track. (Note that it is
possible to place records with identical
recorded keys in the data set.)
A REGIONAL(2) data set can contain dummy
records. A dummy record consists of a Once a REGIONAL(2) data set has been
dummy key and dummy data. A dummy key is created, the file that accesses it can be
identified by the constant (8) 'l'B in its opened for SEQUENTIAL INPUT or UPDATE, or
first byte. The first byte of the data for DIRECT INPUT or UPDATE. It cannot be
contains the sequence number of the record opened for OUTPUT.
on the track.

Dummy records can be replaced by valid

data. They are inserted automatically sequential Access
either when the data set is created or when
a record is deleted, and they are ignored
when the data set is read. (Unlike INDEXED A SEQUENTIAL file that is used to process a
data sets, REGIONAL data sets do not REGIONAL (2) data set may be opened with
require the subparameter OPTCD=L in the DO either the INPUT or the UPDATE attribute.
statement. ) The data transmission statements must not
include the KEY option, but the file may
have the KEYED attribute since the KEYTO
option can be used. The KEYTO option
creatinq a Data set specifies that the recorded key only is ~o
be aSSigned to the specified variable. If
the character-string variable specified in
A REGIONAL(2) data set can be created the KEYTO option has more characters than
either sequentially or by direct access. are specified in the KEYLEN subparameter,
In either case, when the file associated the value returned (the recorded key) is
with the data set is opened, the data set extended on the right with blanks; if it
is initialized with capacity records has fewer characters than specified by
specifying the amount of space available On KEYLEN, the value returned is truncated on
each track. the right.

When a SEQUENTIAL OUTPUT file is used to sequential access is in the physical

create the data set, records must be order in which the records exist on the
presented in ascending order of region data set, not necessarily in the order in
numbers; any region that is omitted from which they were added to the data set. The
the sequence is filled with a dummy record. recorded keys do not affect the order of
If there is an error in the sequence, sequential access. Dummy records are not
including an attempt to place more than one retrieved.
record in the same region, the KEY
condition will be raised. ~hen the file is The rules governing the relationship
closed, any space remaining at the end of between READ and REWRITE statements for a
the current extent is filled with dummy SEQUENTIAL UPDATE file that accesses a
records. REGIONAL(2) data set are identical with
those for a CONSECUTIVE data set (described
If a data set is created using a above) •

Chapter 12: Record-oriented Transmission 189

Direct Access format, VS-format, or U-format
records. Dummy records can be
created, but a data set that has V-
A DIRECT file that is used to process a format, VS-format, or U-format records
REGIONAL(2) data set may be opened with is not preformatted with dummy records
either the INPUT or the UPDATE attribute. because the lengths of records cannot
All data transmission statements must be known until they are written;
include source keys; the DIRECT attribute however, all tracks in the primary
implies the KEYED attribute. The search extent are cleared and the operating
for each record is commenced at the start system maintains a capacity record at
of the track containing the region number the beginning of each track, in which
indicated by the key. it records the amount of space
available on that track.
1. Retrieval: Dummy records are not made
available by a READ statement. The Source keys for a REGIONAL(3) data set
KEY condition is raised if a record are interpreted exactly as those for a
with the specified recorded key is not REGIONAL (2) data set, and the search for a
found. record or space to add a record is
conducted in a similar manner.
2. Addition: A WRITE statement
substitutes the new record for the
first dummy record on the track
containing the region specified by the Dummy Records
source key. If there are nO dummy
records on this track, and an extended
search is permitted by the LIMCT Dummy records for REGIONAL(3) data sets
subparameter, the new record replaces with F-format records are identical with
the first dummy record encountered those for REGIONAL(2) data sets.
during the search.
V-format, VS-format, and U-format dummy
3. Deletion: The record specified by the records are identified by the fact that
source key in a DELETE statement is they have dummy recorded keys «8)'l'B in
converted to a dummy record. the first byte). The four control bytes in
each V-format and VS-format dummy record
4. Replacement: The record specified by are retained, but otherwise the contents of
the source key in a REWRITE statement V-format, VS-format, and U-format dummy
must exist; a REWRITE statement cannot records are undefined. V-format, VS-
be used to replace a dummy record. If format, and U-format format records are
it does not exist, the KEY condition converted to dummy records only when a
is raised. record is deleted; they cannot be
reconverted to valid records.
Note that if a track contains records
with duplicate recorded keys, the record
farthest from the beginning of the track
will never be retrieved during direct Creating a Data Set
access.

A REGIONAL(3) data set can be created

either sequentially or by direct access.
REGIONAL(3) ORGANIZATION In either case, when the file associated
with the data set is opened, the data set
is initialized with capacity records
A REGIONAL(3) data set differs from a specifying the amount of space available on
REGIONAL(2) data set (described above) only each track.
in the following respects:
When a SEQUENTIAL OUTPUT file is used to
1. Each region number identifies a track create the data set, records must be
on the direct-access device that presented in ascending order of region
contains the data set; the region numbers, but the same region number can be
number should not exceed 32767. A specified for successive records. If there
region in excess of 32767 is treated is an error in the sequence, the KEY
modulo 32768; 32778 is treated as 10. condition will be raised. If a track
becomes filled by records for which the
2. A region can contain one or more same region number was specified, the
records, or a segment of a VS-format region number is automatically incremented
record. by one; an attempt to add a further record
with the same region number will raise the
3. The data set can contain F-format, V- KEY condition (sequence error).

190 OS PUI CKT AND OPT LRM PART I

 If a data set is created using a sequential access is in the order of
buffered file, and the last WRITE or LOCATE ascending relative tracks. Records are
statement before the file is closed retrieved in this order, and not
attempts to transmit a record beyond the necessarily in the order in which they were
limits of the data set, the CLOSE statement added to the data set; the recorded keys do
may raise the ERROR condition. not affect the order of sequential access.
Dummy records are not retrieved.
If a DIRECT OUTPUT file is'used to
create the data set, the whole of the The rules governing the relationship
primary extent allocated to the data set is between READ and REWRITE statements for a
initialized when the data set is opened; SEQUENTIAL UPDATE file that accesses a
for F-format records, the space is filled REGIONAL(3) data set are identical with
with dummy records, and for V-format, VS- those for a CONSECUTIVE data set (described
format, and U-format records, the capacity above) •
record for each track is written to
indicate empty tracks. Records can be
presented in random order, and no condition
is raised by duplicate keys or duplicate Direct Access
region specifications. If the data set has
F-format records, each record is
substituted for the first dummy record in A DIRECT file that is used to process a
the region (track) specified in the source REGIONAL (3) data set may be opened with
key; if there are no dummy records on the either the INPUT or the UPDATE attribute.
track, and an extended search is permitted All data transmission statements must
by the LIMCT subparameter, the record is include source keys; the DIRECT attribute
substituted for the first dummy record implies the KEYED attribute.
encountered during the search. If the data
set has V-format, VS-format, or U-format 1. Retrieval: Dummy records are not made
records, the new record is inserted on the available by a READ statement. The
specified track, if sufficient space is KEY condition is raised if a record
available; otherwise, if an extended search with the specified recorded key is not
is permitted, the new record is inserted in found.
the next available space.
2. Addition: In a data set with F-format
Note that for spanned records space may records, a WRITE statement substitutes
be required for overflow onto subsequent the new record for a dummy record in
tracks. the region (track) specified by the
source key. If there are no dummy
Once a REGIONAL(3) data set has been records on the specified track, and an
created, the file that accesses it can be extended search is permitted by the
opened for SEQUENTIAL INPUT or UPDATE, or LIMCT subparameter, the new record
for DIRECT INPUT or UPDATE. It can only be replaces the first dummy record
opened for OUTPUT if the entire existing encountered during the search. If the
data set is to be deleted and replaced. data set has V-format, VS-format., or
U-format records, a WRITE statement
inserts the new record after any
records already present on the
specified track if space is available;
Sequential Access otherwise, if an extended search is
permitted, the new record is inserted
in the next available space.
A SEQUENTIAL file that is used to access a
UGIONAL(3) data set may be opened with 3. Deletion: A record specified by the
either the INPUT or UPDATE attribute. The source key in a DELETE statement is
data transmission statements must not converted to a dummy record. The
iBclude the KEY option, but the file may space formerly occupied by an F-format
have the KEYED attribute since the KEYTO record can be re-used; space formerly
option can be used. The KEYTO option occupied by V-format, VS-format, or U-
specifies that the recorded key only is to format records is not available for
De assigned to the specified variable. If re-use.
the character-string variable specified in
the KEYTO option has more characters than 4. Replacement: The record specified by
are specified in the KEYLEN subparameter, the source key in a REWRITE statement
the value returned (the recorded key) is must exist; a REWRITE statement cannot
extended on the right with blanks; if it be used to replace a dummy record.
has fewer characters than specified by When a VS-format record is replaced,
KEYLEN, the value returned is truncated on the new one must not be shorter than
the right. the old.

Chapter 12: Record-oriented Transmission 191

 Note: If a track contains records with For entry-sequenced data sets, the key is
duplicate recorded keys, the record the relative byte address (RBA) of the
farthest from the beginning of the record. For relative-record data sets, the
track will never be retrieved during key is a relative record number.
direct access.

Keys for Indexed VSAM Data Sets

IVSAM Organization
I
I Keys for key-sequenced data sets and for
There are three types of VSAM data set, entry-sequenced data sets accessed via an
key-sequenced data sets (KSDS), entry- alternate index are part of the logical
sequenced data sets (ESDS), and relative- records recorded on the data set. The
record data sets (RRDS). They are all length and location of the keys are defined
ordered, and they can all have keys when the data set is created. The KEYLOC
associated with their records. Both and KEYLEN options may be included, for
sequential and keyed access are therefore checking purposes, in the ENVIRONMENT
possible with all three types. attribute when the file is declared. If,
when the file is opened, these values
Indexes are mandatory only for key- conflict with those defined for the
sequenced data sets; these indexes being dataset/index combination, the
known as the prime indexes. It is, UNDEFINEDFILE condition is raised.
however, possible to define, over a KSDS or
an ESDS, one or more alternate indexes. An The ways in which the keys may be
alternate index is unique if it does not referenced in the KEY, KEYFROM, and KEYTO
contain duplicate keys, and non-unique if options are as described under "KEY Option"
it does. (A prime index can never have and "KEYFROM and KEYTO Options" earlier in
duplicate keys.) this chapter.
Any change in a data set that has
alternate indexes must be reflected in all
the indexes if they are to remain useful. Relative Byte Addresses (RBA)
IThis activity is known as index upgrade,
land is automatic for any index in the index
lupgrade set of the data set. (For a KSDS, Relative byte addresses allow the
Ithe prime index is always a member of the programmer to use keyed access on an ESOS
lindex upgrade set.) The programmer, associated with a KEYED SEQUENTIAL file.
I however, must avoid making changes in the The RBAs, or keys, are character strings of
Idata set that would cause duplicate keys in length 4, and their values are defined by
Ithe prime index or in a unique alternate VSAM. RBAs cannot be constructed or
I index. manipulated in PL/I; their values, however,
I can be compared in order to determine the
I VSAM data sets are defined to the system relative positions of records within the
by means of the Access Method Services data set. RBAs are not normally printable.
utility program (see the Programmer's Guide
for the compiler). The definition The RBA for a record can be obtained by
completely defines the type of the data Imeans of the KEYTO option, either on a
set, its structure, and the space it IWRITE statement when the data set is being
requires. If the data set is indexed, its Iloaded or extended, or on a READ statement
indexes (together with their key lengths Iwhen the data set is being read. An RBA
and locations) and the index upgrade set lobtained in either of these ways can
are also defined. A VSAM data set is thus Isubsequently be used in the KEY option of a
-created- by Access Method services; the IREAD or REWRITE statement.
operation of writing the initial data into I
a newly-created VSAM data set is referred I An RBA must not be used in the KEYFROM
Ito as loading in this publication. loption of a WRITE statement.
I I
I I
I I
IKEYS FOR VSAM DATA SETS IRelative Record Numbers
I I
I I
IAlI VSAM data sets can have keys associated IRecords in an RRDS are identified by a
Iwith their records. For key-sequenced data Irelative record number that starts at 1 and
Isets, and for entry-sequenced data sets lis incremented by 1 for each succeeding
laccessed via an alternate index, the key is I record. These relative records numbers may
la defined field within the logical record. Ibe used as keys to allow keyed access to

192 OS PL/I CRT AND OPT LRM PART I

the data set. Iprevious READ. A REWRITE statement must
Inot attempt to change the length of the
Keys used as relative record numbers are Irecord that is being replaced.
character strings of length 8. The I
character string value of a source key used I The DELETE statement is not allowed for
in the KEY or KEYFROM option must represent lentry-sequenced data sets.
an unsigned decimal integer constant. If I
the sourcekey is not 8 characters long, it I
is truncated or padded with blanks I
(interpreted as zeros) on the left. The I
va1ue returned by the KEYTO option is a KEY-SEQUENCED DATA SETS
character string of length 8, with leading
zeros suppressed.
The statements and options permitted for
indexed VSAM data sets are shown in figure
12.13. An indexed data set may be a KSDS
ENTRY-SEQUENCED DATA SETS with its prime index, or either a KSDS or
an ESDS with an alternate index. Except
where stated, the following description
The statements and options allowed for applies to all indexed VSAM data sets.
files associated with an ESDS are shown in
figure 12.12.
Loading a KSDS
Loading an ESDS
When a KSDS is being loaded, the associated
file must be opened for KEYED SEQUENTIAL
When an ESDS is being loaded, the OUTPUT. The records must be presented in
associated file must be opened for ascending key order, and the KEYFROM option
SEQUENTIAL OUTPUT. The records are must be used. Note that the prime index
retained in the order in which they are must be used for loading the data set; nO
presented. VSAM data set can be loaded via an
alternate index.
The KEYTO option may be used to recover
the relative byte address of each record as If a KSDS already contains some records,
it is written. The keys thus obtained may and the associated file is opened with the
subsequently be used to achieve keyed SEQUENTIAL and OUTPUT attributes, records
access to the data set. may only be added at the end of the data
set. The rules given in the previous
paragraph apply; in particular, the first
record presented must have a key greater
sequential Access than the highest key present on the data
set.
A SEQUENTIAL file that is used to access an
ESDS may be opened with either the INPUT or
the UPDATE attribute. If either of the Sequential Access
options KEY or KEYTO is used, the file must
also have the KEYED attribute.
A SEQUENTIAL file that is used to access a
Sequential access is in the order in KSDS may be opened with either the INPUT or
which the records were originally loaded the UPDATE attribute.
into the data set. The KEYTO option may be
used on the READ statements to recover the For READ statements without the KEY
RBAs of the records that are read. If the option, the records are recovered in
KEY option is used, the record that is ascending key order (or in descending key
recovered is the one with the specified order if the BKWD option is used). The key
RBA. subsequent sequential access of a record recovered in this way can be
continues from the new position in the data obtained by means of the KEYTO option.
set.
If the KEY option is used, the record
For an UPDATE file, the WRITE statement recovered by a READ statement is the One
causes a new record to be added at the end with the specified key. Such a READ
of the data set. With a REWRITE statement, statement positions the data set at the
the record rewritten is the one with the specified record; subsequent sequential
specified RBA if the KEY option is used; treads will recover the following records in
otherwise it is the record accessed on the lsequence.

Chapter 12: Record-oriented Transmission 193

 WRITE statements with the KEYFROM option at specific points in the data set (mass
are allowed for KEYED SEQUENTIAL UPDATE sequential insert), the SKIP option should
files. Insertions can be made anywhere in be omitted.
the data set, irrespective of the position
of any previous access. If the data set is It is never an error to specify (or
being accessed via a unique index, the KEY omit) the SKIP option: its effect on
condition is raised if an attempt is made performance is significant only in the
to insert a record with the same key as a circumstances described.
record that already exists on the data set.
For a non-unique index, subsequent
retrieval of records with the same key is
in the order in which they were added to Use of the SIS option
the data set.
REWRITE statements with or without the The SIS option is applicable to key-
KEY option are allowed for UPDATE files. sequenced data sets accessed by means of a
If the KEY option is used, the record that DIRECT file.
is rewritten is the first record with the
specified key; otherwise it is the record If mass sequential insert is used for a
that was accessed by the previous READ IVSAM data set, that is, if records with
statement. When a record is rewritten lascending keys are inserted, a KEYED
using an alternate index, the prime key of ISEQUENTIAL UPDATE file is normally
the record must not be changed. I appropriate. In this case, however, VSAM
Idelays writing the records to the data set
I until a complete control interval h'as been
I built. If DIRECT is specified, VSAM writes
Direct Access leach record as soon as it is presented.
I Thus, in order to achieve immediate writing
land efficient use of disk space, a DIRECT
A DIRECT file that is used to access an file should be used and the SIS option
indexed VSAM data set may be opened with should be specified.
the INPUT, OUTPUT, or UPDATE attribute. A
DIRECT file must not be used to access the The SIS option is intended primarily for
data set via a non-unique index. use in online applications.
If a DIRECT OUTPUT file is used to add
records to the data set, the KEY condition
is raised if an attempt is made to insert a SAMEKEY Built-In Function
record with the same key as a record that
already exists.
If a VSAM data set is being accessed via a
If a DIRECT INPUT or DIRECT UPDATE file non-unique alternate index, the presence of
is used, records may be read, written, duplicate keys can be detected by means of
rewritten, or deleted in the same way as the SAMEKEY built-in function. This
for a KEYED SEQUENTIAL file. function returns 'l'B if the input/output
statement has completed sucessfully and the
accessed record is followed by another with
the same key: otherwise it returns 'O'B.
Use of the SKIP option

IThe SKIP option of the ENVIRONMENT

lattribute specifies that the VSAM OPT CD
'·SKp· is to be used wherever possible. It
lis applicable to key-sequenced data sets RELATIVE RECORD DATA SETS
laccessed by means of a SEQUENTIAL file.
I
I If the application program is designed The statements and options permitted for
Ito access individual records scattered VSAM relative record data sets (RRDS) are
Ithroughout the data set, but the access shown in figure 12.14.
Iwill be primarily in ascending key order,
Ithe SKIP option should be specified for the
Ifile.
I ILoading an RRDS
I If the program is designed to read large I
Inumbers of records sequentially, without I
Ithe use of the KEY option, or if it is IWhen a RRDS is being loaded, the associated
Idesigned to insert large numbers of records I file must be opened for OUTPUT. Ei ther a

194 OS PL/I CRT AND OPT LRM PART I

r---------------------------------------------------------------------------------------,
File declaration tValid statements, with options that must
1 lother options that can I
tappear lalso be used I
---------------------------------------------------------------------------------------1
SEQUENTIAL OUTPUTtWRITE FILE{file-expr) FROM(variable); IKEYTO(character-string- I
BUFFERED t I variable) I
I I 1
ILOCATE variable FILE(file-expr); I SET (pointer-variable)
SEQUENTIAL OUTPUTIWRITE FILE(file-expr) FROM(variable); I EVENT (event-variable)
UNBUFFERED ,
, land/or KEYTO(character-
I string-variable)
SEQUENTIAL INPUT IREAD FILE(file-expr) INTO(variable): IKEYTO(character-string-
I BUFFERED 1 I variable)
,
.1 ,
1
lor KEYCexpression)3
I .
IREAD FILE(file-expr) SET(pointer-variable); IKEYTO(character-string-
I
I 1 I variable)
I 1 lor KEYCexpression)3
1 1 I
t tREAD FILE(file-expr); IIGNORECexpression)
1---------------------------------------------------------------------------------------
ISEQUENTIAL INPUT IREAD FILE(file-expr) I EVENT (event-variable)
INTO(variabl~);
1UNBUFFERED t land/or either
1 I IKEY(expression)30r

I 't
1

1
I IKEYTO(character-string-
I
I
variable)
1 IREAD FILE(file-expr):2 I EVENT (event-variable)
I I land/or
I t I IGNORE (expression)
1---------------------------------------------------------------------------------------
ISEQUENTIAL UPDATEtREAD FILE(file-expr) INTO(variable); IKEYTO(character-string-
BUFFERED 1 I variable)
1 lor KEY(expression)3
1 I
tREAD FILE(file-expr) SET(pointer-variable); IKEYTOCcharacter-string-
, I variable)
1 lor KEY(expression)3
I I
IREAD FILE(file-expr);2 IIGNORECexpression)
I I
IWRITE FILE(file-expr) FROMCvariable): IKEYTOCcharacter-string-
1 I variable)
I I
IREWRITE FILE(file-expr); IFROM(variable) and/or
, I KEY (expression) 3
SEQUENTIAL UPDATEIREAD FILE(file-expr) INTOCvariable); 1EVENT (event-variable)
I UNBUFFERED
I
t , land/or either
IKEY(expression)30r
I
I ,,1 IKEYTO{character-string-
I variable)
1 I
I
t ,
tREAD FILE(file-expr);2 IEVENTCevent-variable)
land/or
,(continued)
L ,
_____________________________________________________ ----------------------------------J
I IGNORE Cexpression)

Figure 12.12 (Part 1 of 2). Statements and options permitted for loading and
accessing VSAM entry-sequenced data sets

Chapter 12: Record-oriented Transmission 195

r---------------------------------------------------------------------------------------,
File declaration 1 1valid statements, with options that must IOther options that can I
I appear lalso be used I
SEQUENTIAL UPDATEIWRITE FILE(file-expr) FROM(variable); I EVENT (event-variable)
UNBUFFERED I land/or
I IKEYTO(character-string-
I I variable)
I I
IREWRITE FILE(file-expr) FROM(variable); I EVENT (event-variable)
I land/or KEY(expression)3

1The complete file declaration would include the attributes FILE, RECORD, and
ENVIRONMENT; if either of the options KEY or KEYTO is used, it must
also include the attribute KEYED.

2The statement READ FILE (file-expression); is equivalent to the statement:

READ FILE(file-expression) IGNORE (1);

3The expression used in the KEY option must be a relative byte address obtained by
means of the KEYTO option.
L---------------------------------------______________ ----------------------------------J
Figure 12.12 (Part 2 of 2). Statements and options permitted for loading and
accessing VSAM entry-sequenced data sets

DIRECT or a SEQUENTIAL file may be used. loptions KEY, KEYTO, or KEYFROM is used, the
Ifile must also have the KEYED attribute.
For a DIRECT OUTPUT file, each record is I
placed in the position specified by the I For READ statements without the KEY
relative record number (or key) in the I option, the records are recovered in
KEYFROM option of the WRITE statement (see lascending relative record number order.
"Keys for VSAM Data sets" earlier in this IAny empty slots in the data set are skipped
chapter). lover.
I
For a SEQUENTIAL OUTPUT file, WRITE I If the KEY option is used, the record
statements with or without the KEYFROM Irecovered by a READ statement is the one
option may be used. If the KEYFROM option Iwith the specified relative record number.
is specified, the record is placed in the ISuch a READ statement positions the data
specified slot; if it is omitted, the ,set at the specified record; subsequent
record is placed in the slot following the Isequential reads will recover the following
current position. There is no requirement
for the records to be presented in
ascending relative record numbers. If the
,
Irecords in sequence.

, WRITE statements with or without the

KEYROM option is omitted, the relative IKEYFROM option are allowed for KEYED
record number of the written record can be ISEQUENTIAL UPDATE files. Insertions can be
obtained by means of the KEYTO option. Imade anywhere in the data set, irrespective
lof the position of any previous access.
If an RRDS is to be loaded sequentially, IFor WRITE with the KEYFROM option, the KEY
without use of the KEYFROM or KEYTO Icondition is raised if an attempt is made
options, the file is not required to have Ito insert a record with the same relative
the KEYED attribute. Irecord number as a record that already
lexists on the data set. If the KEYFROM
It is an error to attempt to load a loption is omitted, an attempt is made to
record into a position that already Iwrite the record in the next slot, relative
contains a record: if the KEYFROM option Ito the current position. The ERROR
is used, the KEY condition is raised; if it Icondition is raised if this slot is not
is omitted, the ERROR condition is raised. I empty.
I
I The KEYTO option may be used to recover
Ithe key of a record that is added by means
sequential Access lof a WRITE statement without the KEYFROM
I option.
I
A SEQUENTIAL file that is used to access a I REWRITE statements, with or without the
RRDS may be opened with either the INPUT or IKEY option, are allowed for UPDATE files.
the UPDATE attribute. If any of the IIf the KEY option is used, the record that

196 OS PL/I CKT AND OPT LRM PART I

r---------------------------------------------------------------------------------------,
IFile declaration 1 1Valid statements, with options that must IOther options that can I
I I appear lalso be used I
1---------------------------------------------------------------------------------------
ISEQUENTIAL OUTPUTIWRITE FILE(file-expr) FROMCvariable) I
BUFFERED 3 I KEYFROM(expression): I
I I
ILOCATE variable FILE(file-expr) I SET (pointer-variable)
I KEYFROM(expression): I
SEQUENTIAL OUTPUT WRITE FILE(file-expr) FROMCvariable) IEVENTCevent-variable)
UNBUFF ERED 3 KEYFROM(expression): I
SEQUENTIAL INPUT READ FILE(file-expr) INTOCvariable)i IKEYCexpression) or KEYTO
BUFFERED I Ccharacter-string-
I variable)
I
READ FILE(file-expr) SET(pointer-variable)iIKEY(expression) or KEYTO
I Ccharacter-string-
I variable)
I
READ FILE(file-expr)i 2 I IGNORE Cexpression)

SEQUENTIAL INPUT IREAD FILE(file-expr) INTOCvariable); IEVENTCevent-variable)

UNBUFFERED I land/or either KEY
I I (expression) or KEYTO
I I (character-string-
I I variable)
I I
IREAD FILE(file-expr):2 ,EVENT(event-variable)
I land/or IGNORE(expression)

SEQUENTIAL UPDATE READ FILE(file-expr) INTOCvariable)i KEYCexpression) or KEYTO

BUFFERED (character-string-
variable)

READ FILE(file-expr) SETCpointer-variable); KEYCexpression) or KEYTO

Ccharacter-string-
variable)

READ FILECfile-expr)i 2 IGNORE (expression)

WRITE FILECfile-expr) FROM (variable)

KEYFROMCexpression):

REWRITE FILECfile-expr)i FROMCvariable) and/or

KEY(expression)

DELETE FILE(file-expr):5 KEY(expression)

'SEQUENTIAL UPDATE READ FILE(file-expr) INTOCvariable); EVENT (event-variable)

'UNBUFFERED and/or either KEY
,,I (expression) or KEYTO
Ccharacter-string-
, READ FILE(file-expr);2
variable)

EVENT Cevent-variable)
I
I and/or IGNORE(expression)
I
I WRITE FILECfile-expr) FROMCvariable) EVENT (event-variable)
I (continued) KEYFROM(expression);
L---------------------------------------------------------------------------------------J
Figure 12.13 CPart 1 of 3). Statements and options permitted for creating and
accessing VSAM data sets via prime or alternate indexes

Chapter 12: Record-oriented Transmission 191

r---------------------------------------------------------------------------------------,
File declaration 1 1Valid statements, with options that must lother options that can
I appear lalso be used
SEQUENTIAL UPDATEIREWRITE FILE(file-expr) FROMCvariable); I EVENT (event-variable)
UNBUFFERED I land/or KEYCexpression)
Ccontinued) I I
IDELETE FILECfile-expr);5 IKEY(expression) and/or
I I EVENT (event-variable)
DIRECT't INPUT I READ FILECfile-expr) INTOCvariable)
BUFFERED I KEYCexpression)i
I
IREAD FILE(file-expr) SET (pointer-variable)
I KEY(expression)i
DIRECT't INPUT IREAD FILE(file-expr) INTO (variable) I EVENT (event-variable)
UNBUFFERED I KEY(expression)i I
DIRECT OUTPUT IWRITE FILECfile-expr) FROM (variable)
BUFFERED I KEYFROM(expression)i
DIRECT OUTPUT IWRITE FILE(file-expr) FROM (variable) I EVENT (event-variable)
UNBUFFERED I KEYFROMCexpression): I
DIRECT't UPDATE READ FILE(file-expr) INTO (variable)
BUFFERED KEYCexpression)i
READ FILE(file-expr) SETCpointer-variable)
KEY(expression)i
REWRITE FILE(file-expr) FROM (variable)
KEY(expression)i
DELETE FILE(file-expr) KEY(expression)i 5
IWRITE FILECfile-expr) FROM (variable)
I KEYFROM(expression)i
DIRECT't UPDATE IREAD FILECfile-expr) INTOCvariable) IEVENTCevent-variable)
UNBUFFERED
,,REWRITE FILE(file-expr) FROM (variable)
, KEYCexpression); I
I

,,IDELETE
KEY(expression); ,,
I EVENT (event-variable)

FILE(file-expr) KEY(expression)i 5 'EVENT(event-variable)

I I
IWRITE FILE(file-expr) FROM (variable)
I KEYFROM(expression)i ,IEVENT(event-variable)
1The complete file declaration would include the attributes FILE and RECORD. If any
of the options KEY, KEYFROM, and KEYTO is used, the declaration must also include
the attribute KEYED.
The EXCLUSIVE attribute for DIRECT INPUT or UPDATE files, the UNLOCK statement for
DIRECT UPDATE files, and the NOLOCK option of the READ statement for DIRECT INPUT
files are ignored if they are used for a file associated with a VSAM KSDS.

L---------------------------------------------------------------------------------------J
Figure 12.13 (Part 2 of 3). statements and options permitted for creating and
accessing VSAM data sets via prime or alternate indexes

198 OS PL/I CKT AND OPT LRM PART I

 r---------------------------------------------------------------------------------------,I
laThe statement: READ FILE(file-expression); is equivalent to the statement:
I READ FILE (file-expression) IGNORE(l); I
I I
13A SEQUENTIAL OUTPUT file must not be associated with a data set accessed via an I
I alternate index. I
I I
I~A DIRECT file must not be associated with a data set accessed via a non-unique I
I alternate index. I
I I
15 DELETE statements are not allowed for a file associated with an ESDS accessed via an I
I
L-------------________________________________________
I alternate index.
----------------------------------J
Figure 12.13 (Part 3 of 3). Statements and options permitted for creating and
accessing VSAM data sets via prime or alternate indexes

is rewritten is the record with the The "data set" associated with each
specified relative record number; otherwise TRANSIENT file is in fact an input or
it is the record that was accessed by the output message queue set up by the MCP. A
previous READ statement. READ statement for the file will take the
next message (or the next record from the
DELETE statements, with or without the current message) from the associated queue,
KEY option, may be used to delete records assign the data part to the variable named
from the data set. in the READ INTO option (or set a pointer
to point to the data in a READ SET buffer),
and save the origin name by assigning i t to
Direct Access the variable named in the KEYTO option.
(The PENDING condition is raised if the
input queue is empty when the READ
IA DIRECT file used to access an RRDS may statement is executed.) A WRITE or LOCATE
Ihave the OUTPUT, INPUT. or UPDATE statement will transmit the processed
I attribute. Records may be read, written, message or record to the output queue,
I rewritten, or deleted exactly as though a using the element expression specified in
IKEYED SEQUENTIAL file were used. the KEYFROM option to identify the
destination.

Telepro cessing
ENVIRONMENT Attribute

The teleprocessing facilities of PL/I are

provided by an extension of the basic A message can consist of one logical
record-oriented transmission facilities record, or several logical records, on the
with the addition of the TRANSIENT file teleprocessing data set. The programmer
attribute and the PENDING condition. The must specify whether a complete message
implementation provides a communicating (which may be several logical records) or
link between the PL/I message processing only one logical record is to be
programs using these features, and the transmitted to his PL/I program at each I/O
teleprocessing facilities of the operating operation. He must also specify the size
system. of the record variable (or input and output
buffer, for locate mode), and the number of
A teleprocessing message control program intermediate buffers required for each
(MCP) handles messages originating from and message. This information can be provided
destined for a number of remote terminals by means of the appropriate options of the
or a number of PL/I message processing ENVIRONMENT attribute.
programs. Each origin or destination
associated with a message is identified by The options, and their meanings, are:
a name carried within that message.
Messages are transmitted to and from a PL/I TP(M): Each I/O operation in the PL/I
message processing program via queues in program transmits a complete
main storage. (These queues are supported message
by corresponding intermediate queues in a
disk data set. The PL/I program has access TP(R): Each I/O operation in the PL/I
only to the main storage queues, by means program transmits one logical
of intermediate buffers for each file.) record

Chapter 12: Record-oriented Transmission 199

 r---------------------~-----------------------------------------------------------------,
File deciaration 1 1Vaiid statements, with options that must lother options that can I
I appear lalso be used 1
---------------------------------------------------------------------------------------1
SEQUENTIAL OUTPUTIWRITE FILE(file-expr) FROM(variable); IKEYFROM(expression) or I
BUFFERED I IKEYTO(character-string- I
I I variable) I
I I I
ILOCATE variable FILE(file-expr) I SET (pointer-variable) I
SEQUENTIAL OUTPUTIWRITE FILE(file-expr) FROM(variable); I EVENT (event-variable)
UNBUFFERED I land/or either
I IKEYFROM(expression) or
I IKEYTO(character-string-
I I variable)

SEQUENTIAL INPUT I READ FILE (file-expr) INTO(variable); IKEY(expression) or KEYTO

BUFFERED I I (character-string-
I I variable)
I I
I READ FILE (file-expr) SET(pointer-variable);IKEY(expression) or KEYTO
I I (character-string-
I I variable)
I I
I READ FILE(file-expr);2 I IGNORE (expression)

SEQUENTIAL INPUT IREAD FILE(file-expr) INTO(variable); I EVENT (event-variable)

UNBUFFERED I I and/or either
I IKEY(expression) or KEYTO
I I (character-string-
I I variable)
I I
IREAD FILE(file-expr);2 IEVENT(event-variable)
I land/or IGNORE(expression)
SEQUENTIAL UPDATE READ FILE(file-expr) INTO(variable); KEY(expression) or KEYTO
BUFFERED (character-string-
variable)

READ FILE(file-expr) SET (pointer-variable) KEY(expression) or KEYTO

(character-string-
variable)

READ FILE(file-expr);2 IGNORE (expression)

WRITE FILE(file-expr) FROM(variable); KEYFROM(expression) or

KEYTO(character-string-
variable)

IREWRITE FILE(file-expr); FROM (variable) and/or

I KEY(expression)
I
IDELETE FILE(file-expr); KEY(expression)

SEQUENTIAL UPDATEIREAD FILE(file~expr) INTO(variable); I EVENT (event-variable)

I UNBUFFERED I land/or either
I I IKEY(expression) or REYTO
1I I I (character-string-
II I , variable)
II I I
II IREAD FILE(file-expr)i 2 I EVENT (event-variable)
II(continued) I land/or IGNORE(expression)
IL---------------------------------------------------------------------------------------J
I
IFigure 12.14 (Part 1 of 3). Statements and options permitted for creating and
I accessing VSAM relative-record data sets

200 OS PL/I CRT AND OPT LRM PART I

 r---------------------------------------------------------------------------------------,
IFile declaration 1 1Valid statements, with options that must lother options that can
I I appear lalso be used
1-------------------------------------------------------------
ISEQUENTIAL UPDATEIWRITE FILE(file-expr) FROM(variable);
-------------------------
EVENT (event-variable)
UNBUFFERED I and/or either
(continued) I KEYFROM(expression) or
I KEYTO(character-string-
I variable)
I
'REWRITE FILE(file-expr) FROM(variable); EVENT (event-variable)
I and/or KEY (express ion)
I
IDELETE FILE(file-expr); EVENT (event-variable)
1 and/or KEY (expression)

DIRECT OUTPUT IWRITE FILE(file-expr) FROM (variable)

BUFFERED 1 KEYFROM(expression);
ilDIRECT OUTPUT IWRITE FILE(file-expr) FROM (variable) I EVENT (event-variable)
I UNBUFFERED I KEYFROM(expression); I
1---------------------------------------------------------------------------------------
IDIRECT INPUT IREAD FILE(file-expr) INTO(variable) 1
1BUFFERED 1 KEY(expression); I
1 1 I
1 IREAD FILE(file-expr) SET (pointer-variable) I
I I KEY(expression); 1
1---------------------------------------------------------------------------------------
IDIRECT INPUT IREAD FILE(file-expr) INTO (variable) I EVENT (event-variable)
1UNBUFFERED I KEY(expression); 1
1-------------------------------------------------------------
IDIRECT UPDATE IREAD FILE(file-expr) INTO (variable)
-------------------------
1BUFFERED 1 KEY(expression);
I 1
I IREAD FILE(file-expr) SET (pointer-variable)
1 1 KEY(expression);
1 I
1 IREWRITE FILE(file-expr) FROM(variable)
1 KEY(expression);
1
IDELETE FILE(file-expr) KEY(expression);
1
IWRITE FILE(file-expr) FROM (variable)
I KEYFROM(expression);

DIRECT UPDATE IREAD FILE(file-expr) INTO (variable) I EVENT (event-variable)

UNBUFFERED 1 KEY(expression); I
I I
IREWRITE FlLE(file-expr) FROM(variable) I EVENT (event-variable)
I KEY(expression); I
I I
IDELETE FILE(file-expr) KEY(expression); IEVENT(event-variable)
1 I
IWRITE FILE(file-expr) FROM(variable) IEVENT(event-variable)
I KEYFROM(expression);
L _____________________________________________________ ----------------------------------J
I

Figure 12.14 (Part 2 of 3). statements and options permitted for creatin9 and
accessing VSAM relative-record data sets

Chapter 12: Record-oriented Transmission 201

r---------------------------------------------------------------------------------------,I
11 The complete file declaration would include the attributes FILE and RECORD. If any
I of the options KEY, KEYFROM, and KEYTO is used, the declaration must also include I
I the attribute KEYED. I
I I
I The EXCLUSIVE attribute for DIRECT INPUT or UPDATE files, the UNLOCK statement for I
I DIRECT UPDATE files, and the NOLOCK option of the READ statement for DIRECT INPUT I
I files are ignored if they are used for a file associated with a VSAM RRDS. I
I I
12The statement: READ FILE{file-expression): is equivalent to the statement: I
IL _____________________________________________________
READ FILE(file-expression) IGNORE(l); ----------------------------------J I

Figure 12.14 (Part 3 of 3). statements and options permitted for creating and
accessing VSAM relative-record data sets

RECSIZE: Size of the record variable (or program. The queue is always accessed
input or output buffer, for locate sequentially.
mode) in the PL/I program. If the
TP(M) option is used, this size The data set associated with a TRANSIENT
should, if possible, be equal to file differs from those associated with
the length of all the logical DIRECT and SEQUENTIAL files in that its
records that constitute the contents are dynamiC: reading a record
message. If it is smaller, part removes it from the data set. Such a da~a
of the message will be lost. If set can never be created by a DIRECT or
it is greater, the contents of the SEQUENTIAL file. (It can, however, be
last part of the variable (or accessed as a CONSECUTIVE data set by a
buffer) are undefined. If the SEQUENTIAL file.)
TP(R) option is specified, this
size must be the same as the The TRANSIENT attribute can be specified
logical record length. only for RECORD KEYED BUFFERED files with
either the INPUT or the OUTPUT attribute.
BUFFERS: Number of intermediate buffers (The EVENT option cannot be used for
required to contain the longest teleprocessing operations.) The file may
message to be transmitted. If a also have the ENVIRONMENT attribute with
message is too long for the the options appropriate to teleprocessing.
buffers specified, extra buffers
must be obtained before processing For TRANSIENT files, the file name or
can continue, which increases title must be the ddname of a DO statement.
execution time. The extra buffers The message queue data set is identified in
are obtained by the operating the DO statement by the QNAME parameter.
system: the programmer need not For a TRANSIENT OUTPUT file, the element
take any action. expression specified in the KEYFROM option
must have as its value a recognized
These are the only options of the terminal or program identification.
ENVIRONMENT attribute that can be specified
for a TRANSIENT file.

Error Handling

TRANSIENT Attribute
The conditions that can be raised during
teleprocessing transmission are TRANSMIT,
The TRANSIENT attribute, which is an KEY, RECORD, ERROR, and PENDING.
alternative to the DIRECT and SEQUENTIAL
attributes, indicates that the contents of The TRANSMIT condition can be raised
the data set associated with the file are only on input, and is as described for
re-established each time the data set is other types of transmission.
accessed. In effect, this means that
records can be continually added to the The RECORD condition is raised in the
data set by one program during the same circumstances as for other types of
execution of another program that transmission. (The messages and records
continually removes records from the data are treated as V-format records.)
set. Thus the data set can be considered
to be a continuous queue through which the The ERROR condition is raised as for
records pass in transit between the message other types of transmission; it is also
control program and the message processing raised when the expression in the KEYFROM

202 OS PL/I CKT AND OPT LRM PART I

option is missing or detectably invalid. The list of statements and options
Note that if the expression is permitted for TRANSIENT files is given in
syntactically valid but does not represent tabular form in figure 12.15. Some
an origin or a destination name recognized examples follow:
by the MCP, the KEY condition is raised.
DECLARE (IN INPUT,OUT OUTPUT) FILE
The PENDING condition can be raised only TRANSIENT ENV(TP(M) RECSIZE(124»,
during execution of a READ statement for a (INREC, OOTREC) CHARACTER(120)
TRANSIENT file. It is raised when the VARYING, TERM CHARACTER(S);
associated queue is empty: standard system
action is to wait at the READ statement READ FILE(IN) INTO(INREC) KEYTO(TERM):
until a message is available. When the
PENDING condition is raised, the value
returned by the ONKEY built-in function is
a null string. WRITE FILE(OUT) FROM(OUTREC)
KEYFROM (TERM) :
Note: When the TP(R) optio~ is specified
in the ENVIRONMENT attribute, a message is The above example illustrates the use of
transmitted one record at a time. There is move mode in teleprocessing applications.
no ON-condition or other'automatic means Note that the files IN and OUT are given
for detecting the end of the message: the the attributes KEYED and BUFFERED because
user is responsible for arranging the TRANSIENT implies these attributes. The
indication of the end of the message input buffer for file IN contains the next
(possibly by using the first record as a message (or record from a message,
header giving the necessary control depending on the message format) from the
information. ) input queue. The input queue will also be
named IN unless the file has been opened
with a TITLE option specifying a different
queue name. The message format is
determined by the programmer, and the file
statements and Options declaration for IN includes this
information in the ENVIRONMENT attribute.

The READ statement is used for input, with The READ statement causes the message or
either the INTO option or the SET option: record to be moved from the input buffer
the KEYTO option must be given. The origin into the variable INREC: if the buffer is
name is assigned to the variable named in empty when the READ statement is executed
the KEYTO option. If the-origin name is (i.e., there are no messages in the queue),
shorter than the character-string variable the PENDING condition is raised. 'I'he
named in the KEYTO option, i t is padded on standard system action for the condition is
the right with blanks. If the KEYTO to suspend execution and wait until a
variable is a varying-length string, its message is available. The name of the
current length is set to that of the origin origin is aSSigned to TERM.
name. The origin name should not be longer
than the KEYTO variable_(if it is, i t is After processing, the message or record
truncated), but in any case will not be is held in OUTREC. The WRITE statement
longer than 8 characters. The data part of moves i t to the output buffer, together
the message or record is a~signed to the with the value of TERM (which will still
variable named in the INTO option, or the contain the origin name unless another name
pointer variable named in the SET option is has been assigned to it during processing).
set to point to the data in the READ SET From the buffer, the message will be
buffer. automatically transmitted to the correct
queue for the destination, as specified by
Either the WRITE or the LOCATE statement the value of TERM.
may be used for output: either statement
must have the KEYFROM option -- the first Since the output queue is determined
eight characters of the value of the from the destination name, the fite name
KEYFROM expression are used to identity the OOT has no significance outside the PL/I
destination. The data part of the message program. However, the file would need the
is transmitted from the variable named in TRANSIENT, KEYED, and BUFFERED attributes,
the FROM option of the WRITE statement: or, and the correct message format in the
in the case of LOCATE, a pOinter variable ENVIRONMENT attribute.
is set to point to the location of the data
in the output buffer. When a message is DECLARE (IN INPUT,OUT OUTPUT) FILE
transmitted by an OUTPUT TRANSIENT file as TRANSIENT ENV(TP(M) RECSIZE(124»,
a number of logical records, the end of the MESSAGE CHARACTER(120) VARYING
message must be indicated by closing the BASED(INPTR),
file. TERM CHARACTER(S):

Chapter 12: Record-oriented Transmission 203

r---------------------------------------------------------------------------------------,
IFile Declaration IValid statements, with options that must lother options that can I
I 1appear I also be used I
1---------------------------------------------------------------------------------------
ITRANSIENT INPUT IREAD FILE(file-expr) INTO (variable) I
1 I KEYTO(character-string-variable); I
1 1 I
1 IREAD FILE(file-expr) SET (pointer-variable) I
I I KEYTO(character-string-variable); I
1---------------------------------------------------------------------------------------
ITRANSIENT OUTPUT IWRITE FILE(file-expr) FROM(variable) I
1 1 KEYFROM(expression); I
I 1 1
1 ILOCATE variable FILE(file-expr) I SET (pointer-variable)
I I KEYFROM(expression); I
1---------------------------------------------------------------------------------------
1 The complete file declaration would include the attribute FILE, RECORD, KEYED,
1

1 BUFFERED, and the ENVIRONMENT attribute with either the TP(M) or the TP(R) option.
L---------------------------------------------------------------------------------------J
Figure 12.15 statements and options permitted for TRANSIENT files

READ FILE (IN) SET (INPTR) KEYTO(TERM); the processing program could consist of a
number of subtasks, each associated with a
different queue. Each subtask processes
the input from its associated queue, and
WRITE FILE(OUT) FROM (MESSAGE) transmits output to the required
KEYFROM(TERM); destination. As soon as the PENDING
condition is raised in a subtask, another
This example is similar to the previous subtask could receive input or transmit
one, except that locate mode input is used; output.
the message data is processed in the input
buffer, using the based variable MESSAGE,
which has been declared with the pOinter Summary of Record-Oriented
variable INPTR. (The data of the message
will be aligned on a doubleword boundary.) Tr ansmission
Note that the attribute TRANSIENT implies
KEYED and BUFFERED. The WRITE statement The following points cover the salient
moves the processed data from the input to features of record-oriented transmission:
the output buffer; otherwise its effect is
as described for the WRITE statement in the 1. A SEQUENTIAL file specifies that the
first example. acceSSing, creation, or modification
of the data set records is performed
The technique used in this example would in a particular order:
be useful in applications where the
differences between processed and CONSECUTIVE or REGIONAL data set; from
unprocessed messages were relatively the first record of the data set to
simple, since the maximum size of input and the last record of the data set (or
output messages would be the same. If the from the last to the first if the
length and structure of the output message BACKWARDS attribute has been
could vary widely, depending on the text of specified).
the input message, locate mode output could
be used to advantage; after the input INDEXED or REGIONAL(l) data set; in
message had been read in, a suitable based ascending order of key sequence.
variable could be located in the output
buffer (using the LOCATE statement), where 2. A DIRECT file specifies that records
further proceSSing would take place. The may be processed in random order. The
message would be transmitted immediately particular record is identified by a
before execution of the next WRITE or key.
LOCATE statement for the file.
3. Records in a data set that are
Note that although the EVENT option is accessed, created, or modified by a
not permitted, data transmission could be SEQUENTIAL file mayor may not have
overlapped with processing in an MVT recorded keys. If they do, the
operating system by means of the PL/I recorded keys may be extracted from
multitasking facilities described in the data set or placed into the data
chapter 11, "Multitasking". For example, set by the KEYTO and REYFROM options.

204 OS PL/I CRT AND OPT LRM PART I

 REGIONAL (1) data sets may also be REWRITE statement may be used with
retrieved or created using the KEYTO UPDATE files only. Moreover, for
and KEYFROM options respectively; the DIRECT files, a REWRITE statement uses
region number is specified as the key. the KEY option to identify the
existing record to be replaced; a
4. INDEXED KEYED files opened for WRITE statement uses the KEYFROM
SEQUENTIAL INPUT and SEQUENTIAL UPDATE option, which not only specifies where
may be positioned to a particular the record is to be written in the
record within the data set either by a data set, but also specifies, except
READ KEY or a DELETE KEY operation for REGIONAL(l), an identifying key to
that specifies the key of the desired be recorded in the data set.
record. Thereafter, successive READ
statements without the KEY option will 8. Records of a SEQUENTIAL INPUT or
access the following records in the SEQUENTIAL UPDATE file can be skipped
data set sequentially. over and ignored by use of the IGNORE
option of a READ statement. The
5. Existing records of a data set in a expression of the IGNORE option
SEQUENTIAL UPDATE file can be specifies the number of records to be
modified, ignored, or, if the data set skipped. A READ statement in which
is INDEXED, deleted. The DELETE only the FILE option appears indicates
statement used without the KEY option that one record is to be skipped.
for this type of file specifies that
the last record read is to be deleted. 9. Teleprocessing support is provided by
(If the DELETE statement is used with an extension of the basic record-
a SEQUENTIAL file, the data set must oriented transmission facilities.
have INDEXED organization.) The DELETE TRANSIENT files are associated with
statement can be used with the KEY queues of messages either incoming
option to delete a specific record in from or outgoing to remote terminals.
a DIRECT UPDATE file; also, records Such files must be KEYED and BUFFERED,
can be added to such a file by means and the ENVIRONMENT attribute may be
of the WRITE statement. An eXisting used to specify the message format.
record in an UPDATE file can be TRANSIENT files can be accessed by
replaced through use of a REWRITE READ, WRITE, and LOCATE statements,
statement. which cannot have the EVENT option.

6. When a file has the DIRECT, INPUT or 110. For VSAM data sets, the WRITE
UPDATE, and EXCLUSIVE attributes, it 1 statement is permitted with UPDATE
is possible to protect individual I files. Also, for an ESDS or an RRDS,
records that are read from the data 1 the WRITE statement may have the KEYTO
set. For an EXCLUSIVE file, any READ I option.
statement without a NOLOCK option
automatically locks the record read.
No other task operating upon the same
data set can access a locked record Examples of Declarations of Record
until it is unlocked by the lOCking Files
task. The record is protected from
access by tasks in other jobs, as well
as by those within the same job as the Following are examples of declarations of
locking task. Any task referring to a file constants including the ENVIRONMENT
locked record will wait at that point attribute:
until the record is unlocked. A
record can be explicitly unlocked by DECLARE FILE#3 INPUT DIRECT
the locking task through execution of ENVIRONMENT(V BLKSIZE(328)
a REWRITE, DELETE, UNLOCK, or CLOSE REGIONAL (3 » ;
statement. Records are unlocked
automatically upon completion of the This declaration specifies only three file
locking task. The EXCLUSIVE attribute attributes: INPUT, DIRECT, and ENVIRONMENT.
applies to the data set and not the other implied attributes are FILE (implied
file. consequently, record protection by any of the attributes) and RECORD and
is provided even when all tasks refer KEYED (implied by DIRECT). Scope is
to the data set through use of EXTERNAL, by default. The ENVIRONMENT
different files. attribute specifies that the data set is of
the REGIONAL(3) organization and contains
7. A WRITE statement adds a record to a unblocked varying-length records with a
data set, while a REWRITE statement maximum length of 328 bytes. Note that a
replaces a record. Thus, a WRITE maximum length record will contain only 320
statement may be used with OUTPUT bytes of data to be used by the program,
files, and DIRECT UPDATE files, but a because 8 bytes are required for control

Chapter 12: Record-oriented Transmission 205

information in such V-format records. The With such a declaration, INVNTRY can be
KEY option must be specified in each READ opened for different purposes. It could,
statement that refers to this file. for example, be opened as follows:

DECLARE INVNTRY UPDATE BUFFERED

ENVIRONMENT CF RECSIZE(100) OPEN FILE (INVNTRY)
INDEXED BUFFERS(4»; UPDATE SEQUENTIAL BUFFERED;

This declaration also specifies only three With this OPEN statement, the file
file attributes: UPDATE, BUFFERED, and attributes would be the same as those
ENVIRONMENT. Implied attributes are FILE, specified (or implied) in the DECLARE
RECORD, and SEQUENTIAL (the last two statement in the second example above (the
attributes are implied by BUFFERED). Scope number of buffers would have to be stated
is EXTERNAL, by default. The data set is in the associated DO statement). The file
of INDEXED organization, and it contains might be opened in this way, then closed,
fixed-length records of 100 bytes each. and then later opened with a different set
Four buffers are to be allocated for use in of attributes, for example:
accessing the data set. Note that although
the data set actually contains recorded OPEN FILE (INVNTRY)
keys, the KEYTO option cannot be specified INPUT SEQUENTIAL KEYED;
in a READ statement, since the KEYED
attribute has not been specified. This OPEN statement allows records to be
read with either the KEYTO or the KEY
Note that for both of the above option. Because the file is SEQUENTIAL and
declarations, all necessary attributes are the data set is INDEXED, the data set may
either stated or implied in the DECLARE be accessed in a purely sequential manner:
statement. None of the attributes can be or, by means of a READ statement with a KEY
changed in an OPEN statement or in a DO option, it may be accessed randomly. A KEY
statement. The second declaration might option in a READ statement with a file of
have been written: this description causes a specified record
to be obtained. Subsequent READ statements
DECLARE INVNTRY without a KEY option access records
ENVIRONMENT(F RECSIZE(100) sequentially, beginning with the next
INDEXED); record.

206 OS PL/I CKT AND OPT LRM PART I

 Chapter 13: Editing and String Handling

The data manipulations performed by the If the aSSigned string is shorter than
arithmetic, comparison, and bit-string the length declared for the receiving
operators are extended in PL/I by a variety string variable, the assigned string is
of string-handling and editing features. extended on the right either with blanks,
These features are specified by data in the case of a character-string variable,
attributes, statement options, built-in or with zeros, in the case of a bit-string
functions, and pseudovariables. variable. Assume SUBJECT still has the
attributes CHARACTER (10). Then the
The following discussions give general following two statements assign equivalent
descriptions of each feature, along with values to SUBJECT:
illustrative examples.
SUBJECT = 'PHYSICS';
SUBJECT = 'PHYSICSbbb';
Editing by Assignment
The letter ~ indicates a blank character.

The most fundamental form of editing Let CODE be a bit-string variable with
performed by the assignment statement the attributes BIT(10). Then the following
involves converting the data type of the two statements assign equivalent values to
value on the right-hand side of the CODE:
assignment symbol to conform to the
attributes of the receiving variable. CODE '110011'B;
Because the assigned value is made to
conform to the attributes of the receiving CODE '1100110000'B;
variable, the precision or lengtn of the
assigned value may be altered. Such Note, however, that the following
alteration can involve the addition of statements do not assign equivalent values
digits or characters to and the deletion of to SOBJECT if it has the attributes
digits or characters from the converted CHARACTER (10):
item. The rules for data conversion are
discussed in chapter 4, "Expressions and SUBJECT = '110011'B:
Data Conversions", and in section F, "Data
Conversion and Exp~ession Evaluation". SUBJECT '1100110000'B;

When the first statement is executed, the

bit-string constant on the right is first
ALTERING THE LENGTH OF STRING DATA converted to a character string and is then
extended on the right with blank characters
rather than zero bits. This statement is
When a value is assigned to a string equivalent to:
variable, i t is converted, if necessary, to
the same string type (character or bit) as SUBJECT = '110011bbbb';
the receiving string. If necessary, i t is
truncated or, for fixed-length receiving The second of the two statements
strings, extended on the right to conform requires only a conversion from bit-string
to the declared length of the receiving to character-string type and is equivalent
string. For example, assume SUBJECT has to:
the attributes CHARACTER (10), indicating a
fixed-length character string of ten SUBJECT = '1100110000';
characters. Consider the follOwing
statement: A string value, however, is not extended
with blank characters or zero bits when i t
SUBJECT = 'TRANSFORMATIONS'; is assigned to a string variable that has
the VARYING attribute. Instead, the length
The length of the string on the right is specification of the receiving string
fifteen characters; therefore, five variable ~s effectively adjusted to
characters will be truncated from the right describe t~e length of the assigned string.
end of the string when it is aSSigned to Truncation will occur, though, if the
SUBJECT. This is equivalent to executing: length of the aSSigned string exceeds the
maximum length declared for the varying-
SUBJECT. = •TRANSFORMA ' ; length string variable.

Chapter 13: Editing and String Handling 207

OTHER FORMS OF ASSIGNMENT list are to be obtained from the specified
character string. The PUT statement
specifies that data items of the data list
In addition to the assignment statement, are to be assigned to the specified
PL/I provides other ways of assigning character-string variable. The "data-
values to variables. Among these are two specification" is the same as described for
methods that involve input and output input and output. In general, it takes one
statements: one in which actual input and of the following forms:
output operations are performed, and one in
which data movement is entirely internal. DATA [(data-list)]
(LIST] (data-list)
Input and output Operations EDIT {(data-list) (format-list)} •••
Although the STRING option can be used
Although the assignment statement is with each of the three modes of stream-
concerned with the transmission of data oriented transmission, it is most Useful
between storage locations internal to a with edit-directed transmission, which
computer, input and output operations can considers the input stream to be a
also be treated as related forms of continuous string of characters. For list-
assignment in which transmission occurs directed and data-directed GET statements,
between the internal and external storage individual items in the character string
facilities of the computer. must be separated by commas or blanks; for
data-directed GET statements, the string
Record-oriented operations, however, do must also include the transmission-
not cause any data conversion of items in a terminating semicolon, and each data item
logical record when it is transmitted. must appear in the form of an assignment
Required editing of the record must be statement. Edit-directed transmission
performed within internal storage either provides editing facilities by means of the
before the record is written or after it is format list. Note that the COLUMN control
read. format option may not be used with the
STRING option.
Stream-oriented operations, on the other
hand, do provide a variety of editing The NAME condition is not raised for a
functions that can be applied when data GET DATA statement with the STRING option.
items are read or written. These editing Instead, the ERROR condition is raised for
functions are similar to those provided by situations that would cause the NAME
the assignment statement, except that any condition to be raised for a GET DATA
data conversion always involves character statement with the FILE option.
type, conversion from character type on
input, and conversion to character type on The STRING option permits data gathering
output. or scattering operations to be performed
with a Single statement, and it allows
stream-oriented processing of character
strings that are transmitted by record-
STRING option in GET and PUT statements oriented statements. Consider the
following statement:
The STRING option in GET and PUT statements PUT STRING (RECORD) EDIT
allows the statements to be used to (NAME, PAY#, HOURS*RATE)
transmit data between internal storage (A(12), A(1), P'$999V.99');
locations rather than between the internal
and external storage facilities. In both This statement specifies that the
GET and PUT statements, the FILE option, character-string value of NAME is to be
specified by FILE (file-expr) , is replaced aSSigned to the first (leftmost) 12
by the STRING option, as shown in the character pOSitions of the string named
following formats: RECORD, and that the character-string value
of PAY# is to be aSSigned to the next seven
GET STRING (character-string- character pOSitions of RECORD. The value
expression) of BOURS is then to be multiplied by the
data specification; value of RATE, and the product is to be
edited into the next seven character
PUT STRING (character-string-variable) pOSitions, according to the picture
data specification; specification.
The GET statement specifies that data items Frequently, it is necessary to read
to be aSSigned to variables in the data records of different formats, each of which

208 OS PL/I CKT AND OPT LRM PART I

gives an indication of its format within formats. A picture specification consists
the record by the value of a data item. of a sequence of character codes enclosed
The STRING option provides an easy way to in quotation marks which is either part of
handle such records: for example: the PICTURE attribute, or part of the P
(picture) format-item:
READ FILE (INPUTR) INTO (TEMP);
GET STRING (TEMP) EDIT (CODE) (F(l»: DECLARE PRICE PICTURE'$Z9V99'i
IF CODE ~= 1 THEN GO TO OTHER TYPE:
GET STRING (TEMP) EDIT (X,Y,Z) PUT FILE(SYSPRINT) EDIT
(X(l), 3 F(lO,Q»: ('PART NUMBER', PART#)
(A(12), P'AAA99X'):
The READ statement reads a record from the
input file INPUTR. The first GET statement Picture specifications are of two types:
uses the STRING option to extract the code
from the first byte of the record and to • numeric character specificatons
assign i t to CODE. The code is tested to
determine the format of the record. If the • character-string picture specifications
code is 1, the second GET statement then
uses the STRING option to assign the items A numeric character specification in a
in the record to X,Y, and Z. Note that the PICTURE attribute indicates that the
second GET statement specifies that the data item represents a numeric quantity
first character in the string TEMP is to be but that it is to be stored as a
ignored (the X(l) format item in the format character-string, and indicates how the
list). Each GET statement with the STRING numeric value is to be represented in
option always specifies that the scanning the string. A numeric character
is to begin at the first character of the specification in a P format item
string. Thus, the character that is indicates how a numeric value is, or is
ignored in the second GET statement is the to be, represented as a character-string
same character that is assigned to CODE by on the external medium.
the first GET statement.
A character-string picture specification
In a similar way, the PUT statement with is an alternative way of describing a
a STRING option can be used to create a fixed-length character string, with the
record within internal storage. In the additional facility of indicating that any
following example, assume that the file position in the string may only contain
OUTPRT is eventually to be printed. characters from certain subsets of the
complete set of characters available On the
PUT STRING (RECORD) EDIT operating system.
(NAME, PAY#, HOURS*RATE)
(X(l), A(12), X(10), A(1), X(lO), The concepts of the two types of picture
P'$999V.99'); specifications are described separately
below, and a detailed description of each
WRITE FILE (OUTPRT) FROM (RECORD): picture character, together with examples
of its use, appears in section 0, "Picture
The PUT statement specifies, by the X(l) Specification Characters·. It is
spacing format item, that the first sufficient here to note that the presence
character assigned to the character-string of an A or X picture character defines a
variable is to be a single blank, the ANS picture specification as a character-string
carriage-control code that specifies a picture specification: otherwise, it is a
single space before printing. Following numeric character specification.
that, the values of the variables NAME and
PAY# "and of the expression HOURS*RATE are
assigned. The format list specifies that
ten blank characters are to be inserted Numeric Character Specifications
between NAME and PAY# and between PAY# and
the expression value. The WRITE statement
specifies that record transmission is to be A numeric character specification specifies
used to write the record into the file that the associated data item has a numer1c
O~P~. value but is to be stored (or is to be
represented in the external medium) as a
character string. It also specifies the
form the character string is to take, and
PICTURE SPECIFICATION exactly how the numeric value is
represented in the string. For example:

Picture specifications extend the editing DCL PRICE PICTURE'$Z9V99';

facilities available in PL/I, and provide
the user with greater control over his data This specifies that PRICE is to be

Chapter 13: Editing and string Handling 209

represented by a character-string of length is a digit (zero through nine). The
S. The first character is always $, the numeric value is the value of the digits as
second will be a blank or non- zero digit, an unsigned decimal number (i.e., FIXED
and the third, fourth and fifth characters DECIMAL (n,O». For example:
will be digits. The numeric value is
indicated by the four characters which can DCL DIGIT PICTURE'9'
represent digits, a decimal pOint being COUNTPICTURE'999',
assumed in the position indicated by the V; XYZ PICTURE' (10)9';
hence it is regarded as FIXED DECIMAL
(4,2), and is always positive. 13.2S is The last example shows an alternative way
represented as '$132S' and .9S as '$b09S'. of writing the picture specification 9 ten
times.
The numeric character specification has
two major uses: Example of use:

• For data items which will be concerned DCL 1 CARD IMAGE,

with input/output operations (although 2 DATA CHAR(12),
they may be used anywhere in a program 2 IDENTIFICATION CHAR(3),
where numeric data can occur). However, 2 SEQUENCE PIC'99999'~
most numeric operations on pictured data
are considerably less efficient than the
same operations on coded numeric data.
SEQUENCE = SEQUENCE + 1;
• The second use stems from the fact that WRITE FILE(OUTPUT) FROMCCARD_lMAGE);
a pictured data item effectively has two
values. When the item is used in a (Note that the definition of '9' in a
numeric context, the numeric value is character-string picture is different in
obtained from or stored into the that the corresponding character can be
character-string by the conversion blank or a digit.)
process defined by the picture
specification; when the item is used as
source data in a context where a
character-string expression is required, Picture Characters Z *
the actual character-string which
represents the value is used. For
example: It is often preferable to replace leading
zeros in numbers by blanks. In pictures
DCL COUNT PICTURE'999' INITIAL(O), this is accomplished by using the Z picture
STRING CHAR (3); specification character. A picture
COUNT = COUNT +1; specification containing only ZS and 9s has
STRING = COUNT; one or more ZS optionally followed by one
or more 9s. The representation of numeric
The initial representation of COUNT is data is as for the '9' picture
'000'. In the first aSSignment specification except that if the digit to
statement, this is converted to FIXED be held would otherwise be zero and if all
DECIMAL (3,0), the addition is digit positions to the left would also be
performed, and the result is converted zero, then the character-string will
back to the pictured form '001'. In the contain a blank in this position. For
second assignment statement the value of example:
string is set to '001'.
DCL PAGE_NUMBER PICTURE'ZZ9';
Note particularly that the character
context includes defining. A numeric The value 191 is held as '191', 69 as
character data-item may be defined on a 'b69', S as 'bbS' and zero as 'bbO'. With
character-string and vice versa. a picture specification of all Zs, the
value zero is held as an all-blank string.

The asterisk picture specification

Picture Character '9' in Numeric character has the same effect as the Z
Character Specifications character except that an * is held in the
string instead of a blank. This can be
used, for example, when printing checks,
The picture character '9' is the simplest when it is desired not to leave blank
form of numeric character specification. A spaces within fields. For example:
string of n '9' picture characters
specifies that the item is to be DeL CREDIT PICTURE '$**9.99';
represented by a fixed-length character-
string of length n, each character of which (The $ and (.) characters are described

210 OS PL/I CKT AND OPT LRM PART I

below.) A value of 95 is held as '$**0.95'; DECLARE RATE PICTURE '9V99.99';
a value of 12350 is held as '$123.50'.
Let RATE be used as follows:

RATE = 7.62;
Picture Character V
When this statement is executed, decimal
pOint alignment occurs on the character V
The V picture specification character and not the decimal point picture character
indicates the position of an assumed that appears in the picture specification
decimal point within the character-string. for RATE. If RATE were printed, it would
For example: appear as '762.00', but its arithmetic
value would be 7.6200.
DCL VALUE PICTURE 'Z9V999';
Unlike the character V, which can appear
The string '12345' represents the numeric only once in a picture specification, the
value 12.345. Note that th~ V character in decimal pOint picture character can appear
the picture specification does not specify more than once; this allows digit groups
a character position in the character- within the numeric character data item to
string representation. In particular, on be separated by points, as is common in
assignment to the data item a decimal pOint Dewey decimal notation and in the numeric
is not included in the character string. notations of some European countries.

Because a decimal point picture

character causes a period character to be
Insertion Picture Characters B. / inserted into the character-string value of
a numeric character data item, it is called
an insertion character. PL/I provides
A decimal point picture character(.) can three other insertion characters: comma
appear in a numeric picture specification. e,), slash(/), and blank(B). Consider the
It merely indicates that a pOint is to be following statements:
included in the character representation of
the value. Therefore, the decimal point is DECLARE RESULT PICTURE '9.999.999,V99';
a part of its character-string value. The
decimal point picture character does not RESULT = 1234567;
cause decimal point alignment during
assignment; it is not a part of the The character-string value of RESULT would
variable's arithmetic value. Only the be'1.234.5b7,00'. Note that decimal pOint
character V causes alignment of decimal alignment occurs before the two rightmost
points. For example: digit positions, as specified by the
character V. If RESULT were assigned to a
DECLARE SUM PICTURE '999V.99'; coded arithmetic field, the value of the
data converted to arithmetic would be
SUM is a numeric character variable 1234567.00.
representing numbers of five digits with a
decimal point assumed between the third and It a pOint, comma or slash picture
fourth digits. The actual pOint specified character appears with a string of Z or *
by the decimal point insertion character is zero suppression characters, then if all
not a part of the arithmetic value; it is, previous digits in the string are
however, part of its character-string suppressed, the insertion character is
value. (The decimal point picture suppressed to blank or '*'.
character can appear on either side of the
character V. In certain contexts the two The B character differs from the other
forms have different meanings but V. is three in that a·blank is always inserted in
recommended in most cases. See section D, the corresponding position of the character
·Picture Specification Characters.-) The string, even within a string of * zero
following two statements assign the same suppression characters.
character string to SUM:

SUM = 123;
Picture Character $
SUM = 123.00;

In the first statement, two zero digits are The $ picture character controls the
added to the right of the digits 123. appearance of the currency symbol $ in
specified positions of numeric character
Note the effect of the following data items. For example a dollar sign can
declaration. be appended to the left of a numeric

Chapter 13: Editing and String Handling 211

character item, as indicated in the specifies a character in the character-
following statements: string representation which will hold a
digit and sign, in the representation
DECLARE PRICE PICTURE '$99V.99'; described above, i.e., 12-punch
superimposed on 0, or on 1 through 9 (A
PRICE = 12.45; through I) for positive, ii-punch
superimposed on 0, or on 1 through 9 (J
The character-string value of PRICE is through R) for negative. It can appear
equivalent to the character-string constant anywhere a '9' picture specification
'$12.45'. Its arithmetic value, however, character could have occurred. For
is 12.45. example:

DCL CREDIT PICTURE 'ZZV9T';

Sign Specification in Numeric Character The character-string representation of

Specifications CREDIT is 4 characters. +21.05 is held as
'210E'. -0.07 is held as 'bbOP'.

There are several ways in which signed The I picture specification character
information may be held in a numeric specifies a character position which holds
character data item. The simplest of these the representation of a digit overpunched
is the S character specification. This with a 12-punch if the value is positive or
specifies a character in the character- zero, but just a digit if the value is
string representation which contains '+' if negative.
the value is positive or zero, and "~_I if
the value is negative. It must occur The R picture specification character
either to the right or to the left of all specifies a character position which hold
digit positions. For example: the representation of a digit overpunched
with an ii-punch if the value is negative,
DeL ROOT PICTURE 'S999'; but just a digit if the value is positive.
For example:
50 is held as '+50', zero as '+000' and
-243 as '-243'. Similarly the '+' picture GET EDIT (X) (P'R99');
character specifies a corresponding
character position containing '+' for will set X to (+) 132 on finding '132' in
positive or zero, and blank for negative the next 3 positions of the input stream,
values; the '_I picture character specifies but -132 on finding 'J32'.
a corresponding character position
containing blank for positive or zero, and
1_' for negative values.
other Numeric Character Facilities

overpunched Sign Specification Further details on the use of the above

Characters, T I R picture specification characters, together
with details of picture specification
characters for floating signs and currency
An alternative way of representing signed symbols, and floating pOint values, appear
values, which does not require an in section 0, ·Picture Specification
additional character in the string, is by Characters·.
an overpunched sign specification. This
representation has arisen from the custom The tull list of numeric character
of indicating signs in numeric data held on specification characters is:
punched cards, by superimposing a 12-punch
(to represent +) or an ii-punch (to 9,V,Z,*,Y,(.),(,),/,B,S,+,-,$,CR,DB,T,I,R,
represent -) on top of a column containing K,E,F of which all except K,V,F specify the
a digit (usually the last one in a field). occurrence of a character in the character-
The resulting card-code is, in most cases, string representation.
the same as that for an alphabetic
character (e.g., 12-punch superimposed on 1
through 9 gives A through I, ii-punch
superimposed on 1 through 9 gives J through Character-String picture Specifications
R). The 12-0 and 11-0 combinations are not
characters in the PL/I set but are within
the set of characters accepted by the A character-string picture specification is
operating system. an alternative way of describing a fixed-
length character string, with the
The T picture specification character additional facility of indicating that any

212 OS PL/I CRT AND OPT LRM PART I

position in the string may only contain DECLARE 1 PERSONNEL RECORD,
characters from certain subsets of the 2 NAME, -
complete set of available characters. 3 LAST CBARACTER(15),
3 FIRST CHARACTER(lO),
A character-string picture specification 3 MIDDLE CHARACTER(l),
is recognized by the occurrence of an A or 2 CODE STRING,
X picture specification character. The 3 MALE BIT(l),
only valid characters in a character-string 3 SECRETARIAL BIT(l),
picture specification are X, A, and 9. 3 AGE,
Each of these specifies the presence of one 4 (UNDER 20,
character position in the character-string TWENTY TO 30,
which can contain the following: OVER 30) BIT(l),
3 HEIGHT,-
X any character recognized by the 4 (OVER 6,
particular implementation (i.e., FIVE-SIX TO 6,
all 256 possible bit combinations UNDER 5 6) BIT(l),
represented by the 8-bit byte). 3 WEIGHT, - -
4 (OVER 180,
A any alphabetic character, #, a, $, ONE TEN TO 180,
or blank. UNDER_ll0)-BIT(1),
3 EYES,
9 any digit, or blank. Note the 4 (BLUE,
difference from the 9 picture BROWN,
specification character in numeric HAZEL,
character specifications. GREY,
OTHER) BIT(l),
When a character-string value is aSSigned, 3 HAIR,
or transferred, to a pictured character- 4 (BROWN,
string data item, the particular character BLACK,
in each pOSition is checked for validity, BLOND,
as specified by the corresponding picture RED,
specification character, and the CONVERSION GREY,
condition is raised for an invalid BALD) BIT (1) ,
character. For example: 3 EDUCATION,
4 (COLLEGE,
DECLARE PART# PICTURE 'AAA99X': HIGH SCHOOL,
GRAMMAR_SCHOOL) BIT(l)~
The following values are valid for
assignment to PART#.

'ABC12M'
'bbb09/'
'XYZb13' This structure contains NAME, a minor
structure of character-strings, and
The following values are not (the invalid CODE STRING, a minor structure of bit-
characters are underscored)~ strings. By default, the elements of
PERSONNEL-RECORD have the UNALIGNED
'AB123M' attribute. Consequently, CODE_STRING is
'ABC1/2' mapped with eight elements per byte, that
-
'Mb#AS·, , is, in the same way as a bit-string of
length 25.

Each of the first two bits of the string

represents only two alternatives: MALE or
....MALE and SECRETARIAL or .... SECRETARIAL. The
other categories (at level 3) list several
alternatives each. (Note that the level
number 4 and the attributes BIT (1) are
factored for each category.)
Bit-String Handling

The following examples illustrate SOme of

the facilities of PL/I that can be used in The following portion of a program might
bit-string manipulations. be used with PERSONNEL_RECORD:

Chapter 13: Editing and String Handling 213

INREC: READ FILE (PERSON) such as when a man is described as having
INTO (PERSONNEL RECORD): grey hair and being bald, he would be
IF (~MALE , SECRETARIAL selected by the first method but not by the
, UNDER 20 second. The second method also has the
, UNDER-5 6 disadvantage that if a further item of
, UNDER=110 data, such as another colour of hair, were
, BLUE to be added, the bit string constants would
, (HAIR. BROWN I BLOND) have to be changed in every comparison,
, HIGH SCHOOL) whereas the first method requires that only
I (MALE , ~SECRETARIAL the comparisons in which the new item is
, OVER 30 used need to be changed.
, OVER-6
, OVER=180 If the second method were used, an
, EYES. GREY improvement could be made by using
, BALD combinations of bits to denote each
, COLLEGE) characteristic, rather than Single bits.
THEN PUT LIST (NAME): For instance, the minor structure HAIR
GO TO INREC; could be replaced by a bit string length 3
at the same level in the structure and,
Another way to program the same 'OOO'B could represent bald, 'OOl'B grey-
information retrieval operation is as haired, '010'B red-haired, etc. ThiS would
follows: reduce length required for PERS STRING from
25 to 16 bits, and would obviate the
DECLARE PERS STRING BIT(25) DEFINED possibility of conflicts such as that
CODE_STRING; between bald and grey-haired.
IF PERS STRING The tests might also be made with a
=-, 0110000100110000100000010'1 B series of IF statements, either nested or
THEN GO TO OUTP; unnested, in which each bit would be tested
with a single IF statement.
IF PERS STRING
=-'0110000100110000001000010'B
THEN GO TO OUTP;
String Built-in Functions
IF PERS STRING
=-'1000110010000010000001100'B
THEN GO TO OUTP; PLII provides a number of built-in
fUnctions, some of which also can be used
GO TO INREC; as pseudovariables, to add power to the
string-handling facilities of the language.
OUTP: PUT LIST (NAME): Following are brief descriptions of these
functions (more detailed descriptions
GO TO INREC; appear in section G, -Built-in FUnctions
and pseudovariables W ) .
In this example, the bit string PERS_STRING
is defined on the minor structure The BIT built-in function specifies tbat
CODE_STRING. Bit-string constants are a data item is to be converted to a bit
constructed to represent the values of the string. The built-in function allows a
information being sought. The bit string programmer to specify the length of the
then is compared, in turn, with each of the converted string, overriding the length
bit-string constants. Note that the first that would result from the standard rules
and second constants are identical except of data conversion.
that the first tests for brown hair and the
second tests for blond hair. These two The CHAR built-in function is exactly
variations are specified in the first the same as the BIT built-in function,
example by (HAIR.BROWNIBLOND). except that the conversion is to a
character string whose length may be
Note that the second method of testing specified by the programmer.
PERSONNEL RECORD could not be used if the
structure-were ALIGNED (the base identifi~ The SUBSTR built-in function, which CaB
for overlay defining must beUNALXGNED). also serve as a pseudovariable in a
The first method, if it were used, would be receivin9 field, allows a specific
more efficient with an ALIGNED structure. sUbst.ring to be extracted from (or assiC'jDeil
to in the case of a pseudovariablel witbin
The second method has the disadvantage a specified strinq value.
that the 25 bits in PERS STRING have to
match the bit-string constant exactly. The IMDBX built-in function allows a
This means that in an abnormal situation, string, either a character string or a m. t

214 OS PL/I CRT AND OPT LRM PART I

string, to be searched for the first In this statement the internal
occurrence of a specified substring, which representation of the character 'A' is for
can be a single character or bit. The these implementations a string eight bits
value returned is the location of the first in length. This bit string is converted to
character or bit of the Substring, relative a fixed binary arithmetic value, and used
to the beginning of the string. The value as a subscript for the array. (The decimal
is expressed as a binary integer. If the value of this particular subscript is 193).
substring does not occur in the specified
string, the value returned is zero.
The TRANSLATE built-in function changes
The LENGTH built-in function gives the specified character elements in a string
current length of a character string or bit for specified replacement character
string. It is particularly useful with elements. The 'replacement' element is
strings that have the VARYING attribute. inserted into the 'position' in the string
occupied by the element to be replaced.
The HIGH built-in function provides a
string of a specified length that consists
of repeated occurrences of the highest This built-in function enables the
character in the collating sequence. For programmer to use a translation facility
these implementations, the character is Whereby all the characters in a given
hexadecimal FF. string are translated according to a
translation table contained in two other
The LOW built-in function provides a strings. One of these strings serves as a
string of a specified length that consists key to the replacement characters held in
of repeated occurrences of the lowest the other string. For example:
character in the collating sequence. For
these implementations, the character is DECLARE (W,X,Y,Z) CHAR (3);
hexadecimal 00.
X='ABC';
The REPEAT built-in function permits a Y='TAR';
string to be formed from repeated Z='CAB'i
occurrences of a specified substring. It
is used to create string patterns. W = TRANSLATE (X,Y,Z);
The STRING built-in function, which can /* W = 'ART' */
also be used as a pseUdovariable,
concatenates all the elements in an The VERIFY built-in function compares
aggregate variable into a single string two strings to check whether the bits or
element. characters in one string occur anywhere in
the other string. If all the characters or
The BOOL built-in function allows any of bits in one string are detected in the
the 16 different Boolean operations to be second string, a value of '0' is returned.
applied to two specified bit strings. If a character or bit does not occur in the
second string, a value representing the
The UNSPEC built-in function, which can position of this character or bit in the
also be used as a pseudovariable, specifies first string is returned.
that the internal coded representation of a
value is to be regarded as a bit string The first string is verified from left
with no conversion. For example: to right. A position value for the first
unmatched bit or character only is
x = ARRAY(UNSPEC('A'»; returned.

CHapter 13: Editing and string Handling 215

 Chapter 14: Exceptional Condition Handling and Program
Checkout

When a PL/I program is executed, a large The most common system action is to
number of exceptional conditions are raise the ERROR condition. This provides a
monitored by the system and their common condition that may be used to check
occurrences are automatically detected for a number of different types of errors,
whenever-they arise. These exceptional rather than checking each error type
conditions may be errors, such as overflow individually. standard system action for
or an input/output transmission error, or the ERROR condition depends on the
they may be conditions that are expected processing mode:
but infrequent, such as the end of a file
or the end of a page when output is being Batch processing (opt~izing and checkout
printed. compilers): If the condition is raised
in the major task, the FINISH condition
When checking out a program, a is raised and the program is
programmer can also get a selective flow subsequently terminated. If it is
trace and dumps by specifying that the raised in a subtask, that task is
occurrence of anyone of a list of terminated.
identifiers be treated as an exceptional
condition. Conversational processing (checkout
compiler only): Control is passed to
Each of the conditions for which a test the terminal.
may be made has been given a name, and
these names are used by the programmer to The programmer may specify whether or
control the handling of exceptional not some conditions are to be enabled, that
conditions. The list of condition names is is, are to be checked for so that they will
part of the PL/I language. For keyword cause an interrupt when they arise. If a
names and descriptions of each of the condition is disabled, an occurrence of the
conditions, see section H, -ON-Conditions.- condition will not cause an interrupt.
Under the checkout compiler, the SIZE,
The situations in which these conditions STRINGRANGE, and SUBSCRIPTRANGE conditions
occur is the same for both the optimizing are continuously monitored, whether enabled
and the checkout compilers. The enabling or not.
of these conditions, and the specifying of
the action required when a condition is All input/output conditions and the
raised, are described in this chapter. ERROR, FINISH, and AREA conditions are
always enabled and cannot be disabled. All
with the checkout compiler, the of the computational conditions and the
facilities for making values available to program checkout conditions may be enabled
the programmer during execution are greatly or disabled. The program checkout
extended. These facilities are described conditions and the SIZE condition must be
in chapter 15, -Execution-time Facilities explicitly enabled if they are to cause an
of the Checkout Compiler-. interrupt: all other conditions are enabled
by default and must be explicitly disabled
if they are not to cause an interrupt when
they occur.
Enabled Conditions and Established
Action
A condition that is being monitored, and Condition Prefixes
the occurrence of which will cause an
interrupt, is said to be enabled. Any
action specified to take place when an Enabling and disabling can be specified for
occurrence of the condition causes an the eligible conditions by a condition
interrupt, is said to be established. prefix. A condition prefix is a list of
one or more condition names, enclosed in
Most conditions are checked for parentheses and separated by commas, and
automatically, and when they occur, the connected to a statement (or a statement
system will take control and perform some label) by a colon. The prefix always
standard action specified for the precedes the statement and any statement
condition. Such conditions are enabled by labels. For example:
default, and the standard system action is
established for them. (SIZE): L1: X=(I*.N)/(M+L);

Chapter 14: Exceptional Condition Handling and Program Checkout 217

A condition name in a prefix list indicates of the scope of the redefining prefix, the
that the corresponding condition is enabled redefinition no longer applies. A
within the scope of the prefix. condition prefix can be attached to any
statement except a DECLARE, DEFAULT, or
The name of a condition used in a prefix ENTRY statement.
can be preceded by the word NO, without a
separating blank or connector, to indicate
that the corresponding condition is
disabled. For example: ON Statement

(NOCONVERSION): Y=AIIB:
A standard system action exists for every
condition, and if an interrupt occurs, this
standard system action will be performed
scope of the Condition Prefix unless the programmer has specified an
alternate action in an ON statement for
that condition. The purpose of the ON
The scope of the prefix, that is, the part statement is to establish the action to 'be
of the program throughout which i t applies, taken when an interrupt results from an
is usually the statement to which the exceptional condition that has been
prefix is attached. The prefix does not enabled, either by default Or by a
apply to any functions or subroutines that condition prefix.
may be invoked in the execution of the
statement. ~ The action specified in an ON
statement will not be executed durihg any
A condition prefix to an IF statement portion of a program throughout which the
applies only to the evaluation of the condition has been disabled.
expression following the IF: it does not
apply to the statements in the THEN or ELSE The form of the ON statement is:
clauses, although these may themselves have
prefixes. Similarly, a prefix to the ON ON condition[SNAP]{SYSTEMilon-unitJ
statement has no effect on the statements
in the on-unit. (See section J, ·Statements· for a full
description) •
IA condition prefix to a DO statement or a
ISELECT statement applies only to the The keyword SYSTEM followed by a
levaluation of any expressions in the semicolon specifies standard system action
(statement itself and not to any other whenever an interrupt occurs. It re-
Istatement in the group. Condition prefixes establishes system action for a condition
Ito a WHEN clause apply only to the for which some other action has been
levaluation of expressions in the WHEN established.
Iclause itself: they do not apply to the
Istatements following the WHEN clause. The on-unit is used by the programmer to
specify an alternative action to be taken
Condition prefixes to the PROCEDURE whenever an interrupt occurs.
statement and the BEGIN statement are
special (though commonly used) cases. A The SNAP option specifies that, when an
condition prefix attached to a PROCEDURE or interrupt occurs, a list of all blocks in
BEGIN statement applies to all the the chain of invocation leading to the
statements up to and including the current task is written on the standard
corresponding END statement. This includes system file SYSPRINT. If SNAP is
other PROCEDURE or BEGIN statements nested specified, the action of the SNAP option
within that block. It does not apply to precedes the action of the on-unit. If
any procedures lying outside that block. SNAP SYSTEM is specified, the system action
message is followed immediately by a list
The enabling or disabling of a condition of active blocks.
may be redefined within a block by
attaching a prefix to statements within the The on-unit must be either a single,
block, including PROCEDURE and BEGIN unlabeled, Simple statement or an unlabeled
statements (thus redefining the enabling or begin block. The single statement cannot
disabling of the condition within nested be a RETURN, FORMAT, DECLARE, or DEFAULT
blocks). Such a redefinition applies only statement. It cannot be either of the two
to the execution of the statement to which compound statements, IF and ON, or a do-
the prefix is attached. In the case of a I group, or a select-group. (PROCEDURE,
nested PROCEDURE or BEGIN statement, it I BEGIN, END, DO, and SELECT statements can
applies only to the block the statement never appear as single statements.) The
defines, as well as any blocks contained begin block, if it appears, can contain any
within that block. When control passes out Istatement (except that a RETURN statement

218 OS PL/I CKT AND OPr LRM PART I

can appear only within a procedure nested invalid character is changed in the on-
in the begin block). unit. If i t is not changed, the ERROR
condition is raised.
The single statement on-unit, or the
begin block on-unit, is executed as though
it were a procedure (without parameters)
that was called at the point in the program Scope of the ON Statement
at which the interrupt occurred. If the
on-unit is a single statement it behaves as
though it were a single-statement The execution of an ON statement associates
procedure; when execution of the unit is an action specification with the named
complete, control generally returns to the condition. Once this association is
block from which the on-unit was entered. established, it remains until it is
Just as with a procedure, control may be overridden or until termination of the
transferred out of an on-unit by a GO TO block in which the ON statement is
statement; in this case, control is executed.
transferred to the point specified in the
GO TO, and a normal return does not occur. An established interrupt action passes
from a block to any block it activates, and
Note: The specific pOint to which control the action remains in force for a11
returns from an on-unit varies for subsequently activated blocks unless it is
different conditions. In some cases, it overridden by the execution of another ON
returns to the point that immediately statement for the same condition. If i t is
follows the action in which the condition overridden, the new action remains in force
arose, or the statement following the one only until that block is terminated or
in which the condition was raised. In until a REVERT statement is executed for
other cases, control returns to the actual the condition. When control returns to the
point of interrupt, and the action is activating block, all established interrupt
reattempted. An example of the latt·er case actions that existed at that point are re-
is the return from the on-unit of an ON established. This makes it impossible for
CONVERSION statement. When an interrupt a subroutine to alter the interrupt action
occurs as the result of a conversion error, estab1ished for the block that invoked the
control returns from the on-unit to subroutine.
reattempt conversion of the character that
caused the error (on the assumption that If more than one ON statement for the
the invalid character has been changed same condition appears in the same block,
during execution of the on-unit). If the each subsequently executed ON statement
invalid character is not changed, the ERROR permanently overrides the previously
condition is raised. established condition. No re-establishment
is pOSSible, except through execution of
another ON statement with an identical
action specification (or re-execution,
Null On-Unit through some transfer of control, of an
overridden ON statement).

A special case of an on-unit is the null

statement. The effect of this is the same
as a normal return from a begin-block on- Dynamically Descendant On-Units
unit, except that with the CONVERSION and
AREA conditions, there is nO retry.
It is possible to raise a condition during
Use of the null on-unit is not the same execution of an on-unit and enter a further
as disabling, for two reasons: first, a on-unit. An on-unit entered due to a
null on-unit may be specified for any condition either raised or signalled in
condition, but not all conditions can be another on-unit is a dynamically-descendant
disabled; and, second, disabling a on-unit. A normal return from a
condition, if possible, may save time by dynamically-descendant on-unit
avoiding any checking for this condition. reestablishes the environment of the on-
If a null on-unit is specified, the system unit in which the condition was raised.
must still check for occurrence of the
condition; the action then taken is the
action that would be taken on normal return
from an on-unit. On-units for File Parameters and File
Variables
Note: A null on-unit for the CONVERSION
condition will not cause a permanent loop
if a conversion error occurs, because no File constants or file variables used as
conversion is re-attempted unless the arguments and parameters can be specified

Chapter 14: Exceptional Condition Handling and Program Checkout 219

in input or output condition on-units. The F2 to be entered.
following examples illustrate the rules and
uses of this facility: 3. If a REVERT statement for a particular
condition that specifies a file
1. On-units for a particular condition in parameter is executed, anyon-unit
separate blocks can specify different previously established for the
file identifiers for the same file. argument corresponding to the file
parameter is entered.
For example:
For example:
E: PROCEDURE;
DECLARE Fl FILE; E: PROCEDURE;
ON ENDFILE (Fl) GOTO Ll; DCL Fl FILE:
CALL El (Fl); ON ENDFILE (F1):
CALL El (Fl);

El: PROCEDURE (F2);

DECLARE F2 FILE; El: PROCEDURE (F2);
ON ENDFILE (F2l' GO TO L2: DECLARE F2 FILE;
READ FILE (Fl); ON ENDFILE (F2) GOTO L;
READ FILE (F2);
END El;

An end-of-file encountered for Fl in REVERT ENDFILE (F2);

El causes the on-unit for F2 in El to /*NULL ON-UNIT IN E ASSOCIATED
be entered. If the on-unit in El were WITH ENDFILE INTERRUPI'S FOR F2*/
not specified, an end-of-file READ FILE (F2) INTO (Xl);
condition encountered for either Fl or
F2 would cause entry to the on-unit
for Fl in E.
END E;
2. On-units for a particular input or
output condition in the same block can An end-of-fi1e condition encountered
specify different file identifiers for in the execution of the READ statement
the same file. The presence of a for F2 does not cause the on-unit for
second on-unit overrides the first. F2 in El to be entered. Because of
REVERT statement the on-unit for Fl in
For example: the containing procedure is entered.

E: PROCEDURE; Whenever a file variable is used, the

DECLARE Fl FILE; effect is the same as if the current file-
CALL El (F1); constant value of the variable had been
used. Thus having an ON statement which
SPecifies a file variable refers to the
file constant that is the current value of
the variable when the on-unit is
El: PROCEDURE (F2); established.
DECLARE F2 FILE;
ON ENDFILE (F1) GOTO L1; For example:
READ FILE (F1) INTO (Xl);
DECLARE FV FILE VARIABLE,
FCl FILE,
FC2 FILE;
ON ENDFILE (F2) GOTO L2: FV = FC1;
READ FILE (F2) INTO (X2); ON ENDFILE(FV) GO TO FIN;

READ FILE (Fl) INTO (X3); FV = FC2;

READ FILE(FC1) INTO (Xl);
READ FILE(FV) INTO (X2);

END E: An end-of-file condition raised during the

first READ statement will cause the on-unit
An end-of-fi1e condition raised by to be entered, since the on-unit refers to
execution of the second READ FILE file FC1. If the condition is raised in
(Fl); statement causes the on-unit for the second READ statement, however, the on-

220 as PL/I CKT AND OPT LRM PART I

unit is not entered, since this READ refers CONDITION Condition
to file FC2.

If an ON statement specifying a file The ON-condition of the form:

variable is executed more than once, and
the variable has a different value each CONDITION (identifier)
time, then a different on-unit will be
established at each execution. For allows a programmer to establish an on-unit
example. that will be executed whenever a SIGNAL
statement is executed specifying CONDITION
DECLARE FV FILE VARIABLE, and that identifier.
FC1 FILE,
FC2 FILE; As a debugging aid, this condition can
be used to establish an on-unit whose
execution results in printing information
that shows the current status of the
DO FV=FC1,FC2; program. The advantage of using this
ON ENDFILE(FV) GO TO FIN; technique is that the statements of the on-
END; unit need be written only once. They can
be executed from any point in the program
through placement of a SIGNAL statement.
Following is an example of how the
CONDITION condition might be included in a
program:
REVERT statement
ON CONDITION (TEST) BEGIN;

The REVERT statement is used to cancel the

action specification of all the ON
statements for the named condition that END;
have been executed in the same block in
which the REVERT statement is executed. It Execution of the begin block would be
then re-establishes the action that was in caused wherever the following statement
force at the time of activation of that appears:
block. This statement has tne form:
SIGNAL CONDITION (TEST);
REVERT condition-name;
The identifier can be declared
A REVERT statement that is executed in a contextually (as in the example given
block in which no on-unit has been above) or explicitly. An explicit
established for the named condition is declaration of a condition name could be as
treated as a null statement. follows:

DCL CNAME CONDITION;

ON CONDITION(CNAME) BEGIN;

SIGNAL statement

END;
The programmer may simulate the occurrence
of an ON condition by means of the SIGNAL The CONDITION condition is always
statement. An interrupt will occur unless enabled, but it can be raised only by the
the named condition is disabled. This SIGNAL statement.
statement has the form:

SIGNAL condition-name;
CHECK Condition
The SIGNAL statement causes execution of
the interrupt action currently established
for the specified condition. The principal The CHECK condition is an important tool
use of this statement is in program provided in PL/I for program testing. It
checking, to test the action of an on-unit, is raised during execution of the program
and to determine that the correct action is whenever the value of a deSignated variable
associated with the condition. is mOdified, or whenever control is
transferred to a statement prefixed by a
If the signaled condition is not deSignated label or entry constant.
enabled, the SIGNAL statement is treated as Variables, label constants, and entry
a null statement. constants for which the CHECK condition is

Chapter 14: Exceptional Condition Handling and Program Checkout 221

to be raised are designated explicitly in user all the facilities of PL/I, including
an optional name list given with the CHECK the simplicity of data-directed output for
prefix that enables the CHECK condition. controlling and editing his debugging
If the CHECK prefix is given without the information.
name list, all variables, label constants,
and entry constants that are within the
scope of the CHECK prefix can cause the
CHECK condition to be raised. Variables SIZE condition
that can raise the CHECK condition include
array and structure variables, label
variables, entry variables, event The SIZE condition is not enabled unless it
variables, area variables, file variables, appears in a condition prefix. It is
task variables, based and defined raised it high-order significant digits are
variables, and locator variables. lost from an arithmetic value during
subscripted and locator-qualified names are assignment to a variable or cornpiler-
not allowed but qualified names (i.e., created intermediate storage location, or
members of structures) can be used. iSUB- in an input/output operation. An error
defined variables are not allowed. message is printed, and the ERROR condition
is raised; in the absence of an appropriate
The interrupt occurs immediately after on-unit, this leads to termination of the
assignment to the variable being checked. task. The checkout compiler will detect a
An interrupt will take place, for instance, SIZE error and take standard system action
after the assignment of each element of a whether or not the condition is enabled,
checked array. Exceptions are as follows. although a SIZE on-unit can be entered only
when the condition has been enabled.
1. If arguments specified in a CALL
statement are being passed directly
(as opposed to being passed by means
of dummy arguments), then CHECK for SUBSCRIPTRANGE Condition
these names is raised on return from
the subroutine.
Another ON condition that is used
2. With label and entry constants, the prinCipally for program checkout, but that
interrupt occurs immediately before may also be used in production, is
the execution of the statement or the SUBSCRIPTRANGE. For the optimizing
invocation of the entry name. compiler, the condition needs to be enabled
by a condition prefix. The checkout
The system action for problem variables is compiler will detect a SUBSCRIPTRANGE error
to print the identifier causing the and take standard system action, whether or
interrupt and its new value in the form of not the condition is enabled, although a
data-directed output. For program control SUBSCRIPTRANGE on-unit can be entered only
variables, the information provided is: when the condition has been enabled.

Checkout compiler: As for PUT DATA Since this checking involves a

substantial overhead in both storage space
Optimizing compiler: Name of the and execution time, it usually is used only
identifier in program testing - it is removed for
production programs, SUBSCRIPTRANGE being a
If the CHECK condition is raised by a normally-disabled condition.
SIGNAL CHECK, the standard system action is
to print the identifiers (and their values,
where applicable) given in the name list of
the CHECK prefix. If the CHECK prefix does STRINGRANGE Condition
not have a name list, the standard action
is to print all the identifiers (and their
values, where applicable), that are within The STRINGRANGE condition is not enabled
the scope of the CHECK prefix. unless it appears in a condition prefix.
It is raised by an invalid reference to the
Thus, by preceding a block with a CHECK SUBSTR built-in function and
prefix, as shown in the example in figure pseudovariable, the arguments to which must
14.1, the programmer can obtain selective lie within certain bounds (see "SUBSTR
dumps in a readable format by specifying String Built-in Function" in section G,
variables; he can obtain a flow trace by ·Built-in Functions and pseudovariables·).
specifying labels and entry names. It allows execution to continue with a
SUBSTR reference that has been revised
The CHECK condition may also be either automatically (that is, by standard
specified in an ON statement, if other than system action) or by the programmer using
system action is required. This gives the an on-unit. The checkout compiler will

222 OS PL/I CKT AND OPT LRM PART I

detect a STRINGRANGE error and take out of range, the sample is ignored. If
standard system action whether or not the there is more than one subscript error or
condition has been enabled, although a more than one conversion error in a batch,
STRINGRANGE on-unit can be entered only that batch is then ignored.
when the condition has been enabled.
The numbers to the right of each line
are card sequence numbers, which are not
part of the program itself.
Condition Built-In Functions and
Condition Codes The CHECK prefixes in cards 1 and 25 are
included to help with debugging: in a
production program, they would be removed.
When an on-unit is invoked, it is as if it The prefix in card 1 specifies that
were a procedure without arguments. It is interrupts will occur at the following
therefore impossible to pass to the on-unit times: just before the statements HEADER,
any information about the interrupt (other NEWBATCH, and BADBATCH are executed: just
than the name of the condition). To assist before the procedure INPUT is invoked: and
the programmer in making use of on-units, whenever the value of an element of the
some special functions are provided that variable SAMPLE changes. Since no ON
may be used to inquire about the cause of statement has been executed for the CHECK
an interrupt and possibly to attempt to condition, system action is performed.
correct the error. This will result in the appropriate name
being written on SYSPRINT (together with
These condition built-in functions can the new value in the case of SAMPLE).
be used only in on-units or in blocks
invoked by on-units. They are listed in Since the labels used within the
section G, WBuilt-In functions and internal procedure INPUT are not known in
Pseudovariables w • DIST, they cannot be specified in a CHECK
list for DIST. A separate CHECK prefix is
The condition built-in functions provide therefore inserted just before the
information such as the name of the procedure statement heading INPUT. This
procedure in which the interrupt occurred, check list specifies the labels in INPUT,
the character or character string that and the array TABLE.
caused a conversion interrupt, the value of
the key used in the last record The first statement executed is the ON
transmitted, and so on. Some can be used ENDFILE statement in card 9. This
as pseudovariables for error correction. specifies that the external procedure
SUMMARY is to be called when an ENDFILE
The ONCODE function provides a binary interrupt occurs. This action applies
integer whose value depends on the cause of within DIST and within INPUT and within all
the last interrupt. This function, used in other procedures called by DIST, unless
conjunction with the ERROR condition, they establish their own action for
allows the programmer to deal with errors ENDFILE.
that may be detected by the implementation,
but that are not represented by condition Throughout the procedure, any conditions
names in the language. It can also be used except SIZE, SUBSCRIPTRANGE, STRINGRANGE,
to distinguish between the various STRINGSIZE, and CHECK are enabled by
circumstances under which a particular default: and for all conditions except
condition (for instance the KEY condition) those mentioned explicitly in ON
can be raised. statements, the system action applies.
This system action, in most cases, is to
generate a message and then to raise the
ERROR condition. The action specified for
Example of Use of ON-Conditions the ERROR condition in card 13 is to
display the contents of the card being
processed. When the ERROR action is
The routine shown in figure 14.1 completed, the FINISH condition is raised,
illustrates the use of the ON statement, and execution of the program is
the SIGNAL and REVERT statements, and subsequently terminated.
condition prefixes. The routine reads
batches of cards containing test readings. The statement in card 10 specifies
Each batch has a header card with a sample action to be taken whenever a CONVERSION
number, called SNO, of zero and a trailer interrupt occurs. Since this action
card with SNO equal to 9999. If a consists of more than one statement, it is
conversion error is found, one retry is bracketed by BEGIN and END statements.
attempted with the error character set to
zero. Two data fields are used to The main loop of the program starts with
calculate a subscript; if the subscript is the statement HEADER. Since the CHECK

Chapter 14: Exceptional Condition Handling and Program Checkout 223

r---------------------------------------------------------------------------------------,
(CHECK(HEADER,NEWBATCH,INPUT,BADBATCH,SAMPLE»: /*DEBUG*/ 01
DIST: PROCEDURE; 02
DECLARE 1 SAMPLE EXTERNAL, 03
2 BATCH CHARACTER(6), 04
2 SNO PICTURE '9999·, 05
2 READINGS CHARACTER(70), 06
TABLE(15,15) EXTERNAL, (ONCHAR,ONCODE) BUILTIN
/* ESTABLISH INTERRUPT ACTIONS FOR ENDFILE & CONVERSION */ 08
ON ENDFILE (PDATA) CALL SUMMARY; 09
ON CONVERSION BEGIN; CALL SKIPBCH; 10
GO TO NEWBATCH; 11
END; 12
ON ERROR DISPLAYCBATCHIISNOIIREADINGS); 13
/* MAIN LOOP TO PROCESS HEADER & TABLE */ 14
HEADER: READ INTO (SAMPLE) FILE (PDATA); 15
/* CHECK ACTION LISTS INPUT DATA FOR DEBUG */ 16
IF SNO 1 = 0 THEN SIGNAL CONVERSION; 17
NEWBATCH: GET LIST (OMIN,OINT,~N,AINT) STRING (READINGS); 18
TABLE = 0; 19
CALL INPUT; 20
CALL PROCESS; 21
GO TO HEADER; 22
/* ERROR RETURN FROM INPUT */ 23
BADBATCH: SIGNAL CONVERSION; 24
(CHECK(IN1,IN2,ERR2,ERR1,TABLE»: /*DEBUG*/ 25
INPUT: PROCEDURE; 26
/* ESTABLISH INTERRUPT ACTIONS FOR CONVERSION , SUBRG */ 27
ON CONVERSION BEGIN; 28
IF ON CODE = 624 , ONCHAR = , , 29
THEN DO; ONCRAR = '0': 30
GO TO ERR1; 31
END; 32
ELSE GO TO BADBATCH; 33
END; 34
ON SUBSCRIPTRANGE GO TO ERR2; 35
/* LOOP TO READ SAMPLE DATA AND ENTER IN TABLE */ 36
IN1: READ INTO (SAMPLE) FILE (PDATA); 37
IF SNO = 9999 THEN RETURN; /*TRAILER CARD*/ 38
IN2: GET EDIT (R,OMEGA,ALPHA) (3 P'999') 39
STRING (READINGS): 40
(SUBSCRIPTRANGE): TABLE ( (OMEGA-OMIN)/OINT, (ALPHA-AMIN)/AINT) = R: 41
GO TO IN1; 42
/* FIRST CONVERSION , SUBSCRIPTRANGE ERROR IN THIS BATCH */ 43
ERR2: ON SUBSCRIPTRANGE GO TO BADBATCB: /*FOR NEXT ERROR*/ 44
CALL ERRMESS(SAMPLE,02); 45
GO TO IN1; 46
ERR1: REVERT CONVERSION: /*SWITCB FOR NEXT ERROR*/ 41
CALL ERRMESS (SAMPLE, 01) ; 48
GO TO IN2: 49
END INPUT: 50
END DIST: 51
L---------------------------------------------------------------------------------------J
Figure 14.1. A program checkout routine

condition is enabled for HEADER, an block. which in turn calls a procedure (not
interrupt will occur before HEADER is shown here) that reads on, ignoring cards
executed. The READ statement with the INTO until it reaches a header card. The begin
option will cause a CHECK condition to be block ends with a GO TO statement that
raised for each element of the variable terminates the on-unit.
SAMPLE; consequently, the input is listed
in the form of data-directed output. The GET statement labeled NEWBATCH uses
the STRING option to get the different test
The card read is assumed to be a header numbers that have been read into the
card. If it is not, the SIGNAL CONVERSION character string READINGS, which is an
statement causes execution of the BEGIN element of SAMPLE. Since the variables

224 OS PL/I CKT AND OPT LRM PART I

named in the data list are not explicitly interrupt does occur, the on-unit causes a
declared, their appearance causes implicit transfer to ERR2, which establishes a new
declaration with the attributes FLOAT on-unit for SUBSCRIPTRANGE interrupts,
DECIMAL (6). overriding the action specified in the ON
statement in card 35. Any subs equent
The array TABLE is initialized to zero subscript errors in this batch will,
before the procedure INPUT is called. This therefore, cause control to go to BADBATCH,
procedure inherits the on-units already which signals the CONVERSION condition as
established in DIST, but it can override it existed in the procedure DIST. Note
them. that on leaving INPUT, the on-action
reverts to that established in DIST, which
The first statement of INPUT establishes ~n this case calls SKIPBCH to get to the
a new action for CONVERSION interrupts. next header card.
Whenever an interrupt occurs, the ONCODE is
tested to check that the interrupt is due
to an illegal P format input character and After establishment of a new on-unit, a
that the illegal character is a blank. If message is printed, and a new sample card
the illegal character is a blank, it is is read.
replaced by a zero, and control is
transferred to ERR1. . The statement labeled INl reads an 80-
column card image into the structure
ERRl is internal to the procedure INPUT. SAMPLE. A READ statement does not cause
The statement, REVERT CONVERSION, nullifies input data to be checked for validity, so
the ON CONVERSION statement executed in the CONVERSION condition cannot arise.
INPUT and restores the action specified for
conversion interrupts in DIST (which causes The statement IN2 checks and edits the
the batch to be ignored). data in card columns 11 through 19
according to the picture format item. A
After a routine is called to write an non-numeric character (including blank) in
error message, control goes to IN2, which these columns will cause a conversion
retries the conversion. If another interrupt, with the results discussed
conversion error occurs, the interrupt above.
action is that specified in cards 10 and
11. The next statement (card 41) has a
SUBSCRIPTRANGE prefix. The data just read
The second ON statement in INPUT is used to calculate a double subscript.
establishes the action for a SUBSCRIPTRANGE If either subscript falls outside the
interrupt. This condition must be bounds declared for TABLE, an interrupt
explicitly enabled by a SUBSCRIPTRANGE occurs. If both fall outside the range,
prefix for an interrupt to occur. If an two interrupts occur.

Chapter 14: Exceptional Condition Handling and Program Checkout 225

Chapter IS: Execution-Time Facllities of the Checkout Compiler

This chapter describes language features The extent to which these facilities are
which can provide various facilities to applicable to a particular program depends
help the programmer at execution time. on the processing mode:
These features are implemented by the- PL/I
checkout compiler only. If they are 1. Batch processing:
included in a source program to be
processed by the PL/I optimizing compiler, The programmer does not control the
they are checked for correct syntax and time at which execution begins, and
then ignored; their presence in such a cannot intervene during execution to
program is not regarded as an error. initiate a trace or a current-status
list, or to modify his program. If a
trace or a current-status list is
In order that the working time of both required, the appropriate statements
the programmer and the computer shall be must have been included in the source
used with the maximum efficiency, it is program. output from these facilities
essential that program turnaround should be is not avai~able until execution has
as rapid as possible. The most important terminated.
way of achieving this, as far as the
programmer is concerned, is to reduce the 2. Conversational processing:
time he spends finding out how well his
program works, and to allow him to correct The programmer initiates execution of
any syntactic or logical errors with the his program at the terminal and can
minimum delay. The PL/I checkout compiler intervene during execution to initiate
supports this aim by providing execution- a trace or a current-status list, or
time facilities that: to modify his program. statements to
initiate a trace or status-list can
1. Provide the programmer with also be included in the source
information about designated items. program. output from these facilities
This information comprises: is immediately available and can be
printed at the terminal.
a. A trace of the items, that is,
information is put out whenever If the SYSPRINT file is associated
these items are referenced in pre- with a device other than the
defined situations throughout programmer's terminal, some of
execution. SYSPRINT output will appear on both
devices. That part of the SYSPRINT
b. A list showing the current status output which is not normally available
of the designated items at any at the terminal can be copied onto it
specified point during execution. by means of the appropriate terminal
instruction.
The items to be traced or listed, and
the points at which this output Conversational processing requires a
occurs, are specified by statements in keybOard terminal as the input/output
the source program. The pre-defined device. This enables the programmer to:
situations are specified in the
language. 1. Transmit and receive data at a rate
fast enough to allow him to maintain a
2. Allow the programmer to initiate the train of thought, and
trace dynamically.
2. Have control passed to him at the
3. Provide hi~ with the opportunity, in termin~l, or obtain it by calling
the appropriate processing attention from the terminal.
environment, for amending his program.
Changes made to the existing program processing at the terminal is performed
can be temporary, Or they can be in immediate mode, that is, any instruction
incorporated automatically into the entered can be executed immedi~tely. If a
current source program. The current permitted PL/I statement or statement group
source program can be saved on an is entered, it can be translated and
external data set and can be interpreted (executed) immediately.
retranslated at any time without
leaving the checkout compiler PL/I includes statements and options
environment. that support these facilities. These

Chapter 15: Execution-time Facilities of the Checkout Compiler 227

provide: condition and terminate the task
or, if the condition is raised in
1. Tracing facilities: the major task, terminate the
program. (Note that the raising
Information about designated items can of the ERROR and FINISH conditions
be written on the SYSPRINT file. for the checkout compiler may be
controlled by the ERRORS compiler
2. Current status list: option, described in the
programmer's guide.)
The current status of problem data or
program-control data can be written on In conversational processing, if
the SYSPRINT file. the ERROR condition is raised, the
standard system action is to pass
3. Program amending: control to the terminal.

Extra PL/I statements can be included d. FINISH condition: In batch

in the program during execution. processing, the standard system
Depending on the subcommands used, action in the absence of an on-
such statements may take effect once, unit is simply to continue
or for the remainder of the execution, processing from the point where
or they may be incorporated into the the interruption occurred.
current source program. Such changes
as are thus incorporated become In conversational processing, the
permanent if the current source standard system action is to pass
program is saved on an external data control to the terminal.
set.
3. There are a few PL/I statements that
Note the relationship of PL/I and the cannot be used in immediate mode;
processing mode: these are described in the section
"Program Amending," below.
1. Any statement in a PL/I source program
submitted for batch processing can
also be included in a source program
submitted for conversational Tracing Facilities
processing, and vice versa.

2. There are some language items that The tracing mechanism is activated by the
have or can have a different usage in following statements:
batch processing from that in
conversational processing. They are: Item or feature Statements

a. GO TO statement: In batch Data CHECK/NOCHECK

processing, control is transferred Transfer of control FLOW/NOFLOW
to a statement identified by a
label. In conversational
processing, control can be
transferred to a statement CHECK and NOCHECK Statements
identified by either a label or,
in a GO TO statement entered in
immediate mode, a number. The A CHECK statement provides, for every
number is the number of a statement that comes within its range,
statement in either the current or dynamic enabling of the CHECK condition.
the immediate source porgram, that As a result, the standard system action for
is, a number, or a number followed the CHECK condition can be taken for these
by -T". statements; this action provides that
information is written, on the SYSPRINT
b. HALT statement: In batch file, about the names specified or assumed
processing, this statement is a in the prefix whenever these names appear
null operation. In conversational in pre-defined situations during program
processing, this statement causes execution. If an on-unit has been
execution of the current task to established for the CHECK condition the on-
be suspended and control passed to unit is executed and standard system action
the terminal. is not performed.

c. ERROR condition: In batch A CHECK statement can specify a list of

processing, if the ERROR condition names. If it has such a list, the CHECK
is raised, the standard system condition is enabled for the specified
action is to raise the FINISH names only. If it does not have a list,

228 OS PL/I CKT AND OPT LRM PART I

the CHECK condition is enabled for all the the names A, B, C, and D as members of the
names ~n the program. name list.

A CHECK statement remains effective The first NOCHECK statement deletes A

until the program terminates or an and D from this list; after this pOint, the
appropriate NOCHECK statement is executed. CHECK condition is raised for Band Conly.
The NOCHECK statement suppresses the CHECK
condition for specified or assumed names. The second CHECK statement restores D to
If no names are specified in a NOCHECK the name list and adds a new name E, to the
statement, then the CHECK condition is list. After this pOint, the CHECK
suppressed for all names in the program. condition is raised for B, C, 0, and E.
CHECK and NOCHECK statements executed in a
procedure compiled by the checkout compiler The second NOCHECK statement deletes B
have no effect in any procedures compiled and E from the name list. After this
by the optimizer that may form part of the pOint, the CHECK condition is raised for C
same program. and 0 only.

The range of a CHECK or NOCHECK The CHECK and NOCHECK statements

condition statement is: effectively modify actual or inherited
CHECK or NOCHECK prefixes and add CHECK or
1. In the external block that contains NOCHECK prefixes to currently unprefixed
the CHECK or NOCHECK statement: all statements. A statement inherits a prefix
the statements executed after the either from an actual prefix to a PROCEDURE
execution of the CHECK or NOCHECK or BEGIN block or from a previously-
statement. executed CHECK or NOCHECK statement; in
both cases, the CHECK or NOCHECK keyword
In this context, ·contains· means that effectively adds a corresponding prefix to
the CHECK or NOCHECK statement is in every statement within its range. To
the external block or in a block determine the effect of a CHECK or NOCHECK
internal to the external block. statement, carry out, conceptually, the
following steps.
2. In an external, separately compiled
block invoked from a block to which 1. When a CHECK statement without a name-
the CHECK or NOCHECK statement list is executed, delete all actual or
applies: all references to names inherited CHECK and NOCHECK prefixes
associated with the inherited prefixes within its range, then allow every
if these names are known in both the statement within its range to inherit
invoking and the invoked blocks. a CHECK prefix without a name-list.
Thus, when a name in the CHECK or
NOCHECK statement name list appears in 2. When a NOCHECK statement without a
the invoked external procedure, it name-list is executed, delete all
will be within the range of the actual or inherited CHECK and NOCHECK
statement only if it is declared in prefixes within its range.
both procedures to be EXTERNAL.
3. When a CHECK or NOCHECK statement with
The names can be unsubscripted, non- a name-list is executed, carry out the
locator-qualified variables, label following steps on all statements
constants, or entry constants~ within its range.

The effect of the use of both CHECK and a. Delete from all actual or
NOCHECK statements in a program is shown by inherited prefixes (both CHECK and
the following example: NOCHECK) all names that appear in
the CHECK or NOCHECK statement
CHECK (A,B,C,D); name-list (except where the same
name appears in the statement and
the prefix but refers to a
different data item in each case).
NOCBECK (A,D); In both cases, treat a prefix with
no name-list as having a name-list
that includes all known names.

CHECK (D,E); b. If the statement is a CHECK add a

CHECK prefix having the same name-
list to every statement. If the
statement is a NOCHECK, add a
NOCHECK (B,E); NOCHECK prefix having the same
name-list to every statement. In
The first CHECK statement establishes both cases, exclude any names that

Chapter 15: Execution-time Facilities of the Checkout Compiler 229

 are not known at the statement the initialization. Thus in the example
being prefixed. given, CHECK output is never produced
for the variable C because, in the
Note: Before carrying out Cal, expand into example, nO assignment is made to C.
their element names any structure names in Such output would be produced if, for
the CHECK or NOCHECK statement and in any example, the CHECK statement,was
prefixes that may be modified. executed in a block that contained the
procedure PR, or if the procedure PR was
The action of CHECK and NOCHECK invoked recursively. In the latter
statements in combination with prefixes is instance, CHECK output would be produced
illustrated by the following examples. at the second and all succeeding
They show how the effects of prefixes invocations.
written by the programmer are modified by
the execution of a CHECK or NOCHECK BASED or CONTROLLED: When the variable is
statement. allocated by means of an ALLOCATE or
LOCATE statement. CHECK is never raised
Example 1: by the INITIAL attribute of a BASED
variable that is never explicitly
CHECK: /* NAMES CHECKED FOR: */ allocated.

Note: The CHECK condition is never raised

for the initialization of STATIC variables.
CCHECKCA»: ••• : /* ALL
(CHECK(D,E»: •••• :/* ALL
(NOCHECK(A»: •••• i/* ALL
(NOCHECK): •••• : /* ALL
CCHECK): •••• : /* ALL
FLOW Statement
Example 2:

CHECKCA,B,C): /* NAMES CHECKED FOR: The FLOW statement causes information about
the transfer of control during execution of
a task to be written on the SYSPRINT file.
When a FLOW statement has been executed, it
CCHECKCA»: •••• : /* A,B,C remains effective until the task terminates
CCHECK(D,E»: •••• :/* A,B,C,D,E or until a NOFLOW statement is executed in
(NOCHECK(A»: •••• :/* A,B,C the same task. The FLOW statement has no
(NOCHECK): •••. : /* A,B,C effect outside procedures compiled by the
(CHECK): •••• : /* ALL checkout compiler.

Example 3: I When a task is first attached, the

Istatus of the FLOW/NOFLOW statement is the
NOCHECKCC,D): /* NAMES CHECKED FOR: */ Isame as that of the attaching task at the
Ipoint where the CALL statement was
I executed. Thereafter, the status can be
Ichanged only by FLOW and NOFLOW statements
{CHECK{A»: •••• : /* A */ lexecuted within the task.
{CHECK(D,E»: •••• i/* E */
{NOCHECK(A»: •••• :/* NONE */ When a FLOW statement has been executed
(NOCHECK): •••• : /* NONE */ lin or inherited by a task, every transfer
{CHECK): •••• ; /* ALL EXCEPT C,D */ of control that occurs subsequently in that
task causes a flow comment to be put out
The situations in which the CHECK before the transfer takes place. This
condition is raised are described in "CHECK comment consists of:
Condition" in section H, "ON-Conditions."
Some of them are illustrated in figure 1. The number of the statement that
15.1. causes the transfer of control.

The CHECK condition is raised when 2. The number of the statement to which
AUTOMATIC, BASED, or CONTROLLED variables control is transferred.
are initialized by means of the INITIAL
attribute (with or without the CALL
option). If standard system action is While it is always clear why a
taken, CHECK output is produced as follows: particular statement is specified in the
flow comment as the statement that caused
AUTOMATIC: Only if the CHECK statement has the transfer of control, it is not always
been executed before the establishment so obvious why control was transferred to
of the prologue for the block containing the statement given as the destination.

230 OS PL/I CKT AND OPT LRM PART I

 PR:PROC OPTIONSCMAIN):
DCL (A,B) OECIMALCS),
C CHAR(10) INITC'OAILYRATES') AUTO,
Cl CHAR(2S) BASEO(P),
0(10) LABEL,
GENTRY;

.,
CHECK(A,B,C,Cl,O,F,P):

A=l: /*CHECK OUTPUT FOR A*/

B=2: /*CHECK OUTPUT FOR B*/
ALLOCATE Cl: /*CHECK OUTPUT FOR p*/

0(1): READ FILE (X) INTO(Cl): /*CHECK OUTPUT FOR D(l) AND Cl*/

E: GET DATA(A,B): /*CHECK OUTPUT FOR A AND B*/

DISPLAY (C) REPLY(Cl): /*CHECK OUTPUT FOR Cl*/

CALL F (A,B) : /*CHECK OUTPUT FOR F AT TIME OF CALL*/

/*CHECK OUTPUT FOR A, B ON RETURN
FROM F (EVEN IF VALUES OF Y, Z
NOT CHANGED IN F)*/
CALL G:

F: PROC(Y,Z):
DCL (Y,Z) DECIMAL (5)

Y=20:
.,

END F:
END PRj

Notes:

1. If the CHECK statement had been CHECK:, output

would have been as indicated with, in addition,
CHECK output for E, G, and Y.

2. If dummy arguments had been created for A and

B, no CHECK output would have been produced.

Figure 15.1. Example of use of CHECK statement

Chapter 15: Execution-time Facilities of the Checkout Compiler 231

Consider the following program: ON CONVERSION GO TO L12:
statement is counted as one statement.
number

NOFLOW Statement
3 FLOW;
The NOFLOW statement suppresses the action
of a FLOW statement executed earlier in the
12 ON CONVERSION GO TO L12; same task.

24 GO TO L19; Current Status List

Information about selected items in a

35 L12:CALL ABS: program can be put into the output stream
36 ... , by means of a POT statement with one of the
options LIST, DATA, SNAP, FLOW, or ALL.
This information can comprise names and
values of both problem-data and program-
42 x = F(A,B): control variables and details of data
relating to flow of control and ON
conditions. Note that only the PL/I
checkout compiler can provide all this
57 L19:DO I = 1 TO 99: information. The PL/I optimizing compiler
can provide only the names and values of
problem-data variables, and 'the names of
program control variables.
65 END:
66 A = B•• 2: The information provided by the options
specified in the PUT statement is
summarized in figure 15.3.
117 ABS:PROC: Details of the output provided by the
use of each of these options is given in
the sections below.
124 RETURN:
PUT Variables
130 END ABS:
The data list for the LIST and DATA options
can specify both problem and program-
control variables. Only problem variables
150 SIGNAL CONVERSION: can be specified in an EDIT data list. If
DATA is specified without a data list, the
data is assumed to be all problem and
program-control variables known in the
192 F:PROC(Y,Z) RETURNS(DECIMAL): block.
The information provided for the problem
variables specified or assumed depends on
197 RETURN eM): the data-transmission option selected:
198 END Fi
Option output
In this program, the statement numbers in LIST Value
the flow comments produced by transfers of
control are shown in figure 15.2. DATA Name of variable, and value
Statement numbers are derived from a EDIT Value as specified
count of semicolons, for both simple and
compound statements. In the example above, If a variable specified or assumed for a

232 OS PL/I CRT AND OPT LRM PART I

r---------------------------------------------------------------------------------------,
statement 1 Transferred from I Transferred to I
---------------------------------------------------------------------------------------1
GO TO in on-unit I 12 I 35 I
---------------------------------------------------------------------------------------1
I I 1
GO TO I 24 1 57 I
---------------------------------------------------------------------------------------
CALL 35 I 117
FUnction reference I 42 192
---------------------------------------------------------------------------------------
DO 1 57 IWhen iteration is complete,
I Istatement number of statement
I lafter matching END statement,
I Ithat is, 66
END for iterative DO 65 1 57
---------------------------------------------------------------------------------------
RETURN in 124 I 35
procedure invoked I
by CALL 1
---------------------------------------------------------------------------------------
END in procedure 1 130 I 35
invoked by CALL I 1
---------------------------------------------------------------------------------------
SIGNAL I 150 12

RETURN in 197 42
procedure invoked
as function reference 1 I
L---------------------------------------------------------------------------------------J
Figure 15.2. Flow comments produced by various transfers of control

r---------------------------------------------------------------------------------------,
Option 1 Intormation 1
---------------------------------------------------------------------------------------1
[LIST] (data-list) 1Variables I
DATA [(data-list)] 1 1
EDIT (data-list) (format-list) 1 1
[(data-list) (format-list»)... 1 I
---------------------------------------------------------------------------------------1
SNAP IActive blocks and on-units I
---------------------------------------------------------------------------------------1
FLOW(n)] ILast n transfers of control I
---------------------------------------------------------------------------------------1
ALL[(character-string-expression)] IVariables, active blocks and on-units, 1
Itransfers of control, ON built-in functions 1
L---------------------------------------------------------------------------------------J
Figure 15.3. Program information provided by the PUT statement options

PUT DATA statement is not initialized or is the output for a progra~control variable
not allocated, the checkout compiler comprises information re1ated to the
includes a comment to this effect in the current situation of the variable. For
output. example, the output for a file variable
states whether the file is open or closed,
The information provided for a program- and the output for an event variable states
control variable specified or assumed in a whether the event is active or inactive.
PUT LIST or POT DATA statement depends on
the variable. The name of the variable is Onder the optimizing compiler a POT DATA
put out only if DATA (with or without a statement specifying a program control
data list) is specified. A progra~control variable will cause only the name of the
variable does not have a value in the sense variable to be printed. A PUT LIST or PUT
that a problem variable has one. Instead, EDIT statement must not specify program

Chapter 15: Execution-time Facilities of the Checkout compiler 233

control data under the optimizing compiler. ENVIRONMENT attribute
Number of records transmitted
The value output for each type of If the file is a STREAM file:
program-control variable is: Already-transmitted items in the current
record
AREA
Area size LABEL If variable has valid label constant
Area extent value
List of freed allocations within the Label constant assigned to the variable
extent Statement number
If the label constant is in a procedure
ENTRY that is not the current procedure: A
Entry constant assigned to the variable list of the currently active
(if any)