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) procedures invoked in the process
If the entry constant is internal and is of activating the block containing
in a procedure that is not the current the label constant. If the list of
procedure: active blocks cannot be produced,
statement number because the label variable nO
A list of the currently active longer has a valid value, a comment
procedures invoked in the process of to this effect is made.
activating the block containing the If label variable does not have a valid
entry constant. If the list of active value:
blocks cannot be produced, because the Comment to this effect
entry variable no longer has a valid
value, a comment to this effect is Note: Label variables can be initialized
made. without having constants aSSigned to
them. In the program:
Note: The above output is provided by a
PUT DATA statement specifying any DeL L(3) LABEL;
entry variable or a PUT LIST statement
specifying an entry variable that has
been declared as having a non-null
argument list. If a PUT LIST L(l): ••• ;
statement specifies an entry variable
that has been declared as not
requiring an argument list, the entry
is invoked. In such a case, only PUT
DATA may be used to put out the value L(l) has a value and can appear in a
of the entry variable. GO TO statement; but it is not a label
constant. In this case, the full
EVENT output for a label variable with a
Description of the event: label constant value is transmitted,
Task or I/O event except for the label constant value
Active or inactive itself.
Complete or incomplete
status OFFSET
If the event is active: Whether the offset has a null value
Indication of whether task or I/O event If the offset is not null and the long
Absolute priority form of the offset variable is used:
If a task event: Name of the based variable addressed by
Entry name specified in the CALL the offset
statement that activated the event Name of the area, and value (in bytes)
variable of the offset
Statement number of this CALL Whether it is invalid; for example,
statement because the based variable previously
If an I/O event associated with it had been freed
File name or 'DISPLAY' If the offset is not null and the short
Statement number of I/O statement that form of the offset is used:
activated the event variable The byte-address value of the offset
statement numbers of the WAIT
statements associated with this event POINTER
Whether the pointer has a null value
FILE (variable or constant) If the pOinter is not null and the long
If item is a variable: form of pOinter is used:
File constant aSSigned to variable Name of the based variable addressed by
Whether the file is open or closed the pOinter
If the file is open: If the last value assigned to the pOinter
List of attributes other than the is the value of an offset:

23q OS PL/I CKT AND OPT LRM PART I

r-----------------------------------------,
I r---
statement)
Whether i t is invalid: for example,
1.. Current I because the based variable previously
task 1. SNAP information associated with it has been freed
2. FLOW information If the painter is not null and the short
3. Condition built-in form of pOinter is used:
functions The byte-address of the painter
4. Currentr---
block 11. Entry name TASK
12. Condition Description of the task:
I status Active or inactive
I 3 • Variables Absolute priority
L--- If the task is active:
r--- Entry name specified in the CALL
5. Block 11. As for statement that activated the task
that 12. current variable
invoked I 3. block Statement number of this CALL statement
current L - - -
block
r---
6. Block 1 PUT SNAP Statement
that 11. As for
invoked I 2. current
above 13. block The PUT statement with the SNAP option
block 1 causes the following data to be put into
L--- the stream:
etc, to initially-
invoked procedure of 1. The current statement number.
task
L--- 2. A list of the currently active blocks
r--- and on-units invoked in the process of
2. Highest 1 activating the block in which the PUT
priority 11. As for current statement was executed. Routines
task 12. task, with item compiled by the optimizing compiler,
(excl. 14. 4 being the and FORTRAN and COBOL routines, are
current 15. latest block in included in the list.
task) 16. the chain of
I etc invocation.
L---
r---
3. Next 11. As for current PUT FLOW Statement
highest 12. task, with item
priority 14 • 4 being the
task 15. latest block in The PUT statement with the FLOW option
(excl. 16. the chain of causes a list of the last n transfers of
current I etc invocation. control to be put into the-stream. In each
task) I transfer of control, the statements
1 L--- involved are:
letc., to lowest priority task
L-----------------------------------------J 1. The statement that caused the transfer
of control.
Figure 15.4. Information transmitted
by POT ALL statement 2. The statement to which control is
transferred.
Name of the area, and value (in bytes)
of ,the offset The rules for identifying these statements
(Except that if the area is based or is an are the same as for the FLOW statement.
ele"ment of an array of areas, the value of The value of n is any value specified by
the offset is not transmitted: and if the the programmer; it may be specified in the
area is an element of a based structure, PUT FLOW statement or in the appropriate
n~ither the offset nor the name of the area compiler option. If there are conflicting
is transmitted.) values for n in the PUT statement and the
If the last usage of the pOinter was in a compiler option, the smaller is used. If
READ ••• SET or a LOCATE statement: no value is given in either place, then a
Name of the file default of 25 is assumed.
Record number of the record with which
the pointer is associated Name of Under the optimizing compiler, the syntax
based variable (if a LOCATE of a PUT FLOW statement is checked, then it

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

is ignored. A PUT FLOW statement has nO However, if a variable is based and
effect outside procedures compiled by the the based option for the variable is
checkout compiler. anything other than an unsubscripted
automatic or static pointer or offset,
for example based(expression) or
based(based-pointer), the data for
this item will not be accessed and a
PUT ALL statement comment to this effect will appear in
the output. This is because the
compiler tries to avoid errors
The PUT ALL statement provides the maximum occurring during a PUT ALL statement.
amount of debugging information obtainable
without a dump of main storage. Options
may be specified to select a part only of The options are specified as a character
the total information available. string following the ALL option. The full
list of options is as follows.
The information transmitted by PUT ALL
with no options is as shown in figure 15.4.
The content of each item is as follows. PUT ALL ('DSFCTn' )

SNAP information: The information provided where n is a number 1 through 9999. Any or
by a PUT SNAP statement. In a all of the options may be specified
multitasking program, the chain of together.
invocation is followed back through
all attaching tasks to the main When one or more of the options is
procedure of the program. specified, SNAP and FLOW information is
given for each task for which other
FLOW information: The information provided information is transmitted, except that i t
by a PUT FLOW statement without a is always omitted for the current task.
number-of-statements option. The other information is transmitted if one
or more of the options 0, S, F, or C is
Condition built-in functions: Values of specified. The information is given for
the following built-in functions in all tasks and blocks unless limited by one
data-directed format. or both of the options T and n.

DATAFIELD The meaning of each option is as

ONCBAR follows.
ONCODE
ONCOUNT 0: Values of problem and program control
ONFILE variables, as defined under "Variables"
ONKEY above, are transmitted. Values of file
ONLOC constants are not transmitted.
ONSOURCE
S: The same meaning as 0, except that
This information is given for the array variables are not transmitted.
current task only, because the values
of the built-in functions are no F: Values of file constants are
different in the contexts of other transmitted.
tasks.
Entry name: The name of the entry pOint C: Values of the condition built-in
through which the procedure was functions and the condition status of
entered on its current invocation. each block are transmitted.
This is the same as the corresponding
name in the SNAP information. T: Limits the output to the current task.

Condition status: For each PL/I on- n: Limits the output to this number of
condition: blocks.

Whether i t is enabled. The options 0 and S conflict. There is

also a conflict if two or more numbers
Variables: The value of every problem data corresponding to two values of n appear in
and program control variable and every the string. In these cases, the option
file constant declared in that block, specified latest in the string overrides
in data-directed format. controlled any earlier conflicting option.
variables have every generation
transmitted, starting with the latest. Under the optimizing compiler, the syntax
If a variable is uninitialized or of the POT ALL statement is checked, then
unallocated a comment is printed. i t is ignored.

236 OS PL/I CKT AND OPT LRM PART I

Program Amending and their usage are given in the CMS and
TSO User's Guides for the checkout
compiler.
When processing in conversational mode, the
programmer can suspend program execution The extra PL/I statements are always
and obtain control at the terminal. He executed in immediate mode; this applies
does this by striking the appropriate key whether they are inserted while the
at the terminal. This raises the ATTENTION programmer has control at the terminal or
condition, which causes processing to be whether he has used a terminal command to
interrupted, and in the absence of an cause them to be inserted at a specified
ATTENTION on-unit, control to be passed to pOint once program execution has been
the terminal. If the interrupt takes place resumed. These statements may refer to
within the scope of an ATTENTION on-unit, names in three different circumstances:
control goes to the terminal upon normal
return from the on-unit. 1. The names may be known in the scope of
the current block.
The programmer can then do one of the
following: 2. The QUALIFY command may be used to
specify an external procedure in which
1. He can enter PL/I statements for the name is known.
immediate execution. When these
statements have been processed, he can 3. In the case of an immediate DO-group
cause program execution to be resumed or begin block, the name may be known
at any specified point. only within the scope of that bloCk.
An immediate-mode statement cannot
2. He can enter PL/I statements for alter an existing declaration.
execution at a specified point once
program execution has been resumed. The restrictions imposed on PL/I
These statements are not executed statemeLts used in immediate mode are:
immediately they are entered, as in
the preceding situation, but are 1. The following statements cannot be
stored for later use. Program used in immediate-mode:
execution is resumed; when the
specified point in execution is DEFAULT
reached, then, without further action
by the programmer, program execution ENTRY
is again suspended and the extra
statements are executed. In order to FORMAT
achieve this, the extra statements
must be preceded by an appropriate ON
terminal subcommand. This is an
instruction to the checkout compiler. PROCEDURE
In this instance, the subcommand
specifies the point at which program 2. FETCH and RELEASE are valid in
execution will automatically be immediate mode only when they specify
suspended so that the extra statements procedures specified in FETCH and
entered with i t can be executed. RELEASE statements contained in the
original source program.
3. He can enter, by itseif, one of a
number of terminal subcommands. 3. An unmatched END statement cannot be
used.
The subcommands provide various aids to
debugging that do not involve entering 4. statements cannot have condition
extra statements. prefixes.

Full details of the terminal subcommands 5. The ~INCLUDE facility may not be used.

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

 Chapter 16: Compile-Time Facilities

Compile time is generally defined as that Preprocessor Input and Output

time during which a user's source program
is compiled, or translated, into an
executable object program. Ordinarily, The preprocessor interprets preprocessor
changes to a source program may not be made statements and acts upon the source program
at this time. accordingly. Input to the preprocessor is
a sequence of characters that is the user's
However, with PL/I, the programmer does source program. It contains preprocessor
have some control over his source program statements freely intermixed with the rest
during compile time. His source program of the user's source program. Preprocessor
can contain special statements (identified statements are identified by a leading
by a leading percent symbol (I) that can percent symbol ( ~ ) and are executed as
cause parts o£ the source program to be they are encountered by the preprocessor
altered in various ways: (with the exception of preprocessor
procedures, which must be invoked in order
1. Any identifier appearing in the source to be executed). One or more blanks may
program can be changed. separate the percent symbol from the
statement.
2. If conditional compilation is desired,
the programmer can indicate which In addition to interpreting the
sections of his program are to be preprocessor statements, the preprocessor
compiled. checks the source program for unmatched
delimiters on comments and character-string
3. Strings of text residing in a user constants. It also checks non-preprocessor
library or a system library can be statements for invalid characters, and
incorporated into the source program. replaces them with blanks. This is the
only checking done at this stage on nOn-
PL/I makes source program alteration at preprocessor statements.
compile time possible by providing two
stages: output from the preprocessor consists of
a string of characters called the
1. The preprocessor stage -- During this preprocessed text, which consists of the
stage, the user's source program is altered source program and which serves as
scanned for preprocessor statements, input to the processor stage.
special statements that cause the
preprocessor to alter the text being The programmer can specify compiler
scanned. These statements are options that cause the input to, and the
considered part of the source program, output from, the preprocessor to be
and appear freely intermixed with the printed. The listing of the input to the
statements and other text of the preprocessor, which represents the program
source program. The altered source as coded by the programmer, is known as the
program, resulting from the action of insource listing, and the listing of the
the preprocessor statements, then input to the compiler - the preprocessed
serves as input to the second stage. text if the preprocessor is used - is known
Note that the preprocessor stage is as the source listing.
optional.
Similarly, by the use of compiler
2. The Processor Stage -- During this options, the output from the preprocessor
stage, the output from the first stage may also be punched as a sequenced deck of
is compiled into an executable object cards, or written to a data set defined by
program. a DO statement with the name SYSPUNCH.
This chapter is concerned with the first
stage; the actual compilation of a program
is not discussed. PREPROCESSOR SCAN
In addition to the preprocessor
statements, the programmer has at his The preprocessor starts its scan of the
disposal listing control statements which input text at the beginning of the string
allow him to control the layout of the and scans each character sequentially. As
printed listing of his program. These do long as a preprocessor statement is not
not employ the preprocessor stage. encountered, the characters are placed into

Chapter 16: Compile-time Facilities 239

the preprocessed text in the same order and insertion of a value into preprocessed text
general form in which they were scanned. takes place only after all possible
However, when a preprocessor statement is replacements have been made. Note that the
encountered, it is executed. This deactivation of an identifier causes it to
execution can cause the scanning of the lose its replacement capability but not its
source program and the subsequent formation value. Hence, the subsequent reactivation
of preprocessed text to be altered in of such an identifier need not be
either of two ways: accompanied by the assignment of a
replacement value.
1. The executed statement may cause the
preprocessor to continue the scan from
a different point in the program. For example, if the source program
This new point may very well be one contained the following sequence of
that has already been scanned. statements:

2. The executed statement may initiate %DECLARE A CHARACTER, B FIXED:

replacement activity. That is, it may ~A = 'B+C';
cause an identifier not appearing in a 'B = 2:
preprocessor statement to be replaced X = A:
when that identifier is subsequently
encountered in the scan. The
replacement value will then be written then the following would be inserted int.o
into the preprocessed text in place of the preprocessed text in place of the above
the old identifier (see "Rescanning sequence:
and Replacement" below for details).

The scan is terminated when an attempt X = 2+C:

is made to scan beyond the last character
in the source program. The preprocessed
text is completed and the second stage of In this example, the first statement is
compilation can then begin. a preprocessor DECLARE statement that
activates A and B and also activates them
as preprocessor variables with the default
RESCAN.
Rescanninq and Replacement

The second and third statements are

For an identifier to be replaced by a new preprocessor assignment statements: the
value, the identifier must first be second assigns the character string 'B+C'
activated for replacement. Initially, an to A, and the third assigns the constant 2
identifier is activated by its appearance to B.
in a preprocessor DECLARE statement (i.e.,
a , DECLARE statement). (It can be
deactivated by appearing in a , DEACTIVATE The fourth statement is a
statement and it can be reactivated by nonpreprocessor statement and, therefore,
appearing in a , ACTIVATE statement.) After is not executed at this stage. (For the
it has been activated initially, it must be purpose of this discussion, a
given a replacement value. This is usually nonpreprocessor statement is any statement
done via the execution of a preprocessor or sequence of text that appears in the
assignment statement. Once an identifier source program but is not contained in a
has been activated and been given a value, preprocessor statement, nor in a
any occurrence of that identifier in text preprocessor procedure, nor in a comment.)
other than preprocessor statements is However, because this statement contains A,
replaced by that value, provided that the and A is a preprocessor variable that has
identifier is still active when i t is been activated for replacement, the current
encountered by the scan. Preprocessor value of A will replace it in that
variables can be activated with either the statement. Thus, the string 'B+C' replaces
RESCAN or the NORESCAN options. If the A in the statement. But this string
NORESCAN option applies, the value is contains the preprocessor variable B. Upon
immediately inserted into the program text. checking B, the preprocessor finds that it
If the RESCAN option applies, a rescan is has been activated and that it has been
made during which the value is tested to aSSigned a value of 2. Hence, the value 2
determine whether it, or any part of it, replaces B in the string. Further checking
should be replaced by another value. If it shows that 2 cannot be replaced: scanning
cannot be replaced, it is inserted into the resumes with +C which, again, cannot be
preprocessed text: if it can be replaced, replaced. Thus, the chain of replacements
replacement activity continues until no comes to an end and the resulting statement
further replacements can be made. Thus, is inserted into the preprocessed text.

240 OS PL/I CKT AND OPT LRM PART I

 If, in the above example, the preprocessor statement, is only scanned for
preprocessor variable A has been activated replacement activity; it is not executed.
by this statement: The first time that this statement is
scanned, I has the value 1 and has been
IACTIVATE A NORESCAN: activated. Therefore, each occurrence of I
in this statement is replaced by 1 and the
the statement inserted into the text would following is inserted into the preprocessed
be: text being formed:
x =B + C: Z( l)=X( l)+Y( 1)

since the NORESCAN option for preprocessor Note that each 1 is preceded by seven
variable A suppresses the res canning of the blanks.
result 'B+C' substituted for A.
The fifth statement increments the value
Note that the preprocessor variable B of I by 1 and the sixth statement, a
has a default precision of (5,0) and, preprocessor IF statement, tests the value
therefore. actually contains 2 preceded by of I. If I is not greater than 10, the
four zeros. When this value replaces B in scan is resumed at the statement labeled
the string 'B+C' it is converted to a LAB: otherwise, the scan continues with the
character string and becomes 2 preceded by text immediately following the IGO TO
seven blanks (the rules for conversion of statement. Hence, for each increment of I,
decimal fixed-point values to character up to and including 10, the assignment
string are followed). See the section statement is rescanned and each occurrence
·preprocessor Expressions· later in this of I is replaced by its current value. As
chapter, for details. a result, the following statements are
inserted into the preprocessed text:
Replacement values must not contain
percent symbols, unmatched quotation marks, Z( l)=X( l)+Y( 1):
or unmatched comment delimiters.
Z( 2)=X( 2)+Y( 2) :
The following example illustrates how
compile-time facilities can be used to
speed up the execution of a DO-loop.
Z( 10)=X( 10)+Y( 10):
A programmer might include the following
loop in his program: As before, each number from 1 through 9
is preceded by seven blanks: the number 10
DO 1=1 TO 10: is preceded by six blanks.
Z(I)=X(I)+Y(I):
END; When the value of I reaches 11, control
falls through to the IDEACTIVATE statement.
The following sequence would accomplish the This statement is interpreted as follows:
same thing, but without the requirements of subsequent encounters of the identifie~ I
incrementing and testing during execution in source program text are not to be
of the compiled program: replaced by the value 11 in the
preprocessed text being formed; each I will
IDECLARE I FIXED: be left unmOdified, either for the
11=1; remainder·of the scan or at least until I
ILAB: ; is reactivated by a IACTIVATE statement.
ZCI)=X(I)+Y(I); If I is again activated, it will still have
11=1+1; the value 11 (unless an intervening
IIF 1<=10 ITHEN IGO TO LAB; preprocessor assignment statement has
IDEACTIVATE I; established a new value for I).
The first statement activates I and
establishes it as a preprocessor variable.
The second statement assigns the value 1 to Character strings and comments
I. This means that subsequent encounters
of the identifier I in non-preprocessor
statements will be replaced by 1 (provided PL/I character or bit string constants and
that I remains activated). The third comments are not processed by the
statement is a preprocessor null statement I preprocessor, unless they appear in a
that is used as the transfer target for the I function reference to an active
preprocessor GO TO statement appearing Ipreprocessor procedure. The existence of
later. an otherwise valid preprocessor statement
in a character string or comment will be
The fourth statement, not being a ignored, as will the existence of a

Chapter 16: Compile-time Facilities 241

preprocessor variable for replacement. diagnosed, and it will be given the default
attribute of CHARACTER, but will not be
Such strings or comments will be passed activated for replacement unless it is
through unchanged from input to output. subsequently in an executed 'ACTIVATE
However, this can cause mismatches between statement. The variable will be usable in
input and output lines for strings or preprocessor statements, however, so that
comments extending over several lines, when it is not essential to declare iterative DO
the input and output margins are different, control variables or intermediate result
and particularly where V-format input is temporaries, which are not themselves
used, since the output is always F-format, replacement items.
with margins in columns 2 and 72.
The output line numbering in these cases
will also show this inevitable mismatch. Preprocessor Expressions

Preprocessor expressions are written and

Preprocessor Variables evaluated in the same way as source program
expressions, with the following exceptions:
A preprocessor variable is an identifier 1. The operands of a preprocessor
that has been specified in a 'DECLARE expression can consist only of
statement with either the FIXED or preprocessor variables, references to
CHARACTER attribute. No other attributes preprocessor procedures, decimal
can be declared for a preprocessor integer constants, bit-string
variable. Other attributes are supplied by constants, character-string constants,
the compiler, however. A preprocessor and references to preprocessor built-
variable declared with the FIXED attribute in functions. Repetition factors are
is also given the attributes DECIMAL and not allowed with the string constants
precision (5,0): a CHARACTER preprocessor and the arguments to a built-in
variable is given the VARYING attribute function reference must be
with no maximum length. No con1:extual or preprocessor expressions.
implicit declaration of identifiers is
allowed in preprocessor statements. 2. The exponentiation symbol (**) cannot
be used as an arithmetic operator.
The scope of a preprocessor variable
encompasses all text except those 3. For arithmetic operations, only
preprocessor procedures that have decimal integer arithmetic of
redeclared that variable. The scope of a precision (5,0) is performed: that is,
preprocessor variable that has been each operand is converted to a decimal
declared in a preprocessor procedure is the fixed-point value of precision (5,0)
entire procedure (there is no nesting of before the operation is performed, and
preprocessor procedures). the decimal fixed-point result is
converted to precision (5,0) also.
When a preprocessor variable has been Any character string being converted
given a value, that value replaces all to an arithmetic value must be in tbe
occurrences of the corresponding identifier form of an optionally signed decimal
in text other than preprocessor statements integer constant. Note that the
during the time that the variable is properties of the division operator
active. If the preprocessor variable is are affected. For example, the
inactive, replacement activity cannot occur expression 3/5 evaluates to 0; rather
for the corresponding identifier. than to 0.6.
A preprocessor variable is activated by 4. The conversion of a fixed-point
its appearance in the ~DECLARE statement. decimal number to a character string
It can be deactivated and subsequently always results in a string of length
reactivated by its appearance in 8. (Leading zeros in the number are
~DEACTIVATE and ~ACTIVATE statements, replaced by blanks and an additional
respectively. Deactivation of a three blanks are appended to the left
preprocessor variable does not strip it of end of the number, one of which is
its value: in other words, an inactive replaced by a minus sign if the number
preprocessor variable retains the value it is negative.)
had while it was active and can be altered
by a preprocessor statement or procedure if A character string in an expression
so desired. being assigned to a preprocessor variable
may include preprocessor variables,
If a preprocessor variable is not references to preprocessor procedures,
explicitly declared the error will be constants, and operators: preprocessor

242 OS PL/I CRT AND OPT LRM PART I

 statements cannot be included in such Imust be invoked by a reference of the form:
strings. I
I TEST(X,Y,Z)
I
I A preprocessor procedure headed by:
I
Preprocessor Procedures I IFIND:PROCEDURE(A,B,C) STATEMENT •••• :
I
Imust be invoked from preprocessor text by a
A preprocessor procedure is an internal reference of the form:
function procedure that can be executed
only at the preprocessor stage. Its syntax FIND(X,Y,Z)
differs from other function procedures in
that its PROCEDURE and END statements must If the reference is in non-preprocessor
each have a leading percent symbol. The text, the procedure can be invoked, with
format of a preprocessor procedure is as the same result, by any of the following
follows: references:
~label: [label:]... PROCEDURE FIND(X,Y,Z):
[(identifier
[,identifier] ••• )] FIND BCY) C(Z) A(X);
[STATEMENT]
RETURNS({CHARACTERIFIXED}); FIND(X) C(Z) BCY);
FIND(,Y,Z) A(X);
[label:l ••• RETURN etc.
(preprocessor-expression);
Note that, if the STATEMENT option applies,
and the reference is in non-preprocessor
Itext, the end of the reference must be
" [label:] END [label]: lindicated by a semicolon.
More than one RETURN statement may A condition must be met if the reference
appear. The general rules governing the to the preprocessor procedure is made in a
statements that can appear within a nonpreprocessor statement: the entry name
preprocessor procedure are given in the used in the reference must be active at the
description of the ~PROCEDURE statement in time the reference is encountered. Entry
section J, ·Statements·. One thing should names of preprocessor functions are the
be noted, however: no statement appearing same as preprocessor variables as far as
Iwithin a preprocessor procedure (except for activation and deactivation is concerned:
Ilisting control statements) can have a i.e., they can be activated initially by a
leading percent symbol. "DECLARE statement or by a "ACTIVATE
statement.
Provided its entry name is active, a
INVOCATION OF PREPROCESSOR PROCEDURES preprocessor procedure need not be scanned
before it is invoked. It must, however, be
Ipresent either in the main text, or in text
IA preprocessor procedure is invoked by the included (by a ~INCLUDE statement) before
lappearance of its entry name, together with the pOint of invocation. Preprocessor
Ian optional list of arguments. If the procedure entry names need not be specified
lassociated "PROCEDURE statement does not in "DECLARE statements.
Ihave the STATEMENT option, the argument
Ilist must be a parenthesized list of The value returned by a preprocessor
lpositional arguments following the entry function (i.e., the value of the
I name. If the STATEMENT option is present, preprocessor expression in the RETURN
land the reference to the procedure occurs statement) always replaces the function
lin non-preprocessor text, the arguments may reference and its associated argument list.
lbe specified either in the positional IIf the associated "PROCEDURE statement has
largument list or by keyword reference. If Ithe STATEMENT option, and the reference is
Ithe reference occurs in preprocessor text, lin non-preprocessor text, the semicolon
Ithe positional argument list must be used. Ithat delimits the reference is not retained
I Iwhen the replacement takes place. Note
I For example, a preprocessor procedure that for a reference made in a preprocessor
Iheaded by: statement, the replacement is only for that
I particular execution of the statement: a
I "TEST:PROCEDURE(A,B,C) •••• : subsequent scanning of the statement would

Chapter 16: Compile-time Facilities 243

 again result in the invocation of the argument is converted to the type indicated
function. by the corresponding parameter attribute in
the preprocessor procedure statement for
the function entry name.
ARGUMENTS AND PARAMETERS FOR If the function reference appears in a
PREPROCESSOR FUNCTIONS preprocessor statement, the arguments are
associated with the parameters in the
normal fashion. If there is a
The number of arguments in the procedure disagreement, the arguments are converted
reference and the number of parameters in to the attributes of the corresponding
the IPROCEDURE statement need not be the parameters. Only preprocessor variables,
same. The arguments are interpreted character- string constants, and fixed-
according to the type of statement pOint decimal constants can be passed to a
(preprocessor or nonpreprocessor) in which preprocessor function invoked by a
the function reference appears. The preprocessor statement.
arguments in the argument list are
evaluated before any match is made with the
Iparameter list. If there are more
positional arguments than parameters, the Returned Value
excess arguments on the right are ignored.
I (Note that for an argument that is itself a
Ifunction reference, the function is invoked The value returned by a preprocessor
and executed, even if the argument is function to the pOint of invocation is
lignored later.) Parameters that are not represented by the preprocessOr expr~ssion
Iset by the function reference are given in the RETURN statement of that function.
values of zero, for FIXED parameters, or Before being returned, this value is
the null string, for CHARACTER parameters. converted (if necessary) to the attribute
(CHARACTER or FIXED) specified in the
I Parameters should not be set more than RETURNS option of the function's IPROCEDURE
lonce by a function reference. However, if statement. If the point of invocation is
Ithe value of a parameter is specifed more in a nonpreprocessor statement, and the
Ithan once, for example both positionally entry name has not been activated with the
land by keyword, the first setting is used NORESCAN option, the value is scanned for
Ifor the invocation. replacement activity after it has replaced
the function reference.
The usual rules concerning the creation
of dummy arguments apply if the function Note that the rules for preprocessor
reference is in a preprocessor statement, expressions do not permit the value
but dummy arguments are always created if returned by a preprocessor procedure to
the function reference occurs in a contain preprocessor statements.
nonpreprocessor statement.
If the function reference appears in a
nonpreprocessor statement, the arguments Example of Preprocessor Functions
are interpreted as character strings and
are delimited by the appearance of a comma
or a right parenthesis occurring outside of In the statements below, VALUE is a
balanced parentheses, a character-string preprocessor function procedure that
lenclosed in single quotes, or a comment. returns a character string of the form
IFor example, the positional argument list 'argl(arg2)', where arql and arq2 represent
(ACB,C),D) has two arguments, namely, the the arguments that have been passed to the
string A(B,C) and the string D. If an function. Assume that the source program
argument is not enclosed in quotes and is contains the following sequence:
continued on another line, blanks at the
end of the line are replaced by one blank. IDECLARE A CHARACTER;
IDECLARE VALUE ENTRY;
Each argument is then scanned for DECLARE (Z(10), Q) FIXED;
lpossible replacement activity. (If keyword IA='Z';
linvocation is used, the keywords themselves IVALUE: PROC(ARG1,ARG2) RETURNS (CHAR) ;
I are' not eligible for replacement activity.) DCL ARGl CHAR, ARG2 FIXED;
Both the procedure name and its argument RETURN (ARGlI I' C' IIARG211')');
list must be found at one replacement lEND VALUE;
level. Thus, only the commas and Q = 6+VALUE(A,3);
parentheses seen in the text being scanned
when the procedure name is encountered are When the scan encounters the last
considered in this context. After all statement, A is active and is thus eligible
replacements have been made, each resulting for replacement. Since VALUE is also

244 OS PL/I CKT AND OPT LRM PART I

active, the reference to i t in the last The following text is produced by this
statement causes the preprocessor to invoke preprocessor procedure:
the preprocessor function procedure of that
name. However, before the arguments A and DCL A GENERIC(A2 WHEN (FIXED,FIXED),
3 are passed to VALUE, A is replaced by its A3 WHEN (FIXED, FIXED,
value Z (assigned to A in a previous FIXED),
assignment statement), and 3 is converted A4 WHEN (FIXED, FIXED,
to fixed-point to conform to the attribute FIXED, FIXED),
of its corresponding parameter. VALUE then AS WHEN (FIXED, FIXED,
performs a concatenation of these arguments FIXED, FIXED, FIXED»:
and the parentheses and returns the
concatenated value, that is, the string Z
(3), to the point of invocation. The
returned value replaces the function
reference and the result is inserted into
the preprocessed text. Thus, the I The final example shows a preprocessor
preprocessed text generated by the above Iprocedure which implements a statement of
sequence is as follows: Ithe form:
I
I SEARCH TABLE(array) FOR (value)
I USING(variable) AND(variable);
I
DECLARE (Z(10),Q) FIXED; I This statement searches a specified two-
Q = 6+Z( 3); Idimensional array for a specified value,
lusing specified or default variables for
Ithe array subscripts. After execution of
The preprocessor function procedure GEN the statement, the array subscript
defined in the following example can variables identify the element that
generate a GENERIC declaration for up to 99 contains the specified value. If nO
entry names with up to 99 parameter element contains the specified value, both
descriptors in the parameter descriptor subscript variables are set to -22222.
lists. Only four are generated in this
example, however. The preprocessor procedure that
implements this statement is as follows:

Assume that the source program contains

the following sequence: ISEARCH:
PROC(TABLE,FOR,USING,AND) STATEMEru
RETURNS(CHARACTER):
IDCL GEN ENTRY;
DCL A GEN (A,2,S,FIXED), ••• ; DECLARE(TABLE,FOR,USING,AND,LABL,
D01,D02) CHARACTER,
(PARMSET,COUNTER) BUILTIN:
IGEN: PROC (NAME, LOW, HIGH,ATTR) RETURNS
(CHAR); IF PARMSET(TABLE) 'PARMSET(FOR) THEN:
DCL (NAME, SUFFIX, ATTR, STRING) ELSE SERR:DO:
CHAR, (LOW, HIGH, I, J) FIXED; NOTE('MISSING OR INVALID ARGUMENT(S), II
STRING='GENERIC(': 'FOR "SEARCH"',4):
DO I=LOW TO HIGH;/*ENTRY NAME LOOP*/ RETURN('/*INVALID SEARCH STATEMENT*/'):
IF 1>9 THEN SUFFIX=SUBSTR(I, 7, 2); END:
/* 2 DIGIT SUFFIX*/
ELSE SUFFIX=SUBSTR(I, 8, 1): IF ~PARMSET(USING) THEN USING='I':
/*1 DIGIT SUFFIX*/ IF ~PARMSET(AND) THEN AND='J':
STRING=STRINGIINAMEIISUFFIXI I 'WHEN ('; IF USING = AND THEN GO TO SERR;
DO J=l TO I; /*DESCRIPTOR LIST*/
STRING=STRINGIIATTR; LABL='SL'IICOUNTER;
IF J<I /*ATTRIBUTE SEPARATOR*/ D01=LABLII ':00 'I I USING I I'=LBOUND('I I
THEN STRING=STRINGII','; TABLE I I ' ,1) TO HBOUND (' I I TABLE I I ' , 1 ) : ' ;
ELSE STRING=STRINGI 1')'; D02='DO 'IIUSINGII '=LBOUND('II
/* LIST SEPARATOR */ TABLEII',2) TO HBOUND('IITABLEII',2):':
END:
IF I<HIGH /*ENTRY NAME SEPARATOR*/ RETURN (001 I ID021 I'SELECT(' I I TABLE I I' (I II
THEN STRING=STRINGII','; USING I I ' , , II AND I I I »: WHEN ( , I I FOR I I
ELSE STRING=STRINGI I')': ') LEAVE '1Ih~BLII'; OTHER; END 'I I
/* END OF LIST */ LABLII'; IF 'IIANDII' > HBOUND('II
END; TABLE I 11 ,2) THEN 'IIUSINGII',' IIANDII
RETURN (STRING): , = -22222:'):
~ END: lEND SEARCH:

Chapter 16: Compile-time Facilities 245

 In this example, the PARMSET built-in SUBSTR
function is used to investigate which INDEX
parameters have been set when the procedure LENGTH
is invoked. If USING is not set, the . COMPILETIME
default array subscript variable I is used: COUNTER
if AND is not set, J is used. If TABLE or PARMSET
FOR is not set, or if the invocation would
result in the same variable being used for
both subscripts, a preprocessor diagnostic
message is issued (by means of the IThe SUBSTR, INDEX, and LENGTH built-in
preprocessor NOTE statement) and a warning Ifunctions have the same functions as the
comment is returned for inclusion in the Inon-preprocessor built-in functions of the
source text. Isame names. Upon invocation, the first
largument of SUBSTR, INDEX, or LENGTH is
The COUNTER built-in fUnction is used to I converted, if necessary, to character; the
generate unique labels for the text Isecond and third arguments of SUBSTR are
returned by the procedure. I converted, if necessary, to decimal; and
Ithe second argument of INDEX is converted,
The procedure may be invoked with lif necessary, to character. The returned
keyword arguments or positional arguments, Ivalue is CHARACTER for SUBSTR, and FIXED
or a combination of the two. The following Ifor INDEX or LENGTH.
invocations of the procedure produce
identical results:
The COMPILETIME built-in function
SEARCH TABLE(LIST.NAME) FOR('J.DOE') Ireturns a character string containing the
USING(I) AND(J): Itime and date of its invocation. It may
Ithus be used to generate information about
SEARCH TABLE(LIST.NAME) FOR('J.DOE'): Ithe time and date of compilation of the
Iprogram in which it appears.
SEARCH (LIST. NAME) FOR('J.DOE'):
SEARCH(LIST.NAME,'J.DOE'): I The COUNTER built-in function returns a
Icharacter string of length five containing
SEARCH(,'J.DOE') TABLE(LIST.NAME): la unique decimal number. The value
Ireturned by the first invocation is 00001.
The text returned by any of these IThe value is incremented by one for each
invocations is as follows: Isubsequent invocation, up to a maximum of
199999. COUNTER may be used to generate
SL00001: lunique identifiers, or for general counting
DO I=LBOUND (LIST. NAME, 1) TO I purposes.
HBOUND(LIST.NAME,l):
DO J=LBOUND(LIST.NAME,2) TO
HBOUND(LIST.NAME,2); I The PARMSET built-in function may only
SELECT(LIST.NAME(I,J»; Ibe used within a preprocessor procedure.
WHEN('J.DOE') LEAVE SL00001: lIt is used to determine whether a specified
OTHER: Iparameter has been set on invocation of the
END SL00001; I procedure. PARMSET returns a bit value of
IF J > HBOUND (LIST. NAME, 2.) THEN lone or zero. The returned value is
I,J = -22222: Iconverted if necessary to a FIXED value of
lone or zero, or to a character string of
Here, the returned text has been Ilength one containing '1' or '0'.
formatted in order to show its structure
more clearly. Also, the label SL00001 is
Ireturned only for the first invocation. A I A reference to a preprocessor built-in
Inew unique label is returned for each function in a nonpreprocessor statement is
Isubsequent invocation. executed by the preprocessor only if these
Inames are active. The built-in functions
can be activated only by a ~DECLARE or
I'ACTIVATE statement. If a preprocessor
Ibuilt-in function name is used as the name
10f a user-defined preprocessor procedure,
lit is assumed that references to the name
lare references to the procedure, not to the
IPreprocessor Built-in Functions built-in function. In such cases the
lidentifiers may be re-declared with the
BUILTIN attribute when the built-in
IThe built-in functions that can be executed functions are to be used within a
lat the preprocessor stage are: preprocessor procedure.

246 OS PL/I CKT AND OPT LRM PART I

Preprocessor Do-Group Inclusion of External Text

Strings of external text can be

incorporated into the source program by use
The preprocessor do-group can provide of the %INCLUDE statement. Such text, once
iterative execution of the preprocessor incorporated, is called included text and
statements contained within the group. The may consist of both preprocessor and
format of the preprocessor do-group is as nonpreprocessor statements. Hence,
follows: included text can contribute to the
preprocessed text being formed.

I [label: 1 • •• DO [i=ml [TO m2 [BY m3]1]; Note: If text inclusion is the only pre-
BY m3 [TO m2]J processor facility required, that is, if
the source program and the included text
contain no preprocessor statements other
than 'INCLUDE, the preprocessor stage may
i[label:] ••• END[labell; be omitted. (For the optimizing compiler,
this necessitates the use of the INCLUDE
compiler option. See the programmer's
In the above format, i must be a guide for the optimizing compiler.)
preprocessor'variable and m1, m2, and m3
must be preprocessor expressions. The It the included text contains any
label that can follow the keyword END must preprocessor declarations, the scope of the
be one of the labels preceding the keyword names ~eclared as preprocessor variables is
DO. Preprocessor do-groups may be nested all the included text and any text which
and multiple closure is allowed. follows the included text, except
preprocessor procedures in which the name
Control cannot be transferred into a is redeclared.
preprocessor do-group specifying iteration,
except by way of a return from a The general format and the rules
preprocessor procedure invoked from within governing the use of the iINCLUDE statemen~
the group. are presented in section J, "Statements".

Both preprocessor statements and text The text specified by a iINCLUDE

other than preprocessor statements can statement is incorporated into the source
appear within a preprocessor do-group. program immediately after the point at
However, only the preproc~ssor statements which the statement is executed. The scan
are executed; nonpreprocessor statements therefore continues with the first
are scanned but only for possible character in the included text. All
replacement activity. preprocessor statements in this text are
executed and replacements are made where
Noniterative preprocessor do-groups are required.
useful as THEN or ELSE clauses of iIF
statements. Preprocessor procedures whose
declarations appear in external text can be
The expansion of a preprocessor do-group invoked only after that external text
is similar to that shown under the becomes included text. The result of a
nonpreprocessor DO statement section J, preprocessor procedure reference
"Statements". encountered before that procedure has been
incorporated into the source program is
The example below results in the same undefined.
expansion generated for the example of
preprocessor loop expansion in the section Assume that PAYRL is a member of the
"Rescanning and Replacement" in this data set SYSLIB and contains the following
chapter: structure declaration:

$DECLARE I FIXED; DECLARE 1 PAYROLL,

%DO 1=1 TO 10; 2 NAME,
Z(I)=X(I)+Y(I); 3 LAST CHARACTER (30) VARYING,
'END; 3 FIRST CHARACTER (15) VARYING,
'DEACTIVATE I; 3 MIDDLE CHARACTER (3) VARYING,
2 MAN NO,
The second example under "Returned 3 REGLR FIXED DECIMAL (8,2),
Value" shows how preprocessor do-groups can 3 OVERTIM FIXED DECIMAL (8,2),
be used within a preprocessor procedure 2 RATE,
(percent symbols must be omitted, of 3 REGLAR FIXED DECIMAL (8,2),
course) • 3 OVERTIME FIXED DECIMAL (8,2);

Chapter 16: Compile-time Facilities 247

 Then the following sequence of immediately follOWing the " (only
preprocessor statements: blanks can intervene). All labels
must be unsubscripted statement label
IDECLARE PAYROLL CHARACTER: constants. (Labels on %DECLARE
IPAYROLL='CUM PAY': statements are ignored.)
'INCLUDE PAYRL:
IDEACTIVATE PAYROLL: The functions performed ~ the following
"INCLUDE PAYRL: preprocessor statements have already been
discussed in this chapter:
will generate two identical structure
declarations into the preprocessed text, "ACTIVATE
the only difference being their names, "DEACTIVATE
CUM PAY and PAYROLL. Execution of the "DECLARE
first IINCLUDE statement causes the text in "DO
PAYRL to be incorporated into the source lEND
program. When the scan encounters the "INCLUDE
identifier PAYROLL in this included text, "PROCEDURE
it replaces it by the current value of the RETURN
active preprocessor variable PAYROLL,
namely, CUM_PAY. Further scanning of the Note that the preprocessor RETURN
included text results in no additional statement cannot have a leading " because
replacements. The scan then encounters the i t can be used only within a preprocessor
"DEACTIVATE statement. Execution of this procedure.
statement deactivates the preprocessor
variable PAYROLL and makes the identifier I Five other statements can be eXEcuted at
ineligible for replacement. When the the preprocessor stage:
second IINCLUDE statement is executed, the
text in PAYRL once again is incorporated "assignment
into the source program. This time, "GO TO
however, scanning of the included text "IF
results in no replacements whatsoever, "null
because none of the identifiers in the "NOTE
included text are active. Thus, two
structure declarations, differing in name The preprocessor aSSignment statement is
only, are inserted into preprocessed text. used to evaluate preprocessor expressions
and to assign the result to a preprocessor
variable. All of the examples shown in
this section make use of this statement.
Preprocessor Statements
The " GO TO statement causes the
preprocessor to interrupt its sequential
This section lists tho$e statements that scanning and continue i t elsewhere in the
can be used at the preprocessor stage and source program, specifically at the label
briefly discusses those preprocessor specified in the " GO TO. Thus, it can be
statements that have not yet been explained useful for rescanning or avoiding text.
in this chapter. All of the preprocessor
statements, their formats, and the rules The " IF statement can be used to
governing their use are described in the control the sequence of the scan according
sub-section ·Preprocessor statements· in to the value of a preprocessor expression.
section J, "statements". It must have a THEN clause and it can have
an ELSE clause. Each Clause, as well as
But first, some unrelated comments each preprocessor statement within the
pertaining to preprocessor statements in clause, must be preceded by a J. Nesting
general should be made: of "IF statements is allowed and must
follow the same rules that apply for the
1. Some keywords appearing in nesting of nonpreprocessor IF statements.
preprocessor statements can be
abbreviated as shown in section C, The preprocessor null statement is the
"Keywords and Abbreviations". same as a nonpreprocessor null statement
(except for the percent symbol). It can be
2. Comments can appear within used to provide transfer targets for IGO TO
preprocessor statements wherever statements or it can be used in nested "IF
blanks can appear; however, such statements to balance the "ELSE clauses.
comments are never inserted into For example, IELSEI: is a null ELSE clause.
preprocessed text.
I The "NOTE statement enables the
3. All preprocessor statements can be ,programmer to generate a preprocessor
labeled. Such labels mu~t appear Idiagnostic message of specified text and

248 OS PL/I CKT AND OPT LRM PART I

'severity level. programmer-generated lactivity to be stopped and started at will.
Imessages are treated exactly like
Ipreprocessor-generated messages of the same I
Iseverity level. I Although these statements have an
linitial percent symbol, they are not
I·preprocessor statements", and they do not
Inecessitate the use of the preprocessor.
I Listing Control Statements IIf the preprocessor is used, however, a
I IINOPRINT, IPRINT, ISKIP, or %PAGE statement
I Iwhich appears in the input on a line by
IThe listing control statements enable the litself is applied to both the insource
Iprogrammer to control the layout of his Ilisting (the input to the preprocessor) and
Iprinted listings and to specify which parts Ithe source listing (the preprocessed text).
of the listings are to be printed. The IIf the statement is not on a Single line by
statements are: I itself, it is moved by the preprocessor to
la single line, and applied only to the
'PRINT; Isource listing.
INOPRINT; I
ISKIP [(n) ] : I Because the listing control statements
IPAGE: lare not preprocessor statements, their
ICONTROL({FORMATINOFORMAT}): linitial percent symbols must not be omitted
lif they appear within a preprocessor
The IPRINT and %NOPRINT statements act I procedure. (The ICONTROL statement is not
as on/off controls to govern the printing lallowed within a preprocessor procedure.)
of the listings. The ISKIP and IPAGE I
statements control the spacing of the I The ~PRINT and 'NOPRINT statements apply
listings in a manner similar to the SKIP lonly if the relevant compiler option
land PAGE options or format-items in PUT I (SOURCE Or INSOURCE) has been specified.
Istatements for a PRINT file. The ICONTROL IThe ~PRINT statement will not override, for
Istatement applies only to the formatted I example, the NOSOURCE compiler option.
Ilisting produced by the checkout compiler I
Iwhen the FORMAT compiler option is I More detailed information on the listing
I specified, and enables the formatting Icontrol statements is given in Section J.

Chapter 16: Compile-time Facilities 249

 Chapter 17: Multitasking

The use of a computing system to execute a system. Hence, at any given time, it. may
number of operations concurrently is be necessary for the system to select its
broadly termed multiprogramming. The PL/I next action from a number of different
programmer can make use of the tasks. Each task has a eriority value
multiprogramming capability of the system associated with it, which governs this
by means of the multitaskinq facilities selection process. The programmer can
described in this chapter. control the priority of the task, within
limits, if he wishes to do so; otherwise,
A PL/I program is a set of one or more the priority value is set automatically.
procedures, each of which consists of one
or more blocks of PL/I statements. The
execution of these procedures constitutes ~ CALL B; ~-------4"~ END A;
A:PROC;-------I..
one or more tasks, each of which can be
identified by a different task name. A
task is dynamic; it exists only while the
procedure is being executed. This
distinction between the procedure and its
execution is essential to the discussion of
multitasking. A procedure could be
executed several times in different tasks.
B:PROC; ------~... END;
When the multitasking facilities are not
used, the execution of a program comprising
one or more procedures constitutes a Single
task, with a single flow of control; when a
procedure invokes another procedure,
control is passed to the invoked procedure,
and execution of the invoking procedure is
suspended until the invoked procedure C:PROC;------I... CALL D TASK; - - - - - - I . . . . END C;
passes control back to it. This serial
type of operation is said to be
synchronous: when the progranuner is
concerned only with synchronous operations,
the distinction between program and task is
relatively unimportant.
With multitasking, the invoking
procedure does not relinquish control to D: PROC; ------.1.... END;
the invoked procedure. Instead, an
additional flow of control is established,
so that both procedures can be executed (in Figure 11.1. Synchronous and
effect) concurrently. This process is asynchronous operation
known as attaching a task. The attached
task is a subtask of the attach~g task. A task can have control of either the
Any task can attach a number of subtasks. CPU or the systems's I/O resources. I/O
The task that has control at the outset is may be performed in one task while CPU
called the major task. This parallel type operations are being carried out in
of operation is said to be asynchronous. another, and there may, at the same time,
be other tasks waiting for one or other of
The diagram shown in figure 11.1 the resources. Operation of the CPU can be
illustrates the difference between interrupted if a task of higher priority
synchronous and asynchronous operations. than the current one requires CPU
The arrowed lines represent the control facilities. Interruption can occur, for
flows. Procedures A and B are executed instance, if a higher-priority task
synchronously: C and D are executed completes an I/O operation or if the
asynchronously. current task attaches a subtask of higher
priority. An I/O operation is never
When several procedures are executed as interrupted: I/O resources can only be re-
asychronous tasks, individual statements allocated after completion of an I/O
are not necessarily executed simultaneously operation. When an I/O operation is
by different tasks: whether this occurs completed, the system searches amongst all
depends on the state and resources of the the active tasks that require the 110

Chapter 17: Multitasking 251

resources to find the one with the highest necessitates some extra rules, which are
priority. described in this chapter.
The checkout and optimizing compilers Multitasking also requires some extra
implement the multitasking features of PL/I rules and provisions for input/output. For
in different ways. The optimizing compiler example, without special provision, there
utilizes the operating system tasking would be nothing to prevent one task from
facilities, whereas the checkout compiler operating on a record in a DIRECT UPDATE
maintains full control of all processing, file while another task was operating on
whether synchronous or asynchronous. The the same record; to cope with this, the
results produced by a multitasking program EXCLUSIVE attribute is provided. The
will, however, be the same under both protection of records on EXCLUSIVE files is
compilers. (This is only true if execution described in chapter 12, -Record-Oriented
of the multitasking program is independent Transmission".
of time. If the code in one procedure is
dependent on the values of variables in Tasks can be terminated in a number of
another procedure that is executing different ways. Normal termination occurs
asynchronously, the use of variables in when control for the task reaches a RETURN
separate tasks must be synchronized.) or END statement for the procedure attached
as a task. The EXIT statement specifies
It may be that one task is to run abnormal termination of the task and its
independently of other concurrent tasks for subtasks, while the STOP statement
some time, but then become dependent on specifies abnormal termination of the major
some other task (for example, one task may task (even if STOP is executed in a
require the result of another task before subtask) •
it can be completed). To allow for this,
provision has been made for one task to Multitasking may allow the central
await the completion of an operation at any processing unit and input/output channels
stage of another task before carrying on. to be used more effiCiently, by reducing
This process is known as task the amount of waiting time. It does not
synchronization. Information about the necessarily follow that an asynchronous
state of an operation can be held by an program will be more efficient than an
event variable, to which an event name equivalent synchronous program (although
refers. By specifying an event name in a the latter may be easier to write). It
WAIT statement, the programmer can cause depends on the amount of overlap possible
the task to wait for completion of the between operations with varying amounts of
associated operation before proceeding. input/output: if the overlap is slight,
multitasking .will be the less efficient
The programmer can apply the EVENT method, because of the increased system
option to tasks and certain input/output overheads.
operations, in which case the value of the
event variable is set automatically as a
result of the operation concerned: or he
can set the value explicitly. Tasking and Reentrability
The EVENT option allows an input/output
operation to proceed asynchronously with If multitaSking is required, there is no
the task that initiated it; at any time need to specify the TASK keyword in the
subsequent to the initiation of the OPTIONS option of the PROCEDURE statement
input/output operation, the task can await for the main procedure. Under the
its completion. For example, a task can optimizing compiler, the multitasking
display a message to the operator and, modules of the PL/I library are made
instead of waiting for a reply, can available by means of the SYSLIB DD job
immediately proceed, pausing later to deal control statement; and under the checkout
with the reply. compiler, the multitasking facilities are
always available. It is not an error to
In general, the rules associated with specify TASK in the PROCEDURE statement: if
the synchronous invocation of procedures present, the keyword is ignored. This
apply equally to the asynchronous allows programs written for the PLlI(F)
attachment of tasks. For example, on-units compiler to be compiled without error
established prior to attachment of a messages being generated.
subtask are inherited by the subtask, just
as if the initial block of the subtask had Under the optimizing compiler, it is,
been synchronously invoked. However, however, necessary to specify the REENTRANT
asynchronous operation introduces some option if the procedure could possibly be
extra considerations, such as the fact that attached as more than one task, to be
a number of concurrent tasks can executed concurrently. The code generated
independently refer to one variable. This "by the compiler might otherwise not be

252 OS PL/I CKT AND OPT LRM PART I

reentrant. qualified. Without the task name, the
option merely specifies asynchronous
When REENTRANT is specified, the operation. If the task is to have a name,
compiler will generate code that is the option must appear complete with the
reentrable as far as machine instructions task name, which is thus contextuallY
and compiler-created storage is concerned. declared to have the TASK attribute, unless
However the programmer must ensure that the an explicit declaration exists. This is
logic of his PL/I source code is such that the only way in which a task can acquire a
the program remains reentrable. In name. (Explicit declaration of a task
particular, he must not overwrite static variable does not associate the task name
storage. with any task.) The name can be used to
control the priority of the task at some
other pOint, by means of the PRIORITY
pseudovariable and built-in function. The
Creation of Tasks task name has no other use to the PL/I
programmer.
The programmer specifies the creation of an
individual task by using one or more of the
multitasking options with a CALL statement.
Once a procedure has been activated by
execution of such a CALL statement, all
blocks synchronously activated as a result
of its execution become part of the created
task, and all tasks attached as a result of EVENT Option
its execution become subtasks of the
created task. The created task itself is a
subtask of the task executing the CALL The EVENT option has the following format:
statement. All programmer-created tasks
are subtasks of the major task. EVENT (element-event-name)
~: A task can be attached by a The event name can be subscripted and/or
procedure entered as a result of a function qualified. When this option is used, the
reference in a PUT statement for the event name is contextually declared to have
standard file SYSPRINT. the EVENT attribute (unless an explicit
declaration exists) and is associated with
the completion of the task created by the
CALL statement. Another task can then be
CALL STATEMENT made to wait for completion of this task by
specifying the event name in a WAIT
statement of the other task.
The CALL statement for asynchronous
operation has the same form as that for An event variable has two separate
synchronous operation, except for the values: a completion value that indicates
addition of one (or any combination) of the whether or not the event is complete, and a
multitasking options, TASK, EVENT, or status value that indicates whether the
PRIORITY. These options, in addition to event has been abnormally completed. The
their individual meanings (listed below), completion value is a Single bit, and the
all specify that the invoked procedure is status value is a fixed binary number of
to be executed concurrently with the preciSion (15,0). When the CALL statement
invoking procedure. is executed, the completion value of the
event variable is set to loeB (for
The CALL statement for asynchronous wincomplete W) and the status value to zero
operation can specify arguments to be (for Wnot abnormally completed W). On
passed to the invoked procedure, just as it termination of the created task, the
could if the operation were to be completion value is set to 'l'B, and, in
synchronous. the case of abnormal termination, the
status value is set to 1 (if it is still
zero).
TASK Option The EVENT option can also be specified
on the READ, WRITE, REWRITE, and DELETE
statements, and on the DISPLAY statement
TASK option has the following format: with the REPLY option (see chapter 8,
wlnput and output W). In these cases, it
TASK [(element-task-name)l allows other processing to continue while
the input/output operation is being
The task name can be subscripted and/or executed.

Chapter 11: Multitasking 253

PRIORITY Option lie within the range 0 to the highest on
the current job step).

When a number of tasks simultaneously

require attention, a choice has to be made
Under the optimizing compiler, this choice PRIORITY OF TASKS
is made by the operating system, based on
the relative importance of the various
tasks: a task that has a higher priority A priority specified in a PL/I source
value than the others will receive program is a relative value; the actual
attention first. Note that tasks, other value depends on factors outside the source
than those executing the user's program and program.
those in a wait state, may require
attention from the system, and may have a Under OS, the priority associated with
higher priority than any of the user's each job step is provided by the
tasks. Under the checkout compiler, the programmer, using the PRTY parameter in the
choice is made by the compiler, but when JOB statement. This priority can have any
processing in one task is interrupted, the number from 0 through 14: the higher the
compiler always gives control to the task number, the higher the priority.
within the same program that has the
highest priority. The priority of the major task of the
PL/I program when the program is first
The PRIORITY option has the following entered is:
format:
MIN«16*(jobstep prty)+14),disptch prty)
PRIORITY (expression)
where "disptch prty" is the dispatching
If this option appears in the CALL priority used in the job control language
statement, the expression is evaluated to a parameter DPRTY. The default dispatching
binary integer m, of precision (n,O), where priority is the job step priority. The
n is implementation-defined (15 for this maximum priority for the program is:
implementation). The priority of the
created task is then made m relative-to the (16*Cjobstep prty)+14)
task executing thE CALL statement. The
lowest absolute priority possible is 0; the (This is a minor incompatibility with
highest absolute priority possible is 234. previous releases of the optimizing and
(See "Priority of Tasks," in this chapter) PL/I F compilers, but allows full use of
job control and operating system
If the option does not appear, the facilities.)
priority of the attached task is equated to
that of the task variable named in the TASK If an attempt is made to create a
option, if any, or else equated to thE subtask with a higher priority than the
priority of the attaching task. If the maximum priority, the subtask will be
programmer employs a task variable, hs must executed at the maximum priority. Priority
specify a priority for the task (by means can be reduced to zero, but not below (a
of either thE PRIORITY pseudovariable or priority of less than zero, will be treated
the PRIORITY option of the CALL statement), as zero priority). A task can change its
otherwise the priority will be undefined. own priority and that of any other task.

Examples

1. CALL PROCA TASK(T1); PRIORITY BUILT-IN FUNCTION AND

PSEUDOVARIABLE
2. CALL PROCA TASK(T2) EVENT(ET2)i

3. CALL PROCA TASK(T3) EVENT (ET3) The PRIORITY pseudovariable provides a

PRIORITY(-2); method of setting the priority of a named
task relative to the current task. The
4. CALL PROCA PRIORITY(1); effect of the statement

The CALL statements in the above PRIORITY(T)=N;

examples create four different tasks that
execute one procedure, PROCA. In example is to set the priority of the task T equal
3, the subtask T3 has a lower priority than to the priority of the current task plUS
the attaching task, while in example 4, the the integral value of the expression N. If
unnamed subtask has a higher priority than the priority thus calculated would be
the attaching task. (It is assumed that higher than the maximum priority or less
the priorities of the attached tasks would than zero, the implementation ensures that

254 OS PL/I CKT AND OPT LRM PART I

the priority is set to the maximum, or SHARING DATA BETWEEN TASKS
zerQ, respectively.

The PRIORITY built-in function returns It is the programmer's reponsibility to

the relative priority of the named task ensure that two references to the same
Cthat is, the difference between the actual variable cannot be in effect at one instant
priority of the named task and the actual if either reference would cause the value
priority of the current task). Consider a of the variable to be changed. He can do
task, Tl, that attaches a subtask, T2, that so by including an appropriate WAIT
itself attaches a subtask, T3. If task T2 statement at a suitable pOint in his source
executes the sequence of statements program to force temporary synchronization
of the taSks involved. Subject to this
PRIORITYCT3)=3i qualification, and the normal rules of
X=PRIORITYCT3)i scope, the following additional rules
apply:
X will not necessarily have the value 3.
If, for example, task T2 had an actual 1. Static variables can be, referred to in
priority of 24, and the maximum priority any task in which they are known.
were 26, then execution of the first
statement would result in task T3 having a 2. Regardless of task boundaries, an
priority of 26, not 27. Relative to task automatic variable can be referred ~o
T2, task T3 would have a priority of 2; in any block in which it is known, or
hence, after execution of the second to which it is passed as an argument,
statement, X would have a value of 2. or in which it is referred to using an
appropriate based variable. (Note
Between execution of the two statements, that unless a dummy argument is
control could pass to task Tl, which could created, the value of an argument can
change the priority of task T2, in which change at any time; the current value
case the value of X would depend on the new is used when any reference is made by
priority. For example, given the same any task.)
original priorities as before, task T3
would have a priority of 26 after execution 3. Controlled variables can be referred
of the first statement. If the priority of to in any task in which they are
task T2 were now changed to 20 by its known. However, not all generations
attaching task, Tl, execution of the second are known in each task. When a task
statement would result in X having a value is initiated, only the latest
of 6. generation, if any, of each controlled
variable known in the attaching task
A task name may have a priority assigned is known to the attached task. Both
to it before i t is associated with a tasks may refer to this generation.
procedure. It is not an error if such a Subsequen~ generations in the attached
name is never associated with a procedure. task are known only within the
Thus, when a program is being developed, attached task; subsequent generations
task names may be introduced into the within the attaching task are known
program before the corresponding tasks are only within the attaching task. A
introduced. task can free only its own
allocationsi an attempt to free
allocations made by another task will
have no effect. No generations of the
controlled variable need exist at the
time of attaching. It is not
permissible for a task to free a
controlled generation shared with a
Coordination and Synchronization of subtask if the subtask will later
refer to the generation. When a task
Tasks is terminated, all generations of
controlled storage made within that
The rules for scope of names apply to task are freed.
blocks in the same way whether or not they
are invoked as, or by, subtasks; thus, data 4. Based variables allocated within an
and files can be shared between area are freed when the area is freed;
asynchronously executing tasks. Hence, a unless contained in an area allocated
high degree of cooperation is possible in another task, all based variable
between tasks, but this necessitates some allocations (including areas) are
coordination. Certain additional rules are freed on termination of the task in
introduced to deal with sharing of data and which they were allocated.
files between tasks, and the WAIT statement
is provided to allow task synchronization. 5. Any generation of a variable of any

Chapter 17: Multitasking 255

 storage class can be referred to in providing background to the present
any task by means of an appropriate discussion.
based variable reference. The
programmer must ensure that the The WAIT statement specifies that the
required variable has been allocated task executing it will go into a waiting
at the time of reference. state and execution of another task may be
started or resumed until such time as the
A task may allocate and free based required events have been completed. An
variables in any area to which it can event is complete when its completion value
refer. A task can only free an allocation is 'l'B. Note that the WAIT statement
of a based variable not allocated in an specifies event names, not task names.
area if the based variable was allocated by
that task. An event variable may be associated with
an input/output operation that has been
initiated by the task executing the WAIT
statement. In this case, execution of the
SHARING FILES BETWEEN TASKS WAIT statement has the following effect:

1. If transmission ends (or has ended)

A file is shared between a task and its normally, the event variable is set
subtask if the file is open at the time the complete.
subtask is attached. If a subtask shares a
file with its attaching task, the subtask 2. If the transmission ends (or has
must not attempt to close the file. A ended) requiring input/output
subtask must not access a shared file while conditions to be raised, the event
its attaching task is closing the file. variable is set abnormal (i.e., its
The subtask may re-open a file closed by status value is set to 1) and all the
the attaching task, but it will not then be required conditions are raised. The
shared. event variable is set complete on
return from the last on-unit.
If a file name is known to a task and
its subtask, and the associated file was If an abnormal return is made from an
not open when the subtask was attached, on-unit entered from the WAIT operation,
then the file is not shared; the effect is the associated event variable is set
as if the task and its subtask were complete, the WAIT operation is terminated,
separate tasks to which the file name were and control for the task passes to the
known. That is, each task may separately point specified by the abnormal return.
open, access, and close the file. This
type of operation is guaranteed only for Example
files that are DIRECT in both tasks. Note
that if one task opens a file, no other P1: PROCEDURE;
task can provide the corresponding close
operation.

It is possible that two or more tasks CALL P2 EVENT(EP2):

may attempt to operate simultaneously on CALL P3 EVENT(EP3):
the same record in a data set opened for WAIT (EP2):
direct access; this can be synchronized by WAIT (EP3);
use of the EXCLUSIVE file attribute. This
attribute is described in chapter 12,
"Record-Oriented Transmission" and section
D, "Attributes". END P1;

In this example, the task executing P1 will

proceed until it reaches the first WAIT
WAIT STATEMENT statement: it will then await the
completion of the task executing P2, and
then the completion of the task executing
The WAIT -statement has the following P3, before continuing.
format:

WAIT (event-name [,event-name] ••• )

TESTING AND SETTING EVENT VARIABLES
[(element-expression)];

Full details of the WAIT statement are The two values, completion and status, of
given in section J, "Statements"; the an event variable can be retrieved by the
following is a shorter description, built-in functions COMPLETION and STATUS.

256 OS PL/I CKT AND OPT LRM PART I

 The COMPLETION function returns the Task Tl Task T2 (Event E2)
current completion value of the event
variable named in the argument. This value COMPLETION(EV)='O'B;
is 'O'B if the event is incomplete, or 'l'B
if the event is complete.
WAIT (E2);
WAIT (EV);
The STATUS function returns the current
status value of the event variable named in
the argument. This value is nonzero if the COMPLETION (EV)
event variable has been set abnormal, or 0 ='l'B;
if i t is normal. RETURN;

Task Tl would wait for the completion

These two built-in functions can also be of task T2, and task T2 would wait for
used as pseudovariables; thus, either of task Tl to execute the completion
the two values of an event variable can be pseudovariable to set the event
set independently. Alternatively, it is variable EV complete.
possible to assign the compOSite value of
one event variable to another by specifying Under the checkout compiler this
the event variables in an aSSignment condition is detected and causes
statement. Thus, the setting of an event termination of processing. Under the
variable can be controlled by the optimizing compiler, the program waits
programmer. By this means, he can mark the until canceled by the operating system
stages of a task; and, by using a WAIT or the operator.
statement in one task and an event
assignment (from the COMPLETION built-in
function or another event variable) in
another task, he can synchronize any stage DELAY STATEMENT
of one task with any stage of another.

The programmer should not attempt to The DELAY statement (see section J,
assign a completion value to an event WStatements W) allows a task to wait for a
variable currently associated with an specified period, without reference to an
active task or with an input/output event. event variable.
An input/output event is never complete
until an associated WAIT statement is
executed, the WAIT being in the same task
as the EVENT option. Termination of Tasks
Other ways in which an event variable
can be set have already been discussed A task is terminated by the occurrence of
(such as specifying the event name in the one of the following:
EVENT option of a CALL statement). Full
details of event variables will be found 1. Control for the task reaches a RETURN
under wEVENT Attribute W in section I, or END statement for the initial
-Attributes w• See also wEVENT Option w in procedure of the task.
chapter 12, -Record-Oriented Transmission-.
2. Control for the task reaches an EXIT
Note: statement.

When tasks are being synchronized, the 3. Control for the task, or for any other
following points should be kept in mind: task, reaches a STOP statement.

1. An input/output event must be waited 4. The block in which the task wes
for in the task that initiates the attached is terminated (either
input/output operation. The event can normally or abnormally).
also be waited for in any other task,
but in this case this task will wait 5. The attaChing task itself is
until the event has been set complete terminated.
by a WAIT statement in the initiating
task. 6. Standard system action for the ERROR
condition or the action on normal
2. There is a very real danger that two return from an ERROR on-unit is
tasks could interlock and enter a carried out.
permanent wait state. The programmer
must ensure that this cannot happen in Termination is normal only if item (1) of
a program. For example: the above list applies. In all other

Chapter 17: Multitasking 257

cases, termination is abnormal. before termination of the task performing
these operations.
To avoid unintentional abnormal
termination of a subtask, an attaching task
should always wait for completion of the
subtask in the same block that attached the
subtask before the task itself is allowed Programming Example
to be terminated.
When a task is terminated, the following An example of the application of
actions are performed: multitasking to a banking system is shown
in figure 11.2. The program is divided
1. All input/output events that have been into a batch section and a real-time
initiated in the task and.are not yet section. Each section constitutes a
complete are set complete, and their subtask of the major task; each subtask has
status values (if still zero) are set other subtasks attached to it that perform
to 1: the results of the input/output the various data processing routines
operations are not defined. necessary in each section. The use of
several subtasks increases the program
2. All files that have been opened during efficiency by permitting overlap between
the task and have not yet been closed the input/output operations and the
are closed; all input/output operations performed by the central
conditions are disabled while this proceSSing unit.
action is taking place.
The batch section of the program
3. All allocations of controlled processes batches of cards that contain
variables made by the task are freed. account information (such as cheques
cashed, deposits made, or loan account
4. All allocations of based variables details) and, after a certain number of
made by the task are freed, except transactions, produces a statement.
those it has allocated within an area
allocated by another task (these are The real-time section of the program
freed when the area is freed). provides a means of communication between
itself and the operator, using the DISPLAY
5. All active blocks (including all statement with the REPLY option. This
active subtasks) in the task are facility permits the user to issue commands
terminated. to the program through the operator's
console. These commands can:
6. If the EVENT option was specified when
the task was attached, the completion 1. Cause management or credit
value of the associated event variable information, bank statements, or
is set to t'l'B. If the status value similar information to be made
is still zero, and termination is immediately available.
abnormal, the status value is set to
1. 2. Initiate or terminate processing.
Thus the user can initiate the
1. All records locked by the task are processing of card batches, terminate
unlocked. a section of processing. terminate the
entire program, or reply to a call for
Note: If a task is terminated while it is clarification of mispunched data.
assigning a value to a variable, the value
of the variable is undefined after The functions of the various tasks that
termination. Similarly, if a task is make up the program, and their relationship
terminated while it is creating or updating to each other, are shown in figure 11.3.
an OUTPUT or UPDATE file, the effect on the suggested coding for the ONLINE and PROCESS
associated data set is undefined after procedures is given below. These
termination. It is the responsibility of procedures are internal to the BANKER
the programmer to ensure that assignment procedure, as are all the procedures in the
and transmission are properly completed program in this case.

258 OS PL/I CRT AND OPr LRM PART I

 ONLINE; PROCEDURE;
DECLARE COMMAND CHARACTER(30) VARYING,
COMTYPE( S) CHARACTER (30) VARYING,
COUNT(S) FIXED BINARY INITIAL «S)O),
10 CHARACTER (72) VARYING',
XL(S) LABEL,
ENDBEVT EVENT EXTERNAL;
COMTYPE(l) = 'CREDIT';
COMTYPE(2) = 'STATEMENT';
COMTYPE(3) = 'INFORMATION';
COMTYPE(4) = 'CALL BATCH';
COMTYPE(5) =
'END BATCH';

COMTYPE(S) = 'END PROGRAM';

START: DISPLAY (' NEXT COMMAND') REPLY .(COMMAND);
/*TASK IS IN WAITING STATE UNTIL REPLY IS RECElVED*/
X: 00 I = 1 TO 8;
IF COMMAND = COMTYPE (I)
THEN GO TO XL(I);
END;
DISPLAY (' UNRECOGNIZABLE COMMAND, REPEAT')
REPLY (COMMAND);
GO TO X;
XL(l): DISPLAY ('ACCOUNT 10') REPLY (10);
COUNT (1) = COONT(l) + 1;
CALL CREDIT (ID) PRIORITY (-1); /*ATTACH CREDIT TASK*/
GO TO START;
XL(2) :

XL(S): COMPLETION (ENDBEVT) = 'l'B;

/*SETS EVENT COMPLETE IN BATCH. BATCH
WILL TERMINATE WHEN ALL CARDS READ IN*/
GO.TO START;

END ONLINE;

PROCESS: PROCEDURE;
DECLARE ANS CHARACTER (30) VARYING,
(READEVT, ENDEVT, TEVREAD,
TEVUPDT, TEVRED) EVENT EXTERNAL;
WS: WAIT (READEVT, ENDBEVT) (1);
IF COMPLETION(READEVT)='l'B THEN GO TO READIN;
WAIT (TEVREAD, TEWPDT, TEVRED) (3);
EXS: EXIT;
/*IF 'END BATCH' COMMAND WAIT FOR ASSOCIATED
TASKS BEFORE BATCH IS TERMINATED*/

READIN: COMPLETION (READEVT) = '0' B;

CALL READER TASK (PR1) PRIORITY (-1) EVENT (TEVREAD);
CALL UPDATE TASK (PR2) PRIORITY (-2) EVENT (TEVUPDT);
CALL RED TASK (PR4) PRIORITY (-3) EVENT (TEVRED);
WAIT (TEVREAD, TEVUPDT, TEVRED) (3);
DISPLAY (' CARDS PROCESSED') REPLY (ANS);
IF ANS = 'WAIT' THEN GO TO WS; /*WAIT FOR COMMAND*/
IF ANS = 'READ' THEN GO TO READIN; /*PROCESS NEXT BATClt*/
END PROCESS;

Figure 17.2. Example of multitasking as applied to a banking system

Chapter 17: Mul ti tasking 25'9

 Major task PRIORITY =P
r-------------------~--------,
I BANKER: PROC OPTIONS(MAIN, I
r------------------,
I CREDIT: PROC(X): I
I TASK: I r->IWhatis X's credit I
I Function: I I I rating? I
I Initialization, e.g., open I Subtask CONTROL PRIORITY = P~l I L------------------J
lmaster files. I r~--~-------------------------, I
IAttach on-line control task:I--->IONLINE: PROC: I
I CALL ONLINE TASK(CONTROL) I I Function: I
I PRIORITY (-1) EVENT "DISPLAY ('Next command') 'r------------------,
I (TEVCTRL): I IREPLY (command) I I ISTATEMENT:PROC(Y):I
IWAIT (for command or CONTROLI<-, IAttach tas~ according to l-t->IPrint statement
Itermination): I Icommand, or satisfy a WAIT I Ifor Y's account. I
IIf command, attach subtask I Istatement in a different taskl L------------------J
I BATCH, then return , ,by completing its event var- I
I to WAIT I, liable. The same procedure can I
IIf termination,
L------ end program JI
______________________ II Ibe attached
Idifferent several times as I,
tasks.
r----------------- J Ipriorities should be in the I
r------------------,
IMANIFO: PROC: I
I Irange (P-3) to (P-l0). I ->IExtract management I
V L-----------------------------J I informa tion. I
Subtask BATcH PRIORITY= P-2 I L------------------J
r----------------------------,I
I PROCESS: PROC:
v
r--------------,
I Function:
IInitialization of card
" W A I T satisfied I
I L--------------J
r------------------,
,CREDIT: PROC(Z): I
Iprocessing routines.
IWAITl (for 'Read' or 'End
I
I<-J
-----------------J ->IWhat is Z's credit I
I rating? I
I batch 'commands) • , L------------------J
,CALL (processing tasks). 1--,
IWAIT2 (for cards to be ,
I processed) I V
IDISPLAY ('Cards processed, I other
lany more?'). I tasks
IREPLY ('No more', 'READ', orl
,'wait'): I
I If 'No more': terminate I
I BATCH. ,
, If -Read': return to CALL. I
I If 'Wait' : return to WAIT1. I
L--------------------~-------J

V
r------------------ -----------,------------------------------,
V V
Subtask PRl PRIORITY = P-ll Subtask PR2 PRIORITY = P-12 Subtask PR4 PRIORITY = P-13
Ir---------------------------,
READER: PROC: . I ,UPDATE: PROC:
r--------------------------,
r--------------------------, IRED:
I PROC: I
I Function: I IFunction: I I Function: I
IRead cards into array I IProcess array information: I ,Treatment of 'RED' 1
I (which must have at least I Icheck that each row is I 1accounts. If necessary 1
I three rows). When one row I I full before processing. I ,attac~ task for treatment I
lis filled, test for comple-I IUpdate master files, I lof 'VERY RED' accounts. I
Ition of processing of next I
Irow by subtask PR2 before I
Icontinuing to read. I
Itransaction files.
IWhen statement 'page' is I
Ifull, attach task to print I
I
,
L--------------------------J
V
L---------------------------J I statement. Transfer infor-I Subtask PRS PRIORITY = P-14
Subtask PB3 PRIORITY = P-15 lmation on a 'RED' account I r--------------------------,1
r---------------------------,
ISTATBMENT:PROC(Account ID):I
Ito a 'RED' array for
Iprocessing by 'RED' pro- ,
I IVERYRED: PROC:
1Function: I
I Function:
IPrint statement for the II Icedure.
L_--_______________________ JI IPrint letter for account I
I owner, and owner's name I
L_- _________________________
laccount identified. JI<---------------J Ifor branch manager. 1
L--------------------------J
Figure 17.3. Flow diagram for programming example of multitasking

260 OS PL/I eKT AND OPT LRM PART I

 Chapter 18: Efficient Programming

IThis chapter on efficient programming is I The main purpose of optimization is to

lintended primarily for the user of the PL/I Igenerate object programs which execute as
10ptimizing compiler. Some sections may, Ifast as possible and which occupy as little
Ihowever, be of interest to the user of the Ispace as possible during execution. In
IPL/I Checkout Compiler. Imany cases this will involve generating
I letficient code for the statements written
I The chapter starts with a brief look at Iby the programmer; in other cases, however,
Isome of the various types of optimization the optimizing compiler may alter the
Ithat are provided by the optimizing sequence of statements or operations to
Icompiler and its libraries. improve the performance whilst produCing
I the same result.
I This is followed by some suggestions on
Ihow to tune a PL/I program for more
lefficient performance. The suggestions are The following types of optimization are
larranged in order of increasing programming carried out by the optimiZing compiler:
leffort required to effect the improvements.
IThis section also contains information on • Elimination of common expressions
Ituning a program for a virtual storage
Ienvironment, and concludes with a brief • Transfer of invariant expressions out of
Idiscussion of the benefits of modular loops
I programming.
I • Elimination of redundant expressions
I The next section, wIn-Line Operations·,
Idetails the rules for determining whether • Simplification of expressions
lor not a particular operation will be
limplemented by in-line code. By using the • Initialization of arrays and structures
linformation given in this section, it may
loften prove possible to avoid the overhead • In-line code for conversions
lof library calls for particular operations.
I • In-line code for record I/O transmission
I The next section, "Global Optimization", statements
Idiscusses the various types of global
loptimization performed by the optimizing • Reduction of key conversion for REGIONAL
Icompiler when OPTIMIZE(TIME) is specified. data sets
IThe section also contains some hints on
Icoding PL/I programs to take advantage of • Matching format lists with data lists
19lobal optimization. This section is
Ilikely to be of interest mainly to the • In-line code for string manipulation
Iscientific programmer.
I • In-line code for many of the built-in
I The chapter concludes with a list of functions
Isome of the errors and pitfalls that may be
lencountered by a programmer using PL/I for • Special-case code for DO statements
Ithe first time.
I • Special-case code for array and
I structure assignments
I
I • Register and address optimization,
IOptimization Facilities including maintenance of values in
I registers for as long as possible and
I producing efficient address arithmetic
ITHE COMPILER based on optimal flow-paths
I
I • Program branches kept as much as
IThe optimization facilities of PL/I are possible to the same base address
lavailable only for programs processed by
Ithe PL/I optimizing compiler. The PL/I • Elimination of common constants and
Icheckout compiler does not provide program control data to minimize space
loptimization of object programs: it usage
limplements the optimization language items
Iby checking the syntax and then ignoring • Analysing execution-time options during
Ithem. compile time (the PLIXOPT variable)

Chapter 18: Efficient Programming 261

 some of these types of optimization are ,modules that can be preloaded, in order to
performed even when the NOOPTIMIZE compiler ,improve overall system performance.
option is specified. Full optimization, ICommonly-used PL/I library modules may
however, is attempted only when the
OPTIMIZE (TIME) compiler option is
specified.
,,
lusefully be preloaded.
Decisions on how the libraries are to be
lorganized are usually taken on an
linstallation-wide basis at the time that
THE LIBRARIES ,
Ithe libraries are installed.
I These topics are discussed more fully in
Ithe PL/I Optimizing compiler Installation
The PL/I resident and transient libraries I Manual, Order No. SC33-0026.
contain a large number of modules, each of I
which performs a distinct logical function.
During compilation, the optimizing compiler ,
I
can determine which library modules (if
any) are required and can thus select a
minimal subset of modules for link-editing
,I!EffieieRt Performance
t
with the compiled code. IBecause of the modularity of the PL/I
,libraries and the wide range of
This selection of library modules loptimization performed by the optimizing
lminimizes the main storage requirements of I compiler, many PL/I application programs
Ithe program. It can also cause a reduction Iwill have acceptable performance and will
lin the time requred to load the program Inot require 'tuning' by the programmer.
linto main storage - often an important f
Iconsideration in DB/DC environments. I This section suggests ways in which the
I Iperformance of programs that do not fall
I -tinto the above category may be improved.
I ,IThe section is divided into three parts,
ITHE SYSTEM ENVIRONMENT ·,arranged in order of increasing effort
I Irequired by the programmer to effect the
I
The PL/I libraries can be organized in a
number of different ways within the system
,
timprovements.
I It is assumed that system considerations
environment in which the PL/I programs are Ihave been resolved (for example, the
executed. lorganization of the PL/I libraries), and
falso that the reader has some knowledge of
The library modules that are required Ithe compile-time and execution-time
for initializing and terminating a PL/I Icompiler options (see the Programmer's
program are normally part of the transient IGuide for the compiler).
library. They can, however, be link-edited I
with the object module. This technique can f
Significantly reduce the time taken to I
initialize and terminate execution of a ITUNING A PL/I PROGRAM - STAGE 1
PL/I program, at the expense of the
program's main storage requirements. ,
I
I 1. Remove all debuggin~ aids from the
An installation can place commonly-used I program.
resident library modules into a shared .I
library, so that the same module can be The overheads incurred by some
accessed by any PL/I program executing in debugging aids (for example, the CHECK
the system. Using a shared library may condition prefix) are immediately
increase slightly the execution time of the obvious because they tend to produce
PL/I programs; however, the overall storage lar~e amounts of output. However,
requirements can be reduced if a number of debugging aids such as the
PL/I programs are required to execute SOBSCRIPTRANGE and STRINGRANGE
concurrently. condition prefixes, or the FLOW
compiler option, which produce output
Default execution-time options, based on only when an error occurs, also
Ithe overall requirements of the significantly increase both the
I installation, can be chosen at the time storage requirements and the execution
Ithat the compiler is installed. These may time of the program.
Ibe overridden for individual programs by
I means of the PLIXOPT variable. -I PUT DATA statements should also be
1 : 1 removed from the program, especially
I Program products such as IMS/VS give the·. I those for which no data list is
luser the ability to specify a list of I specified. These statements require

262 as PL/I CKT AND OPT LRM PART I

 control blocks to describe the efficient performance is to look for those
variables and library modules to language features that are inherently
convert their values to external expensive for any compiler to implement,
format, both of which increase the and for which alternative language exists.
program's storage requirements. This type of attention is of most benefit
in heavily-used parts of the program, as
Use of the GOSTMT or GONUMBER compiler identified by the statement frequency table
option will not increase the execution produced by the COUNT compiler option.
time of the progr~, but will increase
its storage requirements. The It is important to realize, however,
overhead is approximately 4 bytes per that a particular use of the language is
PL/I statement for GOSTMT and Inot necessarily bad just because it is less
approximately 6 bytes per PL/I lefficient than some other usage; it must be
statement for GONUMBER. Ireviewed in the context of what the program
lis doing now and what it will be required
2. Specify execution-time options in the Ito do in the future.
PLIXOPT variable, rather than as I
parameters passed to the program I Some examples of language features which
initialization routines. It may prove lare inherently expensive are given below:
beneficial to alter existing programs f
to take advantage of the PLIXOPT i 1. A common programming practice is to
variable, and to recompile them. I put,the format list used by edit-
1 directed input/output statements into
3. After removing the debugging aids, I a FORMAT statement. The FORMAT
compile and execute the program with statement is then referenced from the
the REPORT execut~on-time option. The input/output statement by means of the
output from the REPORT option will R format item. For example:
give the size that should be specified
in the ISASIZE execution-time option DECLARE NAME CHARACTER(20),
to enable all PL/I storage to be MANNO DECIMAL FlXED(S,O);
obtained from a single allocation of
system storage. PUT EDIT (MANNO,NAME)(RCOUTFORM»;
Note: For a full description of the
output from the REPORT option, see the OUTFORM:FORMAT(FC8),X(S),AC20»;
Programmer's Guide for the compiler.
programming in this way reduces the
The program should also be separately level of optimization that the
compiled and executed with the COUNT compiler is able to provide for edit-
compiler option, and the statement directed input/output. If the format
frequency tables used to compare the list is repeated in each input/output
program with the original design. If -I statement,
there is a conflict between the I
original design and the way in which I PUT EDIT CMANNO,NAME)
the program works, this should be f (F(8),X(S),A(20»;
resolved before further attempts are I
made to improve performance. I the compiler is able to generate more
I efficient compiled code which calls
The COUNT option output may also be 'I fewer library modules, with a
used to identify heavily-used sections I consequent saving in execution time
of the program for additional tuning I and load module size.
if this should prove necessary. I
I 2. The use of self-defining data (the
I REFER option) enables data to be held
I I in a compact form; it can, however,
ITUNING A PL/I PROGRAM - STAGE 2 f lead to the production of less-than-
I I optimum compiled code. For example,
I I with the structure:
lIn PL/I there are often several different I
Iways of producing a given effect. One of I DECLARE 1 STR BASED(P),
Ithese ways will usually be more efficient I 2 N,
Ithan another, depending largely on the f 2 BEFORE,
lmethod of implementation of the language I 2 ADJUST (NMAX REFER(N»,
Ifeatures concerned. The difference may be 1 2 AFTER;
lonly one or two machine instructions, or it I
Imay be several hundred. I a reference to BEFORE requires one
I 'I instruction to address the variable,
I The second stage of tuning a program for I whereas a reference to AFTER requires

Chapter 18: Efficient programming 263

 approximately 18 instructions plus a overhead.
call to a resident library module.
This recommendation should be
The most efficient way of organizing a assessed in conjunction with the
self-defining structure is to ensure notes on modular programming given
that the members whose lengths are later in this chapter.
known appear before any adjustable
members, and that the most frequently b. If a GOTO statement references a
used adjustable members appear before label variable, it will be more
those that are less frequently used. efficient if the label constants
The previous example could thus be that are the values of the label
changed to: variable appear in the same block
as the GOTO statement.
DECLARE 1 STR BASED(P),
2 N, c. The PL/I language does not allow
2 BEFORE, the use of the INITIAL attribute
2 AFTER, for arrays that have the
2 ADJUST (NMAX REFER(N»; attributes STATIC and LABEL
because environment information
3. Even though a condition has been for the array does not exist until
explicitly disabled by means of a execution time.
condition prefix, a lot of processing
may be required if a situation occurs However, when using the optimizing
in which the condition would normally compiler to compile procedures
be raised. For example, consider a containing STATIC LABEL arrays,
random number generator in which the improved performance may be
previous random number is multiplied Obtained by specifying the INITIAL
by some factor and the effects of attribute. What happens under
overflow are ignored: these conditions is described
below.
DECLARE (RANDOM, FACTOR)
FIXED BINARY(31,O); The compiler diagnoses the invalid
language (STATIC, LABEL, and
(NOFOFL):RANDOM=RANDOM*FACTOR; INITIAL) and produces message
IEL0580I, but it accepts the
If the product of RANDOM and FACTOR combination of attributes. If
cannot be held as FIXED BINARY(31,O), OPT (TIME) is specified, GO TO
a program check interrupt will be statements that refer to STATIC
produced. This has to be processed by LABEL variables are checked to see
both the system interrupt handler and whether the value of the label
the PL/I error handler before it can variable is a label constant in
be determined that the FIXEDOVERFLOW the same block as the GO TO
condition has been disabled. statement. If it is, the normal
interpretative code produced by
the compiler is replaced by direct
branching code. If it is not,
TUNING A PL/I PROGRAM - STAGE 3 message IEL0918I is produced and
the interpretative code remains
unchanged.
This stage is really a refinement of the
ideas given previously in stage 2. If NOPT is specified, or if
However, whereas stage 2 was concerned with message IEL0918I is produced,
potential savings of hundreds of execution is liable to terminate
instructions, this stage concerns savings with an interrupt, or go into a
of only a few instructions. Again, the loop.
measures that are described are most
effectively applied to the heavily-used d. If pOSSible, avoid using on-units
parts of the program. for the FINISH condition. These
I cause an increase in the time
I 1. The following measures apply to taken to terminate a PL/I program.
I program control:
I e. After debugging, disable any
I a. Avoid unnecessary program normally-disabled conditions that
I segmentation and block structure; were enabled for debugging
I all procedures, on-units, and purposes by removing the relevant
I begin blocks need prologues and prefixes, rather than by including
I epilogues, the initialization and NO-condition prefixes. For
I housekeeping for which carry an instance, disable the SIZE

264 OS PL/I CKT AND OPT LRM PART I

 condition by removing the SIZE should contain three decimal
prefix, rather than by adding a digits, and neither ONSOURCE nor
NOSIZE prefix. The former method ONCHAR is used to correct invalid
allows the compiler to eliminate data, then:
code that checks for the
condition, whereas the latter
method necessitates the generation
of extra code to prevent the
checks being carried out. DCL EXTREP CHARACTER(3),
INTREP FIXED DECIMAL (5,0);
f. Avoid the use of constant
expressions for array bounds and ON CONVERS ION GOTO ERR;
string lengths: the compiler will
assume that the variable is INTREP = EXTREP,
adjustable.
is less efficient than:
DECLARE A(S):
is more efficient than
DCL EXTREP CHARACTER ( 3) ,
DECLARE A(5+3): PICREP PIC '999' DEF EXTREP,
INTREP FIXED DECIMAL (5,0),
2. The following measures apply to
conversions, which should in general
be kept to a minimum. IF VERIFY(EXTREP,'0123456789')
~= 0 THEN GOTO ERR,
a. The section on in-line operations INTREP = PICREP,
which appears later in this
chapter describes which
conversions are done in-line.
f. Internal switches and counters,
b. Use additional variables to avoid and variables used as array
conversions. For example, subscripts, should be declared
consider a program in which a FIXED B!NARY. Data required for
character variable is to be output should in general be
regularly incremented by 1. declared DECIMAL.
DECLARE CTLNO CHARACTER(S),
g. Exercise care in specifying the
precision and scale factor of
CTLNO = CTLNO + 1, variables that are used in
expressions. The use of variables
This example requires two with different scale factors in an
conversions (one of which involves expression can cause the
a library call), while generation of additional object
code to create immediate temporary
DECLARE CTLNO CHARACTER(S), values.
DCTLNO FIXED DECIMAL;
3. The following measures apply to
DCTLNO =
DCTLNO + 1, strings:
CTLNO = DCTLNO,
requires only one conversion. a. The section on in-line operations
which appears later in this
c. Take special care to make chapter discusses those string
structures match when it is operations that are done in line.
intended to move data from one
structure to another.
b. Bit strings Should, if pOSSible,
d. Avoid mixed mode arithmetic, be specified, and tested, as
especially the use of character multiples of eight bits. However,
strings in arithmetic bit strings used as logical
calculations. switches should be specified
according to the number of
e. Use pictured data rather than Switches required. In the
character data if possible. For following examples, (a) is
example, if a piece of input data preferable to (b), and (b) to (c):

Chapter 18: Efficient Programming 265

·f EXlample 1: be necessary for a PL/I library
I routine to access adjacent
i Single switches storage, as well as the string
t itself. If another task accesses
f (a) DCL SW BIT(l) INIT('l'B); this adjacent storage at the same
·f time, then the results may be
·f unpredictable. The problem is
IF SW THEN DO; less likely to arise with aligned
;,f bit strings than unaligned.
of
(b) DCL SW BIT(S) INIT('l'B); c. Note that concatenation operations
f• on bit-strings are time-consuming.
•I: IF SW THEN DO; d. Varying-length strings are
generally less efficient than
t fixed-length strings.
I·
I (c) DeL SW BIT(S) INIT ('l'B);
,
I
1 IF SW = '10000000'B THEN
e. Fixed-length strings are not
efficient if their length is not
known at compile'time, as in the

,,
l
·f
DO; following example:
DCL A CBAR(N);

t f. Do not refer.to the DATE built-in

Example 2: function more than once in a run;
I.f Multiple switches
it is expensive. Instead, refer
to the funct~on once and save the
.J value in a variable for subsequent
t (a) DeL B BIT(3); use; for example, instead of:
1
I PAGEA= TITLEAIIDATE;
t B = 'lll'B; PAGEB= TITLEBIIDATE;
I
I it is more efficient to write
I IF B = '111'B THEN DO;
t DTE=DATE;
I. PAGEA=TITLEAIIDTE;
I (b) DeL B BIT(S); PAGEB=TITLEBIIDTE;
,
f
I B = '11100000'B;
4. The fOllowing measures apply to
input/output:
,t
I
IF B = '11100000'B THEN DO
a. Allocate sufficient buffers to
prevent the program beCOming I/O
I bound, and use blocked output
I records.
t
1 (c) DeL (SWl,SW2,SW3) BIT(l); However, consideration must be
t given to the imp~ct on other
t programs executing within the
t SW1, SW2, SW3 = 'l'B; system.
f b. Open a number of files in a single
t
f IF SW1'SW2'SW3 THEN DO: OPEN statement.
1
I c. In STREAM input/output, u.se long
I data lists instead of splitting up
t If bit-string data whose length is input/output statements.
not a multiple of S is to be held

.
tl
f
t
~
in structures, such structures
should be declared ALIGNED.
Note: The use of bit strings in a
mul~itasking program can
d.

e.
Use edit-direct input/output in
preference to list- or data-
directed •
Consider the use of overlay
.
t
0Ccasionally cause incorrect
resUlts. When the program
defining to simplify transmission
to or from a character string
t: references the bit string, it may structure. For example:
 DCL 1 IN, specify FS or FBS record format,
2 TYPE CHAR(2), whenever possible.
2 REC,
3 A CHAR(S), 5. The following measures apply to
3 B CHAR(7), interlanguage communication:
3 C CHAR(66);
GET EDIT(IN) a. Where poSSible, ensure that PL/I
(A(2),A(S),A(7),A(66»; aggregate arguments will be mapped
the same as those for COBOL or
In the above example, each format- FORTRAN.
item/data-field pair is matched
separately, code being generated b. The compiler cannot always detect
for each matching operation. It when a structure in PL/I and COBOL
would be more efficient to define will map identically. Each
a character string on the element in the base structure has
structure and apply the GET an alignment requirement; for
statement to the string: example, a CHAR(4) item can be
aligned on any byte in main
DCL STRNG CHAR(SO) DEF IN; storage, whereas a FIXED BIN(31)
item must be fullword aligned.
The compiler creates a dummy
argument for the structure
GET EDIT (STRNG) (A(SO»; whenever the first base element
has a less stringent alignment
f. If a file is declared DIRECT requirement than any other base
INDEXED, the ENVIRONMENT options element. This rule is applied
INDEXAREA, NOWRITE, and ADD BUFF independently to each minor
should be applied if possible. structure at level 2. The NOMAP
option should be specified if the
g. When creating or accessing a actual lengths of items do not
CONSECUTIVE data set, use file and require padding bytes to be
record variable declarations that inserted. For example:
cause in-line code to be
generated, if possible. Details DeL 1 5,
of the declarations are given in 2 X CHAR(4),
chapter 12, "Record-Oriented 2 Y FIXED BIN(31);
Transmission· •
The compiler will create a dummy
h. Conversion of source keys for argument for this structure
REGIONAL data sets can be avoided because Y has a greater alignment
if the following special cases are stringency than X. However, the
observed. structure will map identically in
PL/I and COBOL because no padding
(1) For REGIONAL(l): When the is required.
source key is a fixed binary
element variable or constant, c. When arguments do map differently,
use precision in the range use the NOMAPIN option to avoid
(12,0) to (23,0). unnecessary initialization of
dummy arguments, and use the
(2) For REGIONAL(2) and (3): When NOMAPOUT option to avoid
the source key is of the form unnecessary assignment from dummy
(character-string- arguments if the final value is
expressionllr), where r is a not required (e.g_, if the value
fixed binary element variable is unchanged).
or constant, use precision in
the range (12,0) to (23,0). d. Avoid multiple initialization of
the PL/I environment by ensuring:
i. Direct update of an INDEXED data
set is slowed down if an I/O (1) that the main procedure is
operation on the same file PL/I, or
intervenes between a READ and a
REWRITE for the same key. This (2) that a PL/I procedure is
can cause the REWRITE statement to called from the main routine,
issue an extra READ. or
j. When creating or accessing a data (3) that the structure of the
set having fixed-length records, program is such that the PL/I
use standard formatting, that is, environment is not destroyed

Chapter lS: Efficient programming 261

 between calls to PLII I certain pages.
procedures. I
I By deSigning and programming modular
6. The following measures apply to the I programs, it may be possible to achieve
use of storage when storage Ifurther tuning of progams for a virtual
conservation is an important factor: Istorage system.
I
a. Use the UNALIGNED attribute to I To enable the compiler to produce the
obtain denser packing of data with Imost advantageous output, care must be
a minimum of padding. Itaken both in how the source code is
Iwritten and how the data is declared.
b. If a DIRECT UPDATE file is used to I
access an INDEXED data set, but no I In writing source code large branches
records are to be added to the laround the program should be avoided.
data set, specify the NOWRITE IStatements that are frequently executed
option in the ENVIRONMENT Itogether should be placed in the same
attribute for the file. This Isection of the source program.
option will save data management I
approximately 5000 bytes of I In declaring data, the most important
storage. [aspect is the handling of data aggregates
Ithat are considerably larger than the page
c. Avoid the use of iterative do- Isize. Care should be taken that items
groups with multiple Iwithin the aggregate that are accessed
specifications. The following is together are held together. In this
inefficient in terms of storage situation the choice between arrays of
requirements: structures and structures of arrays may be
critical. Consider an aggregate containing
DO I = 1,3,7,15,31; 3000 members and each member consisting of
a name and a number. If it is declared:

,
I
END; DCL 1 A( 3000),
2 NAME CHAR(14),
2 NUMBER FIXED BINARY;
,
I
ITUNING A PROGRAM FOR A VIRTUAL STORAGE
the 100th name would be held adjacently
with the lOOth number and so they could
I SYSTEM easily be accessed together. However, if
I i t is declared:
I
IThe output of the optimizing compiler is DCL 1 A,
Iwell suited to the requirements of a 2 NAME(3000) CHAR(14),
Ivirtual storage system. The executable 2 NUMBER(3000) FIXED BINARY;
code is read-only and is separate from the
data which is itself held in discrete all the names would be held contiguously
segments. For these reasons there is followed by all the numbers, thus the 100th
usually little cause to tune the program to name and the 100th number would be widely
reduce paging. Where such action is separated.
essential, a number of steps can be taken.
However, it should be borne in mind that When choosing the storage class for
the effects of tuning are usually small. variables there is little to choose between
STATIC INTERNAL and AUTOMATIC. The storage
The object of tuning for a virtual where both types of variable are held is
storage system is to minimize the paging, required during execution for reasons other
that is to reduce the number of times the than access to the variables. The storage
data is moved from auxiliary storage into used for based or controlled variables is
main storage and vice-versa. This can be not however required and avoiding these
done by making sure that items that are storage classes may reduce paging.
accessed together are held together and by
making as many pages as possible read only. Complete control of the positioning of
variables can be obtained by declaring them
When using the optimizing compiler the BASED within an AREA variable. All
problem can be approached both by writing variables held within the area will be held
the source program so that the compiler I together.
Iwill produce the most advantageous use of I
Ivirtual storage and, if further tuning is I A further refinement is possible that
,required, by using linkage editor lincreases the number of read only pages.
Istatements to manipulate the output of the IThis is to declare STATIC INITIAL only
Icompiler so that certain items appear on Ithose variables that remain unaltered

268 OS PL/I CKT AND OPT LRM PART I

 throughout the program and to declare the Some of the general benfits that can
procedure in which they are contained result from modular programming are
REENTRANT. If this is done, the static outlined below:
internal CSECT produced by the compiler
will be made read-only, with a consequent • Program size affects the time and space
reduction in paging overhead. required for compilation. Generally,
compilation time increases more than
To produce code that can be manipulated linearly with program size, especially
by linkage editor statements, it is if the compiler has to spill text onto
necessary to understand that the compiler auxiliary storage. Also, the process of
output is a series of CSECTS (control adding code to a program and then
sections) and that these are the units that recompiling it leads to wasteful
are manipulated by the linkage editor. You multiple-compilation of existing text.
can control the linkage editor so that the
CSECTS you specify will be placed together • A procedure designed to perform a singl8
either within pages or so that a particular function need only contain the data
CSECT will be placed at the start of a areas for that function. Because of the
page. The linkage editor statements to do nature of AUTOMATIC storage, there is
this are given in the publication OS/VS less danger of data areas for other
Linkage Editor and Loader, Order No. GC26- fUnctions being corrupted.
3813.
• If a procedure is designed to perform a
The optimizing compiler always produces single function, it can be more easily
at least two CSECTs for every external replaced by a different version. Also,
procedure. One CSECT contains the the same procedure may be useful in
executable code and is known as the program several different applications.
CSECT, the other CSECT contains addressing
data and static internal variables and is • The storage for all the automatic
known as the static CSECT. In addition, it variables in a procedure is allocated
produces a CSECT for every static external when the procedure is invoked at any of
variable. A number of other CSECTs are its entry points. By reducing the
produced for housekeeping purposes. (A number of functions performed by a
full description of compiler output is procedure, it is often possible to
given in the publication OS PL/I Optimizing reduce the number of variables declared
Compiler: Execution Logic, Order No. in the procedure. This in turn can
SC33-002S. ) reduce the overall demand for storage
for automatic variables.
You can affect the number of CSECTs
produced by the compiler by declaring More important from the efficient
variables STATIC EXTERNAL and by making programmdng viewpoint are the following
procedures external thus getting a CSECT considerations.
for each external variable and a program
CSECT and a static internal CSECT for each 1. The compiler has a limitation on the
external procedure. It is possible to number of variables that it can
place a number of variables in one CSECT by consider for global optimization.
declaring them BASED in an AREA that has (Note that the number of variables
been declared STATIC EXTERNAL. does not affect other forms of
optimization.)
When a program is divided into a
satisfactory arrangement of CSECTs it is 2. The compiler has a limitation on the
then possible to analyze the use of the number of flow units that it can
CSECTS and arrange them to minimdze paging. consider for flow analysis and
It should be realized however t.hat this is subsequently for global optimization.
a difficult and time consuming operation
Iwhich should not be undertaken lightly. 3. If the static CSECT or the DSA exceeds
I 4096 bytes in Size, the compiler has
I to generate additional code to address
I the more remote storage.
t
IMODULAR PROGRAMMING 4. If the compiled code for a procedure
I exceeds 4096 bytes in size, the
I compiler may have to repeatedly reset
IAlthough it is possible to write a program base registers.
las a Single external procedure, it is often
Isensible to split the program into a number IExtra invocation of procedures will cause
lof smaller sections, or modules. In PL/I, lexecution time to be increased, but the use
Ithe basic units of modularity are the lof modular programming will often offset
Iprocedure and the begin block. Ithe increase because the additional

Chapter 18: Efficient Programming 269

 r---------------------------------------------------------------------------------------,
Conversion 1 I
--------------------------------------1
Source Target 1
Comments and Conditions I
I
FIXED BINARY I
I
FIXED DECIMAL I
I
FIXED BINARY FLOAT ILong or short FLOAT target.
I
Bit string IString must be fixed-length, ALIGNED, and with
Ilength ~2088. STRINGSIZE condition must be
I disabled.
I
Character string IVia FIXED DECIMAL. String must be fixed-length
or Numeric Picturelwith length ~256 and STRINGSIZE disabled.
IPicture types 1, 2 or 3 when SIZE disabled.
FIXED BINARY
FIXED DECIMAL
FIXED DECIMAL FLOAT If Q1+P1~75. Long or short-FLOAT target.
Bit String String must be fixed-length, ALIGNED, and with
length ~2088. STRINGSIZE Condition must be
disabled.
Character string If precision = scale factor, it must be even.
string must be fixed-length and length ~256.
STRINGSIZE must be disabled.
Numeric picture Picture types 1, 2 and 3.
IFIXED BINARY
I
IFIXED DECIMAL Scale factor <80.
I
FLOAT (Long or I FLOAT Source and target may be single or double length
Short) I
I
IBit string String must be fixed-length, ALIGNED, and with
I length ~2088. STRINGSIZE condition must be
I disabled.
IFIXED BINARY Isource string must be fixed-length, ALIGNED,
I land with length ~32.
I I
Bit string IFIXED DECIMAL 'Source must be fixed-length, ALIGNED, and with
land FLOAT Ilength <32.
I I
\Character string ISource must be fixed-length, ALIGNED, and lengthl
I Ii only. I
---------------------------------------------------------------------------------------1
IBit string I I
I I I
IFIXED DECIMAL ISource length 1 only. CONVERSION condition I
Character I Imust be disabled. I
I FLOAT I I
I I I
I IFIXED BINARY I I
I L---------------------------------------------------------------------------------------J
I
IFigure 18.1 (Part 1 of 2). Implicit data conversion performed in-line

270 OS PL/I CKT AND OPT LRM PART I

r---------------------------------------------------------------------------------------,
1 Conversion 1
1--------------------------------------1
1 Source 1 Target I
comments and Conditions

1---------------------------------------------------------------------------------------
1 ICharacter string IString must be fixed-length with length ~256.
ICharacter Picture 1 I
1 ICharacter Picture IPictures must be identical.
1---------------------------------------------------------------------------------------
1 IFIXED BINARY IVia FIXED DECIMAL. SIZE condition disabled.
1 1 1
I IFIXED DECIMAL IType 2 pictures without * or embedded
1 1 1punctuation. SIZE condition disabled.
INumeric Picture I I
Itype 1 and 2 1FLOAT IVia FIXED DECIMAL. SIZE condition disabled.
1 I 1
1 INumeric Picture IPicture types 1, 2 or 3. SIZE condition
1 I I disabled.
1---------------------------------------------------------------------------------------
ILabel 1Label I
1---------------------------------------------------------------------------------------
____________________________________________________ ----------------------------------J
IL-locator I locator I

Figure 18.1 (Part 2 of 2). Implicit data conversion performed in-line

optimization can cause Significantly fewer For in-line conversions, pictures with
instructions to be executed. this subset of characters are divided into
three types:

Picture type 1: Pictures of all 9s with

In-Line Operations (optionally) a V and a leading or
trailing sign. For example:

Many operations are handled in-line. It , 99V999' , , 99' , 'S99V9',

will repay the user, therefore, to
recognise which operations are performed , 99V+ " '$999'
in-line and which require a library call,
and to arrange his program to use the Picture: type 2: pictures with zero
former wherever possible. The majority of suppression characters and
these in-line operations are concerned with (optionally> punctuation
data conversion and string handling. characters and a sign character.
Also, type 1 pictures with
punctuation characters. For
example:
Data Conversion
'ZZZ', '**/**9', 'ZZ9V.99',

The data conversions performed in-line are '+ZZ.ZZZ·, '$///99', '9.9'

shown in figure 18. A conversion outside
the range or condition given is performed Picture type 3: Pictures with drifting
by a library call. strings and (optionally>
punctuation characters and a sign
Not all the picture characters available character. For example:
may be used in a picture involved in an in-
line arithmetic conversion. The only ones • $$$$', '-, --9', • S/SS/S9 ' ,
permitted are:
'+++9V.9' " $$$9-'
V and 9
Sometimes a picture conversion is not
Drifting or non-drifting characters $ performed in-line even though the picture
S + is one of the above types. This may be
because:
Zero suppression characters Z *
Punctuation characters , . / B 1. SIZE is enabled and could be raised.

Chapter 18: Efficient Programming 271

r---------------------------------------------------------------------------------------,
, String operation 1 Comments and Conditions I
,------------------------------------------------------_·_------------------------------1
1 I Source I Target 1 Comments I
I
Assign
1--------------------------------------------------------------------
INon-adjustable. ALIGNED. INon-adjustable.INo length restriction
Ifixed-Iength bit string IALIGNED. bit lif OPTIMIZE(TIME) is
I I string I specified; otherwise
I I Imaximum length of
, I 181 92 bits
1--------------------------------------------------------------------
IAdjustable or VARYING, I Non-adjustable, I Only if OPTIMIZE(TIME)
IALIGNED bit string IALIGNED bit lis specified
I Istring S 20Q8 I
I I bits I
1--------------------------------------------------------------------
I Non-adjustable, UNALIGNED, I (same as IOnly if OPTIMIZE(TlME)
Ifixed-Iength bit string I source) lis specified. Maximum
Ithat is an element of an I Ilength = 57 bits
I AUTOMATIC, BASED, or STATIC I I
Istructure with nO adjustable I I
lbounds or extents I I
1---------------------------------------------------------------~----
,Non-adjustable, fixed-lengthINon-adjustable I
Icharacter string I character I
1 I string I
1--------------------------------------------------------------------
IAdjustable or VARYING INon-adjustable ,
Icharacter string I character ,
I Istring of I
I Ilength S 256 I
'and', 'not', 'or'IAs for bit string assignments, but no adjustable or varying-length
loperands are handled

Compare lAS for string assignment with the two comparands taking the roles of
Isource and target, but no adjustable or varying-length operands are
I handled

Concatenate lAS for string assignments, but no adjustable or varying-length

Isource strings are handled

STRING function ,Element variables and non-adjustable array and structure variables
lin connected storage.

I Notes: 1. the maximum lengths specified refer to the lengths of operations rather than,
I operands. If the target is fixed-length, the operation length is the target I
I length. If the target is VARYING, the operation length is the lesser of the I
I operand lengths. I
I I
I 2. UNALIGNED bit strings that are parameters, defined variables, or part of I
I
L-----________________________________________________ ----------------------------------J
aggregate variables are not handled. I

Figure 18.2. Conditions under which string operations are handled in-line

272 OS PL/I CKT AND OPT LRM PART I

 2. There is no overlap between the digit
positions in the source and target.
r-----------------------------------------,
String I Comments and Conditions I
For example: Function I I
DECIMAL (6,8) or DECIMAL (5,-3) to PIC
-----------------------------------------1
BIT IAlways I
'999V99' will not be performed I I
BOOL IThe third argument must be a 1
3. The picture may have certain Iconstant. The first two I
characteristics that make it difficult larguments must satisty the I
to handle in-line. example: Iconditions for 'and', 'or', andl
I'not' operations in fig 18.2. I
a. punctuation between a drifting Z I I
or a drifting * and the first 9 is C~ Ihl~~ 1
not preceded by a V. For example: 1 1
HIGH 1Always 1
'ZZ.99' 1 I
INDEX ISecond argument must be a 1
b. Drifting or zero suppression Inon-adjustable character string
characters to the right of the 1<256 characters long
decimal point. For example: I
LENGTH 1Always
'ZZV.ZZ', '++V++' I
LOW 1Always
I
REPEAT ISecond argument must be
string Handling 1constant
I
SUBSTR ISTRINGRANGE must be disabled
IThe string functions and operations I
Iperformed in-line are shown in figures 18.2 TRANSLATEIFirst argument must be
land 18.3. It should be noted that even the Ifixed-Iength, second and third
Istring functions indicated as always being larguments must be constant
Iperformed in-line may sometimes call a I
Ilibrary routine. For example, if the UNSPEC I Al ways
lexpression in the BIT or CHAR functions I
Irequires an implicit conversion not handled 1VERIFY IFirst argument must be
lin-line, the appropriate library routines I 1fixed-length: if CHARACTER it
Iwill be called. 1 Imust be S256 characters, if BITI
I I lit must be ALIGNED, S2048 bits. I
I I Isecond argument must be 1
I 1 I constant I
I L----------------------------------_______ J
I
I Global Optimization Features Figure 18.3. Conditions under which
I string functions are
I handled in-line
ICOMMON EXPRESSIONS
1
I
IThe term "common expression" is used to
Idescribe an expression such as B+C in:
I
I A = B+C
I
I
I
I D = B+C
I
lin which the variables Band C are not
Ireset between the two occurrences of the

Chapter 18: Efficient programming 273

expressions. In a case like this i t is not lof a computational interrupt, either in the
necessary to evaluate the expression more lassociated on-unit, or as the result of the
than once. lexecution of a branch from the on-unit,
Icommon expression elimination is inhibited.
The technique of avoiding repeated IFor example:
evaluation of the same expression is called I
common expression elimination. I ON ZERODIVIDE B,C=l;

An important application of common

expression elimination occurs in statements
containing subscripted variables where the X=A*B+B/C:
same subscript value is used for each Y=A*B+D:
variable. For example:
The compiler would normally attempt to
PAYROLL TAX(MANNO) = PAY_CODE(MANNO) * eliminate the re-evaluation of the sub-
WEEKPMNT(MANNO); expression A*B in the second assignment
statement. However, in this example, if
The value of the subscript expression MANNO the ZERODIVIDE condition is raised during
is computed once only when the statement is the evaluation of B/C the two values for
executed (the computation would involve the A*B would be different. This optimization
conversion of a value from decimal to is inhibited to allow for this possibility.
binary if MANNO were declared a decimal
variable) . Note that the above discussion applies
only when the optimization option ORDER is
specified or assumed. If the programmer
does not require the guarantees described
Interrupt Handling for Programs with above, the optimization option REORDER can
Common Expression Elimination be specified. In this case, common
expression elimination is not inhibited.
The ORDER and REORDER opt~ons are discussed
The order of most operations in each PL/I later in this chapter.
statement is dependent on the priority of
the operators involved. However, the order
of evaluation of those sub-expressions
whose results form the operands of TRANSFER OF INVARIANT EXPRESSIONS OR
operators of lower priority, such as STATEMENTS
subscript expressions, locator qualifier
expressions, and function references, is
not defined beyond the rule that an operand An expression or statement occuring within
must be fully evaluated before its value a loop is said to be invariant if the
can be used in another operation. compiler can detect that the expression
ITherefore on-units associated with Ivalue or statement action would be
linterrupts which occur during the lidentical for each iteration of the loop.
levaluation of such sub-expressions can be I
lentered in an unpredictable order. ( An invariant expression or statement can
I Consequently, an expression might have Ibe moved from within a loop to a point in
Iseveral possible values, according to the the program outside the loop, so that it is
lorder of, and action taken by, the on-units executed once only, rather than for each
that are entered. When a computational on- iteration of the loop. For example:
unit is entered:
DO I = 1 TO N:
1. The values of all variables set by the
execution of previous statements are
guaranteed to be the latest values
aSSigned to the variables, and can be J = 3;
used by the on-unit. For instance the
PUT DATA statement can be used to
record the values of all variables on
entry to an on-unit. END;
2. The value of any variable set in an IThe statement J=3 is invariant and can be
on-unit resulting from a computational Imoved outside the loop. It can be moved
interrupt is guaranteed to be the (forwardS or backwards, according to
latest value assigned to the variable, I circumstances.
for any part of the program. I
I If the programmer wishes to take
Where there is a possibility that ladvantage of this type of optimization, he
variables might be modified as the result Imust specify the optimization option

214 OS PL/I CKT AND OPT LRM PART I

IREORDER on a BEGIN or PROCEDURE block which executed once only, either before or after
Icontains the loop with reorderable the loop.
Istatements or operations. If the option is
Inot specified, the default option ORDER is More efficient execution of loops can be
lassumed and the optimization is inhibited. achieved by maintaining in registers the
I values of variables which are subject to
I frequent modification during the execution
I of the loops. When error-free execution
IORDER AND REORDER OPTIONS permits, values can be kept in registers,
I and considerable efficiency can be achieved
I by dispensing with time-consuming load-and-
IORDER and REORDER are optimization options store operations to reset the values of
Ispecified for a procedure or begin block in variables in their storage locations. If
la PROCEDURE or BEGIN statement. Ithe latest value of a variable is required
I lafter a loop has been executed, the value
I The default is ORDER, but REORDER is lis assigned to the storage location of the
linherited by all contained blocks unless Ivariable when control passes out of the
Ithey explicitly specify ORDER. Iloop.

,
I
I
I
I Register allocation can be more

,
IORDER Option

I
ISignificantly optimized if REORDER is
Ispecified for the plock. However, the
Ivalues of variables that are reset in the
Iblock are not guaranteed to be the latest
'The ORDER option should be specified for a lassigned values when a computational
Iprocedure or begin block if the programmer linterrupt occurs, since the latest value of
Irequires that the most recently assigned la variable may be present in a register but
Ivalues of variables that are modified in Inot in the storage location of the
Ithe block are guaranteed for use in On- I variable. ThUS, anyon-unit entered for a
lunits entered because of computational Icomputational interrupt must not refer to
linterrupts during the execution of Ivariables set in the reorder block.
Istatements and expressions in" the block. I However, use of the built-in functions
lIn a block to which the ORDER option 10NSOURCE and ONCHAR is still valid in this
,applies, common expreSSions may be I context.
leliminated by the compiler. If so, the I
,occurrence of computational interrupts I A program is in error if during
,during execution of the block may be less lexecution there is a computational or
Ithan would occur if common expressions had Isystem action interrupt in a REORDER block
Inot been eliminated. However, if an Ifollowed by the use of a variable whose
linterrupt occurs during execution of an Ivalue is not guaranteed.
'ORDER block, the values of variables in I
Istatements which precede the interrupt are I Since these restrictions preclude the
Iguaranteed to be the most recent values Icorrection of erroneous data, except by
lassigned when reference is made to them in lusing ONSOURCE and ONCHAR pseudovariables
Ithe on-unit for the interrupt. Other forms Ifor a CONVERSION on-unit, the programmer
lof optimization are permitted in an ORDER Imust either depend on the standard system
Iblock except for forward or backward move- 'action, thereby terminating execution of
lout of any expression which can cause an Ithe program, or use the on-unit to perform
I interrupt. Since it would be necessary to lerror recovery and to restart execution by
Idisable all the possible conditions which lobtaining fresh data for computation. The
Imight be encountered, the use of ORDER Isecond approach should ensure thqt all
Ivirtually suppresses any move-out of Ivalid data is processed, and that invalid
,statements or expressions from loops. data is noted, while still taking advantage
I of any possible optimization. For example:
I
I ON OVERFLOW PUT DATA;
,
IREORDER Option DO J = 1 TO M;
DO I = 1 TO Ni
X(I,J) = Y(I) + Z(J) *L + SQRT(W)i
I
'The REORDER option permits the compiler to P = I*Ji
Igenerate optimized code to produce the END;
'result specified by the source program, END;
Iwhen error-free execution takes place.
'Move-out is permitted for any invariant When the above statements appear in a
,statements and expressions from inside a reorder block, the source code compiled is
Iloop to a pOint in the source program interpreted as follows:
leither preceding or following such a loop.
IThus the statement or expression is ON OVERFLOW PUT DATA;

Chapter 18: Efficient Programming 215

 TEMP1 = SQRTCW)i loperational expressions. The
DO J = 1 TO Mi Isimplifications are as follows:
TEMP2 = Ji lexpressions such as 3*B are transformed
DO I = 1 TO Ni linto B+B+B; and in subscript expressions,
X(I,J) = Y(I) +Z(J)*L+TEMP1i lexpressions such as 1+2 are transformed
P=TEMP2; linto I*MULT+2*MULT where MULT is a constant
TEMP2=TEMP2+Ji Imultiplier. The 2*MULT is then used as an
END; loffset factor in the addressing
END; I calculations.
I
TEMP1 and TEMP2 are temporary variables I
created to hold the values of expressions I
moved backwards out of the loops, and the ITAKING ADVANTAGE OF GLOBAL OPTIMIZATION
statement P=I*J can be simplified to P=N*M. I
If an overflow interrupt occurs, the values I
of the variables used in the loops cannot IThis section contains details of coding
be guaranteed to be the most recent values Ipractices whiCh should be observed or
assigned before the occurrence of the lavoided in order to take advantage of the
interrupt, since the current values may be 19lobal optimization facilities offered by
held in registers, and not in the storage luse of the OPTIMIZE(TIME) compiler option.
location to which the on-unit must refer. I
I
Although this example does not show it, I
Ithe subscript calculations for x, Y, and Z ICommon Expression Elimination
Iwill also be optimized. I
I I
I Common expression elimination is inhibited
I by.:
IELIMINATION OF REDUNDANT EXPRESSIONS
I 1. The use in expressions of variables
I whose values can be reset in either an
A redundant expression is an expression input-output or computational on-unit.
that need not be evaluated in order to
continue executing the program correctly. 2. If a based variable is, at some point
in the program, overlaid on top of a
The effect of this optimization is to make variable used in the common
the use of logical expressions in IF expression, then assigning a new value
statements more efficient than a series of to the based variable in between the
nested IF statements. For &xample: two occurences of the common
expression, inhibits optimization.
IF (A = D) I (C = D) THEN
X = Y + Zi For instance, the common expression
X+Z, in the follOWing example, is not
is more efficient, in terms of space eliminated because the based variable
occupied by object code, than: A which, earlier in the program, is
overlaid on the variable X, is
IF A = D THEN X = Y+Z; aSSigned a value in between the two
ELSE IF C=D THEN X = Y + Zi occurences of X+Z.
If A or C does equal 0, the THEN clause in DeL A BASF;D(P);
the first example is executed, without the P=ADDR(X) ;
expression ever being resolved to a single
bit.
P=ADDR(Y) i

EXPRESSION SIMPLIFICATION B=X+Zi

P->A=2i
C=X+Zi
Expression simplification is the process of
changing the form of source statement 3. The use of aliased variables. An
expressions without changing the intended aliased variable is any variable whose
effect so that they can be compiled into value can be modified by references to
more efficient object code. identifiers other than its own
identifier. Examples are variables
TWO forms of expression simplification are with the DEFINED attribute, variables
carried out by the compiler. Both involve used as the base for defined
the use of arithmetic constants in variables, parameters, arguments, and

216 OS PL/I CRT AND OPT LRM PART I

 based variables. units is determined. A flow unit is a
unit of compiled code that can only be
variables whose addresses are known to entered at the first instruction and
an external procedure by means of left at the last. A flow unit may
pOinters that are either external or contain several PL/I source
used as arguments are also assumed to statements; conversely, a single PLiI
be aliased variables. source statement may comprise several
flow units. Common expressions are
The effect of an aliased variable is recognized across individual flow
not to prevent common expression units. However, if the program flow
elimination completely, but to inhibit paths between flow units are complex,
it slightly. For all aliased the recognition of common expressions
variables the compiler builds a list is inhibited across flow units.
of all the variables which could
possibly reference the aliased Common expression elimination is assisted
variable. The list is the same for by thes e points:
each member of the list, and in a
given program there may be many such 1. Variables in expressions should not be
lists. external or associated with external
pointers, or arguments to ADDR built-
When an expression containing an in functions.
aliased variable is being checked for
its use as a common expression, the 2. The source program should not contain
possible flow paths along which external procedures, external label
related common expression could occur variables, or label constants known to
are searched for assignments, not only external procedures.
to the variable referenced in the
expression, but also for all the 3. Variables in expressions should not be
members of the alias list to which set or accessed in on-units if
that variable belongs. If the program possible.
contains an external pOinter variable,
it is assumed that this pOinter could 4. Expressions to be commoned or
be set to all variables whose transferred must be arithmetic (for
addresses are known to external example A+B) or string (for example
procedures, that is, all external EIIF or STRING(G) rather than
variables, all arguments passed to compiler generated.
external procedures, and all variables
whose addresses could be assigned to
the external pointer. Thus variables
addressed by the external pointer, or Transfer of Invariant Expressions
by any other pOinter which has a value
assigned to it from the external
pointer, are assumed to belong to the Transfer of invariant expressions out of
same alias list as the external loops is inhibited by:
variables, etc.
1. ORDER specified for the block.
4. The form of an expression. If the However, transfer is not entirely
expression B+C could be treated as a prevented by the ORDER option. It is
common expression, the compiler would only inhibited for operations which
not be able to detect it as a common can cause computational interrupts.
expression in the following statement: Such operations do not include array
subscript manipulation where the
D=A+B+C; subscripts are represented by binary
halfword integers; such subscripts
The compiler processes the expression cannot cause overflow unless they are
A+B+C from left to right. uninitialized, in which case the
consequently it only recognizes the program is in error anyway.
expressions A+B and (A+B)+C. However,
by coding the expression D=A+(B+C), 2. The use of variables whose values can
the programmer can ensure that it is be set or used by input or output
recognized, since the compiler must statements.
process the expression with the
highest priority first. 3. The use of variables whose values can
be set in input/output or
5. The scope of a common expression. In computational on-units, or which are
order to determine the presence of aliased variables.
common expressions, the program is
analyzed and the existence of flow 4. A complicated program flow, involving

Chapter 18: Efficient programming 211

 external procedures, external label Common Errors and Pitfalls
variables and label constants.

Transfer is assisted by: This is a list of the errors and pitfalls

most likely to be encountered when writing
1. Specifying REORDER for the block a PL/I source program. Some of the items
concern misunderstood or overlooked
2. Avoidance of points 2-4 above language rules, while others result from
failure to observe the implementation
conventions and restrictions.

The warnings apply particularly to

IRedundant Expression Elimination programs compiled by the optimizing
I compiler. Although a source program which
I is in error under the optimizing compiler
Redundant expression elimination is will in general be in error under the
inhibited or assisted by the same factors checkout compiler as well, the checkout
as for transfer of invariant expressions, compiler detects many of the errors listed
described above. and takes appropriate action.

OPERATING SYSTEM AND JOB CONTROL

other Optimization Features

A STATIC variable in an overlay segment

Optimized code can be generated for the could be overwritten during an overlay
following items: operation unless it is contained in the
root segment.
1. For a do-loop control variable except
when its value can be modified either
explicitly or by an on-unit during
execution of a do-loop. SOURCE PROGRAM AND GENERAL SYNTAX

2. For do-loops that do not contain other

do-loops, provided that, if the scope 1. Transcription errors may occur unless
of the control variable extends beyond particular care is taken when writing
the block containing the do-loop, then the following characters:
i t is given a definite value after the
do-loop and before the end of the 1 (numeral), I (letter) , I (or),
block. / (slash), , (quotation mark)~

3. For assignment of arrays or structures (not), 7 (seven) ,

unless non-contiguous storage is used. > (greater than) ;
4. For array initialization where the L (letter) , < (less than) •
same value is assigned to each element
unless the array occupies non- 0 (letter) , 0 (zero) ;
contiguous storage.
S (letter) , 5 (five);
5. For in-line conversions unless they
involve complicated picture or Z (letter) , 2 (two);
character to arithmetic conversions.
(break character),
6. For in-line code for the string built- - (minus sign) ~
in functions SUBSTR and INDEX unless
the on-conditions STRINGSIZE or 2. Ensure that the source program is
STRINGRANGE are enabled. completely contained within the
margins specified by the MARGINS
7. For register allocation and addressing option.
schemes unless the program flow is
complicated by use of external 3. Inadvertent omission of certain
procedures, external label variables, symbols may give rise to errors that
or label constants known to external are difficult to trace. Common errors
procedures. Optimized register usage are: unbalanced quotation marks:
is also inhibited by the use of unmatched parentheses; unmatched
alia sed variables and variables that comment delimiters (e.g., 1* instead
are referenced or set in an on-unit. of */ when closing a comment); and

278 OS PL/I CKT AND OPT LRM PART I

 missing semicolons. are a common source of error. For
example, a comma must follow the entry
4. Reserved keyword operators in the 48- for each element in a structure
character set (e.g., GT, CAT) must in declaration.
all cases be preceded and followed by
a blank or comment. 3. External identifiers should not
contain more than seven characters.
5. Care should be taken to ensure that
END statements correctly match the 4. In a PICTURE declaration, the V
appropriate DO, SELECT, BEGIN, and character indicates the scale factor,
PROCEDURE statements. but does not in itself produce a
decimal point on output. The pOint
6. In some situations, parentheses are picture character produces a point on
required when their necessity is not output, but is purely an editing
immediately obvious. In particular, character and does not indicate the
the expression following WHILE, UNTIL, scale factor. In a decimal constant,
and RETURN must be enclosed in however, the point does indicate the
parentheses. scale factor. For example:

DCL A PIC'99.9',
B PIC'99V9',
PROGRAM CONTROL C PIC'99.V9':
A,B,C=4!>.6:
PUT LIST (A,B,C):
1. The procedure to be given initial
control at execution time must have This will cause the following values
the OPTIONS(~.IN) attribute. If more to be put out for A, B, and C,
than one procedure has the MAIN respectively:
option, the first one encountered by
the linkage-editor gets control. 04.5 456 45.6

2. When a procedure of a program is If these values were now read back

invoked while it is still active in into the variables by a GET LIST
the same task, it is said to be used statement, A, B, and C would be set to
recursively. Under the optimizing the following respective values:
compiler, attempting the recursive use
of a procedure that has not been given 004 5b.O 4~. 6
the RECURSIVE attribute may result in
a program interrupt after exit from If the PUT statement were then
the procedure. This will occur if repeated, the result would be:
reference is made to automatic data of
an earlier invocation of the 00.4 560 4~. 6
procedure.
5. Separate external declarations for the
3. When a procedure may be invoked while same identifier must not specify
it is still active in another task, conflicting attributes, either
the REENTRANT option must be explicitly or by default. If this
specified. occurs the compiler will not be able
to detect the conflict.

If the INITIAL attribute is specified

DECLARATIONS AND ATTRIBUTES for an external identifier, it must be
specified, with the same value, on all
the declarations for that identifier.
1. DECLARE statements for AUTOMATIC An exception to this rule is that an
variables are in effect executed at INITIAL attribute specified for an
entry to a block: sequences of the external identifier in a procedure
following type should not be used: compiled by the optimizing compiler
need not be repeated elsewhere.
A: PROC:
N=4: 6. An identifier cannot be used for more
DCL B(N) FIXED: than one purpose within its scope.
Thus, the use of X in the following
sequence of statements would be in
error:
END:
PUT FILE (X) LIST (A,B,C):
2. Missing commas in DECLARE statements X=Y+Z:

Chapter 18: Efficient programming 219

 X: M=N: DCL L FIXED: /*L IS FIXED DECIMAL
(5,0) REAL
AUTOMATIC*/
7. The prec1s1on of decimal integer
constants should be taken into account 10. The precision of complex expressions
when such constants are passed. For is not obvious. For example, the
example: precision of 1 + 11 is (2,0), that is,
the precision follows the rules for
CALL ALPHA(6): expression evaluation.

ALPHA: PROCEDURE (X) : 11. When a procedure contains more than

DCL X FIXED DECIMAL: one entry point, with different
END: parameter lists On each entry, make
sure that no references are made to
If ALPHA is an external procedure, the parameters other than those associated
above example is incorrect because X with the point at which control
will be given default preciSion (5,0), entered the procedure. For example:
while the constant, 6, will be passed
with preciSion (1,0). A: PROCEDURE(P,Q):
P=Q+ 8: RETURN:
8. When a data item requires conversion B: ENTRY(R,S):
to a dummy, and the called procedure R=P+S: /*THE REFERENCE TO P
alters the value of the parameter, IS AN ERROR*/
note that the dummy is altered, not END:
the original argument. For example:
12. Based storage is allocated in terms of
DCL A FIXED, doublewords: therefore, even for the
B FLOAT: smallest item, at least eight bytes
CALL X(A,B): are required.

X:PROC(Y,Z): 13. The variable used in the REFER option

DCL (Y,Z) FIXED: must be referred to unambiguously.
Y=Z**100: /*A IS ALTERED IN For example:
CALLING PROC*/
Z=Y**3: /*B IS UNALTERED IN DCL 1 A,
CALLING PROC*/ 2 Y FIXED BIN,
END X: 2 Z FLOAT,
1 B,
9. When the attributes for a given 2 Y FIXED BIN,
identifier are incompletely declared, 2 T(l:N REFER(B.Y»;
the rest of the required attributes
are supplied by default. The In any references to this declaration,
following default assumptions should Y must be fully qualified to prevent a
be carefully noted. possible ambiguity.

FLOAT DECIMAL(6) REAL is assumed for 1q. Conflicting contextual declarations

implicitly declared arithmetic must be avoided. P is often used as
variables, unless the initial letter the name of a pOinter: it must not,
is in the range I through N, when therefore, assume by default the
FIXED BINARY(lS,O) REAL is assumed. characteristics of another data type.
For example:
If a variable is explicitly declared
and any of the base, scale, or mOde DCL B BASED (P),
attributes is specified, the others
are taken from the set
FLOAT/DECIMAL/REAL. For example:
P AUTO,
DCL I: /*1 IS FIXED BINARY
(15,0) REAL
AUTOMATIC*/ .,
DCL J REAL; /*J IS FLOAT DECIMAL The explicit declaration of P is
(6) REAL processed first by the compiler and
AUTOMATIC*/ the default attributes, FLOAT and
DECIMAL are added; the contextual
DCL K STATIC: /*K IS FIXED BINARY declaration of P is then conflicting.
(15,0) REAL
STATIC*/ 15. Parameters may not be given one of the

280 OS PL/I CKT AND OPT LRM PART I

 storage class attributes AUTOMATIC, A=O;
BASED, or STATIC; a parameter must
either be CONTROLLED or have nO Note that this problem can also occur
storage class. under the optimizing compiler as a
result of CHECK system action for an
uninitialized array. If the CHECK
condition were enabled for the array
AND INITIALIZATION in the above example, and system
action were taken, the results, and
the way in which the program
1. When a variable is accessed, it is terminates, would be unpredictable.
assumed to have a value which has been The same problem arises when PUT DATA
previously assigned to i t and which is is used.
consistent with the attributes of the
variable. If this assumption is 3. Note the distinction between =
incorrect, either the program will (assignment) and = (comparison). The
proceed with incorrect data or a statement
program interrupt will occur. Such a
situation can result from failure to A=B=C;
initialize the variable, or it can
occur as a result of the variable means ·compare B with C and assign the
having been set in one of the result (either 'l'B or 'O'B) to A,
following ways: performing type conversion if
necessary."
a. by the use of the UNSPEC
pseudovariable q. Assignments that involve conversion
should be avoided if possible (see
b. by record-oriented input "Arithmetic and Logical Operations"
later in this chapter).
c. by overlay defining a picture on a
character string, with subsequent 5. In the case of initialization of or
assignment to the character string aSSignment to a fixed length string:
and then access to the picture if the aSSigned value is shorter than
the string, it is extended on the
d. by passing as an argument a right with blanks (for a character
variable assigned in a different string) or zeros (for bit strings).
procedure, without matching the For example:
attributes of the parameter.
DCL A CHAR(6),
e. by aSSignment to a based variable B CHAR(3) INIT('CR'):
with different attributes, but at A=B:
the same location.
After the execution of the above
Failure to initialize a variable will statements, B would contain CRb, and A
result in the variable having an would contain CRbbbb.
unpredictable value at execution time.
Do not assume this value to be zero. 6. It is not possible to reference a
cross section of an array of
Failure to initialize a subscript can structures; the whole of an array of
be detected by enabling structures, or a single element may be
5UBSCRIPTRANGE, when debugging the referenced, but not a cross section.
program (provided the uninitialized
value does not lie within the range of 7. When SIZE is disabled, the result of
the subscript). an aSSignment which would have raised
SIZE is unpredictable:
2. Under the optimizing compiler, any
attempt to put out a variable or array FIXED BINARY: The result of an
that has not been initialized may well aSSignment here -- which includes, for
cause a data interrupt to occur. For instance, source language assignments
example: and the conversions implied by
parameter matching may be to raise
DCL A(10) FIXED; FIXEDOVERFLOW.
A(1)=10:
PUT LIST (A); FIXED DECI~~L: Truncation to the
nearest byte may occur, without
To avoid the data interrupt, the array raising an interrupt. If the target
should be initialized before the preciSion is even, an extra digit may
assignment statement, thus: be inserted in the high-order byte.

Chapter 18: Efficient programming 281

ARITHMETIC AND LOGICAL OPERATIONS c. The rules for arithmetic to bit
string conversion affect
assignment to a bit string from a
1. The rules for expression evaluation decimal constant:
should be carefully noted, with
particular reference to priority of
operations. The following examples DeL A BIT(l),
show the kind of mistake that can o BIT(S);
occur: A=l: /*A HAS VALUE 'O'B*/
0=1: /*0 HAS VALUE '00010'B*/
X>YIZ is not equivalent to X>YIX>Z but D='l'B; /*0 HAS VALUE
is equivalent to (X>Y)IZ '10000'B*/
IF A=l THEN GO TO Y:
X>Y>Z is not equivalent to X>Y&Y>Z but ELSE GO TO X;
is equivalent to (X>Y»Z

All operation sequences of equal The branch will be to X, because

priority are evaluated left to right, the assignment to A resulted in
except for **, prefix +, prefix -, and the following sequence of actions:
~, which are evaluated right to left.
Thus, the statement
(1) The decimal constant, 1, is
assumed to be FIXED DECIMAL
(1,0) and is assigned to
is equivalent to temporary storage with the
attributes FIXED BINARY(4,0),
A=B**(-(C**D»; taking the value 0001S:

The normal use of parentheses is to

modify the rules of priority; however, (2) This value is now treated as a
it may be convenient to use redundant bit string of length (4), so
parentheses as a safeguard Or to that it becomes 'OOOl'B;
clarify the operation.

2. Conversion is governed by (3) The resultant bit string is

comprehensive rules which must be assigned to A. Since A has a
thoroughly understood if unnecessary declared length of 1, and the
trouble is to be avoided. Some value to be assigned has
examples of the effect of conversion acquired a length of 4,
follow. truncation occurs at the
right, and A has a final value
a. DECIMAL FIXED to BINARY FIXED can of 'O'B.
cause unexpected results if
fractions are involved:
To perform the comparison
DCL I FIXED BIN(31,S) INIT(l); operation in the IF statement,
I = 1+.1; 'O'B and 1 are converted to FIXED
BINARY and compared
The value of I is now 1.0625. arithmetically. They are unequal,
This is because .1 is converted to giving a result of "false" for the
FIXED BINARY(S,4), so that the relationship A=l.
nearest binary approximation is
O.OOOlB (no rounding occurs). The
decimal equivalent of this is In the first assignment to D, a
.062S. A better result would have sequence of actions similar to
been achieved by specifying .1000 that described for A takes place,
in place of .1. except that the value is e~ended
at the right with a zero, because
b. If arithmetic is performed on D has a declared length that is 1
character string data, the greater than that of the value to
intermediate results are held in be assigned.
the maximum fixed decimal
precision (lS,O): d. Assignment of arithmetic values to
character strings involves
DCL A CHAR(6) INIT('123.4S'); conversion according to the rules
DCL B FIXED(5,2); given in section F, -Data
B=A; /*B HAS VALUE 123.45*/ Conversion and Expression
B=A+A; / *B BAS VALUE 246.00*/ Evaluation- •

282 OS PL/I CRT AND OPT LRM PART I

 Example 1 be necessary to write

DCL A CHAR(4), 25+01/3

B CHAR(?);
A='O'; /*A HAS VALUE 'Obbb'*/ The explanation is that constants
A=O; /*A HAS VALUE 'bbbO'*/ have the precision and scale
B=1234567; /*B HAS VALUE factor with which they are
'bbb1234'*/ written, while FIXED division
results in a value of maximum
Note: The three blanks are implementation-defined precision.
necessary to allow for the The results of the two evaluations
possibility of a minus sign, a are reached as follows:
decimal or binary point, and
provision for a Single leading
zero before the pOint.
r---------------------------------,
I precn/I
I Scale I
Example 2 Item I Factor Result

DCL CTLNO CHAR(8) INIT{'O'); 1 (1,0) 1

DO 1=1 TO 100; 3 (1,0) 3
CTLNO=CTLNO+l; 1/3 (15,14) 0.33333333333333
2!> (2,0) 25
25+1/3 (15,14) undefined
(truncation on
END; left:
FIXEDOVERFLOW
In this example, a conversion would be raised
error occurs because of the unless disabled)
following sequence of actions:
01 (2,0) I 01
(1) The initial value of CTLNO, 3 (1,0) 1 3
that is, 'Obbbbbbb'i is 01/3 (15,13)100.3333333333333
converted to FIXED 25 (2,0) 1 25
DECIMAL{15,0). 25+01/3 (15,13)125.3333333333333

(2) The decimal constant, 1,

L---------------------------------J
assumed to be FIXED Alternatively, the PRECISION
DECIMAL(l,O), is added: in built-in function could be used:
accordance with the rules for
addition, the precision of the 25+PREC(1/3,15,13)
result is (16,0).
f. Checking of a picture is performed
(3) This value is now converted to only on assignment into the
a character string of length picture variable:
18 in preparation for the
assignment back to CTLNO. DCL A PIC'999999',
B CHAR(6) DEF A,
(4) Because CTLNO has a length of C CHAR(6);
8, the assignment causes B= ' ABCDEF' :
truncation at the right; thus, C=A; /*WILL NOT RAISE CONV
CTLNO has a final value that CONDITION*/
consists entirely of blanks. A=C; /*WILL RAISE CONV*/
This value cannot be
successfully converted to Note also (A, B, C as declared
arithmetic type for the second above):
iteration of the loop.
A=123456: /*A HAS VALUE
e. FIXED division can result in 123456*/
unexpected overflows or /:ljcB HAS VALUE
truncation. For example, the '123456' */
result of evaluating the C=123456; /*C HAS VALUE
expression 'bbb123 '*/
C=A; /*C HAS VALUE '123456'*/
25+1/3
g. A FIXED DECIMAL element with a
would be undefined and declared even precision (P,Q) may
FIXEDOVERFLOW would be raised. To have an effective precision of
obtain the correct result it would (P+1,Q), as the high-order byte

Chapter 18: Efficient Proqramming 283

 may not be non-zero. The SIZE 4. do-groups cannot be used as on-units;
condition can be used to eliminate a BEGIN block must be used for an on-
this effect: unit of more than one statement.

DCL (A,B,C) FIXED DECIMAL (6,0);

ON SIZE; 5. Upper and lower bounds of iterative do
groups are computed once only, even if
the variables involved are reassigned
within the group. This applies also
(SIZE): A =B + C; to the BY expression.

This ensures that the high-order

byte of A is zero after the Any new values assigned to the
assignment. variables inyolved would take effect
only if the:do-group were started
again.

DO-GROUPS 6. In a do-group with both a control

variable and a WHILE option, the
evaluation and testing of the WHILE
1. The scope of a condition prefix expression is carried out only after
applied to a DO statement is limited determination (from the value of the
to execution of the statement itself; control variable) that iteration may
it does not apply to execution of the be performed. For example, the
entire group. following group would be executed at
most once:
2. An iterative do-group is not executed
if the terminating condition is DO 1=1 WHILE (X>Y) ;
satisfied at initialization:

1=6:
DO J=I TO 4; END;
X=X+J;
END; 7. I is frequently used as the control
variable in a do-group, for example:
X is not altered by this group, since
BY 1 is implied. Iterations can step DO 1=1 TO 10;
backwards, and if BY -1 had been
specified, three iterations would have Within the scope of this implicit
taken place. declaration, I might be contextually
declared as a pointer, for example:
3. Expressions in a DO statement are
assigned to temporaries with the same DCL X BASED (I) ;
characteristics as the expression, not
the variable. For example: The two statements are in conflict and
will produce a diagnostic message.
DCL A DECIMAL FIXED(S,O); When I is a pointer variable, it can
A=10; only be used in a do-group in one of
DO 1=1 TO A/2; the following ways:

a. DCL (I, lA, IB, IC) POINTER;

END;

This loop will not be executed, DO I=IA,IB,IC;

because A/2 has decimal precision
(15,10), which, on conversion to b. DeL (I, IA) POINTER;
binary (for comparison with I),
becomes binary (31,34).

Five iterations would resu1t if the DO DO WHlLE(I=IA);

statement were replaced by
8. If the control variable is used as a
ITEMP=A/2; subScript within the do-group, care
DO 1=1 TO ITEMP; must be taken not to let the variable
or run beyond the bounds of the array
DO 1=1 TO PREC(A/2,6,1) dimension. For instance:

284 OS PL/I CKT AND OPT LRM PART I

 DECLARE A(10): 2. Note the effect of array
DO I = 1 TO N: multiplication:

DCL (A, B, C) ( 10 I 10 ) ;

ACI) = X:

A=B*C:

END: This does not affect matrix

multiplication: it is equivalent to:
If N is greater than 10 then the
assignment statement may overwrite DCL (A,B,C) (10,10);
data beyond the storage allocated to
the array A. Such a bug can be
difficult to find, particularly if the
overwritten storage happens to contain DO 1=1 TO 10:
object code. The error can be DO J=l TO 10:
detected by enabling SUBSCRIPTRANGE. A(I,J)=B(I,J}*C(I,J):
END: END:

i STRINGS
I
DATA AGGREGATES
1. Assignments made to a varying string
by means of the SUBSTR pseudovariable
1. Array arithmetic should be thought of do not set the length of the string.
as a convenient way of specifying an A varying string initially has an
iterative computation. For example: undefined length, so that if all
assignments to the string are made
DeL A(10,20): using the SUBSTR pseudovariable, the
string still has an undefined length
and cannot be successfully assigned to
another variable or written out.
A=A/AC1,1):
2. The user must ensure that the lengths
has the same effect as of intermediate results of string
expressions do not exceed 32767 bytes.
DCL A(10,20): This applies particularly to strings
of varying lengths, as there is nO
object-time length checking.

DO 1=1 TO 10:
DO J=l TO 20:
A(I,J}=A(I,J)/A(l,l): FUNCTIONS AND PSEUDOVARIABLES
END: END:
Note that the effect is to change the 1. When UNSPEC is used as a
value of A(l,l) only, since the first pseudovariable, the expression on the
iteration would produce a value of 1 right is converted to a bit string.
for A(l,l). If the programmer wished consequently, the expression must not
to divide each element of A by the be invalid for such conversion: for
original value of A(l,l), he could example, if the expression is a
write character string containing characters
other than 0 or 1, a conversion error
B=A(l,l): will result.
A=A/B:

or alternatively,
ION-CONDITIONS AND ON-UNITS
DCL A(10,20), I
B(10,20}: I
I 1. Note the correct poSitioning of the ON
I statement. If the specified action is
I to apply when the named condition is
B=A/A(l,l}: I raised by a given statement, the ON

Chapter 18: Efficient programming 285

 statement must be executed before that INPUT/OUTPUT
statement. The statements:

1. The UNDEFINEDFILE condition is raised

GET FILE (ACCTS) LIST (A,B,C): not only by conflicting language
ON TRANSMIT (ACCTS) GO TO TRERR: attributes (such as DIRECT with
PRINT), but also by the following:

would result in the ERROR condition a. Block size smaller than record
being raised in the event of a size (except when records are
transmission error during the first spanned).
GET operation, and the required branch
would not be taken (assuming that no b. LINESIZE exceeding thE permitted
previous ON statement applies). maximum.
Furthermore, the ON statement would be
executed after each execution of the c. KEYLENGTH zero or not specified
GET statement. for creation of INDEXED,
REGIONAL(2), or REGIONAL(3) data
sets.
2. An on-unit cannot be entered by means
of a GOTO statement. To execute an d. Specitying a KEYLOC option, for an
on-unit deliberately, the SIGNAL INDEXED data set, with a value
statement can be used. resulting in KEYLENGTH + KEYLOC
exceeding the record length.

3. CONVERSION on-units entered as a e. Specifying a V-format logical

result of an invalid conversion (as record length of less than 18
opposed to SIGNAL) should either bytes for STREAM data sets.
change the invalid character (by means
of the ONSOURCE or ONCHAR f. Specitying, for FB-format blocked
pseudovariable), or else terminate records, a block size which is not
with a GOTO statement. Otherwise, the an integral multiple of the
system will print a message and raise recordsize.
the ERROR condition.
g. Specifying, for VB-format records,
a logical record length that is
4. At normal exit from an AREA on-unit not at least four bytes smaller
the standard system action is to try than the specified block size.
again to make the allocation. As a
result the on-unit will be entered 2. If a file is to be used for both input
again, and an indefinite loop will be and output, it must not be declared
created. To avoid this, the amount with either the INPUT or the OUTPUT
allocated should be modified in the attribute. The required option can be
on-unit, for example, by using the specified on the OPEN statement.
EMPTY built-in function or by changing
a pointer variable. 3. Input/output lists must be surrounded
by a pair of parentheses: so must
5. Do not use on-units to implement the iteration lists. Therefore, two pairs
program's logic: use them only to of outer parentheses are required in
recover from truly exceptional
conditions. Whenever an on-unit is GET LIST «ACI) DO 1=1 TO N»;
entered, considerable error-handling
overheads are incurred. To implement 4. The last eight bytes of a source key
the logic, the programmer should to access a regional data set must be
perform the necessary tests, rather the character string representation of
than relying on the compiler's a fixed decimal integer. When
condition-detecting facilities. generating the key, the rules for
arithmetic to character string
For example, in a program using conversion should be considered. For
record-oriented output to a keyed data example, the following group would be
set, the programmer might wish to in error:
eliminate certain keys because they
would not fit into the limits of the DCL KEYS CHAR(8):
data set. He may rely on the raising DO 1=1 TO 10:
of the KEY condition to detect KEYS=I:
unsuitable keys, but it is WRITE FILE (F) FROM (R)
considerably more efficient tor him to KEYFROM (KEYS):
test each key himself. END:

286 OS PL/I CKT AND OPT LRM PART I

 The default for I is FIXED tll. Strings used as input data for GET
BINARY(15,0), which requires not 8 but t DATA and GET LIST must be enclosed in
9 characters to contain the character t quotation marks.
string representation of the I
arithmetic values. t 12 • The 48-character representation of a
I semicolon (,.) is not recognized as a
I semicolon if it appears in a data-
S. Note that the file must have the KEYED I directed input stream; the 11-8-6
attribute if the KEY, KEYFROM, or I punch must be used.
KEYTO options are to be used in any I
input/output statement referring to 13. The user must be aware of a limitation
that file. of PUT DATA; (i.e., without a data
list): its effect when used with an
6. The standard file names SYSIN and ON statement is restricted because the
SYSPRINT are implicit only in GET and data known to PUT DATA would be the
PUT statements. Any other reference, data known at the pOint of the on-
such as those in ON statements or unit.
record-oriented input/output
statements, must be explicit. If the ON statement

1. PAGESIZE and LINESIZE are not file ON ERROR PUT DATA;

attributes, that is, they cannot be
included in a declaration for the is used in an outer block, it must be
file; they are options on the OPEN remembered that variables in inner
statement. blocks are not known and therefore
will not be dumped. It would be a
8. When an edit-directed data list is good practice, therefore, to repeat
exhausted, no further format items the on-unit in all inner blocks during
will be processed, even if the next debugging.
format item does not require a
matching data item. For example: If an error occurs during execution of
the PUT DATA statement, and this
DCL A FIXED (5) , statement is within an ERROR on-unit,
B FIXED(S,2); the program will recursively enter the
GET EDIT (A,B) (F(S),F(5,2),X(10»; ERROR on-unit until no more storage
remains. Since this could be wasteful
The X(10) format item will not be of machine time and printout, the
processed. To read a following card ERROR on-unit should be turned off
with data in the first ten columns once it is entered. Instead of:
only, the SKIP option can be used:
ON ERROR PUT DATA:
GET SKIP EDIT (A,B) (F(S), F(S,2»;
better code would be:
9. The number of data items represented
by an array or structure name ON ERROR BEGIN;
appearing in a data list is equal to ON ERROR SYSTEM:
the number of elements in the array or PUT DATA;
structure; thus if mqre than one END;
format item appears in the format
list, successive elements will b~ When PUT DATA is used without a data-
matched with successive format items. list every variable known at that
For example: pOint in the program is transmitted in
data-directed output format to the
DCL 1 A, specified file. Users of this
2 B CHAR(S), facility, however, should note that:
2 C FIXED(S,2);
a) Uninitialized FIXED DECIMAL data
may raise the CONVERSION condition
or a data interrupt.
PUT EDIT (A) (A(S),F(S,2»;
b) Unallocated CONTROLLED data will
B will be matched with the A(S) item, cause arbitrary values to be
and C will be matched with the F(S,2) printed and, in the case of FIXED
item. DECIMAL, may raise the CONVERSION
condition or a data interrupt.
10. Arrays are transmitted in row major
order (e.g., A(l,l), A(1,2), A(1,3), 14. A pointer set in READ SET or LOCATE
A ( 2 , 1), ••• etc. ) SET is not valid beyond the next

Chapter 18: Efficient programming 281

 operation on the file, or beyond a transmission of a record is attempted.
CLOSE statement. In OUTPUT files,
WRITE and LOCATE statements can be
freely mixed. This is:

When i t is required to rewrite a When there is insufficient room in

record that has been read into a the specified region to output the
buffer (using a READ SET statement record on a REGIONAL(3) V- or u-
that specifies a SEQUENTIAL UPDATE format file. Neither the record
file) and then updated, the REWRITE raising the condition nor the
statement without a FROM option may be current record is transmitted.
used. The result of a REWRITE after a
READ SET is always to cause the If a LOCATE is the last I/O statement
contents of the last buffer to be to be executed before the file is
rewritten onto the data set. For closed, the record is not transmitted
example: and the condition may be raised by the
CLOSE statement.
3 READ FILE (F) SET (P);
15. If a reference is made, at object
time, to a based variable that has nOt
been allocated storage, an
5 P->R = S; unpredictable interrupt (protect-ion,
addressing, or specification) may
occur.

1 REWRITE FILE (F); 16. Areas, pOinters, offsets and

structures containing any of these
cannot be used with STREAM I/O.

11 READ FILE (F) INTO (X); 111. When a based variable is freed, the
I associated pOinter no longer contains
I useful information.
I
15 REWRITE FILE (F); 18. A based variable allocated in an area
must be freed in that area. For
example:

19 REWRITE FILE (F) FROM (X); DCL A AREA, B BASED (X);

ALLOCATE B IN (A);
Notes:

Statement 1 will rewrite a record

updated in the buffer. FREE B; /* INVALID * /
FREE B IN (A); /* VALID */
Statement 15 will not change the
record on the data set at all. 19. The alignment in the buffer of the
first byte of the first record in a
statement 19 will raise ERROR, since block that has been read from an ASCII
there is no preceding READ statement. data set is not necessarily on a
doUbleword. The block prefix is
There is one case where it is not doubleword aligned, but the alignment
possible to check for the KEY of the first record depends on the
condition on a LOCATE statement until length of the block prefix.

288 OS PL/I CRT AND OPT LRM PART I

 Chapter 19: Interlanguage Communication Facilities

The PL/I interlanguage facilities permit PL/I. Assigning a value to one variable
communication, at execution time, between causes the same valUE to be assigned to the
programs compiled by the PL/I checkout and other. TherE is no similar equivalence in
optimizing compilers and programs compiled COBOL - no COBOL variable can have common
by one of the following compilers, and storage with a PL/I variable other than as
executed using the corresponding library. an argument or parameter.
The compilers and libraries have all been
developed by IBM for os. The interlanguage facilities are
entirely provided by the PL/I compiler;
I Program program No. they are obtained by specifying the
I appropriate language items in the invoking
lOS FORTRAN IV Compiler or invoked PL/I procedure. Existing COBOL
I (H Extended) 5734-F02 or FORTRAN programs or routines generally
lOS FORTRAN Library Mod I 5734-LM1 do not need modification or recompiling for
lOS FORTRAN Library Mod II 5734-LM3 interlanguage use; new programs or routines
I can be written in these languages and
lOS FULL ANS COBOL (Version 4) compiled as before, without the need to
I Compiler and Library 5736-CB2 antiCipate interlanguage communication.
I (Library only) 5736-LM2 Thus existing COBOL or FORTRAN application
IOS/VS FULL·ANS COBOL Compiler programs can be extended by the use of PL/I
I and Library 5746-CB1 procedures, while COBOL or FORTRAN
I (Library only) 5746-LM4 libraries can be made available to new or
existing PL/I procedures.
Communication between a PL/I program,
and a program compiled by one of the ~ In the context of this Chapter,
FORTRAN or COBOL compilers, can be achieved "routine" includes a COBOL subprogram, or a
in two ways: FORTRAN subroutine or function, including a
FORTRAN library function. The conventions
1. By using a conversion data set for the that exist in these languages for handling
PL/I and COBOL/FORTRAN routines. subroutines and fUnctions apply normally,
and are not modified for interlanguage use.
2. By invoking a COBOL/FORTRAN routine In particular, the restriction that a
from a PL/I routine, or vice versa, FORTRAN function cannot be invoked without
and by passing data either as passing an argument or arguments still
arguments or in the form of static applies when the invocation is from a PL/I
storage. routine.

If a common data set is used to

communicate between a PL/I and a COBOL
routine, the COBOL option of the
ENVIRONMENT attribute may be required. For Interlanguage Facilities
further details, see the section "Data
Interchange (COBOL)" in chapter 12.
While a detailed knowledge of COBOL or
A PL/I procedure can invoke a COBOL FORTRAN is not essential for use of the
routine by use of the CALL statement, or interlanguage facilities, the programmer
can invoke a FORTRAN routine by use of the may need to be aware of the equivalents in
CALL statement or a function reference. data organization in PL/I and the other two
Alternatively, a PL/I procedure can be languages. These equivalents must be
invoked by use of the corresponding understood in order to achieve
1anguage features in a COBOL or a FORTRAN argument/parameter matching.
main program or routine. Arguments can be
passed on invocation, and a value can be The interlanguage facilities
returned for function references. automatically resolve differences in the
mapping for equivalent data organizations,
A COMMON block in FORTRAN has storage when matching arguments and parameters; the
equivalent to that of a STATIC EXTERNAL programmer can, if he wishes, override this
variable in PL/I. If a COMMON block and a action.
STATIC EXTERNAL variable are given the same
name, then they will be allocated the same Facilities are provided to extend PL/I
block of storage, in the same way as two interrupt-handling to cover invoked COBOL
identical STATIC EXTERNAL variables in or FORTRAN routines.

Chapter 19: Interlanguage Communication Facilities 289

Passing Arguments to a COBOL or FORTRAN Note: The COBOL option in the ENVIRONMENT
Routine attribute can be specified for a file that
is to be used in certain input/output
operations. Although this option initiates
When an argument is passed to a COBOL or a remapping of PL/I structures, it is in no
FORTRAN routine, the data type is way associated with the interlanguage
determined in the normal PL/I manner, that facilities described here: a file with this
is, from the parameter descriptor list of option cannot be used as a file argument or
the associated entry declaration, or from a file parameter. For use of the COBOL
the argument itself. The inter language option of the ENVIRONMENT attribute, see
facilities ensure, however, that the "ENVIRONMENT Attribute" in chapter 12,
addressing mechanism for the argument is "Record-Oriented Transmission."
that used by the invoked language, and
that, unless otherwise required, the Data-mapping: In order that an argument
mapping of any aggregates passed is that can be successfully passed to a COBOL or
used by the invoked language. Note that FORTRAN routine, the mapping of the actual
since the interlanguage facilities provided argument passed must correspond to the
by PL/I cannot look at the parameter in the mapping assumed for the parameter by COBOL
invoked routine, it is the programmer's or FORTRAN.
responsibility to ensure that the parameter
in the invoked routine corresponds in data For an element argument, the only
type and organization to the argument requirement is that the alignments of
description in PL/I. argument and parameter are compatible. In
PL/I the alignment of variables is
If the PL/I compiler can determine, at determined by the ALIGNED and UNALIGNED
compile-time, that the mapping of a attributes. The eqUivalent specifications
structure or array argument is the same in in COBOL and FORTRAN are:
PL/I as in the invoked language, the
argument is passed directly to the invoked ~ COBOL FORTRAN
routine. However, where such mapping
equivalence does not exist, the ALIGNED SYNCHRONIZED Normal alignment
interlanguage facilities provide for a
dummy argument to be passed, where the UNALIGNED Unsynchronized No eqUivalent
dummy is mapped according to the rules of
the invoked language. See section K, AData The alignment of a PL/I argument is
Mapping". deduced, like the data type, from the
parameter descriptor list or from the
If the PL/I data types of arguments argument itself. Only ALIGNED elements may
passed to FORTRAN or COBOL have no be passed to SYNCHRONIZED COBOL parameters,
equivalents in these languages, a warning or to FORTRAN parameters. Either ALIGNED
message is produced at compile-time. At or UNALIGNED elements can be passed to
execution-time the results are undefined, COBOL unsynchronized parameters. It is the
and may include abnormal termination. programmer·s responsibility to ensure that
these alignments are compatible.
Data types: PL/I has more data types than
either COBOL or FORTRAN: some have no The prOblem is more complicated for data
equivalents in these languages. The extent aggregates. A PL/I or a COBOL structure
to which PL/I data types have equivalents for example can have either of the
in COBOL or FORTRAN, and therefore can be alignment stringencies given above. In
passed as arguments, is summarized here. addition, each member can have its own
alignment stringency or all members can
Problem data: Most of the PL/I data types have the same alignment stringency.
have equivalents in either COBOL or padding bytes are inserted b¥ the mapping
FORTRAN. Tables of data equivalents for algorithm for the particular language, in
PL/I-COBOL and PL/I-FORTRAN are given order to preserve the required alignment
below, in "COBOL Interface" and "FORTRAN for each member. In a PL/I structure, the
Interface" respectively. alignments are adjusted, where poSSible, to
minimize the amount of padding required;
Program-control data: Arguments of any this adjustment does not occur in a COBOL
program-control data type can be passed to structure. The result is that a structure
an invoked COBOL or FORTRAN routine. mapped with the PL/I mapping algorithm may
However, only an entry argument can be not have the same layout in main storage as
passed and used within tQe invoked routine, a structure mapped with the COBOL
and then only if the routine is a FORTRAN algorithm.
routine. Arguments of any other data type
should not be used in the invoked routine Similarly, the mapping of arrays is
except to be passed in turn to a PL/I different in PL/I and FORTRAN. PL/I stores
procedure. arrays of more than one dimension in row-

290 OS PL/I CKT AND OPT LRM PART I

major-order, while FORTRAN stores them in Invocation
column-major-order. Hence, for arrays with
more than one dimension, a reference to an
element in PL/I is obtained by reversing Invocation of a COBOL or FORTRAN routine is
the order of the subscripts that would be performed by a CALL statement or (in the
used in FORTRAN to refer to the same case of a FORTRAN routine only) function
element. reference that specifies an entry constant
or variable whose value corresponds to the
entry point of a COBOL or FORTRAN routine.
The interlanguage facilities resolve The entry pOint must not be that of a
these problems by creating dummy arguments FORTRAN main program. The entry constant
for PL/I data aggregates passed as or variable must be identified as invoking
arguments to COBOL or FORTRAN routines. COBOL or FORTRAN by use of the appropriate
IWhen a PL/I ALIGNED structure is passed as options in the OPTIONS attribute in the
an argument to a COBOL routine, the mapping declaration of the entry in the PL/I
of the argument in both languages is program. The programmer may also specify,
considered. If the compiler can determine in this deClaration, options which suppress
that the mappings are identical, the re-mapping of data aggregates and an option
argument is passed directly to the COBOL which allOWS PL/I to deal with certain
routine. interrupts in the COBOL or FORTRAN routine.
The options are:
However, if the compiler cannot
determine that the mappings are identical, COBOL: This specifies that the
a dummy argument is created, mapped designated entry point is in a
laccording to the COBOL -SYNCHRONIZED mapping COBOL routine.
algorithm. The values of the members of
the PL/I structure are assigned to the FORTRAN: This specifies that the
corresponding members in the dummy designated entry pOint is in a
argument; the dummy is then passed as an FORTRAN routine.
argument to the COBOL routine. On return
to the PL/I procedure, the values ~n the NOMAP: This specifies that a dummy
dummy argument (which mayor may not have argument is not created; the
been changed) are assigned to the aggregate argument is passed
corresponding members of the original PL/I directly to the invoked
argument. routine.
Similarly, when a PL/I array is passed NOMAPIN: This specifies that, if a dummy
as an argument to a FORTRAN routine, the argument is created, it is not
mapping of the array in both languages is initialized with the values of
considered. If the arrays are the aggregate argument.
unidimensional, and are in connected
storage and are aligned identically, the NOMAPOUT: This specifies that, if a dummy
argument is passed directly to the invoked argument is creat ed, then, on
FORTRAN routine. If either the arrays are return, the values in the dummy
unidimensional and do not meet the above argument are not aSSigned to
conditions, or are multidimensional, a the aggregate argument.
dummy argument is created, mapped according
to FORTRAN array handling. (In effect, INTER: This specifies that any
this means the subscripts are reversed). interrupts occurring during the
The values of the PL/I array elements are execution of a COBOL or FORTRAN
assigned to the corresponding elements in routine that are not dealt with
the dummy argument. The dummy is then by the COBOL or FORTRAN
passed as an argument to the FORTRAN interrupt-handling facilities
routine. On return to the PL/I procedure, are dealt with by the PL/I
the values in the dummy argument (which may interrupt-handling facilities
or may not have been changed) are assigned (see also -Interrupt Handling-
to the appropriate elements of the PL/I later in this chapter).
argument.
The NOMAPIN and NOMAPOOT options
The programmer can specify certain should be used if initialization
options that inhibit or restrict the effect is not required whenever program
of the interlanguage facilities for efficiency is important, because
remapping data aggregates. If several are they allow the compiler to omit
passed at an invocation, he can, for unnecessary initialization code.
example, inhibit the facilities for one
argument, allow them for another argument, ARGn: This is an option of NOMAP,
or restrict them for a third argument. NOMAPIN, and NOMAPOUT which

Chapter 19: Interlanguage Communication Facilities 291

 specifies which arguments the S. DCL A ENTRY;
option applies to. If no ARGn
is specified, the option is CALL XCA);
applied to all arguments.

The following points should be noted in X:PROC(B);

the declaration of the entry name: OCL B OPTIONSCCOBOL);

6. DCL COBSUB ENTRY( ••• , ••• , ••• ,)

1. Either COBOL or FORTRAN (but not both) OPTIONS(COBOL,NOMAP(ARG1,ARG3»;
can appear in the declaration. One or
more of the options NOMAP, NOMAPIN and
NOMAPOUT can appear in the same
declaration. CALL COBSUB(A,B,C);

2. The RETURNS attribute cannot be used

with the COBOL option, as COBOL CALL COBSUB(X,Y,Z);
subprograms do not return values.

3. An entry variable or a parameter can passing Arguments to a PL/I Procedure

be declared with the interlanguage
options.
When an argument is passed to a PL/I
procedure from COBOL or FORTRAN, the data
4. An entry name with the interlanguage type is determined in the normal PL/I
options can. appear in a GENERIC manner, that is from the declaration of the
attribute specification. parameter. The interlanguage facilities
ensure that the addressing mechanism used
5. The entry constant name of the COBOL for the parameter is that used by PL/I, and
or FORTRAN routine may have one that, unless otherwise required, the
through eight characters. If more mapping of any aggregate parameters passed
than eight characters are specified, is also that used by PL/I. Note that since
the leftmost eight only are taken. the interlanguage facilities provided by
PL/I cannot look at the argument in the
Examples: routine invoking PL/I, it is the
programmer's responsibility to ensure that
1. DCL COBOL ENTRY (CHAR(S» the argument passed to PL/I corresponds in
OPTIONS(COBOL INTER), data type and organization to the parameter
declared in PL/I.
COBOLB ENTRY (1, 2 FIXED, 2 FLOAT)
OPTIONS(COBOL NOMAPIN), Data mapping: The situation is similar to
COBOLBXX OPTIONS (COBOL) EXTERNAL that which occurs on invocation of COBOL or
ENTRY( ••• ); FORTRAN by PL/I. The mapping of the
argument on entry to the PL/I procedure
2. DCL FORTA ENTRY CFIXED BINARY) must correspond to the mapping used by PL/'I
OPTIONS (FORTRAN) RETURNS in addressing the parameter.
(FLOAT (5»;
For element arguments and parameters,
3. DCL A EXTERNAL ENTRY ( ••• ) VARIABLE this means that a SYNCHRONIZED or
OPTIONS (FORTRAN), unsynchronized COBOL argument may be passed
to an UNALIGNED PL/I parameter, or that a
B OPTIONSCFORTRAN); SYNCHRONIZED COBOL argument or a FORTRAN
argument can be passed to an ALIGNED PL/I
parameter.
A=B; For aggregate arguments and parameters
CALL AC ••• ); where the mapping of the argument in COBOL
ICsynchronized) or FORTRAN differs from the
4. DCL A GENERIC (COBOLZ mapping of the parameter in PL/I, the
WHEN (CHARACTER) , interlanguage fa~ilities resolve the
FORTZ WBEN(FIXED BINARY», problem by creating a dummy argument which
is passed to the PL/I procedure.
COBOLZ OPTIONS(COBOL),
The dummy argument is mapped according
FORTZ OPTIONS(FORTRAN); to PL/I rules, and, before invocation of

292 OS PL/I CRT AND OPT LRM PART I

the PL/I procedure, the values of the when coding the PROCEDURE or ENTRY
members of the COBOL or FORTRAN argument statement:
are assigned to the corresponding members
of the dummy argument. On return from the 1. Only one of the options MAIN, COBOL,
PL/I prOcedure, the values of the members or FORTRAN can appear in the same
of the dummy argument are assigned back to statement. One or more of the options
the original argument. NOMAP, NOMAPIN, or NOMAPOUT can appear
in the same statement.
If the compiler can recognize that the
mapping in COBOL or FORTRAN and PLII are 2. If the parameters for the procedure
eqUivalent, no such dummy is created. include strings, areas or arrays, the
Alternatively, the programmer can inhibit lengths, sizes or bounds for these
the creation of the dummy, or the must be specified as decimal integer
assignments between the original argument constants.
and the created dummy, by means of options.
3. The RETURNS option cannot be specified
for any entry point invoked by a COBOL
routine.
Invocation
Examples:
The entry pOints in a PLII procedure that 1. P1:PROC(A,B,C) OPTIONS(FORTRAN
are to be invoked from COBOL or FORTRAN NOMAPIN(C) NOMAPOUT(A»;
must be identified by the appropriate DCL A(3,4) FLOAT BIN(20),
options in the corresponding PROCEDURE or B FIXED BIN(31),
ENTRY statement. The programmer may also C(S,6) FLOAT DEC(6):
specify options that suppress re-mapping of
data aggregates. 2. P2:PROC(R,S,T) OPTIONS (FORTRAN
NOMAP);
COBOL: This specifies that the entry
point can only be invoked by a 3. P3:PROC(X,Y) OPTIONS(COBOL NOMAPIN(X)
COBOL routine. NOMAPOOT(Y»;
DCL 1 X, 2 ••• 2 ••• 3 ••• ,
FORTRAN: This specifies that the entry 1 Y, 2 ••• 2 ••• 3 ••• ;
point can only be invoked by a
FORTRAN routine.
NOMAP: This specifies that a dummy Using Common Storage
argument is not created: the
COBOL or FORTRAN aggregate
argument is passed directly to A variable in a PL/I program can be
PL/I. allocated the same block of storage as a
group of variables in a FORTRAN routine.
NOMAPIN: This specifies that, if a dummy This storage can then be used to
argument is created, it is not communicate between the two routines.
initialized with the values of Allocation of common storage is achieved by
the aggregate argument. declaring a PLII variable to be STATIC
EXTERNAL and to have the same name as a
NOMAPOUT: This specifies that, if a dummy COMMON block in the FORTRAN routine. The
argument is created its values STATIC EXTERNAL variable and the COMMON
are not assigned back to the block will then be equivalent to two
aggregate argument on return. declarations of a STATIC EXTERNAL variable
The NOMAPIN and NOMAPOUT in different external PL/I procedures. 'l'he
options should be used, if number of variables using common storage is
initializations not required, not limited to two: any number of
whenever program efficiency is identical STATIC EXTERNAL variables in
important, since they allow the different PL/I procedures may be used
compiler to omit unnecessary together with any number of identical
initialization code. COMMON blocks in different FORTRAN
routines, if all the procedures and
Parameter The parameter or parameters routines are link-edited into a single
list: to which the NOMAP, NOMAPIN, or program. Methods of link-editing are given
NOMAPOUT options apply can be in the compilers' programmers' guides.
specified in a list. If no
list is specified, the option The STATIC EXTERNAL variables must
is applied to-all parameters. follow the normal PL/I rules relating to
these attributes, and they must be of a
The following points should be noted data type that corresponds to the data type

Chapter 19: Interlanguage Communication Facilities 293

of the COMMON variables (see "FORTRAN PL/I procedure is invoked. The extent of
Interface" later in this chapter for a this environment includes the routine that
table of corresponding data types). Also, invoked the PL/I procedure (see figure
the PL/I variables must be aligned to meet 19.1), and the environment remains in
the requirements of the corresponding existence until that routine is terminated.
FORTRAN data type. The environment can be reestablished and
terminated as frequently as required.
The PL/I variables may be initialized Whenever the PL/I environment is destroyed,
using the INITIAL attribute, and the all PL/I controlled and based storage is
FORTRAN variables may be initialized using released, and all PL/I files are closed.
a block data subprogram. If the PL/I
variables on the one hand and the FORTRAN For reasons of efficiency and of
variables on the other are not initialized programmdng convenience, the PL/I
to the same value, the procedure or routine environment should be destroyed as
that is encountered first by the linkage- infrequently as possible during execution
editor determines the initial value of all of a program. This can be ensured if the
the variables. It is not an error to main routine is a PL/I main procedure, or
initialize a PL/I variable to a different if a PL/I procedure, no matter what it
value from a corresponding FORTRAN contains, is invoked from the main routine.
variable, or to initialize one and not the The latter alternative, however, has the
other. disadvantage that if the main routine is in
FORTRAN, the PL/I environment will not be
The PL/I variable may have further ended normally when the final FORTRAN
variables overlayed upon it by means of the RETURN is executed to return control to the
DEFINED attribute, provided that the operating system (see "Termination of
defined variable meets the data type and FORTRAN and COBOL Routines" later in this
alignment requirements of the FORTRAN Chapter) •
variable. If the requirements are not met,
execution errors may occur.

Common storage cannot be used for a PL/I

and a COBOL variable; the only facility Establishing the FORTRAN Environment
provided by PL/I for communication between
a PL/I procedure and a COBOL routine is
that for passing arguments. Before a FORTRAN routine can be eXecuted, a
suitable environment must be established.
The extent of this environment includes the
PL/I procedure that invokes the FOR'I'RAN
INTERLANGUAGE ENVIRONMENT routine, and this environment remains in
existence until the PL/I procedure is
terminated.
IFor a program to be executed, a suitable
environment must first be established. If For reasons of e~ficiency, the FORTRAN
the program contains a PL/I main procedure, environment should be destroyed as
Ithe PL/I environment is established when infrequently as possible during the
the program is first entered. If the main execution of a program. This is ensured if
routine is COBOL or FORTRAN, the the PL/I procedure that calls the FORTRAN
interlanguage facilities will establish the routine is not terminated until all the
required PL/I environment when necessary. FORTRAN calls have been executed, or if the
This section describes the conventions and IFORTRAN environment is extended to include
restrictions in the interlanguage context. Ithe outer PL/I procedure by invoking a
IFORTRAN routine (no matter what it
Icontains) from the outer PL/I procedure.

Establishing the PL/I Environment

Interrupt Handling
If the main routine of the program is a
PL/I main procedure, the PL/I environment
is established on entry to the program. COBOL and FORTRAN routines handle certain
Even if this program contains a mixture of of the hardware interrupts that may occur
PL/I and COBOL or FORTRAN routines, the during their execution, but there are sOme
normal rules for freeing PL/I storage and that they do not handle. The inter language
closing PL/I files apply. communication facilities of PL/I allow any
interrupt not dealt with by a COBOL or
If the main routine of the program is FORTRAN routine to be handled by any PL/I
not a PL/I main procedure, the PL/I procedure from which that routine is
environment is established when the first dynamically descendent.

294 OS PL/I CKT AND OPT LRM PART I

 r-------------------,I
I
I PROC1 (MAIN) 1
I I
1 FORTRAN 1
I I
L-------------------J
r------------------------------------------------------------,
I +++++++++++++1+++++++++++++ 1
1 + 1 + 1
r-------------------, +
+
r-------------------, + r-------------------,
I I 1 1 + 1 I
I PROC8 1 + I PROC2 I + I PROC5 I
1 I + I 1 + I I
I FORTRAN I + I FORTRAN 1 + I FORTRAN I
I 1 + I I + I I
L-------------------J +
+
L-------------------J +
+
L-------------------J
+ +
+ + +++++++++++++1+++++++++++++
+ + + I +
r-------------------, + r-------------------,1
I
+ + r-------------------, +
I 1 + + + I I +
1 PROC9 1 + I PROC3 1 + + 1 PROC6 I +
I I + 1 1 + + I I +
I FORTRAN I + I PL/I 1 + + 1 FORTRAN I +
I I + 1 I + + I , +
L-------------------J +
+
L-------------------J +
+
+
+
L-------------------J +
+
+ + + +
+ + + +
+ + + +
+
+ 1
r-------------------, + +
+
r-------------------, +
I + 1 I +
+ 1 PROC4 I + + I PROC7 I +
+ 1 1 + + I I +
+ I COBOL 1 + + I PL/I 1 +
+ I I + + I I +
+
+
l-------------------J +
+
+
+
L-------------------J +
+
+++++++++++++++++++++++++++ +++++++++++++++++++++++++++
t t
I I
I I
I I
I 1
I 1
Boundaries of PL/I environments------------ J

Figure 19.1. Extent of PL/I environment

The programmer specifies the INTER an on-unit, while established, applies not
option of the OPTIONS attribute when only to the procedure in which it was
declaring the COBOL or FORTRAN entry name. created, but also to all procedures that
(See also the INTER option under "passing are dynamically descendent from it. If
Arguments to COBOL or FORTRAN Routine" there occurs, during the execution of a
earlier in this chapter.) This allows the COBOL or FORTRAN routine, an interrupt that
interrupts not dealt with by the invoked will not be handled by that routine, and if
COBOL or FORTRAN routine to be handled by the routine was invoked by a PL/I procedure
either a PL/I on-unit or by PL/I standard in which the INTER option was specified for
system action. (Except that PL/I cannot the COBOL or FORTRAN entry name, then a
handle a ZERODIVIDE interrupt in a division search is made through all invoking
of COMPUTATIONAL-3 data in a routine procedures for an appropriate on-unit. If
compiled by a COBOL compiler other than the none is found, standard system action is
COBOL E compiler. Such an interrupt will taken. If INTER is not specified, nO
cause termination of the program.) In PL/I, search is made, and the interrupt is dealt

Chapter 19: Interlanguage Communication Facilities 295

with by the operating system control Assume that the CALL FORT; statement is
program. executed, and that FORT then calls Q.
Assume further that an error occurs in Q
Note that the search passes through all which initiates entry to the on-unit
routines in the invoking chain, as far as established in P. At this stage control is
the limit of the PL/I environment. It is still with procedure Q because the on-unit
therefore possible for the search to is regarded as being appended to the
include COBOL and FORTRAN routines. Such procedure from which it was entered. If
routines have no effect on the results of LAB has the value L1, then the GO TO branch
the search, since only PL/I on-units are is in error because it transfers control
searched for, unless one of them is a COBOL back to procedure P and ~n dOing so crosses
routine that has been compiled by a the interlanguage bou~daries between Q and
compiler that does not implement Americam FORT and between FORT and P. If LAB has
National Standard COBOL or that was made the value L2, the GO TO is not in error
available prior to Release 19 of System/360 because control remains in procedure Q. If
Operating system. In these cases, the an interrupt in FORT caused the on-unit to
result of the search and the effects of the be entered before Q was called, then the GO
interrupt are undefined, and may include TO would not have been in error, if LAB had
abnormal termination o£ the program. the value L1: only one interlanguage
boundary would be crossed, namely the
FORTRAN-PL/I boundary between FORT and P.
(LAB should not have the value L2 in this
case because procedure Q is not active).
GO TO Statement

The GO TO statement must not be used to Termination of FORTRAN and COBOL

transfer control across more than one Routines
interlanguage boundary, where an
interlanguage boundary is defined as an
invocation in which one routine calls A routine may be terminated by either
another of a different language. Such executing a statement that terminates th~
transfers of control may be initiated whole program, or by handing control back
inadvertently if the programmer uses a GO to the calling routine.
TO statement in an on-unit. (Note that
entry to an on-unit is not considered as The statements that terminate the whole
transferring control outside the block or program are STOP in FORTRAN and STOP RUN in
routine in which the statement that caused COBOL. They are equivalent to the PL/I
the on-unit to be entered was executed; the STOP statement. The effects of these
on-unit may be regarded as being appended statements are unchanged in a mixed
to the procedure or routine from which it language program; they still terminate the
is entered. This applies even if the on- whole program.
unit is entered from a COBOL or FORTRAN
routine). Consider the following example: If a FORTRAN STOP is executed in a
routine that is within a PL/I enVironment,
P:PROCEDURE; that environment is not ended in the normal
DECLARE LAB LABELCL1,L2) EXTERNAL, way. If a COBOL STOP RUN is executed in a
FORT ENTRY OPTIONS(FORTRAN INTER); routine that is within a PL/I environment,
ON ERROR GO TO LAB; that environment is ended in the normal way
only if it includes the main routine of the
program; otherwise the termination will be
CALL FORT; abnormal. The main difference, from the
programmer's point of view, between a
normal and an abnormal ending is that in
Ll: . . . . . . . ; the abnormal ending, open files in PL/I
procedures are not closed. This could
cause output data to be lost. Considering
END P; the example in figure 19.1, a STOP in PROC2
or a STOP RUN in PROC4 would not close any
Q:PROCEDURE OPTIONS(FORTRAN); files that may be open in PROC3, and a STOP
DECLARE LAB LABEL(L1,L2) in PROC6 would not close any files in
EXTERNAL; PROC1.

A RETURN executed in a FORTRAN

L2: ••••••• ; subroutine or function that is inside a
PL/I environment and which returns control
to a routine outside that environment (in
END Q; other words, a RETURN statement in a

296 OS PL/I CKT AND OPT LRM PART I

FORTRAN routine that directly invokes a routine. Also, the OCCURS clause cannot
PL/I routine but which is not dynamically appear on a level-01 entry. This precludes
descendent from any PL/I routine), ends the the use of a level-01 array in a PL/I
PL/I environment and causes all files in structure passed to or from a COBOL
dynamically descendent PL/I procedures to routine.
be closed. However, a RETURN statement in
a FORTRAN main routine is effectively a A PL/I structure that contains an area
STOP statement: control is passed to the or a bit-string variable should not be
operating system without any files being passed as an argument to a COBOL routine.
closed. If it is, a diagnostic message is produced
and the structure is not automatically
When a COBOL main routine that is within remapped.
a PL/I environment passes control back .to
the operating system, the environment is A bit or character string with the
ended normally. VARYING attribute may be passed to a COBOL
routine, although there is nO equivalent
attribute in COBOL. The address of the
start of the two-byte length prefix is
Multitasking passed, so that the prefix consitutes the
first two bytes of the COBOL string.
Conversely, when COBOL data is passed to a
A PL/I procedure cannot invoke a COBOL or a PL/I string parameter with the VARYING
FORTRAN routine as a task, that is, the attribute, the first two bytes of the
CALL statement must not specify the TASK, argument form the parameter's length
EVENT, or PRIORITY options. prefix.
Only one task of a PL/I program can have
active COBOL or FORTRAN routines at anyone
time. If a PL/I program has more than one FORTRAN INTERFACE
task active at the same time, then, if one
of these tasks has invoked a COBOL or a
FORTRAN routine, the programmer must ensure Argument/parameter matching across a
that the other tasks wait until control has PL/I-FORTRAN interface, and the use of
returned to the PL/I program before another common storage for PL/I and FORTRAN
non-PL/I routine is invoked. variables, require a knowledge of the
equivalence of data types and of data
organizations in the two languages. The
PL/I equivalents of the FORTRAN data types
COBOL INTERFACE are shown in tigure 19.4. These are the
PL/I data types that should appear in PL/I
parameters or parameter descriptors
Argument/parameter matching across a PL/I- associated with FORTRAN arguments or
COBOL interface requires a knowledge of the parameters respectively, and in the
equivalence of data types and of data declaration of STATIC EXTERNAL variables
organization in the two languages. The with the same names as FORTRAN COMMON
PL/I equivalents of the COBOL data types blocks.
are shown in figure 19.2. These are the
PL/I data types that should appear in PL/I The specification of equivalent data
parameter descriptors associated with COBOL aggregates in PL/I and FORTRAN is simpler
arguments or parameters respectively. than in PL/I and COBOL, as the only data
aggregates that exist in FORTRAN are
While a knowledge of the equivalent data arrays. The problems arise when using non-
types is sufficient for specifying COBOL connected unidimensional arrays or
items in terms of PL/I element variables, multidimensional arrays as PL/I arguments.
the specification of equivalent data
aggregates (group items in COBOL, Generally, when passing arguments
structures or arrays in PL/I) requires a between PL/I and FORTRAN, the interlanguage
knowledge of the data-organization facilities pass a unidimensional array
descriptions of the two languages. The directly to the invoked routine, without
example given in figure 19.3 shows how a the creation of a dummy argument. However,
COBOL data aggregate is described in PL/I if a PL/I unidimensional array in non-
terms. connected storage is passed as an argument
to a FORTRAN routine, the interlanguage
In COBOL, the OCCURS clause cannot facilities create a dummy argument into
appear mOre than three times in anyone which the unconnected. array is mapped. The
group-item description. This imposes a dummy is then passed as the
restriction on any PL/I array within a argument. On return, the values in the
structure passed as an argument to a COBOL dummy are assigned to the corresponding

Chapter 19: Interlanguage Communication Facilities 297

r---------------------------------------------------------------------------------------,
1 COBOL I PL/I I
1---------------------------------------------------------------------------------------1
1 1 1 Alignment 1 1 1 Alignment 1
I 1 1-------------------1 1 1------------------1
1 Data type ILength 1 Synch. IUnsynch.1 pata Type 1Length 1 Aligned 1 Un- 1
1 ICbytes)ICaligned) 1 Cun- 1 1 (bytes) I 1aligned 1
I 1 I I aligned) 1 1 1 1 1
1---------------
COMPUTATIONAL1
------------------ -------------------------
1
------- ---------- -------
dec. length: 1
1-4 2 Halfword Byte 1FIXED 2 Halfword Byte
IBINARY(15,0)
IChalfword
I integer)
1
5-9 4 Fullword Byte IFIXED 4 Fullword Byte
BINARY(31,0)
(fullword
integer)
10-18 8 Fullword Byte No equivalent
COMPUTATIONAL-l 4 Fullword Byte FLOAT DEC(6) 4 Fullword Byte
(short float)
ICOMPUTATIONAL-2 8 Doubleword Byte FLOAT DEC(16) 8 Doublewordl Byte
I (long float) 1
1 1
ICOMPUTATIONAL-31 12 Byte Byte FIXED DEC 12 Byte 1 Byte
1 1 I
'DISPLAY 1 any Byte Byte CHARACTER any Byte 1 Byte
1---------------------------------------------------------------------------------------
1 1Decimal length is equal to the number of 9s in the picture.
1
, 2The length of 1 byte applies to the smallest fixed decimal value (i.e., 1 digit).
1 For other values, the length is given by CEIL«number of digits + 1)/2) bytes.
l---------------------------------------------------------------------------------------J
Figure 19.2. COBOL-PL/I data equivalents

r---------------------------------------------------------------------------------------,
1 01 A SYNCHRONIZED. 1 A ALIGNED, 1
1 02 B OCCURS 3 TIMES. 2 B(3), I
I 03 C OCCURS 4 TIMES. 3 C(4), I
1 04 D OCCURS 5 TIMES USAGE COMP-3 4 D(5) FIXED DECIMAL(7,3), 1
I PIC S9999V999. 1
1 02 E USAGE DISPLAY. 2 E, I
I 03 F PIC X(8). 3 F CHAR(8), I
1 03 G PIC 9(8). 3 G PIC '(8)9', 1
I 02 DUMMY OCCURS 6 TIMES. 2 H(6,7) FIXED BINARY (15,0)~ ,
I 03 H OCCURS 7 TIMES USAGE COMP 1
I PIC S9999. I
l---------------------------------------------------------------------------------------J
Figure 19.3. Declaration of a data aggregate in COBOL and PL/I

298 OS PL/I CRT AND OPT LRM PART I

r---------------------------------------------------------------------------------------,
I FORTRAN I PL/I
1---------------------------------------------------------------------------------------
I I I I I I Alignment
IData Type ILength I Alignment I 1
Data Type ILength 1-----------------------
I I(bytes) 1 I 1 (bytes) Aligned I Unaligned
1-----------
IINTEGER*2
-------------------------------------------
2 I Halfword IREAL FIXED BINARY(15,O)
-------
2
-----------
Halfword
-----------
Byte
1 I I
IINTEGER*4 4 Fullword IREAL FIXED BINARY(31,O) 4 Fullword Byte
I I
IREAL*4 4 Fullword IREAL FLOAT DEC(6) 4 Fullword Byte
I I (real short float)
1 I
IREAL*S S DoublewordlREAL FLOAT DEC(16) 8 Doubleword Byte
1 I (real long float)
1 I
IREAL*16 16 DoublewordlREAL FLOAT DEC(33) 16 Doubleword Byte
I I (real extended float)
I I I
ICOMPLEX*S S Fullword ICOMPLEX FLOAT OEC(6) 8 Fullword Byte
I I (complex short float)
I I
ICOMPLEX*16 16 DoublewordlCOMPLEX FLOAT OEC(16) 16 Doubleword Byte
I I (complex long float)
I I
I COMPLEX * 32 32 OoublewordlCOMPLEX FLOAT DEC(33) 32 Doubleword Byte
I I (complex extended
I I float)
1 I
ILOGICAL*l 1 Byte IBIT(S) 1 Byte Bit2
1 I
ILOGICAL*4 4 FUilword IBIT(32) 4 Byte Byte
I----------------------~----------------------------------------------------------------
I 1Generally, FORTRAN data is held inmain storage with these alignments. COMMON data,
I however, is always byte-aligned. This could cause a specification interrupt if the
I items in the COMMON area are not stored in order of decreasing stringency.
I
I 3The fact that the alignment required of unaligned bit strings is bit rather than byte 1
I does not affect PL/I-FORTRAN data interchange, since the FORTRAN string will always 1
I take up an integral number of bytes. I
l---------------------------------------------------------------------------------------J
Figure 19.4. FORTRAN-PL/I data equivalents

elements in the array. COMPILE-TIME RETURN CODES

A dummy argument is always created for a

~ltidimensional array passed between PL/I Diagnostic messages are provided at compile
and FORTRAN routines, unless the NOMAP time as an aid to debugging the program.
option specified. The messages are classified according to
the type of the information they provide.
A numeric value, the return code, is
associated with each class of message, as a
guide to the severity of the error or
If a PL/I array of bit strings is passed possible error that has been diagnosed.
as an argument to a FORTRAN routine, only S The highest return code generated during
or 32 should be specified for the string compilation constitutes the.return code of
lengths. If values other than these are that compilation, and its value is printed
specified, a diagnostic message is produced on the compile-time listing. Diagnostic
and the array is not automatically messages and return codes are described in
remapped. Similarly, only these lengths the programmer's guides for the compilers.
should be used for PL/I variables having The classes of message and corresponding
storage common with FORTRAN variables. return codes are as follows.

Chapter 19: Interlanguage Communication Facilities 299

r---------------------------------------------------------------------------------------,
I COBOL I FORTRAN I
PL/I
Attribute
1---------------------------------------------------------------------1
I Argument I. Parameter I Argument I Parameter I
--------------------------------------------------------------------------------,--------
AJ,IGNED 0000 0000 0000 0000

AREA Note 1 Note 1 Note 1 Note 1

BINARY 0000 0000 0000 I 0000

---------------------------------------------------------------------------------------
BIT Note 1 I Note 1 Note 2 I Note 2
---------------------------------------------------------------------------------------
CHARACTER 0000 I 0000 I OOOlJ OOOlJ
----------------------------------------------~------- ---------------------------------
COMPLEX OOOlJ OOOlJ I Note lJ I Note lJ
---------------------------------------------------------------------------------------
CONNECTED 0000 I 0000 0000 I 0000
---------------------------------------------------------------------------------------
CONTROLLED 0000 I 0012 0000 0012

DECIMAL 0000 0000 Note 3 I Note 3

---------------------------------------------------------------------------------------
DEFINED 0000 I 0000 I
---------------------------------------------------------------------------------------
Dimension Note 8 Note 8 I 0000 0000

ENTRY OOOlJ OOOlJ OOOlJ I OOOlJ

---------------~-------------------------------------- ----"-----------------------------
EVENT OOOlJ I OOOlJ 0004 I OOOlJ
---------------------------------------------------------------------------------------
FILE OOOlJ I OOOlJ OOOlJ OOOlJ
FIXED I 0000 0000 0000 0000
---------------------------------------------------------------------------------------
FLOAT I 0000 I 0000 I 0000 I 0000
---------------------------------------------------------------------------------------1
LABEL I OOOlJ I 0004 I OOOlJ I OOOlJ I
---------------------------------------------------------------------------------------1
Non-connected I Note 5 I 0000 r Note 5 I 0000 I
---------------------------------------------------------------------------------------1
OFFSET I OOOlJ I OOOlJ I OOOlJ I OOOlJ I
---------------------------------------------------------------------------------------1
PICTURE I 0000 I 0000 I OOOlJ I OOOlJ I
---------------------------------------------------------------------------------------1
POINTER I OOOlJ I OOOlJ I OOOlJ I OOOlJ I
---------------------------------------------------------------------------------------1
Precision I Note 6 I Note 6 I Note 1 I Note 1 I
---------------------------------------------------------------------------------------1
REAL I 0000 I 0000 I 0000 I 0000 I
---------------------------------------------------------------------------------------1
Structure I 0000 I 00·00 I Note 1 I Note 1 I
---------------------------------------------------------------------------------------1
TASK I 0004 I OOOlJ I OOOlJ I OOOlJ I
---------------------------------------------------------------------------------------1
UNALIGNED I Note 9 I 0000 I Note 9 I 0000 I
---------------------------------------------------------------------------------------1
VARYING I OOOlJ I 0004 I OOOlJ I OOOlJ I
L---------------------------------------------------------------------------------------J
Figure 19.5 (Part 1 of 2). Return codes produced by PL/I data types

300 OS PL/I CXT AND OPT LRM PART I

r---------------------------------------------------------------------------------------,
~ I
I
1. Checkout compiler: 0004 6. Variable is FIXED(p,O), or is short or
Optimizing compiler: OOOS long FLOAT: 0000
In both cases, creation of a dummy Variable is BINARY FIXED (p,q) with
argument is suppressed q,=O, or is extended FLOAT: 0004
2. BIT(S) or BIT(32): 0000 7. variable is FLOAT, or is FIXED BINARY
Any other length: OOOS with precision (p,O): 0000
In latter case, creation of a dummy Variable is FIXED DECIMAL, or is
argument is suppressed. BINARY(p,q) with q~=O: 0004
3. FLOAT DECIMAL: 0000 S. If item is element of a structure or
FIXED DECIMAL: 0004 is a minor structure: 0000
All other cases: OOOS
". FLOAT COMPLEX: 0000
FIXED COMPLEX: OOOS 9. If argument is an aggregate and
creation of temporary is suppressed
5. If creation of temporary suppressed by by NOMAP, or if argument is
NOMAP option: 0012 scalar: 0012
If no NOMAP option: 0000 If argument is an aggregate and no
NOMAP: 0000
L---------------------------------------------------------------------------------------J
Figure 19.5 (Part 2 of 2). Return codes produced by PL/I data types

Informatory return code 0000 Figure 19.5 shows the return codes
Warning return code 0004 generated by various types of PLII data.
Error return code 0008
Severe error return code 0012
,EXECUTION-TIME RETURN CODES
If no messages are produced, a code of 0000 I
is returned. I
IThe value of the PL/I return code may be
A return code of 0000 indicates that the ,set in a PL/I routine by means of the
compiler found no possible sources of ,PLIRETC built-in subroutine (see the
error. A code of 0004 indicates that Iprogrammer's guide for the compiler).
execution will probably be successful. A I
code of 0008 indicates that an error has , The return code of a non-PL/I routine
been found but that execution nevertheless Imay be obtained by declaring the entry
might be successful. A code of 0012 Ipoint with OPTIONS(RETCODE). This option
indicates that execution will probably not ,causes the value of the PLII return code to
be successful. (be set to the value returned by the non-
IPL/I routine in the lower half of register
As part of the interlanguage facilities 115.
of PL/I, diagnostic messages are produced, I
and the return code set appropriately, if , The latest value of the PLII return code
the programmer specifies arguments or Ican be read by means of the PLIRETV bu1lt-
parameters whose attributes are such that lin function.
errors may occur at execution time. The I
compiler will never prevent data being 'Example:
passed, nor will it attempt to correct I
errors; although it produces messages to
indicate likely sources of error to the ,,
, DECLARE AR ENTRY OPTIONS(ASM,RETCODE);
programmer, it will always allow him to
attempt to pass any type of data he , CALL AR;
specifies. I IF PLIRETV() =0 THEN ••••••• ;

Chapter 19: Interlanguage Communication Facilities 301

Part II: Rules and Syntactic Descriptions

Part II: Rules and Syntactic Descriptions 303

 Section A: Syntax Notation

Throughout this publication, wherever a literal occurrence of the characters

PL/I statement -- or some other combination represented. A notation constant
of elements -- is discussed, the manner of consists either of all capital letters
writing that statement or phrase is or of a special character. For
illustrated with a uniform system of example:
notation.
This notation is not a part of PL/I; it DECLARE identifier FIXED:
is a standardized notation that may be used
to describe the syntax -- or construction
of any programming langu~ge. It This denotes the literal occurrence of
provides a brief but precise explanation of the word DECLARE followed by the
the general patterns that the languag@ notation variable "identifier," Which
permits. It does not describe the meaning is defined elsewhere, followed by the
of the language elements, merely their literal occurrence of the word FIXED
structure; that is, it indicates the order fo1lowed by the literal occurrence of
in which the elements may (or must) appear, the semicolon (;).
the punctuation that is required, and the
options that are allowed.
3. The term "syntactic unit," which is
The following rules explain the use of used in subsequent rules, is defined
this notation for any programming language; as one of the following:
only the examples apply specifically to
PL/I:
a. A single notation variable or
1. A notation variable is the name of a notation constant.
general class of elements in the
programming language. A notation b. Any collection of notation
variable must consist of: variables, notation constants,
syntax-language symbols, and
a. Lower-case letters, decimal keywords surrounded by braces or
digits, and hyphens and must begin brackets.
wi th a letter.
4. Braces {} are used to denote grouping
b. Either all lower-case letters or a of more than one element into a
combination of lower-case and syntactic unit.
upper-case letters. In the latter
case, there must be one portion in Example:
all lower-case letters and one
portion in all upper-case letters,
and the two portions must be identifier
FIXED l
{
separated by a hyppen. FLOAT j
All such variables used are defined in The vertical stacking of syntactic
the manual either syntactically, using units indicates that a choice is to be
this notation, or are defined made. The above example indicates
semantically. For example: that the variable "identifier" must be
fo1lowed by the literal occurrence of
a. digit. This denotes the either the word FIXED or the word
occurrence of a digit, which may FLOAT.
be 0 through 9 inclusive.
5. The vertical stroke I indicates that a
b. file-expression. This denotes the choice is to be made.
occurrence of a reference to a
file. Example:
c. DO-statement. This denotes the identifier (FIXEDIFLOAT}
occurrence of a DO statement. The
upper-case letters are used to This has exactly the same meaning as
indicate a language keyword. the above example. Both methods are
used in this manual to display
2. A notation constant denotes the alternatives.

section A: Syntax Notation 305

 6. Square brackets [ ] denote options. The variable "digit" mayor may not
Anything enclosed in brackets may occur since it is surrounded by
appear once or may not appear at all. brackets. If it does occur, it may be
Brackets can serve the additional repeated one or more times.
purpose of delimiting a syntactic
unit. For example:
({[lower-bound:] upper-bound}I*) 8. Underlining is used to denote an
element in the language being
This denotes the occurrence of either described when there is conflict
a literal asterisk or the variable between this element and one in the
"upper-bound," but not both. If syntax language. For example:
"upper-bound" appears, it can
optionally be preceded by the
syntactic unit composed of the operand {'Il} operand
variable "lower-bound" and the literal
colon.
This denotes that the two occurrences
7. Three dots ••• denote the occurrence of the variable "operand" are
of the immediately preceding syntactic separated by either an "and" ('> or an
unit one or more times in succession. ·or· (I). The operator I is
underlined to indicate that it is an
For example: "or" symbol in the PL/I language
rather than an ·or" symbol in the
[digit] ••• syntax language.

306 OS PL/I CKT AND OPT LRM PART II

 Section B: Character Sets with EBCDIC and Card-Punch Codes

60-CHARACTER SET

Character Card-Punch 8-Bit EBCDIC

Code

o o 1111 0000
1 1 1111 0001
Character Card-Punch 8-Bit EBCDIC 2 2 1111 0010
Code 3 3 1111 0011
4 4 1111 0100
5 5 1111 0101
blank no punches 0100 0000 6 6 1111 0110
12-8-3 0100 1011 7 7 1111 0111
< 12-8-4 (12-8-6) 0100 1100 8 8 1111 1000
( 12-8-5 (0-8-4) 0100 1101 9 9 1111 1001
+ 12-8-6 (12) 0100 1110
,I 12-8-7 (NA)
12 (NA)
0100
0101
1111
0000
$ 11-8-3 0101 1011 Composite
11-8-4 0101 1100 Symbols Card-Punch
*) 11-8-5 (12-8-4) 0101 1101
11-8-6 0101 1110 <= 12-8-4, 8-6 (12-8-6, 8-3)
11-8-7 (NA) 0101 1111 II 12-8-7, 12-8-7 (NA)
11 0110 0000 11-8-4, 11-8-4
/ 0-1 0110 0001 ....**
< 11-8-7, 12-8-4 (NA)
, 0-8-3 0110 1011 .... > 11-8-7, 0-8-6 (NA)
I 0-8-4 (NA) 0110 1100 .. = 11- 8-7, 8-6 (NA)
0-8-5 (NA) 0110 1101 >= 0-8-6, 8-6 (8-6, 8-3)
> 0-8-6 (8-6) 0110 1110 /* 0-1, 11-8-4
? 0-8-7 (12-0) 0110 1111 */ 11-8-4, 0-1
8-2 (8-5) 0111 1010 -> 11,·0-8-6 (11, 8-6)
# 8-3 (NA) 0111 1011
til 8-4 (NA) 0111 1100
8-5 (8-4) 0111 1101
= 8-6 (8-3) 0111 1110
A 12-1 1100 0001
B 12-2 1100 0010
C 12-3 1100 0011
D 12-4 1100 0100
E 12-5 1100 0101
F 12-6 1100 0110
G 12-7 1100 0111 The card-punch codes given in brackets
B 12-8 1100 1000 are BCDIC codes that differ from the
I 12-9 1100 1001 corresponding EBCDIC codes.
J 11-1 1101 0001
K 11-2 1101 0010
L 11-3 1101 0011 NA indicates that the symbol has no
M 11-4 1101 0100 representation in BCDIC. BCDIC codes can
N 11-5 1101 0101 be used in the PL/I source program provided
o 11-6 1101 0110 that the CHARSET(BCD) compiler option is
P 11-7 1101 0111 specified. No BCDIC 8-bit codes are given
Q 11-8 1101 1000 here since, when the CHARSET(BCD) option is
R 11-9 1101 1001 specified, all BCDIC codes in the s·ource
S 0-2 1110 0010 program are converted by the compiler into
T 0-3 1110 0011 EBCDIC.
U 0-4 1110 0100
V 0-5 1110 0101 Although the full PL/I 60-character set
W 0-6 1110 0110 is not available in BCDIC, all the 48-
X 0-7 1110 0111 character set (see next page) is available,
Y 0-8 1110 1000 so if CHARSET(48,BCD) is specified, all
Z 0-9 1110 1001 PL/I operations can be performed.

section B: Character sets With EBCDIC and Card-punch Codes 307

".a-CHARACTER SET
Character Card-Punch 8-Bit EBCDIC ComEgsite 60-Char Set
Code Svmbols Card Punch Eguivalent
blank no punches 0100"0000
12-8-3 0100 1011 12-8-3, 12-8-3
( 12-8-5 (0-8-4 ) 0100 1101 LE 11-3, 12-5 <=
+ 12-8-6 (12) 0100 1110 CAT 12-3, 12-1, 0-3 II
$ 11-8-3 0101 1011 ** 11-S- fI, 11-8-4 **
•
)
11-8-4 0101 1100
11-S-5 (12-8-4) 0101 1101
NL
NG
11-5, 11-3
11-5, 12-1
~
...>
11 0110 0000 NE 11-5, 12-5 ...=
0-1 0110 0001 0-1, 0-1
/
0-8-3
8-5 (8-4)
0110 1011
0111 1101
,.
//

AND
0-S-3, 12-8-3
12-1, 11-5, 12-4
I
:
&
=
A
S-6 (8-3)
12-1
0111 1110
1100 0001
SE
GT
12-1, 12-5
12-7, 0-3
>=
>
8 12-2 1100 0010 LT 11-3, 0-3 <
C 12-3 1100 0011 NOT 11-5, 11-6, 0-3
D 12-4 1100 0100 OR 11-6, 11-9 I
E 12-5 1100 0101 /* 0-1, 11-S-4 /*
F 12-6 1100 0110 */ 11-8-4, 0-1 */
G 12-7 1100 0111 PT 11-1, 0-3 ->
B 12-8 1100 1000
I 12-9 1100 1001
J 11-1 1101 0001
J( 11-2 1101 0010
L 11-3 1101 0011 When using the 4S-character set, the
M 11-4 1101 0100 following rues must be observed:
N 11-5 1101 0101
0 11-6 1101 0110 1. The two periods that replace the colon
P 11-7 1101 0111 must be immediately preceded by a
Q 11-8 1101 1000 blank if the preceding character is a
R 11-9 1101 1001 period.
S, 0-2 1110 0010
T 0-3 1110 0011 2. The two slashes that replace the
U 0-4 1110 0100 percent symbol must be immediately
V 0-5 1110 0101 preceded by a blank if the preceding
W 0-6 1110 0110 character is an asterisk, or
X 0-7 1110 0111 immediately followed by a blank if the
Y O-S 1110 1000 follOWing character is an asterisk.
Z 0-9 1110 1001
0 0 1111 0000 3. The sequence "comma period" represents
1 1 1111 0001 a semicolon except when it occurs in a
2 2 1111 0010 comment, a character string, or a
3 3 1111 0011 picture specification or when it is
fI 4 1111 0100 immediately followed by a digit.
5 5 1111 0101
6 6 1111 0110 fl. If CBARSET(4S) is specified, 60-
7 7 1111 0111 character set symbols may be freely
a 8 1111 1000 intermixed with 4S-character set
9 9 1111 1001 symbols and will be accepted by the
compiler as valid input.
5. 4S-character set "reserved" words
(e.g., ST, LE, CAT, etc.,) must be
preceded and followed by a blank or a
comment.
The card-punch codes given in brackets
are BCDIC codes that differ from the 6. 4S-character set symbo1s represent
corresponding EBCDIC codes. BCDIC codes their 60-character set equivalents
can be used in the PL/I soarce proqram only when they do not occur in a
provided that the CHARSET(B.CD) compiler colIIDent r a cbaracter string r or a
o~ion is specified. No BCDIC a-bit codes picture specification.
are given here since, wben tbe CBARSET(BCD)
o.ption is specified, all BCOIC codes in the A record containing part or all of a
soux-ce proqram are converted by the _a-character set reserved word must be
e_piler into EBCDIC. 3 characters or more in lengtb.

308 OS PL/I CKT AND OPT LRM PART II

 Section C: Keywords and Keyword Abbreviations

Keyword Abbreviation Use of Keyword

A[(w) ) format item
ABS(x) built-in function
ACOS(x) built-in function
IACTIVATE 'ACT preprocessor statement
ADD(x1,xa'X3['X~ ]) built-in function
ADDBUFF option of ENVIRONMENT attribute
ADDR(x) built-in function
ALIGNED attribute
ALL [(character-string- option of PUT statement
expression)]
ALL (x) built-in function
ALLOCATE ALLOC statement
ALLOCATION (x) ALLOCN(x) built-in function
ANY(x) built-in function
AREA condition
AREA[(size)] attribute
ARGn option of NOMAP, NOMAPIN, NOMAPOUT options
ASCII option of ENVIRONMENT attribute
ASIN(x) built-in function
ASSEMBLER ASM option of OPTIONS attribute
ATAN(x1 [, xa] ) built-in function
ATAND(x1 [,xa]) built-in function
ATANH(x) built-in function
ATTENTION ATTN condition
AUTOMATIC AUTO attribute
B[ (w)] format item
BACKWARDS attribute, option of OPEN statement
BASED[(locator-expression)] attribute
BEGIN statement
BINARY BIN attribute
BINARY(x1[,xa[,x3)]) BIN(Xs.l,xa[,x3]) built-in function
BIT [(length)] attribute
BIT (Xs. ( , Xa] ) built-in function
IBKWD option of ENVIRONMENT attribute
BLKSIZE(block-size) option of ENVIRONMENT attribute
BOOL(x1,xa,x3) built-in function
BUFFERED BUF attribute
BUFFERS(n) option of ENVIRONMENT attribute
I BUFND(n) option of ENVIRONMENT attribute
I BUFNI(n) option of ENVIRONMENT attribute
I BUFSP(n) option of ENVIRONMENT attribute
BUFOFF [(n)] option of ENVIRONMENT attribute
BUILTIN attribute
BY option of DO statement, option of
repetitive input/output specification
BY NAME BYNAME option of aSSignment statement
C(real-format-item format item
[,real-format-item)
CALL statement, option of INITIAL attribute
CEIL(x) built-in function
CHAR (X1 ( , xa] ) built-in function
CHARACTER(length)] CHAR ( (length) ) attribute
CHECK statement
CBECK[(name-list)] condition, condition prefix
CLOSE statement
COBOL option of ENVIRONMENT attribute, or
OPTIONS option/attribute
COLUMN(n) COL(n) format item
I COMPILETlME preprocessor built-in function
COMPLETION (x) CPLN(x) built-in function, pseudovariable

Section C: KeywordS and Keyword Abbreviations 309

Keyword Abbreviation Dse of Reyword
COMPLEX CPLX attribute
COMPLEX (x~, xa) CPLX(x~,xa) built-in function, pseudovariable
CONDITION COND attribute
CONDITION (name) COND(name) condition
CONJG(x) built-in function
CONNECTED CONN attribute
CONSECUTIVE option of ENVIRONMENT attribute
ICONTROL listing control statement
CONTROLLED CTL attribute
CONVERSION CONV condition, condition prefix
COPY[(file-expression)] option of GET statement
COS (x) built-in function
COSD(x) built-in function
COSH (x) built-in function
COUNT (file-expression) built-in function
I COUNTER preprocessor built-in function
CTLASA option of ENVIRONMENT attribute
CTL360 option of ENVIRONMENT attribute
ICURRENTSTORAGE(variable) CSTG(variable) built-in function
D option of ENVIRONMENT attribute
DATA option of GET or POT statement
DATAFIELD built-in function
DATE built-in function
DB option of ENVIRONMENT attribute
IDEACTIVATE IbEACT preprocessor statement
DECIMAL DEC attribute
DECIMAL(x~[,xa[,x3]]) DEC(x1 l ,xa l ,x3]]) built-in function
DECLARE DCL statement
iDECLARE IDCL preprocessor statement
DEFAULT OFT statement
DEFINED DEF attribute
DELAY statement
DELETE statement
DESCRIPTORS option of DEFAULT statement
DIM(x~,xa) built-in function
DIRECT attribute
DISPLAY statement
DIVIDE(x~,xa,x3['x_ ]) built-in function
00 statement, repetitive input/output data
specification
100 preprocessor statement
E(w,d[,s) format item
EDIT option of GET or PUT statement
ELSE clause of IF statement
IELSE clause of IIF statement
EMPTY built-in function
END statement
lEND preprocessor statement
ENDFILE(file-expression) condition
ENDPAGE(file-expression) condition
ENTRY attribute, statement
ENVIRONMENT ENV attribute, option of CLOSE statement
ERF(x) built-in function
ERFC(x) built-in function
ERROR condition
EVENT attribute, option of CALL, DELETE,
DISPLAY, READ, REWRITE, and WRITE
statements
EXCLUSIVE EXCL attribute
EXIT statement
EXP(x) built-in function
EXTERNAL EXT attribute
F(w, [,d[,s]) format item
F option of ENVIRONMENT attribute
FB option of ENVIRONMENT attribute

310 OS PL/I CKT AND OPT LRM PART II

Keyword Abbreviation Use of Keyword
FBS option of ENVIRONMENT attribute
FETCH statement
FILE attribute
FILE (file-expression) option of CLOSE, DELETE, GET, LOCATE,
OPEN, PUT, READ, REWRITE, UNLOCK, and
WRITE statements
FINISH condition
FIXED attribute
FIXED(x1 l ,x a l,x3]]) built-in function
FlXEDOVERFLOW FOFL condition, condition prefix
FLOAT attribute
FLOAT(x1 [,xa1) built-in function
FLOOR (x) built-in function
FLOW statement, option of PUT statement
FORMAT statement, option of ICONTROL statement
FORTRAN option of OPTIONS option/attribute
FREE statement
FROM (variable) option of WRITE or REWRITE statements
FS option of ENVIRONMENT att~ibute
GENERIC attribute
GENKEY option of ENVIRONMENT attribute
GET statement
GO TO GOTO statement
IGO TO IGOTO preprocessor statement
HALT statement
BBOUND(xs.,xa) built-in function
HIGB(x) built-in function
IF statement
IIF preprocessor statement
IGNORE(n) option of READ statement
lMAG(x) built-in function, pseudovariable
IN (element-area-variable) option of ALLOCATE and FREE statements
"INCLUDE preprocessor statement
INDEX(xs.,xa) built-in function
INDEXAREA [(index-area- option of ENVIRONMENT attribute
size)]
INDEXED option of ENVIRONMENT attribute
INITIAL IN~T attribute
INPUT attribute, option of OPEN statement
INTER option of OPTIONS option/attribute
XNTERNAL INT attribute
INTO (variable) option of READ statement
IRREDUCIBLE IRRED attribute
KEY (file-expression) condition
KEY(x) option of READ, DELETE, and REWRITE
statements
KEYED attribute, option of OPEN statement
KEY FROM (x) option of WRITE statement
KEYLENGTB (n) option of ENVIRONMENT attribute
KEYLOC(n) option of ENVIRONMENT attribute
KEYTO(variable) option of READ statement
LABEL attribute
LBOUND(Xs.,xa) built-in function
LEAVE option of ENVIRONMENT attribute
'LEAVE statement
LENGTB(x) built-in function
LIKE attribute
LINE(n) format item, option of PUT statement
LINENO(x) built-in function
LINESIZECexpression) option of OPEN statement
LIST option of GET or PUT statement
LOCATE statement
LOG (x) built-in function
LOG 2 (x) built-in function
~OGl.O(x) built-in function

Section C: Keywords and Keyword Abbreviations 311

Keyword Abbreviation Use of Keyword

LOW(x) built-in function

MAIN option of OPTIONS option
MAX(X1,Xa··· x n) built-in function
MIN(x1,xa··· x n) built-in function
MOD(X1,Xa) bUilt-in function
MULTIPLY(x1,Xa,x3['X~]) built-in function
NAME (file-expression) condition
NCP(n) option of ENVIRONMENT attribute
NOCHECK statement
NOCHECK[(name-list)] condition prefix
NOCONVERSION NOCONV condition prefix
NOFlXEDOVERFLOW NOFOFL condition prefix
NOFLOW statement
NOFORMAT option of 'CONTROL statement
NOLOCK option of READ statement
NOMAP[(arg-list)] option of OPTIONS attribute
NOMAPIN[(arg-list)] option of OPTIONS attribute
NOMAPOUT[(arg-list)] option of OPTIONS attribute
NOOVERFLOW NOOFL condition prefix
tiNOPRINT listing control statement
NORESCAN option of IACTIVATE statement
NOSIZE condition prefix
NOSTRINGRANGE NOSTRG condition prefix
NOSTRINGSIZE NOSTRZ condition prefix
NOSUBSCRIPTRANGE NOSUBRG condition prefix
IINOTE preprocessor statement
NOUNDERFLOW NOUFL condition prefix
NOWRI1f£ option of ENVIRONMENT attribute
NOZERODIVIDE NOZDIV condition prefix
NULL built-in function
OFFSET[(area-name)] attribute
OFFSET (X1,Xa) built-in function
ON statement
ONCHAR built-in function, pseudovariable
ONCODE built-in function
ONCOUNT built-in function
ONFILE built-in function
ONKEY built-in function
ONLOC built-in function
ONSOURCE built-in function, pseudovariable
OPEN statement
OPTIONS (list) attribute, option of ENTRY and
PROCEDURE statements
ORDER option of BEGIN and PROCEDURE statements
I OTHERWISE OTHER clause of select-group
OUTPUT attribute, option of OPEN statement
OVERFLOW OFL condition, condition prefix
P 'picture specification' format item
PAGE format item, option of PUT statement
~PAGE listing control statement
PAGESIZE(W) option of OPEN statement
IPARMSET(parameter) preprocessor built-in function
PASSwORD (password-specification) option of ENVIRONMENT attribute
PENDING (file-expression) condition
PICTURE PIC attribute
tPLIRETV built-in function
POINTER PTR attribute
POINTER(x1,xa) PTR(x1,xa) built-in function
POLY(X 1 ,xa) built-in function
POSITION (expression) POS (expression) attribute
PRECISION(x1,xa[,x3]) PREC(x1 ,xa(,x3 ]) built-in function
PRINT attribute, option of OPEN statement
I~PRINT listing control statement
PRIORITY(x) option of CALL statement
PRIORITY [ (x) ] built-in function, pseudovariable

312 OS PL/I CKT AND OPT LRM PART II

Keyword Abbreviation Dse of KeyWord
PROCEDURE PROC statement
JPROCEDURE JPROC preprocessor statement
PROD (x)
PUT
R(x)
• built-in function
statement
format item
RANGE option of DEFAULT statement
READ statement
REAL attribute
REAL (x) built-in function, pseud~variable
RECORD attribute, option of OPEN statement
RECORD (file-expression) condition
RECSIZE(record-length) option of ENVIRONMENT attribute
RECURSIVE option of PROCEDURE statement
REDUCIBLE REO attribute
REENTRANT option of OPTIONS option
REFER(element-variable) option of BASED attribute
REGIONAL(11213) option of ENVIRONMENT attribute
RELEASE statement
REORDER option of BEGIN and PROCEDURE statements
REPEAT ( X1. , xa ) built-in function
I REPEAT option of DO statement
REPLY(c) option of DISPLAY statement
REREAD option of ENVIRONMENT attribute
RESCAN option of IACTIVATE statement
IRETCODE option of OPTIONS attribute
RETURN statement, preprocessor statement
RETURNS (attribute-list) attribute, option of PROCEDURE statement
I REUSE option of ENVIRONMENT attribute
REVERT statement
REWRITE statement
ROUND(X1.,xa) built-in function
ISAMEKEY(x) built-in function
SCALARVARYING option of ENVIRONMENT attribute
I SELECT statement
SEQUENTIAL SEQL attribute
SET (locator-variable) option of ALLOCATE, LOCATE, and
READ statements
SIGN(x) built-in function
SIGNAL statement
SIN(x) built-in function
SIND(x) built-in function
SINH(x) bUilt-in function
ISIS option of ENVIRONMENT attribute
SIZE condition, condition prefix
SKIP[(n) ] format item, option of GET and
POT statements
I SKIP option of ENVIRONMENT attribute
JSKIP listing control statement
SNAP option of ON and PUT statements
SQRT(x) bUilt-in function
I STATEMENT option of IPROCEDURE statement
STATIC attribute
STATUS (x) built-in function, pseudovariable
STOP statement
I STORAGE (variable) STG(variable) bUilt-in function
.STREAM attribute, option of OPEN statement
S'l'RING(x) built-in function, pseudovariable
S'l'RING(string-name) option of GET and PUT statements
S'l'RI NGRANGE STRG condition, condition prefix
STRINGSIZE STRZ condition, condition prefix
iSUB dummy variable of DEFINED attribute
SUBSCRIPTRANGE SUBRG condition, condition prefix
SUBSTR(x1.,xa[,x3]) built-in function, pseudovariable
SUM (x) built-in function
SYSIN name of standard system input file

Section C: Keywords and Keyword Abbreviations 313

Keyword Abbreviation Use of Keyword

SYSPRINT name of standard system output file

SYSTEM option of ON or DECLARE statements
TAN (x) built-in function
TAND(x) built-in function
TANH (x) built-in function
TASK attribute, option of OPTIONS option
TASK(task-name)] option of CALL statement
THEN clause of IF statement
%THEN clause of 'IF statement
TIME built-in function
TITLE (element-expression) option of OPEN statement
TO option of DO statement, option of
repetitive input/output specification
TOTAL option of ENVIRONMENT attribute
TP(MIR) option of ENVIRONMENT attribute
TRANSIENT attribute
TRANSLATE (X1,X2 (,X3]) built-in function
TRANSMIT(file-expression) condition
TRKOFL option of ENVIRONMENT attribute
TRUNC(x) built-in function
U option of ENVIRONMENT attribute
UNALIGNED UNAL attribute
UNBUFFERED UNBJJF attribute, option of OPEN statement
UNDEFINEDFILE UNDF condition
(file-expression) (file-expression)
UNDERFLOW UFL condition, condition prefix
UNLOCK statement
UNSPEC(x) built-in function, pseudovariable
I UNTIL option of DO statement
UPDATE attribute, option of OPEN statement
V option of ENVIRONMENT attribute
VALUE option of DEFAULT statement
VARIABLE attribute
VARYING VAR attribute
VB option of ENVIRONMENT attribute
VBS option of ENVIRONMENT attribute
VERIFY(x1,x2) built-in function
VS option of ENVIRONMENT attribute
VSAM option of ENVIRONMENT attribute
WAIT statement
WHEN (generic-descriptor- option in GENERIC declaration
list)
I WHEN clause of select-group
WHILE option of DO statement
WRITE statement
X(w) format item
ZERODIVIDE ZDIV condition, condition prefix

314 OS PL/I CKT AND OPT LRM PART II

 Section D: Picture Specification Characters

picture specification characters appear in Numeric character data to be read using

either the PICTURE attribute or the P- the P-format item must conform to the
format item for edit-directed input and specification contained in the P-format
output. In either case, an individual item, including editing characters. If the
character has the same meaning. A indicated character does not appear in the
discussion of the concepts of picture input stream, the CONVERSION condition is
specifications appears in chapter 13, raised.
-Editing and string Handling-.
Data aSSigned to a variable declared
Picture characters are used to describe with a character-string picture
the attributes of the associated data item, specification (or data to be written with a
whether it is the value of a variable or a character-string picture format item)
data item to be transmitted between the should conform, character by character (or
program and external storage. be convertible, character by character) to
the picture specification; if it does not,
A picture specification always describes the CONVERSION condition is raised.
a character representation that is either a Character string data read in using the P
character-string data item or a numeric format item must conform to the
character data item. A character-string specification given in the format item. If
pictured item is one that can consist of the indicated character does not appear in
alphabetic characters, decimal digits, and the input stream, the CONVERSION condition
blanks. A numeric character pictured item is raised.
is one in which the data itself can consist
only of decimal digits, a decimal point, Figures in this section i1lustrate how
the letter E, and, optionally, a plus or different picture specifications affect the
minus sign. Other characters generally representation of values when assigned to a
associated with arithmetic data, such as pictured variable or when printed using the
currency symbols, can also be specified, P-tormat item. Each figure shows the
but they are not a part of the arithmetic original value of the data, the attributes
value of the numeric character variable, of the variable from which it is assigned
although the characters are stored with the (or written), the picture speCification,
digits and are considered to be part of the and the character-string value of the
character-string value of the variable. numeric character or pictured character-
Under the optimizing compiler, the maximum string variable.
length of character string pictured data
that is guaranteed to be handled is 1023,
though longer items may be handled if
sufficient storage is available. The Picture Char acters for Character-String
checkout compiler will accept items of Data
length not exceeding 32767 characters.
Under both compilers, the maximum length of
numeric character item is 255. Only three picture characters can be used
in character-string picture specifications:
Arithmetic data assigned to a numeric
character variable is converted to x specifies that the associated position
character representation. Edi~ing, such as can contain any character whose internal
zero-suppression and the insertion of other bit configuration can be recognized by
characters, can be specified for a numeric the computer in use.
character data item.
A specifies that the associated position
Data assigned to a variable declared can contain any alphabetic character or
with a numeric picture specification (or a blank character.
data to be written with a numeric picture
format item) must be either internal coded 9 specifies that the associated position
arithmetic data or data that can be can contain any decimal digit or a blank
converted to coded arithmetic. ThUS, character.
assigned data can contain only digits and,
optionally, a decimal pOint, a sign and the A character picture specification must
exponent delimiter E. It should not contain at least one A or X.
contain any editing characters, for
example, a currency symbol; if it does, the Figure 0.1 gives examples of character-
CONVERSION condition is raised. string picture specifications. In the

Section 0: Picture Specification Characters 315

r---------------------------------------------------------------------------------------,
Source I Source Data I Picture I Character-String I
Attributes I (in constant form) I Specification I Value 1 I
CHARACTER(S) 9B/2L

CHARACTER(S) L26.1
1A variable declared with a character-string picture specification has a character-
string value only.
L---------------------------------------------------------------------------------------J
Figure D.l. pictured character-string examples

figure, the letter b indicates a blank insertion characters appearing in the

character. Note that assignments are. left- picture specification. The character-
adjusted, and any necessary padding with string value does not, however, include the
blanks is on the right. assumed location of a decimal point, as
specified by the picture character V. The
character-string value of a numeric
character variable is used whenever the
Picture Characters for Numeric variable appears in a character-string
Character Data expression operation or in an assignment to
a character-string variable, whenever the
data is printed using list-directed or
Numeric character data must represent data-directed output, or whenever a
numeric values: therefore, the associated reference is made to a character-string
picture specification cannot contain the variable that is defined on the numeric
characters X or A. The picture characters character variable. In such cases, nO data
for numeric character data can specify conversion is necessary.
detailed editing of the data.
The picture characters for numeric
A numeric character variable can be character speCifications may be grouped
considered to have two different kinds of into the following categories:
value, depending upon its use. They are
(1) its arithmetic value and (2) its • Digit and Decimal-Point Specifiers
character-string value.
• Zero suppression Characters
The arithmetic value is the value
expressed by the decimal digits of the data • Insertion Characters
item, the assumed location of a decimal
point, and possibly a sign. The arithmetic • Signs and Currency Symbol
value of a numeric character variable is
used whenever the variable appears in an • Credit, Debit, and Overpunched Signs
expression that results in a coded
arithmetic value or whenever the variable • Exponent Specifiers
is assigned to a coded arithmetic, numeric
character, or bit-string variable. In such • Scaling Factor
cases, the arithmetic value of the numeric
character variable is converted to internal A numeric character specification
coded arithmetic representation. consists of one or more fields, each field
describing a fixed-point number. A
The character-string value is the value floating-point specification has two fields
expressed by the decimal digits of the data - one for the mantissa and one for the
item, as well as all of the editing and exponent. A field may be divided into

316 OS PL/I CRT AND OPT LRM PART II

r---------------------------------------------------------------------------------------,
Source I Source Data I Picture I Character-String
Attributes I (in constant form) I Specification I Value~

FIXED (5) 12345 99999 12345

FIXED(5) 12345 99999V 12345

FIXED (5) 12345 999V99 34500 2

FIXED(5) 12345 V99999 000,¥>2

FIXED (7) 1234567 99999 345612

FIXED(3) 123 99999 00123

FIXED(5,2) 123.45 999V99 12345

FlXED(7,2) 12345.67 9V9 56 2

FIXED(5,2) 123.45 99999 00123

~The arithmetic value is the value expressed by the digits and the actual or assumed
location of the V in the specification.
2In this case, PL/I does not define the result since significant digits have been
truncated on the left. The result shown, however, is that given for these
implementations. The SIZE condition will be raised, if enabled.
L---------------------------------------------------------------------------------------J
Figure 0.2. Pictured numeric character examples

subfields by inserting a V picture fractional parts of the assigned value

specification character~ the portion are aligned on the V character~
preceding the V and that following it (if therefore, an assigned value may be
any) are subfields of the specification. truncated or extended with zero digits
at either end. (Note that if
A major requirement of the picture significant digits are truncated on the
specification for numeric character data is left, the result is undefined and a SIZE
that each field must contain at least one interrupt will occur, if SIZE is
picture character that specifies a digit enabled.) If no V character appears in
position. This picture character, however, the picture specification of a fixed-
need not be the digit character 9. other point decimal value (or in the first
picture characters, such as the zero field of a picture specification of a
suppression characters (Z or * or Y), also floating-point decimal value), a V is
specify digit positions. At least one of assumed at the right end of the field
these characters must be used to define a specification. Th1s can cause the
numeric character specification. assigned value to be truncated, if
necessary, to an integer. The V
character cannot appear more than once
in a picture specification.
DIGIT AND DECIMAL-POINT SPECIFIERS
Figure D.2 gives examples of numeric
character specifications.
The picture characters 9 and V are used in
the simplest form of numeric character
specifications that represent fixed-point
decimal values. ZERO SUPPRESSION CHARACTERS
9 specifies that the associated position
in the data item is to contain a decimal The zero suppression picture characters
digit. specify conditional digit poSitions in the
character-string value and may cause
V specifies that a decimal point is leading zeros to be replaced by asterisks
assumed at this poSition in the or blanks and non leading zeros to be
associated data item. However, it does replaced by blanks. Leading zeros are
not specify that an actual decimal point those that occur in the leftmost digit
is to be inserted. The integer and positions of fixed-point numbers or in the

Section D: picture Specification Characters 317

leftmost digit positions of the two parts characters; they cause the specified
of floating-point numbers, that are to the character to be inserted into the
left of the assumed position of a decimal associated position of the numeric
point, and that are not preceded by any of character data. They do not indicate digit
the digits 1 through 9. The leftmost or character positions, but are inserted
nonzero digit in a number and all digits, between digits or characters. Each does,
zeros or not, to the right of it represent however, actually represent a character
significant digits. Note that a floating- position in the character-string value,
point number can also have leading zeros in whether or not the character is suppressed.
the exponent field. The comma, point, and slash are conditional
insertion characters: within a string of
Z specifies a conditional digit position zero suppression characters, they, too, may
and causes a leading zero in the be suppressed. The blank (B) is an
associated data position to be replaced unconditional insertion character: it
by a blank character. When the always specifies that a blank is to appear
associated data position does not in the associated position.
contain a leading zero, the digit in the
position is not replaced by a blank ~ Insertion characters are applicable
character. The picture character Z only to the character-string value. They
cannot appear in the same field as the specify nothing about the arithmetic value
picture character * or a drifting of the data item.
character, nor can it appear to the
right of any of the picture characters causes a comma to be inserted into the
9, T, I, R, or Y in a field. associated position of the numeric
character data when no zero suppression
* specifies a conditional digit position. occurs. If zero suppression does occur,
It is used the way the picture character the comma is inserted only when an
Z is used, except that leading zeros are unsuppressed digit appears to the left
replaced by asterisks. The picture of the comma position, or when a V
character * cannot appear in the same appears immediately to the left of it
subfield as the picture character Z or a and the fractional part contains any
drifting character, nor can it appear to significant digits, or when the comma is
the right of any of the picture at the start of a string or is preceded
characters 9, T, I, R, or Y in a field. only by characters not specifying digit
positions. In all other cases where
zero suppression occurs, the comma
Figure 0.3 gives examples of the use of insertion character is treated as though
zero suppression characters. In the it were a zero suppression character
figure, the letter b indicates a blank identical to the one immediately
character. preceding it.
Note: If one of the picture characters Z is used the same way the comma picture
or * appears to the right of the picture character is used, except that a point
character V, then all fractional digit e.) is assigned to the associated
positions in the specification, as well as position. This character never causes
all integer digit poSitions, must employ point alignment in the picture
the Z or * picture character, respectively. specifications of a fixed-point decimal
When all digit positions to the right of number and is not a part of the
the picture character V contain zero arithmetic value of the data item. That
suppression picture characters, fractional function is served solely by the picture
zeros of the value are suppressed only if character V. Unless the V actually
all positions in the fractional part appears, it is assumed to be to the
contain zeros and all integer positions right of the rightmost digit pOSition in
have been suppressed. The entire the field, and point alignment is
character-string value of the data item handled accordingly, even if the pOint
will then consist of blanks or asterisks. insertion character appears elsewehre.
No digits in the fractional part are The point (or the comma or slash) can be
replaced by blanks or asterisks if the used in conjunction with the V to cause
fractional part contains any significant insertion of the point (or comma or
digit. slash) in the position that delimits the
end of the integer portion in and the
beginning of the fractional portion of a
fixed-point (or floatin9~point) number,
INSERTION CHARACTERS
as might be desired in printing, since
the V does not cause printing of a
The picture characters comma (,), pOint point. The point must immediately
(.), slash (/), and blank (B) are insertion precede or immediately follow the V. If

318 OS PL/I CKT AND OPT LRM PART II

r---------------------------------------------------------------------------------------,
Source I Source Data I Picture I Character-String I
Attributes I (in constant form) I Specification I Value 1 I
FIXED(5) 12345 ZZZ99 12345
FIXED(S) 00100 ZZZ99 bb100
FIXED(S) 00100 ZZZZZ bb100
FIXED(S) 00000 ZZZZZ bbbbb
FIXED(5,2) 123.4S ZZZ99 bb123
FIXED(S,2) 001.23 ZZZV99 bb123
FIXED(5) 12345 ZZZV99 34500 a
FIXED(5,2) 000.08 ZZZVZZ bbb08
FIXED(S,2) 000.00 ZZZVZZ bbbbb
FIXED(5) 00100 ***** **100
FIXED (5) 00000 ***** * ••••
FIXED(S,2) 000.01 •• *v·* *··01
1The arithmetic value is the value expressed by the digits and the actual or assumed
location of the V in the specification.
alf SIZE is enabled, it would be raised in this case, and the result would be as shown.
If SIZE is not enabled, the result is undefined.
L---------------------------------------------------------------------------------------J
Figure D.3. Examples of zero suppression

the point precedes the V, it will be SIGNS AND CURRENCY SYMBOL

inserted only if an unsuppressed digit
appears to the left of the V, even if
all fractional digits are significant. The picture characters S, +, and - specify
If the point immediately follows the V, signs in numeric character data. The
it will be suppressed if all digits to picture character $ specifies a currency
the right of the V are suppressed, but symbol in the character-string value of
it will appear if there are any numeric character data.
significant fractional digits (along
with any intervening zeros). These picture characters may be used in
either a static or a drifting manner. The
static use specifies that a sign, a
currency symbol, or a blank always appears
in the associated position. The drifting
/ is used the same way the comma picture use specifies that leading zeros are to be
character is used, except that a slash suppressed. In this case, the rightmost
(/) is inserted in the associated suppressed poSition associated with the
position. picture character will contain a sign, a
blank, or a currency symbol (except that
where all digit positions are occupied by
drifting characters and the value of the
B specifies that a blank character always data item is zero, the drifting character
be inserted into the associated position is not inserted).
of the character-string value of the
numeric character data. A drifting character is specified by
multiple use of that character in a picture
field. Thus, if a field contains one
Figure D.4 gives examples of the use of currency symbOl ($), it is interpreted as
insertion characters. In the figure, tbe statiC; if it contains more than one, it is
letter b indicates a blank character. interpreted as drifting. The drifting

Section D: Picture specification Characters 319

r---------------------------------------------------------------------------------------,
Source I Source Data I Picture I Character-String
Attributes I (in constant form) I Specification I Value 1
FIXED(4) 1234 9,999 1,234

FIXED(6,2) 1234.56 9, 999V. 99 1,234.56

FIXED(4,2) 12.34 ZZ.VZZ 12.34
FIXED(4,2) 00.03 ZZ.VZZ bbb03
FIXED (4 , 2) 00.03 ZZV.zz bb.03
FIXED(4,2) 12.34 ZZV.ZZ 12.34
FIXED(4,2) 00.00 ZZV.ZZ bbbbb

FIXED(9,2) 1234561.89 9,999,999.V99 1,234,561.89

FIXED(1,2) 12345.61 **,999V.99 12,345.61
FIXED(1,2) 00123.45 **,999V.99 ***123.45
FIXED(9,2) 1234561.89 9.999.999V,99 1.234.561,89
FI.XED(6) 123456 99/99/99 12/34/56

FIXED (6) 123456 99.9/99.9 12.3/4!>.6

FIXED(6) 001234 ZZ/ZZ/ZZ bbb12/34

FIXED(6) 000012 ZZ/ZZ/ZZ bbbbbb12

FIXED(6) 000000 ZZ/ZZ/ZZ bbbbbbbb
FIXED(6) 000000 **/**/** ********
FIXED(6) 000000 **B**B** **b**b**
FIXED(6) 123456 99B99B99 12b34b56

FIXED(3) 123 9BB9BB9 1bb2bb3

FIXED(2) 12 9BB/9BB 1bb/2bb

1The arithmetic value is the value expressed by the digits and the actual or assumed
location of the V in the specification.
L---------------------------------------------------------------------------------------J
Figure D.4. Examples of insertion characters

character must be specified in each digit the data item is zero: in that case, the V
position through which it may drift. is ignored. A field of a picture
specification can contain only one drifting
Drifting characters must appear in string. A drifting string cannot be
strings. A string is a sequence of the preceded by a digit position nor can i t
same drifting character, optionally occur in the same field as the picture
containing a V and one of the insertion characters * and Z.
characters comma, point, slash, or B. Any
of the insertion characters slash, comma, The position in the data associated with
or point within or immediately following the characters slash, comma, and point
the string is considered part of the appearing in a string of drifting
drifting string. The character B always characters will contain one of the
causes insertion of a blank, wherever it following:
appears. A V terminates the drifting
string, except when the arithmetic value of • slash, comma, or pOint if a significant

320 OS PL/I CKT AND OPT LRM PART II

r---------------------------------------------------------------------------------------,
Source I Source Data I Picture 1 Character-String
Attributes I (in constant form) I Specification I Value 1
FIXED(5,2) 123.45 $999V.99 $123.45
FIXED(5,2) 012.00 99$ 12$
FIXED(5,2) 001.23 $ZZZV.99 $bb1.23
FIXED (5, 2) 000.00 $ZZZV.ZZ bbbbbbb

FIXED (1) 0 $$$.$$ bbbbbb

FIXED(5,2) 123.45 $$$9V.99 $123.45
FIXEQ(5,2) 001.23 $$$9V.99 bb$1.23
FIXED(2) 12 $$$,999 bbb$012
FIXED(4) 123q $$$,999 b$1,234
FIXED(5,2) 2.45 SZZZV.99 +bb2.45

FIXED (5) 214 SS,SS9 +214

FIXED (5) -4 SS,SS9 -q

FIXED(5,2) -123.45 +999V.99 b123.45

FIXED(5,2) -123.45 -999V.99 -123.45

FIXED(5,2) 123.45 999V.99S 123.45+

FIXED(5,2) 001.23 ++B+9V.99 bbb+1.23

FIXED (5, 2) 001.23 ---9V.99 bbbl.23

•I FIXED(5,2) 1l -001.23 SSS9V.99 bb-l.23

1--------------------------------------- ------------------------ ----------------------
1 The arithmetic value is the value expressed by the digits and the actual or assumed
1
I location of the V in the specification.
L---------------------------------------------------------------------------------------J
Figure 0.5. Examples of drifting picture characters

digit has appeared to t~e left it, the V delimits the preCeding portion as
a subfield, and all digit positions of the
• the drifting symbol, if the next subfield following the V must also be part
position to the right contains the of the drifting string that commences the
leftmost significant digit of the field second subfield.

• blank, if the leftmost significant digit Only one type of sign character can
of the field is more than one position appear in each field. An 5, +, or - used
to the right as a static character can appear to the
right or left of all digits in the mantissa
If a drifting string contains the and exponent fields of a floating-point
drifting character n times, then the string specification, and to the right or left of
is associated with n-1 conditional digit all digit positions of a fixed-point
positions. The position associated with specification.
the leftmost drifting character can contain
only the drifting character or blank, never In the case in which all digit positions
a digit. Two different picture characters after the V contain drifting characters,
cannot be used in a drifting manner in the suppression in the subfield will occur only
same field. if all o~ the integer and fractional digits
are zero. The resulting edited data item
If a drifting string contains a V within will then be all blanks (except for any

Section D: Picture Specification Characters 321

insertion characters at the start of the i2-punch (for plus) or an ii-punch (for
field). If there are any significant minus) punched into the same column as a
fractional digits, the entire fractional digit. It indicates the sign of the
portion will appear unsuppressed. arithmetic data item. Only one overpunched
sign can appear in a specification for a
$ specifies the currency symbol. If this fixed-pOint number. A floating-point
character appears more than once, it is specification can contain two, one in the
a drifting character; otherwise it is a mantissa field and one in the exponent
static character. The static character field. The overpunch character can,
specifies that the character is to be however, be specified for any digit
placed in the associated position. The position within a field. The overpunched
static character must appear either to number then will appear in the specified
the left of all digit positions in a digit position.
field of a specification or to the right
of all digit positions in a I The Y picture character specifies that
specification. See details above for Izero is to be replaced by the blank
the drifting use of the character. I character.

S specifies the plus sign character (+) if CR specifies that the associated pOSitions
the data value is ~O, otherwise i t will contain the letters CR if the value
specifies the minus sign character (-). of the data is less than zero.
The character may be drifting or static. otherwise, the positions will contain
The rules are identical to those for the two blanks. The characters CR can
currency symbol. appear only to the right of all digit
positions of a field.
+ specifies the plus sign character (+) if
the data value is ~O, otherwise i t DB is used the same way that CR is used
specifies a blank. The character may be except that the letters DB appear in the
drifting or static. The rules are associated positions.
identical to those for the currency
symbol. T specifies that the associated position,
on input, will contain a digit
specifies the minus sign character (-) overpunched with a i2-punch if the value
if the data value is <0, otherwise it is ~O or an ii-punch if the value is <0.
specifies a blank. The character may be It also specifies that an overpunch is
drifting or static. The rules are to be indicated in the character-string
identical to those for the currency value.
symbol.
I specifies that the associated pOSition,
If, during or before assignment to a on input, will contain a digit
picture, the fractional digits of a decimal overpunched with a 12-punch if the value
number are truncated so that the resulting is ~O; otherwise, it will contain the
value is zero, the sign inserted in the digit with no overpunching. It also
picture corresponds to the value of the specifies that an overpunch is to be
decimal number prior to its truncation. indicated in the character-string value
ThUS, the sign in the picture may depe~d on if the data value is ~O.
how the decimal value was calculated.
R specifies that the associated position,
Figure 0.5 gives examples of the use of on input, will contain a digit
drifting picture characters. In the overpunched with an ii-punch if the
figure, the letter b indicates a blank value is <0; otherwise, it will contain
character. the digit with no overpunching. It also
specifies that an overpunch is to be
indicated in the character-string value
if the data value is <0.
I CREDIT, DEBIT, OVERPUNCHED, AND ZERO
IREPLACEMENT SIGNS IY specifies that a zero in the specified
I digit position is to be replaced
I unconditionally by the blank character.
The character pairs CR (credit) and DB
(debit) specify the signs of real numeric Figure 0.6 gives examples of the CR, DB,
character data items and usually appear in loverpunch, and zero replacement characters.
business report forms. In the figure, the letter b indicates a
blank character.
Any of the picture characters T, I, or R
specifies an overpunched sign in.the Note: The picture characters CR, DB, T, I,
associated digit position of numeric and R cannot be used with any other sign
character data. An overpunched sign is a characters in the same field.

322 OS PL/I CKT AND OPT LRM PART II

 r---------------------------------------------------------------------------------------,
Source I Source Data I Picture I Character-String
Attributes I (in constant form) I Specification I Value 1
FIXED(3) -123 $Z.99CR $1.23CR
FIXED(4,2) 12.34 $ZZV.99CR $12.34bb
FIXED(4,2) -12.34 $ZZV.99DB $12.34DB
FIXED(4,2) 12.34 $ZZV.99DB $12.34bb
FIXED(4) 1021 9991 102A
FIXED(4) -1021 Z99R 102J
FIXED(4) 1021 99T9 10Bl
FIXED(S) 00100 YYYYY bblbb
FIXED(S) 10203 9Y9Y9 lb2b3
FIXED(S,2) 000.04 YYYVY9 bbbb4
1The arithmetic value is the value expressed by the digits and the actual or assumed
location of the V in the specification.
L---------------------------------------------------------------------------------------J
IFigure D.6. Examples of CR, DB, T, I, R, and Y picture characters

r---------------------------------------------------------------------------------------,
Source Source Data I Picture I Character-String
Attributes (in constant form) I Specification I Value 1
FLOAT(S) .12345E06 V.99999E99 .12345E06
FLOAT(S) .12345E-06 V.99999ES99 .12345E-06
FLOAT(S) .12345E+06 V.99999KS99 .12345+06
FLOAT(S) -123.4SE+12 S999V.99ES99 -123.45E+12
FLOAT(S) 001.23E-Ol SSS9.V99ESS9 +123.00Eb-3
FLOAT(S) 001.23E+04 ZZZV.99KS99 123.00+02
FLOAT(S) 0Ol.23E+04 SZ99V.99ES99 +123.00E+02
FLOAT(S) OOl.23E+04 SSSSV.99E-99 +123.00Eb02

1The arithmetic value is the value expressed by the mantissa, multiplied by 10 to the
power indicated in the exponent field.
L---------------------------------------------------------------------------------------J
Figure 0.7. Examples of floating-point picture specifications

Section 0: Picture Specification Characters 323

r---------------------------------------------------------------------------------------,
Source 1 Source Data 1 Picture 1 Character-String
Attributes 1 (in constant form) 1 Specification 1 Value 1

FIXED(4,0) 1200 99F(2) 12

FIXED (7,0) -1234500 S999V99F(4) -12345

FIXED(5,5) .00012 99FC-5) 12

FIXED (6,6)· .012345 999V99FC-4) 12345

1The arithmetic value is the same as the character-string value, multiplied by 10 to

the power of the scaling factor.
L---------------------------------------------------------------------------------------J
Figure 0.8. Examples of scaling factor picture characters

EXPONENT SPECIFIERS exponent delimiters. In the figure, the

letter b indicates a blank character.

The picture characters K and E delimit the

exponent field of a numeric character
specification that describes floating-point SCALING FACTOR
decimal numbers. The exponent field is
always the last field of a numeric
character floating-point picture The picture character F specifies a scaling
specification. The picture characters K factor for fixed-point decimal numbers. It
and E cannot appear in the same appears at the right end.of the picture
specification. specification and is used in the following
format:
K specifies that the exponent field
appears to the right of the associated F «(+1-] decimal-integer-constant)
position. It does not specify a
character in the numeric character data F specifies that the optionally signed
item. decimal integer constant enclosed in
parentheses is the scaling factor. The
E specifies that the associated position scaling factor specifies that the
contains the letter E, which indicates decimal pOint in the arithmetic value of
the startlof the exponent field. the variable is that number of places to
the right (if the scaling factor is
The value of the exponent is adjusted in positive) or to the left (if negative)
the character-string value so that the of its assumed poSition in the
first significant digit of the first field character-string value.
(the mantissa) appears in the position
associated with the first digit specifier The scaling factor must not imply a
of the specification (even if it is a zero scale outside the range -128 to 127.
suppression character).
Figure 0.8 shows examples of the use of
Figure 0.7 gives examples of the use of the scaling factor picture character.

324 OS PL/I CKT AND OPT LRM PART II

 Section E: Edit-Directed Format Items

This section describes each of the edit- appear in the stream, however, unless the
directed format items that can appear in specitied field width allows for them.
the format list of a GET or PUT statement. Truncation, due to inadequate field-width
specification is on the left for arithmetic
There are three categories of format items, on the right for string items.
items: data format items, control format
items, and the remote format item. Note that the value of binary data both
on input and output is always represented
In this section, the three categories in decimal form for edit-directed
are discussed separately and the format transmission.
items are listed under each category. The
remainder of the section contains detailed Following is a list of data format
discussions of each of the format items, items:
with the discussions appearing in
alphabetic order. Fixed-point format item F

Floating-point format item E

Data Format Items Complex format item C

Picture format item p

A data format item describes the external
format of a single data item. Bit-string format item B

For input, the data in the stream is Character-string format item A

considered to be a continuous string of
characters; all blanks are treated as
characters in the stream, as are quotation
marks. Each data format item in a GET Control Format Items
statement specifies the number of
characters to be obtained from the stream
and describes the way those characters are The control format items specify the layout
to be interpreted. Strings should not be of the data set associated with a file.
enclosed in quotation marks, nor should the The following is a list of control format
letter B be used to identify bit strings. items:
If the characters in the stream cannot be
interpreted in the manner specified, the Paging format item PAGE
CONVERSION condition is raised.
Line skipping format item SKIP
For output, the data in the stream takes
the form specified by the format list. Line position format item LINE
Each data format item in a PUT statement
specifies the width of a field into which Column position format item COLUMN
the associated data item in character form
is to be placed and describes the format Spacing format item X
that the value is to take. Enclosing
quotation marks are not inserted, nor is A control format item has no effect
the letter B to identify bit strings. unless it is encountered before the data
list is exhausted.
Leading blanks are not inserted
automatically to separate data items in the The PAGE and LINE format items apply
output stream. String data is left- only to output and only to files with the
adjusted in the field, whose width is PRINT attribute. The SKIP, COLUMN and X
specified. Arithmetic data is right- format items apply to both input and
adjusted. Because of the rules for output.
conversion of arithmetic data to character
type, which can cause up to three leading The PAGE, SKIP, and LINE format items
blanks to be inserted (in addition to any have the same effect as the corresponding
blanks that replace leading zeros), there options of the PUT statement (and of the
generally will be at least one blank GET statement, in the case of SKIP), except
preceding an arithmetic item in the that the format items take effect only when
converted field. Leading blanks will not they are encountered in the format list,

Section E: Edit-directed Format Items 325

while the options take effect before any The character-string format item
data is transmitted. describes the external representation of a
string of characters.
The COLUMN format item positions the
file to the specified character position in General rules:
the current or following line. It cannot
be used in a GET STRING or PUT STRING 1. The "field-width" is an expression
statement. that is evaluated and converted to an
integer, which must be non-negative,
The spacing format item specifies each time the format item is used. It
relative horizontal spacing. On input, it specifies the number of character
specifies a number of characters in the positions in the data stream that
stream to be skipped over and ignored; on contain (or will contain) the string.
output, i t specifies a number of blanks to
be inserted into the stream. 2. On input, the specified number of
characters is obtained from the data
For the effects of control format items stream and aSSigned, with any
when specified in the first GET or PUT necessary conversion, truncation, or
statement following the opening of a file, padding, to the associated element in
see "OPEN Statement n in section J, the data list. The field width is
"Statements". always required on input, and if it
has a value equal to zero, a null
string is assumed. If quotation marks
appear in the stream, they are treated
Remote Format Item as characTers in the string.

3. On output, the associated element in

The remote format item specifies the label the data list is converted, if
of a FORMAT statement that contains a necessary, to a string of characters
format list which is to be taken to replace and is truncated or extended with
the remote format item. blanks on the right to the specified
field width before being placed into
The remote format item is: the data stream. If the field width
is equal to zero, the format item and
R(statement-Iabel-designator) its associated element in the data
list are skipped, and no characters
The "statement-Iabel-designator" is a are placed into the data stream.
label constant or scalar label variable. Enclosing quotation marks are never
inserted. If the field width is not
specified, it is assumed to be equal
to the character-string length of the
Use of Format Items element named in the data list (after
conversion, if necessary, according to
the rules given in section F, "Data
Most of the format items listed below are Conversion and Expression
followed by a specification. In all cases Evaluation").
except the picture and remote items, any
expression contained in the specification
can be given as decimal integer constants,
as element variables, or as other element B-Format Item
expressions. The value assigned to a
variable during an input operation can be
used in an expression in a format item that The B-format item is:
is associated with a later data item. An
expression is evaluated and converted to an B [(field-width)]
integer each time the format item is used.
The bit-string format item describes the
external representation of a bit string.
Each bit is represented by the character 0
Alphabetic List of Format Items or 1.

General rules:
A-Format Item
1. The "field-width" is an expression
that is evaluated and converted to an
The A-format item is: integer, which must be non-negative,
each time the format item is used. It
A [(field-width)] specifies the number of data-stream

326 OS PL/I CKT AND OPT LRM PART II

 character positions that contain (or the CONVERSION condition to be raised.
will contain> the bit string.
3. On output, the real format items
2. On input, the character representation describe the forms of the real and
of the bit string may occur anywhere imaginary parts of the complex data
within the specified field. Blanks, item in the data stream. If the
which may appear before and after the second real format item is omitted, it
bit string in the field, are ignored. is assumed to be the same as the
Any necessary conversion occurs when first. The letter I is never appended
the bit string is assigned to the to the imaginary part. If the second
associated element in the data list. real format item (or the first, if
The field width is always required on only one appears) is an F or E item,
input, and if it is equal to zero, a the internal sign will be printed only
null string is assumed. Any character if the value of the imaginary part is
other than 0 or 1 in the string, less than zero. If the real format
including embedded blanks, quotation item is a P item, the sign will be
marks, or the letter B, will raise the printed only if the S or - or +
CONVERSION condition. picture character is specified. If
the I is to be appended, it must be
3. On output, the character specified as a separate data item in
representation of the bit string is the data list, immediately follOwing
left-adjusted in the specified field, the variable that specifies the
and necessary truncation or extension complex item. The I, then, must have
with blanks occurs on the right. Any a corresponding format item (either A
necessary conversion to bit-string is or P).
performed. No quotation marks are
inserted, nor is the identifying
letter B. If the field width is equal
to zero, the format item and its COLUMN Format Item
associated element in the data list
are skipped, and no characters are
placed into the data stream. If the The COLUMN format item is:
field width is not specified, it is
assumed to be equal to the bit-string COLUMN (character-position)
length of the element named in the
data list (after conversion, if The column position format item
necessary, according to the rules positions the file to a specified character
given in section F "Data Conversion position within the current or following
and Expression Evaluation"). line. It can be used with either input or
output files.

General rules:
C-&ormat Item
1. The "character-position" is an
expression which is evaluated and
The C-format item is: converted to an integer, which must be
non-negative, each time the format
C(rea1-format-item[,real-format-item]) item is used.

The complex format item describes the 2. The file is positioned to the
external representation of a complex data specified character position in the
item. current line, provided it has not
already passed this position. On
General rules: input, intervening character positions
are ignored; on output, they are
1. Each "real-format-item" is specified filled with blanks. If the file is
by one of the F-, E-, or P-format already positioned after the specified
items. The P-format item must character poSition, the current line
describe numeric character data; it is completed and a new line is
cannot describe character-string data. started; the format item is then
applied to the following line.
2. On input, the complex format item
describes the real and imaginary parts 3. If the specified character position
of the complex data item within lies beyond the rightmost character
adjacent fields in the data stream. position of the current line, or if
If the second real format item is the value of the expression for the
omitted, it is assumed to be the same character position is less than one,
as the first. The letter I will cause then the character position is assumed

Section E: Edit-directed Format Items 327

 to be one. point number, an exponent of zero is
assumed.
Note: The rightmost character
position is determined as follows: The external form of a floating-point
number is:
a. For output files, it is determined
by the line size. [+1-] mantissa['[E](+I-}texponent]
b. For input files, the compiler uses
lE [+I-]f
the length of the current logical The mantissa must be a decimal fixed-
record to determine the line size pOint constant.
and, hence, the rightmost
character position. In the case a. The number can appear anywhere
of V-format records, this line within the specified field; blanks
size is equal to the logical may appear before and after the
record length minus the number of number in the field and are
bytes containing control ignored. If the entire field is
information. blank, the CONVERSION condition is
raised. When nO decimal point
4. The COLUMN format item has no effect appears, the expression for the
unless it is encountered before the number of fractional digits
data list is exhausted. specifies the number of character
positions in the mantissa to the
5. The COLUMN format item must not be right of the assumed decimal
used in a GET STRING or PUT STRING point. If a decimal point does
statement. appear in the number, it overrides
the specification of the number of
the fractional digits.

E-Format Item The value expressed by "field-

width" includes trailing blanks,
the exponent pOSition, the
The E-format item is: positions for the optional plus or
minus signs, the position for the
ECfield-width,number-of-fractional-digits optional letter E, and the
[,number-of-significant-digits]) position for the optional decimal
point in the mantissa.
The floating-point format item describes
the external representation of decimal b. The exponent is a decimal integer
arithmetic data in floating-point format. constant. Whenever the exponent
and preceding sign or letter E are
General rules: omitted, a zero exponent is
assumed.
1. The -field-width", "number-of-
fractional-digits", and "number-of- 3. On output, the internal data is
significant-digits" can be represented converted to floating-point, and the
by expressions, which are evaluated external data item in the specified
and converted to integers when the field has the following general form:
format item is used.
[-] (s-d digits}.{d digits}
"Field-width" specifies the total E {+I-} exponent
number of characters in the field.
In this form, s represents the number
"Number-of-fractional-digits" of significant digits, and d
specifies the number of digits in the represents the number of fractional
mantissa that follow the decimal digits. The value is rounded if
point. necessary. If the data item is
fractional, the character 0, rather
"Number-of-significant-digits" than s-d digits, appears before the
specifies the number of digits that decimal point.
must appear in the mantissa.
a. The exponent is a two-digit
2. On input, the data item in the data decimal integer constant, which
stream is the character representation may be two zeros. The exponent is
of an optionally signed decimal automatically adjusted so that the
floating-point or fixed-point constant leading digit of the mantissa is
located anywhere within the specified nonzero. When the value is zero,
field. If the data item is a fixed- zero suppression is applied to all

328 OS PL/I CKT AND OPT LRM PART II

 digit positions (except the first) point constant located anywhere within
to the left of the decimal point. the specified field. Blanks may
All other digit positions contain appear before and after the number in
zero. the field and are ignored. If the
entire field is blank, it is
b. If the above form of the number interpreted as zero.
does not fill the specified field
on output, the number is right-
adjusted and extended on the left The number of fractional digits, if
with blanks. If the number of not specified, is assumed to be zero.
significant digits is not
specified, it is taken to be 1 If nO scaling factor is specified and
plus the number of fractional no decimal point appears in the field,
digits. The field width for non- the expression for the number of
negative values of the data item fractional digits specifies the number
must be greater than or equal to 5 of digits in the field to the right of
plus the number of significant the assumed decimal point. If a
digits. For negative values of decimal pOint actually does appear in
the data item, the field width the data, it overrides the expression
must be greater than or equal to 6 for the number of fractional digits.
plus the number of significant
digits. However, if the number of If a scaling factor is specified, it
fractional digits is zero, the effectively multiplies the value of
decimal point is not written, and the data item in the data stream by 10
the above figures for the field raised to the integral value (E) of
width are reduced by 1. the scaling factor. Thus, if E is
positive, the number is treated as
c. The rounding of internal data is though the decimal point appeared E
as follows: if truncation causes places to the right of its given
a digit to be lost from the right, position. If E is negative, the
and this digit is greater than or number is treated as though the
equal to 5, then 1 is added to the decimal point appeared E places to the
digit to the left of the truncated left of its given position. The given
digit. position of the decimal pOint is that
indicated either by an actual point,
d. If the field width is such that if it appears, or by the expression
significant digits or the sign are for the number of fractional digits,
lost, the SIZE condition is in the absence of an actual point.
raised.
3. On output, the internal data is
converted, if necessary, to fixed-
pOint; the external data is the
F-Format Item character representation of a decimal
fixed-point number, rounded if
necessary, and right-adjusted in the
The F-format item is: specified field.

F(field-width[,number-of-fractional-digits If only the field width is specified

[,scaling-factor]]) in the format item, only the integer
portion of the number is written; no
The fixed-point format item describes decimal pOint appears.
the external representation of a decimal
arithmetic data item in fixed-point format. If both the field width and number of
fractional digits are specified, but
General rules: the scale factor is not, both the
integer and fractional portions of the
1. The "field-width", "number-of number are written. If the value (d)
fractional-digits", and nscaling- of the number of fractional digits Is
factor" can be represented by element greater than zero, a deCimal pOint is
expressions, which are evaluated and inserted before the rightmost Q
converted to integers when the format digits. Trailing zeros are supplied
item is used. The evaluated field when the number of fractional digits
width and number of fractional digits is less than d (the value d must be
must both be non-negative. less than the-field width)~
Suppression of leading zeros is
2. On input, the data item in the data applied to all digit positions (except
stream is the character representation the first) to the left of the decimal
of an optionally signed decimal fixed- pOint.

Section E: Edit-directed Format Items 329

 The rounding of internal data is as SKIP(O) item-carriage return with no
follows: if truncation causes a digit line spacing.
to be lost from the right, and this
digit is greater than or equal to 5, 4. If "line-number" is equal to zero, it
then 1 is added to the digit to the is assumed to be one.
left of the truncated digit.
5. The LINE format item has no effect
The integer value (E) of the scaling unless it is encountered before the
factor effectively multiplies the data list is exhausted.
value of the associated element in the
data list by 10 raised to the power of
Q, before i t is edited into its
external character representation.
When the number of fractional digits P-Format Item
is zero, only the integer portion of
the number is used.
The P-format item is:
On output, if the value of the fixed-
point number is less than zero, a P 'picture-specification'
minus sign is prefixed to the external
character representation; if it is The picture format item describes the
greater than or equal to zero, no sign external representation of numeric
appears. Therefore, for negative character data and of character-string
values of the fixed-point number, the data.
field width specification must include
a count of both the sign and the The "picture-specification" is discussed
decimal pOint. in detail in section 0, "Picture
Specification Characters" and in the
If the field width is such that any discussion of the PICTURE attribute in
character is lost, the SIZE condition section I, "Attributes".
is raised.
On input, the picture specification
describes the form of the data item
expected in the data stream and, in the
LINE Format Item case of a numeric character specification,
how the item's arithmetic value is to be
interpreted. Note that the picture
The LINE format item is: specification should accurately describe
the data in the input stream, including
LINE (line-number) characters represented by editing
characters. It the indicated character
The line position format item specifies does not appear in the stream, the
the particular line on the current or CONVERSION condition is raised.
following page of a PRINT file upon which
the next data item is to be printed. On output, the value of the associated
element in the data list is converted to
General rules: the form specified by the picture
specification before it is written into the
1. The "line-number" can be represented data stream.
by an expression, which is evaluated
and converted to an integer, which
must be non-negative, each time the
format item is used. PAGE Format Item

2. Blank lines are inserted, if

necessary. The PAGE format item is:

3. If the specified line number is less PAGE

than or equal to the current line
number, or if the specified line is The paging format item specifies that a
beyond the limits set by the PAGESIZE new page is to be established. It can be
option of the OPEN statement (or by used only with PRINT files.
default), the ENDPAGE condition is
raised. An exception is that if the General rules:
specified number is equal to the
current line number, and the column 1. The establishment of a new page
one character has not yet been implies that the file be positioned to
transmitted, the effect is as for a line one of the next page.

330 OS PL/I CKT AND OPT LRM PART II

 2. The PAGE format item has no effect General rules:
unless i t is encountered before the
data list is exhausted. 1. The "relative-position-of-next-line n
can be specified by an element
expression, which is evaluated and
converted to an integer, w, which must
be non-negative, each time the format
R-Format Item item is used. It must be greater than
zero for non-PRINT files. If it is
not, or if it is omitted, 1 is
The R-format item is: assumed.

R (statement-label-designator) 2. The new line is the wth line after the

present line.
The remote format item allows format
items in a FORMAT statement to replace the 3. If w is greater than one, then on
remote format item. input, one or more lines will be
ignored; on output, one or more blank
General rules: lines will be inserted.

1. The "statement-label-designator" is a 4. w may be equal to zero for PRINT files

label constant, or an element label only; the effect is that of a carriage
variable, or a function reference that return without line spacing.
has as its value the statement label Characters previously written may be
of a FORMAT statement. The FORMAT overprinted.
statement includes a format list that
is taken to replace the format item. 5. For PRINT files, if the specified
relative position is beyond the limit
2. The R-format item and the specified set by the PAGESIZE option of the OPEN
FORMAT statement must be internal to statement (or the default), the
the same block. (If the procedure is ENDPAGE condition is raised.
executed recursively, they must be in
the same invocation.) 6. If the SKIP format item is the first
item to be executed after a file has
3. There can be no recursion within a been opened, output commences on the
FORMAT statement. That is, a remote wth line of the first page. If w is
FORMAT statement cannot contain an R- zero or 1, it commences on the first
format item that names itself as a line of the first page.
statement label designator, nor can it
name another remote FORMAT statement 7. The SKIP format item has nO effect
that will lead to the naming of the unless i t is encountered before the
original FORMAT statement. Avoidance data list is exhausted.
of recursion can be assured if the
FORMAT statement referred to by a
remote format item does not itself
contain a further remote format item. X-Format Item

4. Any conditions enabled for the GET or

PUT statement must also be enabled for The X-format item is:
the remote FORMAT statement(s) that
are referred to. x (field-width)

5. If the GET or PUT statement is a The spacing format item controls the
single statement of an on-unit, i t relative spacing of data items in the data
cannot contain a remote format item. stream. It is not limited to PRINT files.

General rules:

SKIP Format Item 1. The "field-width n is an expression,

which is evaluated and converted to an
integer, which must be non-negative,
The SKIP format item is: each time the format item is used.
The integer specifies the number of
SKIP[(relative-position-of-next-line)] blanks before the next field of the
data stream, relative to the current
The line skipping format item specifies position in the stream.
that a new line is to be defined as the
current line. 2. On input, the specified number of

Section E: Edit-directed Format Items 331

 characters is spaced over in the data
stream and not transmitted to the
program.
3. On output, the specified number of
blank characters are inserted into the
stream.
4. The spacing format item has nO effect
unless it is encountered before the
data list is exhausted.

332 OS PL/I CKT AND OPT LRM PART II

 Priority Operator Type of Operation Reference Remarks
Table of CEIL Values
Tt

*" Arithmetic Figure F. 4 Result is in coded arithmetic form When conversions are made between decimal and binary bases, the n CEI L (n"3'32) n CEIL (n/3'32)
values of the precision attributes need to be multiplied or divided by
No conversion required
3'32, and the result needs to be rounded to an integer. This table shows 1 4 1-3 1
- If operand is in coded arithmetic form
the result of the multiplication or division and rounding. 2 7 4-6 2
Operand is converted to FIXED DECIMAL If the source precision attribute is positive, the next largest integer 3 10 7-9 3
FIXED DECIMAL if it is a CHARACTER string or numeric (in PUI terms, the CEIL value) is taken after mu~tiplication. For example: 4 14 10-13 4
1 prefix +, - Arithmetic 5 14-16 5
target character (PICTURE) representation of a 17
5*3'32=16'6
fixed-point decimal number 6 20 17-19 6
CEI L (16'6)=17
7 24 20-23 7
Operand is converted to FLOAT DECIMAL The new precision attribute would therefore be 17.
8 27 24-26 8
FLOAT DECIMAL if it is a numeric character (PICTURE) This result could have been read directly from the table, which shows 9 27-29 9
30
target representation of a floating-point decimal that CEIL (n*3.32) where n=5 is 17. 10 30-33 10
34
number If the source precision attribute is negative (the scale factor of the 11 34-36 11 1/\
37
FIXED BINARY Operand is converted to FIXED BINARY if precision attribute may be negative), the next lowest integer (in PUI 12 40 37-39 12 RI
target it is a BIT string terms, the FLOOR value) is taken. For example: 13 44 40-43 13
DI
..., Bit string BIT target All non·BIT data converted to BIT (-5) *3'32=(-16'6)
14 47 44-46 14
15 50 47-49 15
FLOOR (-16'6)=(·17)
2 .. / Arithmetic FigureF.4 Result is in coded arithmetic form
The new scale factor would therefore be -17
16 54 50-53 16
17 57 54-56 17
3 infix +,., Arithmetic Figure F. 4 Result is in coded arithmetic form 18
It can be seen from the example that the table may be used with negative 18 60 57-59
If one or both operands are CHARACTER values as well as positive, since 19 64 60-63 19
CHARACTER target or DECIMAL, non-CHARACTER operand(s) 20 67 64-66 20
FLOOR (-n)=-CEll (n)
converted to CHARACTER 21 70 67-69 21
4
" Concatenation
If operands are BIT and BINARY or both
22
23
74
77
70-73
74-76
22
23
BIT target operands are BINARY, non·BIT operand(s) 24 80 77-79 24
converted to BIT 25 83 80-82 25
5 «-.. «= =-,= >= >-,> Comparison Figure F.5 Result is always either 'l'B or 'O'B 26
27
87
90
83-86
87-89
26
27
D
6 8, Bit string BIT target All non·BIT data converted to BIT 90-92 28
28 93
7 I Bit string BIT target All non·BIT data converted to BIT 29 97 93-96 29
30 100 97-99 30 D
Figure F.3 indicates target attributes for 100-102 31
All forms of assignment See specific target 31 103 FI
all forms of assignment 107 103-106 32
32 (a
33 110 107-109 33
Figure F.1. List of priority of operations and guide to conversion rules n
110-112 34
The operators are listed in order of priority, group 1 having the highest priority ana group 7 the lowest. All operators in the same priority 113-116 35
group have the same priority. For example, the exponentiation operator * * has the same priority as the prefix + and prefix - operators and
the "not" operator,: Figure F .2. Table of eEl L (n *3.32) and CE I L (n/3.32) values
If two or more operators in priority group 1 appear in an expression, the order of priority is right to left within the expression; the rightmost
exponentiation or prefix +, -, or., operator has the highest priority, the next rightmost the next highest, and so on. For all other operators,
1/
if two or more in the same priority group appear in an expression, their relative order or priority is their order left to right within the expression.

334 OS PL/I CKT AND OPT LRM PART II

 Table of CEil Values
The following may cause conversion to any attributes:
I When conversions are made between decimal and binary bases, the n CEIL (n*3'32) n CE I L (n/3'32) ~ase Target attributes
values of the precision attributes need to be multiplied or divided by
3'32, and the result needs to be rounded to an integer. This table shows Assignment Attributes of variable on left of assignment symbol
:orm 1 4 1-3 1
the result of the multiplication or division and rounding. 2 7 4-6 2 Operand in an expression Determined by rules for evaluation of expressions
IECIMAL If the source precision attribute is positive, the next largest integer 3 10 7-9 3
umeric (in PUI terms, the CEIL value) is taken after muHiplication. For example : 4 10-13 Istream input (GET statement) Attributes of receiving field
14 4
Ion of a 5 17 14-16 5
5 4 3'32=16'6 Istream output (PUT statement) As determined by format list if stream is edit directed,
CEI L (16'6}=17 6 20 17-19 6 otherwise character-string
7 24 20-23 7
)ECIMAL The new precision attribute would therefore be 17. Argument to PROCEDURE or ENTRY Attributes of corresponding parameter
8 27 24-26 8
JRE)
This result could have been read directly from the table, which shows 9 30 27-29 9
decimal Argument to built-in function or pseudovariable Depends on the function or pseudovariable
that CEIL (n*3.32) where n=5 is 17. 10 34 30-33 10
If the source precision attribute is negative (the scale factor of the 11 37 34-36 11 INITIAL attribute Other attributes of variable being initialized
:INARY if precision attribute may be negative), the next lowest integer (in PL/I 12 40 37-39 12 RETURN statement expression Attributes specified in PROCEDURE or ENTRY statement
terms, the FLOOR value) is taken. For example: 13 44 40-43 13
14 44-46 14 DO statement, BY or TO option Attributes of control variable
T (-5) *3'32=(-16'6) 47
15 50 47-49 15 Irhe following may cause conversion to character-string:
FLOOR (-16'6)=(-17)
1 16 54 50-53 16
The new scale factor would therefore be -17 ~tatement Option
17 54-56 17 Maximum String Length Used
1 57
It can be seen from the example that the table may be used with negative 18 60 57-59 18 DISPLAY Source, 72-character maximum
=tACTER values as well as positive, since 19 60-63 19
64
operand(s} 20 64-66
Record liD KEY FROM Key length specified + 8
FLOOR (-n)=-CEIL (n) 67 20
21 67-69 21 KEY Key length specified + 8
70
22 74 70-73 22 iOPEN TITLE
or both Determined by conversion rules, 8 character maximum
23 77 74-76 23
)perand(s} trhe following may cause conversion to a binary integer:
24 80 77-79 24
25 83 80-82 25 ~tatement Option/A ttribute/Reference Precision
B 26 87 83-86 26
DECLAR E/ ALLOCATE/DEFAU L T length, size, 15
27 90 87-89 27
T dimension, bound, 15
28 93 90-92 28
repetition factor 15
T 29 97 93-96 29
30 100 97-99 30 DELAY milliseconds 31
Ites for
31 103 100-102 31
FORMAT interation factor 15
32 107 103-106 32
(and format items w 15
33 110 107-109 33
'n GET and PUT) d 7
110-112 34
le priority s 7
113-116 35
ators and p 7
Figure F.2. Table of CEIL (n*3.32) and CEIL (n/3.32) values iOPEN L1NESIZE 15
the rightmost
PAGESIZE 15
:>perators,
the expression, 110 SKIP 15
LINE 15
IGNORE 15

~AIT statement expression option 31

lMost statements subscript 15

Figure F .3. Circumstances causing conversion

 Section F: Data Conversion and Expression Evaluation

The purpose of this section is to help the Figure F.4 shows, for all arithmetic
user analyze a mixed expression, involving operations, the conversions that will take
problem data, to determine the conversions place.
that will occur, and the effect these
conversions will have on the final result. Figure F.S shows, for all problem data
In this context, an assignment is comparisons, the conversions that will take
considered as a special case of a mixed place.
expression. An expression is termed "mixed"
for one of two reasons: Source to target rules are given for
each of the following data types:
1. Operands have attributes that differ.
For example, Coded Arithmetic:

DCL A CHAR(6),B FIXED BINARY(3l); FIXED BINARY

FIXED DECIMAL
A=B; FLOAT BINARY
FLOAT DECIMAL
B is converted to character-string
form before assignment to A. PICTURE (numeric character)

2. Operands have attributes that are not CHARACTER

compatible with the operation to be
performed. For example, BIT

DCL C BIT(10) VARYING; The following pages take each of these

data types as a target and give the
C=C+Ci conversion rules for all the others taken
as sources to that target. The source to
C is converted to an arithmetic value target rules are used directly for all
before the addition is performed. The conversions that do not involve operators.
arithmetic result of the addition is See tigure F.3.
converted to bit-string form before
assignment back to C. The relationship between figures F.l,
F.4, and F.S, and the source to target
This section gives all the circumstances rules is illustrated as follows:
and rules under which such conversions take
place.
r----------,
Conversions may also occur in situations IFigure F.11-------,
other than assignment or expression L---- -----J I
evaluation. However, the rules given here 1
are directly applicable to these 1
situations. Figure F.3 lists all the r----------, I
circumstances under which conversion may 1Figure F. 41 1
occur. L----------J I
1 I
1 V
1 r----------,
1 IFigure F.51
SECTION ORGANIZATION I L----------J
1 I
V V V
The conversion rules are presented by
figures F.l, F.4, and F.S, and by source to
r----------------------,I
Isource to target rules
target rules. L----------------------J
Figure F.l shows the operations that may One other figure, tigure F.2, is an aid
be performed, gives their priority in to calculating the new precision resulting
expression evaluation, and contains from a conversion.
references to figures F.4 and F.S, and to
source to target rules where further The placement of the figures in this
information may be obtained. section is designed so that the user can

section F: Data Conversion and Expression Evaluation 335

have access to most of the information at reference S gives the attributes of the
one page opening. Figures F.l and F.2 are result as FIXED BINARY(p,q), where the
together on a foldout page so that they are precision for multiplication is:
clear of the normal page. Figures F.4 and
F.5 are each on a foldout page and placed p=1+(1+2*3.32)+S=14
at the back of the section. Thus, figures q=(1*3.32)+0=4
F.l, F.2, and F.4 or F.5, and specific
source to target rules can all be viewed • resultl has attributes FIXED
simultaneously. BINARY(14,4)

EXAMPLE OF USE OF THE CONVERSION RULES

step 2

The following example illustrates how

information is retrieved from the figures Refer to figure F.4a using the attributes
and the source to target rules. of resultl as the first operand and the
attributes of FD as the second operand.
DCL FB FIXED BINARY(S), This gives the code reference 7. In figure
FD FIXED DECIMAL(5,2), F.4c, code reference 7 gives the attributes
CH CHARACTER(12)~ of the result as FIXED BINARY(p,q), where
CH=4.2*FB+FD~ the precision for addition is:

From the priority rules in figure F.l, the p=1+MAX(14-4,(Cl+S*3.32)-2*3.32»+7=19

assignment statement is executed in the q=MAX(4, (2*3.32»=7
following steps:
• result2 has attributes FIXED
1. resultl=4.2*FB BINARY (19, 7)

2. result2=resultl+FD

3. CH=result2 Step 3

The attributes of the result at each

step are determdned as follows. Refer to the rules for FIXED BINARY source
to CHARACTER target. The source is first
converted to FIXED DECIMALCp,q), where

step 1 p=1+19/3.32=7
q=7/3.32=3

The constant 4.2 has implied attributes of Refer to the rules for FIXED DECIMAL
FIXED DECIMALC2,1). source to CHARACTER target. The decimal
constant is assigned to an intermediate
Refer to figure F.4a using the string of length 10.
attributes of the constant as the first
operand and the attributes of FB as the The intermediate string is assigned to
second operand. This gives the code CH, which is padded on the right with two
reference S. In figure F.4d, code blank characters.

336 OS PL/I CRT AND OPT LRM PART II

Source: Target: Coded Arithmetic

Coded Arithmetic

The four data types FIXED BINARY, FIXED DECIMAL, FLOAT BINARY, and
FLOAT DECIMAL are all coded arithmetic data. Rules for conversion
between them are given under each data type taken as a target.
However, the following general points should be noted:

• Small changes in value may occur due to truncation on the right in

conversion from decimal to binary, and between fixed-point decimal
and floating-point decimal.

• If a complex value is converted to a real value, the imaginary

part is ignored. If a real value is converted to a complex value,
the imaginary part is zero.

PICTURE (numeric character)

Data is first interpreted as decimal with scale and precision

determined by the corresponding PICTURE specification. The item is
then converted to the base, scale, mode, and precision of the target.
See under specific target types of coded arithmetic data using FIXED
DECIMAL or FLOAT DECIMAL as the source.

CHARACTER

The source string must represent a valid arithmetic constant or

complex expression; otherwise, the CONVERSION condition will be
raised, if enabled. The constant can be signed, and can be surrounded
by blanks, but cannot contain blanks between the sign and the value,
or between the end of the real part and the sign preceding the
imaginary part of a complex expression.

A null string gives the value zero.

The constant will have base, scale, mode, and prec~s~on attributes.
It will be converted to the attributes of the target when they are
independent of the source attributes, as in the case of assignment.
see under specific target types of coded arithmetic data using the
attributes of the constant as the source.

However, if an intermediate target is necessary, as is the case in

evaluation of an operational expression, the attributes of the
intermediate target are those it would have if a decimal fixed-point
integer of precision (15,0) had appeared in place of the string.
(This allows the compiler to generate code to handle all cases,
regardless of the attributes of the contained constant.)
Consequently, any fractional portion of the constant is lost. See
under specific target types of coded arithmetic data using FIXED
DECIMAL as the source.

If a character string which represents a complex number is assigned

to a real target, the complex part of the string is not checked for
valid arithmetic characters and CONVERSION will not be raised,
since only the real part of the string is assigned to the target.

BIT

The source string is interpreted as an unsigned binary integer whose

precision is (31,0) if the conversion occurs during evaluation of an
operational expression, or whose precision is (56,0) if the conversion
occurs during an assignment. The greater precision allowed for in an
assignment is possible because the compiler can readily determine the

Section F: Data Conversion and Expression Evaluation 331

Source: 'l'arget: coded Arithmetic
(continued)

BIT (continued)

final target. See under specific target types of coded arithmetic

data using FIXED BINARY as the source.

If the source string is longer than the allowable precision, bits on

the left are ignored: if nonzero bits are lost, the result is
undefined and the SIZE condition will be raised if enabled.

A null string gives the value zero.

338 OS PL/I CRT AND OPT LRM PART II

Source: Target: FIXED BINARY

FIXED BINARY

The binary point alignment is maintained during precision conversion,

and therefore padding or truncation can occur on the left or the
right. If nonzero bits on the left are lost, the result is undefined;
the SIZE condition will be raised, if enabled.

FIXED DECIMAL

If the precision of the source is (P~,q1)' the precision of the result

is (P2,q2)' where p2=1+CEIL(p~*3.32) and q2=CEIL(q~*3.32). If the
calculated value of P2 exceeds 31, significant digits on the left may
be lost, this will cause the SIZE condition to be raised, if enabled,
and the result is undefined.

FLOAT BINARY

This conversion can occur only when data is assigned. The precision
conversion is the same as that given for FIXED BINARY to FIXED BINARY
with p~ as declared or indicated and q~ as indicated by the binary
point position and modified by the value of the exponent.

FLOAT DECIMAL

This conversion can occur only when data is assigned. The precision
conversion is the same as that given for FIXED DECIMAL to FIXED BINARY
with P1 as declared or indicated and q~ as indicated by the d~cimal
point position and modified by the value of the exponen~.

PICTURE (numeric character>

CHARACTER
BIT

See under Coded Arithmetic Target.

Section F: Data Conversion and Expression Evaluation 339

Source: Target: FIXED DECIMAL

FIXED BINARY

If the precision of the source is (P1,q1)' the precision of the result

is (P2,Q2). where P2=1+CEIL(p1/3.32) and Q2=CEIL(Q1/3.32).

FIXED DECIMAL

The decimal point alignment is maintained during precision conversion,

and therefore padding or truncation can occur on the left or the
right. If nonzero bits on the left are lost, the result is undefined;
the SIZE condition will be raised, if enabled.

FLOAT BINARY

This conversion can occur only when data is assigned. The prec1s10n
conversion is the same as that given for FIXED BINARY to FIXED DECIMAL
with P1 as declared or indicated and Q1 as indicated by the binary
point position and modified by the value of the exponent.

FLOAT DECIMAL

This conversion can occur only when data is assigned. The precision
conversion is the same as that given for FIXED DECIMAL to FIXED
DECIMAL with P1 as declared or indicated and Q1 as indicated by the
decimal pOint position and modified by the value of the exponent.

PICTURE (numeric character)

CHARACTER
BIT

See under Coded Arithmetic Target.

340 OS PL/I CKT AND OPT LRM PART II

Source: Target: FLOAT BINARY

FIXED BINARY

If the precision of the source is (P1,Q1)' the prec1s10n of the result

is P2, where P2=P1. The exponent will indicate any fractional part of
the value.

FIXED DECIMAL

If the precision of the source is (P1,Q1)' the precision of the result

is P2, where P2=CEIL(p1*3.32). The exponent will indicate any
fractional part of the value.

FLOAT BINARY

The prec1s1on of the result may be converted from short to long

precision by padding with zeros on the right, or may be converted from
long to short precision by truncation on the right.

FLOAT DECIMAL

If the precision of the source is (P1,Q1)' the precision of the result

is P2, where P2=CEIL(p1*3.32).

PICTURE (numeric character)

CHARACTER
BIT

See under Coded Arithmetic Target.

Section F: Data Conversion and Expression Evaluation 341

Source: Target: FLOAT DECIMAL

FIXED BINARY

If the precision of the source is CP1,Q1)' the prec1s10n of the result

is P2, where P2=CEILCP1/3.32). The exponent will indicate any
fractional part of the value.

FIXED DECIMAL

If the precision of the source is CP1,Q1)' the prec1s1on of the result

is P2, where P2=P1. The exponent will indicate any fractional part of
the valuE.

FLOAT BINARY

If the precision of the source is CP1)' the precision of the result is

P2, where P2=CEILCP1/ 3 • 32 ).

FLOAT DECIMAL

The precision of the result may be converted from short to long

precision by padding with zeros on the right, or may be converted from
long to short precision by truncation on the right.

PICTURE Cnumeric character)

CHARACTER
BIT

See under coded Arithmetic Target.

342 OS PL/I CKT AND OPT LRM PART II

Source: Target: PICTURE (numeric character)

Upon conversion to numeric character form, the source data acquires

attributes that depend entirely on the known attributes of the target
variable. Any PICTURE specification implies coded arithmetic data,
which is either FIXED DECIMAL or FLOAT DECIMAL. The following rules
for different source to numeric character target show those target
attributes that are necessary to permit error-free assignment.

FIXED BINARY

If the precision of the source is (P1,q1)' the target must imply,

FIXED DECIMAL (l+x+q-y,q) or

FLOAT DECIMAL (x)
where x>=CEIL(p1/3.32),y=CEIL(q1/3.32) , and q>=y.

FIXED DECIMAL

If the precision of the source is (P1,Q1)' the target must imply,

FIXED DECIMAL (x+q-pl,q) or

FLOAT DECIMAL (x)
where x>=p and q>=q1.

FLOAT BINARY

If the precision of the source is (P1), the target must imply,

FIXED DECIMAL (p,q) or

FLOAT DECIMAL (p)
where p>=CEIL(p1/3.32) and the values of p and q take account of
the range of values that may be held by the exponent of the
source.

FLOAT DECIMAL

If the precision of the source is (P1)' the target must imply,

FIXED DECIMAL (p,q) or

FLOAT DECIMAL (p)
where P>=P1 and the values of p and q take account of the range of
values that may be held by the exponent of the source.

PICTURE (numeric character)

The implied attributes will be either FIXED DECIMAL or FLOAT DECIMAL.

See the respective entries for this target.

CHARACTER
The source string must represent a valid arithmetic constant: otherwise the
CONVERSION condition will be raised if enabled. (See Target: Coded Arithmetic).

section F: Data Conversion and Expression Evaluation 343

Source: Target: PICTURE (numeric character)
(continued)

BIT

If the length of the source string. is (n), the target must imply,

FIXED DECIMAL (l+x+q,q) or

FLOAT DECIMAL (x)
where x>=CEIL{n/3.32) and q>=O.

344 OS PL/I CRT AND OPT LRM PART II

Source: Target: CHARACTER

Coded Arithmetic

The arithmetic value is converted to a decimal constant. The constant

is inserted into an intermediate character-string whose length is
derived from the attributes of the source. The intermediate string is
assigned to the target according to the rules given for CHARACTER to
CHARACTER.

Note that the rules for coded arithmetic to character-string

conversion are also used for list-directed and data-directed output,
and for evaluating keys (even for REGIONAL files).

FIXED BINARY

The binary precision (P1,q1) is first converted to the equivalent

decimal precision (p,q), where p=1+CEIL(P1/3.32) and q=CEIL(Q1/3.32).
Thereafter the rules are the same as those given for FIXED DECIMAL to
CHARACTER.

FIXED DECIMAL

A decimal fixed-point source with precision (p,q) is converted as

follows:

1. If p>=q>=O then:

• The constant is right adjusted in a field of width p+3.

• Leading zeros are replaced by blanks, except for a single zero

that immediately precedes the decimal point of a fractional
number.

• A minus sign will precede the first digit of a negative number.

A positive value is unsigned.

• Unless the source is an integer, the constant has q fractional

digits.

2. If p<q or q<O, a scaling factor is appended to the right of the

constant. The scaling factor has the form:

F{+I-}nnn, where {+I-}nnn has the value of q.

The length of the intermediate string is p+k+3, where k is the

number of digits necessary to hold the value of q (not including
the sign or the letter F).

If the arithmetic value is complex, the intermediate string consists

of the imaginary part concatenated to the real part. The left-hand,
or real, part is generated exactly as a real source. The right-hand,
or imaginary, part is always signed, and it has the letter I appended.
The generated string is a complex expression with no blanks between
its elements. The length of the intermediate string is:

2*p+7 for p>=q>=O and

2*(p+k)+1 for p<q or q<O.

The following examples show the intermediate strings that are

generated from several real and complex fixed-point decimal values:

precision: (5,0) (4,1) (4,-3) (2,1)

value 2941 -121.1 -3219000 1.2+0.31
string 'bbbb2941' 'b-121.1' '-3279F+3' 'bbb1.2+0.3I'

section F: Data Conversion and Expression Evaluation 345

Source: Target: CHARACTER
(continued)

FLOAT BINARY

The floating-point binary precision (P1) is first converted to the

equivalent floating-point decimal precision (p), where
p=CEIL(p1/3.32). Thereafter the rules are the same as those given for
FLOAT DECIMAL to CHARACTER.

FLOAT DECIMAL

A decimal floating-point source with precision (p) is converted as if

it were transmitted by an E-format item of the torm E(w,d,s) where:

w, the length of the intermediate string, is p+6.

d, the number of fractional digits, is p-1.
s, the number of significant digits, is p.

An E-format item generates a floating-point decimal constant with a

signed 2-digit exponent (see section E, "Edit Directed Format Items").

If the arithmetic value is complex, the intermediate string consists

of the imaginary part concatenated to the real part. The left-hand,
or real, part is generated exactly as a real source. The right-hand,
or imaginary, part is always signed, and it has the letter I appended.
The generated string is a complex expression with no blanks between
its elements. The length of the intermediate string is:

2*p+13.

The following examples show the intermediate strings that are

generated from several real and complex floating-point decimal values:

precision: (5) (5) (3)

value 1735*10**5 -.001663 1
string 'b1.73~OE+08' '-1.6630E-03' 'b1.00E+OO'

precision: (5)
value 17.3+1.51
string 'b1.7300E+01+1.5000E+OOI'

PICTURE (numeric character)

A real numeric character field is interpreted as a character string

and assigned to the target string according to the rules given for
CHARACTER to CHARACTER. If the numeric character field is complex,
the real and imaginary parts are concatenated before assignment to the
target string. Insertion characters wi 11 be included in the target". string.

CHARACTER

The source string is assigned to the target string from left to right.
If the source string is longer than the target, excess characters on
the right are ignored, and the STRINGSIZE condition will be raised, if
enabled. If the target is longer than the source, the target is
padded on the right with blanks.

BIT
Bit 0 becomes character 0 and bit 1 becomes character 1. A null bit
string becomes a Dull character string. The generated character
string is assigned to the target string according to the rules given
for CHARACTER to CHARACTER.

346 OS PL/I CKT AND OPT LRM PART II

Source: Target: BIT

Coded Arithmetic

If necessary, the arithmetic value is converted to binary and both the

sign and any fractional part are ignored. (If the arithmetic value is
complex, the imaginary part is also ignored.) The resulting binary
integer is treated as a bit string. It is assigned to the target
according to the rules given for BIT to BIT.

FIXED BINARY

If the prec1s1on of the source is (p,q), the length of the

intermediate bit string is given by:

MIN (31, (p-q» •

If (p-q) is negative or zero, the result is a null bit string.

The following examples show the intermediate strings that are

generated from several fixed-point binary values:

precision: (1) (3 ) (4,2)

value 1 -3 1.25
string 'l'B 'Oll'B 'Ol'B

FIXED DECIMAL

If the prec1s1on of the source is (p,q>, the length of the

intermediate bit string is given by:

MIN(31,CEIL«p-q)*3.32».

If (p-q) is negative or zero, the resul·t is a null bit string.

The following examples show the intermediate strings that are

generated from several fixed-point decimal values:

precision: (1) (2,1)

value 1 1.1
string 'OOOl'B 'OOOl'B

FLOAT BINARY

If the prec1s1on of the source is (p), the length of the intermediate

bit string is given by:

MIN(31,p).

FLOAT DECIMAL

If the precision of the source is (p), the length of the intermediate

bit string is given by:

MIN(31,CEIL(p*3.32».

PICTURE (numeric character)

Data is first interpreted as decimal with scale and precision

determined by the corresponding PICTURE specification. The item is
then converted according to the rules given for FIXED DECIMAL or FLOAT
DECIMAL to BIT.

Section F: Data Conversion and Expression Evaluation 347

Source: Target: BIT
(continued)

CHARACTER

Character 0 becomes bit 0 and character 1 becomes bit 1. Any

character other than 0 or 1 will raise the CONVERSION condition, if
enabled. A null string becomes a null bit string. The generated bit
string, which has the same length as the source character-string, is
assigned to the target according to the rules given for BIT to BIT.

BIT

The source string is assigned to the target string from left to right.
If the source string is longer than the target, excess bits on the
right are ignored, and the STRINGSIZE condition will be raised, if
enabled. If the target is longer than the source, the target is
padded on the right with zeros.

348 OS PL/I CKT AND OPT LRM PART II

Tables for Arithmetic Operations
Second Operand
Code
Coded arithmetic Numeric character
(PICTURE)
FIXED FLOAT
CHARACTER (n::!) BIT (n2) 1 FIX
DECIMAL BINARY DECIMAL BINARY Fixed- Floating-
These tables indicate the attributes of the result when a two-operand arithmetic expression is evaluated, together with any (P2,Q2 ) (P2,Q2) (P2) (P2 ) point point
2 FIX
conversions to tempor;Jry attributes which take place during evaluation. To find the attributes of the result and to determine
DECIMAL
what intermediate conversions, if any, take place, proceed as follows: 1 5(b) 3(c) 6(d) W Y W x 3 FL(
(PI,QI)
1. Refer to figure F.4a_ Find the entry that corresponds to the operands in the expression to be evaluated. The entry FIXED FL(
BINARY 4
consists of either a number, or one or two letters, or a number followed by one or two letters in brackets_ The numbers 7(x) 2 8(d,z) 4(d) W Y W x
(PI,ql)
are used to determine the attributes of the result and the letters to determine the intermediate conversions. Where there Coded
arithmetic DECIMAL 5 FIX
are no letters, no intermediate conversions take place; where there are letters and numbers, the reader has the choice of 3(y) 6(d,z)
(PI) 3 6(d) W y W x
either determining the attributes of the result without reference to the intermediate conversions, or of working through FLOAT
each intermediate conversion. First BINARY FL(
8(z) 4(z) 8(z) 4 W y W x 6
Operand (PI)
2. a. If the entry in figure F.4a consists of a number only, refer to Figure F.4c or F.4d, whichever is appropriate to the
operation being performed, and read off the attributes against the number that was found in figure F .4a. These are Numeric Fixed-point a a a a a,w a,y a,w a,x
character 7 FIX
the attributes of the result.
(PICTURE) Floating-point c c c c c,W c,y c,W C,x
b. If the entry in figure F.4a consists of a letter or letters only, the reader must determine the attributes of each inter-
mediate operand before he can determine the attributes of the result. This is done by looking up the corresponding CHARACTER (nl) a a a a a,w a,y a,w a,x 8 FLC

entry in figure F.4b, then looking up the source to target rules indicated there; the source to target rules will give the BIT (nl) b b b b b,w b,y b,w b,x
intermediate attributes. Steps 1 and 2 are then repeated using the intermediate attributes_ Where an entry in figure Figure F .4c.
To determine whether mode of result is REAL or COMPLEX:
F.4a consists of two letters separated by a comma the first refers to the intermediate attributes of the first operand, If both operands are REAL, there is no conversion of mode and the result is REAL.
and the second to those of the second operand. If both operands are COMPLEX, there is no conversion of mode and the result is COMPLEX.
c. If the entry in figure F.4a consists of a number followed by a letter or letters in brackets, either use the number to If one operand is REAL and the other is COMPLEX, the REAL operand is converted to COMPLEX and the result is COMPLEX, with two exceptional
find the attributes of the result directly, according to the instructions in Step 2 (a) or follow through the intermediate cases. The exceptions are exponentiations in which the second operand (the exponent) is either a FIXED (p,O) variable or a fixed-point decimal
integer constant: in these cases, no conversion of mode takes place prior to evaluation but the result is COMPLEX, Code
conversions, according to the instructions in Step 2 (b). The latter method is likely to be of greatest value when debugging,
the former when writing the program_ Figure F .4a. Master Table for arithmetic operations 1 3 FLC
Note: The letters referring to intermediate operands do not apply when an exponentiation operation is to be [unl
p =
performed; this table cannot be used to determine intermediate operands for exponentiation operations. I

2 4 FLC
Maximum Precisions of Arithmetic Data [unl
p = I
Figures F .4c and F.4d give formulas for the calculation of precisions_ The actual precision values can never exceed the
implemented maximums, which are: 5 6 FLC
[unl
31 for FIXED BINARY
p= I
15 for FIXED DECIMAL
53 for FLOAT BINARY 7 8 FLC
[unl
16 for FLOAT DECIMAL
p= I
First Operand Second Operand
Target
Code Code
Note: There ar
a w FIXED DECIMAL
b x FIXED BINARY
Real mode:
c y FLOAT DECIMAL If x = 0 and y
d z FLOAT BINARY If x = 0 and y
Ifx<Oandy
Figure F .4b. Key to conversions condition is ra

Figure F .4d.
 Second Operand Precision of the result
Code Attributes of result
Coded arithmetic Numeric character ADDITION or SUBTRACTION MU L TIPLICATION DIVISION
(PICTURE)
FIXED FLOAT p=15
CHARACTER (n:!) BIT (n2) 1 FIXED DECIMAL (p,ql
DECIMAL BINARY DECIMAL Fixed- p=1+MAX(PI-QI ,Pz- q2 1+ q P=PI + P~ + 1 q=15 - ((PI -qll +q~)
BINARY Floating-
· with any (P2,Q2) (P2,Q2) (P2) (P2 I point point q=MAX (ql,qzl q=ql + q~ p=31
2 FIXED BINARY (p,ql
to determine q=31 - ((p I - q I I + q~ I
DECIMAL
1 5(bl 3(c) 6(d) w Y w x 3 FLOAT DECIMAL (pI
(PI,ql)
mtry FIXED FLOAT BINARY (pI
p=MAX (PI, p:!)
BINARY 4
e numbers 7(x) 2 8(d,z) 4(d) w Y W x
(PI,qI)
Ihere there Coded p=1 + MAX (r - s, P2 - q2) + q p=l + r + P2 p=31
arithmetic DECIMAL 5 FIXED BINARY (p,q) q= MAX (s, q2 ) q=s + q2 p=31 - ((r - s) + q2 I
~ choice of
(ptl 3(y) 6(d,z) 3 6(d) W y W x
19 through FLOAT where r·o 1 + PI * 3.32, s = ql *3.32
First BINARY 6 FLOAT BINARY (p) p=MAX (PI *3.32, pz I
8(zl 4(z) a(z) 4 W y w x
Operand (PII
! to the
p=l + MAX (PI - ql, r - s) + q p=l + PI + r p=31
·hese are Numeric Fixed-point a a a a a,w a,Y a,w a,x q=MAX (q I, s) q=ql + S p=31-((PI -q\l+s
character 7 FIXED BINARY (p, q)
(PICTURE) Floating-point c c c c c,W c,Y c,W c,X where r = 1 + P2 * 3·32 and s=q2 * 3·32
~ch inter-
sponding CHARACTER (n I) a a a a a,w a,Y a,w a,x 8 FLOAT BINARY (p) p=MAX (PI, P:! *3.32)

,ill give the BIT (nl) b b b b b,w b,Y b,w b,x

Figure FAc. Result table for ADDITION, SUBTRACTION, MULTIPLICATION, and DIVISION
in figure
To determine whether mode of result is REAL or COMPLEX:
operand, If both operands are REAL, there is no conversion of mode and the result is REAL.
If both operands are COMPLEX, there is no conversion of mode and the result is COMPLEX.
Imber to If one operand is REAL and the other is COMPLEX, the REAL operand is converted to COMPLEX and the result is COMPLEX, with two exceptional
ntermediate cases. The exceptions are exponentiations in which the second operand (the exponent) is either a FIXED (p,OI variable or a fixed-point decimal
integer constant: in these cases, no conversion of mode takes place prior to evaluation but the result is COMPLEX. Code Attributes of result Special cases (see also Note below)
when debugging,
1 3 FLOAT DECIMAL (pI Case First Operand
Figure FAa. Master Table for arithmetic operations Second Operand Attributes of result
[unless special case A or C appliesl
A FIXED DECIMAL Unsigned integer FIXED DECIMAL (p, ql
p = MAX (PI, P2 I
(PI, q}) constant with value n [provided p < - 15]
2 4 FLOAT BINA~Y (pI p = (PI + 1 \ *n - 1
(unless special case B or C applies] q = ql *n
p = MAX (PI, q21
~d the
B FIXED BINARY Unsigned Integer FIXED BINARY (p, q)
5 6 FLOAT BINARY (pI
(PI, QI) constant with value n (provided p <, 31)
(unless special case A or C applies)
p = MAX (PI *3·32, P2) P = (PI + 1 I *n . 1
q = PI *n
7 a FLOAT BINARY (pI
[unless special case Bar C applies) C FLOAT FIXED FLOAT (pd
p = MAX (PI, (P2 *3·321) (pd (P2,0) with base of first operand
First Operand Second Operand
Target
Code Code
Note: There are further special cases of x ** y, as follOWS:
a w FIXED DECIMAL
b x FIXED BINARY Real mode: Complex mode:
c y FLOAT DECIMAL If x = 0 and Y >0, result is 0 If x = 0, and real part of y >0 and
d z FLOAT BINARY If x = 0 and Y < = 0, ERROR condition is raised imaginary part of y = 0, result is 0
If x <0 and Y not FIXED (p, 01, ERROR <
If x = 0 and real part of y = 0 or
Figure F Ab. Key to conversions condition is raised imaginary part of y~ = 0, ERROR condition
is raised
If x..., = 0 and real and imaginary parts of
y = 0, result is 1

Figure F Ad. Result table for EXPONENTIATION

Section F: Data Conversion and Expression Evaluation 349

Tables for Comparison Operations Second operand Type 0'
Code
These tables show the attributes to which the two operands of a comparison operation are converted before they are compared. compar
Coded arithmetic Numeric
They also show the type of comparison that is made. character Algebra
FIXED FLOAT (PICTURE)
Refer first to figure F .5a. Find the entry in this table that corresponds to the two operands in the expression to be evaluated; CHARACTER (n2) BIT (n2) 2 Charact
the entry will consist of two numbers separated by a comma. The numbers refer to the entries in figure F .5b; these indicate DECIMAL BINARY DECIMAL BINARY Fixed· Floating·
(P2,Ql) (P2,Ql) (P2) (Pl) point point 3 Bit
the attributes to which each operand is converted. The first number gives the attributes to which the first operand is converted,
and the second number those for the second operand. For example, consider the following comparison, with variables being DECIMAL 4 Algebra
1,1 4,1 5,1 8,1 1,10 5,11 1,12 4,13
declared as shown. (PI,qtl
FIXED
BINARY 5 Algebra
1,4 1,1 7,6 7,1 1,4 7,6 1,13 1,13
DECLARE ITEM CHARACTER (5), (PI,qtl
Coded
STANDARD FIXED BINARY (15,0); arithmetic DECIMAL 6 Algebra
1,5 6,7 1,1 6,1 1,5 1,11 1,14 6,9
(PI)
FLOAT
First BINARY 7 ~Igebra
operand 1,8 1,7 1,6 1,1 1,8 1,6 1,15 1,9
(Ptl
IF ITEM-,=STANDARD THEN DO;
Numeric Fixed·point 10,1 4,1 5,1 8,1 *10,10 5,11 10,12 4,13 B Algebra
character
In figure F.5a, the entry corresponding with a first operand having the CHARACTER attribute and a second operand having (PICTURE) Floating-point 11,5 6,7 11,1 6,1 11,5 ·11,11 11,14 6,9
the attributes FIXED BINARY is the two numbers 13, 1. Entry 13 in figure F.5b shows attributes FIXED BINARY (31,0), 9 ~Igebra
CHARACTER (n 1 ) 12,1 13,1 14,1 15,1 12,10 14,11 2,2 2,2
which indicates that ITEM is converted to coded arithmetic form with these attributes. Entry 1 in Figure F .5b is "No conver· 10 Algebra
sian", indicating that STANDARD is not converted. Both entries show that the comparison will be algebraic. (The two BIT (n.) 13,4 13,1 9,6 9,1 13,4 9,6 9,2 3,3
11 Algebrc
entries in figure F .5b will always show the same type of comparison). The tables indicate, then, that ITEM will be converted
If one operand is COMPLEX and the other is REAL, the REAL operand is converted to COMPLEX before the comparison is made. 12 Algebrc
to FIXED BINARY (31,0) and will then be compared algebraically with STANDARD whose attributes remain FIXED
BINARY (15,0). 13 Algebrc
it For the optimizing compiler only, if both operands are numeric character form and have identical PICTURE specifications, the
type of comparison is character and no conversion of operands takes place. 14 Algebr;
Maximum Precisions for Arithmetic Data
15 Algebrc
Figure F .5b gives formulas for the calculation of precisions. The actual precision values can never exceed the implemented
16 Algebrc
maximums, which are: Figure F .5a. Master table for comparison operations
31 for FIXED BINARY
15 for FIXED DECIMAL
53 for FLOAT BINARY
16for FLOAT DECIMAL

Note 1: If the

Figure F .5b.
 Second operand Type of
Code Attributes of comparison target
, are compared, comparison
Coded arithmetic Numeric
character 1 Algebraic No conversion
FIXED FLOAT (PICTURE)
o be evaluated; CHARACTER (n2) BIT (n2) 2 Character CHARACTER (MAX (nt, n2)) where (n1) and (n2) are the lengths of the first and second operands, respectively,
~se indicate DECIMAL BINARY DECIMAL BINARY Fixed- Floating-
(P2,q2) (P2,Q2) (P2) (P2) point point 3 Bit BIT (MAX (nl, n2)) where (nl) and (n2) are the lengths of the first and second operands, respectively
Id is converted,
DECIMAL 4 Algebraic FIXED BINARY (l+p"3'32, q*3'32) where (p,q) is precision of operand being converted (If operand is in numeric
iables being 1,1 4,1 5,1 8,1 1,10 5,11 1,12 4,13
(Pl,q.! character (PICTURE) form, see Note 1)
FIXED
BINARY 5 Algebraic FLOAT DECIMAL (p) where (p,q) is precision of operand being converted /If operand is in numeric character (PICTURE)
1,4 1,1 7,6 7,1 1,4 7,6 1,13 1,13
(Pt,ql) form, see Note 1 )
Coded
arithmetic DECIMAL 6 Algebraic FLOAT BINARY (p*3'32) where (p) is precision of operand being converted (If operand is in numeric character
1,5 6,7 1,1 6,1 1,5 1,11 1,14 6,9 (PICTURE) form, see Note 1)
(pd
FLOAT
First BINARY 7 ~Igebraic FLOAT BINARY (p) where (p, q) is precision of operand being converted (If operand is in numeric character (PICTURE)
operand 1,8 1,7 1,6 1,1 1,8 1,6 1,15 1,9
(p(l form, see Note 1)

Numeric Fixed-point 10,1 4,1 5,1 8,1 *10,10 5,11 10,12 4,13 8 Algebraic FLOAT BINARY (p*3'32) where (p, q) is precision of operand being converted (If operand is in numeric character
character (PICTURE) form, see Note 1)
~rand having (PICTURE) Floating-point 11,5 6,7 11,1 6,1 11,5 *11,11 11,14 6,9
9 !4lgebraic FLOAT BINARY (31)
.RY (31,0),
CHARACTER (n t ) 12,1 13,1 14,1 15,1 12,10 14,11 2,2 2,2
"No conver- 10 Algebraic FIXED DECIMAL (Precision same as implied by PICTURE specification of operand being converted)

1e two BIT (n.! 13,4 13,1 9,6 9,1 13,4 9,6 9,2 3,3 FLOAT DECIMAL (Precision same as implied by PICTURE specification of operand being converted)
11 Algebraic
Ie converted
If one operand is COMPLEX and the other is REAL, the REAL operand is converted to COMPLEX before the comparison is made, 12 Algebraic FIXED DECIMAL (15,0)
:IXED
13 Algebraic FIXED BINARY (31,0)
.. For the optimizing compiler only, if both operands are numeric character form and have identical PICTUR E specifications, the
type of comparison is character and no conversion of operands takes place, 14 Algebraic FLOAT DECIMAL (15)

15 !Algebraic FLOAT BINARY (50)

Ilemented FLOAT DECIMAL (10)
16 Algebraic
Figure F ,5a, Master table for comparison operations

Note 7: If the operand being converted is in numeric character form, its precision is that which is implied by the PICTURE specification,

Figure F ,5b. Types of comparsion operation and targets

Section F: Data Conversion and Expression Evaluation 351

 Section G: Built-in Functions and Pseudovariables

All of the built-in functions that are String-handling Built-in Functions

available to the programmer are given in
this section and are presented in
alphabetical order. Any built-in fUnction These functions simplify the processing of
that can also be used as a pseudovariable bit and character strings. They are:
has a subentry describing the action of the
pseudovariable. BIT REPEAT
BOOL STRING
The general form of a built-in function CHAR SUBSTR
reference is as follows: HIGH TRANSLATE
INDEX UNSPEC
LENGTH VERIFY
LOW
where x or x~,X2 ••• ,xn represent the
arguments required. For some functions one
or more arguments are optional. For
example:
Arithmetic Built-In Functions

Each function in the alphabetical list These functions allow the programmer to
is identified by the general form of the control conversion of base, scale, mode,
function reference (the pseudovariable and precision both directly and during
reference is always identical to the basic arithmetic operations. Other
equivalent function reference). In functions in this class are used to
general, each function description has the investigate simple properties of arithmetic
following items: values, for example, the SIGN function
indicates the sign of an arithmetic value.
1. A description of the value returned. They are:

2. Details of the arguments. ABS I MAG

ADD MAX
3. Any other qualifications on the use of BINARY MIN
the function. CEIL MOD
COMPLEX MULTIPLY
4. When applicable, a description of the CONJG PRECISION
action of the equivalent DECIMAL REAL
pseudovariable. DIVIDE ROUND
FIXED SIGN
FLOAT TRUNC
FLOOR

CLASSIFICATION OF BUILT-IN FUNCTIONS

The built-in functions can be classified Mathematical Built-In Functions

according to the PL/I features they are
intended to serve. These classes are:
These functions provide standard
string-handling mathematical operations. They are:
Arithmetic
Mathematical ACOS' LOG
Array-handling ASIN LOG 2
Condition-handling ATAN LOG10
storage Control ATAND SIN
Multitasking ATANH SIND
Input/Output COS SINH
Preprocessor COSO SQRT
Miscellaneous COSH TAN
ERF TAND
The first four classes are all ERFC TANH
computational built-in functions. EXP

Section G: Built-in Functions and Pseudovariables 353

Array-Handling Built-In FUnctions 1Input/Output Built-In Functions

These functions all operate on array These functions allow the programmer to
arguments and return a single value investigate the current state of a file.
property of an array. They are: They are:

ALL LBOUND COUNT

ANY POLY LINENO
DIM PROD SAME KEY
HBOUND SUM

IPreprocessor Built-In Functions

I
I
Condition-handling Built-In FUnctions These functions are the only built-in
functions that can be executed by the
preprocessor. They are:
These functions allow the programmer to
investigate interrupts that arise from COMPILETIME
enabled conditions. Each of the functions COUNTER
returns a value that is defined only within INDEX
the scope of an on-unit that can be entered L.ENGTH
for the condition specific to the built-in PARMSET
function or within the scope of an on-unit SUBSTR
for the ERROR or FINISH condition when
raised as standard system action. They The SUBSTR, LENGTH, and INDEX built-in
are: functions are the same as the non-
preprocessor built-in functions of the same
DATAFIELD ONFILE names. The COUNTER, COMPILETIME, and
ONCHAR ONKEY PARMSET built-in functions can be executed
ONCODE ONLOC only by the preprocessor.
ONCOUNT ONSOURCE
In preprocessor statements, the
preprocessor built-in function names are
always active as built-in functions unless
they have been declared to have some other
storage Control Built-In Functions meaning. In non-preprocessor statements,
the preprocessor built-in function names
are recognized as built-in functions only
These functions allow the programmer to if they are active when they are
determine the storage requirements and encountered and have not been declared with
location of variables, to assign special an attribute other than BUILTIN.
implementation-defined values to area and
locator variables, to perform conversion
between offset and pointer values, and to
obtain the number of generations of a IMiscellaneous Built-in Functions
controlled variable. They are: I
I
ADDR NULL IThe built-in functions which do not fit
ALLOCATION OFFSET linto any of the foregoing classes are:
EMPTY POINTER I
CURRENTSTORAGE STORAGE I DATE
I PLIRETV
I TIME
I
Multitasking Built-In Functions

CONVERSION OF ARGUMENTS
These functions allow the programmer to
investigate the current state of an event
variable. They are: Conversion of arguments can occur for many
of the built-in functions. Arguments to
COMPLETION these built-in functions can be operational
PRIORITY expressions. An expression argument, which
STATUS can include references to built-in

3511 OS PL/I CKT AND OPT LRM PART II

functions, is evaluated and converted, Array-handling Built-In Functions
according to the rules for data conversion,
to a form suitable for the built-in
function. The data type required by each Any conversion of arguments required for
argument is given in each function these functions is noted in the function
description. description.

ACCURACY OF THE MATHEMATICAL FUNCTIONS

string-handling Built-In Functions

The accuracy of a result is influenced by
two factors:
Some of these functions require arithmetic
as well as string arguments. The 1. The accuracy of the argument.
arithmetic arguments denote the length of a
string and therefore should be integer or 2. The performance of the algorithm.
capable of being converted to integer. The
string arguments can be represented by an Most arguments contain errors. An error in
arithmetic expression that will be a given argument may have accumulated over
converted to string either according to several steps prior to the evaluation of a
data conversion rules or according to the function. Even data fresh from input
rules given in the function description. conversion may contain slight errors. The
The programmer should ensure that the effect of argument error on the accuracy of
conversion will cause the function to a result depends solely on the nature of
operate on the string type he requires. the mathematical function and not on the
algorithm that computes the result. Errors
of this type are not discussed furt.her in
this publication.

Performance statistics for each

Arithmetic Built-In Functions mathematical function are given in figures
G.l and G.2. The values are based on the
assumption that the arguments are free from
Some of these functions derive the data error.
type of their results from one or more
arguments. When the data types of the For each function, accuracy values are
arguments differ, they are converted given for the valid argument range or
according to the following scheme: i f representative segments of it. In each
scales differ, fixed-point is converted to case the particular statistics given are
floating-point; if bases differ, decimal is the most meaningful to the function and
converted to binary; and if modes differ, range under consideration.
real is converted to complex. These rules
are applied after any string-type arguments For example, the root-mean-square(RMS)
have been connected to arithmetic. When a of the relative error and the maximum
data attribute of the result cannot agree relative error of a set of results-are
with that of the argument, for example, the generally useful and revealing statistics,
FLOOR built-in function, the rules are but are useless for the range of a function
given in the function description. where its value becomes zero: the slightest
error of the argument value can cause an
The symbol N is used to represent the unbounded fluctuation in the relative
maximum precision allowed for fixed-point magnitude of the result. Such is the case
results. The value of N is defined as: with SIN(x) for values of 'x' close to pi:
in this range it is more appropriate to
15 for FIXED DECIMAL discuss absolute errors.
31 for FIXED BINARY
The values for short and long precision
floating-point arguments are given in
figure G.l. They are derived from random
distribution of 5000 arguments per range,
Mathematical Built-In Functions generated to be either uniform or
exponential, as appropriate. The values
for extended preCision floating-point
All of these functions operate on floating- arguments are given in figure G.2. They
point values to produce a floating-point are derived from 2000 randomly-distributed
result and therefore, if any argument is arguments, generated to have one of the
not floating-point, i t will be converted. four types of distribution noted at the

Section G: Built-in Functions and pseudovariables 355

foot of each part of the figure. NULL ARGUMENTS

Note that, in both figures, each value

quoted for the maximum error refers to a INon-Preprocessor Built-in Functions
particular sample and should be regarded
only as a guide to the true maximum error.
IA number of non-preprocessor built-in
Maximum and RMS values are given for functions do not require arguments. It
short, long, and extended floating-point should be noted that the functions must
results. either be explicitly declared with the
BUILTIN attribute or contextually declared
Maximum and RMS values for the relative by including a null argument list in the
or (where necessary) the absolute errors function reference, for example, ONCHAR().
are given for each function range. These Otherwise, the name cannot be recognized by
are defined as follows: the compiler as a built-in function name.

Let f(x) = the true value for the I The functions tnat have nO arguments or
function Ihave a Single optional argument are:

g(x) = the calculated value for the DATAFIELD ONKEY

function DATE ONLOC
EMPTY ONSOURCE
Then the absolute error of the result is NULL PLIRETV
ONCHAR PRIORITY
ABS(f(x)-g(x» ONCODE STATUS
ONCOUNT TIME
and the relative error of the result ONFILE
is
ABS«f(x)-g(x»/(f»
IPreprocessor Built-in Functions
Let the number of sample results obtained I
be n; then the RMS of the absolute error I
is: IThe preprocessor built-in functions which
Ido not require arguments are COUNTER and
SQRT(~«f(X )-g(x »**2)/n) ICOMPlLETlME. These built-in functions
Ishould not be given a null argument list;
and the RMS of the relative error is lall preprocessor built-in functions shoUld
Ibe declared if they are to be active in
SQRT(2:«(f(X )-g(x »/f(x »**2)/n) Inon-preprocessor statements.

PSEUDOVARIABLES

Certain built-in functions can be used to

AGGREGATE ARGUMENTS represent receiving fields. In this form
they are pseudovariabl~s. Except when
noted in the description of the
The only functions that can accept pseudovariable, it can appear on the left
structure arguments are ADDR, ALLOCATION, of the equal sign in an assignment or DO
and STRING. statement; it can appear in a data list of
a GET statement; and it can appear as the
All built-in functions that can have string name in a KEYTO, STRING, or REPLY
arguments can have array arguments. But option.
whereas ADDR, ALLOCATION, STRING, and the
array-handling functions return single Since all pseudovariables are also
values, all other functions return an array built-in functions, only a short
of values. Thus for functions such as description is given in the relevant
SUBSTR, anyone of the arguments can be an function description.
array (if more than one is an array, the
bounds must be identical). This facility Note that pseudovariables cannot be
is equivalent to placing the function nested; for example, the following
reference in a do-loop where one or more statement is invalid:
arguments is a subscripted array reference
that is modified by the control variable. UNSPEC(SUBSTR(A,1,2» = 'OO'B;

356 OS PL/I CKT AND OPT LRM PART II

The pseudovariables are:

COMPLETION REAL
COMPLEX STATUS
IMAG STRING
ONCHAR SUBSTR
ONSOURCE UNSPEC
PRIORITY

Section G: Built-in Functions and Pseudovariables 351

r---------------------------------------------------------------------------------------,
" , Short Floating Point, Long Floating Point ,
Function
' I
,Argument, Range
1-------------------------------------------
I Relative Error I Relative Error
Name I Mode I I *10**8 I *10**17
'
1
I1 1-------------------------------------------
1 RMS I MAX I RMS I Max
ACOS(x) real 1 ABS{x)~0.5 1 43 , 88 1 7.2 I 20
1---------------------------------------------------------------
I O.5<ABS{x)~1 I 16 1 89 1 6.6 I 21
---------------------------------------------------------------------------------------
ASIN{x) I real I ABS(x)~0.5 1 10 1 54 I 4.4 I 21
I
1
1---------------------------------------------------------------
1 O.5<ABS(x)~1 1 26 I 94 1 5.9 1 21
ATAN{x) I real I ABS(x)<l 13 90 4.1 21
I
1
1---------------------------------------------------------------
I full range 1 225 1 99 I 5.2 I 17
1-------------------------------------------------------------------------
1 complex 1 full range I 221 , 110 1 5.2 , 44
---------------------------------------------------------------------------------------
ATAN{X1,X2) 1 real 1 ABS{X1)~1, 1
1 1 ABS(x2)~12 29 160 1 6.9 36
ATAND(x) I similar to real ATANH(x)
ATANH(x) real I ABS(x)~0.2 I 46 1 110 1 I
I-------------~-------------------------------------------------
I ABS(x)<0.9 ,39 1 120 1 ,
1---------------------------------------------------------------
1 I
ABS{x)~0.25 I 1 5.8 1 21
11 1---------------------------------------------------------------
1 ,
ABS(x)~0.95 1 1 9.0 1 25
1-------------------------------------------------------------------------
I complex 1 full range 1 2 22 1 120 1 5.6 1 41
COS (x) real 1 I O~x~pi 1 4.7 1 12 I 7.3 1 27
1---------------------------------------------------------------
1 1 4.0
-10~x<0,pi<x~10 1 12 1 6.9 1 27

1
1---------------------------------------------------------------
I 10<ABS{x)~100
1 4.0 1 12 1 100 1 270
1-------------------------------------------------------------------------
1 complex 1 3 120
ABS(a)~10,ABS(b)~11 1 320 1 31 1 380
cOSD(x) 1 similar to real COS (x)

cOSH(x) real 1 ABS(x)~l I 41 1 96 1 1

1---------------------------------------------------------------
1 1<ABS(x)<2 1 21 1 72 1 1
1---------------------------------------------------------------
1 ABS(x)~170 1 20 1 82 1 1
1---------------------------------------------------------------1
1 ABS(x)~17 1 1 1 11 1 39 1
1--------------------------------------------------------~------I
1 ABS{x)~5 1 1 1 11 1 38 1
-------------------------------------------------------------------------1
complex 3 , 97
ABS(a)~10,ABS(b)~1', 310 1 25 , 73 1
---------------------------------------------------------------------------------------1
1 RMS and Max values given are absolute errors. I
2 All these ranges are distributed exponentially; all other distributions are uniform. I
3 Where (a+i*b) represents x. ,
l---------------------------------------------------------------------------------------J
Figure G.1 (Part 1 of 3). Performance of the mathematical built-in functions with
short and long preCision floating-pOint arguments

358 OS PL/I CKT AND OPT LRM PART II

r---------------------------------------------------------------------------------------,
I 1 I Short Floating Point 1 Long Floating Point
Function
1 1
1 Argument 1 Range
j-------------------------.-----------------
1 Relative Error 1 Relati ve Error
Name 1 Mode 1 1 *10**8 I *10**17
11 11 1-------------------------------------------
1 RMS 1 MAX 1 RMS 1 Max
---------------------------------------------------------------------------------------
ERF(x) I real I ABS(x>~1 1 11 1 85 1 2.6 1 19
1I 1---------------------------------------------------------------
1 1<ABS(x)<2.04 1 3.1 1 11 1 0.95 1 2.9
11 1---------------------------------------------------------------
I 2.04<AaS(x><3.91921 3.5 1 6.0 1 - 1 -
11 1---------------------------------------------------------------
I 2.04<ABS(x><6.092 1 1 1 0.80 1 1.4
ERFC (x) real -3 •.8<x<O 30 94 1
---------------------------------------------------------------
-6<x<0 1 1 6.5 21
---------------------------------------------------------------
OSxS1 13 1 69 2.7 15
---------------------------------------------------------------
1<xS2.04 37 1 200 1 9.1 43
---------------------------------------------------------------
2.04<x<4 31 130 I 8.7 33
4Sx<13.3 820 1500 200 350
EXP(x) real 1 -1<x<1 13 44 5.4 21
fu11 range 1 12 46 4.7 43
--------- ---------------------------------------------------------------
complex ABS(a)~170 1 1
AB5(b)~pi/2 I 65 I 240
---------------------------------------------------------------
ABS(a)S170. I I
pi/2<ABS(b)S20 ·63 1 230 1
---------------------------------------------------------------
ABS(a)<l 1 I I
ABS(b)<pi/2 I 1 I 19 62
------------------------------------------------------ ---------
ABS(a)<20 1 1
ABS(b)<20 I I 20 82
-------------------------------------~---------------- ---------------------------------
LOG (x) real I excluding 1 I I 1
IO.S<X<2.0 2 I 12 1 84 I 5.5 I 34
1I 1---------------------------------------------------------------
I 0.5<x<2.01 I 2.5 1 6.8 I 2.4 I 4.7
1-------------------------------------------------------------------------
1 complex I fu11 range I 238 I 190 I 13 I 53
---------------------------------------------------------------------------------------
LOG 2 (x) real 1 excluding 1
I 0.5<x<2.02 I 34 1 98 I 8.8 I 43
I
1---------------------------------------------------------------
1 O.5<x<2.0 1 1 23 1 48 I 2.9 I 5.8
1---------------------------------------------------------------------------------------
I LOGl0(x) 1 real I excluding 1 1 I 1
1 1 IO.S<x<2.0 a I 22 I 110 1 6.6 1 32
I
1
11 1---------------------------------------------------------------
1 O. S<x<2 • 0 1 I 2. 3 1 7. 2 I 1. 2 I 2. 9
1---------------------------------------------------------------------------------------
1 1 RMS and Max values given are absolute errors.
1 a A11 these ranges are distributed exponentially; all other distributions are uniform.
I 3 Where (a+i*b) represents x.
L--------------------------------------------------------------------_------------------J
Figure G.l (part 2 of 3). Performance of the mathematical built-in functions with
short and long precision floating-point arg~ments

Section G: Built-in Functions and Pseudovariables 359

r---------------------------------------------------------------------------------------,
I 1 1 Short Floating Point 1 Long Floating Point 1
Function
1 I
1 Argument 1 Range
1-------------------------------------------1
I Relati ve Error 1 Relati ve Error I
Name 1 Mode 1 1 *10**8 1 *10**17 I
1I 1I 1-------------------------------------------1
I RMS 1 MAX 1 RMS I Max I
---------------------------------------------------------------------------------------1
SIN(x) I rea1 1 1 ABS(x)Spi/2 1 4.8 I 12 I 1.8 1 7.7 1
I
I
1---------------------------------------------------------------1
1 pi/2<ABS(x)S10 I 4.6 1 13 I 32 I 240 I
1
1
1---------------------------------------------------------------1
1 10<ABS(x)S100 I 4.6 1 12 I 93 I 270 1
1-------------------------------------------------------------------------1
3
1 complex 1 ABS(a)S10,ABS(b)S11 120 1 340 1 200 I 11000 1
---------------------------------------------------------------------------------------1
SIND (x) 1 similar to real SIN(x) I
-------------
SINH (x)
---------
real
---------------------------------------------------------------1
ABS(x)Sl 1 20 1 88 1 I I
---------------------------------------------------------------1
1<ABS (x)<2 I 25 1 100 1 1 1
---------------------------------------------------------------1
ABS(x)S110 I 20 1 82 1 1 I
---------------------------------------------------------------1
ABS (x) S11 1 I 1 10 1 36 1
---------------------------------------------------------------
ABS(x)<0.881314 I 1 3.1 20
---------------------------------------------------------------
0.881314<ABS(x)S5 I 1 10 35

complex 1 ABS(a)S10,ABS(b)S11 88 210 23 64

SQRT(x) 1 real 1 full range 2 f 13 1 48 1 3.1 1 11

1-------------------------------------------------------------------------
1 complex 1 full range 1 254 1 220 1 13 1 49
------------- -------------------------------------------------------------------------
TAN(x) 4
rea1 1 ABS(X)Spi/4 1 29 1 160 1 6.2 1 39
1---------------------------------------------------------------
t pi/4<ABS(x)<pi/2 I 37 I 150 1 1
1---------------------------------------------------------------
1 pi/4<ABS(x)<1.5 1 I 1 41 1 230
1---------------------------------------------------------------
1 pi/2<ABS(x)S10 1 32 1 480 I - 1 -
1---------------------------------------------------------------
1 1.5<ABS(x)S10 1 I 1 1800 1 41000
1---------------------------------------------------------------
I 10<ABS(x)S100 I 31 1 140 1 1800 1 27000
1-------------------------------------------------------------------------
1 complex 1 ABS(a)<1,ABS(b)<9 1
3 53 1 290 1 11 1 11
TAND(x) 1 similar to read TAN(x)
TANH (x) real 1 ABS(x)SO.7 1 15 1 18 1 1
1---------------------------------------------------------------
1 0.1<ABS(x)S9.011 1 3.9 I 2.3 I 1
1---------------------------------------------------------------
1 ABS(x)SO.54931 1 1 1 3.8 1 19
1---------------------------------------------------------------
I 0.54931<ABS(x) I 1 I 1
1 1 S20.101 1 I 1 1.0 1 16
1-------------------------------------------------------------------------
1 complex 1 ABS(a)<9,ABS(b)<1 1
3 52 1 270 1 17 1 69
14 Each figure here depends on the particular pOints encountered near the singularities
1 of the function, where no error control can be maintained.
L---------------------------------------------------------------------------------------J
Figure G.l (part 3 of 3). Performance of the mathematical built-in functions with
short and long precision floating-point arguments

360 OS PL/I CKT AND OPr LRM PART II

r---------------------------------------------------------------------------------------,
1 1 1 1 Relative Error *10**3lJ
Function
Name
I Argument 1
1 Mode 1
Range IDistribution 1-----------------------------
1 Type 1 1
1 I 1(see foot of 1 RMS I Max
1 1 1 table) 1 1
ACOS(x) 1 real 1 ABS(x)~l u 9.9 32
ASIN(x) 1 real 1 ABS(x)~l I U 8.1 32
---------------------------------------------------------------------------------------
ATAN(x) 1 real 1 ABS(x)<10**15 1 T 1 1.3 1 30
1------------------------·-------------------------------------------------
1 complex 2 1 full range 1 EU 1 12 1 110
---------------------------------------------------------------------------------------
ATAN(x~,x2) 1 real 1 full range EU 1 8.5 38
ATANH(x) 1 real 1 ABS(x)<0.25 1 U 1 8.6 1 28
11 1---------------------------------------------------------------
1 ABS (x) 0 • 95
~ 1 U 1 18 1 50
1-------------------------------------------------------------------------
1 complex 2 1 full range 1 EU 1 11 1 59
COS(x) real 1 O~x<pi~ 1 U 1 1.5 1 3.3
1---------------------------------------------------------------
1 -10<x<0,pi~x<10~1 U 1 1.6 1 3.5
1
1
1---------------------------------------------------------------
1 10~ABS(x)<200~ 1 U 1.6
1 3.5
1
1-------------------------------------------------------------------------
1 complex 2 1 ABS(a)<10 1 U 1 24 1 62
1 , ABS (b) <1 1 u, ,
---------------------------------------------------------------------------------------
COSH(x) 1 real 1 ABS(x)<10 1 U 1 15 1 61
1-------------------------------------------------------------------------
1 complex 2 1 ABS(a)<10 1 U 1 20 1 67
1 1 ABS (b) <1 1 u 1 1
---------------------------------------------------------------------------------------
ERF(x) real 1 ABS(x) <1 1 U I 5.3 1 30
1---------------------------------------------------------------
I 1~ABS(x)<2.8437 1 U 1 2.3 1 9.2
1---------------------------------------------------------------
I 2.8431~ABS(x)<5 1 U I 1.3 1 1.9
ERFC(x) real 1 -5<x<0 lUI 12 1 31
1---------------------------------------------------------------
I O~x<l 1 U 1 5.8 1 33
1---------------------------------------------------------------
1 1~x<2.8431 1 U I 28 1 11
1---------------------------------------------------------------
1 2.8431~x<5 1 U 1 180 1 490
~RMS and Max values are for absolute errors 2Where x=a+i*b
E exponential EU a+i*b=r*EXP(i*k) where x=a+i*b
U uniform (linear) or (ATAN only) x~=a, x2=b, and:
T tangents of linearly-scaled r has E distribution in (0,10**15)
angles in (-pi/2,pi/2) k has U distribution in (-pi, pi)
L---------------------------------------------------------------------------------------J
Figure G.2 (Part 1 of 3). Performance of the mathematical built-in functions with
extended-precision floating-point arguments

section G: Built-in Functions and pseudovariables 361

r---------------------------------------------------------------------------------------,
1 1 1 1 Relative Error *10**34
Function 1 Argument 1 Range IDistribution 1-----------------------------
Name 1 Mode 1 1 Type 1 1
1 I 1(see foot of I RMS 1 Max
1 1 1 table) 1 1
EXP(x) real 1 ABS(x)<l 1 U I 4.3 I 15
1---------------------------------------------------------------
1 ABS(x)<10 1 U 1 3.8 1 15
1---------------------------------------------------------------
1 -180<x<174 1 U I 3.7 1 15
-------------------------------------------------------------------------
complex21 ABS(a)<170 1 U 1 7.8 I 35
1 ABS(b)<pi/2 1 U 1 1
1---------------------------------------------------------------
1 ABS(a)<170 1 U 1 8.0 1 33
1 pi/2~ABS(b)<100 1 U 1 1
LOG(x) real 1 0.99<x<1.01~ 1 U 1 0.084 1 0.20
1---------------------------------------------------------------
1 0 • 5<x<2~ 1 u 1 1. 7 1 3. 2
1---------------------------------------------------------------
1 10**-78<x<10**75 1 E I 8.9 1 45
complex 2 1 full range EU 9. 8 1 51
---------------------------------------------------------------------------------------
LOG 2 (x) real I 0.99<x<1.01~ 1 U 1 0.055 1 0.13
1---------------------------------------------------------------
1 0.5<x<2~ 1 U 1 1.0 1 1.9
1---------------------------------------------------------------
1 10**-78<x<10**75 1 E 1 4.4 1 30
------------- -----------------------------------------------------------_._------------
LOG10(x) real 1 O.99<x<1.01~ 1 U 1 0.038 1 0.16
1---------------------------------------------------------------
1 0 • 5<x<2~ 1 U 1 1. 5 1 2. 9
1---------------------------------------------------------------
1 10**-78<x<10**75 1 E 1 12 1 38
SIN(x) real 1 ABS(x)<pi/2~ 1 U 1 1.2 1 3.0
1---------------------------------------------------------------
1 pi/2~ABS(x)<10~ 1 U 1 1.6 1 3.5
1---------------------------------------------------------------
1 10~S(x)<200~ 1 U 1 1.5 1 3.6
complex 2 1 ABS(a)<10 U 24 60
1 ABS(b)<l U

SINH (x) 1 real 1 ABS (x) <1 1 u 1 6.8 1 29

11 1---------------------------------------------------------------
1 1~BS(x)<10 1 U 1 13 1 54
1-------------------------------------------------------------------------
1 complex 1 ABS(a)<10
3 1 U 1 18 1 53
1 1 ABS (b) <1 1 u 1 1
~RMS and Max values are for absolute errors 2Where x=a+i*b

E exponential EU a+i*b=r*EXP(i*k) where x=a+i*b

U uniform (linear) or (ATAN only) x~=a, x2=b, and:
T tangents of linearly-scaled r has E distribution in (0,10**75)
angles in (-pi/2,pi/2) k has U distribution in (-pi, pi)
L---------------------------------------------------------------------------------------J
Figure G.2 (Part 2 of 3). Performance of the mathematical built-in functions with
extended-precision floating-point arguments

362 OS PL/I CKT AND OPT LRM PART II

r---------------------------------------------------------------------------------------,
1 1 1 I Relative Error *10**34
Function
Name
1 Argument 1
,Mode 1
Range 'Distribution 1-----------------------------
, Type, 1
1 1 ,(see foot of, RMS 1 Max
1 1 , table), 1
SQRT(x) 1 real 1 10**-50<x<10**50 E 3.0 15
1
1
1---------------------------------------------------------------
I 10**-78<x<10**15, E , 2.8 I 14
1-------------------------------------------------------------------------
I complex 2 , full range I EU I 1.1 1 21
---------------------------------------------------------------------------------------
TAN(x) r e a l , ABS(x)<pi/4 I U I 9.6 , 36
1---------------------------------------------------------------
I pi/4~ABS(x)<pi/2lUI 8.9 , 39
1---------------------------------------------------------------
1 pi/2~S(x)<10 I U I 12 I 52
11 1---------------------------------------------------------------
1 10SABS(x)<200 1 U I 11 1 46
1-------------------------------------------------------------------------
1 complex 2 1 ABS(a)<l 1 U , 15 1 61
1 1 ABS (b) <9 1 U 1 1
---------------------------------------------------------------------------------------
TANB(x) I real I ABS(x)<0.54931 lUI 5.0 1 25
11 1---------------------------------------------------------------
1 0.54931~BS(x)<5 I U I 2.6 1 21
1-------------------------------------------------------------------------
1 complex 2 1 ABS(a)<9 1 U I 15 1 53
1 1 ABS(b)<l 1 U I I
1RMS and Max values are for absolute errors 2Where x=a+i*b
E exponential EU a+i*b=r*EXP(i*k) where x=a+i*b
U uniform (linear) or (ATAN only) x1=a, x2=b, and:
T tangents of linearly-scaled r has E distribution in (0,10**15)
angles in (-pi/2,pi/2) k has U distribution in (-pi, pi)
L---------------------------------------------------------------------------------------J
Figure G.2 (Part 3 of 3). Performance of the mathematical built-in functions with
extended-precision floating-point arguments

section G: Built-in Functions and Pseudovariables 363

ABS(x) Arithmetic 1. A BASED, DEFINED, parameter,
subscripted, or structure-base-
element variable that is an
ABS returns the absolute value of a given unaligned fixed-length bit string.
expression x. If x is real, it is the
positive value of x; if x is complex, it is 2. A minor structure whose first base
the positive square root of the sum of the element is an unaligned fixed-
squares of the real and imaginary parts. length bit string (except where it
is also the first element of the
If x is fixed and complex with precision containing major structure).
(p,q), the precision of the result is given
by: 3. A major structure that has the
DEFINED attribute or is a
(MIN(N,p+l),q) parameter, and that has an
unaligned fixed-length bit string
where N is the maximum allowable number of as its first element.
digits.
4• A variable not in connected
storage.
ACOS(x) Mathematical If x is .an aggregate, the returned value
identifies the first element.
ACOS returns a floating-point value that If x is a varying string, the retarned
represents the inverse (arc) cosine in value identifies the two-byte prefix.
radians of a given value x.
If x is an area, the returned value
x must be real, and the absolute value identifies the control information.
mast be less than or equal to 1, i.e.,
ABS(x)<=l. The result is in the range: If x is a controlled variable that has not
been allocated, the null pointer value is
O<=ACOS(x)<=pi returned.
If x is a parameter and a dummy argument
has been created, the returned value
Arithmetic identifies the dummy argument.
Note that because of condition 4 above, if
ADD returns the sum of two values x~ and Xa x is a parameter, it must have the
with a precision specified by X3 and X~ • CONNECTED attribute.
X1 and Xa values to be added.
unsigned decimal integer constant Array-Handling
specifying the number of digits to be
maintained throughout the operation;
it must not exceed the implementation ALL returns a bit string in which each bit
limit. is 1 if the corresponding bit in each
element of the given array x exists and is
decimal integer constant, optionally 1 • The length of the result is equal to
signed, specifying the scale factor of that of the longest element.
the result. For a fixed-point result,
if ~is omitted, zero is assumed. For If x is not a bit-string array, it is
a floating-point result, X't must be converted to bit string. It must not be
omitted. iSUB-defined.

ADDR(x) storage Control ALLOCATION (x) Storage Control

ADDR returns a pointer value that identifes Abbreviation: ALLOCN

the location at which a given variable x
bas been allocated.
ALLOCATION returns a default-precision
x a variable of any data type and fixed-point binary integer specifying the
organization and of any storage class number of generations that can be accessed
except: in the current task for a given controlled

364 OS PL/I CKT AND OPT LRM PART II

variable x. -pi/2 for xa=O and X1<O

x the name of the controlled variable.

·The name must be level one and -pi+arctan(x1/xa) for xa<O and X1<O
unsubscripted.
If x is not allocated, the result is zero.
ATAND(XJ,[,Xa]) Mathematical

ANY (x) Array-Handling ATAND returns a floating-point value that

represents the inverse (arc) tangent in
degrees of a given value x 1 or of a given
ANY returns a bit string where each bit is ratio X1/Xa.
1 if the corresponding bit in any element
of the given array x exists and is 1. The If X1 alone is specified it must be
length of the result is equal to that of real. The result is in the range:
the longest element.
-90<ATAND(x1)<90
If x is not a bit-string array, it is
converted to bit string. It must not be If X1 and xa are specified, they must
iSUB-defined. both be real. The result is defined in
terms of the function ATAN as:
180/pi*ATAN(x1,xa)
ASIN(x) Mathematical

ASIN returns a floating-point value that ATANH(x) Mathematical

represents the inverse (arc) sine in
radians of a given value x.
ATANH returns a floating-point value that
x must be real, and the absolute value represents the inverse (arc) hyperbolic
must be less than or equal to 1, i.e., tangent of a given value x.
ABS(x)<=l. The result is in the range:
If x is real, its absolute value must be
-pi/2<=ASIN(x) <=pi/2 less than 1, i.e., ABS(x)<l.
If x is complex, it must not be +1 or -
1. The result is defined as:
ATAN(x, [,Xa]) Mathematical
LOG«1+x)/(1-x»/2
ATAN returns a floating-point value that
represents the inverse (arc) tangent in
radians of a given value X1 or of a given BINARY (x, [,Xa[,X3]]) Arithmetic
ra tio xs./xa.
If X1 alone is specified and is real, BINARY returns the binary representation of
the result is in the range: a given value X1 with a precision specified
by xa and X3.
-pi/2<ATANex1 ) <pi/2
X1 value to be converted to binary base.
If X1 alone is specified and is complex,
it must not be +i or -i. The result is Xa unsigned decimal integer specifying
given by: the number of digits to be maintained
throughout the operation; it must not
-i*ATANB(i*x1) exceed the implementation limit.
If X1 and xa are specified, they must decimal integer, optionally Signed,
both be real. It is an error if X1 and Xa specifying the scale factor of the
are both zero. The results for all other result. For a fixed-point result, if
values of X1 and xaare given by: xa is given and X3 is omitted, a scale
factor of zero is assumed. For a
arctan (X1/Xa) for xa>O floating-point result, only xa can be
given. If both Xa and X3 are omitted,
pi/2 for xa=O and X1>O the precision of the result is

Section G: Built-in Functions and Pseudovariables 365

 determined from the rules for base (MIN(N,MAX(p-q+1,1»,O)
conversion.

where N is the maximum number of digits

allowable.
BIT(x,- [,x a 1) String-handling

Bit returns a bit string representation of

a given value X1.

expression to be converted. String-handling

an expression that can be converted to
integer specifying the length of the
resulting bit string. If necessary,
X2 is converted to a binary integer of CHAR returns a character string
precision (15,0). If X2 is omitted, representation of a given value X1.
the length is determined by the rules
for type conversion. X1 expression to be converted.

an expression that can be converted to

integer specifying the length of the
BOOL(x,-,xa,X3) string-handling resulting character string. If
necessary, X2 is converted to a binary
integer of precision (15,0). If X2 is
BOOL returns a bit string that is the omitted, the length is determined by
result of a Boolean operation, speCified by the rules for type conversion.
X3, on bit strings X1 and X2. The length
of the result is equal to that of the
longer operand, X1 or X2.
ICOMPILETIME Preprocessor
and X2 bit-string expressions or I
expressions that may be converted to I
bit strings. ICOMPILETIME returns a character string of
Ilength 18, containing the date and the time
bit string of four bits. Each bit lof compilation. The returned string has
specifies the result when a bit from the following format:
X1 is compared with the corresponding
bit from X2 as follows: DD~MMM~YY~HH.MM.SS

X1 X2 result where ~ is a blank and:

0 0 bit 1 of X3 DO is the day of the month.

0 1 bit 2 of X3 MMM is the month in the
1 0 bit 3 of X3 form JAN, FEB, MAR, etc.
1 1 bit 4 of X3 YY is the year.
HB is the hour.
If X1 and X2 are different lengths, the MM is the minute.
shorter is ~added on the right with zeros SS is the second.
to match the longer. If X3 is not a bit
string expression of length 4, it will be A leading zero in the day of the month
converted and padded on the right with field is replaced by a blank; no other
zeros or truncated on the right, as leading zeros are suppressed.
necessary.
If no timing facility is available, the
last eight characters of the returned
string are set to 00.00.00.
CEIL(x) Arithmetic

CEIL returns the smallest integer greater COMPLETION (x) Multitasking

than or equal to a given value x. x must
be real.
COMPLETION returns a single bit specifying
If x is fixed-point with precision the completion value ot a given event x.
(p,q), the precision of the result is given If the event is incomplete, 'O'B is
by: returned; if complete, 'l'B is returned.

366 OS PL/I CKT AND OPT LRM PART II

COMPLETION Pseudovariable CONJG(x) Arithmetic

The pseudovariable sets the completion CONJG returns the conjugate of a given
value of the given event x. x must be complex value x, i.e., the same value with
inactive. No interrupt can occur during the sign of the imaginary part reversed.
assignment to the pseudovariable. The If x is real, it will be converted to
COMPLETION pseudovariable cannot be used as complex.
the control variable in a do-goup.

COS (x) Mathematical

COS returns a floating-point value that

COMPLEX(Xa"xa) Arithmetic represents the cosine of a given value x.

x an expression whose value is in

radians.

Abbreviation: CPLX(x~,xa) If x is complex, the result is given by:

cos(a)*cosh(b)-i*sin(a)*sinh(b)

COMPLEX returns a complex value formed from where (a+i*b) represents x.

two given values X1 and Xa.

real value that is to be the real part

of the result. COSO(x) Mathematical

real value that is to be the imaginary

part of the result. COSO returns a floating-point value that
represents the cosine of a given value x.
If x~ and Xa differ in base, the decimal
one is converted to binary; if they differ x an expression whose value is in
in scale, the fixed-point is converted to degrees. x must be real.
floating-point. The result will have the
same base and scale. Both X1 and Xa must
be real.

The precision of the result, if fixed-

point, is given by: COSH(x) Mathematical

(MIN(N,MAX(p1-Q1,Pa-qa)+MAX(q1,qa»,
MAX(Q~,q2» COSH returns a floating-point value that
represents the hyperbolic cosine of a given
where (P1,Q1) and (Pa,qa) are the value x.
precisions of X1 and Xa respectively, and N
is the maximum number of digits allowable. If x is complex, the result is given by:

If the arguments, after any necessary cosh(a)*cos(b)+i*sinh(a)*sin(b)

conversions have been performed, are
floating point, and their precisions are P1 where (a+i*b) represents x.
and Pa, then the precision of the result is
MAX ( P1 , P:.a) •

COUNT (x) Input/Output

COMPLEX Pseudovariable
COUNT returns a binary integer of default
precision specifying the number of data
The pseudovariable assigns the real part of items transmitted during the last GET or
a complex value to the variable X1 and the POT operation on the specified file x.
imaginary part to the variable xa. Only a
complex value can be assigned to the x a file expression, the file must have
pseudovariable. The COMPLEX pseudovariable the STREAM attribute.
cannot be used as the control variable in a
do-group. The count of transmitted items for a GET

Section G: Built-in Functions and Pseudovariables 367

lor PUT operation on the specified file is storage.
linitialized to zero before the data item is
I transmitted, and is incremented by one t
lafter the transmission of each data item in I The value returned by CURRENTSTORAGE(x)
Ithe list. lis defined as the number of bytes that
Iwould be transmitted in the following
Note that if an on-unit or procedure is I circumstances:
entered during a GET or PUT operation and,
within that on-unit or procedure, a GET or
PUT operation is executed for the same DECLARE F FILE RECORD OUTPUT
file, the value of COUNT is reset for the OPTIONS(SCALARVARYING);
new operation; i t is restored when the
original GET or PUT is continued.
WRITE FILE(F) FROM(x);

I
COUNTER Preprocessor I If x is a scalar varying-length string,
Ithe returned value includes the length-
Iprefix of the string and the number of
COUNTER returns a character string of Icurrently-used bytes; it does not include
length 5, containing a decimal number. lany unused bytes in the string.
The returned number is 00001 for the first
invocation, and is incremented by one on I
each successive invocation. COUNTER may be I If x is a scalar area, the returned
used to generate unique identifiers, or for Ivalue includes the area control bytes and
general counting purposes. Ithe current extent of the area; i t does no~
linclude any unused bytes at the end of the
If COUNTER is. invoked more than 99999 larea.
times, a diagnostic is issued and 00000 is
returned. The next invocation is treated
as the first. If x is structure or array containing
areas or varying-length strings, the
returned value includes the area control
bytes, the maximum sizes of the areas, the
CURRENTSTORAGE(x) storage Control length prefixes of the strings, and the
number of bytes in the maximum lengths of
the strings. There is one exception to
Abbreviation: CSTG(x) this rule: if x is a structure whose last
element is a non-dimensional area, the
returned value includes that area's controi
CURRENTSTORAGE returns a fixed-point binary bytes and the current extent of that area;
integer of precision (31,0) giving the i t does not include any unused bytes at the
implementation-defined storage, in bytes, end of that area.
required by a specified variable Wx".
I
x a variable of any data type, data I CURRENTSTORAGE cannot be used to obtain
organization, and storage class Ithe storage requirements of a structure
except: Imapped according to the COBOL mapping
I algorithm.
1. A BASED, DEFINED, parameter,
subscripted, or structure-base-
element variable that is an
unaligned fixed-length bit string.
DATAFIELD condition-handling
2. A minor structure whose first or
last base element is an unaligned
fixed-length bit string (except DATAFIELD is used in a NAME condition on-
where i t is also the first or last unit to return a character string whose
element of the containing major value is the name and contents of the field
structure). that caused the condition to be raised.

3. A major structure that has the It can also be used in an on-unit for an
BASED, DEFINED, or parameter ERROR or FINISH condition raised as part of
attribute, and which has an the standard system action for the NAME
unaligned fixed-length bit string condition.
as its first or last element.
If DATAFIELD is used out of context, a
4. A variable not in connected null string is returned.

368 os PL/I CKT AND OPT LRM PART II

 Arithmetic

DATE returns a character string of length DIVIDE returns the quotient of two values
six, in the form yymmdd, where: X1 and xa with a precision specified by X3
and x", •

yy the current year

rom the current month dividend
dd the current day

Xa divisor

unsigned decimal integer constant

specifying the number of digits to be
Arithmetic maintained throughout the operation;
i t must not exceed the implementation
limit.

decimal integer constant, optionally

DECIMAL returns the decimal representation signed, specifying the scale factor of
of a given value a1 with a precision the result. For a fixed-point result,
specified by X2 and X3. if x", is omitted, a scale factor of
zero is assumed. For a floating-point
result, only X3 can be given.
X1 value to be converted to decimal base.

X2 unsigned decimal integer constant

specifying the number of digits to be
maintained throughout the operation; storage Control
i t must not exceed the implementation
limit.
EMPTY returns an area of zero extent. It
decimal integer constant, optionally is used to free all allocations in an area.
signed, specifying the scale factor of Note that the value of this function is
the result. For a fixed-point result, automatically aSSigned to an area variable
if X 2 is given and X3 is omitted, a when it is allocated.
scale factor of zero is assumed. For
a floating-point result, only xa can
be given.
ERF(x) Mathematical
If both X2 and X3 are omitted, the
precision of the result is determined from
the rules for base conversion. ERF returns a floating-point value that
represents the error function of a given
value x. x must be real.

DIM(xa.'x,a) Array-Handling The result is given by:

x -t 2
ERF(x)=£ f e dt
DIM returns a default-precision fixed-point
binary integer specifying the current
vII 0

extent of a specified dimension X2 of a

given array X1. ERFC(x) Mathematical

the given array; i t must be currently

allocated. ERFC returns a floating-point value that
represents the complement of the error
Xa the element expression specifying a function of a given value x. x must be
particular dimension of X1. If real.
necessary, xa is converted to a binary
integer of precision (15,0). The result is defined in terms of the
function ERF as:
X1 must not have less than (xa) dimensions,
land must not be an array of structures. 1-ERF(x)

Section G: Built-in Functions and Pseudovariables 369

EXP(x) Mathematical HBOUND(x"x,il) Array-Handling

EXP returns a floating-point value that HBOUND returns a default-precision fixed-

represents the base of the natural point binary integer specifying the current
logarithm system e to a given power x. upper bound o! a specified dimension Xa of
a given array X1_
X1 the given array; it must be currently
allocated.
Arithmetic
xa an element expression specifying a
particular dimension of X1. If
FIXED returns the fixed-point necessary, xa is converted to a binary
representation of a given value X1 with a integer of precision (15,0).
precision specified by xa and X3.
X1 must not have less than (xa) dimensions,
X1 value to be converted to fixed-point land must not be an array of structures.
scale.
Xa unsigned decimal integer constant
specifying the total number of digits BIGB(x) String-handling
in the result.
decimal integer constant, optionally HIGH returns a character string of length x
signed, specifying the scale factor of where each character is the highest
the result. If X3 is omitted, a scale character in the collating sequence
factor of zero is assumed. (hexadecimal FF).
If both Xa and X3 are omitted, the default x expression specifying the length. If
value (15,0), for a binary result, or necessary, x is converted to a binary
(5,0), !or a decimal result, is assumed. integer of precision (15,0).

FLOAT(X, (,X,il]) Arithmetic I MAG (x) Arithmetic

FLOAT returns the floating-point lMAG returns the imaginary part of a given
representation of a given value X1 with a complex value x. If real, x is converted
precision specified by xa. to complex. The mode of the result is
real.
X1 value to be converted to floating-
point scale.
Xa unsigned decimal integer constant lMAG Pseudovariable
specifying the total number of digits
in the result. If Xa is omitted, the
default value 21, for a binary result, The pseudovariable assigns a real value or
or 6, for a decimal result, is real part of a complex value to the
assumed. imaginary part of a given complex variable
x. x must be complex.

FLOOR(x) Arithmetic
INDEX(x"Xa) string-handling
FLOOR returns the largest integer less than
or equal to a given value x. x must be INDEX returns a halfword binary integer
real. indicating the starting position within the
string X1 of a substring identical to
If x is fixed-point with prec1s1on (p,q), string xa.
the precision of the result is given by:
X1 string to be searched
("IN(N,MAX(p-q+l,l»,O)
xa string to be searched for
where N is the maximum number of digits
allowable. If xa does not occur in X1. the value

370 os PL/I CRT AND OPr LRM PART II

 zero is returned. the given array; it must be currently
allocated.
If xa occurs more than once in X1' the
starting position of the first occurrence
is returned. xa an element expression specifying the
particular dimension of X1. If
If any argument is character or decimal, necessary, Xa is converted to a binary
conversions are performed to produce integer of precision (15,0).
character strings. Otherwise if the
arguments are bit and binary, or both
binary, conversions are performed to X1 must not have less than (xa) dimensions,
produce bit strings. land must not be an array of structures.

IINDEX(xs,xa) Preprocessor
I
I
IINDEX (preprocessor) returns a FIXED value LINENO(x) Input/output
lindicating the starting position within
Istring X1 of a substring identical to
Istring xa. LINENO returns a default-precision fixed-
I point binary integer specifying the current
X1 string to be searched line number of the specified file x.
Xa string to be searched for x a file expression, the file must have
the PRINT attribute.
If Xa does not occur in X1, the value zero
is returned.
If xa occurs more than once in X1 , the LOG (x) Mathematical
starting position of the first "occurrence
is returned.
LOG returns a floating-point value that
The arguments of INDEX (preprocessor) are represents the natural logarithm, i.e.,
converted to character if necessary. base e, of a given value x. If x is real,
it must be greater than zero. If x is
complex, it must not be equal to 0+01. The
fUnction is multiple-valued if x is
LENGTH (x) String-handling complex; hence, only the principal value
can be returned. The principal value has
the form:
LENGTH returns a default-precision fixed-
point binary integer specifying the current (a+i*b)
length of a given string x. If x is
binary, it is converted to bit string; where b is the range:
otherwise any other conversion required is
to character string. -pi<b<=pi.

ILENGTH (x) Preprocessor LOG2(x) Mathematical

I
I
ILENGTH (preprocessor) returns a FIXED value LOG2 returns a floating-point value that
Ispecifying the current length of a given represents the binary logarithm, i.e., base
Istring x. If x is FIXED, it is converted 2, of a given value x. x must be real and
Ito CHARACTER. greater than zero.

LBOUND(x, ,Xa) Array-Handling tOG10(x) Mathematical

LBOUND returns a default-precision fixed- LOG10 returns a floating-point value that

point binary integer specifying the current represents the common logarithm, i.e., base
lower bound of a specified dimension Xa of 10, of a given value x. x must be real and
a given array X1. greater than zero.

Section G: Built-in FUnctions and Pseudovariables 371

LOW(x) String-handling

LOW returns a character string of length x If the arguments, after any necessary
where each character is the lowest conversions have been performed,. are
character in the collating sequence floating point, and their precisions are
(hexadecimal 00). If necessary, x is P~,Pa'P3 ••• Pn, then the precision of the
converted to binary integer of precision result is MAX(P1,Pa,P3 ••• Pn).
(15,0).

x expression specifying the length

MOD(X"xa) Arithmetic

MAX (Xi., Xa . . . , xp) Arithmetic IMOD returns the smallest non-negative

value, R, such that:
MAX returns, from a set of two or more (Xi. - R)/Xa =n where n is an integer.
arguments, the value of the argument with
the largest value. IR is the smallest non-negative value that
must be subtracted from a given value xi. to
X1,Xa ••• ,xn list of values from which the make it exactly divisible by the given
largest is to be returned. value xa.
The maximum number of arguments that the X1 must be real. If X1 is positive, R
function will accept is 64. All the is the remainder of the division of Xi. and
arguments must be real. Xa; if x1 is negative, R is the modular
eqUivalent of this remainder.
If the arguments are fixed-point with
precisions: Xa must be real. If xa is zero, the
ZERODIVIDE condition is raised. If R is
floating-point, the precision is the
greater of those of X1 and xa; if R is
the precision of the result is given by: fixed-pOint, the precision is given by:
(MIN(N,MAXCP1-Q1,Pa-qa···,Pn-qn)+
MAX(qi.,qa.·· ,qn» ,MAX(Q1,qa ••• ,~»
where (P1,Q1)' and (Pa,qa) are the
If the arguments, after any necessary precisions of X1 and Xa respectively.
conversions have been performed, are
floating point, and their precisions are If X1 and xa are fixed-point with different
P1,pa,P3 ••• Pn, then the preCision of the scale factors, R may be truncated on the
result is MAX(P1,Pa,P3 ••• Pn). right, and the SIZE condition is raised, if
enabled.

Arithmetic
Ari thmet'ic
MIN returns, from a set of two or more
arguments, the value of the argument with MULTIPLY returns the product of two values
the smallest value. X1 and xa with a precision specified by X3
and X41 •
X1,Xa ••• ,xn list of values from which the
smallest is to be returned. X1 and xa values to be multiplied.
The maximum number of arguments that the unsigned decimal integer constant
function will accept is 64. All the specifying the number of digits to be
arguments must be real. maintained throughout the operation;
it must not exceed the implementation
If the arguments are fixed-pOint with limit.
precisions:
decimal integer constant, optionally
(P1,~),(Pa,Qa)···,(Pn,~) signed, specifying the scale factor of
the result. For a fixed-pOint result,
the precision of the result is given by: if x4\is omitted, a scale factor of
zero is assumed. For a floating-pOint
(MIN(N,MAX(p1-q1,P2-Qa···,Pn-qn)+ result, only X3 can be given.

372 OS PL/I CRT AND OPT LRM PART II

 Storage control ON CODE Condition-handling

NULL returns a null pOinter value, i.e., a ONCODE returns a default-precison fixed-
value that cannot identify any generation point binary integer that defines the
of a variable. The null pOinter value can type of interrupt that caused the on-unit
be converted to OFFSET by assignment of the to become active. It can be used in any
built-in function value to an offset on-unit. All on-codes are defined in
variable. section H, "On-Conditions".

If ONCODE is used out of context, zero

is returned.

OFFSET (X,.,Xa) Storage control

ONCOUNT Condition-handling
OFFSET returns an offset value derived from
a given pOinter x~ and relative to a given
area X2. If x~ is null, then the null ONCOUNT returns a default-precision fixed-
value is returned. pOint binary integer specifying the number
of interrupts that remain when an on-unit
x~ a pointer expression. It must is entered. Both types of multiple
identify a generation of a based interrupt are discussed in section H, "ON-
variable within area X2. Conditions".

an area variable If ONCOONT is used out of context, zero

is returned.
If x~ is an element expression, then X2
must be an element Variable.

ONFILE Condition-handling

ONCHAR Condition-handling
ONFILE returns a character string whose
value is the name of the file for which an
ONCHAR returns the character that caused input/output or CONVERSION condition is
the CONVERSION condition to be raised. It raised. It can be used in an on-unit for
can be used in an on-unit for the any input/output or CONVERSION condition,
CONVERSION condition or for ERROR or FINISH or for the ERROR or FINISH condition raised
condition raised as standard system action as standard system action for an
for the CONVERSION condition. input/output or the CONVERSION condition.

If the ONCHAR built-in fUnction is used If ONFILE is used out of context, a null
out of context, a blank is returned unless string is returned.
ONCBAR has a value given to i t by an
assignment to the pseudovariable out of
context; in this case, the character
assigned to the pseudovariable is returned Condition-handling
by the built-in function.

ONKEY returns a character string whose

value is the key of the record that caused
ONCHAR pseudovariable an input/output condition to be raised. It
can be used in an on-unit for any
input/output condition, except ENDFILE, or
The pseudovariable resets the current value for the ERROR or FINISH condition raised as
of the ONCHAR built-in function. The value standard system action for an input/output
assigned to the pseudovariable is converted condition. Note that ONKEY is always set
to a character string of length 1. The new for operations on a KEYED file, even if the
character is used when the conversion is statement that causes the condition to be
r-e-attempted. raised has not specified the KEY, KEYTO, or
KEYFROM options.
If the pseudovariable is used out of
context, and the next reference to the The result is determined by the
built-in function is also out of context, following rules:
then the character assigned to the
pseudovariable is returned. The out-of- 1. For any input/output condition (other
context assignment is otherwise ignored. than ENDFILE), or for the ERROR or

section G: Built-in Functions and Pseudovariables 313

 FINISH condition raised as standard value aSSigned to the pseudovariable is
system action for these conditions, converted to a character string and, if
the result is the value of the necessary, is padded on the right with
recorded key from the I/O statement blanks to match the length of the field
causing the error. that caused the error. The new string is
used when the conversion is re-attempted.
For REGIONAL(l) data sets, the result
is an eight-byte character
representation of the region number. When conversion is re-attempted, the
If the key was incorrectly specified, string assigned to the pseudovariable is
the result is the last eight bytes of processed as a Single data item. For this
the source key. If the source key is reason, the error correction process should
less than eight bytes, it is padded on not assign a string containing more than
the right with blanks to make it eight one data item when the conversion occurs
bytes. If the key was correctly during the execution of a GET LIST or GET
specified, the eight-byte character DATA statement. The presence of blanks or
string consists of the region number commas in the string will cause further
in character form padded on the left conversion error.
with blanks, if necessary.

2. For a REWRITE statement that attempts

to write an updated record on to an
indexed data set when the key of the
updated record differs from that of
the input record, the result is the I PARMSET (x) Preprocessor
value of the embedded key of the input I
record. I
IPARMSET returns the truth value of the
If ONKEY is used out of context, a null lassertion that parameter x was set when a
string is returned. Ipreprocessor procedure was invoked.

Ix a parameter of a preprocessor
Condition-handling I procedure.

ONLOC returns a character string whose I PARMSET may be used only within a
value is the name of the entry-point of the Ipreprocessor procedure, and x must be a
procedure in which the condition was Iparameter of that procedure. It may be
raised. It can be used in anyon-unit. lused freely in preprocessor expressions.

If ONLOC is used out of context, a null

string is returned. I PARMSET returns a bit value of one if
Ithe parameter has been set, or a bit value
lof zero if it has not. The returned value
lis converted if necessary to a FIXED value
ONSOURCE Condition-handling lor to a CHARACTER value of length one.

ONSOURCE returns a character string whose , PARMSET is always returns zero if the
value is the contents of the field that was Iprocedure reference does not contain an
being processed when the CONVERSION largument that matches the specified
condition was raised. It can be used in an ,parameter. However, PARMSET may also
on-unit for the CONVERSION condition or for Ireturn zero if a matching argument does
the ERROR or FINISH condition raised as appear in the reference, but the reference
standard system action for the CONVERSION is in another preprocessor procedure. The
condition. rules that apply in this case are as
follows:
If ONSOURCE is used out of context, a
null string is returned. 1. If the argument is not itself a
parameter of the invoking procedure,
PARMSET returns one.

ONSOURCE Pseudovariable 2. If the argument is a parameter of the

invoking procedure, PARMSET returns
the value for the specified parameter
The pseudovariable resets the current value when the invoking procedure was itself
of the ONSOURCE built-in function. The invoked.

374 OS PL/I CKT AND OPT LRM PART II

,,,PLIRETV a(m)
n-m
+~
j-l
(a(m+ j )*1ilr x (p+i»
IPLIRETV returns a fixed binary integer of
Idefault precision whose value is the j=l i=O
,current value of the PL/I return code.

I If (q-p)«n-m-1) then x(p+i)=x(q) for

I The value of the PL/I return code is (p+i»q.
leither the value specified by a CALL
I PLIRETC statement, or the value r·eturned in
,the lower-half of register 15 by a COBOL, If m=n then the result is a(m).
I FORTRAN, or Assembler routine whose entry
,point is declared with OPTIONS(RETCODE •• ).
If Xa is an element expression, it is
interpreted as an array of one element,
i.e., x(l), and the result is defined as:

n-m
POINTER(x"Xa) storage Control
~ a(m+j)*x(l)**j
Abbreviation: PTR(x1 ,xa) j=O
X1 must not be iSUB-deinfed.
POINTER returns a pointer value derived
from a given offset value X1 and a given
area xa. If X1 is null then the null value
is returned. PRECISION(x"xa[,xa]) Arithmetic

an offset expression. It must

identify a generation of a based
variable, but not necessarily in xa.
If it is not in Xa, the generation PRECISION returns a given value x 1 with a
must be equivalent to one in xa. p~ecision specified by Xa and Xa.
Xa an area variable. value whose precision is to be
changed.
Generations of based variables in
different areas are equivalent if, up to unSigned decimal integer constant
the allocation of the latest generation, specifying the number of digits that
the variables have been allocated and freed the value of X1 is to have after
the same number of times as each other. conversion; it must not exceed the
implementation limit.
decimal integer constant, optionally
POLY(X"Xa) Array-Handling signed, specifying the scale factor of
the result. For a fixed-point result,
if X3 is omitted, a scale factor of
POLY returns a floating-point value that zero is assumed. For a floating-point
represents a polynomial formed from two result, X3 must not be given.
given unidimensional arrays X1 and Xa.
The base and scale of the returned value
an array defined as a(m:n), where are the same as those of X1.
(m:n) represents the lower and upper
bounds.
Xa an array defined as x(p:q), where PRIORITY (x) Multitasking
(p:q) represents the lower and upper
bounds.
PRIORITY returns a halfword binary integer
If the elements of one or both of the indicating the priority associated with the
arrays are not floating-point, they are given task variable x. It gives the
converting to floating-point priority relative to the priority of the
current task. No interrupt can occur
The returned value is defined as: during evaluation of PRIORITY.

Section G: Built-in Functions and pseudovariables 375

PRIORITY Pseudovariable be (xa+l) occurrences of the string xl._
xl. string to be repeated
The pseudovariable adjusts the priority of
the task associated with the given task xa an expression that can be converted to
variable x. It receives a halfword binary integer indicating number of
integer, and sets the priority of a to· the repetitions.
received value, relative to the priority
held by the current task immediately prior If xl. is arithmetic, it will be converted
to the assignment. x may be associated to string - bit string if it is binary,
with any active or inactive task, including character string if it is arithmetic. If
the current one. The task variable may be Xa is zero or negative, the string xl. is
omitted, in which case the variable returned.
associated with the current task is
assumed. No interrupt can occur during If xa is an array, then xI. should be an
assignment to the PRIORITY pseudovariable. array with identical bounds.
The PRIORITY pseudovariable cannot be used
as the control variable in a DO group.
ROUND(x"Xa) Arithmetic
PROD (x) Array-Handling
ROUND returns the given value xl. rounded at
a digit specified by xa.
PROD returns the product of all the
elements in a given array x. the value to be rounded.
x an array of integers or floating-point decimal integer constant, optionally
elements. Signed, specifying the digit at which
rounding is to occur. If Xa is
If the elements of x are non-integer poSitive, it is the (xa)th digit to
fixed-point, they are converted to the right of the point; if negative,
floating-point. it is the (xa+l)th digit to the left
of the paint.
If the elements of x are string, they
are converted to integers. The preCision If xl. is floating-point, xa is ignored: the
of the result for fixed-point integers is rightmost bit of the mantissa is set to 1.
(N, 0), where N is the maximum number of
digits allowable. x must not be iSUB- The precision of a fixed-paint result i~
defined. given by:
(MAX(l,MIN(p-q+l+xa,N»,xa)
REAL (x) Arithmetic where (p,g) is the preCision of xl. and N is
the maximum number of digits allowable.
REAL returns the real part of a given Note that the rounding of a negative
complex value x. x will be converted to value results in the rounding of its
complex if it is real. absolute value, then the sign is replaced.

REAL Pseudovariable ISAMEKEY(x) Input/Output

I
I
The pseudovariable assigns a real value or ISAMEKEY returns a Single bit indicating
the real part of a complex value to the Iwhether a record that has been accessed is
real part of a·given complex variable x. x Ifollowed by another with the same key.
must not be real. I
Ix a file expression, the file must have
I the RECORD attribute.
I
REPEAT(x,-,xa) string-handling I The SAMEKEY built-in function returns a
IBIT(l) value. Upon successful completion
lof an input/output operation on file ·x·,
REPEAT returns a string consisting of the lor immediately before the RECORD condition
string xl. concatenated to itself the number lis raised, the value of SAMEKEY is set to
of times specified by Xa, i.e., there will l-l'B if the record processed is followed by

376 OS PL/I CKT AND OPT LRM PART II

lanother record with the same key. SINH(x) Mathematical

I
1 A value of 'O'B is returned if the file SINH returns a floating-point value that
Idoes not have the KEYED and SEQUENTIAL represents the hyperbolic sine of a given
I attributes, if the file is not open, if the value x. If x is complex, the result is
Ifile is not associated with a VSAM indexed given by:
Idata set, or if the record processed is not
Ifollowed by another record with the same sinh(a)*cos(b)+i*cosh(a)*sin(b)
I key.
1 where (a+i*b) represents x.
I If the input/output operation causes a
Icondition other than RECORD to be raised,
Ithe value of SAMEKEY is 'O'B if file
Ipositioning has been changed or lost. SQRT(x) Mathematical
I Otherwise, the value of SAMEKEY remains
I unchanged.
I SQRT returns a floating-point value that
I The value returned by SAMEKEY is represents the square root of x. If x is
lundefined if ·x· has the STREAM attribute. real, it must not be less than zero. The
result is the positive square root of x.
If x is complex, the function is multiple-
valued; hence, only the principal value can
SIGN(x) Arithmetic be returned. The principal value has the
form:
SIGN returns a default-precision fixed- (a+i*b)
point binary integer that indicates whether
a given value x is positive, zero, or where either a>O, or a=O and b>=O.
negative. The value returned is as
follows:
value of x value returned STATUS[(x)] Multitasking

x > ° +1
STATUS returns a default-precision fixed-
x = ° pOint binary integer specifying the status
° value of a given event x. If the event is
x < ° -1 normal, zero is returned; if abnormal, non-
zero is returned. If no argument is
x must be real. specified, the event associated with the
current task is assumed.

SIN (x) Mathematical

STATUS pseudovariable
SIN returns a floating-point value that
represents the sine of a given value x. The pseudovariable resets the status value
of a given event x. No interrupt can occur
x an expression whose value is in radians. during aSSignment to the pseudovariable.
If x is complex, the result is given by:
sin(a)*cosh(b) +i*cos (a) *sinh(b) STORAGE (x) Storage Control
where (a+i*b) represents x.
Abbreviation: STG(x)

SIND (x) Mathematical STORAGE returns a fixed-point binary

integer of precision (31,0) giving the
implementation-defined storage, in bytes,
SIND returns a floating-point value that required by a specified variable ·x".
represents the sine of a given value x.
x a variable of any data type, data
x an expression whose value is in organization, and storage class
degrees. x must be real. except:

Section G: Built-in Functions and pseudovariables 311

 1. A BASED, DEFINED, parameter, function reference.
subscripted, or structbre-base-
element variable that is an If x is a structure that has padding caused
unaligned fixed-length bit string. by ALIGNED elements, the padding is not
included in the result.
2. A minor structure whose first or
last base element is an unaligned If any of the strings in the aggregate x
fixed-length bit string (except are of varying length, only the current
where it is also the first or last length, and not including the two-byte
element of the containing major length prefix, is concatenated.
structure) •
x must not be iSUB-defined.
3. A major structure that has the
BASED, DEFINED, or parameter If x is an element variable, the rules for
attribute, and which has an aggregates apply except that there is nO
unaligned fixed-length bit string concatenation.
as its first or last element.
4. A variable not in connected
storage. STRING pseudovariable
The value returned by STORAGE(x) is
defined as the number of bytes that would The pseudovariable assigns a string, piece
Ibe transmitted in the following by piece, to the given aggregate variable
I circumstances: x, until either all of the aggregate
I elements are filled or nO piece of the
I DECLARE F FILE RECORD INPUT aSSigned string remains. In the latter
I OPTIONS(SCALARVARYING); case, any remaining strings in the
I aggregate variable are filled with blanks
I or, if varying-length, are given zero
I READ FILE (F) INTO (x); length.
I
I If x is a scalar varying-length string, The STRING pseudovariable must not be
Ithe returned value includes the length- used in the data speCification of a GET
Iprefix of the string and the number of statement, nor in an INTO or KEYTO option
I bytes in the maximum length of the string. of a READ statement.
I
I If x is a scalar area, the returned The STRING pseudovariable cannot be used
Ivalue includes the area control bytes and as the control variable in a DO-group.
Ithe maximum size of the area.
I A varying-length string is filled to its
I If x is a structure or array containing maximum length.
lareas or varying-length strings, the
Ireturned value includes the area control
I bytes, the maximum sizes of the areas, the
Ilength prefixes of the strings, and the string-handling
Inumber of bytes in the maximum lengths of
Ithe strings.
I SUBSTR returns a substring of the given
I STORAGE cannot be used to obtain the string X1.
Istorage requirements of a structure mapped
laccording to the COBOL mapping algorithm. X1 string from which the substring is to
be extracted.

xa an expression that can be converted to

STRING (x) string-handling integer indicating the starting
position of the substring in X1.
STRING returns an element string that is X3 an expression that can be converted to
the concatenation of all the elements of a integer specifying the length of the
string data aggregate. substring in x~. If %3 is zero, a
null string is returned. If X3 is
x an array or structure expreSSion whose Omitted, the substring returned is
elements are either all character position xa in x~ to the end of x~.
strings and/or numeric character data,
or all bit strings. If X1 is not a string, it is converted to a
bit string if binary or a character string
x cannot be an operational expression or a if decimal.

378 OS PL/I CRT AND OPT LRM PART II

 The STRINGRANGE condition, if enabled, where (a+i*b) represents x.
is raised if the values of X2 and X3 are
such that the substring does not lie
entirely within x~. If STRINGRANGE is not
enabled, then under the optimizing compiler TAND(x) Mathematical
the result is undefined and under the
checkout compiler, standard system action
is taken (even if there is STRINGRANGE on- TAND returns a floating-point value that
unit established.) represents the tangent of a given value x.
x an expression whose value is in
degrees. x must be real.
ISUBSTR(x&,xa[,X3]) Preprocessor
,ISUBSTR
I
(preprocessor) returns a substring TANH (x) Mathematical
lof a specified string (see description of
Ithe non-preprocessor built-in function in
Ipreceeding paragraphs). If necessary, x~ TANH returns a floating-point value that
lis converted to CHARACTER and xa and X3 are represents the hyperbolic tangent of a
,converted to FIXED. given value x.
x an expression whose value is in
radians.
SUBSTR Pseudovariable
If x is complex the result is defined as:
The pseudovariable assigns a string to a -i*TAN(i*x)
substring of the given string x. The
remainder of string x is unchanged.

SUM (x) Array-Handling

TIME returns a character string of length
nine, in the form hhmmssttt, where:
SUM returns the sum of all the elements in
a given array x. hh the current hour
nun number of minutes
x an array of arithmetic elements. ss number of seconds
ttt number of milliseconds
If the elements of x are fixed-point, the
precision of the result is (N,q), where N If no timing facility is available, TIME
is the maximum number of digits allowable returns the value (9)'0'.
and q is the scale factor of x. If the
elements of x are strings, they are
converted to integers.
String-handling
x must not be iSUB-defined.
TRANSLATE returns a string the same length
as a given string X1 where all or some of
TAN (x) Mathematical the characters may have been changed.
Characters are changed according to a look-
up table provided by strings xa and X3.
TAN returns a floating-point value that
represents the tangent of a given value x. The function operates on each character
of X1 as follOWS:
x an expression whose value is in
radians. If a character in X1 is found in X3' then
the character in Xa that corresponds to the
If x is complex, the result is defined as: one in X3 is copied to the result:
otherwise, the character in X1 is copied
REAL (TAN(x» = TANCa)*(1-TANH(b)**2)/ directly to the result.
(1+(TAN(a)*TANB(b»**2)
character string to be searched for
IMAG(TAN(x» = TANH(b)*(1+TAN(a)**2)/ possible translation of all or some of
Cl+(TAN(a)*TANH(b»**2) its characters.

Section G: Built-in FUnctions and Pseudovariables 379

 character string containing the
translation values of characters.
r-----------------------------------------,
bit-string I attributes of x
length I

X3 character string containing the 16 tFlXED BINARY (p,q) for p<16

characters that are to be translated.
If X3 is omitted, a string of 256 32 IFIXED BINARY (p,q) for p>15
characters is assumed; it contains all !FLOAT BINARY (p) for p<22
possible characters arranged in IFLOAT DECIMAL (p) for p<7
ascending order (hexadecimal 00 !POINTER (standard length)
through FF). I OFFSET
IFILE constant or variable
!POINTER (under checkout
strings X2 and X3 should be the same Icompiler with COMPATIBLE
length; otherwise X2 is padded with blanks, !option)
or truncated, on the right to match the
length of X3. 64 tFLOAT BINARY (p) for 21<p<54
!FLOAT DECIMAL (p) for 6<p<17
!LABEL constant or variable
Any non-character arguments are !ENTRY constant or variable
converted to character.
128 !FLOAT BINARY(p) for 53<p<110
IFLOAT DECIMAL(p) for 16<p<34
!TASK
IPOINTER (under checkout
Icompiler with NOCOMPATIBLE
!option)
TRUNC(x) Arithmetic
256 !EVENT

TRONC returns an integer that is the n tBIT (n)

truncated form of a given value x. If x is
positive or zero, the result is the largest n+16 IBIT VARYING where n is the
integer less than or equal to x. If x is Imaximum length of x.
negative, the result is the smallest
integer greater than or equal to x. x must 8*n ICHARACTER (n)
be real. 'PICTURE
I (with character-string
Ilength of n)
If x is fixed-point with precision
(p,q), the precision of the result is given 8* (n+2) ICHARACTER VARYING where n is
by: ,the maximum length of x.

(MIN(N,MAX(p-q+1,1»,0) 8*(n+16) IAREA (n)

where N is the maximum number of digits 8*FLOOR(n) ,FIXED DECIMAL (p,q)

allowable. ,where n = (p+2)/2
l-----------------------------------------J
ONSPEC(x) String-handling

UNSPEC returns a bit string that is the

internal coded form of a given value x.

x expression of any data type. UNSPEC pseudovariable

The length of the returned bit-string

depends on the-attributes of x. The pseudovariable assigns a bit string
directly to the given variable x, i.e., nO
If x is a varying-length string, its conversion to the data type of the variable
two-byte prefix is included in the returned is atte~ed. The bit string is padded, if
bit-string. necessary, on the right with zeros to match
the length of the variable. If x is a
If x is complex, the length of the varying length string, its two-byte prefix
returned string is twice the value given in is included in the field to which the bit
the following table. string is assigned.

380 OS PL/I CKT AND OPT LRM PART II

 string-handling string to be scanned for any character
not in Xa.
VERIFY returns a default-precision fixed-
point binary integer indicating the Xa the verification string, consisting of
position in the given string X~ of the a set of characters in any order.
first character or bit that is not in the
given string Xa. If all the characters or
bits in X1 do appear in Xa, a value of zero If either argument is character or decimal,
is returned. The arguments are converted conversions are performed to produce
to strings if they are arithmetic. If one character strings. Otherwise, if the
string argument is bit and the other arguments are bit and binary or both
character, the bit is converted to binary, conversions are performed to
character. produce bit.

Section G: Built-in Functions and Pseudovariables 381

 Section H: ON-Conditions

The on-conditions are those exceptional of a condition prefix is discussed in

conditions that can be specified in PLII by chapter 14, "Exceptional Condition Handling
means of an ON statement. If a condition and Program Checkout".)
is enabled, the occurrence of the condition
will result in an interrupt. The conversely, those conditions that are
interrupt, in turn, will result in the always disabled unless they have been
execution of the current action enabled by a condition prefix are:
specification for that condition. If an ON
statement for that condition is not in SIZE
effect, the current action specification is
the standard system action for that SUBSCRIPTRANGE
condition. If an ON statement for that
condition is in effect, the current action STRI NGRANGE
specification is either SYSTEM, in which
case the standard system action for that STRINGSIZE
condition is taken, or an on-unit, in which
case the programmer has supplied his own CHECK
action to be taken for that condition.
The appearance of one of these five in a
Some conditions are always enabled condition prefix renders the condition
unless they have been explicitly disabled enabled throughout the scope of the prefix;
by condition prefixes; others are always the condition remains disabled outside this
disabled unless they have been explicitly scope. Further, a condition prefix speci-
enabled by condition prefixes; and still fying NOSIZE, NOSUBSCRIPTRru~GE, NOSTRING-
others are always enabled and cannot be RANGE, NOSTRINGSIZE, or NOCHECK will
disabled. disable the corresponding cop-dition
throughout the scope of that prefix. Since
Those conditions that are always enabled SIZE, STRINGRANGE, and SUBSCRIPTRANGE
unless they have been explicitly disabled represent errors that are likely to prevent
by condition prefixes are: successful execution, the checkout compiler
checks for these conditions, and takes
CONVERSION standard system action, even when they are
disabled, although an on-unit cannot be
FIXEOOVERFLO~ entered while the corresponding condition
is disabled.
OVERFLOW
All other conditions are always enabled
UNDERFLOW and remain so for the duration of the
program. These conditions are:
ZERODIVIDE
AREA KEY
Each of the above conditions can be
disabled by a condition prefix specifying ATTENTION NAME
the condition name preceded by NO without
intervening blanks. Thus, one of the CONDITION PENDING
following names in a condition prefix will
disable the respective condition: ENDFILE RECORD

NOCONVERSION ENDPAGE TRANSMIT

NOFIXEDOVERFLOW ERROR UNDEFINEDFILE

NOOVERFLOW FINISH

NOUNDERFLOW

NOZERODIVIDE Condition Codes (ON-Codes)

Such a condition prefix renders the
corresponding condition disabled throughout The ONCODE built-in fUnction may be used by
the scope of the prefix; the condition the programmer in anyon-unit to determine
remains enabled outside this scope. (Scope the nature of the error or condition that

Section H: ON-conditions 383

caused entry into that on-unit. The codes 44 Uncorrectable transmission error
corresponding to the conditions and errors on input from index set (VSAM).
checked for are given below:
45 Uncorrectable transmission error
Error or Exceptional Condition on output to sequence set (VSAM).

o The ONCODE built-in function has 46 Uncorrectable transmission error

been used outside an on-unit. on input from sequence set (VSAM).

KEY Condition Codes

ERROR Condition Code
50 SIGNAL KEY statement executed.
3 Execution of SIGNAL ERROR
statement in place of statement 51 Key specified cannot be found.
diagnosed as in error.
52 Attempt to add keyed record which
FINISH Condition Codes has same key as a record already
present in data set, or, in a
4 SIGNAL FINISH, STOP, or EXIT REGIONAL (1) data set, attempt to
statement executed. write into a region already
or containing a record.
Main procedure completed normally.
53 Value of expression specified in
ERROR Condition Code KEYFROM option during sequential
creation of INDEXED or REGIONAL
9 SIGNAL ERROR statement executed. data set is less than value of
previously specified key or region
Note: For further ERROR condition number.
codes, see code numbers 1000
onwards. 54 Key conversion error has occurred,
possibly due to region number not
NAME Condition Codes being numeric character.

10 SIGNAL NAME statement executed. 155 Key specified is invalid.

or
unrecognizable identifier in GET 56 Attempt to access a record using a
DATA input stream. key that is outside the data set
limits.
RECORD Condition Codes
57 No space available to add a keyed
20 SIGNAL RECORD statement executed. record.

21 Record variable smaller than 58 Key of record to be added lies

record size. outside the range(s) specified for
the data set.
22 Record variable larger than record
size. ENDFILE Condition code

23 Record variable length is either 70 SIGNAL ENDFILE statement executed.

zero or too short to contain the or
embedded key. Attempt to read past the file
delimiter.
24 Zero length record has been read
from a REGIONAL data set. UNDEFINEDFILE Condition Codes

TRANSMIT Condition Codes 80 SIGNAL UNDEFINEDFILE statement has

been executed.
40 SIGNAL TRANSMIT statement
executed. 81 Conflict in file attributes exists
at open time between attributes in
41 Uncorrectable transmission error DECLARE statement and those in
in output data set. explicit or implicit OPEN
statement.
42 Uncorrectable transmission error
in input data set. 82 Conflict between file attributes
and phySical organization of data
43 Uncorrectable transmission error set, e.g. between file
on output to index set (VSAM). organization and device type.

384 OS PL/I CKT AND OPT LRM PART II

 line number is equal to current
page size.
VSAM data set has not been loaded.

83 After merging ENVIRONMENT options

with DD statement and data set PENDING Condition Code
label, data set specification is
incomplete, e.g. blocksize or 100 SIGNAL PENDING statement executed.
record format has not been Q!:
specified. READ issued for TRANSIENT INPUT
file when message queue empty.
84 No DD statement associating file
with a data set. STRINGSIZE Condition Code

85 During initialization of a DIRECT 150 SIGNAL STRINGSIZE statement

OUTPUT file associated with a executed.
REGIONAL data set, an input/output or
error occurred. Characters have been lost in an
assignment to a character-string
86 Linesize greater than variable or temporary or in an
implementation-defined maximum. input/output operation.
or
Invalid value in an ENVIRONMENT OVERFLOW Condition Code
option.
300 SIGNAL OVERFLOW statement has been
81 After merging ENVIRONMENT options executed.
with DD statement and data set or
label, conflict exists in data set Magnitude of floating-point number
specification, e.g., record format exceeds permitted maximum.
incompatible with block size or
file organization. FIXEDOVERFLOW Condition Code

88 After merging ENVIRONMENT options 310 SIGNAL FIXEDOVERFLOW statement

with DD statement and data set executed.
label, conflict exists in data set or
specification, e.g., record format Length of result of fixed-point
incompatible with block size or arithmetic operation exceeds
file organization. permitted maximum.

89 Password invalid or not specified. ZERODIVIDE Condition Code

91 ENVIRONMENT option invalid for 320 SIGNAL ZERODIVIDE statement

file accessing VSA.M data set. executed.
Q!:
92 Error detected by VSAM while Attempt to divide by zero.
opening a VSAM data set.
or UNDERFLOW Condition Code
During opening of a VSAM data set
with the BKWD option, the attempt 330 SIGNAL UNDERFLOW statement
to poSition the data set at the executed.
last record failed. or
Magnitude of a floating-point
93 Unidentified error detected by the number is smaller than the
operating system while opening a permitted minimum.
data set.
SIZE Condition Code
1
194 REUSE specified for a non-reusable 340 SIGNAL SIZE statement executed.
1 data set. or
1 High-order non-zero digits have
195 Alternate index specified for a been lost in an assignment to a
1 VSAM data set is empty. variable or temporary, or
significant digits have been lost
ENDPAGE Condition Code in an input/output operation.

90 SIGNAL END PAGE statement executed. 341 High order non-zero digits have
or been lost in an input/output
Attempt to start new line when operation.

Section H: ON-conditions 385

STRINGRANGE Condition Code F-format item for a GET STRING
statement.
350 SIGNAL STRINGRANGE statement
executed. 604 Error during processing of an
or F-format item for a GET FILE
Length of the arguments of a statement.
SUBSTR reference failed to comply
with the rules described for the 605 Error during processing of an
SUBSTR built-in fUnction. F-format item for a GET FILE
statement following a TRANSMIT
AREA Condition Codes condition.

360 Attempt to allocate a based 606 Error during processing of an

variable within an area that E-format item for a GET STRING
contains insufficient free storage statement.
for allocation to be made.
601 Error during processing of an
361 Insufficient space in target area E-format item for a GET FILE
for assignment of source area. statement.

362 SIGNAL AREA statement executed. 608 Error during processing of an

E-format item for a GET FILE
ATTENTION Condition Code statement following a TRANSMIT
condition.
1400 SIGNAL ATTENTION statement
executed 609 Error during processing of a
or B-format item for a GET STRING
Attention signaled from terminal. statement.

CONDITION Condition Code 610 Error during processing of a

B-format item for a GET FILE
500 SIGNAL CONDITION (condition) statement.
statement has been executed.
611 Error during processing of a
CHECK Condition Codes B-format item for a GET FILE
statement following TRANSMIT
510 SIGNAL CHECK statement executed. condition.
or
Value of all or part of variable 612 Error during character string to
is about to change, or execution arithmetic conversion.
of labeled or named statement is
about to take place, within scope 613 Error during character string to
of CHECK prefix. arithmetic conversion for a GET or
PUT FILE statement.
SUBSCRIPTRANGE Condition Code
614 Error during character string to
520 SIGNAL SUBSCRIPTRANGE statement arithmetic conversion for a GET or
executed. PUT FILE statement following a
or TRANSMIT condition.
Subscript has been evaluated and
found to lie outside its specified 615 Error during character string to
bounds. bit string conversion.

521 subscript of iSUB-defined variable 616 Error during character string to

lies outside bounds of bit string conversion for a GET or
corresponding dimension of base PUT FILE statement.
variable.
611 Error during character string to
CONVERSION Condition Codes hit string conversion for a GET or
PUT FILE statement following a
600 SIGNAL CONVERSION statement TRANSMIT condition.
executed.
618 Error during character string to
601 Invalid conversion attempted picture conversion.
during input/output of a character
string. 619 Error during character string to
picture conversion for a GET or
603 Error during processing of an PUT FILE statement.

386 OS PL/I CKT AND OPT LRM PART II

 620 Error during character string to statement with an EVENT option,
picture conversion for a GET or and no corresponding WAIT has been
PUT FILE statement following a executed.
TRANSMIT condition.
1014 Attempt to initiate further
621 Error in decimal P-format item for input/output operation when number
a GET STRING statement. of incomplete operations equals
number specified by ENVIRONMENT
622 Error in decimal P-format input option NCP(n) or by default.
for a GET FILE statement.
1015 Event variable has been specified
623 Error in decimal P-format input for an input/output operation when
for a GET FILE statement following already in use.
a TRANSMIT condition.
1016 After UNDEFINEDFILE condition has
624 Error in character P-format input been raised as a result of an
for a GET FILE statement. unsuccessful attempt to implicitly
open a file, the file was found to
625 Error exists in character P-format be unopened on normal return from
input for a GET FILE statement. the on-unit.

626 Error exists in character P-format 1018 End of file or string was
input for a GET FILE statement encountered in data before end of
following a TRANSMIT condition. data-list or (in edit-directed
transmission) format list.
ERROR Condition Codes
1019 Attempt to close file which was
~: For other ERROR conditions, see not opened in current task.
condition codes 3 and 9.
1020 Further input/output attempted
1002 GET or PUT STRING specifies data before WAIT statement executed to
that exceeds size of string. ensure completion of previous
READ.
1003 Further output prevented by
TRANSMIT or KEY conditions having 1021 Attempt to access a record locked
been previously raised for the by another file in this task.
data set.
1022 Insufficient space on direct-
1004 Attempt to use PAGE, LINE, or SKIP access storage for VSAM data set.
S 0 for non-print file.
1023 Exclusive file closed while
1005 In DISPLAY(element-expression) records still locked in a subtask.
REPLY (character-variable)
statement, element-expression or 1024 Incorrect sequence of I/O
character-variable is of zero operations on device-associated
length. file.

1007 A REWRITE or a DELETE statement 1025 Insufficient virtual storage

has not been preceded by a READ. available for VSAM to complete
request. .
1008 Unrecognized identifier in a
string specified in a GET STRING 1026 No position is established in
DATA statement. VSAM data set.

1009 An input/output statement 1021 Record already held in exclusive

specifies an operation or an control.
option which conflicts with the
file attributes. 1028 Requested record lies on
non-mounted volume.
11011 Data management has detected an
I input/output error but is unable 1029 Attempt to reposition in VSAM
I to provide any information about data set failed.
I its cause.
11030 An error has ocurred during
1013 Previous input operation 1 index upgrade on a VSAM data set.
incomplete: REWRITE or DELETE 1
statement specifies data which has 11031 Invalid sequential write attempted
been previously read in by a READ 1 on VSAM data set.

Section H: ON-conditions 387

1500 computational error; short function ~ 1.
floating point argument of SQRT
built-in function is negative. 1516 Computational error; absolute
value of extended floating point
1501 computational error; long floating argument of ATANH built-in
point argument of SQRT built-in function ~ 1.
function is negative.
1517 Computational error in SIN, COS,
1502 computational error; extended SIND, or COSD built-in function;
floating pOint argument of SQRT absolute value of extended
built-in function is negative. floating point argument exceeds
(2**106)*pi (SIN and COS) or
1503 computational error in LOG, LOG2, (2**106)*180 (SIND and COSD).
or LOGI0 built-in function;
extended floating pOint argument 1518 Computational error; absolute
is S o. value of short floating pOint
argument of ASIN or ACOS built-in
1504 computational error in LOG, LOG2, function exceeds 1.
or LOGI0 built-in function; short
floating point argument is S O. 1519 Computational error; absolute
value of long floating pOint
1505 computational error in LOG, LOG2 argument of ASIN or ACOS built-in
or LOGI0 built-in function: long fUnction exceeds 1.
floating point argument is S O.
1520 Computational error; absolute
1506 computational error in SIN, COS, value of extended floating pOint
SIND, or COSD built-in function; argument of ASIN, ACOS built-in
absolute value of short floating fUnction exceeds 1.
point argument exceeds (2**18)*pi
(SIN and COS) or (2**18)*180 (SIND 1521 Computational error; extended
and COSD). floating point arguments of ATAN
or ATAND built-in function both
1507 Computational error in SIN, COS, zero.
SIND, or COSD built-in function;
absolute value of long floating 1522 Computational error; absolute
point argument exceeds (2**50)*pi value of extended floating point
(SIN and COS) or (2**50)*180 (SIND argument of TAN or TAND built-in
and SIND). function ~ (2**106)*pi or
(2**106)*180, respectively.
1508 Computational error; absolute
value of short floating pOint 1550 Computational error; real short
argument of TAN or TAND built-in floating-point base is zero and
functuion exceeds, respectively, fixed-point integer exponent not
(2.*18)*pi or (2**18)*180. positive.
1509 Computational error; absolute 1551 Computational error: real long
value of long floating point floating-point base is zero and
argument of TAN or TAND built-in fixed-point integer exponent not
function exceeds, respectively, positive.
(2*.SO)*pi or (2**50)*180.
1552 Computational error; real short
1510 computational error; short floating point base is zero and
floating point arguments of ATAN the floating-point or non-integral
or ATAND built-in function both exponent is not positive.
zero.
1553 Computational error; real long
1511 Computational error; long floating floating point base is zero and
point arguments of ATAN or ATAND the floating-point or non-integral
built-in function both zero. exponent is not positive.
1514 Computational error; absolute 1554 Computational error; complex short
value of short floating pOint floating point base is zero and
argument of ATANH built-in fixed-point integer exponent is
function ~ 1. not posi ti ve.

1515 Computational error: absolute 1555 Computational error: complex long

value of long floating point floating point base is zero and
argument of ATANH built-in fixed-point integer exponent is

388 OS PL/I CRT AND OPr LRM PART II

 not positive. 300b Picture description of target does
not match non-character-string
1556 computational error; complex short source.
floating point base is zero and
floating-point or non-integral 3008 Checkout compiler only: remote
exponent is not positive and real. format item specifies label not in
current block.
1557 computational error; complex long
floating point base is zero and 3!>00 Checkout compiler only: argument
floating-point or non-integral to HIGH built-in function is less
exponent is not positive and real. than zero.
1558 computational error; complex short 3501 Checkout compiler only: argument
floating point argument of ATAN or to LOW built-in function is less
ATANH built-in function has value, then zero.
respectively, of tlI or tl.
3502 Checkout compiler only: argument
1559 computational error; complex long to BIT built-in function less than
floating point argument of ATAN or zero.
ATANH built-in function has value,
respectively, of tlI or tl. 3503 Checkout compiler only: argument
to CHAR built-in function less
1560 computational error; real extended than zero.
floating-point base is zero and
fixed-point integer exponent not 3798 ONCHAR or ONSOURCE pseUdovariable
positive. used out of context.
1561 computational error: real extended 3799 In an on-unit entered as a result
floating point base is zero and of the CONVERSION condition being
floating-point or non-integral raised by an invalid character in
exponent is not positive. the string being converted, the
character has not been corrected
1562 computational error: complex by use of the ONSOURCE or ONCHAR
extended floating point base is pseudovariables.
zero and integer exponent is not
positive. 3800 Checkout compiler only: length of
data aggregate exceeds system
1563 Computational error: complex limit of 2**24 bytes.
extended floating pOint base is
zero and floating-point or 3801 Checkout compiler only: element
non-integral exponent is not of an array in a structure cannot
positive. be mapped.

1564 computational error: complex 3802 Checkout compiler only: array

extended floating point argument bound is out of valid range.
of ATAN or ATANH built-in function
has value, respectively, of ±11 or 3803 Checkout compiler only: array has
t1. lower bound greater than upper
bound.
2002 WAIT statement cannot be executed
because of restricted system 3804 Checkout compiler only: string
facility. has 1ength greater than permitted
maximum.
3000 Field width, number of fractional
digits, and number of significant 3805 Checkout compiler only: length of
digits (w,d, and s) specified for string less than zero.
E-format item in edit-directed
input/output statement do not 3806 Checkout compiler only: size of
permit transmission without loss area exceeds permitted maximum.
of significant digits or sign.
3807 Checkout compiler only: size.of
3004 Checkout compiler only: A-format area is less than zero.
width unspecified in format list
for GET EDIT statement. 3808 Aggregate cannot be mapped in
COBOL or FORTRAN.
3005 Checkout compiler only: B-format
width unspecified in format list 3901 Attempt to invoke task having name
for GET EDIT statement. variable that is already

Section H: ON-conditions 389

 associated with an active task. area.
3904 Event variable specified as 4052 Checkout compiler only: pOinter
argument to COMPLETION addresses based variable whose
pseudovariable while already in attributes differ from attributes
use for a DISPLAY statement. of variable declared with that
pOinter value.
3906 Assignment to an event variable
that is already active. 4053 Checkout compiler only: reference
to based variable when pOinter
3907 Attempt to associate an event addresses storage that no longer
variable that is already contains the variable.
associated with an active task.
4054 Checkout compiler only: locator
3909 Attempt to create a subtask (using variable refers to a locate mode
CALL statement) when insufficient input/output buffer when buffer is
main storage available. not the latest one or when file is
closed.
3910 Attempt to attach a task (using
CALL statement) when number of 4055 Checkout compiler only: attempt
active tasks was already at limit to assign to an offset variable a
defined by ISASIZE paramter of locator that does not reference
EXEC statement. storage in the appropriate area.
3911 WAIT statement in on-unit 4056 POINTER or OFFSET built-in
specifies that an event already function does not address a valid
being waited for in task from allocation of storage in the
which on-unit was entered. specified area.
3912 Attempt to execute CALL with TASK 4057 Checkout compiler only: locator
option in block invoked while qualifying a based variable refers
executing PUT FILE(SYSPRINT) to storage which has not been
statement. allocated in current task.
3913 CALL statement with TASK option 4058 Checkout compiler only: a based
specifies an unknown entry pOint. structure is referred to by means
of a pointer that is not valid for
3914 Attempt to call FORTRAN or COBOL that structure.
routines in two tasks
simultaneously. 5000 Checkout compiler only: number of
arguments being passed does not
4000 Checkout compiler only: use of match number of parameters.
uninitialized variable as source.
5001 Checkout compiler only:
4001 Checkout compiler only: reference attributes of argument being
to CONTROLLED variable before it passed do not match attributes of
has been allocated. corresponding parameter.
4002 Controlled variable with bound, 5002 Checkout compiler only:
length, or size as * has been attributes of value being returned
specified in an ALLOCATE statement do not match those implied by
when no previous allocation context of function reference.
exists.
5003 Checkout compiler only: attempt
4003 Checkout compiler only: IN option to return a value from a block
of ALLOCATE statement specifies an invoked by a CALL statement.
area not the same as that declared
to be associated with offset 5004 Checkout compiler only: block
variable specified in SET option. invoked as a fUnction without
returning a value.
4050 Checkout compiler only: attempt
to refer to a based variable whose 5005 FORTRAN routine would pass invalid
pointer has the null or other data type.
initial va1ue.
5050 Checkout compiler only: attempt
4051 Checkout compiler only: attempt to use defined variable whose
to free a variable that has no storage extends beyond end of base
valid allocation in its associated variable.

390 OS PL/I CRT AND OPT LRM PART II

 POSITION attribute specifies value
greater than permitted maximum.
Multiple Interrupts
5051 Checkout compiler only: size of
simple defined area greater than
that of base variable. A multiple interrupt is the simultaneous
occurrence of two or more interrupts.
8091 Operation exception.
With processors that do not have
8092 privileged operation exception. imprecise interrupts (for example, all
system/3bO models excluding the Model 91>,
8093 EXECUTE exception. a multiple interrupt can only occur for the
conditions TRANSMIT and RECORD. The
8094 Protection exception. interrupt for TRANSMIT is always processed
first. The interrupt for RECORD will be
8095 Addressing exception. ignored unless there is an on-unit for
TRANSMIT that causes normal return.
8096 specification exception.
In most of the System/370 range,
8091 Data exception. particularly the 155, 158, 165, 168, and
the 195, as well as the System/360 Model
9002 Attempt to execute GO TO 91, the processors have a second type of
statement specifying label in an multiple interrupt, known as an imprecise
inactive block. interrupt, which can occur during parallel
processing. The interrupt may be due to
9003 Checkout compiler only: attempt the raising of a PL/I condition or a
to invoke an entry point ~n a hardware exception which subsequently
procedure compiled by the raises the ERROR condition. The conditions
optimizing compiler when that and exceptions that may cause an imprecise
procedure's containing block is interrupt are shown below, in the order in
inactive. which they are processed.

9004 Checkout compiler only: linkage PL/I on-conditions:

editor cannot find entry constant
on specified data set. 1• UNDERFLOW
2. FIXEDOVERFLOW
9005 Checkout compiler only: attempt 3. SIZE
to use label variable in a GO TO 4. OVERFLOW
statement when value not in label 5. ZERODIVIDE
list.
Hardware interrupts:
9050 Program has been terminated by an
abend. 6. Data exception
1. Specification exception
9051 Attempt to invoke procedure 8. Addressing exception
compiled by the checkout compiler 9. Protection exception
from one compiled by the
optimizing compiler. Event I/O and imprecise interrupts
cannot occur as part of the same multiple
9101 Checkout compiler only: number of interrupt.
lines specified in STEPLINES
compiler option has been Imprecise interrupt conditions are
transmitted. processed successively, until one of the
following occurs, in which case nO
9200 Program check occurred in subsequent conditions are processed.
SORT/MERGE program.
1. The processing of a condition causes
9201 SORT is not supported in CMS. termination of the task, through
either standard system action, normal
9250 Procedure to be fetched cannot be return from an on-unit, or abnormal
found. termination in the on-unit.

9251 Permanent transmission error when 2. Control is transferred out of an on-

fetching a procedure. unit by means of a GO TO statement, so
that a normal return is not allowed to
9252 FETCH/RELEASE is not supported in take place.
eMS.

Section H: ON-conditions 391

List of Conditions 1. computational conditions -- those
conditions associated with data
handling, expression evaluation, and
This section presents conditions in computation. They are:
alphabetical order. In general, the
following information is given for each
condition: CONVERSION
FIXEDOVERFLOW
1. General format -- given only when it OVERFLOW
consists of more than the condition SIZE
name. UNDERFLOW
ZERODIVIDE
2. Description -- a discussion of the
condition, including the circumstances
under which the condition can be 2. Input/output conditions -- those
raised. Note that an enabled conditions associated with data
condition can always be raised by a transmission. They are:
SIGNAL statement; this fact is not
included in the descriptions.
ENDFILE
3. Result -- the result of the operation END PAGE
that caused the condition to occur. KEY
This applies when the condition is NAME
disabled as well as when i t is PENDING
enabled. In some cases, the result is RECORD
not defined; that is, it cannot be TRANSMIT
predicted. This is stated wherever UNDEFINEDFILE
applicable.

4. Standard system action -- the action 3. program-checkout conditions -- those

taken by the system when an interrupt conditions that facilitate the
occurs and the programmer has not debugging of a program. They are:
specified an on-unit to handle that
interrupt. CHECK
SUBSCRIPTRANGE
5. Status -- an indication of the STRINGRANGE
enabled/disabled status of the STRINGSIZE
condition at the start of the program,
and how the condition may be disabled 4. Storage Control condition
(if possible) or enabled.
AREA
6. Normal return the pOint to which
control is returned as a result of the 5. System action conditions -- those
normal termination of the on-unit. A conditions that provide facilities to
GO TO statement that transfers control extend the standard system action that
out of an on-unit is an abnormal on- is taken after the occurrence of a
unit termination. Note that if a condition or at the completion of a
condition (except the ERROR condition> program. They are:
has been raised by the SIGNAL
statement, the normal return is always ERROR
to the statement immediately following FINISH
SIGNAL.
6. programmer-named condition

CONDITION
Classification of Conditions
7. Conversational Processinq Condition

The conditions are classified as follows: ATTENTION

392 OS PL/I CKT AND OPT LRM PART II

 storage Control loption has been specified for the
I compilation. If the option has not been
I specified, signalling attention causes the
Description: The AREA condition is raised I program to be terminated. In
in either of the following circumstances: Ichecker/optimizer mixtures, however, the
IINTERRUPT option can be omitted; an
1. When an attempt is made to allocate a lestablished ATTENTION on-unit will be
based variable within an area that lentered irrespective of whether it is in a
contains insufficient free storage for Ichecker-compiled or an optimizer-compiled
the allocation to be made. I module.

2. When an attempt is made to perform an

area assignment, and the target area In batch processing under the checkout
contains insufficient storage to compiler, a SIGNAL ATTENTION statement
accommodate the allocations in the causes an on-unit to be entered, or, if
source area. there is nO ATTENTION on-unit, causes a
comment to be printed, with no interrupt in
Result: In both cases the attempted the flow of control.
allocation or assignment has no effect.
In batch processing under the optimizing
standard System Action: In the absence of I compiler, a SIGNAL ATTENTION statement
an on-unit, the system prints a message and Icauses an on-unit to be entered. If there
raises the ERROR condition. lis no ATTENTION on-unit, the condition is
leffectively ignored, and there is no
status: AREA is always enabled: it cannot linterruption in the flow of control.
be disabled.
IStandard System Action: Under the checko~
Normal Return: On normal return from the compiler, control is passed to the
on-unit, the action is as follows: terminal. The transfer of control takes
place, in general, at the end of the
1. If the condition was raised by an statement currently being executed. There
allocation, the allocation is are exceptions to this rule if the
reattempted. Before the attempt is statement is a stream input/output
made, the area reference is statement or a compound statement. The
reevaluated. Thus, if the on-unit has exceptions are detailed in OS Time Sharing
changed the value of a pointer Option: PL/I Checkout Compiler.
qualifying the reference to the
inadequate area so that it pOints to Iunder the optimizing compiler, the
another area, the allocation is lattention is effectively ignored.
reattempted within the new area.
I Status: ATTENTION is always enabled; it
2. If the condition was raised by an area cannot be disabled.
assignment, or by a SIGNAL statement,
execution continues at the point of Normal Return: On return from an ATTENTION
interrupt. on-unit, processing is resumed at a pOint
in the program immediately following the
point at which the interrupt occurred.

ATTENTION Conversational Processing

CHECK [(name-list)] program Checkout

Abbreviation: ATTN

Description: The ATTENTION condition is The optional -name list- is one or more
raised when the user signals attention at names separated by commas; a name may be a
the terminal during conversational qualified name. Each name must be one of
I processing. Raising the condition the following:
interrupts processing to enter an ATTENTION
lon-unit, or, for the checkout compiler 1. An entry constant.
only, to pass control to the terminal.
2. A label constant.
The condition can also be raised by a
SIGNAL ATTENTION statement in batch or 3. An unsubscripted variable representing
conversational processing. an element, an array, or a structure,
of any data type. The variable must
I Under the optimizing compiler, an not be iSUB-defined, and must not be
IATTENTION on-unit will be entered when explictly qualified by a locator in
lattention is signaled only if the INTERRUPT the name-list.

Section H: ON-conditions 393

 Under the optimizing compiler, the they were declared, the elements of that
following restrictions apply to based structure or array of structures. For
variables in the name list: example, if P is defined:

a. the variable must not have the DECLARE 1 P, 2 Q, 2 R, 2 S;

OFFSET attribute.
then:
b. the variable must not be a member
of a structure declared with the CHECK (P)
REFER option.
is equivalent to:
c. The pointer on which the variable
is based must not be based, CHECK (P.Q, P.R, P.S)
defined, or a parameter, and i t
must not be a member of an array The CHECK condition is raised within the
or structure. scope of a CHECK prefix in any of the
following cases:
Under the optimizing compiler, defined
variables in the name list must not 1. If a name in the CHECK prefix is a
have been defined: statement label constant, the
condition is raised and the interrupt
a. On a controlled variable. occurs prior to the execution of the
statement to which the label is
b. On an array with one or more prefixed. If the label is prefixed to
adjustable bounds. a FORMAT statement, the condition is
not raised.
c. With a POSITION attribute that
specifies other than a constant. 2. If a name in the CHECK prefix is a
variable (as specified in the general
The names appearing in a CHECK prefix format above), the condition is raised
refer to the names known within the block whenever the value of the variable, or
or statement to whicb the prefix is of any part of the variable, is
attached. Under the optimizing compiler, changed by any statement within the
the maximum number of names that may be scope of the prefix.
specified in the name-list is 255. There
is no limit under the checkout compiler. Specifically, if the identifier ID
represents th~ variable, the condition
oescription: The CHECK condition is raised is raised in the following cases:
only within the scope of a CHECK condition
prefix. Such a condition prefix may be a. ID appears on the left-hand side
prefixed to any statement except a DECLARE, of an assignment statement. (This
DEFAULT or ENTRY statement. The CHECK applies to BY NAME aSSignment only
condition is enabled separately for each if the name mentioned changes its
name in the list of the CHECK prefix. For value.)
example, the prefix (CHECK (A,B,C»: is
equivalent to (CHECK (A»: (CHECK (B»: b. 10 is set as a result of a
(CHECK (C»:. Hence, the action pseudovariable appearing on the
specification can be controlled separately left-hand side of an assignment
for each name. Alternatively, if no name statement.
list is given, the condition is enabled for
each variable, entry constant, and label c. 10 appears as the control variable
constant within the scope of the CHECK ot a DO-group or a repetitive
prefix. Under the checkout compiler, a specification in a data list (or
label on the same statement as a CHECK it is set as a result of a
prefix is not included in the scope of the pseudovariable appearing as the
prefix, but is included under the control variable of a DO-group or
optimizing compiler. a repetitive specification in a
data list).
The REVERT statement can be used to
change the action specification for one or d. ID appears in the data list of an
more names in the list. Also, a NOCHECK edit-directed or list-directed GET
prefix can be used to disable the CHECK statement.
condition for specific names.
e. ID is altered by data-directed
If the name of a structure or array of input.
structures appears in the name list
following CHECK, such a list is equivalent f. 10 appears in the REPLY option of
to one that contains, in the order in which a DISPLAY statement.

394 OS PL/I CKT AND OPT LRM PART II

g. ID appears in the STRING option of If a statement causes a CHECK
a PUT statement. condition to be raised for several
names, the conditions will be raised
h. ID is passed as an argument to a in the left-to-right order of
programmer-defined procedure, no appearance of the names.
dummy argument is created, the
procedure terminates with a RETURN 3. If an identifier in the CHECK prefix
or END, and the procedure is not name list is an entry constant, the
invoked with the TASK, PRIORITY, condition is raised and the interrupt
or EVENT option. occurs prior to each invocation of the
entry point corresponding to the entry
i. ID appears in the KEYTO or INTO constant. The condition is raised
option of a READ statement. Note only if the entry point is invoked by
that if the READ statement has an the entry constant given in the
EVENT option, the CHECK condition prefix.
will not be raised.
Result: When CHECK is raised, there is no
j. 10 is a locator variable and effect on the statement being executed.
appears in a SET option or is set
implicitly. Standard System Action: In the absence of
a CHECK on-unit, the output consists of the
k. ID is a non-static variable set by current statement number together with the
the INITIAL attribute. data shown in tigure H.l.
In a, b, d, and ~ above, if 10 is a
data aggregate, the CHECK condition is
r-----------------------------------------,
Variable or I Checkout I Optimizing I
raised and the ipterrupt occurs each Constant 1Compiler 'Compiler ,
time an element of that aggregate is
given a value. If 10 is an element of
-----------------------------------------1
Arithmetic or 1 Name and Value ,
a data aggregate, the condition is string variable I I
raised for that element only, not the
whole array.
-----------------------------------------11
Area, file, entry I 1
event, label, lAs for PUT I Name ,
The condition is not raised under any locator or task I DATA 1 I
of the following circumstances: variable I 1 I
Entry or l a b e l , I I
a. If the value of a variable defined constant 1 1 I
on ID or on part of 10 changes in
any of the ways described above.
L-----------------------------------------J
Figure H.l. Output for CHECK condition
b. If the parameter that represents
the argument 10 changes value. If SIGNAL CHECK without a name-list is
given, in the absence of a CHECK on-unit,
c. If 10 appears in a GO TO or RETURN within the scope of a CHECK prefix that is
statement or any statement that also without a name list, all problem data
involves the execution of a GO TO identifiers within the scope of the prefix
or RETURN statement. are printed, together with their values.
In addition, under the checker the names
Note that in all of the above and values ot all internal program control
contexts, 10 can appear in subscripted variables and the names of all external
or qualifi~d form. Note also that 10 program control variables within the scope
need not appear in the name list of a of the prefix are printed.
CHECK prefix; it only need represent a
structure or element contained by, or Note: Standard system action for the CHECK
containing, a name in the list. condition requires access to the variable:
consequently, if SIGNAL CHECK is given for
The interrupt for a CHECK condition an unallocated variable, an error will
occurs immediately after the result, as it would if the variable were
assignment to 10, except in case h. accessed by an on-unit. Under the checker,
Then it occurs immediately after a comment will be printed and execution
execution of the subroutine's RETURN continued if the variable has the INTERNAL
or END statement. In a 00 statement, attribute; variables with the EXTERNAL
the interrupt occurs each time control attribute or any variable under the
proceeds sequentially to the statement optimizer will raise ERROR.
following the 00 statement. If the DO
specifies repetitive execution, the Status: CHECK is disabled by default and
interrUpt occurs each time the control within the scope of a NOCBECK condition
variable changes value. prefix. It is enabled only within the

Section B: ON-conditions 395

scope of a CHECK prefix. PICTURE specification, or when a string
being converted to coded arithmetic data
For other details of the enabling and does not contain the character
disabling of the CHECK condition, see representation of an arithmetic constant.
chapter 14, -Execution-Time Facilities of
the Checkout Compiler-. All conversions of character-string data
are carried out character-by-character in a
Normal Return: Upon the normal completion left-to-right sequence and the condition
of the on-unit for the CHECK condition, occurs for each invalid character. The
execution continues immediately following condition is also raised if all the
the point at which the interrupt occurred. characters in the string are blank. When
an invalid character is encountered, an
interrupt occurs (provided, of course, that
CONVERSION has not been disabled) and the
CONDITION (name) programmer-Named current action specification for the
condition is executed. If the action
specification is an on-unit, the invalid
Abbreviation: COND(name) character can be corrected within the unit
by using the ONSOURCE or ONCHAR
The Rname R must be specified by the pseudovariables. When one of these
programmer. The appearance of an pseudovariables has been used, the
identifier with CONDITION in an ON, SIGNAL, conversion is retried on return from the
or REVERT statement constitutes a on-unit. If the error has not been
contextual declaration for it: the corrected the program will loop. If these
identifier is given the EXTERNAL attribute. pseudovariables have not been used the
ERROR condition is raised.
An identifier may also be declared
explicitly as a condition name by means of Result: When CONVERSION occurs, the
the CONDITION attribute. contents of the entire result field are
undefined.
Description: CONDITION is raised by a
SIGNAL statement that specifies the standard System Action: In thc absence of
appropriate identifier. The identifier an on-unit, the system prints a message and
specified in the SIGNAL statement raises the ERROR condition.
determines which CONDITION condition is to
be raised. status: CONVERSION is enabled throughout
the program, except within the scope of a
Standard system Action: In the absence of condition prefix specifying NOCONVERSION.
an on-unit for this condition, the system
prints a message and continues with the Normal Return: Upon the normal termination
statement following SIGNAL. of the on-unit for this condition, control
returns to the beginning of the string and
Status: CONDITION is always enabled; i t the conversion is retried.
cannot be disabled.

Normal Return: Upon the normal completion

of the on-unit, execution continues with ENDFILE (element-file-'expr) Input/output
the statement following the SIGNAL
statement that caused the interrupt.
Description: The ENDFILE condition can be
raised during a GET or READ operation; it
is caused by an attempt to read past the
CONVERSION Computational file delimiter of the file named in the GET
or READ statement. It applies only to
SEQUENTIAL INPUT, SEQUENTIAL UPDATE and
Abbreviation: CONV STREAM INPUT files.

Description: The CONVERSION condition In record-oriented I/O, ENDFILE is

occurs whenever an invalid conversion is raised whenever a file delimiter is
attempted on character-string data. This encountered during the execution of a READ
attempt may be made internally or during an statement.
input/output operation. For example, the
condition occurs when a character other In stream-oriented I/O, ENDFILE is
than 0 or 1 exists in a character string raised during the execution of a GET
being converted to a bit string; other statement" if a file delimiter is
examples are when a character string being encountered either before any items in the
converted to a numeric character field GET statement data list have been
contains characters not permitted by the transmitted or between transmission of two

396 OS PL/I CRT AND OPT LRM PART II

of the data items. If a file delimiter is ENDPAGE is raised only once per page,
encountered within a data item, or if it is except when i t is raised by the SIGNAL
encountered while an X format item is being statement. If the on-unit does not start a
implemented, the ERROR condition is raised. new page, the current line number may
increase indefinitely. If a subsequent
LINE option or LINE format item specifies a
If the file is not closed after ENDFILE line number that is less than or equal to
occurs, then any subsequent GET or READ the current line number, ENDPAGE is not
statement for that file immediately raises raised, but a new page is started with the
the ENDFILE condition again. current line set to 1. An exception is
that if the current line number is equal to
If ENDFILE is raised by an input/output the specified line number, and the file is
statement using the EVENT option, the positioned on column 1 of the line, ENDPAGE
interrupt does not take place until the is not raised.
execution of a subsequent WAIT statement
for that event in the same procedure. If ENDPAGE is raised during data
transmission, then, on return from the on-
standard System Action: In the absence of unit, the data is written on the current
an on-unit, the system prints a message and line, which may have been changed by the
raises the ERROR condition. .on-unit. If ENDPAGE results from a LINE or
SKIP option, then, on return from the on-
status: The ENDFILE condition is always unit, the action specified by LINE or SKIP
enabled: it cannot be disabled. is ignored.

Normal Return: Upon the normal termination If a SIGNAL statement is used to raise
of the on-unit for the condition, execution ENDPAGE, this condition can also occur
continues with the statement immediately during output of the page.
following the GET or READ statement that
caused the ENDFILE (or, if ENDFILE was standard system Action: In the absence of
raised by a READ with the EVENT option, an on-unit, the system starts a new page.
control passes back to the WAIT statement If the condition is si9naled, execution is
from which the on-unit was invoked). unaffected and continues with the statement
following the SIGNAL statement.
Note: If a file is closed in an on-unit
for this condition, the results of normal Status: ENDPAGE is always enabled: it
return are undefined. Exit from such an cannot be disabled.
on-unit should be by means of a GO TO
statement. Normal Return: Upon the normal completion
of the on-unit for this condition,
execution of the PUT statement continues in
the manner described above.
ENDPAGE (element-file-expr) -Input/Output

Description: The ENDPAGE condition is system Action

raised when a PUT statement results in an
attempt to start a new line beyond the
limit specified for the current page. This Description: The ERROR condition is raised
limit can be specified by the PAGESIZE under the following circumstances:
option in an OPEN statement; if PAGESIZE
has not been specified, a default limit of 1. As a result of the standard system
60 is applied. The attempt to exceed the action for an ON-condition for which
limit may be made during data transmission that action is to "print an error
(including associated format items, if the message and raise the ERROR
PUT statement is edit-directed), by the condition".
LINE option, or by th~ SKIP option.
ENDPAGE can also be raised by a LINE option 2. As a result of an error (for which
or LINE format item that specified a line there is no ON-condition) occurring
number less than the current line number. during program execution.

When ENDPAGE is raised, the current line 3. As a result of a SIGNAL ERROR

number is one greater than that specified statement.
by the PAGESIZE option (or 61, if the
default applies) so that it is possible to Standard system Action: This depends on
continue writing on the same page. The On- the processing mode:
unit may start a new page by execution of a
PAGE option or a PAGE format item, which Batch processing (optimizing or checkout
sets the current line to 1. compiler): If the condition is raised

Section H: ON-conditions 397

 in the major task, the FINISH condition at which the condition was raised.
is raised and the task is terminated.
If the condition is raised in any other
task, the task is terminated. Conversational processing (checkout
compiler only): Control is passed to
Conversational processing (checkout the terminal. processing that is then
compiler only): Control is passed to initiat.c:d at the terminal takes place as
the terminal. processing that is then if it were in a FINISH on-unit, and
initiated at the terminal takes place as completion of that processing (other
if it were in an ERROR on-unit, and than by a GO TO statement out of the on-
completion of this processing (other unit) constitutes a normal return from
than by a GO TO statement out of the on- the on-unit.
unit) constitutes a return from the on-
unit. Status: FINISH is always enabled: it
cannot be disabled.
status: ERROR is always enabled; it cannot
be disabled. Normal Return: Upon the normal completion
of the on-unit, execution of the
Normal Return: With certain exceptions, interrupted statement is resumed.
this depends on the processing mode:

Batch processing (optimizing or checkout

compiler): The standard system action FIXEDOVERFLOW Computational
for batch processing mode is taken.

Conversational processing (checkout Abbreviation: FOFL

compiler only): The FINISH condition is
raised. Description: The FIXEDOVERFLOW condition
occurs when the length of the result of a
The exceptional cases occur under the fixed-point arithmetic operation exceeds
checkout compiler when a SIGNAL ERROR the maximum length allowed by the
statement is executed in place of a implementation. This maximum is 15 for
statement in which the compiler has found decimal fixed-point values and 31 for
an error. In these cases, normal return is binary fixed-point values.
to the statement following the one in which
ERROR was signaled. The cases are Result: The result of the invalid fixed-
characterized by an oncode of 3. point operation is undefined.

Standard System Action: In the absence of

an on-unit, the system prints a message and
FINISH system Action raises the ERROR condition.

Status: FIXEDOVERFLOW is enabled

Description: The FINISH condition is throughout the program, except within the
raised during execution of a statement scope of a condition prefix that specifies
which would cause the termination of the NOFIXEDOVERFLOW.
major task of a PL/I program, that is, by a
STOP statement in any task, or an EXIT Normal Return: Upon normal termination of
statement in the major task, or a RETURN or the on-unit for this condition, control
END statement in the initial procedure of returns to the point immediately following
the major task. The condition is also the pOint of interrupt.
raised by SIGNAL FINISH in any task, and as
part of the standard system action for the Note: If the SIZE condition is disabled,
ERROR condition. The interrupt occurs in an attempt to assign an oversize number to
the task in which the statement is a fixed decimal variable may raise the
executed, and anyon-unit specified for the FIXEDOVERFLOW condition.
condition is executed as part of that task.
An abnormal return from the on-unit will
avoid any subsequent task termination
processes and permit the interrupted task KEY (element-file-expr) Input/Output
to continue.

standard system Action: This depends on Description: The KEY condition can be
the processing mode: raised only during operations on keyed
records. It is raised in any of the
Batch processing (optimizing or checkout following cases:
compiler): No action is taken; that is,
proceSSing is continued from the point 1. The keyed record cannot be found.

398 OS PL/I CKT AND OPT LRM PART II

 2. An attempt is made to add a duplicate return are undefined. Exit from such an
key. on-unit should be by means of a GO TO
statement.
3. The key is out of saquence.

4. An error occurred in the conversion of

the key.
NAME (element-file-expr) Input/Output
5. The key has a null string or begins
with the dummy record string (8)'1'B;
or, for a VSAM ESDS, the key is not a Description: The NAME condition can be
valid relative byte address raised only during a data-directed GET
statement with the FILE option. It is
6. No space is available to add the keyed raised in any of the to1lowing situations
record. where an unrecognizable element variable
appears in the stream:
1. The key is outside the data set limits
(regional data sets only). 1. There is an invalid character in thc
variable:
8. The key of a record to be added lies
outside the range(s) specified for the A non-blank delimiter (comma,
data set. (This case applies only to semicolon, or end-of-file mark) on
VSAM key-sequenced data sets.) left hand side of equals sign.

Note: When a LOCATE statement is used A non-blank character between the

for a VSAM key-sequenced data set, the right parenthesis and the equal sign
KEY condition for this LOCATE
statement is not raised until A subscript character is not a digit
transmission of the record is
attempted; that is, at the next WRITE 2. There is an invalid blank in the
or LOCATE statement for the file, or variable:
when the file is closed.
Within the name or a subscript value.
If KEY is raised by an input/output (Note: Blanks are permitted on either
statement using the EVENT option, the side of the period in a qualified
interrupt does not occur until the name, or between a sign and a digit in
execution of a subsequent WAIT statement a subscript)
for that event in the same procedure.
3. The name is missing or invalid:
When a LOCATE statement is used for a
REGIONAL(3) data set with V-format or U- No counterpart in the data list
format records, and there is not enough
room in the specified region, the KEY If there is no data list, the name is
condition is not raised until transmission not known in the block
of the record is attempted. Neither the
record that causes the condition to be Qualified name is not fully qualified
raised nor the current record is
transmitted. More than 256 characters for a fully
qualified name
standard System Action: In the absence of
an on-unit, the system prints a message and The name is iSUB-defined
raises the ERROR condition.
4. A subscript list is missing or
Status: KEY is always enabled; it cannot invalid:
be disabled.
A subscript is missing
Normal Return: Upon the normal completion
of the on-unit for this condition, control Incorrect number of subscripts
passes to the statement immediately
following the statement that caused KEY to More than five digits in a subscript
be raised (or, if KEY was raised by an (leading zeros ignored)
input/output statement with the EVENT
option, control passes back to the WAIT A subscript is beyond the permitted
statement from which the on-unit was range
invoked) •
The programmer may retrieve the
Note: If a file is closed in an on-unit incorrect data field by using the built-in
for this condition, the results of normal fUnction DATAFIELD in the on-unit.

Section H: ON-conditions 399

standard system Action: In the absence of returns to the point of interrupt (unless
an o~-unit, the system ignores the the condition was Signaled), where
incorrect data field, prints a message, and execution is suspended until an appropriate
continues the execution of the GET record becomes available. If the condition
statement. was Signaled, execution continues with the
statement immediately following the SIGNAL
status: NAME is always enabled; it cannot statement that caused the interrupt.
be disabled.

Normal Return: Upon the normal completion Note: The value of the ONKEY Duilt-in
of the on-unit for this condition, the fUnCtion when the PENDING condition is
execution of the GET statement continues raised is a null string.
with the next identifier in the stream.

RECORD (element-file-expr) Input/Output

OVERFLOW computational

Description: The RECORD condition can be

Abbreviation: OFL raised only during a READ, WRITE, LOCATE,
or REWRITE operation. It is raised by any
Description: The OVERFLOW condition occurs of the following:
when the magnitude of a floating-point
number exceeds the permitted maximum. The 1. When the record length specified for a
magnitude of a floating-point number or file with fixed-length records is
intermediate result must not be greater smaller than the variable in a READ
than approximately 10 75 or 2252. INTO statement; the remainder of the
variable is undefined. If the
Result: The value of such an invalid variable is a varying-length string,
floating-point number is undefined. RECORD is not raised if the
SCALARVARYING option is applied to the
standard system Action: In the absence of file.
an on-unit, the system prints a message and
raises the ERROR condition. 2. When the record is larger than the
variable in a READ INTO statement; the
status: OVERFLOW is enabled throughout the remainder of the record is lost.
program, except within the scope of a
condition prefix specifying NOOVERFLOW. 3. When the maximum record length is
smaller than the variable in a WRITE,
Normal Return: Upon normal termination of REWRITE, or LOCATE statement. For
the on-unit for this condition, control WRITE or REWRITE, the remainder of the
returns to the point immediately following variable is lost; for LOCATE, the
the point of interrupt. variable is not transmitted.

4. When the record length specified for a

file with fixed-length records is
PENDING (element-file-expr) Input/Output larger than the variable in a WRITE,
REWRITE, or LOCATE statement; the
remainder of the record is undefined.
Description: Except when signaled, the If the variable is a varying-length
PENDING condition can be raised only during string, RECORD is not raised if the
execution of a READ statement for a SCALARVARYING option is applied to the
TRANSIENT INPUT file. It is raised when an file.
attempt is made to read a record that is
temporarily unavailable (i.e., when the 5. When the variable in a WRITE or
message queue associated with the file REWRITE statement indicates a zero
contains no messages at the time the READ length; no transmission occurs. If
statement is executed). the variable is a varying-length
string, RECORD is not raised if the
Standard System Action: In the absence of SCALARVARYING option is applied to the
an on-unit, the action is as described for file.
normal return.
6. When the variable in a WRITE or
status: PENDING is always enabled; it REWRITE statement is too short to
cannot be disabled. contain the data set embedded key; no
transmission occurs. (This case
Normal Return: Upon the normal completion currently applies only to VSAM key-
of the on-unit for this condition, control sequenced data sets.)

400 OS PL/I CKT AND OPT LRM PART II

 If the SCALARVARYING option is applied calculated fixed-point value exceeds the
to the file (it must be applied to a file maximum allowed by the implementation (see
using locate mode to transmit varying- the description of the FIXEDOVERFLOW
length strings), a 2-byte length prefix is condition), SIZE occurs when the size of
transmitted with an element varying-length the value being assigned to a data item
string. The length prefix is not reset if exceeds the declared (or default) size of
the RECORD condition is raised. If the the data item. SIZE can be raised on
SCALARVARYING option is not applied to the assignment of a value regardless of whether
file, the length prefix is not transmitted: or not FlXEDOVERFLOW was raised in the
on input, the current length of a varying- calculation of that value.
length string is set to the shorter of the
record length and the maximum length of the The declared size is not necessarily the
string. actual precision with which the item is
held in storage; however, the limit for
If RECORD is raised by an input/output SIZE is the declared or default size, not
statement using the EVENT option, the the actual size in storage. For example, a
interrupt does not occur until the fixed binary item of precision (20) will
execution of a subsequent WAIT statement occupy a full word in storage, but SIZE is
for that event in the same proc~dure. raised if a value whose size exceeds FIXED
BINARY(20) is assigned to it.
The RECORD condition is not raised for
undefined-length records read from: Result: The contents of the data item
receiving the wrong-sized value are
A CONSECUTIVE data set to a SEQUENTIAL undefined.
UNBUFFERED file
standard system Action: In the absence of
A REGIONAL(3) data set to a DIRECT file an on-unit, the system prints a message and
raises the ERROR condition.
Standard System Action: In the absence of
an on-unit, the system prints a message and status: SIZE is disabled within the scope
raises the ERROR condition. of a NOSIZE condition prefix and elsewhere
throughout the program, except within the
Status: RECORD is always enabled; it scope of a condition prefix specifying
cannot be disabled. SIZE. Under the checkout compiler, the
standard system action takes place for SIZE
Normal Return: Upon normal completion of under the circumstances given under
the on-unit, execution continues with the -Description" above, even when the
statement immediately following the one for condition is disabled; no on-unit for this
which RECORD occurred (or if RECORD was condition can be entered, however, while it
raised by an input/output statement with an is disabled.
EVENT option, control returns to the WAIT
statement from which the on-unit was Normal Return: Upon normal termination of
invoked) • the on-unit for this condition, control
returns to the point immediately following
Note: If a file is closed'in an on-unit the point of interrupt.
for this condition, the results of normal
return are undefined. Exit from such an
on-unit should be by means of a GO TO
statement. STRINGRANGE Program-Checkout

Abbreviation: STRG
Computational
Definition: The STRINGRANGE condition is
raised whenever the lengths of the
Description: The SIZE condition occurs arguments to a SUBSTR reference fail to
only when high-order (i.e., leftmost) comply with the rules described for the
significant binary or decimal digits are SUBSTR built-in function. It is raised for
lost in an assignment to a variable or an each such reference.
intermediate result or in an input/output
operation. This loss may result from a Standard System Action: A message is
conversion involving different data types, printed and processing continues as
different bases, different scales, or described for normal return.
different precisions.
status: STRINGRANGE is disabled by default
The SIZE condition differs from the and within the scope of a NOSTRINGRANGE
FlXEDOVERFLOW condition in that, whereas condition prefix. It is enabled only
FIXEDOVERFLOW occurs when the size of a within the scope of a STRINGRANGE condition

Section H: ON-conditions 401

prefix. Under the checkout compiler, the status: STRINGSIZE is disabled by default
standard system action takes place for and within the scope of a NOSTRINGSIZE
STRINGRANGE under the circumstances given condition prefix. It is enabled only
under "Definition" above, even when the within the range of a STRINGSIZE condition
condition is disabled; no on-unit for this prefix.
condition can be entered, however, while it
is disabled. Normal Return: On normal return from the
on-unit, execution continues from the point
Normal Return: On normal return from the of interruption.
on-unit, execution continues with a revised
SUBSTR reference whose value is defined as
follows:
SUBSCRIPTRANGE Program-checkout
Assuming that the length of the source
string (after execution of the on-unit, if
specified) is k, the starting point is i, Abbreviation: SUBRG
and the length of the substring is j;
Description: SUBSCRIPTRANGE can be raised
1. If i is greater than k the value is whenever a subscript is evaluated and found
the null string. to lie outside its specified bounds. The
condition is also raised when an iSUB
2. If i is less than or equal to k, the subscript is outside the range given in the
value is that substring beginning at declaration of the iSUB defined array. The
the ~h character or bit of the source order of raising SUBSCRIPTRANGE relative to
string and extending g characters or evaluation ot other subscripts is
bits, where ~ and ~ are defined by: undefined.

m=MAX(i,l) Result: When SUBSCRIPTRANGE has been

raised, the value of the illegal subscript
n=MAX(O,MIN(j+MIN(i,l)-l,k-m+l» is undefined, and, hence, the reference is
lif j is specified] also undefined.

n=k-m+l Standard System Action: In the absence of

[if j is not specified] an on-unit, the system prints a message and
raises the ERROR condition.
This means that the new arguments are
forced within the limits. Status: SUBSCRIPTRANGE is disabled by
default and within the scope of a
The values of i and j are established NOSUBSCRIPTRANGE condition prefix. It is
bef'ore entry to the on-unit; they are not enabled only within the scope of a
reevaluated on return from the on-unit. SUBSCRIPTRANGE condition prefix. Under the
checkout compiler, the standard system
The value of k may change in the on-unit action takes place for SUBSCRIPTRANGE under
if the first argument of SUBSTR is a the circumstances given under "Description"
varying-length string. The value !l is above, even when the condition is disabled;
computed on return from the on-unit using no on-unit for this condition can be
any new value of k. entered, however, while it is disabled.

Normal Return: Normal return from a

SUBSCRIPTRANGE on-unit raises the ERROR
STRINGSIZE program-Checkout condition.

Abbreviation: STRZ
TRANSMIT (element-file-expr) Input/Output
Definition: The STRINGSIZE condition is
raised when a string is about to be
assigned to a shorter string. Description: The TRANSMIT condition can be
raised during any input/output operation.
Result: After the interrupt, the truncated It is raised by a permanent transmission
string is assigned to its target string. error and therefore signifies that any data
The right hand characters or bits of the transmitted is potentially incorrect.
source string are truncated so that the
target string can accomodate the source During input, TRANSMIT is raised after
string. assignment of the potentially incorrect
record. If records are blocked, TRANSMIT
standard System Action: A message is is raised for each subsequent record in the
printed and processing continues. block. During output, TRANSMIT is raised

402 OS PL/I CKT AND OPT LRM PART II

after transmission of the potentially order of appearance (taken from left to
incorrect data item has been attempted. right) of the file names in that OPEN
statement.
If records are blocked, transmission
will occur when the block is complete,
rather than after each I/O statement If the condition is raised by an
implicit file opening in an input/output
When a spanned record is being updated, statement without the EVENT option, then,
the TRANSMIT condition is raised on the upon normal return from the on-unit,
last segment of a record only. It is not processing continues with the remainder of
raised for any subsequent records in the the interrupted input/output statement. If
same block, although the integrity of these the file was not opened in the on-unit,
records cannot be assumed. then the statement cannot be continued and
the ERROR condition is raised.
If TRANSMIT is raised by an input/output
statement using the EVENT option, the
interrupt does not take place until the If the condition is raised by an
execution of a subsequent WAIT statement implicit file opening in an input/output
for that event in the same procedure. statement having an EVENT option, then the
interrupt occurs before the event variable
Standard System Action: In the absence of is initialized. In other wordS, the event
an on-unit, the system prints a message and variable retains its previous value and
raises the ERROR condition. remains inactive. On normal return from
the on-unit, the event variable is
status: TRANSMIT is always enabled; it initialized, that is, it is made active and
cannot be disabled. its completion value is set to loeB
(provided the file has been opened in the
Normal Return: Upon the normal completion on-unit). Processing then continues with
of the on-unit, processing continues as the remainder of the interrupted statement.
though no error had occurred, allowing However, if the file has not been opened in
another condition (e.g., RECORD) to be the on-unit, the event variable remains
raised by the statement or data item that uninitialized, the statement cannot be
raised the TRANSMIT condition. (If continued, and the ERROR condition is
TRANSMIT is raised by an input/output raised.
statement with an EVENT option, control
returns to the WAIT statement from which
the on-unit was invoked.) Some cases for which the UNDEFINEDFILE
condition is raised are as follows:
Note: If a file is closed in an on-unit
for this condition, the results of normal
return are undefined. Exit from such an 1. A conflict in attributes exists.
on-unit should be by means of a GO TO
statement
2. The blocksize has not been specified.

3. There is no recognizable DD statement

UNDEFINEDFILE (element-file-expr) for the file.
Input/Output
4. The TOTAL option of the environment
Abbreviation: UNDF(element-file-expr) attribute has been specified and
either attributes have been added on
Description: The UNDEFINEDFILE condition an OPEN statement or attributes
is raised whenever an attempt to open a implied by an I/O statement conflict
file is unsuccessful. If the attempt is with default attributes.
made by means of an OPEN statement that
specifies more than one file name, then the Standard System Action: In the abe ence of
condition is raised as follows: an on-unit, the system prints a message and
raises the ERROR condition.
Checkout compiler: After an attempt
to open each file status: UNDEFINEDFILE is always enabled;
i t cannot be disabled.
Optimizing compiler: After attempts
to open all the other files specified Normal Return: Upon the normal completion
in the statement of the final on-unit, control is given to
the statement immediately following the
If the condition is raised for more than statement that caused the condition to be
one file in the same OPEN statement, on- raised (see -Description- for action in the
units will be executed according to the case of an implicit opening).

Section H: ON-conditions 403

UNDERFLOW Computational the on-unit for this condition, control
returns to the point immediately following
the point of interrupt.
Abbreviation: UFL

Description: The UNDERFLOW condition

occurs when the magnitud.e. of a floating- ZERODIVIDE Computational
point number is smaller than the permitted
minimum. (For System/360 and System/370
implementations, the magnitude of a non- Abbreviation: ZDIV
zero floating-point value may not be less
than approximately 10- 78 or 2- 26 °.) Description: The ZERODIVIDE condition
occurs when an attempt is made to divide by
UNDERFLOW does not occur when equal zero. This condition is raised for fixed-
numbers are subtracted (often called pOint and f1oating-point division. The
significance error). optimizing compiler may also raise this
condition, instead of FIXEDOVERFLOW, when
Note that the expression X**(-Y) (where the result of a conversion from decimal to
Y>O) can be evaluated by taking the binary exceeds the maximum length a1lowed
reciprocal of X**Y; hence, the OVERFLOW by the implementation, that is, 31.
condition may be raised instead of the
UNDERFLOW condition. Result: The result of a division by zero
is undefined.
Result: The invalid floating-point value
is set to o. standard System Action: In the absence of
an on-unit, the system prints a message and
standard System Action: In the absence of raises the ERROR condition.
an on-unit, the system prints a message and
continues execution from the point at which status: ZERODIVIDE is enabled throughout
the interrupt occurred. the program, except within the scope of a
condition prefix specifying NOZERODIVIDE.
status: UNDERFLOW is enabled thrOughout
the program, except within the scope of a Normal Return: Upon normal termination of
condition prefix specifying NOUNDERFLOW. the on-unit for this condition, control
returns to the point immediately following
Normal Return: Upon normal termination of the pOint of interrupt.

404 OS PL/I CKT AND OPr LRM PART II

 Section I: Attributes

This section gives detailed descriptions of The ALXGNED and UNALIGNED attributes
all attributes in alphabetical order. .specify the pOSitioning of data elements in
Alternative attributes are discussed storage, to influence speed of access or
together. storage economy respectively. They may be
specified for element, array, or structure
Figure 1.1 has been compiled from the variables.
individual rules for attributes and is
intended to serve as a quick reference to ALIGNED specifies that the data element
the following: is to be aligned on the storage boundary
corresponding to its data type requirement.
1. The classification of attributes
according to data type. UNALIGNED specifies that a bit string is
to be mapped on the next available bit
2. The valid combinations of attributes bo~ndary, and that a halfword, a word, or
that may be applied to a data item. doubleword item is to be mapped on the next
For a variable, attributes must be available byte boundary.
selected from the columns Data
Attributes, Scope Attributes, Storage General format:
Attributes, and Alignment Attributes.
For the types of constants shown in ALIGNED I UNALIGNED
the table, attributes must be selected
from columns Data Attributes and Scope General rules:
Attributes. Note that a complete set
of attributes for a data item may be 1. Although they are essentially element
obtained by explicit or contextual data attributes, ALIGNED and UNALIGNED
declaration and programmer-defined or can be applied to any array or
standard defaults. structure. This is equivalent to
applying the attribute to all
3. Those attributes that conflict. contained elements that are not
Attributes shown as applying to one explicitly declared with the ALIGNED
data type conflict with those of any or UNALIGNED attribute.
other data type, except for those
attributes shown as applying to both 2. Application of either attribute to a
types. Alternative attributes within contained array or structure overrides
a data type, e.g., BIT and CHARACTER, an ALXGNED or UNALIGNED attribute that
are conflicting. otherwise would apply to elements of
the contained aggregate by having been
The following example illustrates the specified for the containing
function of the figure: structure.
DECLARE ST BIT(10); 3. The LIKE attribute is expanded before
the ALIGNED and UNALIGNED attributes
Given the above declaration, the standard are applied to the contained elements
default attributes, AUTOMATIC, INTERNAL, of the LIKE structure variable. The
and UNALIGNED will be applied to the name only ALIGNED and UNALIGNED attributes
ST. that are carried over from the LIKE
structure variable are those
Figure 1.2 is an expansion of the entry explicitly specified for substructures
for file constants in figure 1.1, to and elements of the structure
include the relationships between file variable.
attributes and options of the ENVIRONMENT
attribute for the different data set 4. For overlay defining involving bit-
organizations. The figure also shows the and character-class data, both the
attribute implications of each file defined item and the overlaid part of
attribute. the base item must be UNALIGNED. For
all other types of defining,
equivalent i~ems must be either both
ALIGNED or both UNALIGNED.
ALIGNED and UNALIGNED
5. The ALIGNED and UNALIGNED attributes
of an argument actually passed must
Abbreviation: UNAL for UNALIGNED match the attributes of the

Section X: Attributes 405

DATA TYPE DATA ATTRIBUTES SCOPE ATTRIBUTES STORAGE ATTRIBUTES ALIGNMENT
ATTRIBUTES
Arithmetic REAL ICOMPLEX
variable 1 FLOAT I FIXED {ALIGNED}
BINARY I DECIMAL {UNALIGNED}
(precision)
String BIT I CHARACTER
variable [ (length) ] {INTERNAL}
[VARYING] {EXTERNAL} {ALIGNED }
Storage Class: {UNALIGNED}
Picture {PICTURE } AUTOMATIC
variable {~ICOMPLEX PICTURE} INTERNAL is STATIC
standard default BASED
Label LABEL and mandatory CONTROLLED
variable for:
AUTOMATIC, AUTOMATIC is standard
File FILE [VARIABLE] BASED, default for INTERNAL.
variable DEFINED, STATIC is standard
parameter default for EXTERNAL.
Entry ENTRY {ALIGNED }
variable 2 and standard [INITIAL] {UNALIGNED}
[RETURNS] [OPTIONS] default for:
[VARIABLE] CONTROLLED, Defined:
STATIC DEFINED
Locator POINTER I {OFFSET[(area- [POSITION]
variable variable) ]}
Simple Parameter:
Area AREA[ (Size) ] parameter
variable [CONNECTED]
Event EVENT Controlled Parameter: ALIGNED
variable parameter
CONTROLLED
Task TASK [INITIAL]
variable
File FILE ENVIRONMENT
constant 3 STREAM I RECORD Aggregate Variables
INPUT I OUTPUT I UPDATE
SEQUENTIAL I DIRECT I {INTERNAL} Arrays.: (dimension) may be added to the
TRANSIENT {EXTERNAL} declaration of any variable.
BUFFERED I UNBUFFERED
KEYED BACKWARDS
PRINT EXCLUSIVE Structures: the attributes that may be
speCified for a name in a structure
Entry (as for entry variables, depend upon the level at which the
constant but excluding VARIABLE) EXTERNAL name is declared:
Built-in BUILTIN 1. For a major structure name, exclude
entry data typel the LIKE attribute may
constant be specified.
INTERNAL
Generic GENERIC 2. For a minor structure name, exclude
entry data type~ scope, and storaCJe1 the
constant LIKE attribute may be specified.
Condition CONDITION {INTERNAL} 3. For a base element name, exclude
constant {EXTERNAL} scope and storaCJe.
Standard default attributes are underlined.
1 Identifiers that are implicitly declared (or explicitly declared with only scope, storage,
or aliqnment) are assumed to be arithmetic variables. If the initial letter of the
identifier is I through N, FIXED BINARY (15,0) are standard defaultsl all others are
FLOA~ DECIMAL (6). If BINARY, DECIMAL, REAL, or COMPLEX are specified, FLOAT is standard
default; otherwise if precision is specified with a scale factor, FIXED is standard
default.
2 ENTRY is implied by IRREDUCIBLE, REDUCIBLE, RETURNS, or OPTIONS. An entry constant may
have the parameter attribute.
3 File attributes, and their relationship to options of the ENVIRONMENT attribute, are
deacribed in Figure 1.2. A file conataat . .y ha. . the par...ter attribute.
Figure 1.1. Classification of attributes according to data types

406 OS PL/I CKT AND OPT LRM PART II

 RECORD

Types of File SEQUENTIAL DIRECT

~:
BUF UNBUF
I attribute or option must be
C T C specified or implied.
0 e 0 D default attribute or option.
N 1 N 0 optional attribute or option:
S R e S R R specified only if required.
E I E P E E I E S attribute or option must be
Applicable S C N G r C G N G specified.
Attributes and T U D I 0 U I D I - invalid attribute or option.
Options R T E 0 c T 0 E 0
E I X N
, I N X N The term "specified" includes the
A V E A n V A E A appearance of an option in the
M E D L g E L D L ENVIRON~~F.NT attribute or in the
DCP subparameter of the DD card.

Attrihutes Implied

F FILE I I I I I I I I I
I STREAM D - - - - - - - - FILE
L RECORD - I I I I I I I I FILE
E INPUT D D D D D D D D D FILE
OUTPUT 0 0 0 0 0 0 0 0 0 FILE
A UPDATE - 0 0 0 - 0 0 0 0 FILE RECORD
T SEQUENTIAL - D D D - D D - - FILE RFCORD
T DIRECT - - - - - - - S S FILE RECORD KEYED
R BUFFERED - D D D I - - - - FILE RECORD
I UNBUFFERED - - - - - S S D D FILE RECORD
B PRINT 0 - - - - - - - - FILE STREM1 OUTPUT
U BACKWARDS - 0 - - - 0 - - - FILE RECORD SEOUENTIAL INPtlT
T KEYED - - 0 0 I -. 0 I I FILE RECORD
E TRANSIENT - - - - I - - - - FILE
EXCLUSIVE - - - - - - - 0 0 FILE RECORD
ENVIRONMENT I I S S S I S S S FILE

0
P
FIFBIFSIFBSIVI I S - - - S - - -
VBIVSIVBSIU VS and VBS are invalid with STRE1\M
T FIFBIDIDBlu S S - - - - - - - ASCII data sets only
I FIVIVSIU - - - S - - S - S Only F for REGIONAl, (1) and (2)
0 FIFBIVIVB
N RECSIZE(n)
- - S - - - - S - vs invalid with mmUF
I I I I I I I I I One or both must be specified for
S BLKSIZE(n) I I I I - I I I I { CONSECUTIVE, INDEXED, and RFGIONAL fi lese
ASCII 0 0 - - - - - - -
0 BUFOFF(n) 0 0 - - - - - - -
F CTLASAICTL360 - 0 - - - 0 - - - } invalid for ~SCII data sets.
SCALARVARYING - 0 0 0 - 0 0 0 0
E LEAVE 0 0 - - - 0 - - -
N REREAD 0 0 - - - 0 - - -
V COBOL - 0 0 0 - 0 0 0 0
I BUFFERS(n) I I I I I - - - -
R CONSECUTIVE - D - - - D - - -
0 INDEXED - - S - - - - S -
N REGIONAL - - - S - - S - S
M ({11213})
E TP ({MI R}) - - - - S - - - -
N KEYLENGTH(n) - - S S - - S S S for REGIONAL (2) ann (3) OUTPUT only
T KEYLOC(n) - - 0 - - - - 0 -
NCP(n) - 0 0 0 - 0 0 0 0
TRKOFL - 0 - 0 - 0 0 - 0 invalid for REGIONAL (3)
INDEXAREA(n) - - - - - - - 0 -
ADDBUFF(n) - - - - - - - 0 -
NOWRITE - - - - - - - 0 - UPDATE files only.
GENKEY - - 0 - - - - 0 - INPUT or UPDATE files only; KEYED
is required.
TOTAL 0 0 0 0 0 0 0 0 0

Additional Notes:

1. UPDATE is invalid for tape files.

2. BACKWARDS is valid only for tape files.

3. KEYED is required for INDEXED and REGIONAL output.

4. File declarations for VSAM data sets are discussed
in chapter 12, "Record-Oriented Transmission."

Figure 1.2. File declarations (files associated with non-VSAM data sets)

Section I: Attributes 407

 corresponding parameter. If these 1. The area size for areas that are not
attributes of the original argument do of static storage class is given by an
not match those of the corresponding expression whose integral value
parameter, a dummy argument is specifies the number of bytes to be
created. reserved.

6. If abased variable is used to refer 2. The size for areas of static storage
to a generation of another variable, class must be specified as a decimal
the ALIGNED and UNALIGNED attributes integer constant. The theoretical
of both variables must agree. maximum size permitted is 16,111,200
bytes; in practice the maximum depends
1. The alignment of string data depends on the amount of main storage
not only on the use of ALIGNED or available to the program.
UNALIGNED, but also on whether the
strings are fixed-length or varying- 3. An asterisk may be used to specify the
length. A summary of string alignment size if the area variable being
is included in figures K.1 and K.2. declared is controlled or is a
parameter. In the case of a
8. TASK r EVENT r and AREA cannot be controlled area variable that is
unaligned. declared with an asterisk, the size
must be specified in the ALLOCATE
9. If an unaligned fixed-length bit statement used to allocate the area.
string is used as the argument of the In the case of a parameter that is
ADDR function, or appears as the first declared with an asterisk, the size is
element of a based structure which is inherited from the argument.
used in a LOCATE or ALLOCATE
statement, the locator value returned 4. Data of the area type cannot be
may not address the bit string at the converted to any other type; an area
first bit position. can be assigned to an area variable
only.
Assumptions:
5. No operators can be applied to area
1. Defaults are applied at element level. variables.
The default for bit-string data,
character-string data, and numeric 6. An area variable cannot be unaligned.
character data is UNALIGNED; for all
other types of data, the default is 1. If an area has the BASED attribute,
ALIGNED. the size attribute must be a decimal
integer constant unless the area is a
2. For all operators and user-defined and member of a based structure and the
built-in functions, the default for REFER option is used (see chapter 8,
ALIGNED or UNALIGNED is applicable to ·storage Control").
the elements of the result.
8. For RECORD input/output, only the
3. Constants take the default for ALIGNED extent (rather than the declared size)
or UNALIGNED. and control information of an area is
transmitted (except when the area is
in a structure and is not the last
item in it - then, the declared size
is transmitted).

Assumptions:

The AREA attribute defines storage that, on 1. If the size specification is omitted,
allocation, is to be reserved for the a default value is assumed. For this
allocation of based variables. storage implementation, it is 1000.
thus reserved can be allocated to and freed
from based variables by naming the area 2. An area variable can be contextually
variable in the IN option of the ALLOCATE declared by its appearance in an
and FREE statements. Storage that has been OFFSET attribute or an IN option.
freed can be subsequently reallocated to a
based variable.

General format: AUTOMATIC, STATIC, CONTROLLED and BASED

AREA [(size)]
Abbreviations: AUTO for AUTOMATIC
General rules: CTL for CONTROLLED

408 OS PL/I CKT AND OPT LRM PART II

 The storage class attributes are used to 5. For a structure variable, a storage
specify the type of storage allocation to class attribute can be given only for
be used for data variables. the major structure name. The
attribute then applies to all elements
of the structure or to the entire
AUTOMATIC specifies that storage is to array of structures. If the attribute
be allocated upon each entry to the block CONTROLLED or BASED is given to a
to which the storage declaration is structure, only the major structure
internal. The storage is released upon and not the elements can be allocated
exit from the block. If the block is a and freed.
procedure that is invoked recursively, the
previously allocated storage is "pushed 6. The following rules govern the use of
down" upon entry; the latest allocation of based variables:
storage is "popped up" upon termination of
each generation of the recursive procedure a. Whenever a locator value is needed
(for a discussion of push-down and pop-up to complete a based variable
stacking, see chapter 6, "Program reference, and none is explicitly
Organization"). specified, the value of the
locator expression in the relevant
STATIC specifies that storage is to be BASED attribute is used. It is an
allocated when the program is loaded and is error if no locator has been
not to be released until program execution declared.
has been completed.
b. When reference is made to a based
CONTROLLED specifies that full control variable, the data attributes
will be maintained by the programmer over assumed are those of the based
the allocation and freeing of storage by variable, while the qualifying
means of the ALLOCATE and FREE statements. pOinter variable identifies the
Multiple allocations of the same controlled location of data.
variable, without intervening freeing, will
cause stacking of generations of the c. A based variable can be used ~o
variable. identify and describe existing
data; to obtain storage by means
BASED, like CONTROLLED, specifies that of the ALLOCATE statement; or to
full control over storage allocation and obtain storage in an output buffer
freeing will be maintained by the by means of the LOCATE statement.
programmer, but by various methods that are
described in chapter 8, "Storage Control" d. The relative locations of based
multiple allocations are not stacked but variables allocated within an area
are available at any time; each can be can be identified by the values of
identified by the value of a pOinter offset variables.
variable.
e. The EXTERNAL attribute cannot
General format: appear with a based variable
declaration, but a based variable
STATIC I AUTOMATIC I CONTROLLED I reference can be qualified by an
BASED[(e1ement-locator-expression)] external pointer variable.

General rules: f. A based structure can be declared

to contain adjustable area-sizes,
1. Automatic and based variables can have array-bounds, and string-length
internal scope only. Static and specifications, by using the REFER
controlled variables may have either option. See chapter 8, ·Storage
internal or external scope. Control" •

2. Storage class attributes cannot be g. References to based variables in a

specified for entry constants, file CHECK prefix list or in a data
constants, members of structures, or list for data directed
DEFINED data items. input/output cannot be explicitly
locator qualified.
3. Parameters can be declared explicitly
with the storage class attribute h. A BASED VARYING string must have a
CONTROLLED, but not STATIC, BASED, or maximum length equal to the
AUTOMATIC. maximum length of any string upon
which it is defined. For example:
4. Variables declared with adjustable
lengths and dimensions cannot have the DECLARE A CHAR(SO) VARYING
STATIC attribute. BASED(Q) ,

Section I: Attributes 409

 B CHAR(50) VARYING; BINARY and DECIMAL
Q=ADDR(B) ;

i. The INITIAL attribute may be Abbreviations: BIN for BINARY

specified for a based variable. DEC for DECIMAL
The values are used only upon
explicit allocation of the based The BINARY and DECIMAL attributes
variable with an ALLOCATE or specify the base of the data items
LOCATE statement. represented by an arithmetic variable as
either binary or decimal.
If both the REFER option and the
INITIAL attribute are used for the General format:
same member, initialization is
done after the object of the REFER BINARY I DECIMAL
has been assigned its value.
General rule:
Assumptions:
The BINARY or DECIMAL attribute cannot
1. Default storage class is AUTOMATIC for be specified with the PICTURE attribute.
internal variables and STATIC for
external variables. Assumptions:

2. A pointer variable can be contextually Undeclared identifiers (or identifiers

declared by its appearance: declared only with one or more of the
dimensions, UNALIGNED, ALIGNED, scope, and
in the BASED attribute storage class attributes) are assumed to be
arithmetic variables with aSSigned
in the SET option of a LOCATE, attributes depending upon the initial
ALLOCATE, or READ statement letter. For identifiers beginning with any
letter I through N, the standard default
as a locator qualifier. attributes are REAL FIXED BINARY (15,0).
For identifiers beginning with any other
alphabetic character, the standard default
attributes are REAL FLOAT DECIMAL (6). If
FIXED or FLOAT and/or REAL or COMPLEX are
declared, then DECIMAL is assumed.

BACKWARDS

The BACKWARDS attribute specifies that the BIT, CHARACTER, and VARYING
records of a SEQUENTIAL INPUT file
associated with a data set on magnetic tape
are to be accessed in reverse order, i.e., Abbreviations: CHAR for CHARACTER
from the last record to the first record. VAR for VARYING

General format: The BIT and CHARACTER attributes are used

to specify string variables. The BIT
BACKWARDS attribute specifies a bit string. The
CHARACTER attribute specifies a character
General rules: string.

1. The BACKWARDS attribute applies to General format:

RECORD files only: that is, it

l
conflicts with the STREAM attribute. BIT
It implies RECORD and SEQUENTIAL. (length)] [VARYING]
CHARACTER
2. The BACKWARDS attribute applies to
magnetic tape files only. General rules:

1. The length attribute specifies the

length of a fixed-length string or the
maximum length of a varying-length
string. If it is not specified, a
length of one is assumed. For a bit
string the length is specified in
bits, and for a character string, in
See AUTOMATIC. bytes.

410 OS PL/I CKT AND OPT LRM PART II

2. The VARYING attribute specifies that BUFFERED and UNBUFFERED
the variable is to represent varying-
length strings, in which case length
specifies the maximum length. The Abbreviations: BUF for BUFFERED
current length at any time is the UNBUF for UNBUFFERED
length of the current value. The
storage allocated for varying-length The BUFFERED attribute specifies that
strings is two bytes longer than the during transmission to and from auxiliary
declared maximum length. The initial storage each record of a RECORD file must
two bytes hold the string's current pass through intermediate storage buffers.
length (in bytes for a character
string or bits for a bit string). The UNBUFFERED attribute specifies that
such records need not pass through buffers.
3. If present, the length attribute must It does not, however, specify that they
immediately follow the CHARACTER or must not. Hidden buffers will, in fact, be
BIT attribute at the same factoring used if INDEXED, REGIONAL(2), or
level with or without intervening REGIONAL(3) is specified in the ENVIRONMENT
blanks. attribute or if the records are variable-
length.
4. The length attribute may be specified
by an expression or an asterisk. General format:

If the length specification is an BUFFERED I UNBUFFERED

expression, it is converted to an
integer when storage is allocated for General rules:
the variable.
1. The BUFFERED and UNBUFFERED attributes
The asterisk notation can be used for can be specified for RECORD files
parameters or controlled variables. only.
The length can be taken from a
previous allocation or, for CONTROLLED 2. The UNBUFFERED attribute may not be
variables, it can be specified in a specified for TRANSIENT files.
subsequent ALLOCATE statement.
3. The locate-mode I/O statements LOCATE
There are restrictions on the use of and READ SET can be used only on
asterisks and expressions in the buffered files.
length specifications of the elements
of data aggregates in parameter Assumption:
descriptors: expressions may be used
only for controlled parameters, and The default for SEQUENTIAL and TRANSIENT
asterisks must not be used if the files is BUFFERED. UNBUFFERED is assumed
corresponding argument is such that a for DIRECT files, un1ess BUFFERED is
dummy is created. specified explicitly.

5. If a string has the STATIC attribute,

the length attribute must be a decimal
integer constant. BUILTIN

6. If a string has the BASED attribute,

the length attribute must be a decimal The BUILTIN attribute specifies that any
integer constant unless the string is reference to the associated name within the
a member of a based structure and the scope of the declaration is to be
REFER option is used. (See chapter 8, interpreted as a reference to the built-in
-storage Control-). function, a pseudovariable, or built-in
subroutine of the same name.
7. The BIT, CHARACTER, and VARYING
attributes cannot be specified with Genera1 format:
the PICTURE attribute.
BUILTIN
8. The PICTURE attribute can be used
instead of CHARACTER to declare a General rules:
fixed-length character-string variable
(see the PICTURE attribute). 1. BUILTIN is used to refer to a built- in
function, a pseudovariable or a built-
9. The maximum length allowed for a bit- in subroutine in a block that is
or character-string variable is contained in another block in which
32,767. The minimum length for any the same identifier has been declared
string is zero. to have another meaning.

Section I: Attributes 411

 2. If the BUILTIN attribute is declared name.
for a name, the attribute INTERNAL is
implied. No other attributes may be General format:
given to the name.
CONDITION
3. The BUILTIN attribute cannot be
declared for parameters. Built-in General rules:
functions without arguments should be
declared, either explicitly, with the 1. The only other attributes that can
BUILTIN attribute, or contextually by apply to a condition name are the
using a null argument list, or scope attributes, INTERNAL and
implicitly using a DEFAULT statement. EXTERNAL.
A list of these built-in functions is
given in section G, "Built-in 2. The only statements in which a
Functions and Pseudovariables." condition name can appear are ON,
SIGNAL, REVERT, DECLARE, and DEFAULT.

Assumptions:
CHARACTER
An identifier that appears with the
CONDITION condition in an ON, SIGNAL, or
see BIT. REVERT statement is contextually declared
to be a condition name.

The default scope is EXTERNAL.

COMPLEX and REAL

Abbreviation: CPLX for COMPLEX

CONNECTED
The COMPLEX and REAL attributes are used
to specify the mode of an arithmetic
variable. REAL specifies that the data Abbreviation: CONN
items represented by the variable are to be
real numbers. COMPLEX specifies that the The CONNECTED attribute is applied only
data items represented by the variable are to parameters, and specifies that the
to be complex numbers, that is, each data parameter will be a reference to connected
item is a pair: the first member is a real storage only and, hence, allows the
number and the second member an imaginary parameter to be used as a target or source
number. in record-oriented I/O or as a base in
string overlay defining.
General format:
General format:
REAL I COMPLEX
CONNECTED
General rule:
General rules:
If a numeric character variable is to
represent complex values, the COMPLEX 1. CONNECTED is an additive attribute of
attribute must be specified with the non-controlled aggregate parameters
PICTURE attribute. The COMPLEX attribute and may be associated only with level-
is the only other arithmetic or string data one names. It may be specified in a
attribute that can be specified with the DECLARE statement or in a parameter
PICTURE attribute. descriptor of an ENTRY attribute.

Assumption: 2. An argument passed to a CONNECTED

parameter must be a reference to
The standard default is REAL. connected storage. If not, a dummy
argument is created in connect ed
storage.

CONDITION

Abbreviation: COND CONTROLLED

The CONDITION attribute specifies that

the associated identifier is a condition See AUTOMATIC.

412 OS PL/I CRT AND OPT LRM PART II

DECIMAL these rules, see Figure 1.3.

see BINARY. A base variable and a defined variable

~ if the base variable when passed
as an argument would match a parameter
which had the attributes of the
DEFINED defined variable (except for the
DEFINED attribute). For this purpose,
the parameter is assumed to have all
Abbreviation: DEF array bounds, string lengths, and area
sizes specified by asterisks.
The DEFINED attribute specifies that the
variable being declared is to be associated For simple and iSUB defining a PICTURE
with some or all of the storage associated attribut~ can only be matched by a
with the designated base variable. PICTURE attribute that is identical
except for repetition factors. For a
General format: reference to specify a valid base
variable in string overlay defining,
DEFINED{base-variablel (base-variable)} the reference must be to connected
[POSITION(element-expression)]} storage. The implementation allows
the programmer to override the
The "base-variable" is the variable matching rule completely, provided he
whose storage is to be associated with the is willing to accept that this could
variable being declared; the latter is the have unwanted side-effects On his
"defined variable". program.
The POSITION attribute specifies the 3. The values specified or derived for
beginning of the part of a string base any array bounds, string lengths, or
variable with which the defined variable is area sizes in a defined variable need
to be associated. The position is that of not always match those of the base
the first bit or character in the required variable, but must be such that the
part of the base variable. defined array, string or area can be
contained in the corresponding base
General rules: array, string or area.
1. The purpose of defining one variable 4. Some attributes of the base variable
on another is to allow the programmer need not or cannot match those of the
to refer to internally stored data by defined variable. The fol.l.owing
more than one name. The name of the restriction should be noted:
base variable is the name initially
declared for the data. Each variable Base Variable:
defined on this base variable has a
different name. If the internally May be EXTERNAL or INTERNAL,
stored data is a data aggregate, a qualified, or subscripted, or both.
defined variable can comprise all the A parameter (in string overlay
data or only a specified part of it. defining, the parameter must
The defined variable does not inherit refer to connected storage).
any attributes from the base variable. Cannot be BASED or DEFINED.
2. There are three types of defining; Defined variable:
simple, iSOB, and string overlay.
Must be INTERNAL and a
If the POSITION attribute is level-one identifier.
specified, string overlay defining is May have the dimension attribute.
in effect; in this case the base Cannot be INITIAL
variable must not contain iSUB AUTOMATIC/BASED/CONTROLLED/STATIC
references. If the subscripts or a parameter.
specified in the base variable contain
references to iSOB variables, iSOB 5. If the base variable is EXTERNAL, it
defining is in effect. If neither must be known in the procedure to
iSOB variables nor the POSITION which the defined variable is
attribute is present, then simple internal. An EXTERNAL base variable
defining is in effect if the base may be known in several external
variable and defined variable match procedures; a change to its val.ue made
according to the criteria given below; in one of these causes a simil.ar
otherwise string overlay defining is change to the value of the defined
in effect. For a tabulated summary of variable.

Section I: Attributes 413

r---------------------------------------------------------------------------------------,
POSITION attribute I References to iSUB I Base and defined I Type of defining I
specified I variables in base I match 1. I in effect I
I item subscripts I I I
---------------------------------------------------------------------------------------1
I I I I
YES I I I string overlay I
--------------------- -----------------------------------------------------------------1
I I I
YES I I iSUB I
1 I I
-----------------------------------------------------------------1
I 1 I
NO 1 YES I simple I
1 1 I
NO 1-------------------------------------------1
I I 1
I NO I string overlay I
I I I
---------------------------------------------------------------------------------------1
l.A definition of matching in this context is given in General Rule 2. I
L---------------------------------------------------------------------------------------J
Figure 1.3. Guide to types of defining

6. In references to defined data, the structure variable to be referred to by

SUBSCRIPTRANGE and STRINGSIZE another name.
conditions are raised for the array
bounds and string lengths of the General rules:
defined variable, not the base
variable. 1. The defined and base variab1es can
comprise any data type; they must
7. The determination of values and the match, in the sense described earlier
interpretation of names occurs in the in this section. If the ALIGNED or
following sequence: UNALIGNED attribute is speQ~fied for
an element in the defined variable, it
a. The array bounds, string lengths, must also be specified for the
and area sizes of a defined corresponding element in the base
variable are evaluated on entry to variable.
the procedure in which the
variable is declared. 2. The defined variable may have the
dimension attribute. The base
b. A reference to a defined variable variable may be subscripted; the
is a reference to the current subscripts must not be iSUB variables.
generation of the base variable.
When a defined variable is passed 3. The POSITION attribute cannot be used
as an argument without creation of in simple defining.
a dummy, the corresponding
parameter refers to the generation 4. In Simple defining of an array:
of the base variable that is
current when the argument is a. The base variable can be a cross-
passed. This remains true even if section of an array.
the base variable is reallocated
within the invoked procedure. b. The number of dimensions in the
defined variable must be equal to
c. When a reference is made to the the number of dimensions in the
defined variable, the order of base variable.
evaluation of the subscripts of
the base and defined variable is c. The rarge specif 1ed by a bound
undefined. pair of the defined array must
equal or be contained within the
range specified by the
corresponding bound pair of the
Simple Defining base array.
5. In simple defining of a string, the
Simple defining allows an element, array or length of the defined string must be

414 OS PL/I CRT AND OPT LRM PART II

 less than or equal to the length of General rules:
the base string.
1. The defined and base arrays can
6. In simple defining of an area, the comprise any data types, and must have
size of the defined area must be equal identical attributes (apart from the
to the size of the base area. dimension attribute).

1. A base variable may be, or may 2. The defined variable must have the
contain, a VARYING string, provided dimension attribute. In the
that the corresponding part of the declaration of the defined array, the
defined variable is a VARYING string base array must be subscripted, and
of the same maximum length. the subscript positions cannot be
specified as asterisks.
Examples:
3. The POSITION attribute cannot be used
DCL A(lO,lO,lO), in iSUB defining.
Xl(2,i,2) DEF A,
X2(10,10) DEF A(*,*,S), 4. An iSUB variable is a reference, in
X3 DEF A(L,M,N); the subscript list for the base array,
to the ith dimension of the defined
Xl is a three-dimensional array that array. At least one subscript in the
consists of the first two elements of base-array subscript-list must be an
each row, column and plane of A. X2 iSUB expression which, on evaluation,
is a two-dimensional array that gives the required subscript in the
consists of the fifth plane of A. base array. The value of i ranges
X3 is an element that consists of the from 1 to n, where n is the number of
element identified by the subscript dimensions in the defined array. The
expressions L,M,and N. number of subscripts for the base
array must be equal to the number of
DCL B CHAR(lO), dimensions for the base array.
Y CHAR(S) DEF B;
S. As well as the general rules for
Y is a character string that consists evaluation, the following should be
of the first five characters of B. noted:

DCL C AREA(SOO), a. If a reference to a defined array

Z AREA(SOO) DEF C; does not specify a subscript
expression, subscript evaluation
Z is an area defined on C. occurs during the evaluation of
the expression or assignment in
DCL 1 D UNALIGNED, which the reference occurs.
2 E,
2 F, b. The value of i is specified as a
3 G CHAR(lO) VAR, decimal integer constant. Within
3 H, an iSUB expression, an iSUB
1 S UNALIGNED DEF 0, variable is treated as a fixed
2 T, binary variable, with default
2 U, precision.
3 V CHAR(lO) VAR,
3 W; c. A subscript in a reference to a
defined variable is evaluated even
S is a structure defined on D; for if there is no corresponding iSUB
simple defining the organization of in the base-variable subscript
the two structures must be identical. list.
A reference to T is a reference to E,
V to G, etc. 6. iSUB-defined variables may not appear
in the explicit or assumed data-list
of a data-directed transmission
statement or a CHECK statement or
prefix.
iSUB Defining
Examples:

iSUB defining allows a programmer to create DeL A(100,100) CHAR(l),

a defined array that consists of designated X(10,10) CHAR(l)
elements from a base array. Both defined DEF A(lSUB+20,2SUB+90);
and base arrays can be arrays of
structures. X is a two-dimensional array that

Section I: Attributes 41S

 consists of the elements of A that lie 3. iSUB variables cannot be used for the
within the bounds 21 - 30 for the base variable in string overlay
first dimension, and 91 - 100 for the defining.
second dimension.
4. The POSITION attribute can be used to
DCL B(2,5), specify the bit or character within
Y(S,2) DEF B(2SUB,lSUB); the base v~riable at which the defined
variable is to begin. It has the
Y is a two-dimensional array that format:
consists of the elements of B with the
bounds transposed. POSITION (element-expression)

DCL A(10,10) B(S,S) DEF where the expression, on evaluation,

A(1+lSUB/S,1+2SUB/S); provides the position of the required
bit or character relative to the start
In this case there is a many-to-one of the base variable. This attribute
mapping of certain elements of B to a can precede or follow the DEFINED
single element of A. B(I,J) is attribute; if it is omitted,
defined on: POSITION(l) is assumed. The value
provided by the expression can range
A(l,l) for 1<5 and J<5 from 1 to n, where g is defined as
A(l,2) for 1<5 and J=S
A(2,l) for 1=5 and J<S n = N(b) - N(d) + 1
A(2,2) for 1=5 and J=5
where N(b) is the number of bits or
Since all the elements B(I,J) are characters in the base
defined on the single element A(l,l) variable, and
when I<5 and J<5, assignment of a N(d) is the number of bits or
value to one of these elements causes characters in the defined variable.
the same value to be assigned to all
of them. The expression is evaluated, and
converted to an integer, at each
reference to the defined item. The
absolute maximum permissible value is
String Overlay Defining 32767.

5. When the defined variable is a bit

String overlay defining allows a programmer class aggregate:
to associate a defined variable with the
storage for a base variable. Both the a. the POSITION attribute can contain
defined and the base variable must be only an unsigned decimal integer
string or picture data. constant;

General rules: b. the base variable must not be

subscripted.
1. Neither the defined nor the base
variable can have the ALIGNED or the 6. The base variable must refer to data
VARYING attributes. in connected storage.

2. Both the defined and the base 7. Under the optimizing compiler, an
variables must belong to the bit array overlay-defined on another array
class, or both must belong to the is always assumed to be in unconnected
character class. The bit class storage. Under the checkout compiler,
consists of: it is treated as being in unconnected
storage only when the bounds of the
a. Fixed-length bit strings. base and defined items differ.

b. Aggregates of fixed-length bit Examples:

strings.
DeL A CHAR(100),
The character class consists of: V(lOr10) CHAR(l) DEF A:

a. Fixed-length character strings. V is a two-dimensional array that

consists of all the elements in the
b. Character string and numeric character string A.
pictured data.
DCL B(10) CHAR(l),
c. Aggregates of ~ and Q. W CHAR(lO) DEF B;

416 OS PL/I CKT AND OPT LRM PART II

 W is a character string that consists c. An asterisk specifies that the
of all the elements in the array B. actual bounds are to be specified
in an ALLOCATE statement, if the
DeL C(10,10) BIT(l), variable is CONTROLLED, or in a
X BIT(40) DEF C POS(20); declaration of an associated
argument, if the variable is a
X is a bit string that consists of 40 simple parameter. Thus, the
elements of C, starting at the 20th asterisk notation can be used only
element. for parameters and CONTROLLED
variables.
DCL E PIC'99V.999',
Zl(6) CHAR(l) DEF E, 3. Bounds that are expressions are
Z2 CHAR(3) DEF E POS(4), evaluated and converted to FIXED
Z3(4) CHAR(l) DEF E POS(2): BINARY (15,0) when storage is
allocated for the array. For simple
Zl is a character-string array that parameters, bounds can be only
consists of all the elements of the optionally signed decimal integer
decimal numeric picture E. Z2 is a constants or asterisks. 4. The
character string that consists of the bounds of arrays declared STATIC must
elements '999' of the picture E. Z3 be optionally signed decimal integer
is a character-string array that constants.
consists of the elements '9.99' of the
picture E. 5. The bounds of arrays declared BASED
must be optionally signed decimal
integer constants unless the array is
part of a based structure and the
Dimension Attribute REFER option is used. (See chapter 8,
·Storage Control".)

The dimension attribute specifies the 6. The dimension attribute must

number of dimensions of an array and the immediately follow the array name (or
bounds of each dimension. The dimension the parentheSized list of names, if it
attribute either specifies the bounds is being factored). Intervening
(either the upper bound or the upper and blanks are optional.
lower bounds) or indicates, by use of an
asterisk, that the actual bounds for the 7. The maximum permissible number of
array are to be taken from elsewhere. dimensions is 15. The minimum
permissible value for a lower bound is
General format: -32768; the maximum permissible for an
upper bound is 32767.
Cbound [,bound] •.• )

where "bound· is:

DIRECT, SEQUENTIAL, and TRANSIENT
{[lower-bound:] upper-bound}l*

and ·upper-bound· and -lower-bound" are Abbreviation: SEQL for SEQUENTIAL

element expressions.
The DIRECT, SEQUENTIAL, and TRANSIENT
General rules: attributes specify access information for
the data set associated with a file.
1. The number of bounds specifications
indicates the number of dimensions in The DIRECT and SEQUENTIAL attributes
the array unless the variable being specify the manner in which the records in
declared is contained in an array of a data set associated with a RECORD file
structures, in which case it inherits are to be accessed. SEQUENTIAL implies
dimensions from the containing that the records are to be accessed
structure. according to their physical or logical
sequence in the data set. (The records in
2. The bounds specification indicates the Ian indexed data set are processed in their
bounds as follows: logical sequence: the records in a
CONSECUTIVE or REGIONAL data set are
a. If only the upper bound is given, processed in their physical sequence.)
the lower bound is assumed to be DIRECT specifies that the records are to be
1. accessed by use of a key: each record must,
therefore, have a key associated with it.
b. The lower bound must be less than Either of these two attributes implies the
or equal to the upper bound. RECORD attribute.

Section I: Attributes 417

I Note that the SEQUENTIAL attribute does UNLOCK statement, DIRECT is assumed.
Inot necessarily imply that keyed access to
Ithe data set cannot be used. In general, 3. The TRANSIENT attribute implies KEYED
Ifor INDEXED and VSAM data sets, a mixture and RECORD.
lof keyed and sequential access is possible.
The following rules apply specifically
to the use of the TRANSIENT attribute:
The TRANSIENT attribute is designed for
teleprocessing applications. It indicates 1. The TRANSIENT attribute can be
that the contents of the data set specified only for RECORD KEYED
associated with the file are reestablished BUFFERED (or UNBUFFERED ) files with
each time the data set is accessed. In either the INPUT or OUTPUT attribute.
effect, this means that records can be
continually added to the data set by one 2. Input can be specified only by a READ
program during the execution of another statement with the KEYTO option and
program that continually removes records either the INTO option or the SET
from the data set. Thus the data set can option.
be considered to be a continuous queue
through which the records pass in transit 3. Output can be specified only by a
between a message control program and a WRITE statement or a LOCATE stat anent,
message processing program. either of which must have the KEYFROM
option.
Note that DIRECT and SEQUENTIAL specify
only the current usage of the file~ they do 4. The EVENT option is not permitted.
not specify physical properties of the data
set associated with the file. The data set 5. The "data set" associated with a
associated with a SEQUENTIAL file may TRANSIENT file is in fact a queue of
actually have keys recorded with the data. messages maintained automatically in
Most data sets accessed by DIRECT files are main storage by a separate message
created by SEQUENTIAL files. However, a control program using the
data set associated with a TRANSIENT file teleprocessing facilities of the
differs from those associated with DIRECT operating system. The queue is always
and SEQUENTIAL files in that its contents accessed sequentially.
are dynamic~ reading a record removes it
from the data set. Such a data set can 6. The element expression specified in
never be created or accessed by a DIRECT or the KEYFROM option should have as its
SEQUENTIAL file. value a recognized terminal or process
queue identification.
The use of TRANSIENT files is almost
totally dependent on the implementation~
for this reason, a list of rules for the
use of TRANSIENT is given below the general
rules and assumptions.

General format: The ENTRY attribute specifies that the

identifier being declared is either an
SEQUENTIAL I DIRECT I TRANSIENT external entry constant or an entry
variable. It is also used to describe the
General rules: attributes of the parameters of the entry
pOint.
1. DIRECT files must be KEYED~ this
attribute is implied by DIRECT. General format:
SEQUENTIAL files mayor may not have
the KEYED attribute. ENTRY(parameter-descriptor-list)]

2. The DIRECT, SEQUENTIAL, and TRANSIENT where "parameter-descriptor-list" is:

attributes cannot be specified with
the STREAM attribute. [parameter descriptor(,parameter
descriptor] ••• ]
3. TRANSIENT files must be KEYED. This
attribute is implied by TRANSIENT.

Assumptions: Rules for Parameter Descriptor lists

1. Default is SEQUENTIAL for RECORD

files. 1. A parameter descriptor list can only
be given to describe the attributes of
2. If a file is implicitly opened by an the parameters of the associated

418 OS PL/I CKT AND OPT LRM PART II

 external entry constant or entry indicates one parameter:
variable.
by the closing parenthesis when it
If nO parameter descriptor list is follows a comma with no intervening
given, the arguments are assumed to descriptor: ENTRY(FLOAT BINARY,)
match the parameters: if a parameter indicates two parameters.
descriptor list is given, it is used
for argument and parameter matching A declaration ENTRY( ) is equivalent
and the creation of dummy argUments: to ENTRY with no parameter descriptor
the parameter descriptor list must be list and the entry name must never
supplied if arguments do not match the have any arguments.
parameters.
In the example in rule 2 above, the
2. A descriptor describes the attributes parameter C has no descriptor nor has
of a single parameter. For example, the structure parameter E.
the descriptors for the parameters in
the following procedure: 5. In general, the attributes may appear
in any order in a parameter
TEST:PROCEDURE (A,B,C,D,E,F): descriptor, but for an array parameter
descriptor, the dimension attribute
DECLARE A FIXED DECIMAL (5), must be the first specified. For a
B FLOAT BINARY (15), structure parameter descriptor, the
C POINTER, level numbers must appear in the same
1 D, order as the level numbers of the
2 P, corresponding parameter, and they must
2 Q, precede the attributes for each level:
3 R FIXED DECIMAL, the descriptor level numbers need not
1 E, be the same as those of the parameter,
2 X, but the structuring must be identical;
2 Y, the attributes for a particular level
3 Z, may appear in any order.
F(4) CHARACTER (10):
Note: Each descriptor level number,
together with any attributes specified
for the level, is delimited by a comma
END TEST; (see example above).
could be declared as follows: 6. Defaults are not applied to a
parameter descriptor unless attributes
DECLARE TEST ENTRY or level numbers are specified in the
(DECIMAL FIXED (5), descriptor. If a level number and/or
BINARY FLOAT (15), the dimension attribute only is
, specified in a descriptor, FLOAT
1, DECIMAL(6) REAL are assumed.
2,
2, 1. Extents (lengths, sizes, and bounds)
3 DECIMAL FIXED, in parameter descriptors may only be
, specified by decimal integer constants
(4) CHARACTER (10»: or by asterisks. Extents in
descriptors for controlled parameters
3. The parameter descriptors must appear may only be specified by asterisks.
in the same order as the parameters
they describe. If a descriptor is 8. Attributes gi ven in the parameter
absent, the argument is assumed to descriptor list can be established
match the parameter. implicitly by use of the DEFAULT
statement in conjunction with the
4. If a descriptor is not required for a DESCRIPTORS option. However they are
parameter, the absence of a descriptor not applied for missing descriptors.
must be indicated in one of the
following ways: General rules:
by a comma: 1. The ENTRY attribute, without a
ENTRY(CHARACTER(10)",FIXED DECIMAL) parameter descriptor list, is implied
indicates four parameters; by the .attributes OPTIONS, REDUCIBLE,
IRREDUCIBLE, and RETURNS.
by an asterisk followed by a comma or
the closing parenthesis of the 2. The ENTRY attribute cannot be
parameter descriptor list: ENTRY(.) specified with the BU:tLTIN or GENERIC

Section I: Attributes 419

 attribute. 9. When a reference to any entry
expression does not include an
argument list, the procedure it
3. The ENTRY attribute must be specified represents is not invoked in the
or implied for a parameter following contexts:
representing an entry constant or
entry variable argument. a. The righthand side of an
aSSignment to an entry variable.
The maximum permissible depth of
nesting of the ENTRY attribute is two. b. Comparison with an entry
For example: expression.
c. An argument to a generic entry
DCL E ENTRY(ENTRY(FIXED»: name.
is permissible, but: d. An argument passed to an entry
parameter.
DCL E ENTRY(ENTRY(ENTRY(FIXED»):
e. An argument to the UNSPEC built-in
is not permissible. function.
4. Factoring of attributes is not f. Any context that requires a
permitted within the parameter variable (applicable only to entry
descriptor list of an ENTRY attribute variables).
specification.
110. If an entry variable has as its value
5. External entry constants must be 1 an entry constant which is an entry
explicitly declared. 1 pOint of an internal procedure, the
1 generation of the block that contains
6. The optional attribute VARIABLE is an 1 the procedure which was active (and,
additive attribute. When given, it 1 for recursive blockS, current) when
specifies that the associated 1 the entry constant was aSSigned to the
identifier is an entry variable. The 1 entry variable must still be active
VARIABLE attribute is declared 1 when the entry variable is referenced
implicitly if the identifier is 1 in a CALL statement.
declared with anyone or more of the
following attributes: If the variable has an invalid value,
the checkout compiler will raise the
ALIGNED dimension ERROR condition: under the optimizing
AUTOMATIC INITIAL compiler, however, detection of such
BASED parameter an error is not guaranteed.
CONTROLLED STATIC
DEFINED UNALIGNED 11. The values of two entry expressions
may be compared using either the = or
7. The use of an entry variable in a CALL ~= comparison operator. It is not an
statement or function reference means error to specify, in a comparison
that associated entry pOints cannot be operation, an entry variable whose
known until execution time. When an value is an entry point of an inactive
entry variable declared without a block.
parameter descriptor list appears
either in a CALL statement or as a 12. Entry names on the same PROCEDURE or
function reference that involves ENTRY statement do not compare equal.
passing arguments, the arguments are
assumed to match the parameters of the 13. The ENTRY attribute cannot be
referenced entry pOint. However, if a specified in a RETURNS attribute or
parameter descriptor list is given in option. ENTRY statement do not
the declaration of an entry variable, compare equal.
the parameters of the referenced entry
point are assumed to match the Assumptions:
attributes given in the parameter
descriptor list: dummy arguments are The ENTRY attribute can be implied. The
created if necessary. appearance of an identifier as a label
prefix of either a PROCEDURE statement or
8. When a reference to any entry an ENTRY statement constitutes an explicit
expression includes an argument list dec1aration of that identifier as an entry
(which may be a null argument list), constant. Its attributes are obtained from
the procedure it represents is always this explicit declaration and from the
invoked. declarations, if any, given in an

420 OS PL/I CKT AND OPT LRM PART II

additional DECLARE statement. The REREAD.
attributes are obtained as follows:
scope attribute: For an external entry
constant, the scope is EXTERNAL
(INTERNAL is invalid). For an entry
variable, the scope is INTERNAL by
default. The EVENT attribute specifies that the
associated identifier is used as an event
RETURNS Attribute: This is obtained name. Event names are used to investigate
from the RETURNS attribute in the the current state of tasks or of
DECLARE statement. asynchronous input/output operations. They
can also be used as program switches.
General format:
ENVIRONMENT
EVENT
Abbreviation: ENV General rules:
The ENVIRONMENT attribute is an 1. An identifier may be explicitly
implementation-defined attribute that declared with the EVENT attribute in a
specifies various file characteristics that DECLARE statement. It may be
are not part of the PL/I language. contextually declared by its
appearance in an EVENT option of a
General format: CALL statement, in a WAIT statement,
in a DISPLAY statement, or in various
ENVIRONMENT (option-list) input/output statements (see chapter
10, "Input and Output", and chapter
Options in the "option list" are separated 11, "Multitasking").
by blanks or commas. The option list is
defined individually for each 2. Event names may also have the
implementation of PL/I. For this following attributes:
implementation, it is as follows:
Dimension
[record-format] [BUFFERS(n»)
[data-set-organization] Scope (the default is INTERNAL)
[magnetic tape handling]
[printer-punch-control] Storage class (the default is
[COBOL] [data-management-optimization] AUTOMATIC)
[key-classification)
[KEYLENGTH(n)] DEFINED (event names may only be
[KEYLOC(n») defined on other event names)
[SCALARVARYING]
[teleprocessing format] INITIAL or INITIAL CALL
[direct access device usage]
[ASCII - data interchange code) 3. An event variable has two separate
[BUFOFF[(n)] - buffer offset] values:
[TOTAL]
[PASSWORD(password-specification)] a. A Single bit which reflects the
[SISISKIP] completion value of the variable.
[REUSE] '1'B indicates complete, lOeB
[BKWD] indicates incomplete.
[BUFND(n)]
[BUFNI(n)] b. A fixed-point binary value of
(BUFSP(n)] default precision (i.e.,(15,0»
which reflects the status value of
The options may appear in any order. They the variable. A zero value
are described in chapter 11, "Stream- indicates normal, nonzero
Oriented Transmission" and chapter 12, indicates abnormal status.
"Record-Oriented Transmission".
The values of the event variable can
The ENVIRONMENT attribute may be be separately returned by use of the
included only in a DECLARE statement. It COMPLETION and STATUS built-in
cannot be specified as an option of an OPEN functions. The COMPLETION function
statement. It can be specified as an returns a bit-string value
option of thQ CLOSE statement for the corresponding to the completion Value
volume disposition options LEAVE and of the variable; STATUS returns a

Section I: Attributes 421

 fixed binary value corresponding to with another event, or to modify the
the status value. completion value of an active event
variable by event variable assignment
Assignment of one event variable to or by use of the COMPLETION pseudo-
another causes both the completion and variable.
status values to be assigned.
Conversion between event variables and 8. It is an error to assign a value to an
any other data type is not possible. active event variable (including an
event variable in an array, structure,
4. Event variables may be elements of an or area) by means of an input/output
aggregate. Aggregates containing statement.
event variables may take part in
assignment, provided that this would 9. On execution of a CALL statement with
not require conversion to or from the EVENT option, the event variable,
event data. if inactive, is set to zero status
value and to incomplete. The sequence
5. The values of the event variable can of these two assignments is
be set by one of the following means: uninterruptable, and is completed
before control passes to the named
a. Use of the COMPLETION entry pOint. On termination of the
pseudovariable, to set the task initiated by the CALL statement,
completion value. the event variable is set complete and
is no longer active. If the task
b. Use of the STATUS pseudovariable, termination is not due to RETURN or
to set the status value. END in the task, then the event
variable status is set to 1, unless it
c. Event variable assignment. is already nonzero. The sequence of
the two assignments to the event
d. By a statement with the EVENT variable values is uninterruptable.
option.
10. On execution of an input/output
e. By a WAIT statement for an event statement with the EVENT option, the
variable associated with an event variable, if inactive, is set to
input/output event or DISPLAY zero status value and to incomplete.
statement. The sequence of these two assignments
is uninterruptable and is completed
f. By the termination of a task with before any transmission is initiated
which the event variable is but after any action associated with
associated. an implicit opening is completed. An
input/output event variable will not
g. By closing a file on which an be set complete until either the
input/output operation with an termination of the task that initiated
event option is in progress. the event or the execution, by that
task, of a WAIT statement naming the
6. On allocation of an event variable, associated event variable. The WAIT
its completion value is 'O'B operation delays execution of this
(incomplete). The status value is task until any transmission associated
undefined. (On the checkout compiler with the event is terminated. If no
it is set to the uninitialized value input/output conditions are to be
used for fixed binary(15) items.) raised for the operation, the event
variable is set complete and is nO
7. An event variable may be associated longer active. If any input/output
with an event, that is, a task or an conditions are to be raised, the event
input/output operation, by means of variable is set to have a status 'value
the EVENT option on a statement. The of 1 and the relevant conditions are
variable remains associated with the raised. On normal return from the
event until the event is completed. last on-unit entered as a result of
For a task the event is completed when these conditions, or on abnormal
the task is terminated because of a return from one of the on-units, the
RETURN, END or EXIT: for an event variable is set complete and is
input/output event, the event is no longer active.
completed during the execution of the
WAIT for the associated event Which 11. Event variables cannot be unaligned.
must be present in the task that
initiated the input/output operation. 12. TWo event variables can be compared
During this period the event variable using a = or a ,= comparison operator.
is said to be active. It is an error The variables compare equal if both the
to associate an active event variable status and completion values are equal,

422 OS PL/I CKT AND OPT LRM PART II

otherwise they compare not equal. locked by that task are unlocked.

Assumptions:

EXCLUSIVE 1. If a file is implicitly opened by the

UNLOCK statement, it is given the
EXCLUSIVE attribute.
Abbreviation: EXCL
2. EXCLUSIVE implies RECORD, DIRECT,
The EXCLUSIVE attribute specifies that KEYED, and UPDATE.
records in a DIRECT UPDATE file may be
locked by an accessing task to prevent
other task~ from interfering with an
operation. The section entitled "EXCLUSIVE EXTERNAL and INTERNAL
Attribute" in chapter 10, "Input and
Output", contains a table showing the
effects of various operations on EXCLUSIVE Abbreviations: EXT for EXTERNAL
files and the records contained in them. INT for INTERNAL

General format: The EXTERNAL and INTERNAL attributes

specify the scope of a name. INTERNAL
EXCLUSIVE specifies that the name can be known only
in the declaring block and its contained
General rules: blocks. EXTERNAL specifies that the name
may be known in other blocks containing an
1. The EXCLUSIVE attribute can be applied external declaration of the same name.
to RECORD KEYED DIRECT UPDATE or INPUT
files only. General format:

2. A READ statement referring to a record EXTERNAL I INTERNAL

in an EXCLUSIVE file has the effect of
locking that record, unless the READ General rules:
statement has the NOLOCK option', or
unless the record has already been 1. When a major structure name is
locked by another task; in the latter declared EXTERNAL in more than one
case, the task executing the READ block, the attributes of the structure
statement will wait until the record members must be the same in each case,
is unlocked before proceeding. although the corresponding member
names need not be identical.
3. A DELETE or REWRITE statement
referring to a locked record will 2. Members of structures always have the
automatically unlock the record at the INTERNAL attribute and cannot be
end of the DELETE or REWRITE declared with any scope attribute.
operation; if the record has been However, a reference to a member of an
locked by another task, the task external structure, using the member
executing the DELETE or REWRITE name known to the block containing the
statement will wait until the record reference, is effectively a reference
is unlocked. While a DELETE or to that member in all blocks in which
REWRITE operation is taking place, the the external name is known, regardless
record is always locked. of whether the corresponding member
names are identical.
4. Automatic unlocking takes place at the
end of the operation, on completion of Assumptions:
anyon-units entered because of the
operation (that is, at the INTERNAL is assumed for entry names of
corresponding WAIT statement when the internal procedures and for variables with
EVENT option has been specified) or by any storage class. EXTERNAL is assumed for
a GO TO branch out of such an on-unit. file constants and entry constants of
external procedures. programmer-defined
5. A locked record can be explicitly condition names are assumed to be EXTERNAL.
unlocked by the task that locked it,
by means of the UNLOCK statement.

6. Closing an EXCLUSIVE file unlocks all

the records locked by that task in the
file.
The FILE attribute specifies that the
1. When a task is terminated, all records identifier being declared is a file name.

Section I: Attributes 423

General format: file constant by any of the "file
description attributes". Refer to chapter
FILE 10, "Input and output", for discussion of
the file attributes. In addition, an
General rules: identifier can be contextually declared as
a file constant through its appearance in
1. File description attributes, such as the FILE option of any input or output
RECORD, INPUT, etc., cannot be applied statement, or in an ON statement for any
to a file variable. input/output condition.

2. A file expression is a file constant, An identifier with the FILE attribute is

a file variable or a function assumed to be a file variable if the
reference that represents a file identifier is an element of an array or
value. It may be used as: structure, or if any of the following
additional attributes is specified:
a. an argument to the FILE or COpy
option Storage class attributes
dimension attributes
b. an argument to be passed to a parameter
function or subroutine ALIGNED or UNALIGNED
DEFINED
c. an argument to an input/output INITIAL
condition name for ON, SIGNAL, and VARIABLE
REVERT statements

d. an argument to a RETURN statement

FIXED and FLOAT
3. On-units can be established for a file
constant through a file variable that
represents its value. The FIXED and FLOAT attributes specify the
scale of the arithmetic variable being
For example: declared. FIXED specifies that the
variable is to represent fixed-point data
DCL F FILE, items. FLOAT specifies that the variable
G FILE VARIABLE; is to represent floating-point data items.
G=F;
L1: ON ENDFILE(G); General format:
L2: ON ENDFILE(F);
FIXED I FLOAT
The statements labelled L1 and L2 are
eqUivalent. General rule:

4. A dummy argument is created for a file The FIXED and FLOAT attributes cannot be
constant argument to a CALL statement specified with the PICTURE attribute.
or function reference.
Assumptions:
5. A file variable may be specified in a
CHECK prefix list. Tqe CHECK Undeclared identifiers (or identifiers
condition is not raised for such a declared only with one or more of the
file variable by its appearance as a dimension, ALIGNED or UNALIGNED, scope, and
FILE option in ON, SIGNAL, and REVERT storage class attributes) are assumed to be
statements. arithmetic variables with aSSigned
attributes depending upon the initial
6. The value of a file variable may be letter. For identifiers beginning with any
transmitted by record-oriented letter I through N, the standard default
transmission statements. The value attributes are REAL FIXED BINARY (15,0).
may not be valid after transmission. For identifiers beginning with any other
alphabetic character, the standard default
7. The values of two file expressions may attributes are REAL FLOAT DECIMAL (6). If
be compared using either the = or BINARY or DECIMAL and/or REAL or COMPLEX
comparison operator. The expressions are specified, FLOAT is assumed.
compare equal only if they represent
file values, all of whose parts are
equal.
Assumptions:

The FILE attribute can be implied for a See FIXED.

424 OS PL/I CKT AND OPT LRM PART II

GENERIC LABEL (No label list may be
specified)
Mode
The GENERIC attribute is used to define an Number of dimensions (No bounds
entry name that is generic to a specified may be
group of entry expressions. When the specified)
generic name is referred to, one of the OFFSET (No area variable may be
specified entry expressions is selected, specified)
based upon the arguments specified for the PICTURE 'picture-specification'
generic name in the reference. POINTER
Precision (Number of digits and
General format: scale factor must be
specified)
GENERIC (entry-expression WHEN Scale
(generic-descriptor-list) TASK
[,entry-expression WHEN UNALIGNED
(generic-descriptor-list}l ••• ); VARYING
where generic-descriptor-list is: A missing descriptor may be indicated
[descriptor[,descriptorl ••• l by an asterisk or a comma in the
generic descriptor list.
General rules:
6. An entry expression used as an
1. The only attribute than can be argument in a reference to a generic
specified for the namE being given the value only matches a descriptor of
GENERIC attribute is INTERNAL. type ENTRY. If there is no such
description, the program is in error.
2. Each entry expression following the
GENERIC attribute corresponds to one 1. An argument with the GENERIC attribute
member of the generic group. An matches an ENTRY attribute in a
entry-expression must be a constant or generic descriptor list.
variable of type ENTRY. It must not
be based, subscripted, or defined. 8. Under the optimizing compiler, if a
locator attribute (POINTER or OFFSET)
3. The same entry-expression may appear is specified in the generiC descriptor
more than once within a single GENERIC list, the corresponding parameter must
declaration with different lists of have the same attribute; no conversion
descriptors. from one type to the other can be
performed when the entry-point is
4. The selection of a particular entry invoked. Under the checkout compiler,
expression is based upon the arguments the conversion can be performed.
of, or absence of all arguments from,
the reference to the generic name. 9. Level numbers must not be specified in
When a generic name is referred to, a generiC descriptor. An aggregate
the number of arguments and attributes may be passed as an argument to a
of each argument are compared with generic entry name but no dummy
each generic descriptor list from left argument will be created.
to right until all the attributes in
one generic descriptor list are found 10. GeneriC names (as opposed to
to be attributes of the arguments. references) may be specified as
The reference is then interpreted as a arguments to non-generic entry names.
reference to the member with the
matching generic descriptor list. If the non-generic entry name is an
entry variable or an external entry
5. The only attributes allowed are those constant it must be declared with a
that affect generic selection: these parameter descriptor list. The
are: descriptor for the generiC argument
must be ENTRY with a parameter
ALIGNED descriptor list. This nested list is
AREA (No size may be specified) used to select the argument to be
Base passed. For example:
BIT (No length may be specified)
CHARACTER CNo length may be A: PROC:
specified) DCL B GENERIC (C WHEN(FIXED),
ENTRY (No descriptor list may be D WHENCFLOAT»,
specified) E ENTRY (ENTRY(FIXED»;
EVENT CALL ECB):
FILE

Section I: Attributes 425

 1. Each item in the list can be a
END A: constant, a parenthesized expression,
a reference, an asterisk denoting no
When procedure E is invoked, C is initialization for a particular
selected and passed as the argument, element, or an iteration
since the ~escriptor specifies that specification.
the parameter specified by the entry
name parameter is FIXED. 2. In this discussion, the term
"constant" denotes one of the
If the non-generic entry name is an following:
internal entry constant, the
corresponding parameter must be [+1-1 arithmetic-constant
declared ENTRY with a parameter _
descriptor list. This list is used to bit-string-constant
select the argument to be passed. For
example: character-string-constant

A: PROC: entry-constant
DCL B GENERIC (C WHEN(FIXED),
D WHEN(FLOAT»: file-constant
CALL E(B):
E: PROC (P): label-constant
DCL P ENTRY(FIXED):
[+1-1real-constant{+I-limaginary
constant
END E:
END A: The term "expression" denotes an
element expression used to provide an
When procedure E is invoked, C is initial value to be assigned to the
selected and passed as the argument, initialized data item. An expression
since the parameter of entry name is always enclosed in parentheses when
parameter is declared to be FIXED. specified in the INITIAL attribute.
The term ~reference" denotes a
reference to a variable or a function
which can be used for the initial
value of the data item.
INITIAL
3. The time at which the INITIAL
attribute is applied depends on the
Abbreviation: INIT storage class of the variable.

The INITIAL attribute has two forms. STATIC: When the external procedure
The first specifies a constant, expression, in which the variable is declared
or function reference, whose value is to be is entered.
assigned to a data item when storage is
allocated to it. The second form specifies AUTOMATIC: When the block in which
that, through the CALL option, a procedure the variable is declared is
is to be invoked to perform initialization entered.
at allocation. The variable is initialized
by assignment during the execution of the CONTROLLED: When the ALLOCATE
called routine (rather than by this routine statement is executed.
being invoked as a function that returns a
value to the point of invocation). BASED: When an ALLOCATE or a LOCATE
statement is executed for the
General format: variable. If the variable is
referenced only by setting a
1. INITIAL (item [,item1 ••• ) pOinter and is never specified in
an ALLOCATE or LOCATE statement,
2. INITIAL CALL entry-expression the INITIAL attribute specified in
[argument-list1 a DECLARE statement is never
applied.
General rule:
4. Only one initial value can be
The INITIAL attribute cannot be given to specified for an element variable:
constants, defined data, structures or more than one can be speCified for an
parameters (except CONTROLLED parameters). array variable. A structure variable
can be initialized only by separate
Rules for form 1: initialization of its elementary

426 OS PL/I CKT AND OPT LRM PART II

 names, whether they are element or in parentheses. Note that a string
array variables. repetition factor must be an unsigned
decimal integer constant. For
5. Initial values specified for an array example, consider the following:
are assigned to successive elements of
the array in row-major order (final «2)'A')is equivalent to ('AA')
subscript varying most rapidly). «2)('A'» is equivalent to ('A','A')
«2)(1)'A') is equivalent to ('A','A')
6. If too many initial values are
specified for an array, excess ones 12. Iterations may be nested.
are ignored; if not enough are
specified, the remainder of the array 13. It is an error to specify an iteration
is not initialized. factor in an INITIAL attribute of a
scalar item.
7. Only constant values with no
operations, for example, 3, 'ABC', can 14. Names used in expressions and function
be specified in the INITIAL attribute references for initial values must be
for STATIC variables, except that the known within the block in which the
NULL built-in function may be used to initialized item is declared.
initialize a STATIC pointer variable.
15. STATIC label or entry variables cannot
8. The iteration speCification has one of have the INITIAL attribute.
the following general forms:
16. An alternate method of initialization
(iteration-factor) is available for elements of arrays of
reference I constant I (expression) non-STATIC label variables: an element
of a label array can appear as a
(iteration-factor) statement prefix, provided that all
item[, item] ••• subscripts are optionally signed
decimal integer constants. The effect
(iteration-factor) * of this appearance is the
initialization of that array element
The "iteration-factor" specifies the to a value that is a constructed label
number of times the constant, constant for the statement prefixed
expression, or item list, is to be with the subscripted reference. This
repeated in the initialization of statement must be immediately internal
elements of an array. If a constant to the block containing the
or expression follows the iteration declaration of the array. Only one
factor, then the specified number of form of initialization can be used for
elements are to be initialized with a given label array. If CHECK is
that value. If a list of items specified for such an array and the
follows the iteration factor, then the elements of the array are initialized
list is to be repeated the specified in this way, the CHECK condition is
number of times, with each item not raised at initialization.
initializing an element of the array.
If an asterisk follows the iteration 17. If the attributes of an item in the
factor, then the specified number of INITIAL attribute differ from those of
elements are to be skipped in the the data item itself, then, provided
initialization operation. the attributes are compatible,
conversion will be performed.
9. The iteration factor can be an element
expression, except for STATIC data, in 118. If a STATIC EXTERNAL item is given the
which case i t must be an unsigned I INITIAL attribute in more than one
decimal integer constant. When I declaration, i t must have this
storage is allocated for the array, I attribute on all of its declaratiOns,
the expression is evaluated to give an I and the value specified must be the
integer that specifies the number of I same in every case, except that an
iterations. I INITIAL attribute specified on a
I declaration in a procedure compiled by
10. A negative or zero iteration factor I the PL/I Optimizing Compiler need not
causes no initialization. I be repeated.

11. The initialization of an array of Rules for form 2:

strings may include both string
repetition and iteration factors. 1. The "entry-expression" and -argument-
Where only one of these is given i t is list" passed must satisfy the
taken to be a string repetition factor condition stated for prologues as
unless the string constant is placed discussed in chapter 6, ·program

Section I: Attributes 427

 Organization". INPUT, OUTPUT, and UPDATE

2. Form 2 cannot be used to initialize The INPUT, OUTPUT, and UPDATE attributes
STATIC data. indicate the function of the file. INPUT
specifies that data is to be transmitted
from auxiliary storage to the program.
Examples: OUTPUT specifies that data is to be
transmitted from the program to auxiliary
a. DECLARE SWITCH BIT (1) storage either to create a new data set or
INITIAL ('l'B); extend an existing one. UPDATE specifies
that the data can be transmitted in either
b. DECLARE MAXVALUE INITIAL (99), direction; that is, the file is both an
MINVALOE INITIAL (-99); input and an output file.

c. DECLARE A (100,10) INITIAL General format:

«920)0, (20) «3)5,9»;
INPUT I OUTPUT I UPDATE
d. DECLARE TABLE (20,20) INITIAL
CALL SET_UP (X,Y); General rules:

e. DECLARE 1 A(8), 1. A file with the INPUT attribute cannot

2 B INITIAL (0), have the PRINT attribute.
2 C INITIAL «8)0);
2. A file with the OUTPUT attribute
f. DECLARE Z(3) LABEL; cannot have the BACKWARDS attribute.

3. A file with the UPDATE attribute

cannot have the STREAM, BACKW~DS, or
PRINT attributes. A declaration of
Z(l): IF X = Y THEN GO TO EXIT; UPDATE for a SEQUENTIAL file indicates
the update-in-place mode. To access
such a file, the sequence of
statements must be READ, then REWRITE.

Z(2): A = A + B + C * D; Assumptions:

Default is INPUT. The PRINT attribute

implies OUTPUT. The EXCLUSIVE attribute
implies UPDATE.
Z(3): A = A + 10;

INTERNA~
GO TO Z(I);

See EXTERNAL.

EXIT: RETURN;

Example c results in the following: IRREDUCIBLE and REDUCIBLE

each of the first 920 elements of A is set
to 0, the next 80 elements consist of 20
repetitions of the sequence 5,5,5,9. Abbreviations: IRRED for IRREDUCIBLE
RED for REDUCIBLE
in Example d, SET UP is the name of a
procedure that sets the initial values of IThe REDUCIBLE and IRREDUCIBLE attributes
elements in TABLE. X and Yare arguments lare optimization attributes. Although
passed to SET_UP. Ithese attributes are part of the PL/I
I language, they are not fully implemented by
In Example e, B and C inherit a leither the checkout or the optimizing
dimension of (8) but, whereas only the I compiler. If the attributes are specified,
first element of B is initialized, all the Ithey are checked for syntax errors, and the
elements of C are initialized. limplied attribute ENTRY is applied; they
lare otherwise ignored.
In the last example, transfer is made to
a particular element of the array Z by , REDUCIBLE and IRREDUCIBLE are specified
giving I a value of 1,2, or 3. in entry-constant declarations of function

428 OS PL/I CKT AND OPT LRM PART II

procedures. REDUCIBLE specifies that if Assumption:
the entry name appears with an argument
list that is identical to an argument list The DIRECT attribute implies KEYED.
used in an earlier invocation, the function
need not necessarily be reinvoked and the
result of the earlier evaluation may be
used. IRREDUCIBLE specifies that this type
of optimization is not permitted.
Optimization within a function procedure is
not affected by either attribute. The LABEL attribute specifies that the
identifier being declared is a label
General format: variable and is to have statement labels as
values. To aid in optimization of the
IRREDUCIBLE I REDUCIBLE object program, the attribute specification
may also include the values that the name
General rule: can have during execution of the program.
1. These attributes can be applied only General format:
to external entry constants or entry
variables, since internal entry names LABEL ((statement-label-constant
cannot be declared. For internal [,statement-label-constant] ••• )]
entry constants, the equivalent
options can be applied to PROCEDURE or General rules:
ENTRY statements.
1. If a list of statement label constants
Assumptions: is given, the variable must have as
its value a member of the list when
The IRREDUCIBLE and REDUCIBLE attributes used in a GO TO statement or R format
imply ENTRY. item. The label constants in the list
must be known in the block containing
The standard default is IRREDUCIBLE. the declaration. Under the optimizing
compiler, the maximum permissible
number of label constants in the list
is 125. There is no limit under the
checkout compiler.
2. The parenthesized list of statement
label constants can be used in a LABEL
attribute specification for a label
array.
The KEYED attribute specifies that the
options KEY, KEYTO, and KEYFROM may be used 3. A label variable may not be used to
to access records in the file. These identify a PROCEDURE or ENTRY
options indicate that keys are involved in statement, and an entry constant may
accessing the records in the file. not be assigned to a label variable.
General format: q. A subscripted label specifying an
element of a label array can appear as
KEYED a statement label prefix if the label
variable is not STATIC, but it cannot
General rules: appear in an END· statement after the
keyword END. For further information,
1. A KEYED file cannot have the see the INITIAL attribute.
attributes STREAM or PRINT.
5. A label variable may have another
2. The KEYED attribute can be specified label variable or a label constant
for RECORD files only, and must be aSSigned to it. When such an
associated with direct access devices aSSignment is made, the environment of
or with a file with the TRANSIENT the source label is assigned to the
attribute. target.
3. The KEYED attribute must be specified 6. The INITIAL attribute cannot be
for every file with which any of the specified for STATIC label variables.
options KEY, KEYTO, and KEYFROM is
used. It need not be specified if 1. A label variable used in a GO TO
none of the options are to be used, statement must have as its value a
even though the corresponding data set label constant that is used in a block
may actually contain recorded keys. that is active at the time the GO TO

Section I: Attributes q29

 is executed. If the variable has an General rules:
invalid value, the checkout compiler
will raise the ERROR condition: under 1. The ·structure variable· can be a
the optimizing compiler, however, major structure name or a minor
detection of such an error is not structure name. It can be a qualified
guaranteed. name, but it cannot be subscripted.
Also, it must not contain a REFER
8. Labels may be compared. Comparison variable. For example, the
operators permitted for labels are = declaration:
and ~=. Labels on the same statement
compare equal. It is not an error to DECLARE 1 A BASED,
specify, in a comparison operation, a 2 X FIXED BINARY,
label variable whose value is a label 2 Y (Z REFER (X» I
constant used in a block that is nO 1 B BASED LIKE Ai
longer active.
is invalid, because references to the
9. A label prefixed to a null statement REFER object X would be ambiguous.
does not compare equal to a label
prefixed to the statement immediately 2. The "structure-variable· must be known
following the null statement. in the block containing the LIKE
attribute specification. The
For example: structure names in all LIKE attributes
A: ; are associated with declared
B: X=1: structures before any LIKE attributes
are expanded. For example:
Label A is not equal to label B.
DECLARE 1 A, 2 C, 3 E, 3 F,
10. A label prefixed to a FORMAT statement 1 D, 2 C, 3 G, 3 Hi
does not compare equal with the label
prefixed to the following statement.
11. A label prefixed to an END statement BEGIN:
does not compare equal with the label DECLARE 1 A LIKE D, 1 B LIKE A.C;
prefixed to the following statement.
12. The label on IF statement does not
compare equal with that on the END:
succeeding THEN clause.
These declarations result in the
following:
1 A LIKE D is expanded to give:

1 A, 2 C, 3 G, 3 H
Length Attribute
1 B LIKE A.C is expanded to give:

See BIT. 1 B, 3 E, 3 F

3. a. Neither the ·structure variable"

nor any of its substructures can
be declared with the LIKE
attribute. For example, the
following is invalid:
DECLARE 1 A LIKE C,
1 B,
The LIKE attribute specifies that the name 2 C,
being declared is a structure variable with 3 D,
the same structuring as that for the name 3 E LIKE X,
following the attribute keyword LIKE. 2 F,
Substructure names, elementary names, and 1 X,
attributes for substructure names and 2 Y,
elementary names are to be identical. 2 Z:
General format: because the LIKE attribute of A
specifies a structure, C, that
LIKE structure-variable contains an identifier, E, that

430 OS PL/I CRT AND OPT LRM PART II

 has the LIKE attribute. attributes are ~ecomputed. An
exception is that this does not apply
b. "Structure variable" must not be a to the INITIAL attribute for any
substructure of a structure elements of a label array that has
declared with the LIKE attribute. been initialized by prefixing to a
For example, the following is statement.
invalid:
6. If a direct application of the
DECLARE 1 A LIKE G.C, description to the structure declared
1 B, LIKE would cause an incorrect
2 C, continuity of level numbers (for
3 D, example, if a minor structure at level
3 E, 3 were declared LIKE a major structure
2 F, at level 1) the level numbers are
1 G LIKE B; modified by a constant before
application.
because the LIKE attribute of A
specifies a substructure, G.C, of 7. The LIKE attribute is expanded before
a structure, G, declared with the the ALIGNED and UNALIGNED attributes
LIKE attribute. are inherited by the contained
elements of a structure.
c. Under the optimizing compiler, no
substructure of the major 8. The LIKE attribute is expanded before
structure containing "structure the standard defaults or DEFAULT
variable w can have the LIKE statements are applied.
attribute. For example, the
following is invalid under the
optimizing compiler:
OFFSET and POINTER
DECLARE 1 A LIKE C,
1 B,
2 C, Abbreviation: PTR for POINTER
3 D,
3 0, The OFFSET and POINTER attributes
3 E, describe locator variables. A pointer
2 F LIKE X, variable can be used in a based variable
1 X, reference to identify a particular
2 Y, generation of the based variable. Offset
2 Z; variables identify a location relative to
the start of an area; pointer variables
because the LIKE attribute of A identify any location, including those
specifies a structure, C, within a within areas.
structure, B, that contains a
s~bstructure, F, having the LIKE General format:
attribute.
POINTER I OFFSET
4. Neither additional substructures nor ((element-area-variable)]
elementary names can be added to the
created structure; any level number General rules:
that immediately follows the
Wstructure variable" in the LIKE 1. A pointer variable can be explicitly
attribute specification in a DECLARE declared in a DECLARE statement, or it
statement must be algebraically equal can be contextually declared by its
to or less than the level number of appearance as a pointer qualifier, by
the name declared with the LIKE its appearance in a BASED attribute,
attribute. or by its appearance in a SET option.

5. Attributes of the "structure variable" 2. An offset variable cannot be

itself do not carryover to the contextually declared. If no area
created structure. For example, variable is specified the offset can
storage class attributes do not carry only be used as a locator qualifier
over. If the "structure variable w through use of the POINTER built-in
following the keyword LIKE represents function.
an array of structures, its dimension
attribute is not carried over. 3. The value of a pOinter variable can be
Attributes of substructure names and set in any of the following ways:
elementary names, however, are carried
over; contained dimension and length a. With the SET option of a READ

Section I: Attributes 431.

 statement. statement, then the area associated
with that offset variable must be an
b. By a LOCATE statement. unsubscripted, non-defined, element
variable. The area may be based, bUt
c. By an ALLOCATE statement. if so, its qualifier must be an
unsubscripted, non-based, non-defined
d. By assignment of the value of painter: and this pointer must not be
another locator variable, or a used to qualify the area explicitly in
locator value returned by a user- declaration of the offset variable.
defined function. NO such restrictions apply to the
checkout compiler.
e. By assignment of an ADDR or NULL
built-in function value. 8. With one exception, locator data
cannot be transmitted using STREAM
4. The value of an offset variable can be input/output. The exception is that,
set in anyone of the following ways: for the checkout compiler, locator
variables can appear in a PUT DATA or
a. By an ALLOCATE statement. PUT LIST statement.

b. By assignment df the value of 9. Whenever implicit conversion between

another locator variable, or a pOinter and offset takes place the
locator value returned by a user- area variable designated in the OFFSET
defined function. attribute is used to establish the
value.
c. By assignment of the NULL built-in
function value. Assumption:

5. Locator variables cannot be operands The variable named in the OFFSET

of any operators other than the attribute is contextually declared to have
comparison operators = and , =. the AREA attribute.

6. Locator data cannot be converted to

any other data type, but pOinter can
be converted to offset, and vice OPTIONS
versa.

7. A locator value can be assigned only The OPTIONS attribute specifies

to a locator variable. When an offset characteristics of entry data. The OPTIONS
value is assigned to an offset attribute impli6s the ENTRY attribute and
variable, the area variables named in is additive. It has nO effect on argument
the OFFSET attributes are ignored. passing and generic selection.

A pointer value is converted to offset General Format:

by effectively deducting the painter
value for the start of the area from OPTIONS (options-list)
the pointer value to be converted.
This conversion is limited to pOinter It is used in the following manner:
values that relate to addresses within
the area named in the OFFSET DECLARE identifier
attribute. Except when assigning the
NULL built-in function value, it is an [ENTRY[(parameter-descriptor-list)]]
error to attempt to convert to an
offset variable that is not associated [VARIABLE] OPTIONS(option-list):
with an area.
The options are separated by blanks.
In conversion of offset data to For this implementation, the options are:
pointer, the offset value is added to
the pOinter value of the start of the
I
l
area named in the OFFSET attribute. COBOL [additional-options]
It is an error to attempt to convert FORTRAN [additional-options]
an offset variable that is not {ASSEMBLERIASM} INTER [RETCODE]
associated with an area.
One or more additional options may
In any conversion of locator data appear, in any order, with either the COBOL
under the optimizing compiler, if the or the FORTRAN option. They are:
offset variable is a member of a
structure, or if it appears in a DO NOMAP [(argument-list)]
statement or a multiple assignment NOMAPIN [(argument-list)]

432 OS PL/I CKT AND OPT LRM PART II

 NOMAPOUT [(argument-list)] options prevent the manipulation of
data aggregates at the interface
INTER between PL/I and either COBOL or
RETCODE FORTRAN.

The COBOL, FORTRAN, and additional

options are described only briefly One or more of these options can
below; a full account of appear in the same OPTIONS-attribute
the effect and usage is given in chapter specification.
19, WInterlanguage Communication".
The arguments to which each option
General rules: applies can be specified in the
optional "argument-list" that follows
1. The OPTIONS attribute can only be used the option keyword. The format of the
in an entry declaration. It can only "argument-list" is:
be specified for external entry constants,
or entry variables, or parameters. (ARGi [,ARGj] ••• )

2. The options can be specified in any where i,j, ••• are decimal integers,
order. and the option is to apply to the ith,
jth, ••• items in the argument list of
3. The COBOL option specifies that the procedure reference.
designated entry point is in a COBOL
subprogram. Only the arguments to which this
option applies are specified in the
4. The FORTRAN option specifies that the argument list; they can be specified
designated entry point is in a FORTRAN in any order.
subroutine or function.
If there is no argument list for an
5. The ASSEMBLER option specifies that option, the option is assumed to apply
the designated entry point is in an to all the arguments passed on
assembler subroutine; this option aids invocation of the entry name.
invocation of the entry pOint from a
PL/I program, by causing arguments to An OPTIONS specification should not
be passed directly to the subroutine, include the same argument in more than
rather than via PL/I control blocks. one specified or assumed argument
The option is subject to the following list.
rules:
1. The INTER option specifies that the
a. An entry name declared with the PL/I interrupt handling facilities are
OPTIONS (ASSEMBLER) attribute to deal with those interrupts
cannot be used as a function occurring during execution of a non-
reference. PL/I routine or subprogram that are
not handled by the invoked program or
b. Any number of arguments can be its associated facilities. Note that
passed in the CALL statement routines executed with the INTER
invoking the entry, from zero up option must follow certain PL/I
to the number implied by the entry conventions if the interrupt is to be
declaration, but intervening successfully handled by PL/I. (See
arguments cannot be omitted. the programmer's guide for the
compiler. )
c. If the INTER option (see rule 1)
is omitted, a warning diagnostic ~ For Models 91 and 195, the INTER
will be issued, and INTER will be option will pass all interrupts to the
assumed; the PL/Iinterrupt PL/I interrupt handler, never to the
handling facilities will deal with appropriate non-PL/I routines.
interrupts that are not handled by
the assembler routine, provided 8. The RETCODE option specifies that, on
that certain PL/I conventions are return from the non-PL/I routine, the
followed. (see the programmer's value in the lower half of register 1~
guide for the compiler.) is to be saved as the PL/I return
code. This option enables non-PL/I
d. Multitasking options cannot be routines to pass return codes to PLiI.
used when invoking subroutines for The value of the return code can be
which OPTIONS(ASSEMBLER) has been interrogated by means of the PLIRETV
specified. built-in function.

6. The NOMAP, NOMAPIN and NOMAPOUT Examples:

Section I: Attributes 433

 DCL COBOLA OPTIONS(COBOL NOMAP(ARG1) number of arguments and parameters
NOMAPOUT(ARG3»; must be the same.

3. Attributes other than parameter can be

supplied by a DECLARE statement
CALL COBOLA(X,Y,Z); /* x, Y, Z ARE internal to the proced\~e. A
STRUCTURES */ parameter cannot be declared with any
file attributes other than FILE, or
with any of the attributes STATIC,
., AUTOMATIC, BASED, BUILTIN, EXTERNAL,
GENERIC, or DEFINED.
DCL FRTRNA OPTIONS(FORTRAN I~TER);
4. If a parameter is to be used as a base
item for string overlay defining, or
is to be specified in record-oriented
CALL FRTRNA(L,M); /* L AND M ARE*/ transmission, the CONNECTED attribute
/*ARRAYS */ must be declared explicitly.

s. Bounds, lengths, and sizes of simple

., parameters must be specified either by
DCL ASSEMA OPTIONS(ASM INTER RETCODE) asterisks or by constants. Only
ENTRY(FIXED DEC",FLOAT); controlled parameters may have the
INITIAL attribute.

6. If the attributes of an argument do

CALL ASSEMA(A,B,C,D); /*VALID*/ not match those given for the
corresponding parameter, a dummy
argument is generated with attributes
that agree with those of the
CALL ASSEMA(A,B); /*VALID*/ parameter. The original argument is
then converted and assigned to the
dummy argument. The conversion is
performed automatically for internal
CALL ASSEMA; /*VALID*/ entry constants: but for external
entry constants and entry variables, a
parameter-descriptor list must be
given in an appropriate entry
CALL ASSEMA(A",D): /*INVALID*/ declaration if conversion is required.

The relationships between arguments

and parameters is discussed in chapter
O~PUT 9, ·Subroutines and Functions".

Assumptions:
see INPUT.
If attributes are not supplied in a
DECLARE statement, default attributes are
applied, depending on the initial letter of
Parameter Attribute the parameter identifier and on any
associated DEFAULT statement. A parameter
has the INTERNAL attribute by default.
The parameter attribute specifies that a
name in an invoked procedure represents an
argument passed to that procedure.
PICTURE
General rules:

1. An identifier is explicitly declared Abbreviation: PIC

with the parameter attribute by its
appearance in a parameter list. The The PICTURE attribute is used to define
identifier must not be subscripted or the internal and external formats of
qualified. character-string and numeric character data
and to specify the editing of data.
2. A parameter list is specified in a Numeric character data is data having an
PROCEDURE or ENTRY statement. arithmetic value but stored internally in
Parameters in a parameter list character form. Numeric character data
correspond, from left-to-right, with must be converted to coded arithmetic
arguments in an argument list. The before arithmetic operations can be

434 OS PL/I CKT AND OPT LRM PART II

performed. PreCision Attribute
The picture characters are described in
·Picture Specification Character" in Part The prec1s10n attribute is used to specify
II. the minimum number of significant digits to
be maintained for the values of the data
General format: items, and to specify the scale factor (the
assumed position of the binary or decimal
PICTURE t point). The preCision attribute applies to
both binary and decimal data.
'character-picture-specification'
General format:
'numeric-picture-specification'
(number-of-digits [,scale-factor])
A "picture specification", either character
or numeric, is composed of a string of The "number-of-digits· is an unsigned
picture characters enclosed in single decimal integer constant and "scale-factor"
quotation marks. An individual picture is an optionally Signed decimal integer
character may be preceded by a repetition constant. The precision attribute
factor, which is a decimal integer specification is often represented, for
constant, B, enclosed in parentheses, to brevity, as (p,q), where E represents the
indicate repetition of the character B "number-of-digits· and g represents the
times. If n is zero, the character is "scale-factor".
ignored. Picture characters are considered
to be grouped into fields, some of Which General rules:
contain subfields.
1. The preCision attribute must follow,
General rules: with no intervening keywords or names,
the scale (FIXED or FLOAT), base
1. The "character-picture-specification· (DECIMAL or BINARY), or mode (REAL or
is used to describe a character-string COMPLEX) at the same factoring level.
data item.
2. The number of digits s~ecifies the
2. The "numeric-picture-specification" is number of digits to be maintained for
used to describe a character item that data items assigned to the variable.
represents either an arithmetic value The scale factor specifies the number
or a character-string value, depending of fractional digits. No point is
upon its use. actually present; its location is
assumed.
3. A numeric character data item can have
only a decimal base. Its scale and 3. The scale factor can be specified for
precision are specified by the picture fixed-point variables only; the number
characters. The PICTURE attribute of digits is specified for both fixed-
cannot be specified in combination -point and floating-point variables.
with base, scale, or precision Q. When the scale is FIXED and no
attributes. If the mode of the scale factor is specified, it is
numeric character data is COMPLEX, assumed to be zero: that is, the
however, the COMPLEX attribute must be variable is to represent integers.
explicitly stated.
5. The scale factor of the variable, or
Q. Only coded arithmetic data or of an intermediate result must be in
character string data representing the range -128 through +121.
arithmetic constants may be assigned
to a numeric picture variable. 6. The scale factor can be negative, and
it can be larger than the number of
digits. A negative scale factor (-q)
always specifies integers, with the
POINTER point assumed to be located g places
to the right of the rightmost actual
digit. A positive scale factor (q)
See OFFSET. that is larger than the number of
digits always specifies a fraction,
with the point assumed to be located g
places to the left of the rightmost
POSITION actual digit. In either case,
intervening zeros are assumed, but
they are not stored; only the
See DEFINED. specified number of digits are

Section I: Attributes Q35

 actually stored.

7. The precision attribute cannot be

specified in combination with the See COMPLEX.
PICTURE attribute.

8. The maximum number of digits allowed

is 15 for decimal fixed-point data, 31
for binary fixed-point data, 33 for
decimal floating-point data, and 109
for binary floating-point data. RECORD and STREAM

Assumptions:
The RECORD and STREAM attributes specify
The standard defaults for precision are the kind of data transmission to be used
as follows: for the file. STREAM indicates that the
data of the file is considered to be a
(5,0) for DECIMAL FIXED continuous stream of data items, in
(15,0) for BINARY FIXED character form, to be assigned from the
(6) for DECIMAL FLOAT stream to variables, or from expressions
(21) for BINARY FLOAT into the stream. RECORD indicates that the
file consists of a collection of physically
separate records, each of which consists of
one or more data items in any form. Each
record is transmitted as an entity to or
from a variable.

General format:

RECORD I STREAM

General rules:
The PRINT attribute specifies that the data
of the file is ultimately to be printed. 1. A file with the STREAM attribute can
The PAGE and LINE options and format items be specified only in the OPEN, CLOSE,
of the PUT statement and the PAGESIZE GET, PUT, ON, and aSSignment
option of the OPEN statement can be used statements.
only with files having the PRINT attribute.
These options are described in section J, 2. A file with the RECORD attribute can
"Statements" • be specified only in the OPEN, CLOSE,
READ, WRITE, REWRITE, LOCATE, UNLOCK,
General format: DELETE, ON, and assignment statements.

PRINT 3. A file with the STREAM attribute

cannot have any of the following
General rules: attributes: UPDATE, DIRECT,
SEQUENTIAL, TRANSIENT, BACKWARDS,
1. The PRINT attribute implies the OUTPUT BUFFERED, UNBUFFERED, EXCLUSIVE, and
and STREAM attributes. KEYED, any of which implies RECORD.

2. The PRINT attribute conflicts with the 4. A file with the RECORD attribute
RECORD attribute. (However RECORD cannot have the PRINT attribute.
files can be associated with the
printer~ see chapter 12, "Record- Assumptions:
Oriented Transmission".)
Default is STREAM. If a file is
3. The PRINT attribute causes the initial implicitly opened by a READ, WRITE,
data byte.within each record to be REWRITE, LOCATE, UNLOCK, or DELETE
reserved for ANS printer control statement, RECORD is assumed.
characters. These control characters
are set by the PAGE, SKIP, or LINE
format items or options.

Assumption:
REDUCIBLE
If no FILE or STRING specification
appears in a PUT statement, the standard
output file SYSPRINT is assumed. See IRREDUCIBLE.

436 OS PL/I CKT AND OPT LRM PART II

RETURNS constants. The returned value has the
specified length or size.

The RETURNS attribute is specified in an Assumptions:

ENTRY declaration to define the data
attributes of a value returned by an entry If the RETURNS attribute is not
variable or an external procedure. specified for an external entry point, a
RETURNS attribute is assumed specifying
General format: default attributes; the defaults are either
as specified in a DEFAULT statement or are
RETURNS (attribute ••• ) the standard defaults: REAL FIXED BINARY
(15,0) if the entry constant begins with
It is used in the following manner: any of the letters I through N, otherwise,
REAL FLOAT DECIMAL (6).
DECLARE identifier
[ENTRY (parameter descriptor list)]
[VARIABLE] RETURNS (attribute ••• );

General rules: SEQUENTIAL

1. The attributes in the parenthesized

list following the keyword RETURNS See DIRECT.
must be separated by blanks (except
for attributes, such as precision,
that are enclosed in parentheses).
They must agree with the attributes Size Attribute
specified either explicitly in the
RETURNS option of the PROCEDURE or
ENTRY statement to which the entry See AREA.
name is prefixed, or by default.

2. The attributes specify the data

characteristics of the value returned STATIC
when the entry is invoked as a
function.
See AUTOMATIC.
3. The only attributes that may be
specified are string or arithmetic
attributes (including VARYING), or
ALIGNED, UNALIGNED, POINTER, OFFSET, STREAM
AREA, FILE, EVENT, TASK, and LABEL.
The OFFSET attribute may include an
area name; under the optimizing See RECORD.
compiler, this must be a non-defined,
unsubscripted, unqualified name, but
under the checkout compiler it may be
any area expression other than a
function reference. The LABEL
attribute may include a list of label
constants. The TASK attribute describes a variable
that may be used as a task name, to test or
4. If RETURNS attributes are not control the relative priority of a task.
specified with an explicitly declared
entry constant of an external function General format:
procedure, default attributes are
applied according to the entry TASK
constant identifier. Standard default
assumptions are given below. General rules:

Note: The value returned by a 1. An identifier can be explicitly

procedure function reference should declared with the TASK attribute in a
agree with the attributes specified by DECLARE statement, or i t can be
RETURNS; if it does not agree, there contextually declared by its
is an error since no conversion will appearance in a TASK option of a CALL
be performed. statement.

5. string lengths and area s~zes must be 2. Task variables can also have the
specified by decimal integer following attributes:

section I: Attributes 437

 a. Dimension variable is SEt by means of either the
PRIORITY pseudovariable or the
b. Scope (the default is INTERNAL) PRIORITY option of the CALL statement
which invokes the task, its priority
c. storage class (the default is will be undefined.
AUTOMATIC)
1. Task data cannot be converted to any
d. DEFINED (task variables may only other data type.
be defined on other task names)
8. Assignment of task data to an inactive
e. INITIAL and INITIAL CALL task variable is permitted. The value
aSSigned must be the priority of a
3. A task expression can be used in the task derived from a task expression.
following contexts only:
9. Two task expressions can be compared
a. In the TASK option of a CALL using = or a ~= comparison operator.
statement The variables compare equal if their
priorities are equal, otherwise they
b. As an argument of the PRIORITY compare not equal.
pseudovariable or built-in
function
c. As an argument in a CALL statement TRANSIENT
or function reference
d. As a parameter in a PROCEDURE or See DIRECT.
ENTRY statement
e. In an ALLOCATE or FREE statement
UNALIGNED
f. In an assignment statement
g. In a RETURN statement See ALIGNED.
h. AS the control variable of a DO-
loop.
UNBUFFERED
i. In a comparison operation.
4. A task variable may be associated with See BUFFERED.
the priority of a task by including
the task name in the TASK option of a
CALL statement. A task variable is
said to be active if its associated UPDATE
task is active. A task variable must
be in an allocated state when it is
associated with a task and must not be See INPUT.
freed while it is active. An active
task variable cannot be associated
with another task.
VARIABLE
5. A task variable contains a Single
value, a priority value. This value
is a fixed-point binary value of IThe VARIABLE attribute can be used only
precision (15,0). This value can be Iwith the ENTRY or FILE attributes. It
tested and adjusted by means of the lestablishes the name as an entry-variable
PRIORITY built-in function and lor a file-variable.
·pseudovariable. The built-in function
returns the priority of the task General format:
argument relative to the priority of
the task executing the function. VARIABLE
Similarly, the pseudovariable permits
assignment, to the named task
variable, of a priority relative to
the priority of the task executing the VARYING
assignment.
6. Unless the priority of the task See BIT.

438 OS PL/I CRT AND OPT LRM PART II

 Section J: Statements

This section presents the PL/I statements structure.

in alphabetical order. (The preprocessor
statements are alphabetically arranged at 3. "Dimension" indicates a dimension
the end of this section.) Most statements attribute. "Attribute" indicates an
are accompanied by the following AREA, BIT, CHARACTER, or INITIAL
information: attribute.

1. Function a short description of the 4. A dimension attribute, if present,

meaning and use of the statement must specify the same number of
dimensions as that declared for the
2. General format -- the syntax of the associated identifier.
statement
5. The attribute BIT may appear only with
3. Syntax rules -- rules of syntax that a BIT identifier; CHARACTER may appear
are not reflected in the general only with a CHARACTER identifier; AREA
format may only appear with an area
identifier.
4. General rules -- rules governing the
use of the statement and its meaning 6. A structure element name, other than
in a PL/I program the major structure name, may appear
only if the relative struc~uring of
the entire major structure containing
the element appears as in the DECLARE
ALLOCATE statement for that structure. In this
case, dimension attributes must be
specified for all identiters that are
Abbreviation: ALLOC declared with the dimension attribute.

The ALLOCATE statement causes storage to be Syntax rules 7 and 8 apply only to
allocated for specified controlled or based Option 2:
data.
7. The based variable appearing in the
General format: ALLOCATE statement may be an element
variable, an array, or a major
ALLOCATE option[,optionJ ••• ; structure. When it is a major
structure, only the major structure
where ·option" has one of two forms: name is specified.

Option 1 8. The SET option, if present, may appe~r

preceding or following the IN option.
[levelJ identifier [dimensionJ
[attribute] ••• General rules:

Option 2 Rules 1 through 6 apply only to option 1:

based-variable-identifier 1. When Option 1 is used, an ALLOCATE

[SETCelement-locator-variable)] statement for an identifier for which
[INCelement-area-variable)] storage was allocated and not freed
causes storage for the identifier to
Syntax rules: be "pushed down" or stacked. This
pushing down creates a new generation
Syntax rules 1 through 6 apply only to of data for the identifier. When
Option 1: storage for this identifier is freed,
using the FREE statement, storage is
1. ·Level" indicates a level number. The ·popped upn or removed from the stack.
first identifier appearing after the
keyword ALLOCATE must be a level 1 2. Bounds for arrays, lengths of strings,
identifier. and sizes of areas are fixed at the
execution of an ALLOCATE statement.
2. Each identifier must represent data of
the controlled storage class or be an a. If a bound, length, or size is
element of a controlled major explicitly specified in an

section J: statements 439

 ALLOCATE statement, it overrides 6. Any evaluations performed at the time
that given in the DECLARE the ALLOCATE statement is executed
statement. (e.g., evaluation of expressions in an
INITIAL attribute) must not be
interdependent.
b. If a bound, length, or size is
specified by an asterisk in an Rules 7 through 12 apply only to Option 2:
ALLOCATE statement, the bound,
length or size is taken from the 7. When Option 2 is used, storage is not
current generation. If no "pushed down" or stacked. In this
generation of the variable exists, case, reference may be made to any
the bound, length, or size is generation of a based variable through
undefined and the program is in a locator variable.
error.
8. The allocation of a based variable
c. Either the ALLOCATE statement or a involves the based variable to be
DECLARE or DEFAULT statement must allocated, a locator variable to
specify any necessary dimension, identify the new generation, and an
size, or length attributes for an area if the generation is to be
identifier. Any expression taken allocated in an area. If no SFT
from a DECLARE or DEFAULT option is specified, a SET option is
statement is evaluated at the assumed to specify the locator
point of allocation using the variable given in the BASED attribute
conditions enabled at the ALLOCATE of the based variable declaration; i t
statement, although names in the is an error, in such a case, if this
expression are interpreted in the BASED attribute does not specify a
environment of the DECLARE or locator variable. If the SET option
DEFAULT statement. specifies an offset variable and no IN
option is present then an IN option is
d. If, in either an ALLOCATE or a assumed to specify the area given in
DECLARE statement, bounds, the OFFSET attribute of the offset
lengths, or sizes are specified by variable declaration; in such a case,
expressions that contain it is an error if this OFFSET
references to the variable being attribute does not specify an area
allocated, the expressions are variable.
evaluated using the value of the
most recent generation of the ·9. If the SET option specifies an offset
variable. variable, the locator value
identifying the new generation is
3. Upon allocation of an identifier, assigned to the offset variable; the
initial values are assigned to it if IN option must be present, or be
the identifier has an INITIAL assumed, and it must specify either
attribute in either the ALLOCATE the same area as that specified in the
statement or DECLARE statement. OFFSET attribute of the offset
Expressions or a CALL option in the variable declaration, or an area
INITIAL attribute are executed at the contained in or containing that area.
point of allocation, using the
conditions enabled at the ALLOCATE 10. If no IN option is present and none is
statement, although the names are assumed, the new generation is
interpreted in the environment of the allocated in storage associated with
declaration. If an INITIAL attribute the task which executes the ALLOCATE
appears in both DECLARE and ALLOCATE statement. The SET option in this
statements, the INITIAL attribute in case must specify a pOinter variable.
the ALLOCATE statement is used. If
initialization inVOlves reference to 11. If the IN option appears in, or is
the variable being allocated, the assumed for, the ALLOCATE statement,
reference will be to the new storage will be allocated in the named
generation of the variable. area, for the based variable. If
sufficient storage does not exist
4. To determine whether or not storage within this area, the AREA condition
has been allocated for an identifier will be raised.
and how many generations exist, the
built-in function ALLOCATION may be 12. The amount of storage allocated for a
used. based variable depends on its
attributes, and on its dimensions,
5. A parameter that is declared length, or size specifications if
CONTROLLED may be specified in an these are applicable at the time of
ALLOCATE statement. allocation.

440 05 PL/I CKT AND OPT LRM PART II

r---------------------------------------------------------------------------------------,
I
option 1 (Element Assignment)

element-variable} [,element-variable]
{pseudovariable = element-expression:
,pseudovariable
option 2 (Array Assignment)
array-variable ,array-variable structure-expression (,BY NAMEl}
{pseudovariable } [ ,pseudovariable ] = { array-expression
element-expression
(,BY NAMEl :

IOption 3 (structure Assignment)

I
: {structure-variable}frstructure-variableJ ••• = {structure-expression (,BY NAMEl}:
I pseudovariable . ~pseudovariable element-expression
L---------------------------------------------------------------------------------------J
Figure J.1. General formats of the assignment statement

These attributes are determined from General rules:

the declaration of the based variable,
and additional attributes may not be 1. Aggregate assignments (Options 2 and
specified in the ALLOCATE statement. 3) are expanded into a series of
A based structure may contain element aSSignments according to rules
adjustable array bounds or string 5 through 8.
lengths or area sizes (see ftREFER
Option", in "Storage Control" in Part 2. An element assignment is performed as
I). Note that the asterisk notation follows:
for bounds, length, or size is not
permitted for based variables. a. Subscripts and locator
qualifications of the target
variables, and the second and
third arguments of SUBSTR
pseudovariable references, are
evaluated first. (The order of
Assignment statement evaluation of subscripts and
qualifiers is undefined).
The assignment statement is used to b. The expression on the right-hand
evaluate an expression and to assign its side is then evaluated.
value to one or more target variables: the
target variables may be element, array, or c. For each target variable (in left
structure variables. The target variables to right order), the expression is
can be pseudovariables. converted to the characteristics
of the target variable according
General formats: to rules for data conversion
(except that whenever a conversion
The assignment statement has three of arithmetic base is involved,
general format options. They are given in the value is converted directly to
figure J.1. the precis·ion of the target
variable). The converted value is
syntax rules: then assigned to the target
variable.
1. In Option 2, each target variable must
be an array. If the right-hand side d. The element variable can be a
contains arrays of structures, then variable with the PICTURE
all target variables must be arrays of attribute. The rules for
struct ures • The BY NAME option may be assignments to picture targets are
given only when the right-hand side described in section 0, "Picture
contains at least one structure. Specification Characters ft •
2. In Option 3, each target variable must 3. The following rules apply to string
be a struct ure. element assignment:

Section J: Statements 441

 a. The assignment is performed from e. If the target is an event
left to right, starting with the variable, the expression can only
leftmost position. be an event variable. The
assignment is uninterruptable, and
b. If the target variable is a fixed- it involves both the completion
length string, the expression and status values. An event
value is . trl.Ulcatp.d on the right if variable does not become active
it is too long (raising the when it has an active event
STRINGSIZE condition, if enabled) variable assigned to it. It is an
or padde~ on the right (with error to aSSign to an active event
blanks for character string, zeros variable.
for bit strings) if the value is
too short. (Note that a string t. If the target is a STATUS
pseudovariable is considered to be pseudovariable, a value can be
a fixed-length string.) The assigned whether or not the event
resulting value is assigned to the variable is active. It is an
target. error to aSSign to a COMPLETION
pseudovariable if the named event
c. If the target is a VARYING string variable is active.
and the value of the expression is
longer than the maximum length g. If the target is an entry
declared for the variable, the variable, the expression can only
value is truncated on the right be an entry expression.
(raising the STRINGSIZE condition,
if enabled). The target string h. If the target is a file name
obtains a current length equal to variable, the expression can only
its maximum length. If the value be a file expression.
of the expression is not longer
than the maximum length, the value i. If the target is a task variable,
is assigned; the target string the expression can only be a task
obtains a current length equal to variable or a task function
the length of the value. reference. The task variable
specified must be inactive. The
4. The following rules apply to other aSSignment involves the priority
element assignments: of the task variable or task
function reference.
a. If the target is an area variable,
the expression must be an area 5. The first target variable in an
variable or function. The AREA aggregate assignment is known as the
condition will be raised by this master variable. If the master
assignment if the size of the variable is an array, then an array
target area is insufficient for expansion (Rule 6) is performed:
the current extent of the area otherwise, a structure expansion
being assigned. (Rules 7 and 8) is performed. The
CHECK condition for assignment to a
b. If the target is a pOinter target variable is raised (when
variable, the expression can only suitably enabled) after assignment to
be a pointer (or offset) variable each element. In the case of BY NAME
or a pOinter (or offset) function aSSignment, the CHECK condition for
reference. If the expression is the target variable is raised
of offset type, its value is regardless of whether any value is
converted to pointer. aSSigned to an item. The label prefix
of the original statement is applied
c. If the target is an offset to a null statement preceding the
variable, the expression can only other generated statements.
be an offset (or pointer) variable
or an offset (or pointer) function 6. In Option 2, all array operands must
reference. If the expression is have the same number of dimensions and
of pointer type, its value is identical bounds. The array
converted to offset. aSSignment is expanded into a loop as
follows.
d. If the target is a label variable,
the expression can only be a label LABEL: DO jl LBOUND(master-variable,l) TO
variable or label constant. HBOUND(master-variable,l);
Environmental information (i.e.,
information that identifies the DO j2 = LBOUND(master-variable,2) TO
invocation of the block) is always HBOUND(master-variable,2);
assigned to the label variable.

442 OS PL/I CKT AND OPT LRM PART II

 can be arrays.
a. The first item immediately
DO jn = LBOUND(master-variable,n) TO contained in the master variable
HBOUND(master-variable,n); is considered.
generated assignment statement b. If each structure operand and
target variable has an immediately
END LABEL; contained item with the same
identifier, an assignment
In this expansion, n is the number of statement is generated as follows:
dimensions of the master variable that the statement is derived by
are to participate in the assignment. replaCing each structure operand
In the generated assignment statement, and target variable with its
all array operands are fully immediately contained item that
subscripted, using (from left to has this identifier. If any
right) the dummy variables jl to jn. structure contains no such
If an array operand appears with no identifier, no statement is
subscripts, it will only have the generated. If the generated
subscripts jl to jn; if cross-section assignment is a structure or
notation is used, the asterisks are array-of-structures assignment, BY
replaced by jl to jn. If the original NAME is appended. The first
assignment statement (which may have generated assignment is given the
been generated by Rule 7 or Rule 8) label prefix of the original
has a condition prefix, the generated assignment statement; all
assignment statement is given this generated assignment statements
condition prefix. If the original are given the condition prefix of
assignment statement (which may have the original assignment statement.
been generated by Rule 8) has a BY
NAME option, the generated assignment c. Step b is repeated for each of the
statement is given a BY NAME option. items immediately cqntained in the
If the generated assignment statement master variable. The assignments
is a structure assignment, it is are generated in th~ order of the
expanded as given below. items contained in the master
variable.
7. In Option 3, where the BY NAME option
is not specified, the following rules d. Steps a through c may generate
apply: further array and structure
assignments. These are expanded
a. None of the operands can be according to Rules 6 through 8.
arrays, although they may be
structures that contain arrays.
b. All of the structure operands must
have the same number, k, of
immediately contained items.
c. The assignment statement (which The BEGIN statement heads and identifies a
may have been generated by Rule 6) begin block.
is replaced by ~ generated
assignment statements. The !th General format:
generated assignment statement is
derived from the original BEGIN(ORDERIREORDER];
assignment statement by replacing
each structure operand by its !th Syntax rules:
contained item; such generated
assignment statements may require 1• A label of a BEGIN statement may be
further expansion according to subscripted, but such a label caMlfM:
Rule 6 or Rule 7. All generated appear in an END statement.
assignment statements are given
the condition prefix of the General rules:
original statement.
1. A BEGIN statement is used in
8. In Option 3, where the BY NAME option conjunction with an END statement to
is given, the structure assignment, delimit a begin block. A complete
which may have been generated by Rule discussion of begin blocks can be
6, is expanded according to steps a found in chapter 6, ·Program
through d below. None of the operands Organisation."

Section J: statements 443

 2. ORDER and REORDER are optimization 2. When the TASK option is used, the task
options for use by the optimizing name, if given, is associated with the
compiler. If they are included in a task created by the CALL. Reference
program processed by the checkout to this name enables the priority of
compiler, they are checked for syntax the task to be controlled at some
errors and then ignored. Their other point by the use of the PRIORITY
presence in such a program is not an pseudovariable and built-in function.
error.
3. ORDER and REORDER specify the extent 3• When the EVENT option is used, the
to which the block is to be optimized. event name is associated with the
In general, ORDER permits optimization completion of the task created by the
to the degree such that the latest CALL statement. Another task can then
values of variables set in a block are wait for completion of this created
guaranteed available in a task by specifying the event name in a
computational on-unit entered at any WAIT statement.
point during execution of the block.
REORDER permits a greater degree of Upon execution of the CALL statement,
optimization; with REORDER the latest the event variable is made active, and
values of variables set in the block the completion value is set to 'O'B
are not guaranteed available in an on- and the status value to O. Upon
unit entered during execution of the termination of the created task, the
block. If neither is specified, ORDER completion value is set to 'l'B and,
is assumed, but REORDER is inherited unless the task has been terminated by
by all contained blocks unless they a RETURN qr END statement, the status
explicitly specify ORDER. is set to 1 if still zero.
4. If the PRIORITY option is used, the
expression in the PRIORITY option is
evaluated to an integer ~, of an
implementation-defined precision
(15,0). The priority of the named
The CALL ~tatement invokes a procedure and task is then made m relative to the
causes con~rol to be transferred to a task in which the CALL is executed.
specified entry point of the procedure.
If a CALL statement with the EVENT or
General format: TASK option does not have the PRIORITY
option, the priority of the invoked
CALL {entry-expression I generic-name I task is made equal to that of the task
bUilt-in name} variable in the TASK option, if there
is a task variable, or else made equal
[(argument [,argument] • • • )] to the priority of the invoking task.
The programmer must specify a priority
[TASK [(element-task-name)]] [EVENT if he uses a task variable, (by means
(element-event-name)] [PRIORITY of either a PRIORITY option on the
(expression)]; CALL statement or the PRIORITY
pseudovariable prior to the CALL
Syntax rules: statement), otherwise the task will be
of undefined priority.
1. The entry expression, generic name, or
built-in name represents the entry 5. Expressions in these options, as well
point of the subroutine invoked. as any argument expressions, are
evaluated in the task in which the
2. The TASK, EVENT, and PRIORITY options call is executed. This includes
can appear in any order. execution of anyon-units entered as
the result of the evaluations.
General rules:
6. The environment of the invoked
1. The TASK, EVENT, and PRIORITY options, procedure is established after
when used alone or in any combination, evaluation of the expressions named in
specify that the invoked and invoking Rule 5, and before the procedure is
procedures are to be executed invoked.
asynchronously. Note that if either
the EVENT option or the PRIORITY 7. A CALL statement must not be used to
option, or both, are used without the invoke a procedure if control is
TASK option, the created task will returned to the invoking procedure by
have no name. (see chapter 17, means of a RETURN(expression)
wMul t i taksing W • ) statement.

444 OS PL/I CRT AND OPT LRM PART II

 8. See chapter 9, ·Subroutines and The names must be known in the block
Functions· for detailed descriptions in which the CHECK statement is
of the interaction of arguments with executed.
the parameters that represent these
arguments in the invoked procedure". If no names are specified, the CHECK
statement is assumed to apply to every
9. If the procedure invoked by the CALL name known in the external procedure
statement has been specified in a that contains the CHECK statement,
FETCH or RELEASE statement, and if it whether or not these names were known
is not present in main storage, the at the time the CHECK statement was
CALL statement initiates dynamic executed. These names may be known in
loading of the procedure from other, separately compiled, external
auxiliary storage. The execution of procedures.
the invocation is delayed until the
procedure has been loaded. General Rules:

In this case, the entry expression 1. Execution of a CHECK statement has the
must be an entry constant, and it must effect of enabling a CHECK condition-
be eqUivalent to both the name by prefix, or of modifying an existing
which the procedure is known in CHECK condition-prefix, for every
external storage and a point through statement that is executed after the
which the procedure may be entered: execution of the CHECK statement.
and the same constant must have
appeared in a FETCH or RELEASE The prefixes thus derived operate in
statement compiled at the same time as the same way as ordinary prefixes. If
the CALL statement. A main procedure the condition is raised, any CHECK on-
may not be dynamically loaded. A unit established is executed. If
fetched procedure may not fetch a there is no on-unit, the standard
further procedure. system action for the CHECK condition
is taken. The situations in which the
CHECK condition is raised are
described in ·CHECK Condition·, in
section H, ·On-Conditions".

2. The variable can be of any storage

The CHECK statement causes the CHECK class, or DEFINED, or a parameter.
condition to be dynamically enabled for
specified or assumed names. 3. If the name of a structure or an array
of structures appears in the name
The PL/I checkout compiler implements list, this is expanded into a list of
the CHECK statement in this sense, but the the names of all the elements in the
PL/I optimizing compiler implements this structure or array of structures, in
statement by checking the syntax and then the order in which they were declared.
ignoring it. This expanded list appears in the name
list for the derived prefixes.
General format:
4. The information provided by standard
CHECK[(name-list)]; system action for the CHECK condition
for a particular name is:
Syntax rules:
a. The statement number of the
1. The optional "name-list- is one or statement in which the references
more names separated by commas. to the name occurs.

2. A name must be one of the following: b. Information similar to that put

out by a PUT DATA statement for
a. An unsubscripted variable the particular type of variable.
representing element, an array or
a structure of any data type. The If the name is the name of an array,
variable must not be iSUB-defined the information includes the
or locator qualified. subscripted name of the element to
which a new value is being assigned.
b. A label constant.
5. If the name is an entry name, this can
c. An entry constant. be specified as an entry constant or
an entry variable, whether it appears
3. If a name-list is specified, the CHECK in a function reference, a CALL
statement applies to those names only. statement, or an INITIAL CALL

section J: statements 445

 attribute. If the reference is to an DECLARE
entry variable, the information
provided by standard system action
includes the name of the entry Abbreviation: DeL
constant associated with the
particular invocation of the entry The DECLARE statement is the principal
variable. method for explicitly declaring attributes
of names.
6. A CHECK statement remains effective
until: General format:

a. The program terminates, or DECLARE

[level] identifier[attribute] •••
b. An appropriate NOCHECK statement [SYSTEM]
is executed. l,[level] identifier[attribute] •••
(SYSTEM]] ••• ;

Syntax rules:

1. Any number of identifiers may be

declared in one DECLARE statement.

The CLOSE statement dissociates the named 2. "Level" is a nonzero unsigned decimal
file from the data set with which it was integer constant. If a level number
associated by opening in the current task. is not specified, level 1 is assumed
for all element and array variables.
General format: Level 1 must be specified for all
major structure names. A blank space
CLOSE FILE(file-expr ) must separate a level number from the
[ENVIRONMENT({LEAVEIREREAD})] identifier following it.
[,FILE(file-expr )
[ENVIRONMENT({LEAVEIREREAD})]] ••• ; 3. Attributes specified in DECLARE
statements are separated by blanks.
General rul es : Except for the dimenSion, length, and
precision attribute specifications,
1. The FILE(file-expression) option they may appear in any order. The
specifies which file is to be closed. dimension attribute specification must
It must appear once. Several files immediately follow the array name; the
can be closed by one CLOSE statement. length and preciSion attribute
There must be a FILE option for each specifications must follow one of
one. their associated attributes. A comma
must follow the last attribute
2., A closed file can be reopened. specification for a particular- name
(or the name itself if no attributes
3. Closing an unopened file, or an are specified with it), unless it is
already closed file, has no effect. the last name in the DECLARE
statement, in which case the semicolon
4. The CLOSE statement cannot be used to is used.
close a file in a task different from
the one that opened the file. If a 4. "SYSTEM" specifies that the standard
file is not closed by a CLOSE default attributes are to be applied
statement, i t is automatically closed to the associated identifier;
at the completion of the task in which attributes are not taken from DEFAULT
i t was opened. statements. "SYSTEM" may appear
before, after, or between the other
6. All input/output events associated attributes.
with the file that have a status value
of zero when the file is closed are Factoring of Attributes
set complete, with a status value of
1. Attributes common to several names can
be factored in a declaration to eliminate
1. A CLOSE statement unlocks all records repeated specification of the same
in the file previously locked in the attribute for many identifiers. Factoring
task in which the CLOSE appears. is achieved by enclOSing the names in
parentheses, and following this by the set
8. The ENVIRONMENT attribute with either of attributes which apply. All factored
the REREAD or LEAVE options can be attributes must apply to all of the names.
given. No factored attribute can be overridden for

446 OS PL/I CRT AND OPT LRM PART II

any of the names, but any name within the DEFAULT
list may be given other attributes so long
as there is no conflict with the factored
attributes. Factoring of attributes is Abbreviation: OFT
permitted only in the DECLARE and DEFAULT
statement, but not within an ENTRY The DEFAULT statement allows the
attribute declaration. The dimension programmer to specify the default
attribute may be factored. The precision attributes to be applied to designated
and length attributes can be factored only identifiers that require implicit
in conjunction with an associated keyword declaration of some or all of their
attribute. Factoring can be nested as attributes. The DEFAULT statement can
shoWn in the fourth example below. specify default attributes for:

1. Explicitly declared identifiers

Names within the parenthesized list are
separated by commas. 2. contextually declared identifiers

3. Attributes to be included in parameter

Note: Structure level numbers can also be descriptors
factored, but a factored level number must
precede the parenthesized list. 4. Implicitly declared identifiers and
values returned from function
procedures
DECLARE (A,B,C,D) BINARY FIXED (31);
General format: See figure J.2.

DECLARE (E DECIMAL(6,5), General Rules:

F CHARACTER(10» STATIC:
1. Any attributes not applied according
to DEFAULT statement rules for any
DECLARE 1 A, 2(B,C,D) (3,2) BINARY partially complete explicit or
FIXED (15), ••• : contextual declarations, and for
implicit declarations, are supplied
DECLARE «A,B) FIXED(10), C FLOAT(S» according to standard default rules.
EXTERNAL:
2. There may be more than one DEFAULT
General rules: statement within a block. The scope
of a DEFAULT statement is the block in
1. A particular level 1 identifier can be which it occurs, and all blocks within
specified in only one DECLARE that block which neither include
statement within a particular block. another DEFAULT statement with the
All attributes given explicitly for same range, nor are contained in a
that identifier must be declared block having a DEFAULT statement with
together in that DECLARE statement. the same range.
(Note, however, that identifiers
having the FILE attribute may be given It is possible for a containing block
attributes in an OPEN statement as to have a DEFAULT statement with a
well. See "The OPEN statement" in range that is partly covered by the
this section and chapter 10, "Input range of a DEFAULT statement in a
and output" for further information.) contained block. In such a case, the
range of the DEFAULT statement in the
containing block is reduced by the
range of the DEFAULT statement in the
2. Attributes of external names, in contained block.
separate blocks and compilations, must
be consistent (except that an INITIAL For example:
attribute given in one declaration in
a procedure compiled by the optimizing P: PROCEDURE;
compiler need not be repeated). L1 : DEFAULT RANGE (XY) FIXED:

3. Labels may be prefixed to DECLARE

statements. However, a branch to such Q: BEGIN:
a label is treated as a branch to a L2: DEFAULT RANGE (XYZ) FLOAT:
null statement. Condition prefixes END Pi
cannot be attached to a DECLARE
statement. The range and scope of DEFAULT

Section J: Statements q47

r---------------------------------------------------------------------------------------,
DEFAULT {simple-specificationlfactored-specification}
(,{simple-specificationlfactored-specification}] •••

"simple-specification" is

RANGE ({identifier I letter: letter}

(,{identifierlletter:letter}] ••• )
[attribute-specification]

RANGE(.) [attribute-specification]

DESCRIPTORS [attribute-specification]

"factored-specification" is

({simple-specificationlfactored-specification}
[,(simple~specificationlfactored-specification}] ••• )
(attribute-specification]

"attribute-specification" is

attribute... (VALUE(VaIUe-specificatiOn)]}
{ VALUE (value-specification)
l---------------------------------------------------------------------------------------J
Figure J.2. General formats of the DEFAULT statement

statement Ll is all identifiers in the The base and scale attributes may be
procedure P beginning with the factored, if, when expanded, the above
characters XY, together with all format is used.
identifiers in begin block Q beginning
with the characters XY, except for
those beginning with the characters The size of AREA data, or length of
XYZ. The range and scope of the BIT or CHARACTER data, can be an
DEFAULT statement L2 is all the expression or a decimal integer
identifiers in begin block Q beginning constant, or can be specified as an
with characters XYZ. asterisk.

Example:
3. VALUE (value-specification) may appear
anywhere within an attribute DEFAULT RANGE(A:C)
specification, except before an array VALUE (FIXED DECIMAL(10),
dimension attribute. FLOAT DECIMAL(14),
AREA(2000»;
4. VALUE establishes any default rules DECLARE B FIXED DECIMAL, C FLOAT
for a string length, area size, and DECIMAL,
preCision. The base and scale A AREA;
attributes in the value specification
must be present to identify a These statements are equivalent to:
particular precision specification
with a particular attribute. DECLARE B FIXED DECIMAL(10), C FLOAT
DECIMAL(14), A AREA(2000);
5. A value specification is a list of one
or more of the following in any order; 6. RANGE deSignates the particular
identifiers to which the attributes
a. AREA (size) specified in a DEFAULT statement
apply.
b. BIT (length)
a. The form of RANGE(identifier) is
c. CHARACTER (length) used when the default rules are to
apply to those identifiers which
d. {base-attribute scale-attribute I contain the letters indicated in
scale-attribute base-attribute} "identifier" as their first and
(precision[,scale factor]) subsequent letters. For example:

448 OS PL/I CKT AND OPT LRM PART II

 RANGE (ABC) letter A, and FLOAT BINARY for those
with the initial letter B.
applies to these identifiers:
9. Labels may be prefixed to DEFAULT
~C statements. However, a branch to such
ABCD a label is treated as a branch to a
ABCD •••• etc. null statement. Condition prefixes
cannot be attached to a DEFAULT
but not to: statement.

ABO Rules for Attributes in a DEFAULT

ACB Statement:
AB
A 1. The file attributes (excluding FILE),
and the attributes ENTRY, ENVIRONMENT,
hence a single letter in the RANGE RETURNS, LIKE, and VARIABLE are not
specification applies to all permitted in an attribute
identifiers which start with that specification. If FILE is used, it
letter. implies a scope attribute of INTERNAL
and the attribute VARIABLE.
b. An alternative specification of
RANGE is the form "letter:letter" 2. It is not possible to use the DEFAULT
This is used to specify that statement to create a structure.
identifiers with initial letters Structure elements are given default
which either correspond to the two attributes according to the identifier
letters specified, or to any of the element, not the qualified
letters between the two in structure element name.
alphabetic sequence, are subject
to the default attributes 3. The following attributes are allowed
specified for a particular range. in an attribute specification only if
The letters given in the the restriction given below for each
specification must be in is observed.
increasing alphabetic order, for
example: AREA - without a size specification
BIT - without a string length
RANGE{A:G,I:M,T:Z) specification
CHARACTER - without a string length
c. RANGE(*> specifies all identifiers specification
in the scope of the DEFAULT LABEL - without a label list
statement. Arithmetic base and scale attributes -
without preciSion specifications
7. DESCRIPTORS specifies that the
associated attributes are to be 4. The CONTROLLED attribute cannot be
included in any parameter descriptors applied to a parameter or parameter
in a parameter descriptor list of an descriptor. For any identifier that
explicit entry declaration, provided is a parameter name, a specification
that the inclusion of any such of CONTROLLED as a default attribue
attributes is not prohibited by the will be ignored, and the attribute
presence of alternative attributes of will be ignored if it appears in a
the same class and provided that at DESCRIPTORS attribute specification.
least one attribute is already
present. From the second provision it 5. The dimensions of an array are
follows that the DESCRIPTORS default permitted as attributes, but only as
attributes are not applied to the first item in an attribute
parameters having null descriptors, specification. The bounds may be
that is, parameters whose attributes specified as a arithmetic constant or
match those of the corresponding an expreSSion involving variables.
argument. For example:

8. Factored-default-specification: this DEFAULT RANGE (J) (5);

form is used as follows: DEFAULT RANGE (J) (5,5) FIXED;

DEFAULT (RANGE (A)FIXED, RANGE (B) but not

FLOAT) BINARY;
DEFAULT RANGE (J) FIXED (5);
This statement establishes default
attributes FIXED BINARY for implicitly 6. The INITIAL attribute may be
declared identifiers with the initial specified.

section J: Statements 449

 organization must be INDEXED or key-
sequenced VSAM.

The DELAY statement causes the execution of 5. The EVENT option allows processing to
a task to be suspended for a specified continue while a record is being
period of time. deleted.

General format: When control reaches a DELETE

statement containing this option, the
DELAY (element-expression); -event variable- is made active (that
is, i t cannot be associated with
General rules: another event) and is given the
completion value loeB, provided that
1. Execution of the DELAY statement the UNDEFINEDFILE condition is not
causes the element expression to be raised by an implicit file opening
evaluated and converted to an integer (see -Note- below). The event
g; execution is then suspended for ~ variable remains active and retains
milliseconds. The value is recorded its loeB completion value until
to 1/50th or 1/60th second, depending control reaches a WAIT statement
on whether the frequency of the specifying that event variable. At
electrical supply to the machine is 50 this time, either of the following can
or 60 hertz (cycles per second). occur:

2. If no timing facility is available, a. If the DELETE statement has been

DELAY acts as a null statement. executed successfully and neither
of the conditions TRANSMIT or KEY
Example: has been raised as a result of the
DELETE, the event variable is set
DELAY (20); complete, given the completion
value 'l'B, and the event variable
This statement causes execution of the is made inactive, that is, can be
task to be suspended for 20 milliseconds or associated with another event.
11 milliseconds (approximately), depending
on whether the supply is 50 or 60 hertz. b. If the DELETE statement has
resulted in the raising of
TRANSMIT or KEY, the interrupt for
DELETE each of these conditions does not
occur until the WAIT is
encountered. At such time, the
The DELETE statement deletes a record from corresponding on-units (if any)
an UPDATE file. are entered in the order in which
the conditions were raised. After
General format: a return from the final on-unit,
or if one of the on-units is
DELETE FILE (file-expr) terminated by a GO TO statement,
[KEY(expression)] the event variable is given the
[EVENT(event-variable)]; completion value 'l'B and is made
inactive.
General rules:
Note: If the DELETE statement causes
1. The options may appear in any order. an implicit file opening that results
in the raising of UNDEFINEDFILE, the
2. The FILE option specifies the UPDATE on-unit aSSOCiated with this condition
file; i t must be specified. is entered immediately and the event
variable remains unchanged; that is,
3. The KEY option must be specified if the event variable remains inactive
the file is a DIRECT UPDATE file. It and retains the same value i t had when
can be specified for a SEQUENTIAL the DELETE was encountered. If the
UPDATE file with INDEXED or key- on-unit does not correct the
sequenced VSAM organization. The condition, then, upon normal return
expression is converted to a character from the on-unit, the ERROR condition
string and determines which record is is raised; if the condition is
to be deleted. corrected in the on-unit, that is, if
the file is opened successfully, then,
4. If the file is a SEQUENTIAL UPDATE upon normal return from the on-unit,
file, and the KEY option is omitted, the event variable is set to 'O'B, i t
the record to be deleted is the last is made active, and execution of the
record that was read; the data set DELETE statement continues.

450 as PL/I CKT AND OPT LRM PART II

6. The DELETE statement unlocks a record The completion part of the event
only if that record had been locked in variable will be given the value 'O'B
the same task in which the DELETE until the reply is completed, when it
appears. will be given the value 'l'B. The
reply is considered complete only
1. The DELETE statement can cause after the execution of a WAIT
implicit opening of a file. statement naming the event. Another
DISPLAY statement must not be executed
Example: until the previous reply is complete.
DELETE FILE(ALPHA) KEY (DKEY); Example:
This statement causes the record DISPLAY ('END OF JOB');
identified by DKEY to be deleted from the
data set associated with the file ALPHA. This statement causes the message "END
If the record was previously locked in the OF JOB" to be displayed.
same task, it is unlocked.

DISPLAY

The DISPLAY statement causes a message to The DO statement heads a do-group and can
be displayed to the machine operator. A also be used to specify repetitive
response may be requested. execution of the statements within the
group.
General format:
General formats:
option 1.
The three format types for the DO
DISPLAY (element-expression); statement are shown in Figure J-3.
option 2. Syntax rules:
DISPLAY (element-expression) 1. In all three types, the DO statement
REPLY (character- is used in conjunction with the END
variablelpseudovariable) statement to delimit a do-group. Only
[EVENT (event-variable)]; Type 1 does not provide for the
repetitive execution of the statements
General rules: within the group.
1. Execution of the DISPLAY statement 2. In Type 3, the variable or
causes the element expression to be pseudovariable must represent a Single
evaluated and, where necessary, element; "variable" may be subscripted
converted to a varying character and/or qualified. (The following
string of implementation-defined pseudovariables may not be used under
maximum length (126 characters ). the optimizing compiler: COMPLETION,
This character string is the message COMPLEX, PRIORITY, STRING.) Real
to be displayed. arithmetic variables are generally
used, but all variable types are
2. In Option 2, the character variable or allowed, provided that the expansions
pseudovariable receives a string that given in the general rules below
is a message to be supplied by the result in valid PL/I programs. Note
operator. The STRING pseudovariable that if ·variable· is a progra~
must not be used. The message cannot control variable, the BY and TO
exceed 126 characters. options cannot be used in
"specification·.
3. In Option 2, if the EVENT option is
not specified, execution of the 3. Each expression in a specification
program is suspended until the must be an element expression.
operator's message is received. In
option 1, execution continues 4. If ·BY expression3· is omdtted from a
uninterrupted. "specification," and if "TO
expression2· is included,
4. If the EVENT (event-variable) option ·expression3· is assumed to be 1.
is given, execution will not wait for
the reply to be completed before 5. If "TO expression2" 1s omitted from a
continuing with subsequent statements. ·specification,· and if ·BY

section J: Statements 451

lr---------------------------------------------------------------------------------------,
I Type 1. DO:
I
I
I WHILE(element-expreSSiOn) [UNTIL(element-expreSSiOn)]}
1 Type 2. DO { UNTIL (element-expression) [WHILE(element-expression)]

pseudovariable }
Type 3. DO = specification [,specification] ••• :
{ variable

where "specification" has the form:

r- -,
,
ITO expression2[BY expression311
,
expressionl ,BY expression3[TO expression21 I [WHILE(expression4)]1[UNTIL(expressionS)1:
, I
I REPEAT expression6 ,
L_ _J

1 The WHILE and UNTIL options may appear in either order.

L- ____________________________________________________ ----------------------------------J
Figure J.3. General formats of the DO statement

expression3" is included, repetitive LABEL: DO WHILE (expressionl)

execution continues until it is UNTIL (expression2):
terminated by the WHILE or UNTIL statement-l
clause or some statement causes
control to pass out of the group.
statement-n
6. If "REPEAT expression6" is included in END:
a specification, repetitive execution NEXT: statement /*STATEMENT
continues until it is terminated by FOLLOWING THE DO GROUP*/
the WHILE or UNTIL clause or some
statement causes control to pass out The abOve is exactly equivalent to the
of the group. following expansion:
7. If "TO expression2n, nBY expression3", LABEL: IF (expressionl) THEN: ELSE
and "REPEAT expression6" are all GO TO NEXT:
omitted from a specification, it statement-1
implies a Single execution of the
group, with the control variable
having the value of "expressionl".
The UNTIL clause is redundant is this statement-n
case, but, if "WHILE expression4" is LABEL2: IF (expression2) THEN: ELSE
included, the single execution will GO TO LABEL:
not take place unless "expression4" is NEXT: statement /*STATEMENT
true. FOLLOWING THE DO GROUP*/
General rules: If the UNTIL option is omitted, the IF
statement at label LABEL2 in the
1. In Type 1, the DO statement only expansion is replaced by the statement
delimits the start of ado-group: it GO TO LABEL:. If the WHILE option is
does not provide for repetitive omitted, the IF statement at label
execution. LABEL is replaced by a null statement.
Note that if the WHILE option is
2. In Type 2, the DO statement delimits omitted, statements 1 through ~ are
the start of a do-group and provides executed at least once.
for repetitive execution as defined by
the following: 3. In Type 3, the DO statement delimits

452 OS PL/I CRT AND OPr LRM PART II

the start of a do-group and provides LABEL: p=ADDR(variable):
for controlled repetitive execution. el=expression1;
v=el;
LABEL2: ;
If the specification includes the TO IF Cexpression4) XHEN:
or BY option, the action of the do- ELSE GO TO NEXT;
group is defined by the following: statement-l

LABEL: DO variable=
expressionl statement-m
TO expression2 LABELl: IF (expressionS) THEN
BY expression3 GO TO NEXT:
WHILE (expression4) LABEL3: v=expression6;
UNTIL(expressionS); GO TO LABEL2;
statement-l NEXT: statement
In the above expansions, p is a
compil,er-created pOinter: v is a
statement.;.m compiler-created based-variable based
LABELl: END: on p and with the same attributes as
NEXT: statement -variable-. -el," "e2,· and "e3" are
compiler-created variables having the
For a variable that is not a attributes of -expressionl,·
pseudovariable, this is exactly -expression2,- and -expression3,"
equivalent to the following expansion: respectively. Note that the
generation of the control variable is
LABEL: p=ADDR(variable): established once outside the loop,
el=expressionl; immediately before the initial value
e2=expression2: expression (expressionl) is evaluated.
e3=expression3:
v=el: Additional rules for the above
LABEL2: IF (e3>=O)& (v>e2)I expansions follow:
(e3<O)&(v<e2)
THEN GO TO NEXT; a. The above expansions only show the
IF (expression4) THEN: result of one ·specification." If
ELSE GO TO NEXT: the DO statement contains more
statement-l than one "specification," the
statement labeled NEXT is the
first statement in the expansion
for the next "specification." The
statement-m second expansion is analogous to
LABELl: IF (expressionS) THEN the first expansion in every
GO TO NEXT; respect. Note, however, that
LABEL3: v=v+e3: statements 1 through !!! are not
GO TO LABEL 2 ; actually duplicated in the
NEXT: statement program.
If the specification includes the b. If the WHILE clause is omitted,
REPEAT option, the action of the do- the IF statement immediately
group is defined by the following: preceding statement-l in each of
the expansions is omitted.
LABEL: DO variable=
expressionl c. If the UNTIL clause is omitted,
REPEAT expression6 the IF statement immediately
WHILE (expression4) following statement-m in each of
UNTIL(expressionS); the expansions is omitted.
statement-l
d. If -TO expression2- is omitted,
and -BY expression3" is included,
the statement "e2=expression2- and
statement-m the IF statement identified by
LABELl: END: LABEL2 in the first expansion are
NEXT: statement omitted.
For a variable that is not a e. If -BY expression3· is omitted,
pseudovariable, this is exactly and -TO expression2- is included,
equivalent to the following expansion: the statement "e3=expression3" in

Section J: statements 453

 the first expansion is replaced by represents the initial value of the
ne3=ln. control variable, and "expression6" is
an expression that is evaluated and
f. If nTO expression2", nBY aSSigned to the control variable after
expression3 n , and "REPEAT each execution of the statements in
expression6 n are all omitted, the the group.
first expansion applies. All
statements involving e2 and e3, as 8. Control may transfer into a do-group
well as the statement GO TO from outside the do-group only if the
LABEL2, are omitted. do-group is delimited by the DO
statement in Type 1; that is, only if
4. The WHILE clause in Types 2 and 3 repetitive execution is not specified.
specifies that, before each repetition consequently, repetitive do-groups
of statement execution, the associated cannot contain ENTRY statements.
element expressiop is evaluated, and,
if necessary, converted to a bit I 9. The generation of a control variable
string. If any bit in the resulting that is either pointer-qualified or
string is 1, the .statements of the do- controlled is established outside the
group are executed. If all bits are loop, immediately before the initial
0, then, for Type 2, execution of the value expression (expression1) is
do-group is terminated, while for Type evaluated. If the control variable
3, only the execution associated with generation is changed in the loop by
the "specification" containing the either changing its pointer or by
WHILE clause is terminated: repetitive allocating it, the loop is continued
execution for the next with the control variable derived from
-specification," if one exists, then the previous generation. However any
begins. reference to the control variable
inside the loop is a reference to the
5. The UNTIL clause in Types 2 and 3 subsequent generation. It is an error
specifies that, after each repetition to free the generation.
of statement execution, the associated
element expression is evaluated, and, 10. Under the optimizing compiler the
if necessary, converted to a bit maximum permissible depth of nesting
string. If all the bits in the is 49. There is no limit under the
resulting string are 0, the statements checkout compiler.
of the do-group are executed. If any
bit is 1, then, for Type 2, execution
of the do-group is terminated, while
for Type 3, only the execution
associated with the "specification"
containing the UNTIL clause is
terminated; repetitive execution for
the next "specification," if one
exists, then begins.
The END statement closes, or delimits,
6. In a ·specification" that contains Iblocks, do-groups, and select-groups.
the TO and BY options, "expressionl"
represents the initial value of the General format:
control variable .(i.e., "variable" or
"pseudovariable")'; -expression3" END [identifier];
represents the increment to be added
to the control variable after each Syntax rules:
execution of the statements in the
group: expression2 represents the The "identifier" is a label or entry
terminating value of the control constant: it cannot be subscripted.
variable. Execution of the statements
in a do-group terminates for a General rules:
"specification" as soon as the value
of the control variable, when tested 1. If a label follows END, the statement
at the end of the loop, is outside the closes the unclosed do-group, select-
range defined by "expressionl" and group, or block, headed by the nearest
-expression2.- When execution for the preceding DO, SELECT, BEGIN, or
last -specification" is terminated, PROCEDURE statement having that label.
control, in general, passes to the It also closes any unclosed do-groups,
statement following the do-group. select-groups, or blocks physically
within that group or block.
7. In a "specificatibn" that contains the
REPEAT option, "expression1" 2. If a label does not follow END, the

454 OS PL/I CKT AND 0Pl' LRM PART II

 statement closes that do-group, [NOMAPIN [(argument-list)]]
select-group, or block headed by the [NOMAPOUT[(argument-list)]]
nearest preceding DO, SELECT, BEGIN,
or PROCEDURE statement for which there The options are separated by blanks,
is no corresponding END statement. and can appear in any order.

3. If control reaches an END statement The "argument-list" is a list of the

for a procedure, it is treated as a names of the parameters to Which the
RETURN statement. option applies. Not more than sixty-
four parameters can be specified in an
argument list; they can appear in any
order, and are separated by commas or
blanks. If there is nO argument list,
the option is assumed to apply to all
the parameters associated with the
The ENTRY statement specifies a secondary entry name.
entry point of a procedure.
NOMAP, NOMAPIN, and NOMAPOUT can all
General format: appear in the same OPTIONS
specification. This specification
entry-constant: [entry-constant:] ••• should not include the same parameter
ENTRY [(parameter [,parameter] ••• )] in more than one specified or assumed
(RETURNS (attribute list)] argument list.
[IRREDUCIBLE I REDUCIBLE]
(OPTIONS(option-list)]; The use of these options is described
in chapter 19, nInterlanguage
Syntax rules: Communication Facilities".

1. The only attributes in the attribute General rules:

list of the RETURNS option that may be
specified with an ENTRY statement are 1. The relationship established between
the arithmetic, string, ALIGNED, the parameters of a secondary entry
UNALIGNED, POINTER, OFFSET, AREA,· pOint and the arguments passed to that
FILE, EVENT, LABEL, and TASK entry point is exactly the same as
attributes. strings can be given the that established tor primary entry
VARYING attribute. The OFFSET pOint parameters and arguments. See
attribute may include an area name; chapter 9, "Subroutines and
under the optimizing compiler, this Functions", for a complete discussion
must be a non-defined, unsubscripted, of this s ubj ect •
unqualified name. The LABEL attribute
may include a list of label constants. 2. As stated in syntax rule 1, the
An area size or string length must be attributes specified with an ENTRY
specified by a decimal integer statement determine the
constant. characteristics of the value returned
by the procedure when it is invoked as
2. A condition prefix cannot be specified a function at this entry point. The
for an ENTRY statement. value being returned by the procedure
(i.e., the value of the expression in
3. The options RETURNS, REDUCIBLE (or a RETURN statement) is converted, if
IRREDUCIBLE), and OPTIONS can appear necessary, to correspond to the
in any order. specified attributes. If the
attributes are not specified at the
4. The options REDUCIBLE and IRREDUCIBLE entry pOint, default attributes are
are for optimization. If they are to applied, according to the first letter
appear in a program processed by the of the entry name used to invoke the
checkout compiler, they are checked entry pOint.
for syntax errors and ignored; their
presence in such a program is not an 3. If an ENTRY statement has more than
error. one name, each name is interpreted as
though i t were a single entry name for
5. The noptions-list" of the OPTIONS a separate ENTRY statement having the
option specifies one or more same parameter list and explicit
additional implementation-defined attribute specification. For example,
options. These are: consider the statement:

{COBOL I FORTRAN} A: I: ENTRY;

(NOMAP [(argument-list)]] This statement is effectively the same

Section J: Statements 455

 as:

A: ENTRY; The EXIT statement causes immediate

termination of the task that contains the
I: ENTRY. statement and all tasks attached by this
task. If the EXIT statement is executed in
Since the attributes of the returned a major task, it is equivalent to a STOP
value are not explicitly stated, the statement.
characteristics of the value returned
by the procedure will depend on General format:
whether the entry pOint has been
invoked as A or I. EXIT;

4. The ENTRY statement must be internal General rule:

to the procedure for which i t defines
a secondary entry pOint. It may not If executed in a major task, EXIT causes
be internal to any block contained in the FINISH condition to be raised in that
this procedure; nor may i t be within a task. On normal return from the FINISH on-
do-group that specifies repetitive unit, the task executing the statement, and
execution. all of its descendant tasks are terminat-ed.
The completion values of the event
5. When an ENTRY statement is encountered variables associated with these tasks are
in normal sequential flow, control set to 'l'B, and their status values to 1
passes around it. (unless they are already non-zero).

6. IRREDUCIBLE and REDUCIBLE are

optimization options that can only be
specified for function procedures.
REDUCIBLE specifies that if the entry
name appears with an argument list
that is identical to an argument list The FETCH statement indicates to the
used in an earlier invocation, the compiler that the procedures identified by
function will not necessarily be the entry constants are resident on
reinvoked and the result of the auxiliary storage and will need to be
earlier evaluation may be used. copied into main storage if they are to be
IRREDUCIBLE specifies that this type executed. The FETCH statement, when
of optimization is not permitted. executed, causes a test to be made in main
Optimization within a function storage tor the named procedures. Any
procedure is not affected by either procedures found not to be already in main
attribute. If neither option is storage are loaded from auxiliary storage.
specified, IRREDUCIBLE is assumed. A similar test and loading is performed
whenever a procedure named in a FETCH
1. The meaning of the options in the statement is invoked by a CALL statement,
OPTIONS option is: by a CALL option of an INITIAL attribute,
or by a function reference, before an
COBOL: The PL/I procedure is to be attempt is made to execute that procedure.
invoked at this entry pOint by COBOL and FORTRAN routines ,cannot be
only a COBOL subprogram. fetched.

FORTRAN: The PL/I procedure is to be General format:

invoked at this entry point by
only a FORTRAN subroutine or FETCH entry-constant
function. (,entry-constantl ••• ;

NOMAP, NOMAPIN, NOMAPOUT: These General rules:

options prevent the automatic
manipulation of data aggregates at 1. The entry-constant must be a name by
the interface between either COBOL which the procedure to be fetched is
or FORTRAN and PL/I. known to the operating system.

Each option argument-list can Note: Details of the linkage-editing

specify the parameters to Which required for fetchable procedures are
the option applies. If there is given in the Programmer's Guide for
no argument-list for an option, the compiler.
that option is assumed to apply to
all the parameters associated with 2. The entry constant in the FETCH
the invocation of the entry name. statement must be the same as the one

456 OS PL/I CKT AND OPT LRM PART II

 used in the corresponding CALL I 4. The statement that causes a flow
statement, CALL option, or function comment to be written is a transfer
reference. statement; the statement to which
control is transferred is a
3. A fetched procedure may not fetch any destination statement. A summary of
further procedures. the transfer statements and their
destination statements is given below,
4. A FETCH statement will not overlap in figure J.4.
with other statements.
I 5. The FLOW statement remains effective
until:

a. The program terminates, or

b. The task terminates, or

The FLOW statement causes information about c. A NOFLOW statement is executed

the transfer of control within a task to be later in the same task.
written on the SYSPRINT file.

The PL/I checkout compiler implements

the FLOW statement in this sense, but the FORMAT
PL/I optimizing compiler implements this
statement by checking the syntax and then
ignoring it. The FORMAT statement specifies a format
list that can be used by edit-directed
General format: transmission statements to control the
format of the data being transmitted.
FLOW;
General format:
General rules:
label: [label:] ••• FORMAT (format-list);
1. When a FLOW statement has been
executed, the execution of a Syntax rules:
subsequent statement that causes a
transfer of control results in a flow 1. The "format list" must be specified
comment being written on the SYSPRINT according to the rules governing
file. format list specifications with edit-
directed transmission as described in
A flow comment consists of: chapter 10, "Input and output".

a. The number of the statement that 2. At least one "label" must be specified
causes the transfer of control for a FORMAT statement. One of the
labels (or a label variable or a
b. The number of the statement to function reference representing the
which control is transferred value of one of the labels) is the
statement label designator appearing
A flow comment is written after in a remote format item.
control is transferred, but before
execution of the target statement is General rules:
commenced.
1. A GET or PUT statement may include a
2. When a subtask is first attached, its remote format item, R, in the format
FLOW/NOFLOW status is the same as that list of an edit-directed data
of the attaching task at the point specification. That portion of the
where the CALL statement is executed. format list represented by R must be
Thereafter, the status of the subtask supplied by a FORMAT statement
can be altered only by FLOW and NO FLOW identified by the statement label
statements executed within the specified with R.
subtask.
2. The remote format item and the FORMAT
3. The flow comment is written only when statement must be internal to the same
the transfer of control is to a point block.
within the task that contains the FLOW
statement. If control passes to a 3. If a condition prefix is associated
point outside this task, (becaus€ the with a FORMAT statement, i t must be
task terminates), no further flow identical to the condition prefix
comments are written. associated with the GET or PUT

section J: Statements 457

r---------------------------------------------------------------------------------------,
Transfer statement I Destination Statement I

GO TO IStatement prefixed by GO TO label

CALL IPROCEDURE or ENTRY statement in the invoked

I procedure

END or RETURN statement in a procedure ICALL statement

invoked by a CALL statement I
END or RETURN statement that terminates ISTATIC or AUTOMATIC variable: PROCEDURE or
a procedure invoked by the INITIAL CALL IBEGIN statement of the block that contains
attribute Ithe DECLARE statement
IBASED or CONTROLLED variable: ALLOCATE
Istatement that specifies the variable

statement that contains a function IPROCEDURE or ENTRY statement in the

reference linvoked procedure

RETURN statement in a procedure invoked Istatement containing the function reference

as a function reference I
END statement of an iterative do-group IMatching DO statement, even if there are no
Imore iterations to be performed

Iterative DO statement, either when the Istatement that follows the matching END
statement list has been executed in full, I statement
or when the statement list is not to be I
executed I
END statement that terminates an IStatement to which the on-unit returns
on-unit, or a single statement (except Icontrol normally
GO TO or CALL) that is an on-unit I
Statement (including SIGNAL) that resultslFirst, or only, statement of the on-unit
in an interrupt for which there is an I
on-unit I

LEAVE Istatement to which control would be passed

lif the referenced do-group (explicit or
I implied) had terminated normally
SELECT IFirst statement of the "unit" following the
Iselected WHEN or OTHERWISE clause

After execution of a "Qnit" following IThe first executable statement following the
a WHEN or OTHERWISE clause, provided that Iselect-group
the unit does not alter the normal flow I
L---------------------------------------------------------------------------------------J
Figure J.4. Transfer and destination statements

statement referring to that FORMAT

statement.

The FREE statement causes the storage

4. When a FORMAT statement is encountered allocated for specified based or controlled
in normal sequential flow, control variables to be freed. For controlled
passes around it, and the CHECK variables, the next most recent allocation
condition will not be raised for a in the task is made available, and
statement label attached to it. subsequent references in the task to the
identifier refer to that allocation.

5. It is an error to attempt to transfer General format:

control to a FORMAT statement by means
of a GO TO statement. FREE option[,option] ••• :

458 OS PL/I CKT AND OPT LRM PART II

where -option" has one of two forms: is implied if the based variable is
qualified by an offset declared with
Option 1 an associated area. The IN option
cannot appear if the based variable
identifier was not allocated in an area. Note
that area assignment causes allocation
Option 2 of based storage in the target area:
such allocations can be freed by the
[locator-qualifier ->] IN option naming the target area.
based-variable-identifier
[IN(element-area-variable)]

Syntax rules:

1. In Option 1, the -identifier- is a

level-one, unsubscripted variable of
the controlled storage class. The GET statement is a STREAM transmission
statement that can be used in either of the
2. In Option 2, the nbased-variable- following ways:
identifier W must be an unsubscripted,
level-one based variable. 1. It can cause the assignment of data
from an external source (that is, from
3. It is permissible to use both types of a data set) to one or more internal
option in one statement. receiving fields (that is, to one or
more variables).
General rules:
2. It can cause the assignment of data
1. Controlled storage, and based storage from an internal source (that is, from
not in an area, that has been a character-string variable) to one or
allocated in a task cannot be freed by more internal receiving fields (that
any other task. is, to one or more variables).

General format:
2. If a specified nonbased identifier has
no allocated storage at the time the GET option-list:
FREE statement is executed, it is a
no-operation. Following is the format of -option
list-:
Rules 3 through 6 apply only to Option 2.
[FILE (file-expression)
3. If the based variable is not ISTRINGCcharacter-string-expression)]
explicitly qualified by locator [data-specification]
qualification, the locator declared [COPY[ (file-expression)]]
with the based variable will be used (SKIP[(expression)]]
to identify the generation of data
occupying the portion of storage to be General rules:
freed. If no locator has been
declared the statement is in error. 1. If neither the FILE option nor the
STRING option appears, the file option
4. The amount of storage freed depends FILE(SYSIN) is assumed.
upon the attributes of the based
variable, including bounds and/or 2. One data specification must appear
lengths at the time the storage is unless the SKIP option is specified.
freed, if applicable. The user is
responsible for determining that this 3. The options may appear in any order.
amount coincides with the amount
allocated. If the variable has not 4. The -file-expression- of the FILE
been allocated, the results are option represents a file which has
unpredictable. been aSSOCiated, by opening, with the
data set which is to provide the
5. A based variable can be used to free values. It must be a STREAM INPUT
storage only if that storage has been file.
allocated for a based variable having
identical data attributes. The wfile-expression- of the COpy
option represents a file associated
6. The IN option must be specified or with the data set Which is to receive
implied, if the storage to be freed the values. It must be a STREAM
was allocated in an area. The option OUTPUT file.

Section J: statements 459

 5. The "character-string-expression" current line. If the expression is
refers to the character string that is omitted, SKIP(l) is assumed. The SKIP
to provide the data to be assigned to option is always executed before any
the data list. This name may be a data is transmitted.
reference to a built-in function.
Each GET operation using this option 12. For the effect of statement options
always begins at the beginning of the when specified in the first GET
specified string. If the number of statement following the opening of the
characters in this string is less than file, see "OPEN statement" in this
the total number of characters section.
specified by the data specification,
the ERROR condition is raised.
6. When the STRING option is used under
data-directed transmission, the ERROR
condition is raised if an identifier
within the string does not have a Abbreviation: GOTO
match within the data specification.
The GO TO statement causes control to be
1. The "data-specification" is as transferred to the statement identified by
describe-d in chapter 11, "Stream- the specified label.
Oriented Transmission".
General format:
8. If the FILE option refers to a file
that is not open in the current task, element-Iabel-expreSSiOn;}
the file is implicitly opened in the GOTO
task for stream input transmission. { statement-number;

If the COpy option refers to a file Syntax rules:

that is not open in the current task,
the file is implicitly opened in the 1. 'Element-label-expression' can be used
task for stream output transmission. in a GO TO statement in a source
program, or in a GO TO entered in
9. The COpy option, which cannot be used immediate mode.
with the STRING option, specifies that
the source data stream, as read, is to 2. 'Statement-number' can only be used in
be written, without alteration, on the a GO TO immediate statement entered at
specified file. Each new record in the terminal when running under the
the input stream starts a new record checkout compiler.
on the COpy file. If nO file is
specified, the default is standard General rules:
print file SYSPRINT.
1. An element-Iabel-expression is a label
10. If an interrupt during the execution constant, a label variable, or a
of a GET statement with a COpy option function reference that returns a
causes an on-unit to be entered in label value. Since a label expression
which another GET statement is may have different values at each
executed for the same file, and if execution of the GO TO statement,
control is returned from the on-unit control may not always pass to the
to the interrupted statement, then same statement.
resumed execution of that statement
will be as if no COPY option had been 2. A GO TO statement cannot pass control
specified. If, in the on-unit, a PUT to an inactive block or to another
statement is executed for the file task.
associated with the COpy option, the
position of the data tranSmitted will 3. A GO TO statement cannot trans fer
not necessarily be immediately control from outside a do-group to a
following the most recently- statement inside the do-group if the
transmitted COpy data item. do-group specifies repetitive
execution, unless the GO TO terminates
11. The SKIP option causes a new current a procedure or on-unit invoked from
line to be defined for the data set. within the do-group.
The expression, if present, is
converted to an integer w, which must 4. If a GO TO statement transfers control
be greater than zero. If not, the from within a block to a point not
compiler substitutes a value of 1. contained within that block, the block
The data set is positioned at the is terminated. Also, if the transfer
start of the !th line relative to the point is contained in a block that did

460 OS PL/I CKT AND OPT LRM PART II

 not directly activate the block being Syntax rules:
terminated, all intervening blocks in
the activation sequence are also
terminated (see chapter 8, "storage 1. Each unit is either a Single statement
control-, for examples and details). (except DO, SELECT, END, PROCEDURE,
When one or more blocks are terminated BEGIN, DECLARE, DEFAULT, FORMAT, or
by a GO TO statement, conditions are ENTRY), a do-group, a select-group, or
reinstated and automatic variables are a begin block.
freed just as if the blocks had
terminated in the usual fashion.
2. The IF statement itself is not
5. When a GO TO statement specifies a terminated by a semicolon: however,
label constant contained in a block each -unit- specified must be
that has more than one activation, terminated by a semicolon.
control is transferred to the
activation current when the GO TO is 3. Each -unit- may be labeled and may
executed. have condition prefixes.
6. When a GO TO statement transfers General rules:
control out of a procedure that has
been invoked as a function, the 1. The element expression is evaluated
evaluation of the expression that and, if necessary, converted to a bit
contained the corresponding function string. When the ELSE clause (that
reference is discontinued. is, ELSE and its following -unital is
specified, the following occurs:
If any bit in the string is 1, -unit-
1- is executed, and control passes to
the statement following the IF
statement. If all bits in the string
have the value 0, "unit-1- is not
The HALT statement causes execution of a executed and -unit-2 is executed,
ft

task being executed in conversational mode after which control passes to the next
under the checkout compiler to be statement.
interrupted and control passed to the
terminal. When the ELSE clause is not specified,
the following occurs:
General format:
If any bit in the string is 1, -unit-
HALT: 1- is executed, and-control passes to
the statement following the IF
General rules: statement. If all bits are 0, -unit-
1- is not executed and control passes
1. The HALT statement is only effective to the next statement.
in a conversational environment. In a
non-conversational environment and Each -unit- may contain statements
under the optimizing compiler, the that specify a transfer of control
HALT statement is a null operation. (e.g., GO TO): hence, the normal
sequence of the IF statement may be
2. The HALT statement remains effective overridden.
until the programmer at the terminal
causes execution to be resumed. An array or structure variable can
appear in the element expression only
as an argument to a function that
returns an element value.
2. IF statements may be nested: that is,
either -unit-, or both, may itself be
The IF statement tests the value of a an IF statement. Since each ELSE
specified expression and controls the flow clause is always associated with the
of execution according to the result of innermost unmatched IF in the same
that test. block or do-group, an ELSE with a null
statement may be required to specify a
General format: desired sequence of control. Under
the optimizing compiler, the maximum
IF element-expression permissible depth of nesting is 49.
THEN unit-1 There is no restriction under the
[ELSE unit-21 checkout compiler.

Section J: Statements 461

 specified in REFER options are
initialized. A pointer value is
aSSigned to the pointer variable named
The LEAVE statement causes control to leave in the SET option or, if the SET
a do-group in the same way as if the group option is omitted, to the pOinter
had terminated normally. variable specified in the declaration
of the based variable. The pointer
General format: value identifies the record in the
buffer. After execution of the LOCATE
LEAVE [label-constant] statement, values may be assigned to
the based variable for subsequent
General rules: transmission to the data set, which
will occur immediately before the next
1. LEAVE is valid only within a do-group. LOCATE, WRITE, or CLOSE operation on
the file. The transmitted data item
2. If 'label-constant' is specified, it must not be referred after
must be a label of a containing do- transmission.
group.
3. If the KEYFROM option appears, the
3. If 'label-constant' is specified, the value of the expression is converted
do-group that is left is the group to a character string and is used as
headed by the DO statement that has the key of the record when it is
the specified label. If 'label- subsequently written.
constant' is omitted, the do-group
that is left is the group that 4. If the FILE option refers to an
immediately contains the LEAVE unopened file, the file is opened
statement. automatically: the effect is as if the
LOCATE statement were preceded by an
4. The LEAVE statement and the referenced OPEN statement referring to the file.
or implied DO statement must not be in The file is given the attributes
different blocks. RECORD and OUTPUT.

5. LEAVE cannot be the single statement

of an on-unit.

NOCHECK

LOCATE
The NOCHECK statement suppresses the action
of the CHECK statement for the specified
The LOCATE statement, which applies to names.
BUFFERED OUTPUT files, causes allocation of
a based variable in a buffer; it may also The PL/I checkout compiler implements
cause transmission of a based variable the NOCHECK statement in this sense, but
previously allocated in a buffer. the PL/I optimizing compiler implements
this statement by checking the syntax and
General format: then ignoring it.

LOCATE variable FILE(file-expression) General format:

[SET(pointer-variable)]
[KEYFROM(expression»): NOCHECK [(name-list)];

Syntax rules: Syntax rules:

1. The options may appear in any order. 1. The optional -name-list- is one or
more names separated by commas; a name
2. The -variable- must be an can be qualified, but cannot be
unsubscripted level 1 based variable. subscripted or locator-qualified.

General rules: 2. A name must be one of the following:

1. The FILE option specifies the file a. An element, an array or a

involved. This option must appear. structure variable of any data
type.
2. Execution of a LOCATE statement causes
the specified based variable to be b. A label constant.
allocated in the buffer. Components
of the based variable that have been c. An entry constant.

462 OS PL/I CKT AND OPT LRM PART II

 3. If a name-list is specified, the reaches the null statement.
NOCHECK statement applies to those
names only. These names must be known General format:
in the block in which the NOCHECK
statement is executed. [label:] ••• ;

If there is no name-list, the NOCHECK Note that a label prefixed to a null

statement applies to every name in the statement does not compare equal to a label
program. prefixed to the statement immediately
following the null statement.
General rules:
For example:
1. Execution of a NOCHECK statement has
the effect of disabling the CHECK A:;
condition for specified or assumed B: X=T;
names. The condition-prefix can be an
actual prefix, written in the program, Label A does not compare equal to label B.
or a conceptual prefix, derived from a
previous CHECK statement.

2. The NOCHECK statement remains

effective until:

a. The program terminates, or The ON statement specifies what action is

to be taken (programmer-defined or standard
b. It is overidden by an appropriate system action) when an interrupt results
CHECK statement. from the occurrence of the specified
exceptional condition.

General format:
NOFLOW
ON condition [SNAP] {SYSTEM; lon-unit}

The NOFLOW statement suppresses the action Syntax rules:

of the FLOW statement.
1. The condition may be any of those
The PL/I checkout compiler implements described in section H, "On-
the NOFLOW statement in this sense, but the Conditions".
PL/I optimizing compiler implements this
statement by checking the syntax and then 2. The "on-unit" represents a programmEr-
ignoring it. defined action to be taken when an
interrupt results from the occurrence
General format: of the specified "condition". It can
be either a single unlabeled simple
NOFLOW; statement or an unlabeled begin block.
If it is an unlabeled simple
General rules: statement, it can be any simple
statement except BEGIN, DO, LEAVE,
1. The NOFLOW statement remains effective SELECT, END, RETURN, FORMAT,
until: PROCEDURE, ENTRY, DECLARE, or DEFAULT.
If the on-unit is an unlabeled begin
a. The program terminates, or block, any statement can be used
freely within that block, with two
b. The task terminates or exceptions: a RETURN statement can
appear only within a procedure nested
c. It is overridden by a FLOW within the begin block; a LEAVE
statement. statement can appear only within a do-
group nested within the begin block.

3. Since the "on-unit" itself requires a

Null statement semicolon, no semicolon is shown for
the "on-unit" in the general format.
However, the word SYSTEM must be
The null statement causes no action and followed by a semicolon.
does not modify sequential statement
execution. If the label of a null General rules:
statement is enabled for the CHECK
condition, CHECK is raised whenever control 1. The ON statement determines how an

Section J: Statements 463

 interrupt occurring for the specified block, the effect of the prior ON
condition is to be handled. Whether statement is completely nullified.
the interrupt is handled in a standard
system fashion or by a programmer- 3. An on-unit is always treated by the
supplied method is determined by the compiler as a procedure internal to
action specification in the ON the block in which it appears.
statement, as follows: (Conceptually, it is enclosed in
PROCEDURE and END statements.) Any
a. If the action specification is names referenced in an on-unit are
SYSTEM, the standard system action those known in the environment in
is taken. The standard system which the ON statement for that on-
action is not the same for every unit was executed, rather than the
condition, although for most environment in which the interrupt
conditions the system simply occurred.
prints a message and raises the
ERROR condition. The standard 4. A condition raised during execution
system action for ,each condition results in an interrupt if and only if
is given in section H, ·On- the condition is enabled at the point
Conditions·. (Note that the where it is raised.
standard system action is always
taken if an interrupt occurs and a. The conditions AREA, OVERFLOW,
no ON statement for the condition FIXEDOVERFLOW, UNDERFLOW,
is in effect.) ZERODIVIDE, CONVERSION, all of the
input/output conditions, and the
b. If the action specification is an conditions CONDITION, FINISH,
"on-unit," the programmer has ATTENTION, and ERROR are enabled
supplied his own interrupt- by default.
handling action, namely, the
action defined by the statement(s) b. The conditions SIZE, STRINGSIZE,
in the on-unit itself. The on- STRINGRANGE, SUBSCRIPTRANGE, and
unit is not executed when the ON CHECK are disabled by default.
statement is executed; it is
executed only when an interrupt c. The enabling and disabling of
results from the occurrence of the OVERFLO~I, FIXEDOVERFLOW,
specified condition (or if the UNDERFLOW, ZERODIVIDE, CONVERSION,
interrupt results from the SIZE, STRINGSIZE, STRINGRANGE,
condition being signaled by a SUBSCRIPTRANGE, and CHECK can be
SIGNAL statement). controlled by condition prefixes.

2. The action specification (i.e., "on- 5. If an on-unit is a Single statement,

unit" or SYSTEM) established by it cannot refer to a remote format
executing an ON statement in a given specification.
block remains in effect throughout
that block and throughout all blocks 6. If SNAP is specified, then ~hen the
in any activation sequence initiated given condition occurs and the
by that block, unless it is overridden interrupt results, a list of all of
by the execution of another ON the blocks and on-units active at the
statement or a REVERT. statement, as time the interrupt occurred is printed
follows: on SYSPRINT, followed by the FLOW
table. This table is the same as
a. If a later ON statement specifies would be produced by a PUT FLOW
the same condition as a prior ON statement. The list of blocks and on-
statement and this later ON units, and the FLOW table, are printed
statement is executed in a block by the both the checkout and the
that lies within the activation optimizing compilers.
sequence initiated by the block
containing the prior ON statement, 7. Under the optimizing compiler, up to
the action specification of the 49 on-units may be concurrently active
prior ON statement is temporarily in anyone block, and up to 254 in any
suspended, or stacked. It can be one compilation. There are no limits
restored either by the execution under the checkout compiler.
of a REVERT statement, or by the
termination of the block
containing the later ON statement.

b. If the later ON statement and the

prior ON statement are internal to
the same invocation of the same The OPEN statement associates a file name

464 OS PL/I CKT AND OPT LRM PART II

with a data set. It also can complete the names. If the file name is a
specification of attributes for the file, parameter, the identifier of the
if a complete set of attributes has not original argument passed to the
been declared for the file being opened. parameter, rather than the identifier
of the parameter itself, is used as
General format: the identification.
OPEN FILE (file-expr) (options-group]
[,FILE(file-expr) (options-group]] ••• : 3. The LINESIZE option can be specified
only for a STREAM OUTPUT file. The
where "options-group" is as follows: expression is evaluated, converted to
an integer, and used as the length of
lDIRECTISEQUENTIALITRANSIENT] a line during subsequent operations on
[BUFFERED I UNBUFFERED] the file. New lines may be started by
[STREAMIRECORDJ use of the printing and control format
[INPUT I OUTPUT I UPDATE] items or by options in a GET or PUT
[KEYED] [EXCLUSIVE] statement. If an attempt is made to
[BACKWARDS] position a file past the end of a line
[TITLE (element-expression)] before explicit action to start a new
[PRINT] line is taken, a new line is
[LINESIZE(element-expression)] automatically started, and the file is
[PAGESIZE(element-expression)] positioned to the start of this new
line. The following implementation-
Syntax rules: defined values apply:
1. The INPUT, OUTPUT, UPDATE, STREAM, Maximum line size:
RECORD, DIRECT, SEQUENTIAL, TRANSIENT,
BUFFERED, UNBUFFERED, KEYED, F- or U-format: 32,759
EXCLUSIVE, BACKWARDS, and PRINT V-format 32,751
options specify attributes that
augment the attributes specified in Minimum line size:
the file declaration; for rules
governing which of these attributes F- or U-format 1
can be applied together, see chapter V-format: PRINT files 9
11, "Input and "output", and the Non - PRI NT FILES 10
corresponding attributes in section I,
"Attributes". Default line size 120

2. The options in an "option-group" and The LINESIZE option cannot be

the FILE option for a file may appear specified for an INPUT file. The line
in any order. Size taken into consideration whenever
a SKIP option appears in a GET
3. The "file-expression" represents the statement is the line size, if any,
name of the file that is to be that was used to create the data set;
associated with a data set. Several otherwise, the line size is taken to
files can be opened by one OPEN be the current length of the logical
statement. record (minus control bytes, for V-
format records).
General rules:
4. The PAGESIZE option can be specified
1. The opening of an already open file only for a file having the STREAM and
does not affect the file if t.he second PRINT attributes. The element
opening takes place in the same task expression is evaluated and converted
or an attached task. In such cases, to an integer, which represents the
any expressions in the "options-group" maximum number of lines to a page.
are evaluated, but they are not used. During subsequent transmission to the
PRINT file, a new page may be started
2. If the TITLE option is specified, the by use of the PAGE format item or by
"element-expression" is converted to a the PAGE option in the PUT statement.
character string, if necessary, the If a page becomes filled and more data
first eight characters of which remains to be printed before action to
identify the data set (the ddname) to start a new page is taken, the ENDPAGE
be associated with the file. If this condition is raised. The following
option does not appear, the first implementation-defined values apply:
eight characters of the file name
(padded or truncated) are taken to be Maximum page size 32,767
the ddname. Note that this is not the Minimum page size 1
same truncation as that for external Default page size 60

section J: Statements 465

I 5. When a non-print STREAM file is FILE, EVENT, LABEL, and TASK
opened, it is conceptually positioned attributes are allowed. Strings can
as if i t had just completed scanning be given the VARYING attribute. The
of the zeroth record - that is, it is OFFSET attribute may include an area
positioned at the end of an imaginary name; under the optimizing compiler,
record immediately preceding the this must be a non-defined,
record accessed in the first GET or unsubscripted, unqualified, area name.
PUT statement. Thus if the first GET The LABEL attribute may include a list
or PUT specifies, by means of a of label constants. An area size or
statement option or format item, that string length must be specified by a
n lines are to be skipped before the decimal integer constant.
first record is accessed, the file is
then positioned at the start of tne
nth record. 2. OPTIONS, RECURSIVE, RETURNS, ORDER,
REORDER, REDUCIBLE and IRREDUCIBLE,
When a PRINT file is opened, it is can appear in any order and are
physically positioned at column 1 of separated by blanks.
line 1 of the first page. However, if
the first PUT statement specifies that
n lines are to be skipped, the file is 3. The options ORDER, REORDER, REDUCIBLE
treated as though it were positioned and IRREDUCIBLE are for optimization.
at the end of line 0; that is, the PUT If they ar~ included in a program
statement causes the file to be processed by the checkout compiler,
positioned at the start of line n. they are checked for syntax errors and
ignored; their presence in such a
program is not an error.

PROCEDURE
4. The ·options-list" of the OPTIONS
option specifies one or more
The PROCEDURE statement has the following additional implementation-defined
functions: options. These are:

• It heads a procedure. {MAINI COBOL I FORTRAN}

• It defines the primary entry pOint to (NOMAP(argurnent-list)]]

the procedure. [NOMAPIN[{argument-list)]]
[NOMAPOUT[{argument-list)]]
• It specifies the parameters, if any, for
the primary entry pOint. [REENTRANT]

• It may specify certain special [TASK]

characteristics that a procedure can
have. The options are separated by blanks or
commas, and can appear in any order.
• It may specify the attributes of the
value that is returned by the procedure The "argument-list" is a list of the
if it is invoked as a function at its names of the parameters to which the
primary entry point. option applies. Not more than sixty-
four parameters can be specified in an
General format: argument list; they can appear in any
order and are separated by commas or
entry-constant: [entry-constant:] ••• blanks. If there is no argument list,
PROCEDURE[{parameter[,parameter] ••• )] the option is assumed to apply to all
[OPTIONS (option-list)] the parameters associated with the
[RECURSIVE] [RETURNS {data attributes)] entry name.
[ORDER I REORDER]
[REDUCIBLEIIRREDUCIBLE]; NOMAP, NOMAPIN, and NOMAPOUT can all
appear in the same OPTIONS-attribute
Syntax rules: specification. This specification
should not include the same parameter
1. The "data attributes" given in the in more than one specified or assumed
RETURNS option represent the argument list.
attributes of the value returned by
the procedure when it is invoked as a The use of COBOL, FORTRAN, NOMAP,
function at its primary entry pOint. NOMAPIN, and NOMAPOUT is described in
Only arithmetic, string, ALIGNED, chapter 19, "Interlanguage
UNALIGNED, POINTER, OFFSET, AREA, Communication Facilities·.

466 OS PL/I CKT AND OPT LRM PART II

Note: which the procedure has been invoked)
is used to determine the default base,
a. The TASK option need not be precision, and scaie. (Since the
specified for procedures to be entry point can have several entry
processed by the checkout or constants, the default base,
optimizing compilers. However, it precision, and scale can differ
may be required if these according to the entry constant.)
procedures are processed by other
PL/I compilers. 5. ORDER and REORDER are optimization
options. ORDER and REORDER specify
b. The REENTRANT option applies to the extent to which the block is to be
code produced by a PL/I compiler; optimized. In general, ORDER permits
if this option is specified with optimization to the degree such that
either the COBOL or FORTRAN the latest values of all variables set
options, this has no effect on the in a block are guaranteed available in
code in the COBOL or FORTRAN a computational on-unit entered during
program. A program that calls execution of the block. REORDER
COBOL or FORTRAN routines is not permits a greater degree of
reenterable. optimization; with REORDER the values
of variables set in the block are not
c. The TASK option must not be guaranteed to be the most recently
specified with either the COBOL or assigned values in an on-unit entered
the FORTRAN options. during execution of the block. If
neither option is specified, ORDER is
General rules: assumed but REORDER is inherited by
all contained blocks unless they
1. When the procedure is invoked, a explicitly specify ORDER.
relationship is established between
the arguments passed to the procedure 6. IRREDUCIBLE and REDUCIBLE are
and the parameters that represent optimization options that can only be
those arguments in the invoked specified for function p~ocedures.
procedure. This topic is discussed in REDUCIBLE specifies that. if the entry
chapter 9, ·Subroutines and name appears with an arg~ment list
Functions·. that is identical to an argument list
used in an earlier invocation, the
2. OPTIONS may be specified only for an function will not necessarily be
external procedure, and at least one reinvoked and the result of the
external procedure must have the earlier evaluation may be used.
OPTIONS (MAIN) designation; if more IRREDUCIBLE specifies that this type
than one is so designated, the of optimization is not permitted.
operating system will invoke the one Optimization within a function
that appears first, physically. procedure is not affected by either
attribute. If neither option is
3. RECURSIVE must be specified if the specified, IRREDUCIBLE is assumed.
procedure might be invoked
recursively; that is, if it might be 1. If a PROCEDURE statement has more than
reactivated while it is still active. one entry constant, the first constant
If specified, it applies to all of the can be considered as the only label of
entry points (primary and secondary) the statement; each subsequent entry
that the procedure might have. It constant can be considered as a
applies only to the procedure for separate ENTRY statement having an
which i t is declared. identical parameter list as specified
in the PROCEDURE statement. For
4. The ·data attributes· in the RETURNS example, the statement:
option specify the attributes of the
value returned by the procedure when A: I: PROCEDURE (X);
it is invoked as a function at its
primary entry point. The value is effectively the same as:
specified in the RETURN statement of
the invoked procedure is converted to A: PROCEDURE (X);
conform with these attributes before
i t is returned to the invoking I: ENTRY (X);
procedure.
Since the attributes of the value are
If the RETURNS option is not not explicitly stated, the characters
specified, default attributes are of the value returned by the procedure
supplied. In such a case, the name of will depend on whether the procedure
the entry point (the entry constant by has been invoked as A or I.

Section J: Statements &I 67

 8. The meaning of the options in the [ALL[(character-string-expression)]]
OPTIONS option is: PAGE lLINE(element-expreSSiOn)]]
SKIP (element-expression)]
COBOL: The PL/I procedure is to be [ LINE (element-expression)
invoked at its main entry point by
only a COBOL subprogram.
Syntax rules:
FORTRAN: The PL/I procedure is to be
invoked at its main entry point by 1. If neither the FILE nor STRING option
only a FORTRAN subroutine or function. appears, the specification FILE
(SYSPRINT) is assumed. If such a PUT
MAIN: The PL/I procedure is the statement lies within the scope of a
initial procedure of a PL/I program, declaration of the identifier
and is invoked by the operating-system SYSPRINT, SYSPRINT must have been
control program as the first step in declared as FILE STREAM OUTPUT. If
the execution of that program. the PUT statement does not lie within
the scope of a declaration of
NOMAP, NOMAPIN, NOMAPOUT: These SYSPRINT, SYSPRINT is the standard
options prevent the automatic system output file.
manipulation of data aggregates at the
interface between either COBOL or 2. The FILE option specifies transmission
FORTRAN and PL/I. to a data set on an external medium.
The file expression in this option is
Each option argument-list can specify the name of the file that has been
the parameters to which the option associated (by impliCit or explicit
applies. If there- is no argument list opening) with the data set that is to
for an option, that option is assumed receive the values. This file must
to apply to all the parameters have the OUTPUT and STREAM attributes.
associated with the invocation of the
entry name. 3. Under the checkout compiler, the SNAP
option causes a list of all currently
REENTRANT: The code produced by the active blocks and on-units to be
compiler is reenterable. printed on SYSPRINT. Under the
optimizing compiler, the option's
TASK: The PL/I multitasking syntax is checked, then it is ignored.
facilities are to be used.
4. Under the checkout compiler, the FLOW
option causes a comment on each of the
last ~ transfers of control to be put
into the SYSPRINT stream. The rules
determining the nature of each flow
comment are the same as for the FLOW
The PUT statement is a STREAM transmission statement, described earlier in this
statement that can be used in either of the section. If ~ is not specified, the
following ways: value specified in the appropriate
compiler option is used; if no value
1. It can cause the values in one or more is specified there, a default of 25 is
internal storage locations to be taken. Under the optimizing compiler,
transmitted to a data set on an the syntax of the option is checked,
external medium. then it is ignored.

2. It can cause the values in one or more 5. Under the checkout compiler, the ALL
internal storage locations to be option causes all information provided
assigned to an internal receiving by the SNAP and FLOW options to be put
field (represented by a character- into the SYSPRINT stream, together
string variable). with certain other debugging
information. A description of this
3. Under the checkout compiler, it can information is given in chapter 15,
cause program checkout information to -Execution-time Facilities of the
be written onto the SYSPRINT file. Checkout Compiler-. Under the
optimizing compiler, the syntax of the
General format: option is checked, then it is ignored.
The value of the character-string-
PUT [FILE (file-expression)] I expre~sion must be one or more of the
[STRING (character-string-variable)] option characters O,S,F,C,T,n
[data-specification] I concatenated to form a string without
[SNAP] I blanks or punctuation marks, n being
[FLOW [ (n)]] I one through four digits.

468 OS PL/I CKT AND OPT LRM PART II

 6. The STRING option specifies line to be defined for the data set.
transmission from internal storage The expression, if present, is
locations (represented by variables or converted to an integer ~, which for
expressions in the "data- non-PRINT files must be greater than
specification") to a character string zero. The data set is positioned at
(represented by the "character-string- the start of the wth line after the
variable"). It cannot be used with a current line. If-the expression is
SNAP, FLOW, or ALL option. The omitted, SKIP(l) is assumed.
"character-string-variable" can be any
string pseudovariable other than
STRING. For PRINT files w may be less than or
equal to zero: in this case, the
7. The "data specification" option is as effect is that of a carriage return
described in chapter 11, "Stream- with the same current line. If less
Oriented Transmission". than w lines remain on the current
page when a SKIP(w) is issued, ENDPAGE
8. The PAGE, SKIP, and LINE options is raised.
cannot appear with the STRING option.

9. The options may appear in any order: When a SKIP option is specified On the
at least one must appear. first PUT statement of a file, the
data set is positioned at the start of
General rules: the ~h line on the first page. If ~
is zero or one, it is positioned at
1. If the FILE option is specified, and the start of the first line.
the "file-expression" refers to an
unopened file, the file is opened
implicitly as an OUTPUT file. When printing at a terminal in
conversational mode, no more than
2. If the STRING option is specified, the three lines may be skipped: SKIP(w)
PUT operation begins assigning values with w greater than 3 is equivalent to
to the beginning of the string (that SKIP(3).
is, at the left-most character
position), after appropriate
conversions have been performed. 6. The LINE option causes a new current
Blanks and delimiters are inserted as line to be defined for the data set.
usual. If the string is not long The expression is converted to an
enough to accomodate the data, the integer!!.. The LINE option specifies
ERROR condition is raised. that blank lines are to be inserted so
that the next line will be the wth
3. The PAGE and LINE options can be line of the current page. If at least
specified for PRINT files only. All !! lines have already been written on
of the options take effect before the current page or if ~ exceeds the
transmission of any values defined by limits set by the PAGESIZE option of
the data specification, if given. Of the OPEN statement, the ENDPAGE
the three, only PAGE and LINE may condition is raised. If w is less
appear in the same PUT statement, in than or equal to zero, it-iS assumed
which case, the PAGE option is applied to be 1. If ~ specifies the current
first. line, ENDPAGE is raised except when
the file is posi~ioned on column 1: in
4. The PAGE option causes a new current this case, the effect is as for a
page to be defined within the data' SKIP(O) option.
set. If a data specification is
present, the transmission of values
occurs after the definition of the new If the LINE option is specified in the
page. The page remains current until same statement as a PAGE option, the
the execution of a PUT statement with PAGE option is executed first.
the PAGE option, until a PAGE format
item is encountered, or until the
ENDPAGE condition is raised, resulting When printing at a terminal in
in the definition of a new page. A conversational mode, the LINE option
new current page implies line one. causes three lines to be skipped.

When printing at a terminal in 1. For the effects of statement options

conversational mode, the PAGE option when specified in the first PUT
causes three lines to be skipped. statement follOWing the opening of the
file, see ·OPEN statement" in this
5. The SKIP option causes a new current section.

Section J: Statements 469

r---------------------------------------------------------------------------------------,
r-- --, --,
r-- I KEY (expression) (NOLOCKJ I I
I (INTO(variable)] I IlEVENT(event-variable)JI
I IKEYTO(character-string-variable)I I
I L-- --J I
I r-- ---, I
FILE I I KEY (expression) I I
(filename) IlSET(pointer-variable)] I I I
I IKEYTO(character-string-variable) I I
I L-- ---J I
I I
I lIGNORE(expression)] (EVENT(event-variable)] I
L-- --J
l---------------------------------------------------------------------------------------J
Figure J.5. Format of option list for READ statement

file is positioned to the record

having the specified key. Thereafter,
records may be read sequentially from
The READ statement causes a record to be that point on by using READ statements
transmitted from a RECORD INPUT or RECORD without the KEY option. (See general
UPDATE file to a variable or buffer. rule 11.)

General format:
6. The KEYTO option can be given only if
READ option-list; the file has the SEQUENTIAL and KEYED
attributes. It specifies that the key
The format of the option list is shown of the record being read is to be
in figure J.5. assigned to the "character-string
variable" according to the rules for
General rules: character-string assignment. The
KEYTO option can specify any string
1. The options may appear in any order. pseudovariableother than STRING. It
cannot specify a variable declared
2. The FILE option specifies the file with a numeric picture specification.
from which the record is to be read. The maximum permissible length for the
This option must appear. If the file character string is 256.
specified is not open in the current
task, it is opened. Assignment to the KEYTO variable
always follows assignment to the INTO
3. The INTO(variable) option specifies variable. If an incorrect key
the variable into which the record is specification is detected, the KEY
to be read. If· the variable is an condition is raised. For this
aggregate, it must be in connected implementation, the value assigned is
storage; certain uses of unaligned as follows:
fixed-length bit strings are
disallowed (for details, see "Data a. For REGIONAL(l), the eight
Transmitted" in chapter 12, "Record- character region number, padded or
Oriented Transmission"). truncated on the left to the
declared . 1ength of the character-
string variable. If the
4. The KEY and KEYTO options can be character~string variable is of
specified for KEYED files only. varying length, any leading zeros
in the region number are truncated
5. The KEY option must appear if the file and the string length is set to
has the DIRECT attribute. The the number of significant digits.
"element-expression" is converted to a An all-zero region number is
character string that represents a truncated to a single zero.
key. It is this key that determines
which record will be read. b. For REGIONAL(2} and REGIONAL(3),
the recorded key without the
The KEY option may also appear for a region number, padded or truncated
file having INDEXED or VSAM on the right to the declared
organization and the SEQUENTIAL and length of the character-string
KEYED attributes. In such cases, the variable.

410 OS PL/I CRT AND OPT LRM PART II

 c. For INDEXED and for indexed VSAM, and is made inactive.
the recorded key, padded or
truncated on the right to the Note: If the READ statement causes an
declared length of the character- implicit file opening that results in
string variable. the raising of UNDEFINEDFlLE, the on-
unit associated with this condition is
d. For entry-sequenced VSAM data entered immediately and the event
sets, a 4-character relative-byte variable remains unchanged; that is,
address, padded or truncated on the event variable remains inactive
the right to the declared length and retains the same value it had when
of the character-string variable. the READ was encountered. If the on-
unit does not correct the condition,
e. For relative-record VSAM data then, upon normal return from the on-
sets, an 8-character relative- unit, the ERROR condition is raised;
record number with leading zeros if the condition is corrected in the
suppressed, truncated or padded on on-unit, that is, if the file is
the· left to the declared length of opened successfully, then, upon normal
the character string. return from the on-unit, the event
variable is set to 'O'B, i t is made
The KEY condition will not be raised active, and execution of the READ
for such padding or truncation. statement continues.

7. The EVENT option allows processing to 8. Any READ statement referring to an

continue while a record is being read EXCLUSIVE file will cause the record
or ignored. This option cannot be to be locked unless the NOLOCK option
specified for a SEQUENTIAL BUFFERED is specified. A locked record cannot
file. be read, deleted, or rewritten by any
other task until it is unlocked. Any
When control reaches a READ statement attempt to read, delete, rewrite, or
containing this option, the "event unlock a record locked by another task
variable" is made active (that is, i t results in a wait. Subsequent
cannot be associated with another unlocking can be accomplished by the
event) and is given the complet~on locking task through the execution of
value loeB, provided that the an UNLOCK, REWRITE, or DELETE
UNDEFINEDFlLE condition is not raised statement that specifies the same key,
by an implicit file opening (see by a CLOSE statement, or by completion
"Note" below). The event variable of task in which the record was
remains active and retains its lOeB locked.
completion value until control reaches
a WAIT statement specifying that event Note that a record is considered
variable. At this time, either of the locked only for tasks other than the
following can occur: task that actually locks it; in other
words, a locked record call always be
a. If the READ statement has been read by the task that locked it and
executed successfully and none of still remain locked as far as other
the conditions ENDFlLE, TRANSMIT, tasks are concerned (unless, of
KEY or RECORD has been raised as a course, the record has been explicitly
result of the READ, the event unlocked by one of the above methods).
variable is set complete (given
the completion value 'l'B), and 9. The SET option specifies that the
the event variable is made record is to be read into a buffer and
inactive, that is, it can be that a pointer value is to be assigned
associated with another event. to the named locator variable. The
pointer value identifies the record in
b. If the READ statement has resulted the buffer.
in the raising of ENDFILE,
TRANSMIT, KEY, or RECORD, the 10. The IGNORE option may be specified for
interrupt for each of these SEQUENTIAL INPUT and SEQUENTIAL UPDATE
conditions does not occur until files. The expression in the IGNORE
the WAIT is encountered. At such option is evaluated and converted to
a time, the corresponding on-units an integer. If the value, ~, is
(if any) are entered in the order greater than zero, ~ records are
in which the conditions were ignored; a subsequent READ statement
raised. After a return from the for the file will access the (n+1)th
final on-unit, or if one of the record. If n is less than 1, the
on-units is terminated by a GO TO option has nO effect. A READ
statement, the event variable is statement without an INTO, SET, or
given the completion value 'l'B IGNORE option is equivalent to a READ

Section J: Statements 471

 with an IGNORE(1). RETURN

111. A file with INDEXED or VSAM

organization that is being accessed The RETURN statement terminates execution
sequentially may be positioned by of the procedure that contains the RETURN
issuing a READ statement with the KEY statement. If the procedure has not been
option. The specified key will be invoked as a task, the RETURN statement
used to identify the record required. returns control to the invoking procedure.
Thereafter, records may be read The RETURN stat€ment may also return a
sequentially from that point by use of value.
READ statements without the KEY
option. This applies to INPUT and General format:
UPDATE files.
Option 1.
Two poSitioning statements can be
used, with the following formats: RETURN;

READ FILE (file-expression) INTO Option 2.

(variable) KEY (expression);
RETURN (element-expression):
READ FILE (file-expression) SET
(pointer-variable) KEY Gener.al rules:
(expression);
1. Only the RETURN statement in Option 1
12. The EVENT, IGNORE, KEY and NOLOCK can be used to terminate procedures
options cannot be used with a not invoked as function procedures:
TRANSIENT file. control is returned to the pOint
logically following the invocation.

Option 1 represents the only form of

the RETURN statement that can be used
to terminate a procedure initiated as
a task. If the RETURN statement
terminates the major taSk, the FINISH
condition is raised prior to the
RELEASE execution of any termination
processes. If the RETURN statement
terminates any other task, the
The RELEASE statement frees for other completion value of the associated
purposes main storage occupied by event variable (if any) is set to
procedures identified by the specified 'l'B, and the status value is left
entry constants. Also, whenever a unchanged.
procedure named in a RELEASE statement is
invoked by a CALL statement, a CALL option 2. The RETURN statement in Option 2 is
of an INITIAL attribute or a fUnction used to terminate a procedure invoked
reference, and is found not to be resident as a function procedure only. Control
in main storage, a search is made for the is returned to the point of
procedure on auxiliary stor~ge. If it is invocation, and the value returned to
found, it is copied into main storage the function reference is the value of
before any attempt is made to execute it. the expression specified converted to
conform to the attributes declared for
General format: the invoked entry point. These
attributes may be explicitly specified
RELEASE entry-constant at the entry point; they are otherwise
[,entry-constant] ••• ; implied by the initial letter of the
entry name through which the procedure
General rules: is invoked.

1. At execution time, the only effect of Note: The optimizing compiler

the RELEASE statement is to free the provides object code to convert every
necessary storage. It has nO effect RETURN statement expression to the
on the meaning or scope of the entry- RETURNS attributes of every entry
constant. point of the procedure. Some of these
conversions may be invalid and may
2. The entry-constant must be the same as cause diagnostic messages to be
the one used in any corresponding CALL produced when the procedure is
statements or options, or function compiled. At execution time, however,
references, and FETCH statements. only the conversion applicable to the

472 OS PL/I CKT AND OPT LRM PART II

 invoked entry point is performed. 1. The options may appear in any order.
3. If control reaches an END statement 2. The "file-expression" represents the
corresponding to the end of a name of the file containing the record
procedure, this END statement is to be rewritten. The file must have
treated as a RETURN statement (of the the UPDATE attribute.
option 1 form) for the procedure.
3. The FROM option specifies a variable
that represents the record that will
replace the existing record in the
specified file. If the variable is an
REVERT aggregate, it must be in connected
storage; certain uses of unaligned
fixed-length bit strings are
The REVERT statement is used to cancel the disallowed (for details, see "Data
effect of the latest relevant ON Transmitted" in chapter 12, "Record-
statement. It can affect only ON Oriented Transmission").
statements that are internal to the block
in which the REVERT statement occurs o.nd General rules:
which have been executed in the same
invocation of that block. Execution of the 1. If the file referred to by "file-
REVERT statement in a given block cancels expression" has not been opened, i t is
the action specification of any ON opened implicitly with the attributes
statement for the named condition that has RECORD and UPDATE.
been executed in that block; it then re-
establishes the action specification that 2. The KEY option must appear if the file
was in force at the time of activation of has the DIRECT attribute; it can
the block. appear if the file has the SEQUENTIAL
attribute and is associated with a
General format: VSAM data set. It must not appear for
other SEQUENTIAL files. The element-
REVERT condition; expression is converted to a character
string. This character string is the
Syntax rule: source key that determines which
record is to be rewritten.
The "condition" is any of those
described in section H, "On-Conditions". 3. For SEQUENTIAL files with INDEXED
organization, if the key is an
General rule: embedded key, the user must take care
that the rewritten key is the same as
The execution of a REVERT statement has the key in the replaced record.
the effect described above only if (1) an
ON statement, specifying the same condition 4. The FROM option must be specified for
and internal to the same block, was UPDATE files having either the DIRECT
executed after the block was activated and attribute or both the SEQUENTIAL and
(2) the execution of no other similar UNBUFFERED attributes. A REWRITE
REVERT statement has intervened. If either statement in which the FROM option has
of these two conditions is not met, the not been specified has the following
REVERT statement is treated as a null effect:
statement.
a. If the last record was read by a
READ statement with the INTO
option, REWRITE without FROM has
REWRITE nO effect on the record in the
data set.

The REWRITE statement can be used only for b. If the last record was read by a
update files. It replaces an existing READ statement with the SET
record in a data set. option, the record will be updated
by whatever assignments were made
General format: in the buffer identified by the
pointer variable in the set
REWRITE FILE (file-expression) option. When the records are
[FROM(variable)] blocked, a REWRITE statement
[KEY (element-expression)J issued for any record in the block
[EVENT (event-variable)]; causes the complete block to be
rewritten even i f no REWRITE
Syntax rules: statements are issued for other

Section J: Statements 473

 records in the block. is made active, and execution of the
REWRITE statement continues.
5. The EVENT option allows processing to
continue while a record is being 6. If the record rewritten is one that
rewritten. This option must not be was locked in the same task, it
specified for a SEQUENTIAL BUFFERED becomes unlocked.
file.

When control reaches a REWRITE

statement containing this option, the SELECT
event variable is made active (that
is, it cannot be associated with The SELECT statement heads a select-group.
another event) and is given the
completion value loeB, provided that General format:
the UNDEFINEDFILE condition is not
raised by an implicit file opening SELECT [(expression-1)];
(see "Note- below). The event [ [(condition-prefix
variable remains active and retains [,condition-prefix] ••• ) :]
its loeB completion value until WHEN(expression-2,
control reaches a WAIT statement [,expression-2] ••• ) unit ] •••
specifying that event variable. At [ {OTHERWISE OTHER} unit ]
this time, either of the following can END [identifier] ;
occur:

a. If the REWRITE statement has been

executed successfully and none of
the conditions TRANSMIT, KEY, or Syntax rules:
RECORD has been raised as a result
of the REWRITE, the event variable 1. Each "unit" is either a Single
is set complete (given the statement (except DO, SELECT, END,
completion value 'l'B), and the PROCEDURE, BEGIN, DECLARE, DEFAULT,
event variable is made inactive FORMAT, or ENTRY) or a do-group, a
(that is, it can be associated select-group, or a begin block.
with another event).
2. Each unit may be labeled and may have
b. If the REWRITE statement has condition prefixes.
resulted in the raising of
TRANSMIT, KEY, or RECORD, the 3. A select-group must be terminated by
interrupt for each of these an END statement.
conditions does not occur until
the WAIT is encountered. At such General rules:
time, the corresponding on-units
(if any) are entered in the order 1. The expression in the SELECT statement
in which the conditions were is evaluated and its value is saved.
raised. After a return from the The expressions in the WHEN clauses
final on-unit, or if one of the are then evaluated in turn and
on-units is terminated by a GO TO compared with the saved value. If an
statement, the event variable is expression is found that is equal to
given the completion value 'l'B the saved value, the evaluation of
and is made inactive. expressions in WHEN clauses is
terminated, and the "unit" after the
Note: If the REWRITE statement causes associated WHEN clause is executed.
an implicit file opening that results If no such expression is found, the
in the raising of UNDEFINEDFILE, the "unit" after the OTHERWISE clause is
on-unit associated with this condition executed.
is entered immediately and the event
variable remains unchanged, that is, 2. If "expression-1" is omitted, each
the event variable remains inactive "expression-2" is evaluated and
and retains the same value i t had when converted, if necessary, to a bit
the REWRITE was encountered. If the string. If any bit in the string is a
on-unit does not correct the 'l'B, the "unit" after the associated
condition, then, upon normal return WHEN clause is executed. If no
from the on-unit, the ERROR condition "expression-2" yields such a bit
is raised; if the condition is string, the "unit" after the OTHERWISE
corrected in the on-unit, that is, if clause is executed.
the file is opened successfully, then,
upon normal return from the on-unit, 3. After execution of a "unit" following
the event variable is set to loeB, it a WHEN or OTHERWISE clause, control

474 OS PL/I CKT AND OPT LRM PART II

 passes to the first executable ERROR condition the standard system
statement following the select-group, action is to terminate the task (after
unless the normal flow of control is raising the FINISH condition if the
altered within the wunit w• SIGNAL statement is in the major
task) •
4. If wexpression-lft is specified, each
"expression-2 ft must be such that the 2. The on-condition CONDITION can cause
comparison expression an interrupt only as a result of its
specification in a SIGNAL statement.
«expression-l)=(expression-2»
3. If the specified condition is
has a scalar bit value. disabled, no interrupt occurs, and the
SIGNAL statement becomes equivalent to
5. If the OTHERWISE clause is omitted and a null statement, unless, under the
execution of the select-group does not checkout compiler, the condition is
result in the selection of a ·unitW, SIZE, STRINGRANGE, or SUBSCRIPTRANGE,
the ERROR condition is raised. in which case standard system action
takes place.
6. A condition-prefix attached to the
SELECT statement applies only to the 4. If there is no current on-unit for the
evaluation of the expression in the specified condition, then the standard
SELECT statement itself, not to any system action for the condition is
other statements in the group. A performed.
condition-prefix attached to a WHEN
clause applies only to the evaluation
of the expressions in the WHEN clause
itself, not to the wunit· that follows
the WHEN clause.

7. Under the optimizing compiler, the

maximum permissible depth of nesting
of select-groups is 49. There is no
restriction under the checkout The STOP statement causes imm~diate
compiler. termination of the major task and all sub-
tasks

General format:
SIGNAL
STOP;

The SIGNAL statement simulates the General rule:

occurrence of an interrupt. It may be used
to test the current action specification Prior to any termination activity the
for the associated condition. FINISH.condition is raised in the task _in
which the STOP is executed. On normal
General format: return from the FINISH on-unit, all tasks
in the program are_terminated.
SIGNAL condition;

Syntax rule:

The "condition" is anyone of those

described in section H, "On-Conditions w•
UNLOCK
General rules:

1. When a SIGNAL statement is executed, The UNLOCK statement makes the specified
i t is as if the specified condition locked record available to other tasks for
has actually occurred. sequential operations on the record.
execution is interrupted and control
is transferred to the current on-unit General format:
for the_specified condition. After
the on-unit has been executed, UNLOCK option-list;
standard system action for the
condition is performed. This usually FollOWing is the format of Woption
results in control returning to the list":
statement immediately following the
SIGNAL statement. However, for the FILE (file-expression) KEY(expression)

Section J: Statements 475

 General rules: WAIT. Of course, if an on-unit
entered due to the WAIT is terminated
1. The options may appear in either abnormally, control might not pass to
order. the statement following the WAIT.
2. The FILE option specifies the file If the value of the expression is
involved, which must have the zero or negative, the WAIT statement
attributes UPDATE, DIRECT, and is treated as a null statement. If
EXCLUSIVE. the value of the expression is greater
than the number, n, of event names in
3. In the KEY option, the -expression- is the list, the value is taken to be n.
converted to a character string and If the statement refers to an array-
determines which record is unlocked. event name, then each of the array
elements contributes to the count.
4. A record can be unlocked only by the
task which locked it. 4. 1-f the event variable named in the
list has been associated with a task
in its attaching CALL statement, then
the condition in Rule 1 wil~ be
satisfied on termination of that task.
5. If the event variable named in the
The execution of a WAIT statement within an list is associated with an
activation of a block retains control for input/output operation initiated in
that activation of that block within the the same task as the WAIT, the
WAIT statement until certain specified condition in Rule 1 will be satisfied
events have completed. when the input/output operation is
completed. The execution of the WAIT
General format: is a necessary part of the completion
of an input/output operation. If
WAIT (event [,event] ••• ) prior to, or during, the WAIT all
[(element-expression)]; transmission associated with the
input/output operation is terminated,
Syntax rules: then the WAIT performs the following
action. If the transmission has
Each event is an event variable, or an finished without requiring any
array or (for the checkout compiler only) a input/output conditions to be raised,
structure consisting only of event the event variable is set complete
variables. (i.e., COMPLETION(event name) = 'liB).
If the transmission has been
General rules: terminated but has required conditions
to be raised, the event variable is
1. Control for a given block activation set abnormal (i.e., STATUS(event name)
remains within this statement until, = 1) and all the required on-
at possibly separate times during the conditions are raised. On return from
execution of the statement, the the last on-unit, the event variable
condition is set complete.
COMPLETION (event) = 'l'B 6. The order in which on-conditions for
different input/output events are
has been satisfied, for some or all of raised is not dependent on the order
the event names in the list. of appearance of the event names in
the list. If an on-condition for one
2. If the expression does not appear, all event is raised, then all other
the event names in the list must conditions for that event are raised
satisfy the above condition before before the WAIT is terminated or
control is passed to the next before any other input/output
statement 'in this task following the conditions are raised unless an
WAIT. abnormal return is made from one of
the on-units thus entered. The
3. If the optional expression appears, raising of ON conditions for one event
the expression is evaluated when the implies nothing about the completion
WAIT statement is executed and or termination of transmission of
converted to an integer. This integer other,events in the list.
specifies the number of events in the
list that must satisfy the above 1. If an abnormal return is made from any
condition before control for the block on-unit entered from a WAIT, the
passes to the statement following the associated event variable is set

476 OS PL/I CKT AND OPT LRM PART II

 complete, the execution of the WAIT is string is the source key that
terminated, and control passes to the specifies the relative location in the
point specified by the abnormal data set where the record is written.
return. For REGIONAL(2), REGIONAL(3), and
INDEXED, KEYFROM also specifies a
8. If some of the event names in the WAIT recorded key whose length is
list are associated with input/output determined by the KEYLEN subparameter
operations and have not been set or the KEYLENGTH option.
complete before the WAIT is terminated
(either because enough events have 3. The KEYTO option may be used to obtain
been completed or due to an abnormal the relative byte address (RBA) when a
return), then these incomplete events record is added to a VSAM entry-
will not be set complete until the sequenced data set, or the relative
execution of another WAIT referring to record number when a record is added
these events in this same task. to a VSAM relative record data set.
The value returned for an ESDS is a
character-string of length 4
representing an RBA. The value
returned for an RRDS is a character-
string of length 8, representing an
unsigned decimal integer with leading
The WRITE statement is a RECORD zeros suppressed.
transmission statement that transfers a
record from a variable in internal storage 4. The EVENT option allows processing to
to an OUTPUT or UPDATE file. continue while a record is being
Written. This option cannot be
General format: specified for a SEQUENTIAL BUFFERED
file; record transmisson and
WRITE FILE (file-expression) FROM proceSSing are automatically
(variable) overlapped in such a file.
[KEYFROM(element-expression)]
[KEYTO(character-string-variable)] When control reaches a WRITE statement
[EVENT(event-variable)]; containing this option, the "event
variable" is made active (that
Syntax rules: is, it cannot be associated with
another event) and is given the
1. The options may appear in any order. completion value loeB, provided that
the UNDEFlNEDFILE condition is not
2. The "file expression" specifies the raised by an implicit file opening
file in which the record is to be (see "Note" below). The event
written. This file must be a RECORD variable remains active and retains
file that has either the OUTPUT its loeB completion value until
attribute or the DIRECT and UPDATE control reaches a WAIT statement
attributes. specifying that event variable. At
this time, either of the fOllowing can
3. The FROM option specifies a variable occur:
that represents the record to be
written. If the variable is an a. If the WRITE statement has been
aggregate, it must be in connected executed successfully and none of
storage; certain uses of unaligned the conditions TRANSMIT, KEY, or
fixed-length bit strings are RECORD has been raised as a result
disallowed (for details see "Data of the WRITE, the event variable
Transmitted" in chapter 12, "Record- is set complete (given the
Oriented Transmission"). completion value 'l'B), and the
event variable is made inactive,
4. The KEYFROM AND KEYTO options cannot that is, it can be associated with
appear together in the same statement. another event.
General rules: b. If the WRITE statement has
resulted in the raising of
1. If the file is not open in a task, it TRANSMIT, KEY, or RECORD, the
is opened for that task implicitly interrupt for each of these
with the attributes RECORD and OUTPUT conditions does not occur until
(unless UPDATE has been declared). the WAIT is encountered. At such
time, the corresponding on-units
2. If the KEYFROM option is specified, (if any) are entered in the order
the "element expression" is converted in which the conditions were
to a character string" This character raised. After a return from the

section J: statements 477

 final on-unit, or if one of the General rules:
on-units is terminated by a GO TO
statemeht, the event variable is 1. When an identifier is active (and has
given the completion value ('l'B) been given a value if it is a
and is made inactive. preprocessor variable) any encounter
of that identifier within a
Note: If the WRITE statement causes nonpreprocessor statement will
an implicit file opening that results initiate replacement activity in all
in the raising of UNDEFINEDFILE, the cases except when the identifier
on-unit associated with this condition appears within a comment or within
is entered immediately and the event single quotes. For example, if the
variable remains unchanged; that is, source program contains the following
the event variable remains inactive sequence of statements:
and retains the same value it had when
the WRITE was encountered. If the on- ~DECLARE I FIXED, T CHARACTER;
unit does not correct the condition,
then, upon normal return from the on- ~DEACTIVATE Ii
unit, the ERROR condition is raised;
if the condition is corrected in the ~I = 15;
on-unit, that is, if the file is
opened successfully, then upon normal ~T = 'A(I)';
return from the on-unit, the event
variable is set to 'O'B, it is made S = I*T*3;
active, and execution of the WRITE
statement continues. ~I = 1+5;
5. The EVENT option cannot be used with a ';ACTIVATE I;
TRANSIENT file.
';DEACTIVATE T;
R = I*T*2;
Preprocessor Statements
then the preprocessed text generated
by the above would be as follows
All of the statements that can be executed (replacement blanks are not shown):
at the preprocessor stage are presented
al~habetically in this section. S = I*A(I)*3;
R = 20*T*2;
%ACTIVATE 2. If the identifier to which RESCAN or
NORESCAN refers is the name of a
preprocessor variable of type FIXED or
Abbreviation: ~ACT of a preprocessor procedure which
returns a FIXED value, replacement in
The appearance of an identifier in a the output stream occurs irrespective
%ACTIVATE statement makes it active and of which option is specified. If the
eligible for replacement; that is, any identifier to which RESCAN or NORESCAN
subsequent encounter of that identifier in refers is the name of a preprocessor
a nonpreprocessor statement, while the variable of type CHARACTER or of a
identifier is active, will initiate procedure which returns a CHARACTER
replacement activity. value then:
General format: a. RESCAN specifies that when the
identifier is scanned by the
I(label:] ••• ACTIVATE identifier preprocessor, replacement in the
[RESCANINORESCAN] (,identifier output stream takes place as
[RESCANINORESCAN]] ••• ; usual.
syntax rUles: b. NORESCAN specifies:
1. Each identifier must be a preprocessor (1) That when the identifier is
variable, a preprocessor procedure scanned bf the preprocessor,
name, or a preprocessor built-in it is replaced in the output
fv.Qction name. stream by that text which is
the current value of the
2. A IACTlv.ATE statement cannot appear variable named by the
within a preprocessor procedure. identifier, or by that text

478 OS PL/I CKT AND OPT LRM PART II

 which is the result of General rule:
invoking the procedure named
by the identifier. The deactivation of an identifier does
not strip it of its value, nor does it
(2) That this text is not to be prevent it from receiving new values in
res canned for further subsequent preprocessor statements.
replacement. Deactivation simply prevents any
replacement for a particular identifier
RESCAN is the default. from taking place. Deactivation of a
deactivated preprocessor identifier has nO
3. The execution of a %ACTIVATE statement effect.
to activate a preprocessor identifier
that is already activated has no
effect.
"DECLARE

Abbreviation: %DCL
'assignment statement
The 'DECLARE statement establishes an
identifier as a preprocessor variable or a
The %assignment statement is used to preprocessor procedure name and also serves
evaluate preprocessor expressions and to to activate that identifier.
assign the result to a preprocessor
variable. General format:

General format: "[label:] •••

DECLARE identifier
%[label:J ••• preprocessor-variable = {FIXED I CHARACTER I ENTRY I BUILTIN}
preprocessor-expression; [, identifier
{FIXEDICHARACTERIENTRYIBUILTIN}] ••• ;
General rule:
Syntax rules:
When the value assigned to a
preprocessor variable is a character 1. CHARACTER or FIXED must be specified
string, this character string should not if the "identifier" is a preprocessor
contain a preprocessor statement. variable; an entry declaration may be
optionally specified if the
"identifier" is a preprocessor
procedure name. The declaration of a
%DEACTIVATE preprocessor procedure entry name can
be performed explicitly by its
appearance as the label of a
Abbreviation: %DEACT 'PROCEDURE statement. This explicit
declaration however, does not cause
The appearance of an identifier in a the activation of the preprocessor
%DEACTIVATE statement makes it inactive and procedure name.
ineligible for replacement; that is, any
subsequent encounter of that identifier in 2. Only the attributes shown in the above
a nonpreprocessor statement will not format can be specified in a %DECLARE
initiate any replacement activity (unless, statement.
of course, the identifier has been
reactivated in the interim).
3. Factoring of attributes is allowed as
General format: for nonpreprocessor DECLARE
statements.
%[label:J ••• DEACTIVATE identifier
[,identifierJ ••• ; 4. Any label attached to a %DECLARE
statement is ignored by the scan.
Syntax rules:
General rules:
1. Each "identifier" must be either a
preprocessor variable, a preprocessor 1. No length can be specified with the
procedure name, or a preprocessor CHARACTER attribute. If CHARACTER is
built-in fUnction name. specified, it is assumed that the
associated identifier represents a
2. A %DEACTIVATE statement cannot appear varying-length character string that
within a preprocessor procedure. has no maximum length.

Section J: Statements 479

 2. A preprocessor variable declared with group is the same as the expansion for a
the attribute FIXED is also given the corresponding nonpreprocessor do-group and
attributes DECIMAL and (5,0) by wi,w Wml," "m2,· and "m3" have the same
default. meaning that the corresponding expressions
in a nonpreprocessor do-group have.
3. The scope of all preprocessor
variables, procedure names, and labels See "Preprocessor DO-GrOups· in chapter
is the entire source program scanned 16, "Compile-Time Facilities·, for a
by the preprocessor, not including any discussion and an example of its use.
preprocessor procedures that redeclare
such identifiers. The scope of a
declaration in a preprocessor
procedure is limited to that
procedure.

4. An entry declaration may be specified

for each preprocessor procedure in the
source program. It is used to The lEND statement is used in conjunction
activate the entry name. Each time a with 100 or IPROCEDURE statements to
preprocessor function is invoked, its delimit preprocessor do-groups or
arguments are converted if necessary preprocessor procedures.
to the attributes of the corresponding
parameters. General format:

See ·Preprocessor Procedures" in % [label:] ••• END [label];

·Compile-Time Facilities· in Part I,
for a discussion of the association of Syntax rule:
arguments and parameters at the time
of invocation. The label follOWing END must be a label
of a IPROCEDURE or 100 statement. Multiple
5. A preprocessor IDECLARE statement closure is permitted.
behaves as a %ACTIVATE statement when
it is encountered, and activates, with
theRESCAN option, all preprocessor
variables identified in the statement.
IGO TO
6. The BUILTIN attribute may only be
specified for SUBSTR, LENGTH,
INDEX, COUNTER, COMPILETIME, or Abbreviation: IGOTO
PARMSET. It indicates that the
associated identifier is the built-in The IGO TO statement causes the
function of the same name. preprocessor to continue its scan at the
specified label.

General format:

'[label:] ••• GO TO label;

The ~DO statement is used in conjunction General rules:

with a lEND statement to delimit a
preprocessor do-group. It cannot be used 1. The label following the keyword GO TO
in any other way. determines the point to Which the scan
will be transferred. It must be a
General format: label of a preprocessor statement,
although it cannot be the label of a

IUabel:1 ••• 00 [i=m1[::: ::: ::]]: 2.

preprocessor procedure.

A preprocessor GO TO statement
appearing within a preprocessor
Syntax rule: procedure cannot transfer control to a
point outside of that procedure. In
The Wift represents a preprocessor other words, the label following GO TO
variable, and ·ml," "m2," and "m3" are must be contained within the
preprocessor expressions. procedure.

General rule: 3. See ·IINCLUDE Statement· for a

restriction regarding the use of IGO
The expansion of a preprocessor do- TO with included text.

480 OS PL/I CKT AND OPT LRM PART II

 Syntax rules:

The ~IF statement can control the flow of 1. Each "ddname" and "member name" pair
the scan according to the value of a identifies the external text to be
preprocessor expression. incorporated into the source program.
This external text must be a member of
General format: a partitioned data set.

%[label:l ••• IF preprocessor-expression 2. A "ddname" specifies the ddname

~THEN preprocessor-clause-1 occurring in the name field of the
[%ELSE preprocessor-clause-21 appropriate DO statement. Its
associated "member name" specifies the
Syntax rule: name of the data set member to be
incorporated. If "ddname n is omitted,
A preprocessor clause is any single SYSLIB is assumed, and the SYSLIB DD
preprocessor statement other than %DECLARE, statement is required.
~PROCEDURE, ~END, or ~DO (percent symbol
included) or a preprocessor do-group 3. A %INCLUDE statement cannot be used in
(percent symbols included). otherwise, the a preprocessor procedure.
syntax is the same as that for non-
preprocessor IF statements. General rules:

General rules: 1. Included text can contain

nonpreprocessor and/or preprocessor
1. The preprocessor expression is statements.
evaluated and converted to a bit
string (if the conversion cannot be 2. The included text is scanned, in
made, i t is an error). If any bit in sequence, in the same manner as the
the string has the value 1, clause-1 source program: that is, preprocessor
is executed and clause-2, if present, statements arE executed and
is ignored: if all bits are 0, clause- replacements are made where required.
1 is ignored and clause-2, if present,
is executed. In either case, the scan 3. %INCLUDE statements can be nested. In
resumes immediately following the IF other words, included text also can
statement, unless, of course, a %GO TO contain "INCLUDE statements. A ~GO TO
in one of the clauses causes the scan statement in included text can
to resume elsewhere. transfer control to a pOint in ~he
source program or in any included text
2. %IF statements can be nested according at an outer level of nesting, but the
to the rules for nesting reverse is not permitted. An
nonpreprocessor IF statements. analogous situation exists for nested
do-groups that specify iterative
execution: control can be transferred
from an inner group to an outer,
"INCLUDE containing group, but not from an
outer group into an inner, contained
group. There is nO limit to the
The 'INCLUDE statement is used to include permissible depth of nesting.
(incorporate) strings of external text into
the source program being scanned. This 4. Preprocessor statements in included
included text can contribute to the text must be complete. It is not
preprocessed text being formed. permissible, for example, to have half
of a "IF statement in included text
General format: and half in the other part of the
source program.
The "INCLUDE statement is defined as
follows for these compilers: If the source program contained the
following sequence of statements:
%[label:l ••• INCLUDE
IDECLARE (FILENAME1, FILENAME2)
ddname-1 (member-name-1)} CHARACTER;
{
member-name-1 I FILENAME1 'MASTER' ;

,ddname-2 (member-name-2~ " FILENAME2 = 'NEWFILE':

... ,
[ ,member-name-2 J I INCLUDE DCLS;

Section J: Statements 481

 and if the SYSLIB member name DCLS General rules:
contained:
1. User-generated messages are filed
DECLARE (FILENAME1, FILENAME2) together with preprocessor-generated
FILE RECORD INPUT messages. Whether or not a particular
DIRECT KEYED ENVIRONMENT message is subsequently printed
(REGIONAL (3) KEYLENGTB(8) F depends upon its severity level and
RECSIZE(80»; the setting of the compiler FLAG
option.
then the following would be inserted into
the preprocessed text: 2. User-generated messages of severity U
cause immediate termination of
DECLARE (MASTER, NEWFILE) preprocessing and compilation. User-
FILE RECORD INPUT generated messages of severity S, E,
DIRECT KEYED ENVIRONMENT or W may cause termination of
(REGIONAL(3) KEYLENGTB(8) F compilation (or checkout compiler
RECSIZE(80»; execution), depending upon the setting
of the NOSYNTAX, NOCOMPILE, and NORUN
Note that this is a way in which a compiler options.
central library of file declarations can be
used, with each user supplying his own
names for the files being declared.
~null statement

The ~null statement can be used to provide

transfer targets for %GO TO statements. I~
is also useful for balanCing ELSE clauses
in nested IIF statements.
IINOTE
General format:

The INOTE statement enables the user to ~ [label:] ••• ;

generate a preprocessor diagnostic message
of specified text and severity.

General format: ~PROCEDURE

l[label:l ••• NOTE (message[,codel)

Abbreviation: ~PROC
Syntax rules:
The IPROCEDURE statement is used in
1. The nmessage· is a character-string conjunction with a lEND statement to
expression whose value is the required delimit a preprocessor procedure. Such a
diagnostic message. The message preprocessor procedure is an internal
should not exceed 256 characters. function procedure that can be executed
only at the preprocessor stage.
2. The ·code" is a FIXED expression whose
value indicates the severity of the General format:
message, as follows:
I label: [label:] ••• PROCEDURE
code severitI [(identifier [, identifierl ••• )]
[STATEMENT]
0 I RETURNS({CHARACTERIFIXED});
4 W
8 E syn~ax rules:
12 S
16 U 1. Each "identifier" is a parameter of
the function procedure; a maximum of
If ncode R is omitted, 0 is assumed. 63 may be specified.

3. If ·code" has a value other than those 2. One of the attributes CHARACTER or
listed above, a diagnostic message is FIXED must be specified in the RETURNS
produced and a default value is taken. attribute list to indicate the type of
If the value is less than zero or value retUrned by the function
greater than 16, severity U is procedure. There can be no default.
assumed. otherwise, the next higher
severity is assumed. General rules:

482 OS PL/I CKT AND OPT LRM PART II

 1. The only statements and groups that General format:
can be used within a preprocessor
procedure are: [label:] ••• RETURN
Cpreprocessor-expression);
a. the preprocessor assignment
statement General rule:

b. the preprocessor DECLARE statement The value of the preprocessor

expression is converted to the RETURNS list
c. the preprocessor do-group of attribute specified in the iPROCEDURE
statement before it is passed back to the
d. the preprocessor GO TO statement point of invocation. If the point of
invocation is in a nonpreprocessor
e. the preprocessor IF statement statement, replacement activity can be
performed on the returned value after that
f. the preprocessor null statement value has replaced the procedure reference.

g. the preprocessor RETURN statement Note that the rules for preprocessor
expressions do not permit the value
h. the preprocessor NOTE statement returned by a preprocessor procedure to
contain preprocessor statements.
i. the iPAGE listing control
statement.

j. the ISKIP listing control Listing Control Statements

statement.

k. the 'PRINT listing control iCONTROL

statement

1. the INOPRINT listing control The checkout compiler FORMAT option, when
statement specified, may be activated and deactivated
by the iCONTROL statement. Onder the
All of these statements and the do- optimizing compiler, the syntax of the
group must adhere to the syntax and statement is checked, then it is ignored.
general rules given for them in
this section, except that, for 'a' General format:
through 'he, the initial percent
symbols must be omitted. ICONTROLCFORMATINOFORMAT):

2. A GO TO statement appearing in a syntax rules:

preprocessor procedure cannot transfer
control to a point outside of that 1. To influence formatting of a listing,
procedure. the statement must be on a line w~th
no other statements.
3. As implied by general rule 1,
preprocessor procedures cannot be 2. The statement will have no effect if
nested. it appears within a comment. The
statement must not appear in another
4. A preprocessor procedure can be statement.
invoked by a function reference in a
preprocessor statement or a General rules:
preprocessor procedure, or, if the
function procedure name is active, by 1. The ICONTROL statement has no effect
encountering that name in a if the FORMAT compiler option has not
nonpreprocessor statement. been specified.

2. The FORMAT compiler option is

nullified if more ICONTROL statements
Preprocessor RETURN have been executed with the NOFORMAX
option than with the FORMAT option:
the result is as if the FORMAT option
The preprocessor RETURN sta~ement can be had not been specified. In all other
used only in a preprocessor procedure and, cases, the ICONTROL statement has nO
therefore, can have no leading J. It effect on the format.
returns a value as well as control back to
the point from which the preprocessor 3. The statement may be used with or
procedure was invoked. without the preprocessor.

section J: Statements 483

 4. The ICONTROL statement is printed in
the formatted listing. It is also
retained in the text passed to the
compiler, but is ignored by the The statement following a "PAGE statement
compiler. in the program listing is printed on the
Ifirst line of the next page. Examples of
5. If the preprocessor is used, and a Ithe effects of the "PAGE statement are
"CONTROL statement is written on the Ishown in figure J.6
same line as one or more other
statements, the preprocessor moves the General format:
ICONTROL so that it is on a line of
its own in the text passed to the "PAGE:
compiler.
Syntax rules:
1. To cause formatting to take place, the
statement must be on a line with no
IINOPRINT other statements.
I
I 2. The statement will have no effect if
IThe INOPRINT statement causes printing of it appears within a comment. The
the source and insource listings to be statement must not appear in another
suspended from the following statement. statement.
General format: General rules:
"NOPRINT; 1. The statement may be used with or
without the preprocessor. It will
Syntax rules: control both the insource and the
source listing.
1. To cause printing to be suspended, the
statement must be on a line with no 2. After being put into effect, the
other statements. SPAGE; is not printed by the
preprocessor and is deleted from the
2. The statement will have no effect if text by the compiler; it does not
it appears within a comment. It must appear in the formatted listing.
not appear within another statement.
3. If the preprocessor is used, and a
General rules: "PAGE statement is written on the same
line as one or more other statements,
1. The statement may be used with or the preprocessor moves the "PAGE so
without the preprocessor. It will that it is on a line of its own in the
control both the insource and the text passed to the compiler. The
source listinq. insource listing is therefore not
formatted, but the source listing is.
2. The INOPRINT statement causes printing
of the insource and source listings to 4. When the preprocessor is used, an
be suspended. No further statements identifier that is split across the
are printed Until a IPRINT statement end of a line that contains a "PAGE
is encountered. statement is concatenated to form one
word. The second part of the word is
3. If the preprocessor is used, text moved onto the same line as the first
included by a IINCLUDE statement part if there is sufficient space on
inherits the print/noprint status that that line, otherwise the concatenated
was in effect when the IINCLUDE word is printed at the start of a new
statement was executed. INOPRINT and line.
"PRINT statements in the included text
affect the included text only; the
original status is restored at the end
of the included text. ,
4. If the preprocessor is not used,
included text inherits the
,,
,SPRINT

print/noprint status that was in I The SPRINT statement causes printing of the
effect when the IINCLUDE status was ,source and insource listings to be resumed
executed. In this case, however, the ,from the following statement.
original status is not restored at the I
end of the included text. , General format:

484 OS PL/I CKT AND OPT LaM PART II

 "PRINT: 1. To cause formatting to take place, the
statement must be on a line with nO
Syntax rules: other statements.
1. To cause printing to be resumed, the
statement must be on a line with no 2. The statement will have no effect if
other statements. it appears within a comment. The
statement must not appear in another
2. The statement will have no effect if statement.
it appears within a comment. It must
not appear within another statement.
3. n must be a decimal integer constant
General rules: in the range 1 through 999. Omdssion
of the option is equivalent to
1. The statement may be used with or specifying the value 1 for n.
without the preprocessor. It will
control both the insource and the
source listing. General rules:
2. "print" is the default for both the 1. The statement may be used with or
insource and the source listings, without the preprocessor. It will
provided that the relevant compiler control both the insource and the
options are specified. source listing.
3. If the preprocessor is used, text
included by a IINCLUDE statement 2. After being put into effect, the "SKIP
inherits the print/noprint status that statement is not printed by the
was in effect when the "INCLUDE preprocessor and is deleted from the
statement was executed. "NOPRINT and text by the compiler; it does not
"PRINT statements in the included text appear in the formatted listings.
affect the included text only: the
original status is restored at the end
of the included text. 3. If the preprocessor is used, and a
"SKIP statement is written on the same
4. If the preprocessor is not used, line as one or more other statements,
included text inherits the the preprocessor moves the "SKIP so
print/noprint status that was in that it is on a line of its own in the
effect when the IINCLUDE status was text passed to the compiler. The
executed. In this case, however, the insource listing is therefore not
original status is not restored at the formatted, but the source listing is.
end of the included text.
4. When the preprocessor is used, an
identifier that is split across the
end of a line that contains a "SKIP
statement is concatenated to form one
word. The second part of the word is
moved onto the same line as the first
The specified number of lines following a part if there is sufficient space on
ISKIP statement in the program listing are that line, otherwise the concatenated
Ileft blank. Examples of the effects of the word is printed ~t the start of a new
IISKIP statement are shown in figure J.6. line.
General Format 5. If n is greater than the number of
lines remaining on the page, the
"SKIP [ (n) ] : equivalent of a "PAGE statement is
executed in place of the ISKIP
Syntax rules: statement.

Section J: Statements 485

 r---------------------------------------------------------------------------------------,
Programmer's I Insource Listing Source I Source Listing after
~ I
Code I Listing without Preprocessor, preprocessing I
A=B; 'A=B; A=B;
%SKIP(2); ,
C=D; I
I C=D; C=D;
---------------------------------------------------------------------------------------
X=2; JSKIP(l); I X=2; ~SKIP(l); X=2;
Y=O; ,Y=O;
, Y=O;
---------------------------------------------------------------------------------------
B1='1'B; I B1='1'B; B1='1'B;
%SKIP;B2='0'B; , ~SKIP;B2='O'B;
, B2='0'B;
P=O; ••• ISKIP(l);SIG P=O; ••• ISKIP(l);SIG P=O; •••
NAL CONVERSION; NAL CONVERSION;
(G of SIGNAL in SIGNAL
last posn. in line) CONVERSION;
RES=SQRT(X); DCL Z FLOAT; at DCL Z FLOAT; at
IPAGE: start of new page start of new page
DCL Z FLOAT;
OPEN FILE (Fl); No skip to new page PUT CREC 1); at
%PAGE; PUT (REC_1): start of-new page

END LOOP 3B;%PAGE;A No skip to new page ALLOCATE A 3; at

LLOCATE A 3: start of new page
(A of ALLOCATE in
last posn. in line) I I
L------------------------_____________________________ ----------------------------~-----J

Figure J.6. Effects of ~PAGE and ISKIP

l
I

486 OS PL/I CKT AND OPT LRM PART II

 Section K: Data Mapping

This section describes structure mapping with another unit, and so on until the
and alignment of records in buffers. The complete structure has been mapped. The
information is included because, under rules for the process are therefore
certain circumstances, it should be borne categorized as:
in mind when a program is being written.
However, the information is not essential Rules for determining the order of
to programmers using stream-oriented pairing
transmission or unaligned data (other than
bit strings): it is intended for those Rules for mapping one pair
using record-oriented transmission
(particularly locate mode) with aligned These rules are described below, and an
structures. example shows an application of the rules
in detail.
Note: To follow these rules, it is
Structure Mapping necessary to appreciate the difference
between logical level and level number.
The item with the greatest level number is
For any structure (major or minor), the not necessarily the item with the deepest
length, alignment requirement, and position logical level. If thE structure
relative to a doubleword boundary will declaration is written with consistent
depend on the lengths, alignment level numbers or suitable indentation (as
requirements, and relative positions of its in the detailed example given after the
members. The process of determining these rules), the logical levels are immediately
requirements for each level in turn and apparent. In any case, the logical level
finally for the complete structure, is of each item in the structure can be
known as structure mapping. determined by applying the following rule
to each item in turn, starting at the
During the structure mapping process, beginning of the structure declaration:
the compiler minimizes the amount of unused
storage (padding) between members of the "The logical level of a given item is
structure. It completes the entire process always one unit deeper than that of the
before the structure is allocated, most immediate of its containing
according (in effect) to the rules structures."
discussed in the following paragraphs. It
is necessary for the user to understand For example:
these rules for such purposes as
determining the record length required for DeL 1 A, 4 B, 5 C, 5 D, 3 E, 8 F, 1 G;
a structure when record-oriented
input/output is used, and for determining 1 2 3 3 2 3 3
the amount of padding or rearrangement
required to ensure correct alignment of a The lower line shows the logical level for
structure for locate-mode input/output (see each item in the declaration.
"Record Alignment", at the end of this
section).
structure mapping is not a physical RULES FOR ORDER OF PAIRING
process. Although during this discussion
such terms as "shifted" and "offset" are
used, these terms are used purely for ease The steps in determining the order of
of discussion, and do not imply actual pairing are as follows:
movement in storage; when the structure is
allocated, the relative locations are 1. Find the minor structure with the
already known as a result of the mapping deepest logical level (which we will
process. call logical level n).
The mapping for a complete structure 2. If the number of minor structures at
reduces to successively combining pairs of logical level n exceeds one, take the
items (elements, or minor structures whose first one of them as it appears in the
individual mappings have already been declaration.
determined). Once a pair has been
combined, it becomes a unit to be paired 3. Using the rules for mapping one pair

Section K: Data Mapping 487

 (see below), pair the first two doubleword boundary by the amount
elements appearing in this minor indicated.
structure, thus forming a unit.
2. Begin the other item of the pair at
4. Pair this unit with the next element the first valid poSition following the
(if any) appearing in the declaration end of the first item. This position
for the minor structure, thus forming will depend on the alignment
a larger unit. requirement of the second item.
Alignment and length requirements for
5. Repeat rule 4 until all the elements elements are given in figures K.1 and
in the minor structure have been K.2. (If the item is a minor
combined into one unit. This structure, its alignment requirement
completes the mapping for this minor will have been determined already.)
structure; its alignment requirement
and length, including any padding, are 3. Shift the first item towards the
now determined and will not change second item as far as the alignment
(unless the programmer cpanges the requirement of the first item will
structure declaration). Its offset allow. The amount of shift determines
from a doubleword boundary will also the offset of this pair from a
have been determined;- note that this doubleword boundary.
offset will be significant during
mapping of any containing structure, After this process has been completed,
and it may change as a result of such any padding between the two items will have
mapping. been minimized and will remain unChanged
throughout the rest of the operation. The
6. Repeat rules 3 through 5 for the next pair can nOw be considered to be a unit of
minor structure (if any) appearing at fixed length and alignment requirement; its
logical level n in the declaration. length is the sum of the two lengths plus
padding, and its alignment requirement is
7. Repeat rule 6 until all minor the higher of the two alignment
structures at logical level n have requirements (if they differ).
been mapped. Each of these minor
structures can now be thought of as an
element for structure mapping
purposes. EFFECT OF UNALIGNED ATTRIBUTE

8. Repeat the process for minor

structures at the next higher logical The example of structure mapping given
level; that is, make n equal to (n-1) below shows the rules applied to a
and repeat rules 2 through 7. structure declared ALIGNED, because mapping
of aligned structures is more complex Owing
9. Repeat rule 8 until n = 1; then repeat to the number of different alignment
rules 3 through 5 for the major requirements. The general effect of the
structure. IUNALIGNED attribute is to reduce halfword,
fullword, and doubleword alignment
requirements down to byte, and to reduce
the alignment requirement for bit strings
RULES FOR MAPPING ONE PAIR from byte down to bit. The same structure
mapping rules apply, but the reduced
alignment requirements are used. This
As stated earlier, terms apparently means that unused storage between items can
implying phySical storage are used here only be bit padding within a byte, and
only for ease of discussion; the storage never a complete byte: bit padding may
thus implied may be thought of as an occur when the structure contains bit
imaginary model consisting of a number of strings.
contiguous doublewords. Each doubleword
has eight bytes numbered zero through 7, so TASK, EVENT and AREA data cannot be
that the offset from a doubleword boundary unaligned. If a structure has the
can be given; in addition, the bytes in the UNALIGNED attribute and i t contains an
model may be numbered continuously from element that cannot be unaligned, then
zero onwards, starting at any byte, so that UNALIGNED is ignored for that element; the
lengths and offsets from the start of a element is aligned by the compiler and an
structure can be given. error message is put out. For example, in
a program with the declaration
1. Begin the first item of the pair on a
doubleword boundary; or, if the item DECLARE 1 A UNALIGNED,
is a minor structure that has already 2 B,
been mapped, offset it from the 2 C AREA(100);

488 05 PL/I CKT AND OPT LRM PART II

C is given the attribute ALIGNED, as the The minor structure at the deepest
inherited attribute UNALIGNED conflicts logical level is G, so that this is mapped
with AREA. first as shown in figure K.3. Then E is
mapped, followed by N, S, C, and H, in that
order as shown in figures K.4 through K.S.
Finally, the major structure A is mapped as
EXAMPLE OF STRUCTURE MAPPING shown in figure K.9.

For each structure, a table is given

This example shows the application of the showing the steps in the process,
structure mapping rules for a structure accompanied by a diagram g1v1ng a visual
declared as follows: interpretation of the process. At the end
of the example, the structure map for A is
DECLARE 1 A ALIGNED, set out in the form of a table (figure
2 B POINTER, K.l0) showing the offset of each member
2 C, from the start of A.
3 D FLOAT DECIMAL(14),
3 E,
4 F LABEL,
4 G,
S H CHARACTER(2),
S I FLOAT DECIMAL(13),
4 J FIXED BINARY(31,O),
3 K CHARACTER(2),
3 L FIXED BINARYC20,O),
2 H,
3 N,
4 P FIXED BINARY(S),
4 Q CHARACTER(S),
4 R FLOAT DECIMAL(2),
3 S,
4 T FLOAT DECIMALC1S),
4 U BIT(3),
4 V CHAR(1),
3 W POINTER,
2 X PICTURE '$9V99'i

Section K: Data Mapping 489

r---------------------------------------------------------------------------------------,
I I storage I I I
Variable IStored Internally I Requirements I Alignment I Explanation I
Type I as I (in Bytes) I Requirements I I
BIT (n) lOne byte for eachl CEIL(n/a) I
Igroup of a bits I I
I (or part thereof) I I
1
CHARACTER (n) lOne byte per n I
1character IData may
Ibegin on
PICTURE lOne byte for each I.Number of Byte lany byte
IPICTURE character I PICTURE charac- o through 7
I (except V, K, andlters other than
Ithe F scaling IV, K, and F
I factor I specification
I specification) I

DECIMAL FIXED (p,q) I Packed decimal CEIL ( (p+1) /2)

Iformat (1/2 byte
Iper digit, plus
11/2 byte for
I sign)
BIT(n) VARYING ITwo-byte prefix I 2+CEIL(n/S)
Iplus one byte fori
leach group of a I
Ibits (or part 1
I thereof) I
CHARACTER(n) ITwo-byte prefix I 2+n
VARYING Iplus one byte perl Halfword
I character I
BINARY FIXED (p,q) I Halfword
P < =15 Ibinary integer 2 Data may begin
I 1 on byte 0,2,
I I 4 or 6

p > 15
1-----------------
IFullword binary
I integer
BINARY FLOAT (p) Data may
P < 22 I Short 4 Full begin on
-------------------Ifloating-point word byte 0 or
DECIMAL FLOAT (p) I 4 only
p < 7 I
-------------------------------------
POINTER1 I

IOFFSET1 I
1-------------------------------------1
1FILE I - I
1-------------------------------------------------------
IENTRY I I
1-------------------------------------1
I LABEL I I
a
1-------------------------------------------------------
ITASK I - I 16
1-------------------------------------------------------
IEVENT I I 32
L---------------------------------------------------------------------------------------J
Figure K.l (Part 1 of 2). Summary of alignment requirements for ALIGNED data

490 OS PL/I CKT AND OPT LRM PART II

r---------------------------------------------------------------------------------------,
I I I Storage I I
1 Variable 1Stored Internally 1 Requirements I Alignment 1 Explanation
1 Type 1 as I (in Bytes) I Requirements I
1---------------------------------------------------------------------------------------
IBINARY FLOAT (p) I 1 I IData may
1 21 < P < 54 "lLong I I Double 1begin on
1-------------------1 floating-point I 8 ,word Ibyte 0
IDECIMAL FLOAT (p) , , I ,only
I 6 < P < 17 1 1 I I
1-------------------------------------------------------I 1
IBINARY FLOAT(p) 1 I I I
153 < p < 110 1Extended 1 1 I
I-------------------Ifloating-point I 16 1 I
IDECIMAL FLOAT(p) I I I I
116 < p < 34 I I I I
1-------------------------------------------------------I 1
I AREA 1 116+size 1 I
I------------------~--------------------------------------------------------------------
11 Locators (pointers and offsets) used in programs processed by the checkout compiler
1 can be 4 or 16 bytes long. The mapping of four-byte locators is described here; the
I mapping of 16-byte locators is identical except for the extra storage requirement.
L---------------------------------------------------------------------------------------J
Figure K.1 (Part 2 of 2). summary of alignment requirements for ALIGNED data

Section K: OataMapping "'1

r---------------------------------------------------------------------------------------,
I I Storage I I I
Variable IStored Internally I Requirements I Alignment I Explanation I
Type I as I (in Bytes) I Requirements I I
---------------------------------------------------------------------------------------1
BIT (n) lAs many bits as I n bits IBit IData may begin I
I are required, I I Ion any bit in I
Iregardless of I I lany byte 0 I
I byte boundaries I I Ithrough 1 I
CHARACTER (n) lOne byte per I n I
I character I I
-------------------------------------------------------I
PICTURE I one byte for each I Number of PICTURE
IPICTURE characterlcharacters other
I (except V or K) Ithan V or K
BIT(n) VARYING ITWo-byte prefix I
Iplus one byte forl2 bytes + n bits
leach group of 8 I
Ibits (or part I
I thereof) I
-------------------------------------------------------
CHARACTER(n) I Two-byte prefix I 2+n
I VARYING I plus one byte perl
1 1character I
1-------------------------------------------------------
IDECIMAL FIXED(p,q) IPacked decimal I CEIL«p+1)/2)
I Iformat (1/2 byte I
1 Iper digit, plus I Data may begin
I 11/2 byte for I on any byte 0
1 I sign) I through 1
1-------------------------------------------------------
IBINARY FIXED (p,q) IBalfword binary I
Byte
1 p < = 15 1integer I 2
I1 p > 15
1-----------------
IFullword binary
-----------------
I I integer
1-------------------------------------
I BINARY FLOAT (p) I
1 p < 22 I Short
1-------------------1
IDECIMAL FLOAT (p) I
floating-point
1 p < 1 1
1-------------------------------------
I POINTER I -
1-------------------------------------
I OFFSET I
1-------------------------------------
1FILE 1
L---------------------------------------------------------------------------------------J
Figure K.2 (Part 1 of 2). Summary of alignment requirements for UNALIGNED data

492 OS PL/I CKT AND OPT LRM PART II

r---------------------------------------------------------------------------------------,
I 1 1 storage I I
I Variable Istored Internally 1 Requirements 1 Alignment 1 Explanation
1 Type 1 as I (in Bytes) 1Requirements
1-------------------------------------------------------
1ENTRY I I
------------ ------------------
1-------------------------------------1
1LABEL 1 I
1-------------------------------------1
IBINARY FLOAT (p) 1 1
1 21 < P < 54 1Long 1
I-------------------Ifloating-point I 8
IDECIMAL FLOAT (p) 1 I
I 6 < P < 17 1 I
1-------------------------------------------------------
IBINARY FLOAT(p) I I
153 < p <110 I Extended I
I-------------------Ifloating-point I 16
IDECIMAL FLOAT(p) 1 1
116 < P < 34 I I
1---------------------------------------------------------------------------------------
I ~ TASK, EVENT, and AREA data cannot be UNALIGNED. A pOinter or offset can be 4 or
I 16 bytes long (see figure K.1) •
.l---------------------------------------------------------------------------------------J
Figure K.2 (Part 2 of 2). Summary of alignment requirements for UNALIGNED data

Section K: Data Mapping 493

 r----------------------------------------------------------------------,
I 1 1 IOffset from I I
I Name of 1 Alignment 1 Length IDoubleword 1 Length of 1 Offset from
1 Item I Requirement 1 I--------~--I padding I G
I I I 1Begin 1 End I I
Step 1
1----------------------------------------------------------------------
1 H I Byte 1 2 I 0 1 1 I I
I I I Double 1 8 1 0 I 7 I I
I I I I I 1 I
Step 2 I *H I Byte I 2 I 6 I 7 I I 0
I I I Double I 8 I 0 1 7 1 0 I 2
1----------------------------------------------------------------------
I G I Double I 10 I 6 I 7 1 1
L----------------------------------------------------------------------J
*First item shifted right

H I
~ ,
Step I

Step 2

•
G
Figure K.3. Mapping of minor structure G

494 OS PL/I CKT AND OPT LRM PART II

 r----------------------------------------------------------------------,
I IOffset from I I
Name of I Alignment Length IDoubleword I Length of I Offset from
Item I Requirement 1-----------1 padding I E
I I Begin, End I I
----------------------- ----------------------------------------------
step 1 F 1 Word 8 0 7
G I Double 10 6 7
I
step 2 *F I Word 8 4 3 0
G 'Double 10 6 7 2 10
I
step 3 F I
through I Double 20 4 7
G ,
J ,Word 4 0 3 0 20
-------------------------------------------- -------------------------
E I Double ,24 1 4 , 3 ,
L----------------------------------------------------------------------J
*First item shifted right

F G

Step 0
~~~~~~~~~~~~~~~_P~~~~~~~~~~~~~~_+_

F G

Step 2

F G J

Step 3

E
Figure K.4. Mapping of minor structure E

Section K: Data Mapping 495

 r----------------------------------------------------------------------,
I tOffset froml I I
Name of Alignment I Length IDoubleword I Length of I Offset from I
Item Requirement I 1-----------1 padding I N I
I I Begin I End I I I
step 1
---------
P
------------------------------------------------------------1
Halfword I 2 I 0 I 1 I I 0 I
Q Byte I 5 I 2 I 6 I I 2 I
I I I I I I
step 2 P I I I I I I
through Halfword I 1 I 0 I 6 I I I
Q I I' I I 1
R Word I 4 I 0 I 3 I 1 I 8 I
----------------------------------------------------------------------1
N I word I 12 I 0 I 3 I I I
l----------------------------------------------------------------------J

Step I

P Q R
,.-A---w •

Step 2

,
•
N
Figure K.5. Mapping of minor structure N

496 os PL/I CKT AND OPT LRM PART II

 r----------------------------------------------------------------------,
I I IOffset from I I
Name of I Alignment I Length IDoubleword I Length of I Offset from
Item I Requirement I 1-----------1 Padding I S
I I I Begin I End I I
step 1 T Double 8 0 I 1 0
U Byte 1 0 I 0 0 8
I
Step 2 T I
through Double 9 0 I 0
U I
V Byte 1 1 I 1 0 9
----------------------------------------------------------------------
S Double I 10 I 0 I 1 I I
L----------------------------------------------------------------------J

T
I

Step I o

Step 2 0

, ",

S
Figure K.6. Mapping of minor structure S

section K: Data Mapping 491

 r----------------------------------------------------------------------,
I 1 IOffset froml I
Name of I Alignment 1 Length IDoubleword I Length of I Offset from
Item I Requirement 1 1-----------1 Padding 1 C
I 1 IBegin End 1 I
Step 1 D Double 8 0 1 o
E Double 2q q 3 q 12
Step 2 D
through Double 36 0 3
E
K Byte 2 q 5 o 36

step 3 D
through Double 38 0 5
K
L Word q 0 3 2 qO

I Double I 3 I I
L--------------------_________________________________
C qq 0
-----------------J

D E (I~ngth 24)
Step I

D E (length 24) K
, ,A, , • .. .,.,...,.,.....,

Step 2 I011 1213141 516Il9fjJ?~ 41 5Ofr-7r""""'°1llr-""'qT 1--r""14""""ls-r-10-'--17'--10'--1r-II21-'31--r4Is'"""'"r"lb-'-17'-°

-....yo23 1 1

D E (I eng th 24) K L
, ~ , , ~ ~,. ,
Step 3
l0ll 121314151617~1415)()f7IOII 1213141516171°11 121314151bl7io
,
c
Figure K.1. Mapping of minor structure C

q98 OS PL/I CKT AND OPT LRM PART II

 r----------------------------------------------------------------------,
I I IOffset from 1 I
Name of I Alignment I Length IDoubleword 1 Length of 1 Offset from
Item 1 Requirement I 1----------- Padding, M
, I I Begin, End I
----------------------- -------------------- -------------------------
Step 1 N Word 12 0 3 ,
S Double 10 0 1 I
I
Step 2 *N Word 12 4 7 I 0
S Double 10 0 1 0 I 12
I
Step 3 N I
through Double 22 4 1 I
S I
W Word 4 4 7 2 I 24
----------------------- ----------------------------------------------
M I. Double 1 28 ,4 I 7 I 1
L-----------------------------------------------------_________________ J
*First item shifted right

N s
Step I 0
~~~~+_~~_+-L~~~~~L4~-L~4_~~~~~-L~~L-~~

N s
Step 2

N S w
Step 3

,
M
Figure K.8. Mapping of minor structure M

Section K: Data Mapping 499

 r----------------------------------------------------------------------,
1 1 IOffset from 1 1 1
Name of 1 Alignment 1 Length IDoubleword I Length of 1 Offset from 1
Item 1 Requirement 1 1-----------1 Padding 1 A 1
I I I Begin I End I I I
Step 1 B Word 4 0 3
C Double 44 0 3

step 2 *B Word 4 4 1 0
C Double 44 0 3 0 4

Step 3 B
through Double 48 4 3
C
M Double 28 4 1 0 48

Step 4 B
through Double 16 4 1
M
X Byte 4 0 3 0 16
---------
A
-------------
Double
----------------------------------------------
80 I 4 I 3 I I
_________________ -----------------J
L------------------------~-----------
*First item shifted right

B C (I ength 44)

Step I

B C

Step 2

B C M (length 28)
, " '" ,. Vi ,., •

Step 3 101 I 121314IsI617IOI'Jf)1314IsI617IOI'Jf)1~3~14~15~16~17~IO~I'~12~13~14~15~lb~17~IO

B C M X
• A .... ~.. ,. \,,'&.
Step 4
101 I 121314ISI6171°1')()f314ISI6171°1')(,6314ISI6171°1'121314IS1& 17 1°
,
A ('e",th 10)
Figure )(.9. Mapping of major structure A

500 OS PL/I CRT AND OPT LRM PART II

r----------------------------
A
-------------,
From A
B o
C From C 4
o o II
padding (4) 8 12
E From E 12 16
F o 12 16
padding (2) 8 20 211
G From G 10 22 26
H o 10 22 26
I 2 12 211 28
J 20 32 36
1< 36 110
padding (2) 38 112
L 110 1111
M From M 118
N From N o 118
p o o 48
Q 2 2 50
padding (1) 1 1 55
R 8 8 56
S From S 12 60
T o 12 60
U 8 20 68
V 9 21 69
padding (2) 22 10
W 211 12
X 16
l---------------------------------------------------------------------------------------J
Figure K.l0. Offsets in final mapping of structure A

Section K: Data Mapping 501

Record Alignment from the buffer to correctly aligned
storage.

The user must pay attention to record If, however, a structure is defined as:
alignment within the buffer when using
locate mode input/output. The first data 1 SBASED BASED(P) LIKE S;
byte of the first record in a block is
generally aligned in a buffer on a and READ SET(P) statements are used,
doubleword boundary (see figure K.~4); the reference to SBASED.B will, for the first
next record begins at the next available record in the block, be to data aligned at
byte in the buffer. The user must ensure a doubleword plus one byte, and will
that the alignment of this byte matches the probably result in a specification
alignment requirements of the based interrupt.
variable with which the record is to be
associated. The same problem would have arisen had
the file originally been created by using
For blocked records, doubleword the statement:
alignment of the first byte of data in each
record in the block is ensured if the LOCATE SBASED SETCP);
record length (RECSIZE) is a multiple of
eight. For spanned records, the block size Again, for the first record in the
(BLKSIZE) must be a multiple of eight if block, P would be set to address a
this alignment is required. For data read doubleword and references to SBASED.B would
from ASCII data sets, the first byte of the be invalid.
block prefix is doubleword-aligned; to
ensure similar alignment of the first byte In both cases the problem is avoided if
of the first record, the prefix length must the structure is padded in such a way that
be a multiple of eight bytes, less four to B is always correctly aligned:
allow for the four record length bytes.
1 S,
Most of the alignment problems 2 PAD CHAR(3),
described here occur in ALIGNED based or 2 A CHAR(l),
non-based variables. If these variables 2 B FIXED BINARY;
were UNALIGNED, the preservation of the
record alignment in the buffer would be The block format would now be as in figure
considerably easier. K.13; B is always on a word boundary.
padding may be required at the beginning
If a VB-format record is to be and end of a structure to preserve
constructed with logical records defined by alignment.
the structure:
The alignment of different types of
1 S, record within a buffer is shown in figure
2 A CHAR(l), K.14. For all organizations and record
2 B FIXED BINARY(3l,0); types, except FB, V and VB records in
INDEXED data sets with KEYLOC = 0 or
this structure is mapped as in figure K.ll. unspecified, the first data byte in a block
(or hidden buffer) is always on a
r-----------------------,
I IA I B I
doubleword boundary. The position of any
successive records in the buffer depends on
I--J--J--------J--J--J--I the record format.
t t t
W W W For INDEXED data sets with unblocked F-
format records, the LOCATE statement will
W Word boundary use a hidden buffer if the data set key
length is not a multiple of eight and the
Figure K.ll. Format of structure S KEYLOC value is 1, 0 or is not specified
(that is, RKP = 0). The pointer variable
will pOint at this hidden buffer.
If the block was created using a
sequence of WRITE FROM(S) statements, the A special problem arises when using
format of the block would be as in figure locate mode input/output in conjunction
K.l2, and i t can be seen that the alignment with a based variable containing adjustable
in the buffer differs from the alignment of extents, i.e., containing a REFER option.
S. Consider the following structure:

There is no problem if the file is then 1 S BASED(P),

read using move mode READ statements, e.g., 2 N,
READ INTO(S), because information is moved 2 C CHAR (L REFER (N»;

502 OS PL/I CKT AND OPT LRM PART II

If i t is desired to create blocked V-format LENGTH =L;
records of this type, using locate mode /*SAVE DESIRED LENGTH L */
input/output, record alignment must be such L = 2* CEILCL/2);
that N is half-word aligned. If L is not a /* ROUND UP TO MULTIPLE OF 2*/
multiple of 2 then. if the alignment of the LOCATE S FILE CF);
current record is correct, that of the N = LENGTH;
following record will be incorrect. /* SET REFER VARIABLE */
Correct alignment can be obtained by the
following sequence: This technique can be adapted to other
uses of the REFER option.

r---------------------------------------------------------------------------
I BL I RL IA I B I RL IA I B I
I--J __ J--J-----J--J--J------~-J--J--J-----J--J--J--------J--J--J------------
t t t t t t
o W D W D W
BL = Block length D Doub~eword boundary
RL =Record length W = Word boundary

Figure K.12. Block created from structure S

r---------------------------------------------------------------------------------------
I BL I RL I PAD I }'a_I B I RL I PAD I AI B I
I--J--J--J-----J--J--J-----J--J--------J--J--J-----J--J--J-----J--J--------J--J--J------
t t t t t t t t
o W D W D W D W
BL = Block length D Doubleword boundary
RL Record length W Word boundary

Figure K.13. Block created by structure S with correct alignment

Section K: Data Mapping 503

 · CONSECUT IVE Doubleword
boundary
F,V,VS,D,U data
I
FB data
I data
I
VB,VBS ,DB
~data---. ~data---..

INDEXED
KEYLOC RKP
F 1 0
I
~data~

>1 >0 IEKI I

~data~

0 0 I
r----data~

FB 1 0 I
~data~~data---..

>1 >0 I
----data~~data~

0 0
...-data~ ~data--'"

v 1 4 EKI J
.....-d at a---.
>1 >4 lEKl J
~data~

0 4 I
...-data--...
VB 1 4
I
~data.--.· ~data---...

>1 >4 I
~data~ ~data~

0 4 I
~data~ ~data ....
REGIONAL
F,V,VS,U data I
Notes:
1. EK = embedded key K = key 1 = record length
2. Each I/O operation sets the pointer to the beginning of the data in the records.
3. For CONSECUTIVE data sets with VBS-format records, if the record length is greater
than the block size, the record is moved to a hidden buffer, with the first data
byte on a doubleword boundary.
Figure K.14. Alignment of data in a buffer in locate mode input/output, for
different formats and data set organizations

504 OS PL/I CKT AND OPT LRM PART II

 Section L: Compiler Differences

The tables in this section list the Figures L.2 and L.3 show differences
principal differences between the that do not arise directly from differing
optimizing and checkout compilers. compiler functions. Figure L.2 contains
general syntactic and semantic differences,
Figure L.1 gives the differences that and figure L.3 shows differing quantitative
arise from the differing functions of the restrictions on the use of various
two compilers. There are, for" instance, facilities of the language.
keywords concerned with the checkout and
conversational facilities of the checkout
compiler that are not implemented by the
optimizing compiler, and optimization The section is applicable only to
keywords that are not implemented by the error-free programs processed in batch
checkout compiler. mode.

Section L: Compiler Differences 505

r---------------------------------------------------------------------------------------,
Language feature I Optimizing compiler I Checkout compiler I
I implementation I implementation I
---------------------------------------------------------------------------------------
statements: syntax~checkonly I Implemented
CHECK I
NOCHECK I
FWW I
NOFLOW I
PUT SNAP I
PUT FLOW I
PUT ALL I
HALT I
I CONTROL I
Options: I Implemented syntax-check only
ORDER I
REORDER I
TOTAL I
---------------------------------------------------------------------------------------
Built-in subroutines: I Implemented Syntax-check only
PLICKPT I
PLIREST I
PLICANC ,
---------------------------------------------------------------------------------------
PUT DATA statement and I Names of variables only Names and values of
CHECK prefix I transmitted variables transmitted
specifying program I
control data I
---------------------------------------------------------------------------------------
PUT LIST statement I Invalid Values of variables
specifying program I transmitted
control data I
Lengths of pointer and 4 bytes With COMPATIBLE compiler
offset variables option: 4 bytes
With NOCOMPATIBLE compiler
option: 16 bytes
Oncodes I Certain codes not All oncodes implemented
I implemented (See list
I in section Hr "On-
I conditions"). I
L---------------------------------------------------------------------------------------J
Figure L.1. Differences resulting from differing compiler functions

506 os PL/I CKT AND OPT LRM PART II

r---------------------------------------------------------------------------------------,
Language feature I Optimizing compiler I Checkout compiler
I implementation I implementation

Based variable in data- 1 Must not be based on an No corresponding rules

directed I/O and CHECK offset variable.
name-list 2 Must not be a member of
a structure containing
the REFER option.
3 Must not be based on a
pOinter that is based,
defined, or a parameter,
or a member of an
aggregate.

Defined variable in Must not be defined: No corresponding rules

data-directed I/O and 1 on a controlled variable.
CHECK name-list 2 on an array with one or
more adjustable bounds.
3 with a POSITION attri-
bute specifying other
than a constant.

CHECK prefix specifying I CHECK raised for the CHECK not raised for
label of statement to I label the label
which prefix is I
attached I
LIKE attribute Not allowed NO co~responding rule
specifying a minor
structure that is
contained in a major
structure of which
some other minor
structure is declared
with LIKE attribute

Area variable in an I Must be non-defined, No corresponding rule

OFFSET attribute either I unsubscripted,
in DECLARE statement orl unqualified area name
RETURNS attribute or I
option I
Area variable in OFFSET I Not allowed No corresponding rule
attribute in parameter I I
descriptor I I
---------------------------------------------------------------------------------------1
Data-directed output I output in row major order I Output as interleaved arrays I
of dimensioned I for each array I in row major order I
structure I I I
---------------------------------------------------------------------------------------1
Exponentiation I see section F, figure f.4d 1
L---------------------------------------------------------------------------------------J
Figure L.2 (Part 1 of 2). Differing qualitative restrictions

Section L: compiler Differences 507

r---------------------------------------------------------------------------------------,
Language feature I Optimizing compiler I Checkout compiler I
I implementation I implementation ,
Aggregate argument to Dummy argument cannot be No corresponding rule
generic entry name be created

Parameter string length, Length or size attribute I Dummy created if length or

or area size specified I assumed to match argument: I size differs from argument
as other than decimal , dummy never created I
integer constant I I
---------------------------------------------------------------------------------------
Attributes of entry No dummy argument I Dummy argument created
argument and parameter I
differ in alignment I
only I
Pseudovariables: Not allowed as control No corresponding rule
COMPLETION variables for do-groups
COMPLEX
PRIORITY
STRING
UNDEFINEDFILE condition Raised once, after Raised at each attempt to
in OPEN statement attempting to open every open a file that is un-
specifying more than file defined
one file name
Standard default files No corresponding rule Used by compiler. Must not
SYSIN and SYSPRINT be declared with attributes
conflicting with compiler
requirements. SYSPRINT
always open, therefore no
new page started for
program's output
Locator conversion 1 If offset is a structure No corresponding rules
(offset to pointer and member, or if it appears
vice versa) in a DO statement or
multiple assignment, the
associated area must be
an unsubcripted,
non-defined element
variable. If the area is
based, its locator must
be an unsubscripted,
non-based, non-defined
pointer, and it must not
be used to explicitly
qualify the area in the
offset declaration.
2 Locator conversion can-
not be performed between
argument and parameter:
both must be either
offset or pointer.
L---------------------------------------------------------------------------------------J
Figure L.2 (Part 2 of 2). Differing qualitative restrictions

508 OS PL/I'CKT AND OPT LRM PART II

 r---------------------------------------------------------------------------------------,
Language feature I Optimizing compiler I Checkout compiler
I implementation I implementation
---------------------------------------------------------------------------------------
Maximum number of 255 I No corresponding rule
blocks in one I
compilation I
Maximum level of 50 I No corresponding rule
nesting of blocks I
---------------------------------------------------------------------------------------
Maximum number of I 49 in any block I No corresponding rule
active on-units I 254 in any compilation I
---------------------------------------------------------------------------------------
Maximum level of I 49 No corresponding rule
nesting of DO and IF I
statements I
Maximum level of 49 No corresponding rule
nesting of select-
groups
Maximum level of 1, except that an adjust- No corresponding rule
dependency in DECLARE able bound may not dep-
statement end on a defined var-
iable whose base:
1. is a parameter,
2. is automatic with
adjustable extents,
or 3. has fixed subscripts
Maximum number of 125 No corresponding rule
entries in list of
constants in
declaration of COBOL
variable
Maximum level of Depends on storage avail- No corresponding rule
locator qualification able, but never less than
10
Maximum length of I Depends on storage avail- 32161
character-string I able, but never less than
picture data I 1023
------------------------------------------------------- -------------------------------
Maximum number of I 400 maximum. The exact No corresponding rule
subscripted label I number depends on the main
variables or I storage available to the
subscripted label I compiler, and is one tenth.
prefixes in one block I of the spill file record
I size. The maximum of 400
I is obtained when the size
I of main storage available
I to the compiler is greater
I than 80k bytes
---------------------------------------------------------------------------------------
Maximum number of I 32 for statements that I No corresponding rule
active qualified I generate intermediate I
temporary results I temporary results for I
I BASED, dynamically DEFINED, I
I I or subscripted variables I
L---------------------------------------------------------------------------------------J
Figure L.3. Differing quantitative restrictions

Section L: compiler Differences 509

510 OS PL/I CRT AND OPl' LRM PART II
 Glossary

access: the act that encompasses the 5. The state in which a task is said to
references to and retrieval of data. be before it has been terminated.
action specification: in an ON statement, additive attributes: attributes for which
the on-unit or the single keyword SYSTEM, there are nO defaults and which, if
either of which specifies the action to be required, must always be added to the list
taken whenever an interrupt results from ot specified attributes or be implied
raising of the named on-condition. The (i.e., they have to be added to the set of
action specification can also include the attributes, if they are required).
keyword SNAP.
address: a specific storage location at
activate (a block): to initiate the which a data item can be stored.
execution of a block. A procedure block is
activated when it is invoked at any of its adjustable extent: bound (of an array),
entry points; a begin block is activated length (of a string), or size (of an area)
when i t is encountered in normal flow of that may be different for different
control, including a branch. generations of the associated variable.
Adjustable bounds, lengths, and sizes are
activation (of a block): specified as expressions or asterisks (or
by REFER options for based variables),
1. The process of activating a block. which are evaluated separately for each
generation. They cannot be used for static
2. The execution of a block. variables.

activation (of a preprocessor variable or aggregate: see data aggregate.

entry name): the establishment of the
validity for replacement of the value of a aggregate expressions: an array expression
variable or the returned value of an entry or a structure expression.
name. The first activation must be the
result of the appearance of the name in a alignment: the storing of data items in
IDECLARE statement. If an active variable relation to certain machine-dependent
or entry name is made inactive by a boundaries.
IDEACTIVATE statement it may be activated
again by a %ACTIVATE statement. allocated variable: a variable with which
main storage has been associated and not
active: freed.

1. The state of a block after activation allocation:

and before termination.
1. The reservation of main storage for a
2. The state in which a preprocessor variable.
variable or preprocessor entry name is
said to be when its value can replace 2. A generation of an allocated variable.
the corresponding identifier in source
program text. alphabetic character: any of the
characters A through Z of the English
3. The state in which an event variable alphabet and the alphabetic extenders #, $,
is said to be during the time i t is and ~ (which may have different graphic
associated with an asynchronous representation in different countries).
operation. An event variable remains
active and, hence, cannot be alphameric charact.er: an alphabetic
associated with another operation character or a digit.
until a WAIT statement specifying that
event variable has been executed or, alternative attribute: an attribute that
in the case of an event variable may be chosen from a group of two or more
associated with a task, until an EXIT, alternatives. If none is specified, a
RETURN, or END statement has caused detault is assumed.
termination of the task.
ambiguous reference: a reference that is
4. The state in which a task variable is not sufficiently qualified to identify One
said to be when its associated task is and only one name known at the point of
attached. reference.

Glossary 511
ancestral task: the attaching task or any evaluation yields an array of values.
of the tasks in a direct line from the
given task to, and including, the major
task. array of structures: an ordered collection
of identical structures specified by giving
~: a declared portion of contiguous the dimension attribute to a structure
main storage identified by an area variable name.
and reserved, on allocation, for the
allocation of based variables. aSSignment: the process of giving a value
to a variable.
area variable: a variable with the AREA
attribute; its values may only be areas. asynChronous operation: the overlap of an
input/output operation with the execution
argument: an expression in an argument of statements or the concurrent execution
list as part of a procedure reference. of procedures using multiple flows of
control for different tasks.
argument list: a parenthesized list of one
or more arguments, separated by commas, attachment of a task: the invocation of a
following an entry-name constant, an entry- procedure and the establishment of a
name variable, a generic name, or a built- separate flow of control to execute the
in function name. The list is passed to invoked procedure (and procedures it
the parameters of the entry point. invokes) asynchronously with execution of
the invoking procedure.
arithmetic constant: a fixed-point
constant or a floating-point constant. attention: an occurence, external to a
Although most arithmetic constants can be task, that could cause an interrupt to the
signed, the sign is not part of the task.
constant.
attribute:
arithmetic conversion: the transformation
of a value from one arithmetic 1. A descriptive property associated with
representation to another. a name to describe a characteristic of
items that the name may represent.
arithmetic data: data that has the
characteristics of base, scale, mode, and 2. A descriptive property used to
precision. It includes coded arithmetic describe a characteristic of the
data and pictured numeric character data. result of evaluation of an expression.

arithmetic operators: either of the prefix automatic storage allocation: the

operators + and -, or any of the following allocation of storage for automatic
infix operators: + - */ ** variables.

arithmetic picture data: decimal picture automatic variable: a variable that is

data or binary picture data containing the allocated automatically at the activation
following types of picture specification of a block and released automatically at
characters. the termination of that block.

1. Decimal digit characters. base: the number system in terms of which

an arithmetic value is represented.
2. Zero-suppression characters.
base element: the name of a structure
3. Sign and currency symbol characters. member that is not a minor structure.

4. Insertion characters. base item: the automatic, controlled, or

static variable or the parameter upon which
5. Commercial characters. a defined variable is defined. The name
may be qualified and/or subscripted.
6. Exponent characters.
based storage allocation: the allocation
array: a named, ordered collection of data of storage for based variables.
elements, all of which have identical
attributes. An array has dimensions based variable: a variable whose
specified by the dimension attribute, and generations are identified by locator
its individual elements are referred to by variables. A based variable can be used to
subscripts. An array can a1so be an refer to values of a variable of any
ordered collection of identical structures. storage class; it can also be allocated and
freed explicitly by use of the ALLOCATE and
array expression: an expression whose FREE statements.

512 OS PL/I CKT AND OPT LRM PART II

begin block: a collection of statements 1. CR (credit).
headed by a BEGIN statement and ended by an
END statement that is a part of a program 2. DB (debit).
that delimits the scope of names and that
is activated by normal sequential flow of 3. T, I, and R, the overpunched-sign
control, including any branch resulting characters, which indicate that the
from a GO TO statement. associated position in the data item
contains or may contain a digit with
an overpunched sign and that this
binary: the number system based on the overpunched sign is to be considered
number 2. in the character string value of the
data item.
bit: a binary digit (0 or 1).
comparison operators: infix operators used
bit string: a string composed of zero or in comparison expressions. They are ~<
more bits. (not less than), < (less than), <= (less
than or equal to), ~= (not equal to), =
bit-string operators: the logical (equal to), >= (greater than or equal to),
operators ~ (not), & (and), and I (or). > (greater than), and ~> (not greater
than) •
block: a begin block or procedure block.
compile time: in general, the time during
block heading statement: the PROCEDURE or which a source program is translated into
BEGIN statement that heads a block of an object module. In PL/I, it is the time
statements. during which a source program can be
altered (preprocessed), if desired, and
bounds: the upper and lower limits of an then translated into an Object program.
array dimension.
compile-time statements: see preprocessor
buffer: intermediate storage, used in statement~.
input/output operations, into which a
record is read during input and from which complex data: arithmetic data, each item
a record is written during output. of which consists of a real part and an
imaginary part.
built-in function: a function that is
supplied by the language. composite operators: an operator composed
of two operator symbols, e.g., ~>
call: (verb) to invoke a SUbroutine by
means of the CALL statement or CALL option: compound statement: a statement that
(noun) such an invocation. contains other statements. IF and ON are
the only compound statements.
character set: a defined collection of
characters. See language character set and concatenation: the operation that joins
data character set. two strings in the order specified, thus
forming one string whose length is equal to
character string: a string composed of the sum of the lengths of the two strings.
zero or more characters. It is specified by the operator 'I.
character-string picture data: data condition: see on-conditions.
described by a picture specification which
must have at least One A or X picture condition list: a list of one or more
specification character. condition prefixes.

closing (of a file): the dissociation of a condition name: a language keyword (or
file from a data set. CONDITION followed by a parenthesized
programmer-defined name) that denotes an
coded arithmetic data: arithmetic data on-condition that might arise within a
that is stored in a form that is task.
acceptable, without conversion, for
arithmetic calculations. condition prefix: a parenthesized list of
one or more language condition names,
comment: a string of zero or more prefixed to a statement. It specifies
characters used for documentation, that is' whether the named on-conditions are to be
preceded by /* and terminated by */ and enabled.
which is a separator.
connected reference: a reference to
commercial character: the following connected storage: it must be apparent,
picture specification characters; prior to execution of the program, that the

Glossary 513
 storage is connected. data aggregate: a logical collection of
two or more data items that can be referred
connected storage: main storage of an to either collectively or individually; an
uninterrupted linear sequence of items that array or structure.
can be referred to by a single name.
data character set: all of those
constant: an arithmetic or string data characters whose representation is
item that does not have a name and whose recognized by the computer in use.
value cannot change; an unsubscripted label
prefix or a file name or an entry name. data-directed transmission: the type of
stream-oriented transmission in which data
contained text: all text in a procedure is transmitted as a group, comprising one
(including nested procedures) except it~ or more items separated by commas or
entry names and condition prefixes of th~ blanks, terminated by a semicolon, where
PROCEDURE statement; all text in a begin each item is of the form:
block except labels and condition prefixes
of the BEGIN statement that heads the name = value
block. Internal blocks are contained in
the external procedure. The name can be qualified and/or
subscripted.
contextual declaration: the appearance of
an identifier that has not been explicitly data format item: a specification used in
declared, in a context that allows the edit-directed transmission to describe the
association of specific attributes with the representation of a data item in the
identifier. stream.

control format item: a specification used data item: a Single unit of data; it is
in edit-directed transmission to specify synonymous with element.
positioning of a data item within the
stream or printed page. data list: a parenthesized list of
expressions or repetitive specifications,
control variable: a variable used to separated by commas, used in a stream-
control the iterative execution of a group. oriented input or output specification that
See iterative do-group. represents storage locations to which data
items are to be assigned during input or
controlled parameter: a parameter for values which are to be obtained for output.
which the CONTROLLED attribute is specified
in a declare statement; i t can be data set: a collection of data external to
associated only with arguments that have the program that can be accessed by the
the CONTROLLED attribute. program by reference to a single file name.

controlled storage allocation: the data specification: the portion of a

allocation of storage for controlled stream-oriented data transmission statement
variables. that specifies the mode of transmission
(DATA, LIST, or EDIT) and includes the data
controlled variable: a variable whose list (or lists) and, for edit-directed
allocation and release are controlled by mode, the format list (or lists).
the ALLOCATE and FREE statements, with
access to the current generation only. data stream: data being transferred from
or to a data set by stream-oriented
conversion: the transformation of a value transmission, as a continuous stream of
from one representation to another to data elements in character form.
conform to a given set of attributes.
data transmission: the transfer of data
cross section of an array: the elements from a data set to the program or vice
represented by the extent of at least one versa.
Idimension of an array. An asterisk in the
place of a subscript in an array reference deactivated: the state in which a
indicates the entire extent of that preprocessor variable or entry name is said
dimension. to be when its value cannot replace the
corresponding identifier in source program
current generation: that generation (of an text.
automatic or controlled variable) currently
available by reference to the name of the decimal: the number system based on the
variable. number 10.

data: representation of information or of decimal digit character: the picture

value in a form suitable for processing. specification character 9.

514 OS PL/I CKT AND OPT LRM PART II

decimal picture data: arithmetic picture dummy argument: temporary storage that is
data specified by picture specification created automatically to hold the value of
characters containing the following types an argument that cannot be passed by
of picture specification characters: reference.
1. Decimal digit characters. edit-directed transmission: the type of
stream-oriented transmission in which data
2. The virtual point picture character. appears as a continuous stream of
characters and for which a format list is
3. zero-suppression characters. required to specify the editing desired for
the associated data list.
4. Sign and currency symbol characters.
element: a single item of data as opposed
5. Insertion characters. to a collection of data items such as an
array: a scalar item.
6. Commercial characters.
element expression: an expression whose
7. Exponent characters. evaluation yields an element value.
declaration: elementary name: see base element.
1. The establishment of an identifier as element variable: a variable that
a name and the construction of a set represents an element: a scalar variable.
of attributes (partial or complete)
for it. enabled: that state in which a particular
on-condition will result in a program
2. A source of attributes of a particular interrupt that would cause an on-unit for
name. that condition to be entered.
default: the alternative attribute or entry constant: an entry. name.
option assumed, or specified for assumption
by the DEFAULT statement, when no such entry expression: an expression whose
attribute or option has been specified. evaluation yields an entry value.
defined item: a variable declared to entry name: an identifier that is
represent part or all of the same storage explicitly or contextually declared to have
as that assigned to another variable known the ENTRY attribute (unless the VARIABLE
as the base item. attribute is given) or has an implied ENTRY
attribute; the value of an entryvariable.
delimiter: all operators, comments, and
the following characters: percent, entry point: a point in a procedure at
parentheses, comma, period, semicolon, which it may be invoked. (See primary
colon, assignment symbol, and blank: they entry point and secondary entry pOint.)
define the limits of identifiers,
constants, picture specifications, iSOBs, entry variable: a variable that can
and keywords. represent entry values. It must have both
the ENTRY and VARIABLE attributes.
descriptor: see parameter descriptor.
entry value: the entry pOint represented
digit: one of the characters 0 through 9. by an entry constant; the value includes
the environment of the activation that is
dimensionality: the number of bounds associated with the entry constant.
specifications in an array declaration.
environment (of an activation):
disabled: the state in which a particular information associated with the invocation
on-condition will not result in an of a block that is used in the
interrupt that would cause an on-unit for interpretation of references, within, the
that condition to be entered. invoked block, to data declared outside the
block. This information includes
do-group: a sequence of statements headed generations of automatic variables, extents
by a DO statement and ended by its of defined variables, and generations of
corresponding END statement, used for parameters.
control purposes.
environment {of a label constant):
do loop: see iterative.do-group. identity of the particular activation of a
block to which a reference.to a statement-
drifting-characters: see sign and currency label constant applies. This information
symbol characters. is determined at the time a.statement-label

Glossary 515
constant is passed as an argument or is not contained in any other procedure.
assigned to a statement-label variable, and
it is passed or assigned along with the factoring: the application of one or more
constant. attributes or of a level number to a
parenthesized list of names.
epilogue: those processes that occur
automatically at the termination of a block field (in the data stream): that portion
or task. of the data stream whose width, in number
of characters, is defined by a single data
evaluation: reduction of an expression to or spacing format item.
a single value, an array of values, or a
structured set of values. field (of a picture specification): any
character-string picture specification or
~: an activity in a program whose that portion (or all) of a numeric
status and completion can be determined character picture specification that
from an associated event variable. describes a fixed-point number.
event variable: a variable with the EVENT ~: a named representation, within a
attribute, which may be associated with an program, of a data set or data sets. A
event; its value indicates whether the file is associated with the data set or
action has been completed and the status of data sets for each opening.
the completion.
file attribute: any of the attributes that
explicit declaration: the appearance of an describe the characteristics of a file.
identifier in a DECLARE statement, as a
label prefix, or in a parameter list. file constant: a name declared for a file
and for which a complete set of file
exponent characters: the follOwing picture attributes exists during the time that the
specification characters: file is open.
1. K and E, which are used in floating- file expression: an expression whose
point picture specifications· to evaluation yields a file name.
indicate the beginning of the exponent
field. file name: a name declared for a file.
2. F, the scaling factor character, file variable: a variable to which file
specified with an integer constant constants can be assigned; it must have
which indicates the number of decimal both the attributes FILE and VARIABLE. No
positions the decimal point is to be file-name attributes, other than FILE, can
moved from its assumed position, to the be specified for a file-name variable.
right (if the constant is positive) or
to the left (if the constant is fixed-point constant: see arithmetic
negative) • constant.
expression: a notation, within a program, floating-point constant: see arithmetic
that represents a value, an array of constant.
values, or a structured set of values; a
constant or a reference appearing alone, or flow of control: sequence of execution.
combinations of constants and/or references
with operators. format item: a specification used in edit-
directed transmission to describe the
extent: representation of a data item in the stream
(data format item) or to specify
1. The range indicated by the bounds of positioning of a data item within the
,an array dimension, the range stream (control format item).
indicated by the length of a string,
or the range indicated by the size of format list: a parenthesized list of
an area. format items required for an edit-directed
data specification.
2. The significant allocations in an
area. fully-qualified name: a qualified name
that is complete, i.e., that includes a11
external name: a name (with the EXTERNAL names in the hierarchical sequence above
attribute) whose scope is not necessarily the structure member to which the name
confined only to one block and its refers, as ·well as the name of the member
contained blocks. itself.
external procedure: a procedure that is function: a function procedure

516 os PL/I CKT AND OPT LaM PART I I

(programmer-specified or built-in): a an auxiliary medium and main storage.
procedure that is invoked by the appearance
of one of its entry names in a function insertion picture character: a picture
reference and which returns a value to the specification character that is, on
point of reference. assignment of the associated data to a
character string, inserted in the indicated
function reference: the appearance of an position. When used in a p-format item for
entry-name or built-in function name (or an input, an insertion character serves as a
entry variable) in an expression. checking picture character.
generation (of a variable): the allocation interleaved array: an array whose name
of a static variable, a particular refers to non-connected storage.
allocation of a controlled or automatic
variable or the storage indicated by a interleaved subscripts: a subscript
particular locator qualification of a based notation, used with subscripted qualified
variable, or by a defined variable or a names, in which not all of the necessary
parameter. SUbscripts immediately follow the same
component name.
generic key: a character string that
identifies a class of keys: all keys that internal block: a block that is contained
begin with the string are members of that in another block.
class. For example, the recorded keys
'ABCD', 'ABCE', and 'ABDF', are all members internal name: a name that is not known
of the classes identified by the generic outside the block in which it is declared.
keys 'A' and 'AB', and the first two are
also members of the c1ass 'ABC': and the internal procedure: a procedure that is
three recorded keys can be considered to be contained within a block.
unique members of the classes 'ABCD',
'ABCE', 'ABDF', respectively. internal text: all of the text contained
in a block except that text that is
generic name: the name of a family of contained in another block. Thus the text
entry names. A reference to the name is of an internal block (except its entry
replaced by the particular entry name whose names) is not internal to the containing
parameter descriptors match the attributes block.
of the arguments in the argument list at
the point of invocation. interrupt: the redirection of flow of
control of the program (possibly temporary)
I group: a do-group or a select-group: it as the result o~ an on-condition or
can be used wherever a single statement can attention.
appear,' except as an on-unit.
invocation: the activation of a procedure.
identifier: a string of alphameric and,
possibly, break characters, not contained invoke: to activate a procedure at one of
in a comment or constant and which is its entry points.
preceded and followed by a separator: the
initial character must be alphabetic. invoked procedure: a procedure that has
been activated at one of its entry points.
implicit declaration: the establishment of
an identifier, which bas no explicit or invokinq block: a block containing a
contextual declaration, as a name. A statement that activates a procedure.
default set of attributes is assumed for
the identifier. iteration factor: an expression that
specifies:
implicit opening: the opening of a file as
the result of an input or output statement 1. In an INITIAL attribute specification,
other than the OPEN statement. the number of consecutive elements of
an array that are to be initialized
infix operator: an operator that appears with a given constant.
between two operands.
2. In a format list, the number of times
initial procedure: an external procedure a given format item or list of items
whose PROCEDURE statement has the OPTIONS is to be used in succession.
(MAIN) attribute. Every PL/I program must
have an initial procedure. It is invoked iterative do-group: a do-group whose ,DO
automatically as the first step in the statement specifies a control variable
execution of a progam. and/or a WHILE option.
input/output: the transfer of data between key: data that identifies a record within

Glossary 517
a direct-access data set. See source key stream-oriented transmission in which data
and recorded key. in the stream appears as constants
separated by blanks or commas and for which
keyword: an identifier that is part of the formatting is provided automatically.
language and which, when used in the proper
context, has a specific meaning to the locator qualification: in a reference to a
compiler. based variable, either a locator variable
or function reference· connected by an arrow
known: (applied to a name) recognized with to the left of a based variable to specify
its declared meaning; a name is known the generation of the based variable to
throughout its scope. which the reference refers, or the implicit
connection of a locator variable with the
label: a name used to identify a statement based reference.
other than a PROCEDURE or ENTRY statement;
a statement label. locator variable: a variable whose value
identifies the location in main storage of
label constant: an unsubscripted name that a variable or a buffer.
appears prefixed to any statement other
than a PROCEDURE or ENTRY statement. locked record: a record in an EXCLUSIVE
DIRECT UPDATE file that is available to
label list (of a statement): all of the only one task at a time.
label prefixes of a statement.
logical level (of a structure member): the
label list (of a label variable depth indicated by a level number when all
declaration): a parenthesized list of one level numbers are in direct sequence, that
or more statement-label constants is, when the increment between successive
immediately following the keyword LABEL to level numbers is one.
specify the range of values that the
declared variable may have; names in the logical operators: the bit-string
list are separated by commas. When operators, (not), , (and), and I (or).
specified for a label array, it indicates
that each element of the array may assume lower bound: the lower limit of an array
any of the values listed but no other. dimension.
label prefix: a label prefixed to a major structure: a structure whose name is
statement. declared with level number 1.
label variable: a variable declared with major task: the task that has control at
the LABEL attribute and thus able to assume the outset of execution of a program. It
as its value a label constant. exists throughout the execution of the
program.
language character set: a character set
whiah has been defined to represent program minor structure: a structure that is
elements in the source language (in this contained within another structure. The
context, character-string constants and name of a minor structure is declared with
comments are not considered as program a level number greater than one.
elements).
mode (of arithmetic data): a
leading zeros: zeros that have no characteristic of arithmetic data; real or
significance in the value of an arithmetic complex.
integer; all zeros to the left of the first
si~nificant integer digit of a number. multiple declaration: two or more
declarations of the same identifier
level number: an unsigned decimal integer internal to the same block without
constant in a DECLARE or ALLOCATE statement different qualifications, or two or more
that specifies the position of a name in external declarations of the same
the hierarchy of a structure. It precedes identifier with different attributes in the
the name to which it refers and is same program.
separated from that name by the name's
delimiter. Level numbers appear without mUltiprocessinq: the use of a computing
the names in a parameter descriptor of an system with two or more processing-units to
ENTRY attribute specification. execute two or more programs
simultaneously.
level-one variable: a major structure
name; any unsubscripted variable not mUltiprogramming: the use of a computing
contained within a structure. system to execute more than one program
concurrently, using a single processing
list-directed transmission: the type of unit.

518 OS PL/I CRT AND OPT LRM PART II

multitasking: a facility that allows a excludes SYSTEM and SNAP.
programmer to execute more than one PL/I
procedure simultaneously. opening (of a file): the association of a
file with a data set and the completion of
name: an identifier appearing in a context a full set of attributes for the file name.
where it is not a keyword.
operand: an expression to whose value an
nesting: the occurrence of: operator is applied.

1. A block within another block. operational expression: an expression

containing one or more operators.
2. A group within another group.
operator: a symbol specifying an operation
3. An IF statement in a THEN clause or an to be performed. See arithmetic operators,
ELSE clause. bit-string operators, comparison operators
and concatenation.
4. A function reference as an argument of
a function reference. option: a specification in a statement
that may be used to influence the execution
5. A remote format item in the format or interpretation of the statement.
list of a FORMAT statement.
packed decimal: the internal
6. A parameter descriptor list in another representation of a fixed-point decimal
parameter descriptor list. data item.

7. An attribute specification within a padding:

parenthesized name list for which one
or more attributes are being factored. 1. one or more characters or bits
concatenated to the right of a string
non-connected storage: separate locations to extend the string to a required
in storage that contain related items of length. For character strings,
data that can be referred to by a single padding is with blanks; for bit
name but that are separated by other data string, with zeros.
items not referred to by that name.
Examples are the storage referred to by an 2. one or more characters or bits
unsubscripted elementary name in an array inserted in a structure so that the
of structures or by a subscripted name structure elements have the required
referring to an array cross section in alignment.
which the subscript list contains an
asterisk to the left of any element parameter: a name in a procedure that is
expression. used to refer to an argument passed to that
procedure.
null locator value: a special locator
value that cannot identify any location in parameter descriptor: the set of
internal storage: it gives a positive attributes specified for a single parameteI;'
indication that a locator variable does not in an ENTRY attribute specification.
currently identify any generation of data.
parameter descriptor list: the list of all
null string: a string data item of zero parameter descriptors in an ENTRY attribute
length. specification.

numeric character data: see decimal parameter list: a parenthesized list of

picture data. one or more parameters, separated by commas
following either the keyword PROCEDURE in a
offset variable: a locator variable with PROCEDURE statement, or the keyword ENTRY·
the OFFSET attribute, whose value in an ENTRY statement. The list
identifies a location in storage, relative corresponds to a list of arguments passed
to the beginning of an area. at invocation.

on-condition: an occurrence, within a PL/I partially-qualified name: a qualified name

task, that could cause a program interrupt. that is incomplete, i.e., that includes one
It may be the detection of an unexpected or more, but not all, names in the
error or of an occurrence that is expected, hierarchical sequence above the structure
but at an unpredictable time. member to which the partially-qualified
name refers, as well as the name of the
on-unit: the specified action to be member itself.
executed upon detection of the on-condition
named in the cpntaining ON statement. This picture specification: a character-by-

Glossary 519
character description of the composition reference.
and characteristics of decimal picture data
and character-string picture data. processor: a program that prepares source
program text (possible preprocessed text)
picture specification character: any of for execution.
the characters that can be used in a
picture specification. See decimal picture program: a set of one or more external
data and character-string picture data. procedures, one of which must have the
OPTIONS (MAIN) option in its PROCEDURE
point of invocation: the pOint in the statement.
invoking block at which the procedure
referenceto the invoked procedure appears. proqram control data: data used in a PLII
program to effect the execution of the
pointer variable: a locator variable with program. Program control data consists of
the POINTER attribute, whose value the following types: entry, task, file,
identifies an absolute location in main label, event, pointer, offset, and area.
storage.
prologue: the processes that occur
precision: the value range of an automatically on block activation.
arithmetic variable expre'ssed as a total
number of digits and, for fixed-point pseudovariable: any of the built-in
variables, the number of those digits function names that can be used to specify
assumed to appear to the right of the a target variable.
decimal or binary point.
qualified name: a hierarchical sequence of
prefix: a label or a parenthesized list of names of structure members, conrtected by
one or more condition names connected by a periods, used to identify a component of a
colon to the beginning of a statement. structure. Any of the names may be
subscripted. See also locator
prefix operator: an operator that precedes qualification.
an operand and applies only to that
operand. The prefix operators are + ranqe (of a default specification): a set
(plus), - (minus), and ~ (not). of identifiers and/or parameter descriptors
to which the attributes in a default
preprocessor: a program that examines the specification of a DEFAULT statement apply.
source program for preprocessor statements
which are then executed, resulting in the record: the logical unit of transmission
alteration of the source program. in a record-oriented input or output
operation.
preprocessor statement: a special
statement appearing in the source program recorded key: a key recorded in a direct-
that specifies how the source program text access volume to identify an associated
is to be altered; i t is executed as it is data record.
encountered by the preprocessor.
recursive procedure: a procedure that may
primary entry point: the entry point be reactivated while still active in the
identified by any of the names in the label same task.
list of the PROCEDURE statement.
reentrant procedure: a procedure that may
priority: a value associated with a task, be reactivated while active in another
that specifies the precedence of the task task.
relative to other tasks.
REFER expression: the expression preceding
problem data: string or arithmetic data the keyword REFER, from which an original
that is processed by a PL/I program. bound, length, or size is taken when a
based variable containing a REFER option is
procedure: a collection of statements, allocated, either by an ALLOCATE or LOCATE
headed by a PROCEDURE statement and ended statement.
by an END statement, that is a part of a
program, that delimits the scope of names, REFER Object: the unsubscripted element
and that is activated by a reference to one variable appearing in a REFER option that
of its entry names. specifies a current bound, length, or size
for a member of a based structure. It must
procedure reference: an entry constant or be a member of the structure, and it must
variable or a built-in function name. The precede the member declared with the REFER
name may be followed by one or more option.
argument lists. It may appear in a CALL
statement or CALL option or as a function reference: the appearance of a name,

520 OS PL/I CKT AND OPT LRM PART II

except in a context that causes explicit self-defining data: a data item, or an
declaration. aggregate of data items, that includes
descriptive information about attributes of
remote format item: the letter R specified the data, such as values for adjustable
in a format list together with the label of bounds or lengths.
a separate FORMAT statement.
separator: see delimiter.
repetition factor: a parenthesized
unsigned decimal integer constant that sign and currency symbol characters: the
specifies: picture specification characters, S, +, -
and $. These can be used
1. The number of occurrences of a string
configuration that make up a string 1. As static characters in which case
constant. they are specified only once in a
picture specification and appear in
2. The number of occurrences of a picture the associated data item in the
specification character in a picture position in which they have been
specification. specified.

repetitive specification: an element of a 2. As drifting characters, in which case

data list that specifies controlled they are specified more than once (as
iteration to transmit one or more data a string in a picture specification)
items, generally used in conjunction with but appear in the associated data item
arrays. at most once, immediately to the left
of the significant portion of the data
returned value: the value returned by a item.
function procedure to the point of
invocation. significant a1location: any unfreed
allocation in an area and any freed
scalar item: a single item of data; an allocation that lies between the start of
element. the area and the end of the unfreed
allocation that is farthest from the start
scalar variable: a variable that can of the area. If a subsequent allocation of
represent only a single data item; an the same size is made in the same location
element variable. the original allocation ceases to be
significant.
scale: a system of mathematical notation:
fixed-point or floating-point scale of an simple parameter: a parameter for which nO
arithmetic value. storage-class attribute is specified; it
may represent an argument of any storage
scale factor: a specification of the class, but only the current generation of a
number of fractional digits in a fixed- controlled argument.
point number.
source key: a key referred to in a record-
scope (of a condition prefix): the portion oriented transmission statement that
of a program throughout which a particular identifies a particular record within a
condition prefix applies. direct-access data set.

scope (of a declaration): the portion of a source program: the program that serves as
program throughout which a particular input to the compiler. The source program
declaration is a source of attributes for a may contain preprocessor statements.
particular name.
source variable: a variable whose value is
scope (of a name): the portion of a to be aSSigned or to take part in some
program throughout which the meaning of a other operation.
particular name does not change.
standard default: the alternative
secondary entry point: an entry point attribute or option assumed when none has
identified by any of the names in the label been specified and there is no applicable
list of an ENTRY statement. DEFAOLT statement.

I select-group: a sequence of selection standard file: a file assumed by the

'clauses headed by a SELECT statement and processor in the absence of a FILE or
Iclosed by its corresponding END statement, STRING option in a GET or PUT statement;
,
lused for control purposes.

,selection clause: A WHEN or OTHERWISE

SYSIN is the standard input file and
SYSPRINT is the standard output file.

Iclause of a select-group. standard system action: action specified

Glossary 521
by the language to be taken in the absence in which they appear, their attributes, and
of an on-unit for an on-condition. their logical level (but not necessarily
their names or declared level numbers).
statement: a basic element of a PL/I
program that is used to delimit a portion
of the program, to describe names used in subfield (of a picture specification):
the program, or to specify action to be that portion of a picture specification
taken. A statement can consist of a field that appears before or after a V
condition list, a label list, a statement picture specification character.
identifier, and a statement body that is
terminated by a semicolon. subroutine: a procedure that is invoked by
a CALL statement or CALL option. A
statement body: that part of a statement subroutine cannot return a value to the
that follows the statement identifier, if invoking block, but it can alter the value
any, and is terminated by the semicolon: it of variables.
includes the statement options.
SUbscript: an element expression that
statement identifier: the PL/I keyword specifies a position within a dimension of
that indicates the purpose of the an array. A subscript can also be an
statement. asterisk, in which case it specifies the
entire extent of the dimension.
statement-label constant: see label
constant. subscript list: a parenthesized list of
one or more subscripts, one for each
statement-label expression: see label dimension of an array, which together
expression. uniquely identify either a single element
or cross section of the array.
statement-label variable: see label
variable. subtask: a task that is attached by the
given task or any of the tasks in a direct
static storage allocation: the allocation line from the given task to the last
of storage for static variables. attached task.

static variable: a variable that is synChronous: using a single flow of

allocated before execution of the program control for serial execution of a program.
begins and that remains allocated for the
duration of execution of the program. target variable: a variable to which a
value is assigned.
stream: see data stream.
task: the execution of one or more
string: a connected sequence of characters procedures by a Single flow of control.
or bits that is treated as a single data
item. task name: an identifier used to refer to
a task variable.
strinq variable: a variable declared with
the BIT or CHARACTER attribute, whose task variable: a variable with the TASK
values can be either bit strings or attribute whose value gives the relative
character strings. priority of a task.

structure: a hierarchical set of names termination (of a block): cessation of

that refers to an aggregate of data items execution of a block, and the return of
that may have different attributes. control to the activating block by means of
a RETURN or END statement, or the transfer
structure expression: an expression whose of control to the activating block or to
evaluation yields a structure set of some other active block by means of a GO TO
values. statement.

structure of arrays: a structure termination (of a task): cessation of the

containing arrays specified by declaring flow of control for a task.
individual members names with the dimension
attribute. truncation: the removal of one or more
digits, characters, or bits from one end of
structure member: any of the minor an item of data when a string length or
structures or elementary names in a precision of a target variable has been
structure. exceeded.

structurinq: the makeup of a structure, in upper bound: the upper limit of an array
terms of the number of members, the order dimension.

522 OS PL/I CRT AND OPT LRM PART II

variable: a named entity that is used to virtual point picture character: the
refer to data and to which values can be picture specification character, V, which
assigned. Its attributes remain constant, is used in picture specifications to
but it can refer to different values at indicate the position of an assumed decimal
different times. Variables fall into three or binary point.
categories, applicable to any data type:
element, array, and structure. Variables zero-suppression characters: the picture
may be subscripted and/or qualified, or specification characters Z, Y, and *, which
locator qualified. are used to suppress zeros in the
corresponding digit positions.

Glossary 523
 Index

ASS built-in function 364

access
+ picture character 322 direct 183,181,190,191
sequential 183,189,181,191
accuracy of mathematical built-in
II concatenation symbol 40 functions 355
ACOS built-in function 364
activation of blocks 65
$ currency symbol 9,322 ADD built-in function 364
$ picture character 211 ADDBUFF option 114
additive attributes 123,125
BACKWARDS attribute 125
* (asterisk) notation ENVIRONMENT attribute 125
ALLOCATE.statement 90 EXCLUSIVE attribute 125
array cross-sections 21 KEYED attribute 125
controlled parameters 118 locked record 125
CONTROLLED variables 90 PRINT attribute 125
simple parameters 118 ADDR built-in function 364,93
* picture character 210 address
* zero suppression character 318 symbolic names 15
*/ (comment identifier) 11 aggregates
arguments 356
data 4,155,285
/ insertion character 319 algebraic comparisons 39
/ insertion picture characters 211 aliased variable 276
/* (comment identifier) 11 ALIGNED attribute 31,405
alignment, record 502
ALL built-in function 364
, insertion character 318 ALL option 62
ALLOCATE statement 439,53
for based variables 97
IACTIVATE preprocessor statement 478 for controlled variables 89
lassignment preprocessor statement 419 with IN option 100
ICONTROL listing control statement 483 allocation
IDEACTIVATEpreprocessor statement 419 buffer 152,161
IDECLARE preprocessor statement 419 of storage 10
IDO preprocessor statement 480 ALLOCATION built-in function 364,91
IELSE clause 248,481 allocation of parameters 111
lEND preprocessor statement 480 asterisk notation 118
IGO TO preprocessor statement 480 bounds, lengths, and sizes 111
IIF preprocessor statement 481 controlled parameter 117
IINCLUDE preprocessor statement 481 expression notation 118
INOPRINT listing control statement 484 parameter attributes 111
INOTE preprocessor statement 482 simple parameter 111
Inu1l preprocessor statem 482 alphabetiC character 9
IPAGE listing contro atement 484 alphabetic list of format items 326
IPRINT listing cont 01 statement 484 A-format item 326
IPROCEDURE preprocessor statement 482 B-format item 326
ISKIP listing contro~ statement 485 C-format item 327
ITHEN clause 248,481 COLOMN format item 321
conversion rules 335
E-format item 328
• number sign 9 F-format item 329
LINE format item 330
P-format item 330
I commercial -at- sign 9 PAGE format item 330
R-format item 331
SKIP format item 331
A picture specification character 22 X-format item 331
A-format item 326 alphameric character 9
abbreviations of keywords 309 altering length of string data 207
abnormal termination of progr~ 69 alternate-index 192

Index 525
alternative attributes 123 array (continued)
BUFFERED and UNBUFFERED 124 dimension 25
INPUT, OUTPUT, and UPDATE 124 extent 25
SEQUENTIAL, DIRECT and TRANSIENT 124 infix operators with 44
STREAM and RECORD 124 parameter 119
ambiguous references 80 prefix operators with 44
amending a program 237 subscripts 26
American standard code for information array expressions 35
interchange (ASCII) 153 converting 44
ANY built-in function 365 data conversion in 45
application of attributes 81 evaluation of 43
application of standard defaults 81 in IF clauses 44
problem data 82 array of structures 29
program control data 82 cross-sections or 29
area 155,98 array-and-array operations 44
ALLOCATE statement with IN option 100 array-and-element operations 44
assignment 101 array-and-structure operations 45
condition 101,393 array-handling built-in functions 354,355
condition codes 386 ASCII (American standard code for
data 25 information interchange) 153
EMPTY built-in function 101 ASCII data sets 153,177
extent of 99 block prefix fields 153,178
FREE statement with IN option 101 BUFOFF option 153,178
input/output of 102 D-format record 154
locator conversion 99 D-format records 178
offset expressions 100 DB-format record 154
offset variables 99 DB-format-records 118
parameter 120 default rules 154,118
variables 155,99 ASCII option 153,171
AREA attribute 408 ASIN built-in function 365
AREA condition 101 ASSE~mLER option 432
ARGn option 291 assignment
argument 119 and initialization 281
aggregate 356 area 101
area parameter 120 BY NAME 46.
array parameter 119 data conversion 36
conversion of 354 editing by 201
dummy 113 other forms of 208
element parameter 119 statement 12,441,51
entry expressions as 115 associating data sets with files 128
entry parameter 119 asterisk (*) notation
file parameter 119 ALLOCATE statement 90
label parameter 119 array cross-sections 21
locator parameter 120 controlled parameters 118
null 356 CONTROLLED variables 90
preprocessor functions 244 simple parameters 11.8
string parameter 120 asynchronous operation 158,251
structure parameter 119 ATAN built-in function 365
arithmetic ATAND bUiit-in function 365
built-in functions 353,355 ATANB built-in function 365
conversion 36 ATTENTION
operation 282 condition 393
operators 10 condition code 386
overflow 17 attribute 405
arithmetic built-in function additive 123,125
arithmetic built-in functions ALIGNED 31,405
arithmetic data alternative 123
base 16 AREA 408
description 15 AUTOMATIC 408
mode 16 BACKWARDS 125,410
precision 16 BASED 408
scale 16 BINARY 410
arithmetic operations 353 BIT 410
general discussion 38 BUFFERED 124,411
results of 38 BUILTIN 411
array 25 CHARACTER 410
bounds 25 COMPLEX 19,412
cross-sections 27 CONDITION 412

526
attribute (continued) BASED attribute 408
CONNECTED 412 based storage 91
CONTROLLED 408 ADDR built-in function 93
DECIMAL 410 ALLOCATE statement 97
declarations 279 area assignment 101
default 81 areas 98
DEFINED 30,413 based variables 91
dimension 411 based variables and input/output 93
DIRECT 417 FREE statement 97
ENTRY 106,114,418 input/output of areas 102
ENVIRONMENT 125,148,162,199,421 list processing 96
EVENT 421 locator qualification 91
EXCLUSIVE 125,423 multiple generations of based
EXTERNAL 423,78 variables 91
file 123,423 multiple locator qualification 102
FIXED 424 NULL built-in function 98
FLOAT 424 pOinter variables 92
GENERIC 425 self-defining data (REFER option) 95
INITIAL 32,426 types of list 98
INPUT 428 based variables 91,93
INTERNAL 423,78 ALLOCATE statement for 97
IRREDUCIBLE 428 and input/output 93
iSUB defining 415 FREE statement for 97
KEYED 125,429 multiple generations of 97
LABEL 429 processing mode 93
length 410 based variables and input/output
LIKE 30,430 LOCATE statement 94
merging of 127 READ with SET statement 94
of returned values 109 batch processing 227
OFFSET 431 begin block 63
OPTIONS 432 as on-unit 63
OUTPUT 428 definition 13
parameter 117,434 termination of 67
parameter descriptor lists 418 BEGIN statement 443,53
PICTURE 19,22,434 BINARY attribute 410
POINTER 431 BINARY built-in function 365
POSITION 30,413 binary digit (bit) 9
prec:1.s:1.on 435 binary fixed-point data 17
PRINT 125,436 default precision 17
processes in application of 81 maximum length 17
REAL 412 binary floating-point data 18
RECORD 124,436 default precision 19
REDUCIBLE 428 extended form 19
RETURNS 110,431 long form 19
SEQUENTIAL 417 maximum size 19
simple defining 414 short form 19
size 408 bit (binary digit) 9
specifications 83 BIT attribute 410
specifying 15 BIT built-in function 214,366
STATIC 408 bit comparisons 39
STREAM 124,436 bit to arithmetic conversion 331
string overlay defining 416 bit to character conversion 346
targets in aSSignment 43 bit to numeric character conversion 344
TASK 437 bit-string
TRANSIENT 202,417 data 22
UNALIGNED 31,405 handling 213
UNBUFFERED 124,411 operations 38
UPDATE 428 operators 10
VARIABLE 438 unaligned 155
VARYING 21,410 BKWD option 170
AUTOMATIC attribute 408 BKWK option 162
automatic storage 87,88 blanks 10
BLKSIZE option 150,166
block
B insertion character 319 activation of 65
B-format item 326 begin 63
BACKWARDS attribute 125,410 definition 13
base of arithmetic data 16 external 64

Index 527
block (continued) built-in function (continued)
general discussion 63 EXP 370
internal 64 FIXED 370
nested 64 FLOAT 370
prefix fields 153,118 FLOOR 370
procedure 63 HBOUND 370
termination of 61 HIGH 215,370
BOOL built-in function 215,366 I MAG 370
in bit-string operations 39 INDEX 214,370
Boolean algebra 39 input/output 354
bounds LBOUND 371
·controlled parameter 118 LENGTH 215,371
simple parameter 118 LINENO 371
bounds of array dimension 25 LOG 371
buffer allocation 152,161 LOG10 371
BUFFERS option 152,161 LOG2 371
DCB subparameter 152 LOW 215,372
BUFFERED attribute 124,411 mathematical 353,355
BUFFERS option 152,161 MAX 372
BUFND option 162,110 MIN 372
BUFNI option 162,110 miscellaneous 354
BUFOFF option 153,118 MOD 372
BUFSP option 162,110 MULTIPLY 312
built-in multitasking 354
functions 111 NULL 373,98
subroutines 112 null arguments 356
built-in function OFFpET 373
ABS 364 ONCHAR 373
accuracy of mathematical functions 355 ONCODE 373
ACOS 364 ONFILE 373
ADD 364 ONKEY 373
ADDR 364,93 ONLOC 374
aggregate arguments 356 ONSOURCE 373
ALL 364 PARMSET 374
ALLOCATION 364,91 PLIRETV 375
ANY 365 POINTER 375
arithmetic 353 POLY 375
array-handling 354,355 PRECISION 375
ASIN 365 preprocessor 354
ATAN 365 PRIORITY 375
ATAND 365 PROD 376
ATANH 365 REAL 376
BINARY 365 REPEAT 215,376
B:::T 214,366 ROUND 376
BOOL 215,366 SAMEKEY 376
CEIL 366 SIGN 377
CHAR 214,366 SIN 377
classification of 353 SIND 377
COMPILETIME 336 SINH 377
COMPLETION 257,366,400 SQRT 377
COMPLEX 367 STATUS 257,377
condition-handling 354 STORAGE 377
CONJG 367 storage control 354
conversion of arguments 354 string 214,215,378
COS 367 string-handling 353,355
COSD 367 SUBSTR 214,378
COSH 367 SUM 379
COUNT 367 TAN 379
COUNTER 368 TAND 379
CURRENTSTORAGE 368 TANH 379
DATAFIELD 368 TIME 379
DATE 369 TRANSLATE 215,379
DECI~..AL 369 TRUNC 380
DIM 369 UNSPEC 215,380
DIVIDE 369 used in data conversion 37
EMPTY 101,369 VERIFY 215,381
ERF 369
ERFC 369 BUILTIN attribute 411

528
BY NAME option 46 characteristics, data 15
BY option 56 characters
byte 31 special 9
CHECK condition 221,393
CHECK condition codes 386
C-format item 327 CHECK condition prefix 394
CALL option 32 CHECK statement 228,445,61
CALL statement 253,444,59 checkout compiler, facilities of 6
EVENT option 253 classes of statements 49
PRIORITY option 254 descriptive statements 49
TASK option 253 DISPLAY statement 51
case selection procedure blocks 63
(see select-group) classification
CEIL built-in function 366 key (GENKEY) 114
CEIL values of built-in functions 353
table of 333 of conditions 392
chained list 97 of statements 49
channel programs (NCP) classification of built-in functions 353
number of 115 arithmetic built-in functions 353
CHAR built-in function 214,366 array-handling built-in functions 354
character condition-handling built-in
• (period) 211 functions 354
+ picture 322 input/output built-in functions 354
* zero suppression 318 mathematical built-in functions 353
/ insertion 319 miscellaneous built-in functions 354
, (comma) 211 multitasking built-in functions 354
, insertion 318 preprocessor built-in functions 354
alphabetic 9 storage control built-in functions 354
alphameric 9 string-handling built-in functions 353
B (insertion) 211 classification of conditions 392
B insertion 319 AREA condition 393
comparisons 39 ATTENTION condition 393
CR picture 322 CHECK condition 393
DB picture 322 COMPLETION built-in func~ion 400
E picture 324 CONDITION condition 396
F picture 324 CONVERSION condition 396
-I picture 322 ENDFILE condition 396
insertion 318 ENDPAGE condition 391
K picture 324 ERROR condition 397
picture 211,322 FINISH condition 398
picture specification 315 FIXEDOVERFLOW condition 398
R picture 322 KEY condition 398
S picture 322 NAME condition 399
special 10 OVERFLOW condition 400
T picture 322 PENDING condition 400
Z zero suppression 318 RECORD condition 400
zero suppression 311 SIZE condition 401
CHARACTER attribute 410 STRINGRANGE condition 401
character sets 301 STRINGSIZE condition 402
introduction 9 SUBSCRIPTRANGE condition 402
use of 10 TRANSMIT condition 402
with EBCDIC and card-punch codes 307 UNDEFINEDFILE condition 403
48-character set 308 UNDERFLOW condition 404
60-character set 307 ZERODIVIDE condition 404
character specifications clause
numeric 209 "ELSE 481
character strings "THEN 481
and comments 241 ELSE 461
PICTURE attribute 22 OTHERWISE 414
character to arithmetic conversion 331 THEN 461
character to bit conversion 348 WHEN 414
character to numeric character CLOSE statement 130,446
conversion 343 clOSing file 126
character-string data 21 in dynamically-loaded procedure 10
picture characters for 315 clOSing nested blocks and groups 64
repetition factors 21 closure of blocks 61
character-string picture COBOL interface 297
specifications 212 COBOL option 291

Index 529
COBOL routine comparison (continued)
passing arguments to 290 operators 10
termination of 296 program control data 39
code tables for 353
AREA condition 386 compile-time operations 6
ATTENTION condition 386 compiler
card punch 307 differences 505
CHECK condition 386 facilities of 6
condition 383 COMPILETIME built-in function 366
condition built-in functions 223 COMPLETION
CONDITION condition 386 built-in function 251,366,400
CONVERSION condition 386 pseudovariable 361
EBCDIC 307 complex arithmetic data 16,19
ENDFILE condition 384 COMPLEX attribute 19,412
END PAGE condition 385 COMPLEX built-in function 367
ERROR condition 384 COMPLEX pseudovariable 367
FINISH condition 384 complex to real conversion 331
FIXEDOVERFLOW condition 385 compound statement 12
information interchange 122 computational statement type 51
KEY condition 384 concatenation operations 40
NAME condition 384 concatenation symbol (II) 40
OVERFLOW condition 385 concepts of PL/I 1
PENDING condition 385 blanks 10
RECORD condition 384 identifiers 10
return 299 string data 21
SIZE condition 385 condition
STRINGRANGE" condition 386 AREA 393
STRINGSIZE condition 385 ATTENTION 393
SUBSCRIPTRANGE condition 386 built-in functions 223
TRANSMIT condition 384 CHECK 221,393
UNDEFINEDFILE condition 384 classification of 392
UNDERFLOW condition 385 codes (ON-codes) 383
ZERODIVIDE condition 385 condition 221,396
coding format 9 condition code 386
coding source programs for optimizing CONVERSION 396
compiler disabling 12
aliased variable 276 ENDFILE 396
common expression elimination 276 END PAGE 391
other optimization features 278 ERROR 202,391
redundant expression elimination 278 FINISH 398
transfer of invariant expressions 277 FIXEDOVERFLOW 398
collections, data 4 KEY 398
COLUMN format item 327 list of 392
comments 11,241 NAME 399
commercial nat" sign (w) 9 OVERFLOW 400
common errors and pitfalls 278 PENDING 203,400
arithmetic and logical operations 282 prefix 12.,217
assignments and initialization 281 RECORD 202,400
data aggregates 285 SIZE 17,222,401
declarations and attributes 219 STRINGRANGE 222,401
do-groups 284 STRINGSIZE 402
functions and pseudovariables 285 SUBSCRIPTRANGE 222,402
input/output 286 TRANSMIT 202,402
on-conditions and on-units 285 UNDEFINEDFILE 403
operating system and job control 218 UNDERFLOW 404
program control 279 ZERODIVIDE 404
source program and general syntax 218 CONDITION attribute 412
strings 285 condition codes (ON-codes) 383
common expression AREA condition codes 386
elimination 276 ATTENTION condition code 386
interrupt handling 274 CHECK condition codes 386
common storage 293 CONDITION condition code 386
communication, inter language 289 CONVERSION condition codes 386
comparison 39 ENDFILE condition code 384
bit 39 ENDPAGE condition code 385
character 39 ERROR condition code 384
conversion of operands in 39 FINISH condition codes 384
operations 39 FIXEDOVERFLOW condition code 385

530
condition codes (ON-codes) (continued) conversion (continued)
KEY condition codes 384 of program control data 37
NAME condition codes 384 rules 33!>
OVERFLOW condition code 385 type 36
PENDING condition code 385 CONVERSION condition 396,41
RECORD condition codes 384 conversion of arguments 354
SIZE condition code 385 array-handling built-in functions 355
STRINGRANGE condition code 386 mathematical built-in functions 355
STRINGSIZE condition code 385 string-handling built-in functions 355
SUBSCRIPTRANGE condition code 386 conversion of data
TRANSMIT condition codes 384 by built-in function 37
UNDEFINEDFILE condition codes 384 in arithmetic operations 38
UNDERFLOW condition code 385 in assignments 36
ZERODIVIDE condition code 385 in comparison operations 39
CONDITION condition 221,396 in operational expressions 36
condition-handling built-in functions 354 coordination and synchronization of
CONJG built-in function 367 tasks 255
CONNECTED attribute 412 DELAY statement 257
connected storage 117 sharing files between tasks 256
CONSECUTIVE data sets 152,168 testing and setting event variables 256
CONSECUTIVE option 162 WAIT statement 256
consecutive organization 178 coordination of tasks
sequential update 179 sharing data between tasks 255
constant COpy option 135
definition 15 COS built-in function 367
file 122 COSO built-in function 361
contained in, definition 75 COSH built-in function 361
contextual declaration 76 COUNT built-in function 367
control COUNTER built-in function 368
format items 325 CR picture character 322
printer/punch 112 creating data set 183,189,190
program 279 creation of tasks 253
storage 81 call statement 253
control area 122 priority of tasks 254
control data, program 23 credit, debit, and overpunched signs 322
control format CR picture character 322
control interval 122 DB picture character 322
control statement I picture character 322
listing 249,483 R picture character 322
type 54 T picture character 322
control variable 55 cross sections
CONTROLLED arrays 27
data 10 arrays of structures 29
parameter 117 CTLASA option 112
storage 88 CTL360 option 172
structures 91 currency symbol ($) 9,319
CONTROLLED attribute 408 current status list 232
controlled parameter PUT ALL statement 236
bounds, lengths, and sizes 118 PUT FLOW statement 235
controlled storage 88 PUT SNAP statement 235
ALLOCATE statement 89 PUT variables 232
ALLOCATION built-in function 91 CURRENTSTORAGE built-in function 368
controlled structures 91
FREE statement 89
multiple generations 90 D option 162
controlled variables O-format record 154,178
ALLOCATE statement for 89 data
FREE statement for 89 aggregates 155,285
multiple generations of 90 binary fixed-point 17
conversational processing 227 binary floating-point 18
conversion conversion 271
arithmetic 36 deCimal fixed-point 16
condition 396 description 3
condition codes 386 elements 15
data 271,35 format items 325
in concatenation operations 40 interchange (COBOL) 173
locator 99 lists 136
of arguments 354 mapping 290,487

Index 531
data (continued) data-directed transmission 133
organization 25 DATAFIELD built-in function 368
problem 290,82 DATE built-in function 369
program control 290,82 DB option 162
set organization 152,168 DB picture character 322
sets 121 DB-format. record 154,178
specifications 136 DCB sUbparameter 152,176
string 21 DECIMAL attribute 410
transmission statements 134,155 DECIMAL built-in function 369
transmitted 155 decimal digit 9
types 3,15,290 decimal digit specifier 317
data conversion 271,35 decimal fixed-point data 16
and expression evaluation 335 default precision 17
exceptional conditions 47 maximum length 17
expressions and 35 deCimal floating-point data 18
in array expres~ions 45 default precision 18
in assignments 36 maximum length 18
in operational expressions 36 decimal-point specifier 317
source to target rules 335 declaration
data lists 136 attributes 279,49
repetitive specification 137 contextual 76
transmission of data-list elements 138 examples 77
data management optimization 174 explicit 75
ADDBUFF option 174 implicit 77
INDEXAREA option 174 record files 205
NOWRITE option 174 DECLARE statement 446,49
data mapping 290,487 default
record alignment 502 assumptions 3
structure mapping 487 attributes 81
data movement statement type 51 record format 151,167
DATA option 140 restoring standard 84
data set 121 rules 154,178
ASCII 153,177 specification, factored 85
CONSECUTIVE 152 statement 83
creating 183,189,190 default attributes 81
information interchange codes 122 application of standard defaults 81
organization 152,168 control of by programmer 49
teleprocessing 171 processes in application of
data set organization attributes 81
CONSECUTIVE 152,168 default precision
INDEXED 168 b~nary fixed-point data 17
REGIONAL 168 binary floating-point data 19
VSAM 168,192 decimal fixed-point data 17
data specification 136 decimal floating-point data 18
data lists 136 default statement 447,49,83
data-directed 140 attribute specifications 83
edit-directed 143 DESCRIPTORS option 83
list-directed 138 factored default specification 85
data transmission statements 134,155 programmer-defined defaults 85
DELETE statement 156 restoring standard defaults 84
LOCATE statement 156 restrictions 85
READ statement 156 scope of 84
REWRITE statement 156 DEFINED attribute 30,413
UNLOCK statement 156 defining
WRITE statement 156 iSUB 415
data transmitted 155 simple 414
area variables 155 string overlay 416
data aggregates 155 DELAY statement 257,450
unaligned bit strings 155 DELETE statement 156,450
varying-length strings 155 descendant on-units
data-directed data specification 140 descriptive statements 49
data-directed data in stream 140 descriptor lists, parameter 114
data-directed data specification for DESCRIPTORS option 83
input 141 device-associated files 176
data-directed data specification for diagnostic statements 61
output 142 differences, compiler
example 143 digit
length of output fields 143 binary (bit) 9

532
digit (continued) END statement 101,454,53,59
decimal 9 as procedure delimiter 52
digit specifier 317 with nested blocks and groups 64
DIM built-in function 369 ENDFILE
dimension attribute 25,417 condition 396
direct access 183,187,190,191 condition code 384
DIRECT attribute 417 END PAGE
disabling conditions 12 condition 391
DISPLAY statement 451,51 condition code 385
DIVIDE built-in function 369 entry attribute 106,114,418
Do loops 451 entry expressions as arguments 115
DO statement 451,55 parameter descriptor lists 114
do-group 284 entry data 24
definition 13 entry expressions as arguments 11S
preprocessor 247 entry parameter 119
doubleword 31 entry pOints
dummy arguments 113 fUnctions 106
dummy records 183,189,185,190 primary 66
dynamic 69 secondary 66
allocation of storage 70 subroutine 106
loading of external procedure 69 ENTRY statement 455,52
dynamically descendant on-units 219 environment
establishing FORTRAN 294
establishing PL/I 294
E picture character 324 interlanguage 294
E-format item 328 ENVIRONMENT attribute 125,199,421
EDIT option 143 for RECORD files 162,114
edit-directed data specification 143 ADDBUFF option 114
format lists 144 ASCII option 177
edit-directed format items 325 BKWD option 110
alphabetic list 326 BLKSIZE option 166
control format items 325 block prefix fields 118
data format items 325 buffer allocation 167
remote format item 326 BUFFERS option 161
table of CEIL values 333 BUFND option 170
edit-directed transmission 134 BUFRI option 110
editing by assignment 207 BUFOFF option 118
altering length of string data 207 BUFSP option 110
picture specification 209 COBOL option 173
editing characters CONSECUTIVE option 168
numeric picture specification 20 CTLASA option 112
element CTL360 option 112
data 15 D-format record 118
expression 35 data interchange (COBOL) 173
parameter 119 data management optimization 114
elimination data set organization 168
common expression 276 DB format record 118
redundant expression 276,218 device-associated files 116
ELSE clause 461 GENKEYoption 114
embedded keys 180 in-line code optimization
EMPTY built-in function 101,369 (TOTAL) 114
enabled conditions INDEXAREA option 174
CHECK condition 221 INDEXED option 168
condition built-in functions 223 key classification (GENKEY) 114
condition codes 223 key length option (KEYLENGTB) 116
CONDITION condition 221 key location option (KEYLOC) 116
condition prefixes 217 KEYLENGTB option 116
dynamically descendant on-units 219 KEYLOC option 116
null on-unit 219 LEAVE option 111
ON statement 218 magnetic tape handling options 171
on-units 219 NCP option 175
REVERT statement 221 NOwRITE option 174
scope of condition prefix 218 number of channel programs
scope of ON statement 219 (NCP) 115
SIGNAL statement 221 optimization options 170
SIZE condition 222 PASSWORD option 169
STRINGRANGE condition 222 printer/punch control 172
SUBSCRIPTRANGE condition 222 record format options 162

Index 533
ENVIRONMENT attribute (continued) expression (continued)
for RECORD files (continued) notation 118
RECSIZE option 165 offset 100
REGlbNAL option 168 operational 35
REREAD option 111 operations 37
REUSE option 110 pOinter 92
SCALARVARYING option 115 preprocessor 242
SIS option 169 simplification 216
SKIP option 169 structure 35
teleprocessing 111 expression and data conversion
TOTAL option 170,114 ambiguous references 80
TP(M) option 111 classes of statements 49
TP(R) option 171 default attributes 81
track overflow (TRKOFL) 175 default statement 83
TRKOFL option 115 EXTERNAL attribute 78
VSAM option 168 INTERNAL attribute 18
for STREAM files 148 multiple declarations 80
ASCII data sets 153 prologues and epilogues 12
block prefix fields 153 expressions and data conversion 35
buffer allocation option 152 extended floating-point form 19
BUFFERS option 152 extent
BOFOFF option 153 of area 99
CONSECUTIVE option 152 of array dimension 25
D-format record 154 EXTERNAL attribute 423,18
data set organization options 152 external blocks 64
DB-format record 154 external names
LEAVE option 153 format restrictions 10
magnetic tape handling options 153 truncation of by compiler 10
record format options 149 external procedure
REREAD option 153 definition (>4
epilogue 13 dynamic loading 69
ERF built-in function 369 external text
ERFC built-in function 369 inclusion of 241
error
condition code 384
conditions 12 F option 162
handling 202 F picture character 324
ERROR condition 202,391 F-format item 329
error condition code 384 facilities
established action interlanguage 289
establishing FORTRAN environment 294 traCing 228
establishing PL/I environment 294 factor, scaling
EVENT attribute 421 factored default specification 85
event data 24 FB option 162
EVENT option 158 FBS option 162
exception control statements 59 FETCH statement 456,53,69
exceptional conditions fetched procedures
during data conversion 41 file
EXCLUSIVE attribute 125,423 additive attributes 125
execution-time facilities 6 alternative attributes 123
EXIT statement 107,456,59 associating data sets with 128
exit-points of subroutine 106 attribute 123
EXP built-in function 310 closing 126
explicit declaration 15 constant 122
scope of 76 data 2~
exponent specifiers 324 expression 123
E picture character 324 in dynamically loaded procedure 10
K picture character 324 opening 126
expression option 156
and data conversion 35 paramefer 119,219
array 35 PRINT 141
as subscript 21 standard 130
common 213 SYSIN 130
element 35 SYSPRINT 130,148
elimination 216,218 variable 123,219
evaluation 335 FILE attribute 423
file 123 FILE option 135,156
general discussion 4

534
FINISH functions (continued)
condition 398 mathematical built-in 353,355
condition codes 384 miscellaneous built-in 354
FIXED attribute 424 multitasking built-in 354
fixed binary data 17 preprocessor built-in 354
FIXED built-in function 370 RETURN statement 109
fixed decimal data 16 storage control built-in 354
fixed-length records 149,164 string built-in 214
FIXEDOVERFLOW string-handling built-in 353,355
condition 398,47
condition code 385
FLOAT attribute 424 general syntax 278
float binary data 18 generiC
FLOAT built-in function 370 entry names 110
float decimal data 18 key 174
FLOOR built-in fUnction 370 references 110
flow of control, modifying statements 54 selection 110
FLOW option 468 GENERIC attribute 425
FLOW statement 230,235,457,61 GENKEYoption 174
format GET statement 459
coding 9 STRING option in 208
list-directed input 139 global optimization 276
list-directed output 139 GO TO statement 109,296,460,54
lists 144 groups 13
format item
alphabetic list of 326
COLUMN 327 halfword 31
control 325 HALT statement 461,59
data 325 handling
edit-directed 325 bit-string 213
LINE 330 error 202
PAGE 330 interrupt 294
remote 326 string 273
SKIP 331 handling options
FORMAT statement 457 magnetic tape 153,171
FORTRAN HBOUND built-in function 370
environment 294 HIGH built-in function 215,370
interface 297
library functions 112
FORTRAN option 291 I picture character 322
FORTRAN routine I/O
passing arguments to 290 general discussion 5
termination of 296 identifiers 10
FREE statement 458,53 definition 10
£o~ based variables 97 format restrictions 10
for controlled variables 89 keywords 10
with IN option 101 IF statement 461
freeing as flow mOdifier 54
implicit 90 comparison operation 40
main storage 69 IGNORE option 151
FROM option 157 IMAG
FS option 162 built-in function 370
function reference operands pseudovariable 370
definition 42 imaginary data 19
functions 108 immediate mode 227
and pseudovariables 285 implicit
and subroutines 105 declaration 77
arithmetic built-in 353,355 freeing 90
array-handling built-in 354,355 opening 121
as expression 42 IN option
as target of assignment 42 ALLOCATE statement with 100
attributes of returned values 109 FREE statement with 101
built-in 111 in-line code optimization (TOTAL) 174
condition-handling built-in 354 in-line operatiOns 271
exit-points of 106 data conversion 271
FORTRAN library 112 string handling 273
GO TO statement 109 inclusion of external text 247
input/output built-in 354 INDEX built-in function 214,246,370

Index 535
INDEXAREA option 174 intermediate result in arithmetic
INDEXED data sets 168 operations 38
INDEXED option 162 intermediate storage of results 43
indexed organization 179 internal
creating data set 183 blocks 64
direct access 183 procedure 64
dummy records 183 INTERNAL attribute 423,78,80
keys 119 internal to, definition 75
sequential access 183 interrupt
infix operators facilities 1
definition 38 handling 294
with arrays 44 multiple 391
with structures 46 interrupt handling 294
information interchange codes 122 by condition prefix 12
INITIAL attribute 32,426 for programs with common expression
initial procedure 67 elimination 274
initialization INTO option 157
assignments and 281 invariant expressions 274
of static variable 87 invocation 291,293
input of preprocessor procedures 243
data-directed 141 of procedure 66
general discussion 5 invoking block 66
list-directed 139 IRREDUCIBLE attribute 428
operation 208 iSOB defining 415
INPUT attribute 124,428 item
input/output 286 A-format 326
based variables and 93 C-format 327
of areas 102 COLUMN format 327
operations 170 data format 325
statement type 50 E-format 328
input/output built-in functions 354 edit-directed format 325
insertion characters 211,318 F-format 329
• insertion character 211 LINE format 330
/ insertion character 211,319 P-format 330
, insertion character 211,318 PAGE format 330
B insertion character 211,319 R-format 331
numeric picture specification 20 remote format 326
insource listing 239 SKIP format 331
integral boundary X-format 331
definition 31 iteration factors
INTER option 291 in initialization 33
interchange (COBOL) iterative do-group 55
data 113
interchange codes 122
interface job control 278
COBOL 297 joining strings(see concatenation)
FORTRAN 297
interlanguage environment 294
establishing FORTRAN environment 294 K picture character 324
establishing PL/I environment 294 key 179,184
GO TO statement 296 classification (GENKEY) 174
interrupt handling 294 condition 398
multitasking 297 condition codes 384
termination of FORTRAN and COBOL embedded 180
routines 296 generic 174
interlanguage facilities 289 length option (KEYLENGTH) 116
COBOL interface 297 location option (KEYLOC) 176
data mapping 290 option 158
data types 290 recorded 179,185
FORTRAN interface 297 source 119,185,188
interlanguage environment 294 key classification 174
invocation 291,293 key classification (GENKEY)
passing arguments to COBOL or FORTRAN generic key 114
routine 290 GENKEY option 114
passing ~rguments to PL/I procedure 292 KEY option 158
problem data 290 KEYED attribute 125,429
program control dat~ 290 KEYFROM option 158
using common storage 293 KEYLENGTH option 162

536
KEYLOC option 162 locator (cont~nued)
KEYTO option 158 parameter 120
keyword qual~fication 91
and keyword abbreviation 309 locator data 24
general definition 10 conversion of 37
statement 12 locator qualif~cation 91
keyword arguments 243 levels of 102
multiple 102
locked record 125
label LOG built-in function 311
data 23 logical operation 282
parameter 119 logical operators 39
prefix 12 LOG10 built-in function 311
LABEL attribute 429 LOG2 built-in function 311
language characteristics long floating-point form 19
general discussion 3 loop, do 55
LBOUND built-in function 311 LOW built-in function 215,312
LEAVE option 153,171
LEAVE statement 462,58
length machine independence of PL/I 3
built-in fUnction 215,311 magnetic tape handling options
of data-directed output fields 143 LEAVE 153,111
parameter bounds, 117 REREAD 153,171
length attribute 410 MAIN option 13
LENGTH built-in function 215,311 main procedure
levels of locator qualification 102 identifying 13
library functions passing argument to 120
FORTRPu~ 112 mapping
LIKE attribute 30,430 data 290,487
LINE rules 488
format item 330 structure 487,96
option 136 mathematical built-in functions 353,355
LINENO built-in function 371 accuracy of 355
LINESIZE option 464 MAX built-in function 372
list function 372
chained 91 maximum size of numeric picture 20
current status 232 member names of external structures
data 136 scope of 80
format 144 merging of attributes 127
of conditions 392 message control program 199
parameter descriptor 114 MIN built-in function 312
processing 96 miscellaneous built-in functions 354
threaded 97 MOD built-in function 312
types of 98 mode 337
LIST option 138 conversion 331
list processing 96 immediate 221
chained list 97 locate 161
threaded list 97 move 159
list-directed 139 of arithmet~c data 16
data in stream 139 processing 93
data specification 138 move mode 159
input format 139 multiple
output format 139 ambiguous references 80
transmission 133 assignment statements 52
listing declarations 80
control statements 249,483 interrupts 391
insource 239 labels 12
source 239 locator qualification 102
listing control statements 249,60 multiple closure of blocks 65
ICONTROL 483 multiple generations
INOPRINT 484 of based variables 91
I PAGE 484 of controlled variables 90
IPRINT 484 MULTIPLY built-in function 372
ISKIP 485 multitasking 291
locate mode 161 built-in functions 354
LOCATE statement 156·,462,94 general discussion 5
locator
conversion 99

Index 531
name on-unit
generic entry 110 dynamically descendant 219
qualified 28 file parameters 219
recognition of 75 file variables 219
symbolic 15 null 219
name (see identifiers) on-conditions 285
NAME condition 384,399 ONCHAR
NAME condition codes 384 built-in function 373
nested blocks pseudovariable 373
definition 64 ONCODE
maxi»um depth 64 (see condition codes)
NOCHECK statement 228,462,61 ONCODE built-in function 373
NOFLOW statement 232,463,61 ONCOONT built-in function 373
NOLOCK option 159 ONFILE built-in function 373
NOMAP option 291 ONKEY built-in function 373
NOMAPIN option 291 ONLOC built-in function 374
NOMAPOOT option 291 ONSOORCE
non-connected storage 117,30 built-in function 374
noniterative DO statement 58 pseudovariable 374
normal termination of program 69 OPEN statement 126,464
notation opening and closing files 126
asterisk 118 associating data sets with files 128
expression 118 CLOSE statement 130
syntax 305 implicit opening 127
NOWRITE option 174 in dynamica1ly-loaded procedure 70
null merging ot attributes 127
ar~Qments 356 OPEN statement 126
built-in function 373,98 standard files 130
character string 21 TITLE option 128
on-unit 219 operand
statement 12,463 definition 35
NULL built-in function 373,98 operating system and job control 278
number of channel programs (NCP) 175 operating system facilities
number sign (#) 9 available to programmer 7
numeric character data 19 operation
picture characters for 316 arithmetic 282,38
numeric character specifications 209 asynchronous 158,251
sign specification in 212 bit-string 38
numeric character to arithmetic combinations of 40
conversion 337 comparison 39
numeric character to bit conversion concatenation 40
numeric character to character expression 37
conversion 346 in-line 271
numeric picture specification infix 36
insertion characters 20 input 208
IIliIxilRWR size 20 logical 282
repetition factors in 19 output 208
prefix 36
synchronous 251
object of REFER option 95 using built-in functions 38
offset operational expressions
expressions 100 definition 35
variables 37,99 operators
OFFSET attribute 431 arithmetic 10
OFFSET built-in function 373 bit-string 10
ON statement 218,463,59 comparison 10
scope of 219 infix 38
with BEGIN block 53 prefix 38
ON-codes priority of 41
(see condition codes) string 10
ON-conditions 383 optimdzation 261
and en-units 285 data management 174
classification of conditions 392 features 278
conditioa codes (ON-codes) 383 in-line code 174
example of use of 223 of input/output operations 170
list of conditions 392 optimizing compiler
multiple interrupts 391 facilities of 6
option 156,95

538
option (continued) option (continued)
ADDBUFF 174 TITLE 128
ALL 62 UNTIL 56
ARGn 291 WHEN 425
ASCII 153,177 WHILE 56
ASSEMBLER 432 OPTIONS attribute 432
BKWD 170 OPTIONS option 466
BLKSIZE 150,166 order
BUFFERS 152,167 of evaluation of expressions 41
BUFND 170 of pairing 481
BUFNI 170 ORDER option 215
BUFSP 170 organization
BY 56 consecutive 118
COBOL 291 data 25
COpy 135 data set 152,168
CTLASA 172 indexed 119
CTL360 172 regional 184
DATA 140 REGIONAL(l) 185
DESCRIPTORS 83 REGIONAL(2) 188
EDIT 143 REGIONAL(3) 190
EVENT 158,253 OTHERWISE clause 414,55
FILE 135,156 output
FLOW 468 data-directed 142
FORTRAN 291 general discussion 5
FROM 157 list-directed format 139
GENKEY 114 operation 208
IGNORE 157 preprocessor 239
INDEXAREA 174 OUTPUT attribute 428
INTER 291 overflow
INTO 157 arithmetic 17
KEY 158 track 11~
KEYFROM 158 OVERFLOW condition 400,41
KEYLENGTH 162,176 OVERFLOW condition code 385
KEYLOC 162,176 overlay defining 416
KEYTO 158 overpunched sign specification
LEAVE 153,171 characters 212
LINE 136
LlNESIZE 464
magnetic tape handling 153,171 P-format item 330
NOLOCK 159 packed decimal form 17
NOMAP 291 PAGE
NOMAPIN 291 format item 330
NOMAPOUT 291 option 135
NOWRITE 174 PAGESIZE option 464
of transmission statements 135,156 pairing 481
OPTIONS 466 parameter
ORDER 215 allocation of 117
PAGE 135 area 120
PAGESIZE 464 array 119
PASSWORD 169 attribute 117
PRIORITY 254 bounds 117
record format 149,162 controlled 111
RECSIZE 150,165 descriptor lists 114,418
RECURSIVE 466 element 119
REENTRANT 466 entry 119
REORDER 275 file 119
REPEAT 56 label 119
REREAD 153,171 . lengths 111
RETURNS 110 locator 120
REUSE 110 preprocessor functions 244
SCALARVARYING 175 relationship with arguments 113
SET 157 simple 117
SIS 169 sizes 117
SKIP 135,169 string 120
STATEMENT 482 structure 119
statements and 203 type 119
STRING 135 parameter attribute 434
TASK 253

Index 539
parameter descriptors POINTER attribute 431
programmer-defined defaults for 85 POINTER built-in function 375
parentheses POLY built-in function 375
PARMSET built-in function 374 POSITION attribute 30,413
passing arguments pOSitional arguments 243
to COBOL routine 290 precision attribute 435
to FORTRAN routine 290 PRECISION built-in function 375
to main procedure 120 precision of arithmetic data 16
to PL/I procedure 292 prefix operation 36
PASSWORD option 169 prefix operators
PENDING definition 38
condition 203,400 with arrays 44
condition code 385 with structures 45
PICTURE attribute 434 prefixes
character strings 22 condition 12,217
numeric character data 19 label 12
picture character 316,322 preprocessed text 239
$ (currency symbol) 211 preprocessor
* (asterisk) 210 do-group 247
'9' in character specification 210 expressions 242
character-string data 315 fUnctions 244
credit 322 input 239
debit 322 output 239
decimal-point specifier 317 procedures 243
digit specifier 317 invocation 243
exponent specifiers 324 keyword arguments 243
factor 324 positional arguments 243
for character-string data 315 STATEMENT option 243
for numeric character data 316 RETURN 483
insertion characters 318 scan 239
overpunched signs 322 stage 239
scaling factor . 324 statements 248,478
signs and currency symbol 319 variables 242
V (decimal point specifier) 211 preprocessor built-in functions 354
Z (zero suppression) 210 preprocessor scan 239
zero replacement 322 character strings and comments 241
zero suppression characters 317 res canning and replacement 240
picture specification 209,22 preprocessor statements 248,60
characters 315 IACTIVATE 418
insertion character. 211 lassignment 419
insertion character / 211 IDEACTIVATE 419
insertion character, 211 IDECLARE 479
insertion character B 211 IDO 480
numeric character 209 lEND 480
overpunched characters 212 IGO TO 480
picture character $ 211 "IF 481
picture character * 210 I INCLUDE 481
picture character '9' 210 I NOTE 482
picture character V 211 Inull 482
picture characters 210 IPROCEDURE 482
repetition factors 22 RETURN 483
sign specification 212 primary entry point 66
picture.specification characters 315 PRINT attribute 125,436
picture specifications PRINT files 141
character-string 212 standard file SYSPRINT 148
pitfalls and common errors 278 printer/punch control (CTL360/CTLASA) 112
PL/I priority
concepts of 1 of operands 41
environment 294 of operators 41
procedure 292 of tasks 254
PLIRETV built-in function 375 PRIORITY built-in function 375
point of invocation of procedure 66 PRIORITY option 254
point specifier PRIORITY pseudovariable 316
V decimal 317 prOblem data 290,82
pointer definition 15
built-in function 375 procedure
expression 92 blocks 63
variables 37,92 labels On 63

540
procedure (continued) PUT statement 468
main 13 PUT variables 232
preprocessor 243
recursive 71
reference 65 qualification
termination of 68 locator 91
procedure block multiple locator 102
definition 13 qualified names 28
invoking 13 of structure elements 28
PROCEDURE statement 466,52 quotation marks 21
processes in application of attributes 81
processing
batch 227 R picture character 322
conversational 227 R-format item 331
list 96 RANGE option 448
mode 159,93 reactivation of active procedure 71
processing modes 159 READ statement 156,470,94
locate mode 161 real arithmetic data 16
move mode 159 REAL attribute 412
processor stage 239 REAL built-in function 376
PROD built-in function 376 REAL pseudovariable 376
program recognition of names 75
amending 237 record
control 279 alignment 502
control data 290,82 condition codes 384
elements 9 D-format 154,178
interrupt handling for 274 DB-format 154,178
message control 199 dummy 183,185,189,190
organization 63 files 205
structure 3,12 fixed-length 149,164
termination 69 locked 125
program control data 290,82 transmission 50
area 25 undefined-length 150,165
comparisons 39 variable-length 149,164
definition 15 RECORD attribute 124,436
entry 24 RECORD condition 202,400
event 24 record format defaults 151,167
file 23 record format options 149,162
label 23 BLKSIZE option 150,166
locator 24 fixed-length records 149,164
restriction on conversion of 37 RECSIZE option 150,165
task 24 undefined-length records 150,165
program organization statement type 52 variable-length records 149,164
programmer-defined default 85 recorded key 179,185
programming example 258 RECSIZE option 150,165
programming techniques for optimizing recursion 71,88
compiler RECURSXVE option 466
in-line operations 271 REDUCIBLE attribute 428
prologues 72 redundant expression elimination 278
pseudovariable reentrability 252
COMPLETION 367 REENTRANT option 466
COMPLEX 367 REFER option 95
definiton 42 reference
general description 356 generic entry names 110
IMAG 370 subroutine 107
nesting restriction 356 REGIONAL data sets 168
ONCBAR 373 regional organization 184
ONSOURCE 374 keys 184
PRIORITY 376 types of 185
REAL 376 REGIONAL(l) organization 185
STRING 378 creating data set 185
SUBSTR 379 direct access 187
ONSPEC 3-80 dummy records 185
punch, card sequential access 187
POT ALL statement 236 REGIONAL(2) organization 188
PUT diagnostic statements 61 creating data set 189
PUT FLOW statement 235 direct access 190
PUT SNAP statement 235 dummy records 189

Index 541
REGIONAL(2) organization (continued) self-defining data (REFER option) 95
sequential access 189 object of REFER option 95
source keys 188 structure mapping 96
REGIONAL (3) organization 190 sequential 124
cre~ting data set 190 access 183,189,187,191
direct access 191 update 179
dummy records 190 SEQUENTIAL attribute 417
sequential access 191 SET option 157
relationship of arguments and setting
parameters 113 event variables 256
allocation of parameters 117 pOinter variables 92
argument and parameter types 119 sharing data between tasks 255
dummy arguments 113 sharing files between tasks 256
entry attribute 114 short floating-point form 19
RELEASE statement 472,53,69 SIGN built-in function 377
remote format item 326 sign specification in numeric character
REORDER option 275 specifications 212
REPEAT built-in function 215,376 SIGNAL statement 221,475,60
REPEAT option 56 signs and currency symbol 319
repetition factors + picture character 322
in character string data 21 $ currency symbol 322
in numeric picture specifications 19 picture character 322
repetitive specification 137 S picture character 322
replacement 240 simple defining 414
REREAD option 153,171 simple parameter 111
rescanning 240 simple statement 12
reserved words 75 simplification, expression 216
restoring standard defaults 84 SIN built-in function 317
results of arithmetic operations 38 SIND built-in function 371
results of assignments 43 SINH built-in function 371
RETURN SIS option 162,169
preprocessor statement 483 SIZE
return codes 299 condition 11,222,401
RETURN statement 107,109,472,59,68 condition code 385
returned value 244 raised in data conversion 47
attributes of 109 size attribute 408
RETURNS attribute 110,437 SIZE condition 11
RETURNS option 110 SKIP
programmer-defined default for 85 format item 331
RETURNS attribute and 106 option 135
REUSE option 162,170 SKIP option 162,169
REVERT statement 221,473,60 SNAP option 235
REWRITE statement 156,473 source 335
ROUND built-in function 376 key 119,185
keys 188
listing 239
S picture character 322 program 218
SAMEREY built-in function 376 to target rules 335
SCALARVARYING option special characters 9
varying-length string option specification
(SCALARVARYING) 175 attribute 83
scale of arithmetic data 16 character 212
scaling factor 324 character-string picture 212
scan, preprocessor 239 characters 315
scope data 136
of condition prefix 218 data-directed data 140
of contextual declaration 76 edit-directed data 143
of declaration of name 75 factored default 85
of DEFAULT statement 84 list-directed data 138
of explicit declaration 76 numeric cha~acter 209
of member names of external picture 209
structures 80 picture character '9' 210
of ON statement 219 repetitive 131
secondary entry point 66 specification for input
SELECT statement 474,55 data-directed data 141
select-group 55 specification for output
definition 13 data-directed data 142
selection, generic 110

542
specifier statement (continued)
decimal digit 317 null 463
decimal-point 317 ON 218,463
digit 317 OPEN 126,464
exponent 324 preprocessor 248,418
V decimal point 317 PROCEDURE 466
SQRT built-in function 377 PUT 468
stage PUT ALL 236
preprocessor 239 PUT FLOW 235
processor 239 PUT SNAP 235
standard defaults READ 156,410
application of 81 RELEASE 412
restoring 84 RETURN 101,109,472
standard file 130 (preprocessor) 483
input file SYSIN 130 REVERT 221,413
output file SYSPRINT 130,148 REWRITE 156,413
statement SELECT 414
IACTIVATE 418 SIGNAL 221,415
lassignment 419 STOP 101,415
"CONTROL 483 UNLOCK 156,475
IDEACTlVATE 419 WAIT 256,416
IDECLARE 479 WRITE 156,417
100 480 STATEMENT option 482
lEND 480 statement prefixes
"GO TO 480 condition 12
"IF 481 label 12
"INCLUDE 481 STATIC attribute 408
INOPRINT 484 static storage 81
"NOTE 482 allocation of 70
Inull 482 initialization of 87
"PAGE 484 static variables 70
"PRINT 484 STATUS built-in function 251,311
"PROCEDURE 482 status list, current 232
"SKIP 485 STOP statement 107,475,59
ALLOCATE 439 storage
and options 203 automatic 87
assignment 441 based 91
BEGIN 443 connected
CALL 253,444 general discussion 111
CHECK 228,445 controlled 88
classes of 49 non-connected
CLOSE 130,446 and DEFINED attribute 30
data transmission 134,155 general discussion 117
DECLARE 446 static 87
DEFAULT.447,83 using common 293
DELAY 257,450 storage allocation 70
DELETE 156,450 types of 4
descriptive 49 STORAGE built-in function 377
DISPLAY 451,51 storage control
DO 451 automatic storage 87
END 101,454 based storage 91
ENTRY 455 built-in functions 354
EXIT 101,456 controlled storage 88
FETCH 456 statement type 53
FLOW 230,451 static storage 87
FORMAT 457 STREAM attribute 124,436
FREE 458 stream transmission
general discussion 12 data-directed data 140
GET 459 list-directed data 139
GO TO 109,296,460 statement type 50
GOTO 101 string 285
HALT 461 built-in function 215,378
IF 461 data 21
LEAVE 462 handling 213
listing control 249,483 operator 10
LOCATE 156,462,94 overlay defining 416
NOCHECK 228,462 parameter 120
NOFLOW 232,463 pseudovariable 318

Index 543
string (continued) subroutine and functions (continued)
unaligned bit 155 entry pOints of 106
STRING built-in function exit-points of 106
in array expressions 44 FORTRAN library functions 112
string built-in functions 214 functions 108
BIT 214 generic entry names and references 110
BOOL 215 paSSing argument to main procedure 120
CHAR 214 relationship of arguments and
HIGH 215 parameters 113
INDEX 214 RETURNS attribute and RETURNS
LENGTH 215 option 106
LOW 215 subroutines and functions 105
REPEAT 215 subscripted qualified names
STRING 215 definition 29
SUBSTR 214 SUBSCRIPTRANGE
TRANSLATE 215 condition 222,402
UNSPEC 215 condition code 386
VERIFY 215 subscripts
string data expressions used as 21
altering length of 207 of arrays 26
bit 22 SUBSTR built-in function 214,246,318
character 21 SUBSTR pseudovariable 319
qualified names 28 SUM built-in function 379
STRING option 135 suppression character
in GET statement 208 * 318
in PUT statement 208 Z 318
STRING pseudovariable 378 zero 311
string-handling built-in functions 353,355 symbol
STRINGRANGE $ currency 322
condition 222,401 symbolic name 15
condition code 386 synchronization of tasks 255
STRINGSIZE 402 synchronous operation 251
condition 402 syntax notation 305
condition code 385 SYSIN standard input file 130
raised in data conversion 47 SYSPRINT
structure 27 standard file 148
arrays of 29 standard output file 130
BYNAME assignm~nts 46
controlled 91
expression 35,45 T picture character 322
infix operators with 46 TAN Quilt-in function 319
mapping 487,96 TAND built-in function 319
operations involving arrays 45 TANH built-in function 319
parameter 119 target variable
prefix operators with 45 attributes of 43
qualified names 28 task
structure mapping 96 coordination 255
example of 489 creation of 253
rules 487 data 24
structure-and-e1ement operations 46 priority of 25lJ
structure-and-structure operations 46 sharing data between 255
structure, program Sharing files between 256
general discussion 3,12 synchronization 255
subparameter, DCB 152,176 termination of 251
subroutine 107 TASK attribute 431
and functions 105 TASK option 253
built-in 112 tasking and reentrability 252
END statement 107 teleprocessing
EXIT statement 107 data sets 171
GOTO statement 107 ENVIRONMENT attribute 199
reference 107 ERROR condition 202
RETURN statement 107 error handling 202-
STOP statement 101 message control program 199
subroutine reference 101 PENDING condition 203
subroutine and functions RECORD condition 202
built-in functions 111 statements and options 203
built-in subroutines 112 TRANSIENT attribute 202
ENTRY attribute 106 TRANSMIT condition 202

544
termination UPDATE attribute 124,428
of blocks 67 update, sequential
of FORTRAN and COBOL routines 296
of program 69
of tasks 257 V decimal point specifier 317
testing event variables 2S6 V option 162
COMPLETION built-in function 257 V picture character 211
STATUS built-in function 2~7 value returned 244
text, preprocessed 239 variable
THEN clause 461 aliased 276
threaded list 97 area 99
TIME built-in function 379 based 91
TITLE option 128 definition 15
TO option 55 file 123
TOTAL option 170 offset 99
tracing facilities painter 92
CHECK statement 228 preprocessor 242
FLOW statement 230 PUT 232
NOCHECK statement 228 setting painter 92
NOFLOW statement 232 static 87
track overflow (TRKOFL) 175 uninitialized 23
transfer VARIABLE attribute 438
of invariant expressions 277 variable-length records 149,164
of invariant expressions or VARYING attribute 21,410
statements 274 varying-length string
TRANSIENT attribute 124,202,417 and area variables 155
TRANSLATE built-in function 215,379 option (SCALARVARYING) 175
transmission VB option 162
data-directed 133 VBS option 162
edit-directed 134 VERIFY built-in function 215,381
list-directed 133 virtual storage tuning 268
of data-list elements 138 VS option 162
transmission statements VSAM data sets 168
data 134,155 VSAM organization 192
options of 135,156
TRANSMIT
condition 202,402 WAIT statement 256,476
condition codes 384 WHEN clause 474,55
transmitted data 155 WHEN option 425
TRUNC built-in function 380 WHILE option 56
tuning a program for virtual storage 268 word 31
type conversion 36 WRITE statement 156,477
types
argument 119
data 290 x picture speCification character 22
of list 98 X-format item 331
of regional organization 185
of statements 49
parameter 119 Y picture character 322

U option 162 Z picture character 210

UNALIGNED attribute 31,405 Z zero suppression character 318
effect of 488 zero replacement picture character 322
unaligned bit strings 155 zero suppression character 311
UNBUFFERED attribute 124,411 ZERODIVIDE
undefined-length records 150,165 condition 385,404,47
UNDEFINEDFILE condition code 385
condition 403
condition codes 384
UNDERFLOW 48-character set 9,308
condition 404,47
condition code 385
uninitialized variables 23 60-character set 9,307
UNLOCK statement 156,475
UNSPEC built-in function 215,380
UNSPEC pseudovariable 380 9 in numeric character specifications 210
UNTIL option 56

Index 545
OS PLjI Checkout and Optimizing Compilers: Reader's
Language Reference Manual Comment
Order Number GC33-0009-4 Form

Your comments about this publication will help us to improve it for you.
Comment in the space below, giving specific page and paragraph references
whenever possible. All comments become the property of IBM.
Please do not use this form to ask technical questions about IBM systems and
programs or to request copies of publications. Rather, direct such questions or
requests to your local IBM representative.
If you would like a reply, please provide your name and address
(including ZIP code).

Fold on two lines, staple, and mail. No postage necessary if mailed in the U.S.A. (Elsewhere,
any IBM representative will be happy to forward your comments.) Thank you for your
cooperation.
 GC33-0009-4

oen
-0
r
::::-

Fold and Staple

First Class Permit

Number 6090
San Jose, California

Business Reply Mail

No postage necessary if mailed in the U.S.A.

Postage will be paid by:

I BM Corporation
P.O. Box 50020
Programming Publishing
San Jose, California 95150

..........................................................................................................................................
Fold and Staple

International Busin. . Machines Corporation

Data Processing Division
1133 Westchester Avenue, White Plains, New York 10604
(U.s.A. only)

IBM World Trade Corporation

832 United Nations Plaza, New York, New York 10017
Unternational)
 u~33-0009-4

o
en
."
r-
:::::

r-
Q)
:l
(Q
c:
Q)
(Q
CD

-
::xJ
CD
CD
~
CD
:l
~
~
Q)
:l
c:
~
."
CD
Z
~
(I)
eN

-
c:»
o
en
....,
eN
o
~
<0
.,."
...
:r
a

Intwnaflonal .............chl.... Corporation

DR Procesalng Dlvlalon
1133 WMlch....r Av_ _, White Plain., New York 10104
(U.s.A. only)

1811 World Trade Corporation

121 United NatIons Plaza, New York, New York 10017
(l1IIerutIonaI)