GC28 6594 7_PLIf_pg Gd_Jan71 7 PLIf Pg Gd Jan71

GC28-6594-7_PLIf_pgGd_Jan71 GC28-6594-7_PLIf_pgGd_Jan71

User Manual: GC28-6594-7_PLIf_pgGd_Jan71

Open the PDF directly: View PDF PDF.
Page Count: 519

DownloadGC28-6594-7_PLIf_pg Gd_Jan71 GC28-6594-7 PLIf Pg Gd Jan71
Open PDF In BrowserView PDF
File No. 5360-29
Order No. GC28-6594-7

Systems Reference Library

IBM System/360 Operating System
PLII (F)
Programmer's Guide
Program Number 360S-NL-Sll

This publication is a companion volume to IBM System/360
Operating System: PL/I (F) Language Reference Manual, Form
C28-8201. Together, the two books form a guide to the
writing and execution of PL/I programs under the control of
an IBM System/360 Operating System that includes the PL/I
(F) Compiler. The Programmer's Guide is concerned with the
relationship between a PL/I program and the operating
system. It explains how to compile, link edit, and execute
a PL/I program, and introduces job control language, the
linkage e¢itor, and other essential features of the operating
system.

OS

Eighth Edition (January, 1971)
This is a major revision of, and obsoletes, C28-6594-6 and
Technical Newsletter GN33-6016. In addition to incorporating
information from the Technical Newsletter this new edition
contains changes to the description of the PL/I sorting
facilities and a number of minor changes throughout. Changes
to the text, and small changes to illustrations, are
indicated by a vertical line to the left of the change;
changed or added illustrations are denoted by the symbol •
to the left of the caption.
This edition applies to Release 20 of the IBM System/360
Operating System, and to all subsequent releases until otherwise indicated in new editions or Technical Newsletters.
Changes are continually made to the specifications herein;
before using this publication in connection with the
operation of IBM systems, consult the latest IBM System/360
Bibliography SRL Newsletter, Form N20-0360, for the editions
that are applicable and current.
The information contained in this publication concerning
Model 195 support is for planning purposes only.
Requests for copies of IBM publications should be made to
your IBM representative or the IBM branch office serving
your locality.
A form for reader's comments is provided at the back of
this publication. If the form has been removed, comments may
be addressed to IBM United Kingdom Laboratories Ltd.,
Programming Publications, Hursley Park, Winchester,
Hampshire, England.
©

Copyright International Business Machines Corporation
1966,1967,1968,1969,1970,1971

Preface

This publication and IBM Systeml360
Operating system: PL/I. (F) Language
Reference.Manual form a complementary pair
Prograuuner's Guide is concerned with the
relati<:>nship between a PL/I program and IBM
Syste~'360 Operating System; it explains
how to compile, link edit, and execute a
PL/I pJrogram. rhe Programmer' s Guide is
concerned with the relationship between a
PL/I pJrogram and IBM System/360 Operating
System;~ it explains how to compile, link
edit, and execute a PL/I program.

Concepts and Facilities, Order No.
GC28-6535
Linkage Editor and.Loader, Order No.
GC28-6538
Job. Control Language . User' s Guide, Order
No. GC28-6703
Job.Control Language Reference, Order No.
GC28-6704
System.Generation, Order No.

Pari: 1 is intended primarily for the
casual (non-specialist) programmer or for
the ne'lI1comer to IBM System/360; the reader
is assumed to have only an elementary grasp
of PL/I and an awareness of the basic
concepts of electronic data processing~. 2
and 3 are designed for use either as
reference material or for reading as an
introduction to the features they describe.

Utilities, Order No.
system :Control Blocks"
GC28-6628

GC28-6554

GC28-6586
Order No.

Messages and Codes, Order No.

GC28-6631

Job.Control Language Charts, Order No.
GC28-6632
supervisor and Data Manaqement services,
Order No. GC28-6646

PREREQUISITE PUBLICATION
Supervisor.and Data Management Macro
Instructions, Order No. GC28-6547
The reader is assumed to have a working
knowled.ge of PL/I; he should therefore be
familiar with the material contained in the
following publication:
IBM SvstenV360 Operating system: PL/I·· (F)
Language Reference Manual, Order No.
GC28-8201

Programmer's Guide.to Debugging, Order
No. GC28-6670
Queued Telecommunications Access Method
Message Processing ',Program Services,
Order No. GC30-2003
Queued Telecommunications Access Method
Message Control Program, Order No.
GC30-2005

RECOMM:I!:NDEDPUBLICATIONS
Sort/Merge, Order No.

GC28-6543

The text of the Programmer's Guide refers
to the following publications for
information outside its scope:

In addition to the publications listed
above, the following contain information
that may be helpful to the user:

IBM Sy:stem/360 Operating system:

IBM System/360 Operating System:

PL/I (F) Compiler, Program Logic Manual,
Order No. GY28-6800

Operator's Reference, Order No.
GC28-6691

PL/I Subroutine Library Program Logic
Manual, Order No. GY28-6801

Operator '. s Procedures, Order No.
GC28-6692

Advalllced Checkpoint/Restart Planning
Guiae, Order No. GC28-6708

system Programmer's Guide, Order No.
GC28-6550
Storage Estimates, Order No.

1For example, as described in Introduction
to IBM Data processing Systems, Order No.
GC20-1684.

GC28-6551

PL/I Subroutine Library, Computational
Subroutines, Order No. GC28-6590
3

IBM System/360:
Principles of ,Operation, order No.
A22='682I

4

Contents

PART 1:: BASIC ·PROGRAMMING
THE PL/I (F) COMPILER

WITH

CHAPTER 1: INTRODUCTION TO THE
OPERATING SYSTEM. • • •

• 13

IBM Sys·tem/360 Operating System. •
Job Scheduler • • •
PL/I (F) Compiler •
Linkage Editor. • • • • • •
Linkage Loader. •

•
•
•
•
•

13
13
14
14
14

Job Control Language •
• 14
Format of Job Control Statements. • • 14
JOB statement • •
• 16
EXEC Statement. • • • • • .•
• 16
DO Statement. • • • •
• 16
Delimiter statement •
• 17
Executing a PL/I Program •

• 17

CHAPTER 2: HOW TO RUN A SIMPLE PL/I
PROGRAlM • • • • • •.•

• 20

Job Control statements
Further Information •

• 20
• 21

CHAPTER 3: HOW TO CREATE AND ACCESS A
SIMPLE DATA SET

• 22

Using a Data Set • •

• 22

How to Create a Simple Data Set. •
Type of output Device (UNIT=) •
Volume Serial Number (VOLUME=SER=).
Name of Data set (DSNAME=) • • • • •
Format of the Records (DCB=) • • • •
Auxiliary'Storage Required (SPACE=)
Disposition of Data Set (DISP=)

•
•
•
•
•
•
•

22
23
23
24
24
24
24

How to ,~ccess an Existing Data Set
Type of Input Device. •
Volume Serial Number.
Name of Data Set. • • •
Format of the Records •
Auxiliary Storage Required.
Disposition of Data Set • .•
special-PUrpose Parameters.
syst,em Output (SYSOUT=) •.•
Data in the Input Stream •.•

•
•
•
•
•
•
•
•
•
•

25
25
25
25
25
25
26
26
26
26

Standard Files •

• 26

Examples

• 26

PART
OF

2:
USING
THE PL/I

ALL
(F)

JOB Statement. • • ,.

• • 31

Job Scheduling ,..
••••
Job scheduling and the Control
Program. • • • • • • •
Primary Control Program (PCP)
MFT Control Program •
MVT Control Program

• • 32

CHAPTER 5: COMPILATION •

• • 37

Introduction •
Compilation

• • 37
• • 37

• • • 11

THE FACILITIES
COMPILER

• 29

CHAPTER 4: JOB INITIALIZATION.

• 31

Introduction •

• 31

• • 32
• • 33
33
35

Job Control Language for Compilation • • 39
EXEC Statement. • • • •
39
DD Statements • • •
• • 40
Example • • • • •
• • • •
43
Optional Facilities • •
Control Options • • •
Preprocessor Options. •
Input Options. ,.
Output Options .•
Listing Options

• • 43
• • 44
46
47
•

Listing,. • • • • •
Options used for the Compilation. •
Preprocessor Input. .• • • • •
•
Source Program. • • • • • • •
•
Attribute and Cross-Reference Table
storage Requirements. • • •
Table of Offsets. • • • • •
•
External Symbol Dictionary. •
•
statistics. • • •• '.
Object Module • • •
•
Diagnostic Messages •
•
Return Code • • • • • • • •
•

•
•
•
•
•
•
•
•
•

49
49
50
50
50
51
52
52
54
54
56
56

57
• • 57

Batched Compilation.
The PROCESS Statement •
Job Control Language for Batched
processing • • • • • • • •
Compile-Time Processing.. • • •
Invoking the Preprocessor •
The %INCLUDE Statement. •

• 48
48

• • 58
• • 58

• • 59
• • • 60

Dynamic Invocation of the Compiler •

61

CHAPTER 6: LINKAGE EDITOR AND LOADER • • 63
Introduction • • • • • • • • •
Choice of Linkage Program •

• • 63
• • 63

Linkage Editor • • • • • • • •
Module Structure. • • • • • •
Linkage Editor Processing •

• • 64
• • 64
65

Job Control Language for Link-Editing • • 66
EXEC Statement. • • • •
• • 66
DD Statements • •
• • • • • .• • • 67
5

• 68

CHAPTER 8: CATALOGED PROCEDURES. • •

Optional Facilities.
LIST.
MAP.
XREF.
LET •
XCAL.
NCAL.
SIZE.

•
•
•
•
•
•
•

Introduction ..

Listing. • • • • • • • • •
Control Statements and Errors •
Diagnostic Message Directory. •
Module Map. • • • • • • • • • •
Cross-Reference Table
Return Code • • • •

•
•
•
•
•
•

70
70
71
71
72
72

Additional Processing.
Format of Control statements. •
Module Name • • • • • • • •
Additional Input Sources.
Overlay Programs. • •

•
•
•
•

72
72
73
73

• 74

Linkage Loader • • • •
Module structure. • • • • •
Linkage Loader Processing •

• 77
• 77
• 78

Example • • • • • •

69
69
69
69
69
69
69

• 70

Job Control Language for Link-Loading. • 80
EXEC Statement. • • • • • •
• 80
DD Statements • • •
• 80
Optional Facilities. •
Control Statements.
Options in the PARM Parameter.
CALL I NOCALL I NCAL • •
EP. • • •
LETINOLET • •
MAPINOMAP • •
PRINTINOPRINT •
SIZE. • • • •
RESINORES • •
Default options
Listing. • • •
Module Map.
• • • •
Explanatory Error or Warning
Messsages. • • • • • • • •
Diagnostic Messages • • • • • •

•
•
•
•
•
•
•
..
•

83
83
83
84
84
84
84
84
84

• 85
• 85
• 85
• 85
• 85
.. 86

CHAPTER 7: EXECUTING THE LOAD MODUL:E • • 87
Introduction • • • •

• 87

Load Module processing • •
Identifying the Module.

• 87
• 87

Job Control Language for Execution
EXEC statement. • • • •
standard DD Statements.
User DD Statements. • •

• 89
.. 90
• 91

Listing. • • • • • • • •
contents of SYSPRINT Listing • •
Return Codes. .• .. • • • • • • •

• 91
• 91
• 92

• 88

communication with Program during
Execution • • • • • • • • • • .. • • • • 92
6

9:3

• .. 93

PL/I Cataloged Procedures Supplied by
IBM • • • .• •
• • • • .. • • • •
Compile and Punch Object Deck
(PLIDFC) •
• • • • .. • • .• •
Compile and Write Object Module
(PLILFC) . •
• • • • • .• • • •
Compile and Link-Edit (PLILFCL) • •
Compile, Link-Edit, and Execute
(PLILFCLG) • .. • • • .. • • • • •
Link-Edit and Execute (PLILFLG) .. •
Compile, Load and Execute (PLILFCG)
Load and Execute (PLILFG) •
..
Dedicated Workfiles • •

.. 93
• 93
• 93
• 94
95
• 95
• 9'5
• 96
96

Using Cataloged Procedures

• • 97

Altering Cataloged Procedures.
Temporary Modi:fication. • •
Permanent Modification. • •

97
97
• .1010

CHAPTER 9: DATA SETS AND PL/I FILES. • .101
Introduction •

.101

Data Sets. • •
• • lOt
Data Set Names.
• .101
Record Formats.
• .10:2
Data Set Organization •
• .104
Labels. • • • • • ~ ..
• • .105
Data Definition (DO) Statement. • • • 105
Files and Data sets • • .. • ..
• .107
Operating system Data Management .. • • .107
Buffers • • • • .• • . '
• .10;~
Access Methods. • • ..
• .109
Data Control Block. •
• .1110
Opening a File. .. • .. .. • • •
• .111
Closing a File. • .. ..
• .11:2
Auxiliary storage Devices.
Card Reader and Punch •
Paper Tape Reader • •
Printer • • • • • • • •
Magnetic Tape • • • • •
Direct-Access Devices •

•
•
•
•
•
•

CHAPTER 10: STREAM-ORIENTED
TRANSMISSION. • .. .. • ..
Record Format. .. • .. .. . ' . •
Fixed-Length Records. • •
Variable-Length Records ..
Undefined-Length Records.
Choice of Record Format •

.11:2
.11:2
.. 11:2
.11:2
.113
.113

.. • .111[J

..
•
..
•

Buffers • • •
DCB Subparameters.

• .ll/[J

• .lll[J
• .11/~
• .111[J
.. .ll'tJ

• .115
• • • 115

Creating a Data Set. • • • • ..
Essential Information •
Example .. • • • • • •

• .11'5
• .1115
.117

Accessing a Data Set

• .117

Essen.tial Information • • • • •
Magnetic Tape Without Standard
Labels • • •
• • • •
Record Format •
Example • • •

.117
.118
.118
.119

PRINT Fil es • • •
Record Format •
Example • • •
Tab Control Table

.119
.120
.120
.120

Standard Files

.122

CHAPTER 11: RECORD-ORIENTED
TRANSMI SSION • • • • ,e •

• 124

Record Format. •
Choice of Record Format

.124
• 124

Buffers. • • • • • • • • •
.125
creating and Accessing Data Sets. • .125
CONSECUTIVE Data Sets. • • • • • • •
creating a CONSECUTIVE Data Set •
Accessing a CONSECUTIVE Data Set.
Example of CONSECUTIVE Data sets.
printing and punching Cards

•
•
•
•

.125
.125
.126
• 128
.129

.130
INDEXED Data sets • • •
Indexes • • • • • • •
• •
.130
• 131
Creating an INDEXED Data Set • •
Accessing an I~DEXED Data Set • • • • 137
Reorganizing an INDEXED Data Set. • .138
Examples of INDEXED Data sets •
.138
REGIONAL Data Sets • .• • • • .• • •
creating a REGIONAL Data Set. •
Accessing a REGIONAL Data Set •
Examples of REGIONAL Data Sets.

.139
.141
.143
.144

Teleproc.essing • • • • • • •
.152
Introduction. .. • • • • •
.152
Messa.ge Processing Program (MPP) • • • 153
How to Run an MPP • • • • • • •
.153
CHAPTER 12: LIBRARIES OF DATA SETS

.155

Introduc·tion •

.155

Structurle of a Partitioned Data set. • .155
Direct.ory • • • • •
••• •
.155
Creating a Partitioned DaLa Set. •
Space Parameter • • • • • •

.156
.157

processing a Member. • • • • •
Processing with PL/I. •

.15t
.159

Operatin9 System Utility Programs.

.160

System Libraries • • • • •
Link JLibrary. • • • • •
Procedure Library • •
PL/I Subroutine Library

.161
.161
.161
.161

Private Libraries.
Job Library • •
step Library. •

• .161
• .161
• .162

CHAPTER 13: MULTITASKING.

• .163

Introduction • • • • • • •

• .163

Multitasking Requirements. • •
• .163
systenV360'Requi;rements
• • 163
Operating system Requirements • • • • 163
Programming Requirements. •
• .163
Multitasking Management. ~ • •
• .164
Trans fer of Control,. • • • • • • • .164
Use of Priorities in PL/I •
• .166
programming considerations.
• .167
Input/Output Handling •
• .1'69
Task Termination.
• .172
Multiprocessing. • . •
Synchronization •

• .173
•
e 174

CHAPTER 14: OTHER FACILITIES OF THE
OPERATING SYSTEM •

• .175

Introduction

• .175

Dump of Main storage

• .175

Checkpoint/Restart Interface •
• .176
Types of Restart • • • • • • •
• .177
Checkpoint/Restart Requirements and
.178
Diagnostic Aids. • • • • • •
Job Control Language Details.
• .178
PL/I CALL Statement Details •
• .180
Restriction on Use of
Checkpoint/Restart • • • • •
• .183
Effect of Checkpoint/Restart on
Data Sets. • • • • •
• .183
Sort Interface • • • • • • • • • • • • • 184
PL/I Sort Environment • • • • • • • • 184
User' Control of SORT ddnames • • • • • 186
Defining the Sorting Application. • .187
Entry Point lHESRTA •
.189
Entry Point lHESRTB .• •
• .191
Entry Point IHESRTC • •
• .193
Entry Point IHESRTD • •
• .195
Sorting Variable-Length Records • • .191
Use of PL/I Sort in a Multitasking
Environment.
• • • • • • • 198
CHAPTER 15: PL/I AND OTHER LANGUAGES • .201
Introduction • •

• .201

Data set Interchange
• • 201
PL/I-FORTRAN Data set Interchange • • 201
PL/I-COBOL Data Set Interchange • • • 203
Linkage with Other Languages • • • • • • 204
PL/I (F) Environment and
Communications • • • • • • • • • • • 204
Communication with Other Languages • • 212

7

PART 3: APPENDIXES. • • • • • • •

.217

APPENDIX A: PROGRAMMING EXAMPLES.

.219

Example 1: Simple PL/I Program • •
Listing • • • • • • • • • • • •

.219
.219

Using standard IBM Cataloged
Procedures .. • • .. • • • .. •
providing Your Own cataloged
Procedures. • • • • •

.. .. 282
• .283

APPENDIX G: IBM SYSTEM/360 MODEL 91
AND MODEL 195 • • • • .. • • •
• ... 287

Example 2: Compiler and Linkage-Editor
Listings. • • • • • •
• • • • • .226
Listing. • • • • •
• • • • • • 227

APPENDIX H: COMPILER DATA SETS •

• .289

APPENDIX B: PARAMETERS OF DD STATEMENT .249

APPENDIX I: ON, RETURN, AND USER
COMPLETION CODES.

• .291

APPENDIX C: VERSIONS OF THE PL/I (F)
COMPILER. • • • • • • • • • • • •

.261

APPENDIX D: SYSTEM REQUIREMENTS. •

.267

Control Program Options.

.267

Machine Requirements • • • •

.267

APPENDIX J: IMPLEMENTATION CONVENTIONS
AND RESTRICTIONS. • •
• .297

APPENDIX E: PL/I LIBRARY SUBROUTINES • .270

APPENDIX K: DIAGNOSTIC MESSAGES . . . . . . 313

APPENDIX F:

.279

Source Program Diagnostic Messages • • .313

Introduction

.279

How to Create a Shared Library. ..

.279

Compile-Time Processing Diagnostic
Messages. • • • • • • • • • • • .. • • .. 445

How to Use a Shared Library. •

.281

8

SHARED LIBRARY. •

ON-Codes . . . . . . . . . . . . . . . . . 291
Return Codes and User Completion codes .294
step Abend Facility • •
.295
Return Codes. • • • • •
.295

Object-Time Diagnostic Messages.

• .467

INDEX.

• .506

.oo

•

•

•

•

•

•

•

Figures

Figure 1-·1. A JOB statement • • •
•
Figure 1-·2. An EXEC statement • ..
•
Figure 1-3. A DD Statement (Using a
Continuation Card). • • .. _. • • •
•
Figure 1-·4. Typical Sequence of Job
Control ,statements for Compile,
Link-Edi.t, and Execute steps..
••
Figure 1--5. Typical Sequence of Job
Control statements for Compile and
Load-and-Execute steps. • -.. .. • • .. • •
Figure 2-·1. Job Control Cards for the
Execution of.a simple PL/I Program • • •
Figure 3-·1. Creating a CONSECUTIVE
Data Set.: Essential Parameters of DD
Statement .. • • • • • • • • • • • • • ..
Figure 3-· 2. Accessing a CONSECUTIVE
Data Set.: Essential Parameters of DD
statement • • • • • • • • • • • •
•
Figure 3-·3. creating a simple
CONSECU'l~IVE Data Set. • .. • • • • • • •
Figure 3-·4. Accessing a Simple
CONSECU'l'IVE Data Set. • • • • • •
•
Figure 5-'1. PLII (F) Compiler:
Simplifi.ed Flow Diagram • • • • •
•
Figure 5-· 2. standard Data sets for
Compilat,ion • • • • • • • • • • •
•
Figure 5-·3. Characteristics of
CompileI: Data Sets. • • • • • • • • • •
Figure 5-·4. Compiler Options,
Abbreviations, and standard Defaults. •
Figure 5-· 5.. Optional Components of
Compiler Listing. • .. • • .. .. • •
..
Figure 5-·6. Typical Standard ESD
Entries • .. • • • • • • • • • • •
..
Figure 5-·7 .. An Example of Batched
Processing_ • • • .. • • • • .. • •
•
Figure 5-· 8. Execution of the Programs
Compiled in Figure 5-7 . . . . . . . . . . . . . .
Figure 5-· 9. Using the Preprocessor to
Create a Source Deck. • • • • • • • .. •
Figure 5-·10. Placing Source
Statements in a New Library .. • •
..
Figure 5-· 11. Including Source
Statements from a Library • • .. •
•
Figure 6-·1. Basic Linkage Editor
Processing. • • .. • • • • • • • •
•
Figure 6-·2. Linkage-Editor Data Sets • •
Figure 6-·3. Processing of Additional
Data Sources. • .. • • .. • • • • •
•
Figure 6-'4. Program Suital:>le for
Overlay Structure • • • • • • • • .. • •
Figure 6-· 5. Overlay Tree Structure
for Proqram of Figure 6-4 • • • • • • ..
Figure 6-·6. Compiling, Link-Editing,
and Executing an Overlay Program. • • •
Figure 6-,7. Loader Processing (SYSLIB
Resolution) • • • . . . . . . . . . . . . . .
Figure 6-· 8. Loader Processing
(Link-Pack Area and SYSLIB
Resolution) • • • • • • • • • • • • • •
Figure 6-·9. Automatic Editing
•

15
16
18
19
19
20
23
25
27
27
38
40
41
44
49
53
59
60
60
61
62
66
67
74
75
76
76
78
79
79

Figure 6-10. Linkage-Loader Data Sets • 81
Figure 8-1. Cataloged Procedure
PL1DFC (Compile and Punch Object
Deck) • • • • • • • • .. • • • • • .. • • 93
Figure 8-2. Cataloged Procedure
PL1LFC (Compile and Write Object
Module) • • • .. • ...
......
94
Figure 8-3. Cataloged Procedure
PL1LFCL (Compile and Link-Edit) • .•
94
Figure 8-4. Cataloged Procedure
PL1LFCLG (Compile, Link-Edit, and
Execute). • • .. • • • • • -. .. ..
95
Figure 8-5. Cataloged Procedure
PL1LFLG (Link-Edit and Execute) • •
95
Figure 8-6. Cataloged Procedure
PL1LFCG (Compile, Load-and-Execute)
96
Figure 8-7. Cataloged Procedure
PL1LFG (Load-and-Execute) • -. .•
96
Figure 8-8. Invoking Cataloged
Procedure PLlLFLG • • • .. • • •
99
Figure 8-9 Executing PL1DFC as an
In-Stream P~ocedure • .• • • • • • • • .100
Figure 9-1. A Hierarchy of Indexes • • • 102
Figure 9-2. Fixed-Length Records • • • • 103
Figure 9-3. Variable-Length Records • • • 103
Figure 9-4. Associating a File with a
Data Set. • • • • • • • • • • • • • • .108
Figure 9-5. Data Management Access
Methods for Record-Oriented
Transmission . . . . . . . . . . . . . . . 110
Figure 9-6. How the Operating System
completes the Data Control Block. • • .111
Figure 9-7. Card Read Punch 2540:
Stacker Numbers . . . . . . . . . . . . . . 112
Figure 10-1.. Creating a Data Set:
Essential Parameters of DD Statement • • 116
Figure 10-2. Using Stream-Oriented
Transmission to Create a Data set • • • 117
Figure 10-3. Accessing a Data Set:
Essential Parameters of DD Statement • • 118
Figure 10-4. Using Stream-Oriented
Transmission to Access a Data Set .• • .119
Figure 10-5. Using a PRINT File • • • • 121
Figure 10-6. Tabular Control Table
(Module IHETAB) • • • .. • • • •
.. .122
Figure 10-7. Making a Temporary
Change in Tab Settings • • • • • • • • • 123
Figure 11-1. Creating a CONSECUTIVE
Data Set: Essential Parameters of DD
statement .. • .. • • • • • • • • • • • • 126
Figure 11-2. DCB Subparameters for
CONSECUTIVE Data Sets • • • • • • • • • 126
Figure 11-3. Accessing a CONSECUTIVE
Data Set: Essential Parpmeters of DD
Statement .. • .. • • •
• • • • • • • 127
Figure 11-4. Creating and Accessing a
CONSECUTIVE Data Set. • • • • • • • • .128
Figure 11-5. ANS Printer and Card
Punch Control Characters. • • • • • • • 129
Figure 11-6. 1403 Printer Control
codes. • • • . • • • • • . • • •
.129

9

Figure 11-7. 2540 Card Read Punch
Control Codes • • • • • • • •
.130
Figure ll-B. Printing with
Record-Oriented Transmission. • •
.130
Figure 11-9. Index Structure of
INDEXED Data Set. • • • • • • • •
.131
Figure 11-10. Adding Records to an
INDEXED Data Set. • • • • • • • •
.132
Figure 11-11. Creating an INDEXED
Data Set: Essential Parameters of DD
Statement • • • • • • • • • • • •
.133
Figure 11-12. DeB Subparameters for
INDEXED Data Set. • • • • • • •
.134
Figure 11-13. Record Formats in an
INDEXED Data Set. • • • • • • •
.136
Figure 11-14. Record Format
Information for an INDEXED Data Set. .136
Figure 11-15. Accessing an INDEXED
Data Set: Essential Parameters of DD
Statement • • • • • ,. • • • .. • •
.13B
Figure 11-16. Creating an INDEXED
Data Set. • • • • • • • .. • .. • •
.139
Figure 11-17. Updating an INDEXED
Data Set. • • • • • • • • • • • •
.140
Figure ll-lB. Creating a REGIONAL
Data set: Essential Parameters of DD
Statement • •
• • • • • • • •
.142
Figure 11-19. DCB Subparameters for
REGIONAL Data Set • • • • • • • • • • .142
Figure 11-20. Accessing a REGIONAL
Data Set: Essential Parameters of DD
Stat ement • • • • • • • • • • • • • • • 143
Figure 11-21. Creating a REGIONAL(l)
Data set. • • • • • • • • • • • • • • .145
Fi,gure 11-22. Accessing a REGIONAL(l)
Data set . . . . . . . . . . . . . . . . . . 146
Figure 11-23. Creating a REGIONAL(2)
Data Set. • .. • • . . . . . . . . . . . . . . 147
Figure 11-24. REGIONAL (2) Data Sets:
Direct Update . . . . . . . . e . . . . . . 14B
Figure 11-25. REGIONAL(2) Data Sets:
Sequential Update and Direct Input. • .149
Figure 11-26. Creating a REGIONAL(3)
Data Set. • • • • • .. • • • • • • • • .150
Figure 11-27. REGIONAL(3) Data Sets:
Direct Update • ,. • • • • • • .. • • • .151
Figure 11-2B. REGIONAL(3) Data Sets:
sequential Update and Direct Input.
.152
Figure 11-29. PL/I Message Processing
Program. • • .. • .. • • • • ...
e
.153
Figure 12-1. A Partitioned Data set
.156
G

e

10

Figure 12-2. A Partitioned Data Set
Directory Block ~ • • • • . ' . • • .. .. .157
Figure 12-3. Contents of Directory
Entry • • • .. .. .. • . ' . • • • •.• '. • .157
Figure 12-4. Placing an Object Module
in a New Library . . . . . . ~ • • • • • • 15B
Figure 12-5. Placing a Load Module in
an Existing Library • • • • •
.159
Figure 12-6. Using a PL/I Program to
Create a Member of a Partitioned Data
Set. ' . . . . . . . . . . . . . . . . . . . 160
Figure 12-7,. Updating a Member of a
Partitioned Data Set. • • • • • • • • .160
Figure 12-B,. Use of JOBLIB statement • • 162
Figure 13-1. Transfer of Control
within a Multitasking Program • • • • • 165
Figure 13-2. Flow of Control through
a Program ,. . . . . . . . '. • • •
.. .167
Figure 14-1. Return Codes from
Checkpoint Module IHECKP. • • •
• .lB2
Figure 14-2. Auxiliary Storage
required for Sort.. • ,. • • . ' .
• .lB5
Figure 14.3. DD Statements for
Sort/Merge.
• • • •
.186
Figure 14-4. PL/I Program Invoking
IHESRTA '. •
• • • • • • • • • • • 191
Figure 14-5. PL/I Program Invoking
IHESRTB • •
• • • • • • • • • • .193
Figure 14-6. PL/I Program Invoking
IHESRTC • •
• • • • • • • • .. • • 195
Figure 14-7. PL/I Program Invoking
IHESRTD • •
• • • •
• .197
Figure 14-8. Using IHESRTA to Sort
Variable-length Records • • • •
• .200
Figure 15-1. FORTRAN-PL/I Data
Equivalents. • • • • •
• .202
Figure 15-2. COBOL-PL/I Data
Equivalents • • .. • • ,. • ,. •
• .204
Figure 15-3. Initial Entry to
Procedures with the MAIN Option • • • • • 206
Figure 15-4. PL/I-FORTRAN: Example of
Named Common Storage. . ' . • • • • • • • 214
Figure D-l. Control Program Options • • 267
Figure D-2. Minimum system
Requirements. • .. • .. • • .. • • ..
• 268
Figure 0-3. possible Minimum
Configurations of Main Storage. ..
.269
Figure F-l. Shared-Library Module
Groups • • • • • ,. • • • .. • • • •
.280
Figure 1-1. Main ON-Code Groupings • • • 292
Figure 1-2. Detailed ON-Code
Groupings • • • • • • • • • • • • • • • 292
oO'.

•

•

PART 1: Basic Programming with the PL/I (F) Compiler

Part 1: Basic Programming with the PL/I (F) Compiler

11

12

Chapter 1:

In IBM System/360, programs are usually
executed as part of a group of programs
collecti'V'ely termed an operating. system.
This chapter introduces IBM System/360
Operatinq System:l. (the operating system
that includes the PL/I (F) compiler), and
describes the job control language that
enables programmers to define the
requir,ements of their programs for the
operating system. Chapter 2 illustrates
the'use of job control language for running
asimplePLII program. The two chapters
are complementary; the first briefly
describes the operating system and job
control language, and the second
demonstrates how to use them to execute a
PL/I program. Chapter 3 introduces the
concept of storage of data and shows how to
use a simple data set.

IBM

Sys~tem/360

Operating System

IBM system/360 Operating system consists of
a control program and a number of
processing programs that together assist
both the operator and the programmer in the
use of IBM System/360. The operating
system relieves the programmer of routine
and time-consuming tasks by controlling the
allocation of storage space and
input/output devices. Through the language
translators that may be included, it makes
programming easier by permitting the use of
high-lev'el languages such as PL/I. And it
increase~s the throughput of the machine
because it can proces,S a stream of jobs
without interruption by the operator; i t
provides automatic transition from one job
to another.
'rhe control :program supervises the
execution of all processing programs and
provides services that are required in
common by the processing programs during
their eJ!:ecution. It has four main
elements::
1.

Supervisor: The supervisor program is
the! control center of the operating
system, and controls and coordinates
all. activity within it.

2.

Master scheduler: The master scheduler
forms a two-way communication link

:l.IBM System/360 operating System is
frequent:ly referred to as 'the operating
system,' or simply 'the system.'

Introduction to the Operating System

between the operator and the operating
system.
3.

Job scheduler: The job scheduler reads
and analyzes the input job stream (the
sequence of control statements and
data entering the system), allocates
input/output devices as necessary,
initiates the execution of processing
programs, and provides a record of the
work processed.

4.

Data management routines: The data
management routines control
input/output operations, regulate the
use of input/output devices, and
provide access to the data held in
them.

The processing programs of the operating
system include service programs (for
example, the linkage editor) and language
translators (for example, the PL/I (F)
compiler) provided by IBM, as well as
programs that are written by the user and
incorporated as part of the system.
All the programs of the operating system
are stored in system,libraries, which are
held in auxiliary storage on a direct-access storage device.
The most important components of the
operating system that directly concern the
PL/I programmer are the job scheduler, the
PL/I (F) compiler, the linkage editor, and
the linkage loader, all of which are
discussed below. The operating system is
described in IBM system/360 Operating
system: Concepts and.Facilities.

JOB SCHEDULER
The job scheduler is the component of the
operating system that handles
communications between the programmer and
the services provided by the operating
system. A simple programming language
called job control language (JCL) enables
the programmer to specify his requirements
to the operating system. The statements of
this language indicate to the job scheduler
the start and name of the job, specify the
programs that are to be executed, and
define the auxiliary storage requirements
of the programs. In response to the job
control statements, the job scheduler
allocates the input/output units required,
notifying the operator of any tapes or disk

Chapter 1: Introduction to the Operating system

13

packs that must be mounted, and then
requests the supervisor program to initiate
the execution of the specified programs.
After the execution of each program the job
scheduler prints a record of the work done.

The use of the linkage loader and the
options available are discussed in Chapter
6.

Job Control Language Examples
PL/I (F) COMPILER
The PL/I (F) compiler is a program that
translates PL/I source programs in'to IBM
system/360 machine instructions. The set
of instructions produced by a compilation
is termed an object.module. An ob-ject
module is not in a form suitable for
loading into main storage and subsequent
execution: first it must be processed by
the linkage editor.or the linkage loader.
(Chapter 5 discusses the compiler and
describes the object module it produces.)

LINKAGE EDITOR

The following discussion of the job control
language is an overview. Job control
language is fully described in IBM
System/360 Operating.System: Job control
Langauqe.User's Guide, and Job Control
Language.Reference: however the most
significant parameters of the DO statemen't
are also described in Appendix B.
Job control language is the means by
which a programmer communicates with the
job scheduler; i,t allows the programmer to
describe the work he wants the operating
system to do, and to specify the
input/output facilities he requires. Only
seven types of s'tatetnent are involved, of
which four are relevant to this discussion:
the JOB statement, the execute (EXEC)
statement, the data definition (DO)
statement, and a delimiter statement.

The linkage editor is a program that
converts object modules into a form
suitable for loading into main storage for
execution; a program in this form is termed
a load module. The output (load module)
from the linkage editor is always placed in
a library, from which the job scheduler can
load it for execution.

The JOB statement identifies a job to
the job scheduler. In IBM System/360
Operating System" a job is an independent
request for the facilities of the operating
system; it comprises one or more job step~~.
A job starts with a JOB statement and
continues until the next JOB statement is
encountered.

The linkage editor can combine
separately produced object modules and
previously processed load modules into a
single load module. It can make changes to
sections of a load module: only sections
that are affected by the changes need be
re-compiled. It also permits a program
that is too large for the space available
in main storage to be divided so that i,t
can be loaded and executed segment by
segment.

The EXEC statement identifies a job stE~p
to the job scheduler. A job step involves
a request for the execution of a program.
Job steps can be interrelated: data can bE~
passed from one job step to the next, and
the execution of one job step can depend on
the successful execution of a preceding
step.
(No such relationship exists betweEm
jobs; they are independent of one another.)
A job step starts with an EXEC statement
and continues until the next EXEC or JOB
statement is encountered.

Chapter 6 discusses the linkage editor
and the differelJ.ces between object modules
and load modules.

LINKAGE LOADER
The linkage loader is a program tha~
converts object modules into load modules,
loads them into main storage and executes
them, all in one job step. It can combine
object or load modules into a single load
module for execution: this load module is
always placed in main storage" never in a
library.
14

DO (data definition) statements describe
the input/output facilities required in a
job step ..
The delimiter (/*) separates data in the
input stream from the succeeding job
control statements.

FORMAT OF JOB CONTROL STATEMENTS
A job control statement consists of one or
mo're aO-byte records. Since aO-column
punched cards are the most common input

Accounting
Programmer's
name
information

Name of
job

...-"'-EX t1PtE: JOB (2345, A 1111 ), J. ilL GGS

100

0

00

0

(l]

00

(]]D (I]

I1J

m

rno no 0 0 0 0 0 0 0 0 0 0 0 0 0 000 0 0 0 DOnO DOC 0 DOnO nOD 0 0 0 COO 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
'r"!"3'r'56 7 H

9101112131415161718192021222l212S26'i!'282930JI313334~3637383940414143444,46414849,OSl51,3,45556515859606161636465666168691011111314151071181980

(1)1101111 10111111111CJlI1[]1101 1 11 1 1111111111111111111 i 11111111 1'1111111,11111111111

22222222222202202222222222222022220222222222222222222222222222222222222222222222
3 3 3 3 3 3 3iD3 3 3 3 3 3 3 303 303 3 3 3 3 30303033 3 3 3 33 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3

44444044444444444044444444444444444444444444444444444444444444444444444444444444
5 5[] 5 5 5 5 5 05 5 5 5 505 5 505 5 5 5 5 505 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5
6 6 6 6 6 6 6 6 6 6 6(] 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 606 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6

7 7 707 707 7 7 7 7 1 7 7 7 7 7 7 7 77 7 77 7 7 7 7 7 7 7(1]7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 77 77 7 77 7 7 7 7 7 7 7 7 7 7 77 7 7 7 7 7 7 7 7 7
~ 8 8 8 8 8 8 8 8 8 8 8 8 808 8 8 808 8 8 8 8(]]a 08

a8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 & 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 a 8 8 8 8 8 8 8 8 8 8 8

99999999999999999999999999999999999999999999999999999999999999999999999999999999
I 2 3 4 5 6 7 6 9 10 11 12 13 14 15 16 II 18 19 20 21 2223242528 27 282930 31 323334 353631 38 39 .0 41 42 4344414641 48495051 525354 ,:' ,6 ,1 5S ,9" ,: bl '.J :4 6H6 67 66 69 10 II 12 13 74 15 16 71 16 19 60
113M

UNITED KINGDOM LIMITED,

Figure i--i.

A

~OBI

JOB Statement

medium for the job stream, the following
discussion refers to card columns rather
than to bytes.
JOB, 'BXEC, and DD statements have the
same format, examples of Which appear in
Figures :iL-l, 1-2, and 1-3. These
statement,s are identified by / / in card
columns :IL and 2. Each statement can
contain four fields (name, operation,
operand, comments), which are separated by
one or more blanks; the name field starts
in coluinn 3. A job control statement must
not extend beyond column 71; if necessary
it can be:! continued on another card, as
shown in Figure 1-3.
The .lliime field, which begins in column ,
3, can range from one to eight characters
1n length, and can contain any alphameric
(alphabe1:ic or numeric) or national (Ii) $ #)
characters. The first character must be
alphabetic or national. This field is
somtimes omitted. The name identifies the
statemeni:. and enables other job control
statemeni:.s (or PL/I statements) to refer to
it.
The ~~eration field specifies the type
of job cc:mtrol statement (JOB, EXEC, DO).
Whether it.he name field is used or not, the
operation field must be preceded by at
least once blank.
The QPerand field can contain one or
more pari5lmeters separated by commas; these

param~ters pass information to the job

scheduler, and, for the JOB, EXEC and DO
statements, are of two types, pOSitional
and keyword. Positional parameters must be
placed at the beginning of the operand
field, and are identified by their pOSition
relative to other parameters. If a
positional parameter is omitted, its
absence is indicated by a comma, unless it
is the last positional parameter, when the
comma is omitted. A keyword parameter
consists of a keyword followed by an equals
sign, which is followed by a single value
or a list of subparameters; keyword
parameters may appear in. any order, and
their omission need not be indicated.
The comments- field is intended for
programmer's notes. It has no fixed
format, and can contain any information.
The comments field is the only field that
can include blanks.
The following paragraphs contain a
general description of the functions of the
JOB, EXEC, DO, and delimiter statements;
these, and other job control statements,
are discussed further under appropriate
headings in later chapters. IBM System/360
Operating system: .Job Control Language,
User'.S Guide, and Job Control Language
Reference, gives a full description of all
the job control statements, their formats
and parameters ..

Chapter 1: Introduction to the Operating system

15

JOB STATEMENT

DD STATEMENT

The JOB statement (Figure 1-1) indicates
the start of a job and the end of the
preceding job. It assigns a name to the
new job. which is used by the job scheduler
in the messages it passes to the operator
and prints on the program 1isting~ The
parameters (none of which need appear
unless your installation has made some of
them mandatory) include the programmer's
name and accounting information.

In IBM System/360, a collection of data
held in an auxiliary storage device (a reel
of magnetic tape, a disk pack. etc •• ) is
termed a data set. A DD statement (Figure
1-3) identifies a data set and describes
its attributes. There must be a DD
statement for each data set that is useal or
created in a job step. The DD statement:s
are placed immediately after the EXEC
statement for the step.

EXEC STATEMENT
The EXEC statement (Figure 1-2) marks the
start of a new job step and the end of the
preceding job step. It requests the job
scheduler to fetch a load module from the
system library (or from another library)
and cause it to be executed; other load
modules can be loaded dynamically during
the execution of the first. but only one
can be named in the EXEC statement. The
first parameter (PGM=) names the program to
be executed. Sometimes the EXEC statement
passes information to the program that it
calls (PARM parameter). and it may include
accounting information and specify
conditions for bypassing the job step.
Name of
job step

Program to
be executed

The parameters of the DD statement
contain such information as the name of the
data set, the name of the volume on which
it resides, the type of device that holals
the data set, the format of the records in
the data set, and the method that will be
used to create or access the data set. The
name of the DD statement provides a
symbolic link between the file named in a
PL/I program and ·the actual name and
location of the corresponding data set.
The DD statement allows the programmer to
leave the specification of his data set
requirements until he is ready to execute
his program, and enables him to relate t,he
file in his program to different data sets
on different occasions. Some data set
information can be given in the PL/I
ENVIRONMENT attribute rather that in a DD
statement.

Information being passed
to program IEMAA

~-/-/~P~L~1~L~~~X~~~C~P~G~M-=~I~~A~~~4'~P~A~R~~~=~'~----------------------------------~
'r

,r

om

000

/

0 OO[D 0
OJ
OD D Dm IlJ

IDJ
0

[I]

mO 0 DDDDnO 0 0 DOD DOD 0 DOnO 0 0 0 0000 Cono 0 G3 0 0 0 DOC 0 0 0 0 0 0 0 000000000000000000000000000000
W3 4 5 6 7 I 'r'10 11 72131415161718

191021W21212~2627281930 3131~343~3Sl7383940 41414J444~46474849505151535455565758596061626J64656667686970

II 11 7374757677787980

III 1 101 1 1 1 1 101 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 Iii I 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 I 1 1 I

[1]1 101 1 1 1 1 1 1 1 1 1 1 1 1 1

22222222222222222222222222222222222222022222222222222222222222222222222222222222
3 3 30303 3 3 303 3 3 3 3 3 3 3 3 303 3 3 3 3 303 3 303 3 3 303 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3
44444444444444044404444440444440444044444444444444444444444444444444444444444444

55555550505555555055555555505555505505505555555555555555555555555555555555555555
6 6 6 6 6 6 6 6 6 6 6 6 6 6 606 6 6 6 6 6 6 6 6 606 6[)6 6 6 6
7 707 7 7 7 707 7 7[J]7 77 7 77 77

Os 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6

077 77 71 77 7 7 77 71 77 7 77 7 7 7 7 77 7 7 7 7 77 7 77 7 77 77 7 7 77 7 77 77 7 7 77 7 7 7 7 7
rna 8 8 8Os 8 8 8 8 808 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8

8 8 8 8 8 8 8 8 8 8 8 8 8 8 808 8 8 8 808 8 8 8
9999999999999999

ng 9 9 9 9 9 9n9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9

1234587'9~l1tlQ~~I6~I619~~n21NW28n28H~~n~~~~n»»d~~o«~«c«u~~~~~e56H5656~~~~"~~~U"ronn73H~~77n~~
IBM

Figure
16

UNITED KINGDOM LIMITED

1-2~

An

EXEC Statement

~081

Chapt:er 3 discusses the creation and
access of simple data sets: Chapter 9 is a
completE! discussion of data management for
a PL/I program.

DELIMITER STATEMENT
The delimiter statement consists of the
charactE!rS /* in card columns 1 and 2.
It
separatE!S data in the input stream from the
job cont:rol statements that follow the
data. Dqta in the input stream is usually
preceded by a DD statement with the operand
*, for E!xample:
//SYSIN DD

*

If the data includes cards that have / / in
the first two columns, i t is preceded by a
DD statE!ment with the operand DATA, for
example:
/

/Sl~SIN

DD DATA

Executi:ng a PL/I Program
A job consists of one or more job steps,
and each job step normally uses one or more
data se·t:s. Thus the sequence of job
control statements for a single job
comprises a JOB statement followed by the
EXEC and DO statements for each job step.
Figure 1-4 illustrates such a sequence; it
has beel simplified by omitting all the
parameters in the various statements.
The execution of a PL/I program requires
two or t:hree job steps:
1.

Compilation: The compiler converts the
PL/I statements into machine
instructions, which form an object
module.

2.

Link-editing or link-loading: The
linkage editor processes the object
module produced in step 1, and forms
it into a load module that can be
eXE~cuted.
The linkage loader converts
the object module into a load module
and executes it.

3.

EXE~cution: The load module formed by
the linkage editor is loaded into main
storage and executed.

The sequence of job control statements
in Figmre 1-4 might be used for compiling,
link-editing, and executing a PL/I program.
The ~JOB statement would probably have to
include certain parameters required by the

installation. The parameters needed and
the values used with them vary from
installation to installation; it is your
responsibility to supply the correct
information in this statement.
The EXEC statement for the first job
step (named PL1L) requests the execution of
the program IEMAA, the PL/I (F) compiler;
the DO statements defining the data sets
required for this step follow the EXEC
statement.
SYSPRINT and SYSIN refer to the
printer and the card reader, respectively,
as they do in the other job steps. The
object module produced by the compiler is
placed in the data set identified by
SYSLIN. SYSUTl and SYSUT3 define data sets
used as workfiles.
The second EXEC statement (LKED) causes
program IEWL, the linkage editor, to be
executed,•. The linkage editor finds its
primary input (the object module) in the
data set referred to by the DO statement
named SYSLIN; it may seek further input
from the private library identified by
SYSLIB. The load module produced by the
linkage editor is placed in the data set
identified by SYSLMOD.
SYSUT1 defines a
data set used as a workfile.
The last EXEC statement (GO) requests
the execution of the load module created by
the linkage editor in the previous step; a
special form of the PGM parameter is used
for this.
The sequence of job control statements
using the linkage loader is shown in Figure

1-5.

Cataloged Procedures
Often the/same set of job control
statements is used over and'over again (for
example, to specify the compilation,
link-editing, and execution of many
different PL/I programs). To save
programming time and to reduce the
possibility of error, sets of standard
series of EXEC and OD statements can be
prepared once and 'cataloged' in a system
library; such a set of statements is termed
a cataloged procedure.
To retrieve a cataloged procedure, an
EXEC statement is used in which the first
parameter (PROC=) names the procedure. The
effect is the same as if the job control
statements of the cataloged procedure
appeared in the job stream in the place of
the EXEC statement that calls the
procedure.
In such an EXEC statement, the
keyword PROC can be omitted; the name of
the procedure stands alone as if it were a

Chapter 1: Introduction to the Operating System

17

Name of
data set

Name of DO
statement

Type of device
(2400 series
magnetic tape
drive)

Record format

//TC:: Tl '0'0 DSNAMC::=Tl='" LC::,lr.'tIT=24

o rno

DO

{DO

DO

0

0 0

UlJo mo 0 0 0 0 000 0 0 0 0no 0 0 0([Jo 0no 0 crTTlo G3 0 0 0 0 000

oa 0 0 0rno 0 0 0 0 0 0 0no 0 0 0 0 0 0 0 0no 0 0 0 00 0 0 0 0

9101J12IJI41516J718'i(2021222124252627'i(293031~351617181940414143444H641484950515253545S56575859~616261646566676869'ltl1711314751077781980
(1]11110111111101111111111111111111111111111111111111 i 111111111111111111111111111
123 4W7 U

2 2 2 202 2 2 2 2 2 202 2 2 2 2 2 2 2 2 2 2 2 2 2 2 202 2 2 2 2 202 202 (1]2 2 2 202 2 2 2 2 2 2 2 202 2 2 2 2 2 2 2 202 2 2 2 2 2 2 2 2 2 2 2
33033033333333333303303033303333303(1333 a03 3 3 3 3 3 3 3 3(1)3 3{D3 3 303 303 3 3 3 3 303 3 3 3 3 3 3 3 3 3

44444444004044404444444404444404440444444444444444444444444444440444444444444444

5550555555555055055555055055555555555505555550555555505555555055 555 5055555555555
6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 60606 6 6 6 6 6 6 606 6 6 6 6 6 6 606 6 6 6 6 6 6 606 6 6 6 6 6 6 6 606 6 6 6 6 606 [J]& 6 6 6 & 6 6 6 6 6 6 6 6

7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 77 77 7 7 7 7 77 7 7 7 7 77 7 77 7 77 7 7 7 7 7 7 7 7 7 7 7 7 7 7 77 77 7 77 7 7 7 77 7 77 7 77 77 7 7 7 7 77 7 7 7
8 8 8 8 a8 8 8 8 8 8 8 8 8 8 8 8088 8 8 808 8 8 808 8 8 808 8 8(D8 8 8 8 8 8 80808 Os 8 8 8 808 rn8 8 8 8 808 81lJa 8 8 8 8 8 8 8 a8

99999999999999999999

ng 9 9 9 9ng 9 9 9 9 9 9 ~59 9 9 9 9 9 9 9 9[l]s 4~9 9 9 9 9 909 5~'9 9 9 9 9 909 9 9 9 6~9 9 9 9 9 9 9 9 9 9 9 9 9 9 9

I 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 J7 18 19 20""22 23 24 25 26 ~ 28 29 30 3' 32 33 34
IBM

UNITED

KINGDOM

LIMITED

36 37 38 39 .0 41 '12 4344 4H6

4849 50 51 52 53 54

56 57 58 59 60 61 62 !3 64 61

67 68 69 70 71 72 13 74 75 76 77 78 79 80

~081

Disposition (new data set,
to be filed at end of job)

"

// DISP=(NC::W,KC::C::P)
(IJ 00 OJ

o0 0 m
mo 0 0Ifno 0 0 0 0mo 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 COo 0 0 G3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
'r"r'3 4 5

7 H 910 1J'ifr114 1516 17 18192021222124252627 282930 31313334 351837 3a3940 41424344 4546 41484950515253545556515859606162636465666168691011 7113 74 75 7. 77 787980

0)11111111111111111111111111111111111111111111111111 i 111111111111111111111111111

22222022222220222222222222222222222222222222222222222222222222222222222222222222
3 3 3 3 3 3 J 3 3 J 3 3OJ 3 3 J 3 3 3 J 3 3 J 3 J 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 J 3 3 3 3 3 3 3 33 3 J 3 3 3 3 33 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3

44404444444444444444444444444444444444444444444444444444444444444444444444444444

5 5 5 5 5 5 5 5([1)5 5 5[l)5 05 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5
6666666066606666666666666666666666666666666666666666 6 6 6 6 6 6 6 6 66666666666666666666

777777077 7 7 7 7? 77077 7 7 7 7 7 7777777 77 7 7 7 7 717 7 7 7 717 7 7777 77 7 7 7 7 77 7777777 77 '17 7 77 77 77 7 7 7
88

a a8 8 sma 8 808 8 8 808 8 a8 8 a 8 8 8 8 8 8 8 8888888 a8 a8 8 8 888 a8 8 8 8 8 8 8 8 8 8 8 8 888888881188888 a 8 8 8 8 8

9999
I 2 3 4

ng 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 ~o9 9 9 9 9 9 9 9 9 9 9 9 9 9 545~·
999999999999999999999999999

'!' 6

I 8 9 10 11 12 13 14 15 16 11 18 19 20 21 22 2324 25 26 27 282930 3' 32333053631 38 39
IBM

UNITfD

Figure 1-3.

KINGDOM

LIMITED

41 424344 4146 41 48495051 52 53

A DO statement (Using a continuation Card)

positional parameter. For example, the
following EXEC statements have the same
effect:

18

56 17 S8 596081 &2 !3 64 6516 67 68 69 10 71 72 13 14 7576 7116 79 80

~081

// EXEC PROC=PL1LFCLG
// EXEC PL1LFCLG

The job control statements in Figure '1-4
(apart from the JOB statement and the DD
statements named SYSIN) are the same as
those in the cataloged procedure PL1LFCLG.
You can use this cataloged procedure, which
is supplied by IBM, for compiling,
link-editing, and executing a PL/I program.
Chapter 2 illustrates the use of PL1LFCLG.
Chapter 8 is a complete discussion of
catalo.ged procedures; it describes the IBM
cataloged procedures for PL/I and tells you
how to modify them and how to catalog your
own procedures.
//EXAMPLE JOB
//PL1L EXEC PGM=IEMAA
//SYSP:RINT DD
//SYSLIN DD
/ /SYSUT1 DD
/ /SYSUT3 DD
//SYSIN DD *
Cards containing PL/I source
statemeQts come here

Start of job

,

I
I
I
I
I
I
I
I

> First job
step

Cards containing PL/I source
statements come here

//LKED EXEC PGM=IEWL
//SYSLIB DD
/ /SYSLlMOD DD
/ /SYSU'T1 DD
//SYSPRINT DD
//SYSLIN DD
//GO EXEC PGM=*.LKED.SYSLMOD
//SYSPRINT DD
//SYSIN DD *

//GO EXEC PGM=LOADER
/ /SYSLI B DD ,
//SYSLIN DD
//SYSLOUT DD
//SYSPRINT DD
//SYSIN DD *
Cards containing data to
be processed by the PL/I
program come here

Cards containing data to
be processed by the PL/I
program come here

I
I

> Second job
step

J

,
I
I
I

I
I
I

> Third job
step

/*

J

//NEXT JOB

Start of next
job

Typical Sequence of Job
Control Statements for
Compile, Link-Edit, and
Execute Steps

I
I
I
I
I
I
I
I

of job

> First job
step

,
I
I
I
I
I
I
I
I
I

> Second job
step

/*

J

//NEXTJOB JOB

Start of next
job

,
I

,Start

J

/*

J

/*

Figure 1-4.

//EXAMPLE JOB
//PL1L EXEC PGM=IEMAA
//SYSPRINT DD
//SYSLIN DD
//SYSUT1 DD
//SYSUT3 DD
//SYSIN DD *

Figure 1-5.

Typical Sequence of Job
Control Statements for Compile
and Load-and-Execute Steps

If a procedure is programmer-written, it
can be tested as an in-stream procedure
before it is placed in the procedure
library. An in-stream procedure is a
series of job control statements enclosed
between a,PROC and a PEND statement
appearing in the job stream. An in-stream
procedure can be executed any number of
times during a job and has the same content
restrictions as a cataloged procedure. For
further information about in-stream
procedures, refer to the publication IBM
system/3600peratinq-System: Job Control
LanquageReference.

Chapter 1: Introduction to the Operating System

19

Chapter 2: How to Run a Simple PL/I Progam

For a PL/I program that uses only
punched-card input and printed output, the
job control statements shown in Figure 2-1
are sufficient~. Appendix A includes an
example of a simple PL/I program that uses
these statements.

cataloged procedure PL1LFCLG contains
three job steps:
PL1L:

The PL/I (F) compiler processes
your source statements and
translates them into a set of
machine instructions (an object~
module).

LKED:

The linkage editor creates a
load module from the object
module produced by the compiler.
A load module is a series of
machine instructions that are in
a form suitable for loading int.o
main storage and subsequent
execution; only load modules can
be loaded and executed.

GO:

The load module created in step
LKED is loaded into main storag'e
and executed.

//EXAMPLE JOB
// EXEC PL1LFCLG
//PL1L.SYSIN DD *
Insert here the cards
containing your PL/I
so~rce statements.
/*

//GO.SYSIN DD

*

Insert here the cards
containing the data to
be processed by your
program.

If your program
requires no
externa 1 data,
omit these
sta tements.

/*

Figure 2-1.

Job Control Cards for the
Execution of a Simple PL/I
Program

Job Control Statements
//EXAMPLE JOB
EXAMPLE is the name of the job. Your
job. name must not have more than eight
alphameric or national characters; the
first character must be alphabetic or
national. No parameters are given for
this statement. If any are needed they
will depend on your installation; the
minimum requirement is probably an
account number and your name. Before
writing the JOB statement, ensure that
you are familiar with the conventions
established by your installation for
the JOB statement and its parameters.
//

EXEC PL1LFCLG
PL1LFCLG is the name of a cataloged
procedure supplied by IBM. When the
job scheduler encounters the name of
such a procedure in an EXEC statement,
i t substitutes for the EXEC statement a
series of job control statements that
have been written previously and
cataloged in a system library. The

~Chapter

9 contains a complete discussion
of data management.
20

//PL1L.SYSIN DO *
This statement indicates that the data
to be processed in step PL1L follows
immediately in the card deck. SYSIN is
the name that the compiler uses to
refer to the device on which i t expects
to find this da'ta.
(In this instance,
the device is the card reader, and the
data is your PL/I program.)
/*

This signifies the end of, the data.
//GO.SYSIN 00 *
This statement indicates ·that the data
to be processed by your program (in
step GO) follows immediately in the
card deck.
/*

This statement marks the end of the
. data to be processed by your program.
Note: You could have used the IBM cataloged
procedure PL1LFCG in place of PL1LFCLG.
This procedure cOnsists of two job steps:
PL1L:

The PL/I (F) compiler processes the
source statements and produces an
object module.

GO:

The object module is converted to a
load module" loaded into main
storage and executed.

FUR'llHER INFORMATION

Chapter 8 describes the cataloged procedure
PL1LFCLG and other PL/I cataloged
procedures supplied by IBM. Chapters 5, 6,
and 7 deal with the job steps (compile,
linkage, and execute) that are included in
PL1LFCG and PL1LFCLG.

Chapter 2: How to Run a Simple PL/I

Prog~am

21

Chapter 3: How to Create and Access a Simple Data Set

A data set is any collection of data in
auxiliary storage that can be created or
accessed by a program. It can be punched
onto cards or a reel of paper tape: or it
qan be recorded on magnetic tape or on a
qirect-access device such as a magnetic
disk or drum. A printed listing can also
be a data set, but it cannot be read by a
program.
Data sets that are created or accessed
by PL/I programs must have one of three
types of organization: CONSECUTIVE,
INDEXED, or REGIONAL or must be a
teleprocessing data set. The items of data
in INDEXED and REGIONAL data sets are
~rranged according to 'keys' that you
supply when you create the data sets.
CONSECUTIVE data sets do not use keys: when
you create such a data set, data items are
iecorded consecutively in the order in
Which you present them. You can read the
data items from a CONSECUTIVE data set only
i'n the order in Which they were presented
or, in the case of a data set on magnetic
tape, in the order in which they were
presented or in the reverse order.
Teleprocessing data sets are organized as
consecutive groups of data items.
This chapter explains how to create and
a,ccess simple CONSECUTIVE data sets stored
on magnetic tape or on a direct-access
device. It is intended to provide an
i.ntroduction to the subject of data
management, and to meet the needs of those
programmers who do not require the full
input/output facilities of PL/I and IBM
S~stem/360 Operating System.
Chapters 9,
fo, and 11 contain a full explanation of
t'he relationship between the data
~anagement facilities provided by PL/I and
tihose provided by the operating system.

U sing a Data Set
To create or access a data set, you must
not only include the appropriate input and
output statements in your PL/I program, but
you must also supply certain information to
the operating system in a DO statement. A
DD statement describes a data set and
indicates how it will be handled: the
information it supplies enables the job
scheduler to allocate the necessary
auxiliary storage devices, and permits the
22

compiler to use the data management
routines of the operating system to
transmit data.
IBM System/360-0perating system: PL/I
(F) Language Reference Manual describes the
input and output statements that you will
need to use in your PL/I program.
Essentially, you must declare a file
(explicitly or contextually) and open it
(explicitly or implicitly) before you can
begin to transmit data. A file is the
means provided in PL/I for accessing a data
set, and is related to a particular data
set only while the file is open: when you
close the file, the data set is no longer
available to your program. This
arrangement allows you to use the same file
to access different data sets at different
times, and to use different files to access
the same data set.
Contextual declaration and implicit
opening' are performed" where required, in
any of the input/output statements GET,
PUT" READ, WRITE, LOCATE, and REWRITE.
You must provide a DO statement for each
data set that you will use in each job
step. If you use the same data set in more
than one job step, each step which refers
to that data set must have a DD statement
for the data set.
If you are using a cataloged procedure,
such as PL1LFCG or PLlLFCLG (described in
Chapter 2), the DD statement for any data
set processed by your program must appear
in job step GO, in which your program will
be executed. To signify its inclusion in
this job step, you must prefix the name of
the DD statement with the name of the job
step. (For example, / /GO. LIST DD... would
indicate a OD statement named LIST in step
GO.) The DD statement for the data set in
the input stream (e.g., GO.SYSIN), if it is
used in a PCP system, must be the last DD
statement in your card deck.

How to Create a Simple Data Set
When you create a new data set, you should
supply the following information to the
operating system:

Parameter of
DD Statement

TYPE OF OUTPUT DEVICE (UNIT=)

Type of: output device that
will wX'ite or punch your
data sert.

UNIT=

Serial number of the volume
(tape x'eel, disk pack,
etc.) t,hat will contain
your data set.

VOLUME=SER=

You must always indicate the type of output
device (magnetic tape or disk drive, card
punch, printer, etc.) that you want to use
to create your data set. Usually the
simplest way to do this is to use the UNIT
parameter, although for a printer or a card
punch it is often more convenient to use
one of the special forms of DD statement
discussed at the end of this chapter.

Name of your data set.

DSNAME=

Format of the records in
your data set.

DCB=

Amount of auxiliary storage
required for your data set
(direct-access devices
only).

SPACE=

Disposition of your data set
at the end of the job step.

DISP=

In the UNIT parameter" you can specify
either the type number of the unit (for
example, 2311 for a disk drive) or the name
of a group of devices (for example, SYSDA
for any direct-access device). Appendix B
includes a list of the valid type numbers;
the group names are established for a
system during system generation.
VOLUME SERIAL NUMBER (VOLUME=SER=)

Note: You can use the abbreviations VOL for
VOLUME and DSN for DSNAME.

A unit of auxiliary storage such as a reel
of magnetic tape or a'magnetic disk pack is
termed a volume; a volume can contain one
or more data sets, and a data set can
extend to more than one volume. Each
volume is identified by a serial number
that is recorded within it (and usually
printed on the label attached to it).
Although a deck of cards" a printed
listing, and a reel of paper tape can be
considered to be volumes, they do not have
serial numbers.

To give this information in the DD
statement, use the parameters listed above.
Appendix B contains a description of these
parameters; the following paragraphs
discuss their use in creating a CONSECUTIVE
data set. Figure 3-1 summarizes this
discussion.

r---------------------T-----------------------------------------------------------------,
I
Parameters of,DD Statement
I

I
I
I

Storage Device

~---------------------T---------------------~--------------------~
I

When required

,What you must state ,

Parameters

I

~---------------------+---------------------+---------------------+---------------------~
I

I

I All

I Always
I

I

I Output device
I UNIT= or SYSOUT=
I
~---------------------+_--------------------~

I Block sizeS.

I DCB=BLKSIZE=

I

~------.---------------+---------------------+---------------------+---------------------~
I

I

Direct access only

'Always

I

I

Auxiliary storage

I space required

I SPACE:

I

I

I

~---------------------+-----------~---------+---------------------+---------------------~
I

I

Data set to be used I

I

I by another job step I Disposition

I
I

but only required
I
I
I
by this job
I
I
I
~---------------------+---------------------+---------------------~
I Data set to be kept , Disposition
I DISP=
I
I after end of job
~---------------------+_--------------------~
,
, Name of data set
'DSN=
I

, magnetic tape
I
I

I

,
I

I Direct access and
I standard labeled
I
I

I DISP=

I

I

~---------------------+---------------------+---------------------~
I
I

Data set to be on
particular volume

I
I

Volume serial number' VOL=SER=
I

I

I

~---------------------~---------------------~---------------------~---------------------~
IS.Alternatively, you can specify the block size in your PL/I program by using the
I
LI _______________________________________________________________________________________
JI
ENVIRONMENT attribute.

Figure 3-1.

Creating a CONSECUTIVE Data Set: Essential Parameters of DD Statement
Chapter 3: How to Create and Access a Simple Data Set

23

You need speGify a volume serial number
only if you want to place the data set on a
particular volume. If you omit the VOLUME
parameter, the job scheduler will print in
your program listing the serial number of
the volume on which it placed the data set.
The VOLUME parameter has several
subparameters. To specify a 'volume serial
number, you need only the SER (serial
number) subparameter (for example
VOLUME=SER=12354).

NAME OF DATA SET (DSNAME=)
You must name a new data set if you want to
keep it for use in future jobs. If the
Qata set is temporary (required only for
the job in which, it is created), you can
still name it" but you need not: if you
omit the DSNAME parameter, the operating
system will assume that the data set is
temporary, and will give it a temporary
name.
(Any name you give to a temporary
data set must be prefixed with the
characters ii; for example. DSNAME='&TEMP.)

FORMAT OF THE RECORDS (DCB=)
You can give record-format information
either in your PL/I program (ENVIRONMENT
attribute or LINESIZE option) or in a OD
statement. This discussion refers only to
the DD statement, and does not apply if you
decide to give the information in your
program; refer to IEM System/360 Operating
system: ',PL/I', (F) ,Language Reference "Manual
for a description of the ENVIRONMENT
attribute and the LINESIZEoption.
The records in a data set must have one
of three formats: F (fixed length), V
(variable length), U (undefined length).
F-format and V-format records can be
blocked or unblocked; V-format records can
be spanned.
In most cases, you must specify a block
size. If you do not give a ,record size,
unblocked records of the same size as the
block size are assumed. Note that, if you
are using a PRINT file to produce p:rinted
output, you do not need to specify a block
size in your DD statement or in your PL/I
program; in the absence of other
information, the compiler supplies a
default line size of 120 characters. If
you do not state the' record format,
U-format is assumed (except for data sets
associated with PRINT files, for wh.ich
V-format is the default).
24

To give record-format information in a
DD statement, use the subparameters RECFM
(record format), BLKSIZE (block size), and
LRECL (logical record length) of the DCB
parameter. The DCB parameter passes
information to the operating system for
inclusion in the data control'block, which
is a table maintained by the data
management routines of the operating system
for each data set in a job step; it
contains a 'description of the data set and
how it will be used. If your DCB parameter
includes more than one subparameter, you
must enclose the list in parentheses. For
example:
DCB= (RECFM=FB, BLKSIZE=1000,LRECL=50)

AUXILIARY STORAGE REQUIRED (SPACE=)
When you create a data set on a
direct-access device, you must always
indicate the amount of space that the data
set will occupy. Use the SPACE parameter
to specify the size and number of the
blocks that the data set will contain. If
you may want to extend the data set in a
later job or job step, ensure that your
original space allocation is sufficient for
future needs; you cannot make a further
allocation later. If the SPACE parameter
appears in a DD s'tatement for a
~on-direct-access device. it is ignored.

DISPOSITION OF DATA SET (DISP=)
If you want to keep a data set for use in ia
later job step or job, you must use the
DISP parameter to indicate how you want it
to be handled. You can pass i,t to another
job step, keep it for use in a later job"
or enter its name in the system catalog.
If you want to keep the data set, but do
not want to include its name in the system
catalog, the operating system will request
the operator to demount the volume in which
it resides and retain it for you. If you
do not include the DISP parameter, the
operating system will assume that the data
set is temporary and will delete it at the
end of the job step.
The DISP parameter can contain three
positional subparameters. The first
indicates whether the data set is new or
already exists, the second specifies what
is to be done with it at the end of the job
step, and the third indicates how it should
be treated if the job step is terminated
abnormally by the operating 'system. If you
omit either of the first two, you must
indicate its absence by a comma.

VOLUME SERIAL NUMBER

For example,
DISP= ( , CATLG , DELETE)
indicatE~s
catalogE~d

that the data set is to be
if the job step termina.tes
normally, and deleted if it is berminated
abnormally: the omission of the :first
subpar~~eter indicates that the data set is
assumed by default to be new~

You can omit the VOLUME parameter if the
data set is cataloged or if it was created
with DISP=(,PASS) in a previous step of the
same job. Otherwise i t must always appear.

NAME OF DATA SET

How to .Access an Existing Data Set
When you want to read or update an existing
data set., your DO statement should include
informat:ion similar to that given when the
data set: was created. However, for data
sets on labeled magnetic tape or on
direct-access devices, you can omit several
parametE~rs because the information they
contain was recorded with the data set by
the opel~a ting system when the data set was
created., Figure 3-2 summarizes the
essential information.
Except in the·· special case of data in
the input stream (described below), you
must al~,ays include the name of the data
set (DSNAME) and its disposition (OISP).

The DSNAME parameter can either refer back
to the DD statement that defined the data
set in a previous job step, or it can give
the actual name of the data set.· (You
would have to use the former method to
refer to an unnamed temporary data set.)

FORMAT OF THE RECORDS
You must always state a block size for
punched cards or paper tape: otherwise,
record-format information is not required.
Block size can also be specified in your
PL/I program, using the ENVIRONMENT
attribute.

AUXILIARY STORAGE REQUIRED
TYPE OF INPUT DEVICE
You can omit the UNIT parameter if the data
set is cataloged or if it was created with
DISP=(,.PASS) in a previous step of the same
job. Ot:herwise, it must always appear.

You cannot add to, or otherwise modify, the
space allocation made for a data set when
it was created. Accordingly, the SPACE
parameter is never required in a OD
statement for an existing data set.

r-------··------------------------------------------------------------------------------,
I
Parameters of DD Statement
I
~-----------------------------------T-------------------------T-------------------------~
I
When required
I
What you must state
I
Parameters
I
~------------------------------------+-------------------------+-------------------------~
I
I Name of data set
I DSN=
I
I Always
~-------------------------+_------------------------~
I
I Disposition of data set I OISP=
I
~------------------T-----------------+-------------------------+_------------------------~
I
IAlI devices
I Input device
I UNIT=
I
IIf data set not .-----------------+-------------------------+------------------------~
Icataloqed
IMagnetic tape andl Volume serial number
I VOL=SER=
I
I
Idirect access
I
I
I
~------------------~-----------------+-------------------------+-------------------------~
IFor pWlched cards or paper tape
I Block size~
I DCB=BLKSIZE=
I
~------.-----------------------------~-------------------------~-----~-------------------~
11 Alternatively, you can specify the block size in your PL/I program by using the
I
lI ________________________________________________________________________________________
JI
ENVIRONMENT attribute.
Figure 3-2.

Accessing a CONSECUTIVE Data Set: Essential Parameters of DO Statement
Chapter 3: Bow to Create and Access a Simple Data Set

25

DISPOSITION OF DATA SET
You must always include the DISP parameter
to indicate to the operating system that
the data set already exists. Code DISP=SHR
if you want to read the data set, DISP=OLD
if you want to read and/or overwrite it, or
DISP=MOD if you want to add records to the
end of it.
You need not code the second term of the
DISP parameter if you want the data. set to
resume the status it had before the job
step; existing data sets will continue to
exist, and newly created data sets will be
deleted.

in the input stream must, like job control.
statements, be in the form of SO-byte
records (usually punched cards), and must
be immediately preceded by a DD statement
with the single parameter * in its operand
field, for example:
//GO.SYSIN DD

*

To indicate the end of the data, include a.
delimiter job control statement (/*). A DD
statement that introduces data in the input
stream must be the last DD statement in the
job step.
If your data includes records that
commence // in the first two columns use
the parameter DATA, for example:
//GO.SYSIN DD DATA

SPECIAL-PURPOSE PARAMETERS
Three parameters of the DD statement have
special significance in that they permit
you to use a very simple form of DD
statement; they are SYSOUT, which is
particularly useful for printed or
punched-card output, and *, and DATA, which
allow you to include data in the input
stream.

SYSTEM OUTPUT (SYSOUT=)
A system output device is any Wlit (but
usually a printer or a card punch) that is
used in common by all jobs. The computer
operator allocates all the system output
devices to specific classes according to
device type and function. The usual
convention is for class A to refer to a
printer and class B to a card punch; the
IBM-supplied cataloged procedures assume
that this convention is followed.
To route your output via a system output
device, use the SYSOUT parameter in your DD
statement. The only essential additional
parameter is the block size (if not already
specified in your PL/I program by using the
ENVIRONMENT attribute). Thus, if you want
to punch cards, you can use the DD
statement
//GO.PUNCH DD SYSOUT=B,DCB=BLKSIZE=80

DATA IN THE INPUT STREAM
A convenient way to introduce data to your
program is to include it in the input job
stream with your control statements. Data
26

Standard Files
PL/I includes two standard files, SYSIN for
input and SYSPRINT for output.
If your
program includes a GET statement without
the FILE option, the compiler inserts the
file name SYSINi if it includes a PUT
statement without the FILE option, the
compiler inserts the name SYSPRINT.
If you use one of the IBM-supplied
cataloged procedures to execute your
program, you will not need to include a DD
statement for SYSPRINTi step GO of the
cataloged procedures includes the
statement:
//SYSPRINT DD SYSOUT=A
Note that no block size is specified in
this DD statementi the block size for the
data set associated with SYSPRINT is
supplied by the (F) compiler. However, if
your program uses SYSIN, either explicitly
or implicitly, you must always include a
corresponding DD statement.

Examples
The examples of simple applications for
CONSECUTIVE data sets shown in Figures 3-3
and 3-4 should need no further explanation.
The first program evaluates the familiar
expression for the roots of a quadratic
equation and records the results in a data
set on magnetic disk and on punched cards.
The second program reads the disk data set
created in the first and prints the
results.

//J001PGEX JOB
// EXEC PL1LFCLG
//PL1L.SYSIN DD *
CREATE: PROC OPTIONS(MAIN);
DCL PUNCH FILE STREAM OUTPUT,
DISK FILE RECORD OUTPUT SEQUENTIAL,
1 RECORD, 2CA,B,C,Xl,X2) FLOAT DEC(6) COMPLEX,
ON ENDFILECSYSIN) GO TO FINISH;
OPEN FILECPUNCH), FILECDISK);
NEXT:
GET FILE(SYSIN) LISTCA,B,C);
Xl=(-B+SQRTCB**2-4*A*C»/(2*A);
X2=(-B-SQRT(B**2-4*A*C»/(2*A);
PUT FILE(PUNCH) EDIT (RECORD) (C(EC16,9»);
WRITE FlLECDISK) FROMCRECORD)i
GO TO NEXT;
FINISH: CLOSE FlLECPUNCH), FILECDISK);
END CREATE;
/*

//GO.PUNCH DD SYSOUT=B,DCB=BLKSIZE=80
/ /GO. DISK DD. UNIT=2311,VOLUME=SER=D186,DSNAME=ROOTS,
//
DCB=(RECFM=FB,BLKSIZE=400,LRECL=40),
//
SPACE=CTRK,Cl,l»,DISP=CNEW,KEEP)
//GO.SYSIN DD
5 12 4
4 -10 4
5 16 2
4 -12 10
5 12.9
29 -20 Li·

*

/*

Figure 3-3.

Creating a Simple CONSECUTIVE Data Set

//J027PGEX JOB
/ /COLEEX: EXEC PL1LFCLG
//PL1L.S:YSIN DD *
ACCESS: PROC OPTIONSCMAIN)i
DCL RESULTS FILE RECORD INPUT SEQUENTIAL,
1 RECORD, 2 CA,B,C"Xl,X2) FLOAT DEC(6) COMPLEX;
ON ENDFILECRESULTS) GO TO FINISH;
PUT FILE (SYSPRINT) EDIT C• A' , • B' , • C' I' "Xl' , " X2 ' )
(XC7),3CA,XC23»,A,XC22),A);
OPEN FILE(RESULTS);
NEXT:
READ FILECRESULTS) INTOCRECORD);
PUT FILE(SYSPRINT) SKIP EDIT(RECORD) (C(FC12,2»);
GO TO NEXT;
FINISH: CLOSE FILECRESULTS);
END ACCESS;
/*

//GO.RESULTS DD UNIT=2311,VOLUME=SER=D186,DSNAME=ROOTS,DISP=COLD,KEEP)
Figure 3·-4.

Accessing a Simple CONSECUTIVE Data Set

Chapter 3: How to Create and Access a Simple Data Set

27

28

PART 2: Using all the Facilities of the PL/I (F) Compiler

Part 2: Using all the Facilities of the PL/I (F) Compiler

29

30

Chapter 4: Job Initialization

Introduction
The operating system requires certain
preliminary information about a job in
order ·to be able to process it. For
exampl,e, it must be able to recognize the
beginning and end of a job, and it requires
detail:s of the job environment (for
example, which control program is used).
Most of this information is provided in the
job control language: the remainder is
either information already known to the
operator because it is established for your
installation, or information you will have
to giv j 9 the operator for your particular
job. l?or example, if you have a choice o:f
control programs, you must tell the
operator which one you want.
The information given in the job control
languaqe is provided in the JOB statement
and its parameters. The JOB statement
indica1:es the beginning of a job and (in
batch processing) the end of a previous
job: the parameters provide information
about t,he job environment. Full details of
the purpose and syntax of this statement
are gi"en in IBM system/360 Operating
System:: Job Control -Language User's Guide"
and Jol? Control Language Reference. The
use of the JOB statement and its parameters
is described briefly here, together with
job scheduling and the types of control
program available.

JOB Statement
The JOB statement is always the first
statemEmt in your job. It identifies the
job to the operating system; in particular,
i t identifies the job to the job scheduler
so that~ the latter can begin job
processing. The job scheduler has three
main components:
1.

2.

Re!ader/interpreter: This checks the
job control language and (if required)
'st~ores the data from the input stream
on a direct-access device and places
control information about the job in
ant input queue.
Indtiator/terminator: This selects the
n€!xt job step for execution, and
allocates devices and resources.
After processing, i t terminates the
job step. After processing of the
last job step, it terminates the job.

3.

Output writer (MFT or MVT): This
handles the transmission of data from
output data sets to a system output
device (such as a printer or a
card-punch) •

The JOB statement also provides
information on:
1.

Work control; for example, accounting
information and the programmer's name.

2.

Job environment; for example,
information relating to the control
program under which the job will be
executed.

..

Note that the JOB statement does not select
the control program for you; i t merely
allows you to specify information required
by the control program yOu are using_ The
information to be given in the job
statement fields is described below.

Name Field
A valid job name must appear in this field.
certain words must not be used as job names
as they are command statements used by the
operator to communicate with the operating
system. Examples of these are SPACE and
JOBNAMES; ,you must find out whether these
or other names are used as command
statements at your installation.
Jobs being executed concurrently should
have different job names.

Operation Field
The word JOB must appear in this field.

Operand Field
The full set of positional and keyword
parameters used with the JOB statement is:
positional
Accounting information
programmer's name
Chapter 4: Job Initialization

31

Keyword
CLASS
COND
MSGCLASS

Sequential scheduling
Each job is processed in the order in which
it exists in the input stream. Only one
job at a time can be processed; all other
jobs in the input stream must wait until
this job is finished. Each job is executE~d
as a single task.

MSGLEVEL
PRTY

sequential scheduling is used by the
primary control program (PCP).

REGION
ROLL
Priority Scheduling
TYPRUN
The use of these is discussed in the IBM
System/360 Operating System:. 'Job Control
Language.Reference.
Although all these parameters are
optional as far as the operating system is
concerned, some or all of them will be
mandatory at your installation, and some
will not be available to you. Therefore,
before using any of them, you need to know:
1.

Which parameters are mandatory at your
installation.

2.

Which parameters are optional at your
installation.

3.

What happens if you omit an optional
parameter that is required for a
particular job. If there is no
default for this parameter, the job
could terminate at this point.

4.

What happens if you include an
optional parameter that is no·~
required for a particular job. The
parameter might be ignored or the job
could terminate.

Note: The examples given in this manual
omi t the parameters of the JOB sta'tement
because of this installation dependence.

Job Scheduling
JOB SCHEDULING AND THE CONTROL PROGRAM
The operating system uses one of two forms
of scheduling to process your job:
sequential scheduling or priority
scheduling. The type of scheduling
employed for your job depends on the
control program used.
32

The jobs in the input stream are placed in
input queues and selected for processing
according to previously determined
priorities. Jobs are processed in a
multiprogramming environment, that is,
several jobs can be processed concurrently.
Each job step can be executed as a single
task or as several tasks:
1.

One job step, one task: Each job step
is executed as a task. The number of
tasks that can exist concurrently is
fixed, and is restricted to the number
selected for execution (that is, tasks
cannot be created during execution of
the job step).
Jobs are processed in this way with
the MFT (multiprogramming with a fixed
number of tasks) control program.

2.

One .job step,' several tasks: Each job
step is executed as a task.
Additional tasks (subtasks) can be
created dynamically during execution
of the job :step. Therefore the numb4er
of tasks that can exist qoncurrently
is variable, and depends on the number
of subtasks created.
Jobs are processed in this way with
the MVT (multiprogramming with a
variable number of tasks) control
program.

Control Program
The three control programs currently
available in the operating system are:
PCP
MFT
MVT

Your installation may have only one of
these control programs" or it may have two
or all of them. You must find out which
control program or programs are available
to you and design your source program
accordingly. To assist you in the choice
(if you have one), a brief description of
each c~ont rol program is given below,
together with the set of JOB statement
paramE~ters applicable to that program.
FurthE!r details of the control programs are
contained in the following publications:
IBM .System/360 operating System:
cOlncepts and Facilities
QJ2lerator'. s Reference

QE,erator's Procedures

scheduler task. These job steps are
executed sequentially.

Output
System output is put out through the SYSOUT
stream; problem program output can be put
out through the SYSOUT stream or a user
data set. Up to eight output writers are
available: each one writes one class of
output onto one device (such as a printer).
Each output class is designated by one of
the letters A through Z•. Class A is the
standard system output class: there must
always be a device available for this
class.

storage Estimates
MFT CONTROL PROGRAM
PRIMARY CONTROL PROGRAM (PCP)
JOB Statement Parameters

JOB Statement Parameters
Accounting information
Programmer's name

Accounting information
CLASS
Programmer's name
COND
COND
MSGCLASS
MSGLEVEL
Z.:SGLEVEL
PRTY
'l~RUN

The jolb stream is read in from a card or
tape d l 9vice, and is loaded into main
storagca. Only one input reader is
available at one time.

Job Selection
Only one job can be processed at a time.
The whole of main storage and all resources
are allocated to that job; no other job can
qain control until this job has completed
execution.

The job stream is read from a card or a
tape device., or from a direct-access
device, and is stored on a direct-access
device. If there is any error in the job
control statements for a job, that job is
terminated. Up to three input readers are
available.

Job Selection
Task EJtecution
The job scheduler programs are executed as
tasks: each job step of the job to be
processed is executed as part of a job

Jobs are placed in an input queue: up to
fifteen input queues are available. The
queue selected depends on the job class, as
specified in the CLASS parameter of the JOB
statement. A job is placed in an input
queue according to its priority, as
Chapter 4: Job Initialization

33

specified in the PRTY parameter of the JOB
statement.
A job with the highest priority is
placed at the head of the queue; tha't with
the lowest at the end. A job with a
plriori ty the same as a job already i:n the
q~eue, is placed immediately behind ,that
job.
If a job is not given a priority, a
default priority is given to it by the
system, and it is placed in an input queue
at the appropriate place.
In MFT, main storage is divided into
partitions. One partition is allocated to
one job at a time. Partitions are
independent units of main storage. The
work being done in one partition cannot
affect work being done in another
partition: data cannot be left in a
partition for use by the next job st.ep to
be loaded.

I
I

Up to fifteen partitions are available
for user jobs (there are other partitions
but they are not available to you):
therefore up to fifteen jobs can be
processed concurrently. The number of
partitions at a given time" and the size of
each one, may be fixed for a particu.lar
installation, but usually both the numbe]:'
and size can be selected by the operator.
The minimum size of a user partition is 8K
bytes. You must find out the conventions
on partitions at your installation.
Partitions are arranged in order of
priority. The partition with the highest
main-storage address has the highest
priority; partitions with successively
lower addresses have successively lower
priorities. A task is the work executed in
a particular partition. Partitions, not
job steps, compete for control; if a job
step enters a wait state or completes
execution, control passes to the partition
waiting with the highest priority. Neither
job class nor job priority have any affect
on competition between tasks for control.
The selection' (by the initiator) of jobs
for execution depends on the relationship
between the partitions and the input queues
(that is, the job classes). A partition
can service up to three job classes: a job
class can be allocated to more than one
partition. If a partition services more
than one job class, it searches those
classes for jobs in a predetermined order.
For example:
Partitions: Highest priority
Lowest priority
34

PO
Pi
P2
P3

Class

Job

Class

Job

Class

Job

A

1

B

1

C

1

2
3

2
3

2
3

Allocations:
Class A:

PO, Pi

Class B:

PO, Pi, P2

Class C:

P2, P3

Partition PO:

A"

Partition Pi:

A, B

Partition P2:

B C
"
C

Partition P3:

B

In this configuration, when the job step
in PO completes execution, class A is
searched to see if there are any jobs
waiting'for selection. If there are not,
class B is searched. Similarly Pi searches
A and then B, P2 searches B and then C, and
P3 searches C only., A job in class A can
be selected for PO or Pi, whichever is the
first 'available; a job in B can be selected.
for PO, Pi or P2, and a job in C for P2 or
P3.

Task Execution
Once a job has been selected for
processing~ its job steps are executed
sequentially. When a job step enters a
wait state, control passes to the job step
waiting in the next highest priority
partition, irrespective of the job class 01:
the waiting job step.

Other ,Considerations
Your installation may have the time-slicin9
facility.. Execution time is divided
('sliced') into a number of discrete
periods. One period is allocated to one
job, the next period to another job, and se)
on, among all the jobs to be processed.
The total execution time for one job is
interleaved with that for other jobs, and
thus all jobs are kept moving. Usually onE~
particular class is reserved for
time-sliced jobs; if your job is to be
time-sliced you must find out the
time-slicing class at your installation.
Similarly, if you use the TYPRUN parameter.,
one class may be reserved for jobs whose
processing is to be delayed.

If your installation has a shared PL/I
library, this could affect the amount of
space available in a partition or even the
parti ticm size .•

The job stream is read from a card or a
tape device p or from a direct-access
device, and is stored on a direct-access
device. If there are any errors in the job
control statements for a job, that job is
terminated. As many input readers as are
required can read input streams.

output
The output.stream from the job is stored
temporarily on a direct-access device. The
output data is stored in an output queue:
each mellilber of the queue is associated with
an output class, as designated in the
SYSOUT parameter. If system and problem
program data are in the same class, they
are placed in the queue member in the
order:
Syst.em messages at job initiation

Job Selection
Jobs are placed in a single input queue,
and are arranged within the queue according
to their priorities, as specified in the
PRTY parameter of the JOB statement.
A job with the highest priority is
placed at the head of the queue; that with
the lowest at the end. A job with a
priority the same as a job already in the
queue, is placed immediately behind that
job.

Problem program data
System messages at job termination
Up to 36 output queues are available. The
contents of each output class are written
out by a system output ,writer onto the
device (printer, punch, or tape) associated
with that class. Up to 36 system output
writers are available; each output writer
can service up to eight output classes.

MVT CONTROL PROGRAM

JOB statement Parameters
Accounting information
Programmer's name
CLASS
COND

MSGCLASS
MSGLEVEL
PRTY
REGION
ROLLTYPRUN

If a job is not given a priority, a
default priority is given to it by the
system, and it is placed in the input queue
at the appropriate place.
In MVT, main storage is divided into
regions. The amount of storage required
for a region is specified in the REGION
parameter. The number of regions that can
exist concurrently depends on the total
size of main storage and on the region
sizes specified. Each job is executed in
one region. Regions are independent units
of main storage; work being done in one
region cannot affect work being done in any
other region. Data cannot be left in a
region for use by the next job step to be
loaded.
A region is not a permanent division of
main storage. It exists only for the
duration of the job step for which it was
created. When a job is selected for
execution, a region is created for it. A
region does not have a priority and does
not compete for control with other regions;
such competition is between the tasks in
the regions.

The selection of jobs for execution from
the input queue depends on the job class
and priority. Jobs are queued in order of
priority or, if they have equal or no
priority, in order of arrival in the queue.
Job class has no affect on job position in
the input queue. Jobs are selected by one
of several initiators •. When an initiator
is allocated to a job class, it selects
Chapter 4: Job Initialization

35

only the jobs in that class: the order of
taking them is determined by the job
priority. An initiator can be allocated to
:more than one job class, and will search
the classes in predetermined ordero Up to
,fifteen job classes are available: the
:number of initiators depends on thE~ number
,of job classes allocated to each one.
,

For example, if there are three
initiators:
InitCA) for jobs in class

A

Init CB)

B

InitCC)

C

and there are eleven jobs in the input
queue as follows:
Job -Class

Priority

B
B
A
A
B
C
A
C
C
A
A

10
9
8
8
7
4

3
2

1
0
0

then, when the job scheduler requires the
next job for processing~ if InitCA) is the
first initiator to be given control, it
ignores the two B jobs at the head of the
queue and selects the first A8 job.. The
next time InitCA) receives control it
selects the second A8 job (assuminq the
contents of the queue have remained the
same) and so on through all the class A
·jobs: A3, AO, AO. When InitCA) cannot find
any jobs to select, InitCB) is given
control and selects the class B jobs in the
order: Bl0, B9, B7. Similarly, when
InitCC) receives control, it selects the
class C jobs in the order: C4, C2, Cl.
More than two initiators can run
together and one initiator can interrogate
more than one class depending on the
installation standards.

Each task competes for control with all the
other tasks being executed. Each task has
a limit priority that depends on:
1.

The value in the PRTY parameter in the
JOB statement.

2.

The value in the DPRTY parameter in
the EXEC statement for that job step ..

3.

If neither of these is specified, a
default value is supplied by the job
scheduler.

Each task also has a despatching
priority; this can be changed during
execution but cannot be greater than the
limit priority. The tasks compete for
control-on the basis of the current values
of their despatching priorities. Note that
in MVT a priority can be specified on the
EXEC statement; this does not affect the
sequential execution of the job steps in a
job but can affect considerably the chances
of an existing task gaining control.
Once a task is being executed, it can
create subtasks dynamically.A subtask has a
limit and despatching priority in the same
way as the originating task, and competes
for control with all the tasks and subtasks
being-executed.

Other-considerations
If your installation has the time-slicing
facility described above in 'MFT Control
Program,' note that usually one particular
priority is reserved for time-sliced jobs ..
Similarly, priorities are reserved for jobs
whose processing is delayed by'use of the
TYPRUN parameter; and for the message
control or message processing programs in
teleprocessing. You must find out the
conventions at your installation. If your
installation has a shared PL/I library,
this could affect the region size. Region
sizes can be affected during execution by
rollout/rollin.

Output
, Task', Execution
Once a job has been selected for
processing, its job steps are executed
sequentially: each job step is a task.
36

MVT output follows the same conventions as
those for MFT output. If your installaticm
has a universal character set CUCS) printc~r
that will be used as an output writer, you
must assign a separate output class to each
character set image in the system library.

Chapter 5:

Introdufction
The PL/:[ (F) compiler translates PL/I
source :3tatements· into machine
instructions. A set of machine
instrudtions suc~ as is produced by the
compiler is termed an object· module.
(If
appropriate control statements are inserted
among the PL/I source statements, the
compilelt:' can create two or more object
modules in a single run by means of batch
compilat.ion. )
Howe',er.. the compiler does not generate
all the machine instructions required to
repres~lt the source program; instead, for
frequenltly used standard routines such as
those that handle the allocation of main
storage space and the transmission of data
between main and auxiliary storage, it
inserts references to standard subroutines
that art? stored in the PL/I subroutine
library.. An object module produced by the
compileJ::- is not ready for execution until
the appJt"opriate library subroutines have
been included; this is the task of an
operating system service program, the
linkage editor or the linkage loader, which
is described in Chapter 6. A module that
has been processed by the linkage editor or
linkage loade~ is termed a load module.
While it is processing a PL/I source
program" the compiler produces a listing
that contains information about the source
program and the object module derived from
it, together 'with diagnostic messages
relatin~J to errors or other conditions
detected during compilation. Much of this
informat:ion is optional, and is supplied
only in response to a request made by
including appropriate 'options' in the PARM
parametE~r of the EXEC statement that
requests execution of the compiler.
The compiler also includes a facility,
the ~)rocessor or compile-time processor,
which ca.n modify the source statements or
insert additional source statements before
, compilat:ion commences.

COMPILATION
The compiler comprises a control module
that remains in main storage throughout
compilat:ion, and a series of subroutines·
(termed phases) that are loaded and
executed in turn under the supervision of

Compilation

the control module. Each phase performs a
single function or a set of functions, and
is loaded only if the services it provides
are required for a particular compilation.
The control module selects the appropriate
phases in accordance with the content of
the source program and the optional
compiler facilities that you select.
Figure 5-1 is a simplified flow diagram of
the compiler.
The data that is processed by the
compiler is known throughout all stages of
the translation process as text.
Initially, the text comprises the PL/I
source statements submitted by the
programmer; at the end of compilation, i t
compr~ses the machine instructions that the
compiler has substituted for the source
statements, to which is added some
reference information for use by the
linkage editor.
The source program must be in the form
of a data set identified by a DD statement
with the name SYSIN; frequently" the data
set is a deck of punched cards. The source
text is passed to the read-in phase either
directly or via one of two preprocessor
phases:

1.

If the source text is in the PL/I
48-character set, the 48-character-set
pr·ocessor translates it into the
60-character set. You must indicate
the need for translation by specifying
the CHAR48 option. 1

2.

If the source text contains
preprocessor statements, the
compile-time-processor phase executes
these statements in order to modify
the source 'program or introduce
additional statements. The
compile-time processor includes a
facility for translating statements
written in the 48-character set into
the 60-character set. To request the
services of the compile-time
processor, specify the MACRO option.

Both preprocessors place the translated
source text in the data set defined by a DD
statement with the name SYSUT3. The
read-in phase takes its input either from
this data set or from the data set defined
by the DD statement SYSIN. This phase
1The compiler options are discussed under
'Optional Facilities,' later in this
chapter.
Chapter 5: compilation

37

SOURCE TEXT
(FROM SYSIN)

CHAR 48

48-CHARACTERSET
PROCESSOR

CHAR60

PROCESSED SOURCE
TEXT VIA SYSUT 3

60 -CHARACTER-SET
TEXT VIA SYSUr 3

READ-IN
PHASE

~TlONARY
~HASE

~NSLATION
~HASES

FINALASSEMBLY
PHASE

OBJECT MODULE
(TO SYS LIN 0 R SYSPUNCH)

Lgure 5-1.
38

COMPILE TIME
PROCESSOR

pur (F) Compiler: Simplified Flow Diagram

check:s the syntax of the source statements
and rfemoves any comments and nonsignificant
blank characters.
Aft.er read-in, the dictionary phase of
the c()mpiler creates a dictionary that
contains entries for all the identifiers in
the source text. The compiler uses the
dictionary to communicate descriptions of
the eJLements of the source program and the
object: program between phases. The
dictionary phase of the compiler replaces
all iclentifiers and attribute declarations
in thE~ source text with references to
dictionary entries.
Translation of the source text into
machine instructions involves several
compil.er phases. The sequence of events
is:
1.

2.

RearJ;'angement of the source text to
f:acilitate translation (for example,
by replacing array or structure
a.ssignments with DO loops that contain
element assignments).
Conversion of the text from the PL/I
syntactic form to an internal
syntactic form.

relocation dictionary, and explains how the
linkage programs use them.

Job Control Language for Compilation
Although you will probably use cataloged
procedures rather than supply all the job
control statements required for a job step
that invokes the compiler, it is necessary
to be familiar with these statements so
that you can make the best use of the
compiler, and if necessary modify the
statements of the cataloged procedures.
The IBM-supplied PL/I cataloged
procedures for compilation are:
PL10FC

Compile only (object module on
punched cards).

PL1LFC

Compile only (object module
stored on magnetic-tape or
direct-access device).

PL1LFCL

Compile and link edit.

3.

Mapping of arrays and structures to
ensure correct boundary alignment.

PL1LFC~

Compile, link edit, and
execute.

4.

Translation of text into a form
similar to machine instructions; this
text form is termed pseudo-code.

PL1LFCG

Compile, load, and execute.

5.

S·torage allocation: the compiler makes
provision for storage for STATIC
v,ariables and generates code to allow
AUTOMATIC storage to be allocated
during execution of the object
p:cogram. (The PL/I library
subroutines handle the allocation of
storage during execution of the object
p:t:'ogram. )

The final-assembly phase translates the
pseudo··code into machine instructions, and
then creates the external symbol dictionary
(ESO) and relocation dictionary (RLD)
requirf:!d by the linkage programs. The
external symbol dictionary is a list that
includes the names of all subroutines that
are rejeerred to in the object module but
are "not. part of the module; these names,
which are termed external references,
includE~ the names of all the PL/I library
subroU't:ines that will be required when the
object program is executed. The relocation
dictionary contains information that
enable!.:; absolute storage addresses to be
assignE~d to locations within the object
module when it is loaded for execution.
Chaptel: 6 contains a fuller discussion of
the ext:ernal symbol dictionary and the

Chapter 8 describes these cataloged
procedures and how to modify or override
the statements they contain.
The following paragraphs describe the
essential job control statements for
compilation; they use statements from the
PL/I cataloged procedures as examples.
Appendix B contains a description of the
parameters of the DO statement that are
referred to.

EXEC STATEMENT
The basic EXEC statement is:
// EXEC PGM=IEMAA
By using the PARM parameter of the EXEC
statement you can select one or more of the
optional facilities offered by the
compiler; these facilities are described
later in this chapter. The use of the
other parameters of the EXEC statement is
as described in Chapter 7, 'Ex~cuting the
Load Module'.
Chapter 5: Compilation

39

r-------------------------------------------------------T---------------T---------------,
I
Purpose
I
ddname
I Associated
I
I

I

ICompiler Option I
~-------------------------------------------------------+---------------+---------------~
Primary input (PL/I source statements)
SYS:IN
Punched card output

SYSPUNCH

DECK, MACDCK

Load module output

SYSLIN

LOAD

To contain overflow from main storage

SYSUTl

storage for:

SYSUT3

1.

Converted source module when 48-character set
used

CHAR48

2.

Source statements generated by preprocessor

MACRO, COMP

Listing

SYSPRINT

Library containing source statements for insertion by

SYSLIB

MACRO

L ________________________________________________________
~ _______________ ~ _______________ J
preprocessor

Figure 5-2.

Standard Data Sets for Compilation

DD STATEMENTS
The compiler requires several standard data
sets, the number depending on the optional
facilities that you request. You m~~t
define these data sets in DD statements
with the standard names listed in Figure
5- 2. The DD sta tements SYSIN and SYSPRINT
are always required, and you should take
uhe precaution of including SYSUTl in case
insufficient main storage is available to
the compiler. In addition, if you specify
any of the options listed in Figure 5-2,
you must include the associated DD
statement.
Figure 5-3 summarizes the
characteristics of the compiler data sets.
You can place any of them on a
direct-access device; if it is likely that
you will do so, include the SPACE parameter
in the DD statements that define the data
sets. The amount of storage space
allocated in the standard cataloged
procedures (Chapter 8) should suffice for
most applications; however, Appendix H
explains how to calculate the requirements
for auxiliary storage.

Primary-Input

(SYS~N)

The primary input to the compiler must l~ a
CONSECUTIVE data set containing PL/I source
statements. These source statements must
comprise one or more external procedures;
if you want to compile more than one
external procedure in a single run, you
40

must separate the procedures in the input
data set with *PROCESS statements
(described under 'Batched Compilation'
later in this chapter)~
Eighty-column punched cards are commonly
used as the input medium for PL/I source
programs. However, the input data set may
be on a direct-access device, magnetic
tape, or paper tape. The data set may
contain either fixed-length records,
blocked or unblocked, or undefined-length
records; the maximum record size is 100
bytes. The compiler always reserves 1000
bytes for two buffers for this data set;
however, you may specify a block size of
more than 500 bytes providing sufficient
space is available to the compiler. (Use
the SIZE option to allocate the additional
space: refer to 'Optional Facilities,'
later in this chapter.)
The standard PL/I cataloged procedures
do not include a DD statement for the inpuit.
data set; consequently, you must always
provide one. The following example
illustrates the s·tatements you might use bo
compile., link-edit, and execute a PL/I
program placed in the input stream:
//COLEGO JOB
// EXEC PL1LFCLG
//PL1L.SYSIN DD •
Insert here the source statements of
your PL/I program
/*

Chapter 8 describes how to add DD
statements to a cataloged procedure.

Note

r---------T--------------------T-----------~----------T-----------T-----------T-----------,
ddnamE~ I
Possible Device
I Record
IRecord Sizel Default I Reserved I No. of I
classes~
I Format
I (bytes) IBlock Size IBuffer Areal Buffers I
I

I
I
I

I

I

I

I

(bytes)

I

(bytes)

I

I

~-------,-+--------------------+-----------+-----------+-----------+-----------+---------~
SYSlN

SYSSQ or input job
streamCspecified
by DD *)

F, FB, U

SYSPUNCH SYSSQ, SYSCP

F,FB

SYSLlN

SYSSQ

F,FB

SYSUTl

SYSDA

F

SYSUT3

SYSSQ

F, FB, U

i 100 (max) I
I
I
I
t

1000

2

SO

SO

400

1

SO

SO

400

1

1024
160

SO

SYSPRlNT SYSSQ or. SYSOUT
device

V, VB

125

SYSLlB ' SYSDA

F, FB, U

100 (max)

~--_----_i--------------------~~----------~-----------~--

25S

129

2

_________ ___________ _________
~

~

~

Magnetic-tape or direct-access device
I
I
I SYSCP Card punch
JI
SYSDA Direct-access device
IL_______________________________________________________________________________________
I~SYSSQ

Figure 5--3.

Characteristics of compiler Data Sets

that you must qualify the name of the added
DD statelrnentwith the name of the job step
within the cataloged procedure to which it
refers C:in this example, PL1L).

is to be routed via the system output
device of class B, which is usually a card
punch.
(However, the DD statement SYSPUNCH
need not refer to a card punch.)

Output (SYSPUNCH,SYSLIN)

The other cataloged procedures that
include a compilation job step contain the
following DD statement:

The complIer places the object module in
the data set defined by the DD statement
SYSLIN if you specify the option LOAD, and
in the da.ta set defined by SYSPUNCH if you
include 1:he option DECK; you may specify
both options in one program. The object
module is in the form of SO-byte
fixed-length records, blocked or unblocked.
The compiler always reserves 400 bytes for
buffers for each of the output data sets;
however, you may specify a block size of
more than 400 bytes providing sufficient
space is available to the compiler~ (Use
the SIZE option to allocate the additional
space: refer to 'Optional Facilities',
later in this chapter.)
The cataloged procedure PL1DFC includes
the DO st:atement
//SYSPUNCH 00 SYSOUT=B
'I'his stat.ement specifies that the data set
~The

E-I€!vel linkage editor does not accept
blocked records; specify blocked records
for SYSLIN only if you are using the
F-Ievel linkage editor.

//SYSLlN DD DSNAME=&&LOADSET,
//
DlSP=(MOD,PASS),
//
UNlT=SYSSQ,
//
SPACE=(SO,(250,100»
This statement defines a temporary data set
named &&LOADSET on a magnetic-tape or
direct-access volume; if you want to retain
the object module after the end of your
job, you must substitute a permanent name
for &&LOADSET (i.e., a name that does not
commence &&) and specify KEEP in the
appropriate DlSP parameter for the last
step in which the data set is used. The
term MOD in the DlSP parameter allows the
compiler to place more than one object
module in the data set, and PASS ensures
that the data set will be available to the
next job step (link-edit) providing a
corresponding DD statement is included
there. The SPACE parameter allows an
initial allocation of 250 eighty-byte
records and, if necessary, 15 further
allocations of 100 records (a total of 1750
records, which should suffice for most
applications).
Chapter 5: Compilation

41

Workspace. '(SYSUT1,' SYSUT3)
The compiler may require two data sets for
use as temporary workspace. They are
defined by DD statements with the names
SYSUT1 and SYSUT3.
SYSUT1 defines a data set, known as the
spill file, which the compiler uses for
overflow text and dictionary blocks when
compiling large source programs or when
less than 57,344 bytes (56K bytes) of main
storage are available for compilation.
This data set must be on a direct-access
device.
It is good practice to include
this DD statement even when you use the
SIZE option to allocate more than 56K bytes
to the compiler. The cataloged procedures
include the following (or a similar)
statement:
//SYSUT1 DD UNIT=SYSDA,
//
SPACE=(1024,(60,60)"CONTIG),
//
SEP=(SYSUT3,SYSLIN)
Although the SEP parameter is not
essential, its employment increases the
efficiency of access to the compiler da"ta
sets. You should never need to modify this
DD statement.
The compiler requires the data set
defined by SYSUT3 only when you use the
48-character set or when you employ the
preprocessor. In each case, the compiler
places the processed text on this data set
before commencing compilation proper. All
the cataloged procedures use the following
DD statement:
//SYSUT3 DD UNIT=SYSSQ,
//
SPACE=(80,(250,250»,
//
SEP=SYSPRINT
Note that if a job being run under MVT
has a number of job steps, and each job
step requires a data set for use as
temporary workspace, the result is a
considerable overhead in time and space.
To reduce this as far as possible, you can
use dedicated workfiles. These are
workspace data sets which are created by
the initiator when the job is selected for
execution. They can be used by each job
step (in the job selected) that requires
temporary workspace; they are dele-ted when
the job is terminated.

data set. For example, if an initiator has
three dedicated workfiles as follows:
//SYSUT1
//SYSUT2
//SYSUT3

DD
DD
DD

(parameters)
(parameters)
(parameters)

then, if you want the workspace for the
SYSUTl and SYSUT3 data sets in a job step
to be provided by the initiator workfiles,
code:
//SYSUTl
//SYSUT3

DD
DD

DSNAME= '& &SYSUT1, •••
DSNAME=&&SYSUT3, •••

The result is that this job step uses
dedicated workfiles as workspace; the
SYSUT1 and SYSUT3 DD statements in your job
stream are ignored. The IBM-supplied
cataloged procedures for PL/I include
SYSUT1 and SYSUT3 DD statements with a
dsname specified in this way.
There are several restrictions on the
substitution.of dedicated workfiles for
workspace data sets in the job stream; for
example. only direct-access devices are
supported.
You should consult your system
programmer on the conventions and
restraints that apply·at your installation
to each type of workspace data set.

Listing (SYSPRINTl
The compiler generates a listing that
incl udes all the source statements that it~
processed, information relating to the
object module, and, when necessary,
diagnostic messages. Most of the
information included in the listing is
optional, and you can specify those parts
that you require by including the
appropriate compiler options. The
information that ma.y appear, and the
associated options, are described under
'Listings', later in this chapter.
You must define the data set on which
you wish the compiler to place its listing
in a DO statement named SYSPRINT. The da"t:a
set must have CONSECUTIVE organization.
Although the listing is usually printed, it
can be written on any magnetic-tape or
direct-access device,. For printed output I'
the following statement will suffice:
//SYSPRINT DD SYSOUT=A

To use dedicated workfiles in your job,
you must first make sure that your
installation has an initiator that can
generate them. If it has, you can use
these workfiles by specifying the ddname of
the initiator workfile as the dsname of the
workspace data set in your job stream; this
data set must be specified as a temporary
42

The compiler always reserves 258 bytes
for buffers for the data set defined by the
DO statement SYSPRINTi however, you may
specify a block size of more than 129 bytc:!s
provided sufficient main storage is
available to the compiler.
(Use the SIZE
option to allocate the additional main

storage: refer to 'Optional
later in this chapter.)

Facilities'~

single quotation marks1: for example:
//EXEC PGM=IEMAA,PARM='SIZE=72K,LIST'

Source

s~atement

Library' '(SYSLIB)

If you use the preprocessor %INCLUDE
statement to introduce source statements to
your program from a library, you can eithe:t"
define the library in a DD statement with
the name SYSLIB, or you can choose your own
ddname (or ddnames) and specify a ddname in
each %INCLUDE statement.
(Refer to
'Compile'-Time Processing', later in this
chapter.) The DD statement SYSLIB is not
included in the compilation job step of the
standard cataloged procedures (and it has a
differen't, function in the link-edit step) ..
Note that for SYSLIB, the maximum record
size pennit,ted is 100 bytes and the maximum
block si:!!:e is 500 bytes.

The length of the option list must not
exceed 100 characters, including the
separating commas: however, many of the
option keywords have an abbreviated form
that you can use to save space. You may
specify the options in any order.
If you are using a cataloged procedure,
you must include the PARM parameter in the
EXEC statement that invokes the procedure
and qualify the keyword with the name of
the procedure step that invokes the
compiler 1 for example:
// EXEC PL1LFCLG,PARM.PL1L=('SIZE=100K',
//
L,E,A)
The compiler options are of two types:
1.

Simple pairs of ke¥words: a positive
form (e.g., LOAD) that requests a
facility, and an alternative negative
form (e,.g. " NOLOAD) that rejects that
facility.

2.

Keywords that permit you to assign a
value to a function (e.g., SIZE=56K).

EXAMPLE
The following example is a typical sequence
of job control statements for compiling a
PL/I prompilation will provide a more
efficient use of main storage but
might result in the spilling of text
blocks (and the production of message
IEM3898I)
4.

The compiler reserves part of the main
stol:'age available to it for use as
data set buffers (intermediate storage
areas for data transmitted between
main and auxiliary storage). The
compiler uses one buffer each for the
data sets defined by SYSLIN and
SYSPUNCH, and two buffers each for
SYSPRINT and SYSIN; in each case, the
sizE~ of the buffer is equal to the
block size of the corresponding data
set. If you specify a block size for
any of the data sets that requires
morE~ buffer space than the compiler
normally reserves, you should allow
for the extra space in your SIZE
opti.on by adding the following
quantities to the 44K bytes minimum
required by the compiler:
(2
(2

*'
*

SYSIN block size) - 1000 bytes
SYSPRINT block size) - 258 bytes

SYSPUNCH block size - 400 bytes
SYSLIN block size - 400 bytes
5.

The text block size determine~ the
total number of pairs of parentheses
used for factoring attributes in a
DECLARE sta tement:

The OPT option specifies the type of
optimization required:
OPT=O instructs the compiler to keep
object-program storage requirements
to a minimum at the expense of
object-program execution time.
OPT=l causes object-program execution
time to be reduced at the expense
of storage.
OPT=2 has the same effect as OPT=l, and
in addition requests the compiler
to optimize the machine
instructions generated for certain
types of DO-loops and expressions
in subscript lists. IBM System/360
Operating-System:PL/I (F) Language
Reference Manual includes a
discussion of DO-loop and
subscript-expression optimization.
There is little difference in
compilation time for optimization levels 0
and 1, but specifying OPT=2 could result in
a substantial increase in compile time.

STMT,or NOSTMT
The STMT option requests the compiler to
produce additional instructions that will
allow statement numbers from the source
program to be included in diagnostic
messages produced during execution of the
compiled program.
The use of this option causes
degradation of execution time. However
you can get information about statement
numbers and their associated offsets by
referring to the TABLE OF OFFSETS.
(See
'Options Used for the Compilation,' below.>
Chapter 5: Compilation

45

reduces compilation speed, specify this
option only when the source module cannot
be compiled with the standard dictionary.
The OBJNM option allows you to name the
load module that will be created by the
linkage editor from the compiled object
module. (If you do not specify a name, the
linkage editor will use the member name
from the DSNAME parameter of the DD
statement SYSLMOD in the link-edit job
step; see Chapter 6.> The option causes
the compiler to place a linkage editor NAME
statement at the end of the object module.
The NAME statement has the effect of
assigning the specified name to the
preceding module when the module is
link-edited. The format of the option is
OBJNM=aaaaaaaa
where 'aaaaaaaa' represents a name
comprising not more than eight characters,
the first of which must be an alphabetic
character. The format of the resultant
NAME statement, which is described fully in
Chapter 6, is
~NAME~aaaaaaaa(R>

where

~

represents a blank character.

The principal purpose of the OBJNM
option is to facilitate the use of the
linkage editor to create a series of load
modules from the output of a batched
compilation. (Refer to 'Batched
compilation', later in this chapter.> You
can also use it to cause the linkage editor
to substitute the new load module for an
existing module of the same name in a
library.

Programs that are large enough to
require the EXTDIC option will be compiled
very much more quickly if a large storage
area is available. Ideally, enough storage
should be available to hold the dictionary
throughout compilation. As a rough
guideline, the SIZE option should specify
about 100,000 bytes plus 75 bytes for each
identifier in the source module. Do not
use the EXTDIC option when SIZE specifies
less than 47,104 bytes.
SYNCHKT" .SYNCHKS or SYNCHKE
This option specifies the conditions foz:'
termination after syntax checking if errors
are detected. The option has three valu.es
specifying termination according to the
severity of. errors.
SYNCHKE terminates compilation if errors
of severity ERROR or above are found during
the syntax checking stages of compilation.
SYNCHKS terminates compilation if errors
of severity SEVERE or above are found
during the syntax checking stages of
compilation.
With the SYNCHKS or SYNCHKE in effect., a
message is written to SYSPRINT stating:-'
'SYNTAX CHECK COMPLETED. COMPILATION
CONTINUES' or 'SYNTAX CHECK COMPLETED.
COMPILATION TERMINATED'
whichever is appropriate.

OBJIN' or OBJOUT
You must specify the option OBJIN if you
intend to execute the compiled program on
an IBM System/360 Model 91 or 195. The
special considerations for PL/I programs
executed on Models 91 and 195 are discussed
in Appendix G.

EXTDIC or NOEXTDIC
The EXTDIC option causes the compiler to
use a dictionary with a capacity of 1.5
times that of the normal dictionary if the
dictionary block size is 1K bytes" and 3.5
times that of the normal dictionary if the
block size is greater than 1K bytes. This
permits successful compilation of large
programs that would otherwise overflow the
dictionary capacity. As the use of EXTDIC
46

When using the value SYNCHKT compilat:ion
is terminated immediately an error of
severity TERMINATION is encountered durlng
the syntax check. In this case the synt.ax
check is not completed, and therefore no
special message is printed.
With SYNCHKT in effect the option is
effectively turned off, and no special
messages will be generated.

PREPROCESSOR OPTIONS
MACRO "or NOMACRO
Specify MACRO when you want to employ the
compiler preprocessor. The use of the
preprocessor is described under
'Compile-Time Processing,' later in this
chapter.

COMP or NOCOMP

SORMGIN

Specify this option if you want the PL/I
source module produced by the preprocessor
to be cClmpiled immediately. The source
module i.s then read by the compiler from
the data set identified by the DD statement
SYSUT3.

The SORMGIN (source margin) option
specifies the extent of the part of each
input record that contains the PL/I source
statements. The compiler will not process
data that is outside these limits. The
option can also specify the position of an
ANS carriage control character to format
the listing of source statements produced
by the compiler if you include the SOURCE
option. The format of the SORMGIN option
is:
'

MACDCR or.· NOMACDCR
SORMGIN=(mmm.nnn[,ccc])
specify "the option MACDCR if you want the
output from the preprocessor in the form of
a card deck. This output is written
(punched) in the data set specified by the
DD statement SYSPUNCH.

where mmm represents the number of the
first byte of the field that
contains the source statements

l•

nnn represents the number of the last
byte of the source statement
field, and
INPUT
CHAR60

Op~rIONS

If the P:L/I source statements are written
in the PI./I 60-character set. specify
CHAR60; if they are written in the
48-character set, specify CHAR48. IBM
system/360 operating.System:'PL/I (F)
Language· Reference Manual lists both
characte:r sets.
(Note that the compiler
will acc1ept source programs written in
either character set if you specify
CHAR48.)

BCD or

ccc represents the number of the byte
that will contain the control
character.

0~'CHAR48

EJ~CDIC

The compiler will accept source statements
in which the characters are represented by
either o:f. two codes; binary coded decimal
(BCD) and extended binary-coded-decimal
interchange code (EBCDIC). For binary
coded decimal, specify the option BCD; for
extended binary coded decimal interchange
code, spc~cify the option EBCDIC.
Whenever
possible t, use EBCDIC since BCD· requires
translation and is therefore less
efficien1t:. IBMsystem/360 Operating
System:PL/I (F). Language Reference Manual
lists thE;! EBCDIC representation of both the
48-character set and the 60-character set.
The 029 Keypunch punches characters in
EBCDIC~f()rm without multipunchingi to
obtain EBCDIC using the 026 you must
multipunch some characters.

The value mmm must be less than or equal
to nnn, and neither must exceed 100. The
value ccc must be outside the limits set by
mmm and nnn. The valid control characters
are:
b

o
+
1

Skip one line before printing
Skip two lines before printing
Skip three lines before printing
Suppress space before printing
Start new page

Chapter 11 contains a full description of
the use of printer control characters. If
you do not specify a position for a control
character, a default position defined by
your installation may apply.
You can
nullify this,default position by specifying
the carriage control character to be zero
(for example, SORMGIN=(1,72,0».
I f the value ccc is grea"ter than the
value set by the LRECL subparameter of the
DCB parameter, the compiler may not be able
to recognize it; consequently the listing
may not have the required format.
If the
character specified is not a valid control
character. a blank is assumed by default.
Source statements genera-ted by the
preprocessor always have a source margin
(2,72). Columns 73-80 contain information
inserted by the preprocessolC'; this
information is described under 'Listing,'
below.
Chapter 5: Compilation

47

OUTPUT OPTIONS

SOURCE or NOSOURCE

LOAD or NOLOAD

The SOURCE option requests a listing of ,the
PL/I source sta·tements processed by the
compiler,. The source statements listed ,are
either those of the original source program
or the output from the preprocessor.

The LOAD option specifies that the compiler
is to place the object module in the data
set defined by the DD statement.with the
name SYSLIN.

NEST· or NONEST
DECK or NODECK
The DECK option specifies that the compiler
is to place the object module, in the form
of 80-column card images, in the data set
defined by the DD statement with ·the name
SYSPUNCH. Columns 73-76 of each card
contain a code to identify the object
module: this code comprises the first four
characters of the first label in the
external procedure represented by the
module. Columns 77-80 contain a 4-digit
decimal serial number: the first card is
numbered 0001, the second 0002, etc.

LISTING OPTIONS
The listings produced by the compiler when
you specify the following options are
described under 'Listing' below.

LINECNT
The LINECNT option specifies the number of
lines to be included in each page of a
printed listing, including heading lines
and blank lines. Its format is:

The NEST option specifies that the source
program listing should indicate for each
statement,. the block level and the level of
nesting of a DO-group.

ATR or NOATR
The ATR option requests the inclusion in
the listing of a table of source program
identifiers and their attributes.
Attributes with a precision of fixed binary
(15.0) or less are flagged •••••••••• ,. An
Aggregate Length Table. giving the length
in bytes of all major structures and
non-structured arrays in the source
program, will also be produced when the ATR
option is specified.

XREF or NOXREF
The XREF option requests the inclusion i.n
the listing of a cross-reference table t~hat
lists all the identifiers in the source
program with the numbers of the source
statements in which they appear. If you
specify both A'l'R and XREF, the, two tablE~s
are combined. An Aggregate Lengh Table
will also be produced when the XREF opti.on
is specified.

LINECNT=xxx:
EXTREF or NOEXTREF
OPLIST or NOOPLIST
The OPLIST option requests a list: showing
the status of all the compiler options at
the start of compilation.

The EXTREF option requests the inclusion of
a listing of the external symbol dictionary
(ESD).

LIST or.NOLIST
SOURCE2 or NOSOURCE2
The SOURCE2 option requests a listing of
the PL/I source statements input to the
preprocessor.
48

The LIST option requests a listing of the
machine instructions generated by the
compiler (in a form similar to System/3fiO
assembler language instructions).

FLAGWo~

FLAGE or FLAGS

The diagnostic messages preduced by the
PL/I (F) cempiler are graded in erder ef
severity. The FLAG eptien specifies the
minimum level ef severity that requires a
message to. be printed:
FLAGW

List all diagnestic messages

FLAGE

I.ist all diagnestic messages
except 'warning' messages

FLAGS

List enly 'severe' errers and
'terminatien' errers

The sevcE~rity levels are discussed under
'Listin9,' belew.

The DUMP eptien requests a fermatted
listing en SYSPRINT ef the compiler
medules c, cempiler sterage. and cempiler
centrel blecks if an unreceverable errer is
enceuntE~red.
The DUMP eptien can also. be
used wit:h eptienal arguments; the nature
and purpese ef these arguments are
discussE~d in the publicatien IBM System/360
Operating system; PL/I. (F) Cempiler.
PregramLegic. Order No.. GY28-6800.
This facility she~ld enly be used in the
event ef: a cempiler failure.

Listing
During cempilatien. the cempiler generates
a listing that centains infermatien about
the cempilatien and about the seurce and
lead meClules. It places this listing in
the data set defined by the DD statement
SYSPRIN'I' (usually eutput to. a printer).
The fell.ewing descriptien ef the listing
refers t.e its appearance en a printed page ..
The l.isting cemprises a small ameunt ef
standarol infermatien that always appears,
tegether with these items ef eptienal
infermat.ien requested in the PARM parameter
ef the DD statement that inveked the
cempiler er that were applied by default.
Figure 5·-5 lists the eptienal cempenents ef
the list.ing and the cerrespending cempiler
eptiens.
The first page ef the cempiler listing
is identified by the cempiler versien
number and the eperating system release
number in the tep left-hand cerner, and by
the heading OS/360 PL/I COMPILER (F) in the

center. Starting'with thi.s page, all the
pages ef the listing are numbered
sequentially in the tep right-hand cerner.
On Page 1. immediately under the page
number, the date ef cempil.atien is recerded
in the ferm yy. ddd (yy=yea.r, ddd=day).
Page 1 also. includes a sta.tement ef the
eptiens specified fer the cempilatien,
exactly as they are written in the PARM
parameter ef the EXEC statement.
The listing always ends with a statement
that no. errers er warning cenditiens were
detected during the cempilatien er with ene
er mere di'agnestic messages. The fermat ef
the messages is described under 'Diagnestic
Messages,' be lew... If yeur machine includes
the timer featur.e, the listing cencludes
with a statement ef the CPU time taken fer
the cempilatien and the elapsed time during
the cempilatien; these times will differ
only in a multipregramming envirenment.
The fellewing paragraphs describe the
eptienal parts ef the listing in the erder
in which they appear. Appendix A includes
a fully annetated example ef a cempiler
listing .•
Listings

Optien Required

optiens for the
cempilatien

OPLIST

Preprecesser input

SOURCE 2

Seurce pre gram

SOURCE

Statement nesting level

NEST

Attribute table

ATR

Cress-reference table

XREF

Aggregate-length table

ATR er XREF

External symbol dictienary

EXTREF

Object medule

LIST

Diagnestic messages fer
severe errers, errers,
and warnings

FLAGS, FLAGE,
FLAGW

Figure 5-5.

Optienal Cempenents ef
Cempiler Listing

OPTIONS USED FOR THE COMPILATION
If the eptipn OPLIST applies, a cemplete
list ef the eptiens fer the cempilatien.
including the default eptiens, fellews the
statement ef the eptiens specified in the
EXEC statement. This infermatien appears
twice, the secend list being in a standard
Chapter 5: cempilatien

49

format to facilitate the automatic
collection of operating-system usage
statistics.

Column
73-77

Input line number from which the
source statement was generated.
This number corresponds to the
line number in the preprocessor
input listing.

78,79

Two-digit number giving the
maximum depth of replacement for
this line. If no replacement
occurred, the columns are blank.

PREPROCESSOR INPUT
If both the options MACRO and SOURCE2
apply, the compiler lists the input
statements to the preprocessor, one record
per line. The lines are numbered
sequentially at the left.
If the compiler detects an error or the
possibility of an error, during the
preprocessor phase, it prints a message on
the page or pages following the input
listing. The format and classification of
the error messages are exactly as described
for the compilation error messages
described under 'Diagnostic Messages,'
below.

80

tE' signifies that an error
occurred while replacement was
being attempted.
If no error
occurred, the column is blank.

Statement Nesting-Level
If the options SOURCE and NEST apply, the
block level and the DO level are printed to
the right of the statement number under
appropriate headings:
STMT LEVEL NEST

SOURCE PROGRAM
If the option SOURCE applies, the compiler
lists the source program input, one record
per line; if the input statements include
carriage control characters, the lines will
be spaced accordingly. The statements in
the source program are numbered
sequentially by the compiler, and the
number of the first statement in the line
appears to the left of each line in which a
statement begins. The statements contained
within a compound (IF or ON) statement are
numbered as well as the compound statement
itself; and, when an END statement closes
more than one group or block, all the
implied END statements are included in the
count:
1
2

3
4
5
6

P: PROC:
X: BEGIN;
IF A=B
THEN A=l:
ELSE DO;

A=O;

7
8

10
11

C=B;
END X;
D=E;
END:

If the source statements were generated
by the preprocessor, colUmns 73-80 contain
the following information:

50

1
2
3
4
5
6
7
8
9

1
2
2
2
2
3
2
1

1
2
1

1
1

A: PROC O~IONS(MAIN);
B: PROC(L);
DO 1=1 TO 10;
DO J=l TO 10;
END:
BEGIN;
END;
END B:
END A:

ATTRIBUTE AND CROSS-REFERENCE TABLE
If the option ATR applies, the compiler
prints an attribute table containing an
alphameric list of the identifiers in the
program together with their declared and
default attributes. If the option XREF
applies, the compiler prints a
cross-reference table containing an
alphameric list of the identifiers in the
program together with the numbers of the
statements in which they appear.
If both
ATR and XREF apply, the two tables are
combined.
Except for file attributes, the
attributes printed will be those that
obtain after conflicts have been resolved
and defaults applied. Since the file
attribute analysis does not take place
until after the attribute list has been
prepared, the attributes that appear in the
list for a file are those supplied by you"
regardless of conflicts.

If either of the options ATR and XREF
applies, the compiler also prints an
aggregat;e-Iength table, which gives, where
possible, the lengths in bytes of all major
structures and all non-structured arrays in
the progrram.

Attribut~e

of an ALLOCATE statement for the aggregate.
An entry appears for every ALLOCATE
statement involving a CONTROLLED aggregate,
since such statements have the effect of
changing the length of the aggregate during
execution. Allocation of a BASED aggregate
does not have this effect, and only one
entry, which is that corresponding to the
DECLARE statement, appears.

Table

If an identifier was declared explicitly,
the number of the DECLARE statement is
listed under the heading DCL NO.. The
statement numbers of statement labels and
entry laLbels are also given under this
heading.
'l'he attributes INTERNAL and REAL are
never included; they can be assumed unless
the respective conflicting attributes
EXTERNAI, and COMPLEX appear.
For'a: file identifier, the attribute
EXTERNAL appears if it applies; otherwise,
only explicitly declared attributes are
listed.
E'or an array, the dimension attribute is
printed first; the bounds are printed as in
the array declaration, but expressions are
replaced by asterisks.
For a. character string or a bit string,
the length preceded by the word • STRING, ,
is print.ed as in the declaration, but an
expression is replaced by an asterisk.

Cross .... Re~ference Table
If the cross-reference table is combined
with the~ attribute table, the numbers of
the statements in which an identifier
appears follow the list of attributes for
. that identifier. The number of a statement
in which a based variable identifier
appears will be included, not only in the
list of statement numbers for that
variable~, but also in the list of statement
numbers for the pointer associated with ito

The length of an aggregate may not be
known at compilation, either because the
aggregate contains elements having
adjustable lengths or dimensions, or
because the aggregate is dynamically
defined.
In these cases, the word
'ADJUSTABLE' or 'DEFINED' appears in the
LENGTH IN BYTES column.
An entry for a COBOL mapped structure,
that is,. for a structure into which a COBOL
record is read or from which a COBOL record
is written, has the word '(COBOL)'
appended, but such an entry will appear
only if the structure does not consist
entirely of:
1.

doubleword data, or

2.

fullword data, or

3.

halfword binary data, or

4.

character string data, or

5.

aligned bit string data, or

6.

a mixture of character string and
aligned bit string data.

If a COBOL entry does appear it is
additional to the entry for the PL/I mapped
version of the structure.
STORAGE REQUIREMENTS
If the option SOURCE applies, the compiler
lists the following information under the
heading STORAGE REQUIREMENTS on the page
following the end of the aggregate-length
table:
1.

The storage area in bytes for each
procedure.

Aggregat.e Length Table

2.

The storage area in bytes for each
BEGIN block.

Each ent.ry in the aggregate-length table
consists: of an aggregate identifier
preceded by a statement number and followed
by the length of the aggregate in bytes.

3.

The storage area in bytes for each ON
unit.

4.

The length of the program control
section (CSECT). The program control
section is the part of the object
module that contains the executable
part of the program.

'l'he s·tatement number is the number
either of the DECLARE statement for the
aggregat.e or, for a CONTROLLED aggregate,

Chapter 5: Compilation

51

5.

The length of the static internal
control section. This control section
contains all storage for variables
declared STATIC INTERNAL.

TABLE OF OFFSETS
If the options SOURCE, NOSTMT, and NOLIST
apply, the compiler lists, for each primary
entry point, the offsets at which the '
various statements occur. This information
is found, under the heading TABLE OF
OFFSETS AND STATEMENT NUMBERS WITHIN
PROCEDURE, following the end of the storage
requirements table.

LD - Label definition: the name of
an entry point to the
external procedure other than
that used as the name of the
program control section.
ID - Four-digit hexadecimal number: the
entries in the ESO are numbered
sequentially, commencing from
0001.
AODR - Hexadecimal representation of the
address of the symbol: this field
is not used by the compiler, since
the address is not known at
compile time.
LENGTH - The hexadecimal length in bytes of
the control section (SO, CM, and
PR entries only).

EXTERNAL SYMBOL OICTIONARY
If the option EXTREF applies, the compiler
lists the contents of the external symbol
dictionary (ESO) for the object module.
The ESO is a table containing all the
external symbols that appear in the module.
(The machine instructions in the object
module are grouped in blocks called control
sections; an external symbol is a name that
can be referred to in a control section
other than the one in which it is defined.>
The information appears under the following
headings:
SYMBOL - An 8-character field that
identifies the external symbol.

Standard.ESD Entries
The external symbol dictionary always
starts with seven standard entries (Figw~e
5-6):
1.

Name of the program control section
(the control section that contains t.he
executable instructions of the object
module). This name is the first label
of the external procedure statement ..

2.

Name of the static internal control
section (which contains storage for
all variables declared STATIC
INTERNAL). This name is the first
label of the external procedure
statement, padded on the left with
asterisks to seven characters if
necessary. and extended on the right:
with the character A.

3.

IHEQINV: pseudo-register for the
invocation count (a count of the
number of times a block is invoked
recursively) ..

4.

IHESADA: entry point of the library
routine that obtains automatic storage
for a block.

5.

IHESAOB: entry point of the library
routine that obtains automatic storage
for variables whose extents are not
known at compile time.

6.

IHEQERR: pseudo-register used by
library error-handling routines.

7..

IHEQTIC: pseudo-register used by thE!
library multitasking routines.

TYPE - Two characters from the following
list to identify the tYPE! of ESD
entry:
SD - Section definition: the name
of a control section within
this module.
CM - Common area: a type of
control section that contains
no executable instructions.
The compiler creates a common
area for each non-string
element variable declared
STATIC EXTERNAL without the
INITIAL attribute.
ER - External reference: an
external symbol that is not
defined in this module.
PR - pseudo-register: a field in a
communications area, the
pseudo-register vect:or (PRV),
used by the compiler and the
library subroutines.

52

thE~

r-'----------------------------------,
SYMBOL
TYPE
IO
ADOR
LENGTH I
FIGS

SO

0001

000000

00033A

***FIG5A

SO

0002

000000

00005F

IHEQINV

PR

0003

000000

000004

IHESAOA

ER

0004

000000

IHESADB

ER

0005

000000

IHEQERR

PR

0006

000000

compiler. If the number of blocks
exceeds the number of characters in
the first table, the first character
of the pseudo-register name is
replaced by a character taken from the
second table, and the last character
recycles. If the first character thus
overwritten is the start of the
external procedure name rather than an
asterisk, the compiler issues a
warning message (since identical
pseudo-register names could be
generated from different procedure
names) •

I

000004

IHEQTIC
PR
0007 000000 000004 J
L_.
___________________________________
Fitgure 5-6.

These pseudo-registers are termed
display pseudo-registers.

Typical standard ESO
Entries

Example:
Other ESO Ent ries

X: PROC:
Y: PROC:
Z: BEGIN;

The rema1n1ng entries in the external
symbol dictionary vary, but generally
include the following:
1.

2.

END X:

The display pseudo-registers for X, Y,
and Z would have the names:

section definition for the 4-byte
control section IHEMAIN, which
contains the address of the principal
entry point to the external procedure.
This control section is present only
if the procedure statement includes
the option MAIN.
section definition for the control
section IHENTRY (always present).
EXf:!cution of a PL/I program always
starts with this control section,
which passes control to the
appropriate initialization subroutine
of the PL/I library: when
initialization is complete, control
passes to the address stored in the
control section IHEMAIN.
(Initialization is required only once
dwring the execution of a PL/I
program, even if it calls another
external procedure: in such a case,
control passes directly to the entry
point named in the CALL statement, and
noit to IHENTRY.)

3.

LO···type entries for all names of entry
points to the external procedure
except the first.

4.

A JPR-type entry for each block in the
compilation. The name of each of the
pseudo-registers comprises the first
label of the external procedure
statement, padded on the left with
as·terisks to seven characters if
necessary, and extended on the right
wi't:h an eighth character selected from
one of two tables used by the

*·.··.XB·
······xo
···*··XC

5.

ER-type entries for all the library
routines and external routines called
by the program. The list includes the
names of. library routines called
directly by compiled code (first-level
routines), and the names of routines
that are called by the first-level
routines.

6.

CM-type entries for non-string element
variables declared STATIC EXTERNAL
without the INITIAL attribute.

7.

sO-type entries for all other STATIC
EXTERNAL variables and for EXTERNAL
file names.

8.

PR-type entries for all file names.
For EXTERNAL file names, the name of
the pseudo~register is the same as the
file name: for INTERNAL file names,
the compiler generates names as for
the display pseudo-registers.

9.

PR-type entries for all controlled
variables. For external variables,
the name of the variable is used for
the pseudo-register name: for internal
variables, the compiler generates
names as for the display
pseudo-registers.
Chapter 5: Compilation

53

DC
DC
DC
DC
DC
DC
DC

STATISTICS
If the option SOURCE applies, the compiler
lists the following information after the
ESD (or, if the option NOEXTREF applies,
after 'storage Requirements'):
1.

Number of records processed by the
preprocessor (MACRO records).

2.

Number of records processed by the
compiler.

3.

Number of statements processed by the
compiler.

4.

Size of object module (in bytes).

OBJECT MODULE
If the option LIST applies, the compiler
generates a map of the static internal
control section and lists the machine
instructions of the object program in a
form similar to System/360 assembler
language. The machine instructions are
described in IBM System/360: Principles of
operation. The following descriptions of
the object module listings include many
terms that can be properly defined only in
the context of an explanation of the
mechanism of compilation and the structure
of the object program: such an explanation
is beyond the scope of this manual.
Both the static internal storage map and
the object program listings start on a new
page. If the LINECNT option specifies 72
or fewer lines per page and the number of
lines to be printed (including skips)
exceeds the specified line count,
double-column format is used. If the
LINECNT option specifies more than 72 lines
per page or the number of lines to be
printed (including skips) is less than the
specified line count, single-column format
is used.

AL4(SI.+X'6000'}
AL4 (SI. +X'7000")
VL4 ( IHESADA)
VL4(IHESADB)
A(DSASUB)
A(EPISUB)
A(IHESAFA)

SI. is the address of the static
internal control section, and IHESADA,
IHESADB, and IHESAFA are library
subroutines. DS.ASUB and EPISUB are
compiler routines for getting and freeing
dynamic storage areas (DSAs).
The remainder of the static control
section is listed, each line comprising the
following elements:
1.

Six-digit hexadecimal offset.

2.

Up to eight bytes of hexadecimal tex-t.

3.

Comment indicating the type of item -to
which the text refers; a comment
appears against the first line only of
the text for an item.

The following abbreviations are used for
the comments (xxx indicates the presence of
an identifier>:
DED FOR TEMP
or DED

Data element descriptor
for a temporary or for a
programmer's variable.

FED

Format element descriptor.

DV •• xxx

Dope vector for a static
variable.

DVD..

Dope vector descriptor.

D.V. SKELETON

Dope vector skeleton for
an automatic or controlled
variable.

ROV..

Record dope vector.

A •• xxx

Address of external
control section or entry
point, or of an internal
label.

ARGUMENT
LIST

Argument list

CONSTANTS

Constants.

SYMTAB

Symbol table entry.

SYM •• xxx

Symbolic name of label
constant or label
variable.

FILE •• xxx

File name.

static Internal storage Map
The first 52 bytes of the static internal
control section are of a standard form and
are not listed. They contain the following
information:
DC
DC
DC
DC
DC
DC
54

F'4096'
AL4(SI.+X'1000·)
AL4(SI.+X'2000')
AL4(SI.+X'3000')
AL4(SI.+X'4000')
AL4(SI.+X'5000')

skeleton~

ON •• Ji~XX

programmer-declared
ON-condition.

ATTRIB

File attributes.

xxx

static variable. If the
variable is not
initialized, no text
appears against the
comment, and there is also
no static offset if the
variable is an array.
(This can be calculated
from the dope vector if
required.)

Object ?rogram Listing
The object program listing includes
comments of the following form as an aid to
identification of the functions of the
components of the program:

*

STATEMENT NUMBER n - identifies the
start of the code generated for
source listing statement number n.

*

PROCEDURE xxx - identifies the start of
the procedure labeled xxx.

*

REAL ENTRY xxx - heads the
initialization code for an entry
point to a procedure labeled xxx.

*
*

PROLOGUE BASE - identifies the start of
the initialization code common to
all entry points to that procedure.
PROCEDURE BASE - identifies the address
loaded into the 'base register for
-t:h e procedure.

A ••

Address constant

AE ••

Apparent entry point (point in
the procedure to which control
passed from the prologue).

BLOCK.

Label created for an otherwise
unlabeled block (followed by the
number of the block).

C ••

Constant (followed by a
hexadecimal dictionary
reference).

CL.

A label generated by the
compiler (followed by a decimal
number identifying the label).

DED ••

Data element descriptor

DV ••

Dope vector

DVD..

Dope vector descriptor

FVDED ••

Data element descriptor of
function value.

FVR..

Function value

IC.

Invocation count
pseudo-register.

ON,••

ON-condition name

PRe •

pseudo-register

RDV ••

Record dope vector

RSW ••

Return switch

SI.

Address of static internal
control section.

SKDV ••

Skeleton dope vector, followed
by hexadecimal dictionary
reference.

SKPL ••

Skeleton parameter list,
followed by hexadecimal
dictionary reference.

ST ••

Symbol table entry

SYM..

Symbolic representation of a
label.

TCA..

Temporary control area: a word
containing the address of the
dope vector of the specified
temporary.

TMP. ..

Temporary, followed by
hexadecimal dictionary
reference·.

TMPDV,. •

Temporary dope vector, followed
by hexadecimal dictionary
reference

* APPARENT

ENTRY xxx - identifies the
point of entry into the procedure
for the entry point labeled xxx.

*

END PROCEDURE xxx - identifies the end
IDf the procedure labeled xxx.

*
*

BEGIN BLOCK xxx - indicates the start
of the begin block with label xxx.
END BLOCK xxx - indicates the end of
-the begin block with label xxx.

* ·INrrIALIZATION

CODE FOR xxx - indicates
it:hat the code following performs
initial value assignment or dope
v'ector initialization for the
variable xxx.

whereever possible, a mnemonic prefix is
used to identify the type of operand in an
instrud~ion, and where applicable this is
followed by a source program identifier.
The following prefixes are used:

Chapter 5: compilation

55

VO ••

Virtual origin

WP1.
WP2.
WS1.
WS2.
WS3.

Workspace, followed by decimal
number of block which alloca"tes
workspace

The compiler lists only those messages
with a severity equal to or greater than
that specified by the FLAG option:

A listing of the various storagE~ areas
is not produced, but the addresses of
variables can be deduced from the object
program listing.

Type of Message

Option

warning
error
severe error
termination error

FLAGW
FLAGE
FLAGS
Always listed

Each error message is identified by an
8-character code~

Example:
1.

The first three characters are IEM,
which identify the message as
emanating from the F compiler.

2.

The next four characters are a 4-diglt
message number. Appendix K lists all
the compiler messages in numeric
sequence.

3.

The last character is the letter I,
which is the operating system code for
an informative message.

A=B+l0El; in the source program
produces :
0002CA

78 00 B 058

LE

O.B

0002CE

7A 00 B 064

AE

0,C •• 08F4

0002D2

70 00 B 060

STE

O,A

A and B are STATIC INTERNAL variables at an
offset of X'60' and X'58', respectively,
from the start of the control section.

DIAGNOSTIC MESSAGES
The compiler generates messages that
describe any errors or conditions that may
lead to error that it detects during
compilation. Messages generated by the
preprocessor appear in the compiler listing
immediately after the listing of the
statements processed by the preprocessor;
all other messages are grouped together at
the end of the listing. The messages are
graded according to their severity:

At the end of a compilation, a message
is printed giving the value for the SIZE
option that will prevent the spill file
being used for dictionary blocks if the
program is recompiled.

RETURN CODE
The compiler returns a completion code to
the operating system to indicate the degree
of success i t achieved. This code appears
in the job scheduler END OF STEP message as
• RETURN CO DE. '
Meaning

A' warning message calls attention t:o a
possible error, although the statement
to which it refers is syntactically
valid.

0000

No diagnostic messages issued;
compilation completed without
error; successful execution
anticipated.

An ~ message describes an attempt
made by the compiler to correct an
erroneous statement (although it may
not specify the corrective action)e

0004

Warning messages only issued;
compilation completed; successful
execution probable.

0008

Error messages issued;
compilation completed, but with
errors; execution may fail.

0012

Severe error messages issued;
compilation may have been
completed, but with errors;
successful execution improbablE!.

0016

Termination error messages
issued; compilation terminated
abnormally; successful execution
impossible.

A severe error message specifies an
error that cannot be corrected. by the
compiler. The incorrect statement or
part of a statement is deleted., but
compilation continues. However, if a
severe error is detected during the
preprocessor stage, compilation is
terminated after the compiler has
listed the source program.
A'termination error message describes
an error that forces the termination of
the compilation.
56

Note: This return code is
returned for all levels of
termination when the syntax check
option is used.

Batched Compilation
The batched compilation facility of the
compile:r allows you to compile more than
one exbernal procedure in a single
execution of the compiler. The compiler
creates an object module for each external
procedure and places them sequentially in
the data set identified by the DD statement
SYSPUNCH or SYSLIN. Batched compilation
can increase compiler throughput by
reducinq operating system overheads, but
has the disadvantage that a termination
error dtetected during the compilation of
one extc?rnal procedure will prevent the
compila'tion of those that follow it.
To specify hatched compilation, you must
include a compiler PROCESS statement in
front of each external procedure except the
first. This statement indicates to the
compile:t: that it must process another
procedu:re, and it allows you to specify new
options for each compilation. The first
procedu;re in the batch does not require a
PROCESS statement since the EXEC statement
that invokes the compiler contains all the
information that it requires.
Note that the return code given for a
batched compilation is the highest code
that would be returned if the procedures
were crnnpiled independently.

THE PROCESS STATEMENT
The fonnat of the PROCESS statement is

*

PHOCESS (' options' ) ;

where 'options' indicates a list of
compi lelt: options exactly as specif ied in
the PAru1 parameter of an EXEC statement;
the list. of options must be enclosed within
sinqle quotation marks. The asterisk must
be in the first byte of the record (card
column :U, and the keyword PROCESS may
follow in the next byte (column) or after
any nU~Jer of blanks. Blanks are also
pennitted between:
keyword PROCESS and the
op:ion-list delimiter (left
parenthesis).

1.

Thc~

2.

The option-list delimiters and the
start or finish of the option list.

3.

The option-list delimiter and the
semicolon.

The options in the option list may
include any of those described under
.f Optional Facilities,' • earlier
in this
chapter. The options must be separated by
commas, and there must be no embedded
blanks. The options apply to the
compilation of the source statements
between the PROCESS statement and the next
PROCESS statement. If you omit any of the
options, the default values apply; there is
no carryover from the preceding EXEC ,
statement or PROCESS statement. The number
of characters is limited only by the
length of the record.
If you do not wish
to specify any options, code

*

PROCESS;

The input record that contains the
PROCESS statement must be in EBCDIC code.

TheOBJNM Option
The OBJNM option determines how the object
modules in a batch will be link-edited
together. The appearance of this option in
the PARM parameter of the EXEC statement or
in a PROCESS statement causes the compiler
to place a linkage-editor NAME statement at
the end of the object module resulting from
the compilation of the external procedure
to which the option refers. When the batch
of object modules is link-edited, the
linkage editor places all the modules
between one NAME statement and the
preceding NAME statement into the same load
module; it takes the name of a load module
from the NAME statement that follows the
last object module that is to be included.
For example, consider the-following source
statements (assuming the option OBJNM=A in
the EXEC statement):
ALPHA: PROC OPTIONS (MAIN) ;

END ALPHA;
PROCESS;
BETA: PROC OPTIONS(MAIN};

*

END BETA;
PROCESS ('OBJNM=B');
GAMMA: PROC;

*

END

GAMMA;
Chapter 5: Compilation

57

compilation of these source statements
would result in the following object
modules and NAME statements:
object module for ALPHA
NAME A

(R)

Object module for BETA
Object module for GAMMA
NAME B (R)
From this sequence of object modules and
control statements, the linkage editor
would produce two load modules, one named A
containing the object program for procedure
ALPHA, and the other named B containing the
object programs for the procedures BETA and
GAMMA.
You should not specify the OBJNl-1 option
if you intend to process the object modules
with the linkage loader. The loader
processes all object modules with the same
name into a single load module; if there is
more than one name, the loader recognizes
the first one only and ignores the others.

of the procedure FIRST; of the options
specified, only SIZE applies to the
compilations of the other procedures. The
OBJNM option (abbreviated to 'N') ensures
that FIRST will be link-edited into a load
module named PGM1, which will contain no
other procedures~
The first PROCESS statement requests a
listing of the external symbol dictionary
for the object module compiled from
procedure SECOND
The second PROCESS
statement includes the option N=PGM2, which
causes the compiler to insert a linkage
editor NAME statement at the end of the
object module compiled from the procedure
PRINT; since this option does not appear in
the preceding PROCESS statement, the object
modules for procedures SECOND and PRINT
will be combined in a single load module
(named PGM2) by the linkage editor.
8

The third PROCESS statement names the
load module that will contain the procedure
THIRD, and also requests that only error.,
severe error, and termination error
messages be listed by the compiler.

JOB CONTROL LANGUAGE FOR BATCHED PROCESSING
The only special consideration relating to
job control statements for batched
processing refers to the data set defined
by the DD statement SYSLIN. If you include
the option LOAD, ensure that this DD
statement contains the parameter
DISP=(MOD,KEEP) or DISP=(MOD,PASS); the
standard cataloged procedures specify
DISP=(MOD,PASS).
If you do not specify
DISP=MOD, successive object modules will
overwrite the preceding modules.
Under pCP or MVT, if you do not specify
sufficient primary extents for the data
sets defined by SYSLIN or SYSPRINT, you may
get an abnormal termination with a system
completion code of 80A, in which case you
should increase the primary extents and run
the job again.

Example
Figure 5-7 is an example of a simple
batched processing program. It illustrates
the use of a single invocation of the
cataloged procedure PL1LFCL to compile four
procedures and link-edit them into three
load modules. Figure 5- 8 illustra"tes how
these load modules could later be executed.
The EXEC statement COLE in Figure 5-7
specifies the options for the compilati.on
58

The DD statement LKED.SYSLMOD overrides
the corresponding statement in the
cataloged procedure, and has the effect of
requesting the linkage editor to place th~~
load modules in the private library PUBPG1~,
from which they can later be called for
execution.
In Figure 5-8, this library is
named again in the DD statement JOBLIB; a
library specified by a DD statement of this
name serves as an extension of the system
program library for the duration of the job
in which the statement appears.
(Chapters
6 and 12 discuss the linkage editor and
program libraries, respectively.)

Compile-time Processing
The compile-time facilites of the (F)
compiler are described in IBMSystem/360
Operating system: PL/I (F) Language
Reference Manual. These facilities allow
you to include in a PL/I program statemen"ts
that, when they are executed by the
preprocessor stage of the compiler, mOdify
your source statements or cause source
statements to be included in your program
from a library. The following discussion
supplements the information contained in
the Language manual by providing some
illustrations of the use of the
preprocessor and explaining how to
establish and use source statement
libraries.

//J067PGEX JOB
//COLE J~XEC PL1LFCL,PARM.PL1L='SIZE=999999,N=PGM1,A' ,PARM.LKED='LIST'
//PL1L.8YSIN DD *
FIRST: PROC OPTIONS(MAIN);
DO I=1250 TO 1500 BY 50;
DO J=10, 15, 20;
K=SQRT(I/J):
PUT SKIP(2) DATA;
END FIRST;
* PROCESS (' EXTREF' ) ;
SECOND:: PROC OPTIONS (MAIN) ;
DCL PRINT ENTRY EXT,
A(5) INIT(1,2~4,8,16),
B(5) INIT(3,5,7,9,11),
C(5,5);
DO I=l TO 5;
DO J=l TO 5;
C(1,J)=12*A(I)/B(J);
END;
END;
CALL PRINT (A,B,C);
END SECOND:
* PROCESS (' N=PGM2' ) :
PRINT: PROC (THOR,TVERT,ARRAY);
DCL THOR(*),TVERT(*),ARRAY(*,*);
I=DIM(THOR,l);
PUT EDIT (THOR) (X(7), (I) F(7,2»;
DO J=l TO DIM(TVERT,l);
PUT SKIP EDIT(TVERT(J), (ARRAY(J,K) DO K=l TO I»(F(7,2»;
END PRINT;
* PROCESS ( , N=PGM3 , FE' ) ;
THIRD: PROC OPTIONS(MAIN);
ON ENDFILE(SYSIN) GO TO FINISH;
NEXT:
GET DATA(A,B);
C=A+8*B**2/3;
PUT SKIP DATA:
GO TO NEXT;
FINISH: END THIRD;
/*

//LKED.SYSLMOD DD UNIT=2311,VOLUME=SER=D186,DSNAME=PUBPGM,DISP=OLD
Figure

~.-7.

An Example of Batched processing

INVOKING THE PREPROCESSOR
The preprocessor stage of the compiler is
executed only if you specify the option
MACRO and include a DO statement with the
name SYSUT3 in the compilation job step.
The compiler uses the data set to hold the
preprocE~ssed source statements until
compilat~ion begins.
The information that
you must: include in the DD statement is
describ€~d under 'DD Statements,' earlier ill
this chapter. The standard cataloged
procedures for compilation all include an
appropriate DO statement.
The t~erm MACRO owes its origin to the
similarity of some applications of the
compile-·time facilities to the macro
languaqe! available with such processors as

the System/360 assembler.
Such a macro
language allows you to write a single
instruction in your program to represent a
sequence of instructions that have
previously been defined.

Three other compiler options, MAeDCK,
SOURCE2., and COMP, are meaningful only when
you also specify the MACRO option. All are
described earlier in this chapter.
Figure 5-9 is a simple example of the
use of the preprocessor to produce a source
deck for a procedure SUBFUN; according to
the value assigned to the preprocessor
variable USE, the source statements will
represent either a subroutine or a
function.

Chapter 5: Compilation

59

//J067PGEl JOB
//JOBLIB DD UNIT=2311,VOLUME=SER=D186,DSNAME=PUBPGM,DISP=OLD
//Jl EXEC PGM=PGMl
//SYSPRINT DD SYSOUT=A
//J2 EXEC PGM=PGM2
//SYSPRINT DD SYSOUT=A
//J3 EXEC PGM=PGM3
IISYSPRINT DD SYSOUT=A
/ISYSIN DD *
A=27, B=42; A=39, B=17; A=15; B=19; A=12, B=7;
/*

Figure 5-8.

Execution of the Prog:rams Compiled in Figure 5-7

//J068PGEX JOB
I/CO EXEC PLlDFC,PARM.PL1D='NOLOAD,NODECK,MACRO,MACDCK,NOCOMP'
//PL1D.SYSIN DO *
SUBFUN: PROC(CITY);
DCL IN FILE RECORD,
1 DATA,
2 NAME CHAR(10),
2 POP FIXED(7),
CITY CHAR(10);
%DCL USE CHAR;
%USE="SUB'; 1* FOR FUNCTION, SUBSTITUTE %USE='FUN' */
OPEN FILE(IN);
READ FILE(IN) INTO(DATA);
NEXT:
IF NAME=CITY THEN DO;
CLOSE FILE(IN);
"IF USE='FUN' "THEN %GO TO Ll;
PUT FILE(SYSPRINT) SKIP LIST (D,ATA) ; END;
%GO TO L2;
RETURN(POP); END;
%Ll: ;
%L2: ;
ELSE GO TO NEXT;
END SUBFUNi
Figure 5-9.

Using the Preprocessor to Create a Source Deck

THE %INCLUDE STATEMENT
IBM system/360 operating System: PLII (F)
Language Reference Manual describes how to
use the "INCLUDE statement to incorporate
source statements from a library into a
PL/I source program~ (A library is a type
of data set that can be used for the
storage of other data sets, termed members.
Thus, a set of source statements that you
may wish to insert into a source p:rogram by
means of a %INCLUDE sta'tement must exist as
a data set (member) within a libra:ry.
Chapter 12 describes how to create a
library and how to place members in it.)
The %INCLUDE statement includes one or
more pairs of identifiers. Each pair of
identifiers specifies the name of a DD
statement that defines a library and, in
parentheses, the name of a member of the
library. For example, the statement:
%INCLUDE DD1(INVERT),DD2(LOOPX)

60

specifies that the source statements in
member INVERT of the library defined by the
DO statement DOl, and those in member LOOPX
of the library defined by DD2, should be
inserted into the source prog~am. The
compilation job step must include
appropriate DD statements.
If you omit the ddname from any pair o:f
identifiers in a %INCLUDE statement, the
preprocessor assumes the ddname SYSLIB. In
such a case" you must include a DD
statement with the name SYSLIB.
(Note that
the IBM-supplied cataloged procedures do
not include a DO statement with this name
in the compilation job step.)
Source statements in a library must be
in the form of fixed-length records of not
more than 100 bytes. The records can be
blocked; the maximum blocking factor is 5.
The source margin for input records
specified by the SORMGIN option applies
equally to included statements.

//J069PGEX JOB
//STEP1 EXEC PGM=IEBUPDTE,PARM=NEW
//SYSPRINT DD SYSOUT=A
//SYSUT2 DD DSNAME=NEWLIB,DISP=CNEW,KEEP),UNIT=2311,
//
VOLUME=SER=D186,SPACE=CCYL,C4,,1»
//SYSIN DD *
./
ADD NAME=FUN,LEVEL=OO,SOURCE=O
SUBFUN: PROCCCITY);
DCL IN FILE RECORD,
1 DATA,
2 NAME CHAR(10),
2 POP FIXED DEC(7),
CITY CHAR(10);
OPEN FILECIN);
NEXT:
READ FILECIN) INTOCDATA);
IF NAME=CITY THEN DO;
CLOSE FILECIN) i
RETURN (POP) i
END;
ELSE GO TO NEXT i
END SUBFUNi
./
ENDUP
/*

Figure 5-10.

Placing Source Statements in a New Library

You can use the operating system utility
program IEBUPDTE to place source statements
in a library. This facility is described
in the publication IBM.System/360 Operatinq
System,.Ultilities.

You can invoke the CF) compiler from an
assembler language program by using one of
the macro instructions CALL, LINK, XCTL, or
ATTACH. If you use the XCTL macro
instruction, you cannot specify any options
for the compilation: the default options
will apply. However, if you use CALL,
LINK, or ATTACH, you can specify:

Example~~

Figures 5-10 and 5-11 are simple
illustrations of how to place source
statements in a library and how to include
these s1:.a tements in a source program.
The program in Figure 5-10 places the
source statements of the procedure SUBFUN
in a ne\i library. In this example, the
source statements will represent a function
procedure.

1.

Options for the compilation.

2.

Alternative ddnames for the data sets
to be used by the compiler.

3.

The number of the first page of the
compiler listing.
Code the macro instructions as follows:

Figure 5-11 illustrates the use of a
%INCLUDE statement to include the source
statements for SUBFUN in the procedure
TEST. ']~he library NEWLIB is defined in the
DD statE~ment PL1L.SYSLIB, which is added to
the stat:ements of the cataloged procedure
PL1LFCLG for this job. Since the source
statement library is defined by a statement
wi th thE! name SYSLIB, the %INCLUDE
statement need not include a ddname.

r---------T---------T---------------------,
I Name
I Operation I
Operand
I
~---------+---------+---------------------~
I[symbol] I CALL
IIEMAA,C[optionlist]
I
I [,[ddnamelist]
1
I
I
I
I
1 [,pagenbr]]),VL
1

I

I symbol

1
1- LINK

1
1EP=IEMAA,

1
1

IPARAM=([optionlist]
1
I[,[ddnamelist]
I
I _________ i I _________ iI _____________________
[, pagenhr]]) , VL=l
L
JI
1

I

I ATTACH

1

Dynami4:! Invocation of the Compiler
Note: The following discussion assumes that
you are familiar with IBM System/360
assemblE!r language.

For a full explanation of these macro
instructions, refer to IBM System/360
Operatinq System: Supervisor and ~ata
Manaqement Macro Instructions.
Chapter 5: compilation

61

//J069PGEl JOB
/ / COLEEX EXEC PL1LFCLG, P ARM. PL1L=' MACRO, LOAD I' NODECK' , PARM. LKED==' ,
//PL1L.SYSLIB DD UNIT=2311,VOLUME=SER=D186,DSNAME=NEWLIB,DISP=OLD
//PL1L.SYSIN DD *
TEST:
PROC OPTIONSCMAIN);
DCL NAME CHAR(10),
NO FIXED(7);
ON ENDFILE(SYSIN) GO TO FINISH;
AGAIN: GET FILE(SYSIN) LIST(NAME);
NO=SUBFUN(NAME);
PUT DATA (NAME, NO) ;
GO TO AGAIN;
%INCLUDE FUN;
FINISH: END TEST;
/*

//GO.IN DD UNIT=2311,VOLUME=SER=D186,DSNAME=POPLIST,DISP=OLD
//GO.SYSIN DD *
, ABERDEEN'
'DONCASTER'
/*

Figure 5-11.

Including Source statements from a Library

The entry-point name IEMAA is the
symbolic name of the (F) compiler.
The address parameters are:
'optionlist': the address of a
variable-length list of compiler
options. The list must begin on a
halfword boundary. The first two bytes
contain a binary count of the number of
bytes in the list (excluding the count
field). Options in the list must be
separated by commas; the list must not
include blanks or zeros.
'ddnamelist': the address of a
variable-length list of alternative
names for the data sets used by the
compiler. The list must begin on a
halfword boundary. The first it.wo bytes
contain a binary count of the number of
bytes in the list (excluding the count
field). Each entry in the list must
occupy an 8-byte field; the sequence of
entries is as follows:
Entry
1

2
3
4

5
6
7
8
9

10

62

Alternative Name
SYSLIN
not applicable
not applicable
SYSLIB
SYSIN
SYSPRINT
SYSPUNCH
SYSUT1
not applicable
SYSUT3

If a ddname is shorter than eight
bytes, fill the field on the right wi1~h
blanks. If you omit an entry, fill i1:.s
field with binary zeros; however, you
may entirely omit entries at the end of
the list.

'pagenbr': the address of a 6-byte
field containing the number is to be
used as the first page number of the
compiler listing. The page number must
begin on a halfword boundary, and the
first halfword must contain the bina~I
value 4 (the length of the remainder of
the field). The other four bytes
contain the page number in binary form.

VL or VL=l: specifies that the sign bit
in the last word of the parameter list
is to be set to 1.

Chapter 6:

Introdu(~tion

An object module produced by the compiler
requires further processing before it is
sui tablE~ for execution. It must be
converted into a load module which can be
loaded into main storage and executed.
Conversion and execution is performed, in
either one or two job steps, by one of two
operating system programs, the linkage
editor <:md the linkage loader. This
chapter describes these programs and the
circumst:ances in which each can be used to
the best, advantage. Both programs are
fully dE~scribed in IBMSystem/360 Operating
system: .Linkage.Editor and Loader.
Thet:wo linkage programs require the
same kind of input, perform the same basic
process (the resolution of external
references within the object module), and
produce the same result, that is, a load
module for execution. They differ in the
way they are used and in what they do with
the load modules they create.
Linkage loader: Execution by the linkage
loader l:'equires one job step, in which a
load module is created, loaded into main
storage., and executed.
Linkage .editor: The linkage editor does no·t
cause the load modules it creates to be
loaded and executed. Instead, each load
module is placed in a program library; a
further job step is required for the
loading and execution of such a load
module.

If you want to keep the load module, or
use facilities that are not available to
the linkage loader, such as providing an
overlay structure, you must use the linkage
editor. The linkage loader is essentially
a one-shot program checkout facility with
limited application.
The differences between the two programs
can be summarized as:
Linkage editor:
1.

Does not cause the load module to be
executed.

2.

Can produce more than one load module
from a batched compilation.

3.

Always places load modules in a
library, from which they can be loaded
for execution in a later job or job
step.

4.

Can accept input from other sources as
well as the primary input source.

5.

Can provide an overlay structure for a
program.

6.

Can be used to modify existing load
modules.

Linkage.loader:
1.

Requires only one job step for
processing, loading, and execution.

2.

Can only produce one load module from
a batched compilation.

3.

Always loads this module into main
storage and executes it.

4.

The load module exists only for the
duration of the job step.

5.

Can accept input only from the primary
source.

6.

Cannot provide an overlay structure
for a program, or modify existing load
modules.

CHOICE OF LINKAGE PROGRAM
The two programs are compatible in the
following respects:
1.

2.

Al1 object modules acceptable as input
to a linkage editor are acceptable as
input to a linkage loader.
All load modules produced by a linkage
editor, except those produced with the
NE (not editable) attribute are
acceptable as input to a linkage
loader.
(When the NE attribute is
produced, the resulting load module
has no external symbol dictionary and
cannot be reprocessed; the external
symbol dictionary is discussed below
in the linkage-editor section.)

Linkage Editor and Loader

Performance Considerations
The execution time of a load module is the
same whether it is created by the linkage
editor or the linkage loader. However, the
Chapter 6: Linkage Editor and Loader

63

editing and loading time for a module is
greatly reduced when the linkage loader is
used. This is achieved by reductions in:
1.

2.

3.

Scheduling time: The object program is
processed, loaded, and executed in one
job step.
Processing time: The linkage loader
can process a module in approximately
half the time required by the linkage
editor, because:
a.

Linkage editor intermediate and
I/O operations are eliminated.

b.

The I/O time for reading modules
can be reduced by the use of
improved buffering techniques and
chained scheduling.

Amount of .auxiliary sto:rage: If the
linkage loader input is the object
module in a compile~load-and-go job,
the auxiliary storage that would be
required by the linkage editor
intermediate and output data sets is
not needed.
If the linkage loader
input is taken from modules
link-edited into a library, the
auxiliary storage requirements for the
library can be reduced by storing the
modules with unresolved library
references; these references can be
resolved at load time.

Linkage Editor
The linkage editor is an operating system
service program that creates load modules.
It always places the load modules in a
library, from which the job scheduler can
call them for execution~
The input to the linkage editor can
include object modules, load modules, and
control statements that specify how the
input should be processed. The ou1:put from
the linkage editor comprises one or more
load modules.
In addition to its primary function of
converting object modules into loaci
modules, the linkage editor can also be
used to:
• Combine previously link-edi·ted load
modules
• Modify existing load modules
• Construct an overlay program
A module constructed as an overlay
program can be execut.ed in an area of main

64

storage that is not large enough to contain
the entire module at one time. The linkage
editor subdivides the module so that it can
be loaded and executed segment by segment.
MODULE STRUCTURE
Object and load modules have identical
structures. They differ only in that a
load module has been processed by the
linkage editor and stored in a library wi·th
certain descriptive information required by
the job schedule:r; in particular, the
module is marked as 'executable' or 'not
executable.' A module comprises three typ1es
of information:
• Text (TXT)
• External symbol dictionary (ESD)
• Relocation dictionary (RLD)

The text of an object or load module
comprises the machine instructions that
represent the program to be executed.
These instructions are grouped in blocks
termed control sections; a control section
is the smallest separately executable uni1:.
within a program.. An object module creatE~d
by the PL/I (F) compiler includes the
following control sections:
• Control section for the shared library
transfer vector..
(This is an area uSE~d
for communication between library
modules in the PL/I shared library and
those in the partition or region.)
• Program control section: contains the
executable part of the program.
• Static internal control section:
contains storage for all variables
declared STATIC INTERNAL and for
constants and static system blocks.
• Control sections termed common areas:
one common area is created for each
EXTERNAL file name and for each
non-string element variable declared
STATIC EXTERNAL without the INITIAL
attribute •
• IHENTRY: execution of a PL/I program
always starts with this control
section, which passes control to the
appropriate initialization routine;
when initialization is complete,
control passes to the address stored in
the control section IHEMAIN.

•

IH~mIN: for a procedure with the MAIN
option, contains the starting address
for execution of the PL/I program.

• cont:rol sections for PL/I library
modules link-edited with the program.

External. Symbol Dictionary
The external symbol dictionary (ESD)
contains a list of all the external symbols
that appear in the module. An external
symbol is a name that can be referred to in
a control section other than the one in
which it~ is defined.
The names of the control sections are
themselves external symbols, as are the
names of variables declared with the
EXTERNAl, attribute and entry names in the
external procedure of a PL/I program.
References to external symbols defined
elsewhel~e are also considered to be
external symbols; they are known as
external·references. Such external
references in a PL/I object module always
include the names of the PL/I subroutine
library modules that will be required for
the execution of the program. They may
also include calls to your own subroutines
that arE! not part of the PL/I subroutine
library, nor already included within the
object module. Part of the linkage
editor's job is to locate the subroutines
referred to, and to include them in the
load module that will be executed.

Relocation Dictionary
At execution time, the machine instructions
in a IOcLd module (including the
instruct:ions generated by the PL/I (F)
compileI:) use two methods of addressing
locations in main storage:
1.

Names used only within a control
section have addresses related to the
starting point of the control section ..

2.

Other names (external names) have
absolute addresses so that any control
section can refer to them.

The I:elocation dictionary (RLD) contains
that enables the absolute
addressE!s to be established when a module
is loadE!d into main storage for execution.
These addresses cannot be determined
earlier because the starting address is not
known until the module is loaded. The
linkage editor consolidates the RLD entries
in the input modules into a single

relocation dictionary when it creates a
load module.

LINKAGE EDITOR PROCESSING
A PL/I compiled program cannot: be executed
until the appropriate PL/I subroutine
library modules have been incorporated.
The library modules are included in two
ways:
1.

By incorporation in the load module
during linkage editing.

2.

By dynamic call during execution.

The first method is used for most of the
PL/I subroutine library modules; the
following paragraphs describe how the
linkage editor locates the modules. The
second is used for modules concerned with
input and output (including those used for
opening and closing files), and for the
modules that issue the execution time error
messages. Appendix E lists all the library
modules, indicating which are loaded
dynamically.
In its basic processing mode, which is
illustrated in Figure 6-1, the linkage
editor accepts data from its primary input
source, a data set defined by a DD
statement named SYSLIN. For a PL/I
program, this input data is the object
module created by the compiler. The
linkage editor uses the external symbol
dictionary in the input module to determine
whether the module includes any external
references for which there are no
corresponding external symbols in the
module: it attempts to resolve such
references by a method termed automatic
library call.
External symbol resolution by automatic
library call involves a search of the
library defined by a DD statement named
SYSLIB; for a PL/I program this will be the
PL/I subroutine library (SYS1.PL1LIB). The
linkage editor locates the modules in which
the external symbols are defined Cif such
modules exist), and incorporates them in
the load module it is creating.
The linkage editor always places the new
load module in the library defined by the
DD statement named SYSLMOD.

informat~ion

Any linkage editor processing additional
to the basic mode described above must be
requested by linkage editor control
statements placed in the primary input.
These control statements are described at
the end of this chapter under 'Additional
Processing. '
Chapter 6: Linkage Editor and Loader

65

(prima:ry input)

r------------,

I
I
I
I
I

I
I

PL/I
object
module

1----,
I
I

l _____________ J

r-------------,
I
I
I

I

PL/I
I
library
I (SYS1.PL1LIB)I

r---

I
I
I

l ________

r-------------,

SYSLMOD
r-------------,
I

Linkage
edi tor

Output
module
library

>I
I
I
I

I
I
I
~-------------> I
I load module I

Ir-------->IL _____________ JI
I
I

I

I
I
I

I

L_____________ J

J

Il _____________ JI
SYSLIB
(call library)
Figure 6-1.

Basic Linkage Editor Processing

Main Storage Requirements
Two levels of the linkage editor are
currently available; each has a number of
different versions. The E-level is
available in 15K, 18K, and 20K versions;
the F-Ievel is available in 44K, aSK, and
128K versions. The capabilities and
capacities of each version are described in
system/36 0 Operating.System: LinkaqeEditor
and Loader.

Job Control Language for Link-Editing
Al though you will probably use catcLloged
procedures rather than supply all the job
control statements required for a job s·tep
that invokes the linkage editor, i t is
necessary to be familiar with these
statements so that you can make the bes·t
use of the linkage editor and, if
necessary, modify the statements of the
cataloged procedures.
The IBM-supplied PL/I cataloged
procedures that refer to the linkage editor
are:
PLILFCL
PLILFCLG
PLILFLG

Compile and link-edit
Compile, link-edit, execute
Link-edit and execute

Chapter 8 discusses these cataloged
procedures and describes how to modify or
override the statements they contain.
The following paragraphs describe the
essential job control statements for
66

link-editing; they use statements from the
PL/I cataloged procedures as typical
examples. Appendix B contains a
description of the parameters of the DD
statements that are referred to.

EXEC STATEMENT
The name IEWL is an alias for the
linkage-editor program.
If you use the
name IEWL in the EXEC statement that
invokes the linkage editor, the job
scheduler will load the version to which
this name corresponds. Normally this would
be either the one which is the largest
available within your operating system, Ol~
the one which is the most suitable for your
job. You should consult your systems
programmer if you need to know what
versions of the linkage editor are
available at your installation, and how to
invoke them. The basic EXEC statement is:
// EXEC PGM=IEWL
By using the PARM parameter of the EXEC
statement, you can select one or more of
the optional facilities offered by the
linkage editor; these facilities are
discussed under 'Optional Facilities,'
below. The use of the other parameters of
the EXEC statement is as described in
Chapter 7, 'Executing the Load Module.'

r------·-----T-------------------------~---------T----------------------------,

I

ddname

I

I Possible device classes1.

Function

I

~------.-----+-----------------------------------+----------------------------~

I SYSLIN
I

I Primary input data, normally the
I output from the compiler

I SYSSQ or the input job
I stream (specified by DD

*)

I
I

~------.-----+-----------------------------------+----------------------------~

I

SYSL~~OD
I Output for load module
I SYSDA
I
~------.-----+----------------------------.-----+------------~---------------~
I SYSU'l'l
I Additional workspace
I SYSDA
I
~------ -----+-----------------------------------+----------------------------~
I SYSPRINT I Listing, including diagnostic
I SYSSQ or SYSOUT device
I
I
I
I
I messages
~------"-----+-----------------------------------+-----------~----------------~
I SYSLIB
I Automatic call library (usually
I SYSDA
I
I
I the PL/I subroutine library)
I
I

.

~------,----~-----------------------------------~----------------------------~
11 SYSSQI Magnetic-tape or direct-access device
I

JI
IL ______
SYSDA,.______________________________________________________________________
Direct-access device

Figure 6-2.

Linkage-Editor Data Sets

DO STATEMENTS

link-edit and execute a PL/I object module
placed in the input stream, you can use the
following statements:

The linkage editor always requires four
standard data sets. You must define these
data sets in DD statements with the
standard names SYSLIN, SYSLMOD, SYSUT1" and
SYSPRINT.
A fifth data set, defined by a DO
statement with the name SYSLIB, is
necessar.y if you want to use the automatic
library call facility.
The five standard
data se'ts are summarized in Figure 6- 2.

//LEGO JOB
// EXEC PL1LFLG
//LKED.SYSIN DO

Insert here the object module to be
link edited and executed
/*

Note:
1.

If modules with identical names appear
in the primary input, the linkage
editor processes only the first of
them.

2.

You can include load modules or object
modules from one or more libraries in
the primary input by using a linkage
editor INCLUDE statement; refer to
'Additional Processing,' below.

Primary.Input (SYSLIN)
The primary input source must be a
CONSEcurIVE data set containing one or more
object lDodules and/or linkage-editor
control statements; a load module cannot be
part of the primary input, although it can
be introduced by the control statement
INCLUDE.. For a PL/I program, the primary
input source is usually a data set
containing an object module created by the
compiler. The data set may be on
magnetic-tape or on a direct-access device,
or you can include it in the input job
stream. In all cases, the input must be in
the form of aO-byte F-format records.
'.rhe cataloged procedure PL1LFLG includes
the DD statement:
//SYSLIN DD DDNAME=SYSIN
This statement specifies that the
primary input data set must be defined in, a
DD statE~ment named SYSIN. If you use this
catalogue procedure, you must supply this
DD statE~ment, specifying the qualified
ddname I~KED.SYSIN. For example, to

*

Output (SYSLMOD)
The linkage editor always places the load
modules that it creates in a library
defined by a DO statement with the name
SYSLMOD.
(A library is a type of
direct-access data set that can be used for
the storage of other consecutive data sets,
frequently load modules); the data sets
stored in a library are termed members. To
store a member in a library, include the
parameter DSNAME=dsname(membername) in the
DD statement that defines the library;
replace 'dsname' with the name of the
library, and 'membername' with the name of
the member.)
Chapter 6: Linkage Editor and Loader

67

The PL/I cataloged procedures include
the following DD statement:

Listing. (SYSPRINT)

//SYSLMOD DD DSNAME=&&GOSET(GO),
//
DISP=(MOD,PASS),
//
UNIT=SYSDA,
//
SPACE=(1024,
//
(50,20,1) ,RLSE)

The linkage edi to:r generates a listing that
includes reference tables relating to the
load modules that it produces and also,
when necessary, diagnostic messages. The
information that may appear is described
under 'Listing,' below.

This statement defines a temporary
library named &&GOSET and assigns the name
GO to the load module that the linkage
editor will place in it. If you want to
retain the load module after execution of
your job, you must replace this DD
statement with one that de:fines your own
permanent library. For example, assume
that you have a library called USLIB on
2311 disk pack serial number 371; to name
the load module MOD1 and place it in this
library, code:

You must define the data set on which
you wish the linkage editor to place its
listing in a DD statement named SYSPRINT.
The data set must have CONSECUTIVE
organization. Although the listing is
usually printed, it can be written on any
type of magnetic-tape or direct-access
device. For printed output, the following
statement will suffice:
//SYSPRINT DD SYSOUT=A

Automatic Call Library (SYSLIB)
//LKED.SYSLMOD
//
//
//

DD DSNAME=USLIB(MOD1),
UNIT=2311,
VOLUME=SER=371,
DISP=OLD

The size of a load module must not
exceed 512K bytes (512 * 1024 bytes) for
programs executed under PCP or MFT; a much
larger load module is permitted for MVTQ
The SPACE parameter in the DD statement
SYSLMOD used in the PL/I cataloged
procedures allows for an initial allocation
of 50K bytes and, if necessary, 15 further
allocations of 20K bytes (a total of 350K
bytes); this should suffice for most
applications.

Workspace (SYSUT1)
The linkage editor requires a temporary
data set on a direct-access device for use
as extra workspace. The DD statement that
defines this data set must have the name
SYSUT1. The following statement contains
the essential parameters:
//SYSUTl DD UNIT=SYSDA,
//
SPACE=(1024,(200,20»
You should never need to modify the DD
statement SYSUT1 in a cataloged procedu:re.
If your installation supports dedica·ted
workfiles, these.can be used to provide
workspace for the link-edit job step. For
details of these workfiles and their use,
see 'Workspace (SYSUT1,SYSUT3)' in Chapter
5, 'Compilation.'
68

If you want the linkage editor to resolve
external references by automatic library
call, you must use aDD statement with the
name SYSLIB to define the library which the
linkage editor must search. You can cause
the linkage editor to search more than one
library by concatenating the DD statements
that define the libraries: include the
ddname SYSLIB in the first statement and
leave the name fields of the following
statements blank.
The link-editing of a PL/I object module
normally requires the presence of a SYSLIB
statement that refers to the PL/I
subroutine library (SYS1.PL1LIB).
The automatic call library can contain
load modules or object modules, but not
both.

EXAMPLE
The following example is a typical sequence
of job control statements for link-editinsr
a PL/I object module. The DD statement
SYSLIN indicates that the object module
will follow immediately in the input
stream; for example, it might be an object:
deck created by invoking the PL/I (F)
compiler with the DECK option (see Chapter
5). The DO statement SYSLMOD specifies
that the linkage editor should name the nE~W
load module LKEX., and that it should placE~
it in a new library named MOOLIB; the
presence of the SPACE parameter and the
keyword NEW in the DISP parameter indicatE~s
to the operating system that this DD

stateme!:nt requests the creation of a new
library.
//LINK JOB
//. EXEC PGM=IEWL
//SYSLMOD DD UNIT=2311,
//
VOLUME=SER=D186,
//
DSNAME=MODLIB(LKEX),
//
DISP=(NEW,KEEP),
//
SPACE=(CYL,(10,10,1»
//SYSUTl DD UNIT=2311,
//
SPACE=(1024,(200,20»
//SYSPRINT DD SYSOUT=A
//SYSLIB DD DSNAME=SYS1.PL1LIB,
//
DISP=OLD
//SYSLIN DD *

LIST
The LIST option specifies that all linkage
editor control statements processed should
be listed in the data set defined by the DD
statement SYSPRINT.

MAP

The MAP option requests the linkage editor
to produce a map of the load module; this
map indicates the relative locations and
lengths of the control sections in the
module.

Insert here the object module to be
link-edt ted
XREF

Optiona~l

Facilities

The linkage editor provides a number of
optional facilities that you can select by
including the appropriate keywords from the
following list in the PARM parameter of the
EXEC statement that invokes it:

The XREF option requests the linkage editor
to produce a map of the load module and a
cross-reference list of all the external
references in each control section. XREF
includes MAP.

LET

LIs~r

The LET option requests the linkage editor
to mark the load module 'executable,' even
if slight errors or abnormal conditions are
found during link-editing.

MAP or XREF
LET or XCAL
NCAl.
SIZg

XCAL

The PARM parameter is a keyword
parametE2lr. Code PARM= followed by the list
of options, separating the names of the
options with commas and enclosing the list
within single quotation marks. For
example::

The XCAL option requests the linkage editor
to mark the load module as executable even
if errors or abnormal conditions, including
improper branches between control sections,
are found during link-editing. XCAL, which
includes LET, applies only to an overlay
module.

// EXEC PGM=IEWL,PARM=ILIST,MAP'
If you are using a cataloged procedure,
you must. include the PARM parameter in the
EXEC statement that invokes the procedure.
and qualify the keyword PARM with the name
of the procedure step that invokes the
linkage editor. For example:
// EXEC PL1LFCLG,PARM.LKED='LIST,XREF'
':l"he j:ollowing paragraphs describe the
optional facilities. The listing produced
by the options LIST, MAP, and XREF are
described under 'Listing,' below.

NCAL
The NCAL option specifies that no external
references should be resolved by automatic
library call. However, the load module is
marked 'executable' (providing there are no
errors).
You can use the NCAL option to conserve
storage space in private libraries since,
by preventing the resolution of external
references during link-editing, you can
Chapter 6: Linkage Editor and Loader

69

store PL/I load modules without the
relevant PL/I library subroutines; the DD
statement SYSLIB is not required. Before
executing such load modules, you must
link-edit them again to resolve the
external references, but the load module
thus created need exist only while it is
being executed. You can use this technique
to combine separately compiled PL/I
routines in a single load module.

Listing
The linkage editor always lists, in the
data set defined by the DD statement
SYSPRINT, any errors or abnormal conditions
that it discovers. It will also list the
following additional information if you
specify the appropriate options:
Listings

Option Required

Control statements
processed by the
linkage editor

LIST

Map of the load module

MAP or XREF

Cross-reference 'table
of external references

XREF

SIZE
The SIZE option specifies the amount of
main storage, in bytes, to be allocated to
the linkage editor; it applies only to the
F-Ievel linkage editor. Code the SIZE
option as a keyword parameter with the
following format:
SIZE=(valuel,value2)
For 'valuel' substitute a decimal
integer number representing the number of
bytes of main storage to be allocated to
the linkage editor, including the
allocation for the load module buff:er
specified in value2.
For 'value2' substitute a decimal
integer number representing the number of
bytes of main storage to be allocat.ed for
the load module buffer. The linkage editor
uses the load module buffer when it reads
in load module records, and also to retain
information for subsequent writing of
output records.
You can specify both values as the
actual number of bytes (for example,
SIZE=(45056,6144» or as a multiple of 1024
bytes (for example, SIZE=(44K,6K». Valuel
must exceed value2; the following table
lists the minimum and maximum values and
the minimum difference between valuel and
value2 for the three designs of the F-Ievel
linkage editor:
Linkage
Editor

Valuel
Min

44K
88K
l28K

44K
88K
128K

Max

Value2
Min
6K
6K
6K

Max
lOOK
lOOK
lOOK

Valuel Value2
(Min) 38K
44K
66K

If you specify SIZE incorrectly, or if
you omit the parameter, a default value set
at system generation is used~
70

The following paragraphs describe the
elements of the listing; the sequence in
which they appear differs between the
E-Ievel and F-Ievel linkage editors.
Appendix A includes a fully annotated
example of a linkage editor listing.
A statement of the level of linkage
edi tor and the options specified appears a,t
the head of the listing.

CONTROL STATEMENTS AND ERRORS
During processing, the linkage editor notE!S
the occurrence of error and other
conditions as it encounters them; these
notes appear as a list immediately after
the heading statement.
If you specify the
LIST option, this list also includes all
control statements processed by the linkage
editor.
Each entry in the list comprises a
7-character code followed by the name of
the control statement to which the code
applies. For a control statement, the code
is always IEWOOQO. All other codes refer
to explanatory,. error, or warning messages;
each code comprises:
1.

The letters lEW, which identify
linkage editor messages.

2.

A 3-digit message number.

3.

A

l-digit severity code as follows:

Meaning

o

A condition which will not cause
an error during execution. The
output module is marked
'executable.'

1

A condition that may cause an
error during execution. The
output module is marked
'executable.'

2

An error that could make
execution impossible. The output
module is marked 'not executable'
unless LET is specified.

3

An error that will make execution
impossible. The output module is
marked 'not executable.'

4

An error condition from which no
recovery is possible. Linkage
editor processing is terminated,
and no output other than
diagnostic messages is producedQ

At t:he end of the list of messages, the
E-Ievel. linkage editor places a statement
of the disposition of the load module; the
F-Ievel. linkage editor places this
statememt at the end of the listing, just
before the Diagnostic Message Directory
(see be!low). The disposition statements,
with one exception, are self-explanatory;
the exc:eption is:
****modulename DOES NOT EXIST BUT HAS
BEE:N ADDED TO DATA SET
The message normally appears when a request
has beem made for the, linkage editor to
substi t:ute the new load module for an
existing module.
It indicates that the
linkage~ editor was unable to locate the
existing module, but has placed the new
module in the data set named in the DD
statemEmt SYSLMOD. If you name a new
module by including a name in the DSNAME
paramet:er of the DD statement SYSLMOD, the
linkagE~ editor assumes that you want to
, replacE~ an existing module (even if the
data SE~t is new).

DIAGNOSTIC MESSAGE DIRECTORY
When pJ:'ocessing of a load module has been
comple't:ed, the linkage editor lists in full
all thE~ diagnostic messages whose numbers
appear in the preceding list. IBM
System(360 operatinq,system: Linkage Editor
and Loader contains explanations of all the
linkagE:! editor messages and their probable
causes., and suggests how to cope with them.

The warning message IEW0461 frequently
appears in the linkage editor listing for a
PL/I program. It refers to external
references that have not been resolved
because NCAL was specified (in this
instance, in a linkage editor LIBRARY
statement). The references occur in PL/I
library subroutines that are link-edited
with your program as a result of automatic
library call. Some library modules may, in
turn, call other library modules. Any
library module that calls a secondary
module that may only occasionally be
required is preceded by a LIBRARY
statement. This specifies that the
references to the secondary modules should
not be resolved unless these modules are
already part of the input to the new load
module, that is, they are external
references. For those secondary modules
that are required, the compiler generates
another external symbol dictionary
containing 'alternative names for the
modules. These new references can be
resolved, and the required modules are
placed in the new load module. If the
secondary modules in turn call other
modules, the process is repeated.

MODULE MAP
The linkage editor listing includes a
module map only if you specify the options
MAP or XREF. The map lists all the control
sections in the output module and all the
entry names in each control section. The
control sections are listed in order of
appearance in the load module; alongside
each control section name is its address
relative to the start of the load module
(address 0) and its length in bytes. The
entry points within the load module appear
on the printed listing below and to the
right of the control sections in which they
are defined; each entry point name is
accompanied by its address relative to the
start of the load module.
Each control section that is included by
automatic library call is indicated by an
asterisk. For an overlay module, the
control sections are arranged by segment in
the order in which they were specified.
After the control sections, the module
map lists the pseudo-registers established
by the compiler. pseudo-registers are
fields in a communications area, the
pseudo-register vector (PRV), used by the
PL/I library subroutines and compiled code
during execution of a PL/I program. The
storage occupied by the PRV is not
allocated until the start of execution of a
PL/I program; therefore, it does not form
part of the load module. The addresses
Chapter 6: Linkage Editor and Loader

71

given in the list of pseudo-registers are
relative to the start of the PRV.
At the end of the module map, the
linkage editor supplies the following
information:
1.

The length of the PRV.

2.

The relative address of the
instruction with which execution of
the load module will commence (ENTRY
ADDRESS).

3.

The total length of the module. For
an overlay module, the length is that
of the longest path.

All the addresses and lengths given in
the module map and associated information
are in hexadecimal form.

Meaning
0000

Normal completion

0004

warning,. but execution should be
successful

0008

Errors, execution may fail

0012

Severe errors, execution
impossible

0016

Termination error

The code 0004 almost invariably appears
after a PL/I program has been link-edited"
because some external references in the
PL/I library subroutines have not been
resolved.
(Refer to 'Diagnostic Message
Directory,' above.>

Additional Processing
CROSS-REFERENCE TABLE
The linkage editor listing includes a
cross-reference table only if you specify
the option XREF. This option produces a
listing that comprises all the information
described under 'Module Map,' above,
together with a cross-reference table of
external references. The table lists the
location of each reference within the load
module, the symbol to which the reference
refers, and the name of the control section
in which the symbol is defined.
For an overlay module, a cross-reference
table is provided for each segment. It
includes the number of the segment in which
each symbol is defined.
Unresolved symbols are identified in the
cross-reference table by the entry
$UNRESOLVED. However, if a symbol was not
resolved owing to the use of the NeAL
option or a LIBRARY statement, it is
identified by $NEVER-CALL.

RETURN CODE
The linkage editor returns a" completion
code to the operating system to indicate
the degree of success it achieved. This
code appears in the job scheduler END OF
STEP message as 'RETURN CODE.' The code is
derived by multiplying the highest
diagnostic message severity code by four.
72

The basic function of the linkage editor is
to create a single load module from the
data that it reads from its primary input
source, but it has several other facilitif~s
that you can call upon by using linkage
editor control statements. The use of
those statements of particular relevance 1:.0
a PL/I program is described under
functional headings, below. All the
linkage editor control statements are fully
described in IBM system/360 Operating
system: Linkage Editor and Loader.

FORMAT OF CONTROL STATEMENTS
A linkage editor control statement is an
80-byte record that contains two fields.
The operation field specifies the operation
required of the linkage editor; it must bE~
preceded and followed by at least one blGillk
character. The operand field names the
control sections, data sets, or modules
that are to be processed, and it may
contain symbols to indicate the manner of
processing; the field consists of one or
more parameters separated by commas. SomE~
control statements may have multiple
operand fields separated by commas.
The position of a control statement in
the linkage editor input depends on its
function.
In the following descriptions of the
control statements, items within brackets
[ ] are optionall1 you may omit them at your
discretion.

MODULE NAME

separate the names by commas, for example:
ALIAS FEE, FIE, FOE, FUM

A load module must have a name so that the
linkage editor and the job scheduler can
identify it. A name comprises up to seven
charactf~rs, the first of which must be
al phabet.i c.

An ALIAS statement can be placed before,
between, or after the modules or other
control statements that are being processed
to form a new load module, but it must
precede the NAME statement that specifies
the primary name of the new module.

You can name a load module in two ways:
1.

If you are creating a single load
module, it is sufficient to include
its name as a member in the DSNAME
parameter of the DD statement SYSLMOD.

2.

If you are creating two or more load
modules in a single execution of the
liJrlkage editor, you will need to use
thc3 NAME statement.
(The PL/I (F)
canpiler can supply the NAME
statements when you use the
bat.ch-compilation feature: see Chapter
5. )

The tormat of the NAME statement is:
NAME membername [( R) ]
f'or I, membername ' substitute the name of
the module. (R), if present, signifies
that the load module is to replace an
existinc:J load module of the same name in
the dati:t set defined by the DD statement
SYSLMOD.
The NAME statement must appear in the
primary input to the linkage editor (the
data set: defined by the DD statement
SYSLIN)i if it appears elsewhere, the
linkage editor ignores it. The statement
must follow immediately after the last
input m~dule that will form part of the
load module it names (or after the INCLUDE
statemerlt that specifies the last module.)

To execute a load module, you can
include an alias instead of the primary
name in the PGM parameter of an EXEC
statement. Providing the alias is not also
the name of an entry point within the
module, execution will commence at the
normal entry point (which, for a PLiI
program, is the control section IHENTRY).
Do not use a NAME or an ALIAS statement to
give a PL/I load module a name that is an
entry name other than IHENTRY. If you do,
the initialization routines which are
called from IHENTRY before control is
passed to your program will be bypassed and
your program will not execute successfully.
Generally. you should not give a PLII
module a name or an alias name that begins
with 'I' (except IHENTRY).

ADDITIONAL INPUT SOURCES
The linkage editor ~an accept input from
sources other than the primary input
defined in the DD statement SYSLIN. For
instance., the automatic library call
facility enables the linkage editor to
include modules from the library named in
the DD statement SYSLIB. You can name
additional input sources by means of the
INCLUDE statement, and you can direct the
automatic call mechanism to alternative
libraries by means of the LIBRARY
statement.

Al terna1~i ve Names
INCLUDE Statement
You can use the ALIAS statement to give a
load module an alternative name; a load
module can have as many as sixteen aliases
in addi·tion to the name given to it in a
SYSLMOD DD statement or by a NAME
statement.
'l'he format of the ALIAS statement is:
ALL~S

symbol

For "symbol' substitute any name of up
to seven characters: the first character
must be alphabetic. You can include more
than one name in an ALIAS statement:

The INCLUDE statement causes the linkage
editor to process the module or modules
indicated. After the included modules have
been processed, the linkage editor
continues with the next item in the primary
input. If an included sequential data set
also contains an INCLUDE statement, that
statement is processed as if it were the
last item in the data set (Figure 6-3).
The format of an INCLUDE statement is:
INCLUDE ddname [(membername)]
Chapter 6: Linkage Editor and

Lo~der

73

- -!

--!

Library
Member

Sequential
Data Set

Primary Input
Data Set

---

---

end
INCLUDE

end
INCLUDE'
not
processed
end
....----

Figure 6-3.

Processing of Additional Data Sources

Replace 'ddname' with the name of a DD
statement that defines eithe:r a sequential
data set or a library that contains the
modules and control statements to be
processed. If the DD statement defines a
library, replace 'membername' with the
names of the modules to be processed,
separated by commas.
You can specify more
than one ddname, each of which may be
followed by any number of member names in a
single INCLUDE statement. For example, the
statement
INCLUDE Dl(MEM1,MEM2),D2(MODA,MODB)
requests the inclusion of the members MEMl
and MEM2 from the library defined by the DD
statement D1, and the members MODA and MODB
from the library defined by D2.

LIBRARY statement
The basic function of the LIBRARY statement
is to name call libraries in addition to
those named in the DD statement SYSLIB.
For this purpose, the format of the
statement is similar to that of the INCLUDE
statement:
LIBRARY ddname(membername)
Replace 'ddname' with the name of a DD
statement that defines the additional call
library, and 'membername' with the names of
the, modules to be examined by the automatic
call mechanism; separate the module names
with commas.
You can also use the LIBRARY statement
to specify external references that should
not be resol ved, or to specify tha·t no
external references should be resolved.
(Refer to IBM System/360 Operating System:
Linkage Editor and Loader.)

74

end

OVERLAY PROGRAMS
To reduce the amount of main storage
required for the execution of a program,
you can organize i t into an overlay
structure.
An overlay program is divided
into segments, which can be loaded and
executed successively in the same area of
main storage. To construct such a program,
you must use linkage editor control
statements to specify the relationship
between the segments.
Note that one
segment" termed the root segment must
remain in main storage throughout the
execution of the program.

Designing the Overlay structure
Before preparing the linkage editor control
statements, you must determine the overlay
tree structure from the program. A tree is
a graphic representation that shows which
segments occupy main storage at different
times.
The design of tree structures is
discussed in IBM System/360 Operating
System: Linkage Editor and Loader, but, for
the purposes of this chapter, Figures 6-4
and 6-5 contain a simple example.
The tree in Figure 6-5 represents the
. execution of the PL/I program of Figure
6-4. The program comprises six procedures,
A, B, C, Dr E, and F. The main procedure A
calls procedures Band F.
Procedure B
calls procedure c, which, in turn, calls
procedures D and E.
(Note that only
procedure A requires the option MAIN.)
The main procedure (A) must be in main
storage throughout the execution of the
program.
Since the execution of procedure
B will be completed before procedure F is
called, the two procedures can occupy the
same storage; this is depicted by the lin.:!s
representing the two procedures in Figure
6-5 starting from the common point (node)

r------------------------,I

IA: PROC OPTIONS(MAIN);

I
I
I
I
I
Clli.L B;
I
I
I
I
I
Clli.L F;
I
I
I
I
I
I
IL ________________________
END Ai
JI

r-----------------------,

IB: PROC;

I

I
I

I
I

I

Cl~L

C;

I

I
I
I
I
END
B;
IL ______
•_________________
JI

r------·---------------,

I C: PROC;

I

I
I
I
I
I

I
I
I
I
I

I

C.z:!~LL

D;

CALL E;

I

I
I
I
I
END
C;
IL ______
•_________________
JI

r-----------------------,I
I D: PROC;
I
I
I
I
I
I
I
I
IL ______
END
D;
.. _________________
JI

r------·-----------------,

I
I
I
I
I
I
I
I
I
END
E:
IL ______
._________________
JI
lEi PROC:

r-----------------------,I

IF: PRoe;

I
I
I
I
I
I
I
I
JI
END F;
IL_______________________
Figure 6-4.

Program Suitable for Overlay
structure

X. ProQ.edure B must remain in storage
while procedures C, D, and E are executed,
but procedures D and E can occupy the same

storage; thus the lines representing
procedures D and E start from the node Y.
The degree of segmentation that can be
achieved can be clearly seen from the
diagram. since procedure A must always be
present, it must be included in the root
segment.. Procedures F, 0, and E can
usefully be placed in individual segments,
as can procedures B and C together; there
is nothing to be gained by separating
procedures Band C, since they must be
present together at some time during
execution.

Control. statements
To specify to the linkage editor how you
want a load module structured, use the
control statements INSERT and OVERLAY. You
must include the attribute OVLY in the PARM
parameter of the EXEC statement that
invokes the linkage editor; if you omit
this attribute, the linkage editor will
ignore the control statements.
The OVERLAY statement indicates the
start of an overlay segment. Its format
is:
OVERLAY symbol
Replace 'symbol' with an arbitrary
symbol representing the node at which the
segment starts (for example, X in Figure
6-5). You must specify the symbolic origin
of every segment, except the root segment,
in an OVERLAY statement.
An INSERT statement positions control
sections in an overlay segment. Its format
is:
INSERT control-section-name
Replace 'control-section-name' with the
names of the control sections (that is,
procedures) that are to be placed in the
segment: if you include two or more names
in the statement, separate them with
commas. The INSERT statements that name
the control sections in the root segment
must precede the first OVERLAY statement.

Creatinq-anOverlay structure
The most efficient method of defining an
overlay structure, and the simplest for a
PL/I program, is to group all the OVERLAY
and INSERT statements together and then
place them in the linkage editor input
(SYSIN) after the modules that form the
Chapter 6: Linkage Editor and Loader

75

I
I
I
I Procedure A
I
I

r-------------.L-----------,-,

I
I
Procedure B I
I
I

X

-+-

I
I
Procedure C I
I
I

I
I
I Procedure F
I
I
I

r-------------.L-------------,

I
I
I Procedure D
I
I
I
Figure 6-5.

Y

I
I
I Procedure E
I
I
I

Overlay Tree Structure for Program of Figure 6-4

program. The linkage editor initially
places all the input modules in the root
segment, and then moves those control
sections that are referred to in INSERT
statements into other segments.

//CREX JOB
// EXEC PLILFCLG,PARM.LKED='OVLY'
//PLIL.SYSIN DD *
Source statements for procedure A
*PROCESS

This method has the advantage that you
can use the batch compilation facility of
the compiler to process all the procedures
in one run and place the object modules in
a temporary CONSECUTIVE data set. You can
then place the linkage editor control
statements in the input stream,
concatenating them with the data set that
contains the object modules.
(Do not use
the compiler OBJNM option to name the
object modules: if you do, the NAME'
statements inserted by the compiler will
cause the linkage editor to attempt to
create separate load modules rather than a
single overlay module.)

Source statements for procedure B
* PROCESS
Source statements for procedure C
*PROCESS
Source statements for procedure D
*PROCESS
Source statements for procedure E
*PROCESS
Source statements for procedure F
/*

Figure 6-6 illustrates how you could use
the PL/I cataloged procedure PLILFCLG to
create and execute the overlay structure of
Figure 6-5.
An alternative approach instead of batch
compilation is to compile the procedures
independently and store them as load or
object modules in a private library. You
can then use an INCLUDE statement to place
them in the input to the linkage editor
(SYSLIN).
76

//LKED.SYSIN DD *
OVERLAY X
INSERT B,C
OVERLAY Y
INSERT D
OVERLAY Y
INSERT E
OVERLAY X
INSERT F
/*

Figure 6-6.

compiling, Link-Editing, and
Executing an Overlay Program

If an INSERT statement contains the name
of an €!xternal procedure, the linkage
editor will move only the related program
control. section, which has the same name.
All other control sections established by
the compiler, and all the PL/I library
subrout.ines, will remain in the root
segment.•
It is important that
PL/I library
subroutines be in the root segment, since
the PL/I (F) compiler does not support
exclusive calls (calls between segments
that do not lie in the same path). For
example" in the structure of Figure 6- 5,
procedures in the segment containing 0;
could call procedures in the segments
containing A, B, C, and D, but not in the
segments containing E or F. Procedures in
the segments containing B and C could call
procedures in the segments containing A, B,
C, D, and E, but not in the segment
containing F. A procedure in the segment
containing B may not call a procedure in
the segment containing A if this latter
procedure calls a procedure in the segment
containing F.
Note: The library modules IHETABS and
IHEMAIN must be in the root segment.
Howe'V'er, certain modules may not be
required by all segments, in which case you
can move them into a lower segment. To do
this, compile the procedures using the
compile:r option EXTREF, and then examine
the exbernal symbol dictionary. For
example, if in the structure of Figure 6-5
the module IHESNS is called only by the
segment containing E, you can move into
that seqment by placing the control,
statemeat INSERT IHESNS immediately after
the sta-tement INSERT E.
Similarly, you can move data control
section::; from the root segment to lower
segment::;. For example, to move the static
internal control section for procedure F
into th,e segment containing F, place the
statement INSERT ******FA after the
statement INSERT F. Note that values
assigned to static data items are not
retained when a segment is overlaid.
(A
storage area in static constitutes static
data fo:r this purpose, but still has the
same US4~ as a DSA). Therefore, do not move
static (lata from the root segment unless it
comprises only:
1.

2.

An alternative method of creating an
overlay structure is to obtain object decks
for the procedures that form the program,
and then to intersperse OVERLAY statements
among them in the linkage editor input.
This method requires more care, since you
must move into the root segment all static
internal control sections (unless they are
read-only) and control sections that refer
to external variables not included in a
common area. The linkage editor
automatically places common areas and any
library subroutines that are used in common
by different procedures, in the common
segments of the paths in which they are
referred to. For example, if only
procedures D and E of Figure 6-5 require
the subroutine IHEOST, the linkage editor
will place it in the segment that contains
procedures Band C; but if procedure F also
refers to IHEOST, the linkage editor will
place i t in the root segment.

Linkage Loader
The linkage loader is an operating system
program that creates and executes load
modules. The modules created are always
placed directly into main storage (never in
a library) and executed.
The input to the linkage loader is a
single object or load module or several
object or load modules, or a mixture of
both types. The output is always a single
load module in main storage.
The linkage loader does not support the
linkage editor control statements (ALIAS,
CHANGE, ENTRY, INCLUDE, INSERT, LIBRARY,
NAME, OVERLAY, REPLACE, SETSSI). The
presence of any of these in the job streaIrl
will not be treated as an error; the job
will continue to be processed, and the name
of the statement is printed on SYSLOUT
together with a diagnostic me~sage.
The linkage loader compensates for the
absence of the facilities provided by these
control statements by allowing the
concatenation of both object and load
modules in the data set defined by the
ddname SYSLIN, and by allowing an entry
point to be specified in the EP option of
the PARM parameter (see below in 'Optional
Facilities').

Values set by the INITIAL attribute
and then unchanged (i.e., read-only
da1:a ).

.MODULE STR UCTURE

Values that need not be retained
bet.ween different loadings of the
seqment.

The structure of a module which is the
input to the linkage loader is the same as
that for a module which is the input to the
Chapter 6: Linkage Editor and Lo.ader

77

linkage editor. This structure has already
been described in 'Module Structure,' in
the linkage editor section.

LINKAGE LOADER PROCESSING
The linkage loader processes the input
module or modules in order to resolve all
external references in control sections.
Once this has been accomplished, the load
module is loaded into main storage and
executed. The basic functions are:
1.

Resolution of external references
between control sections in program
modules.

2.

Resolution of other external
references by inclusion of modules
from the PL/I subroutines library
(situated either on a direct-access
device or in main storage).

3.

Automatic editing by deleting
duplicate copies of program modules.

4.

Using the relocation dictionary (RLD)
to obtain absolute addresses for
control sections; if a particular
control section is not in main storage

when required, the RLD is saved until
the control section has been loaded.

In its basic processing mode, which is
illustrated in Figure 6-7, the linkage
loader accepts data from its primary input
source, a data se-t defined by a DD
statement named SYSLIN. For a PL/I
program, this input data is the object
module created by the compiler. The
linkage loader uses the external symbol
dictionary in the input module to determine
whether the module includes any external
references for which there are no
corresponding external symbols in the
module: it attempts to resolve such
references by a method termed automatic
library call.

External symbol resolution by automatic
library call involves a search of the
library defined bya DD statement named
SYSLIB; for a PL/I program this will be the
PL/I subroutine library (SYS1.PL1LIB).
The linkage loader locates the modules in
which the external symbols are defined (if
such modules exist), and incorporates them
in the load module :it is creating. If all
the external references have been resolved
satisfactorily, the load module is
executed.

A
Object and/or
Load Modules

B

C
A

D

B

c

G
SYSLIN
Main Storage
Object 2[
'Load Modu Ies

D

G
SYSLIB -- called automatically when references
were unresolved at the end of input
from SYS LI N •

Figure 6-7.
78

Loader Processing (SYSLIB Resolution)

User' 5 Region

Object and/or
Load Modu les

A

B......

A

..............

References made in B to
0, E, F, and G are
resolved to the link
pack area.

c
SYSLIN

,')-----""""~
Object m:
Load tv\odu les

Link Pack Area

o
Modules in link pack
area must be
reentrant.

,"'--------'
SYSLIB -- called automatically when
references remain unresolved
at the end of input from
SYSLIN and after searching
the link pack area.

Figure 6-8.

Object and/or
Load Modules

Main Storage

Loader processing (Link-Pack Area and SYSLIB Resolution)

_------------ ---_

~------L""E
.,..
0 ........

.",. -

-

-

-

_

The first copy is
loaded

A

B

C

o

SYSLI N

Figure 6- 9.

Main Storage

Automatic Editing

If you are using the MVT or MFT control
program" the linkage loader will first
search t:he link-pack area for library
modules (see Figure 6-8) before searching
the PL/I subroutine library.
(The
link-pack area is an area of main storage
in which frequently used load modules are
stored permanently; they can be accessed by
any job running under MVT.) Library
modules for PL1LIB must not be loaded into
the link-pack area. If there is more than
one copy of a program module in SYSLIN. the
linkage loader will load the first one and
ignore the rest (see Figure 6-9).

Main Storage Reguirements
The minimum main storage requirements for
the linkage loader are:
1.

storage for loader code: At least 10K
bytes.

2.

Storage for data management access
method routines: At least 4K bytes.

3.

storage for buffers and tables used by
the linkage loader: At least 3K bytes.

Chapter 6: Linkage Editor and Loader

79

4~

storage for the program to be
executed.

Thus the minimum main storage required
when a program is to be processed by the
linkage loader is at least 17K bytes for
the linkage loader and its associated
routines and data areas, and, in addition,
whatever amount of main storage is required
for the program to be executed. If the
loader code and the data management access
routines are stored in the link-pack area,
then the amount of main storage required
for program execution is 3K bytes for the
loader data area and, in addition, the
amount required for the problem program,.

linkage loader pz'ogram in the remainder of'
this section.
By using the PARM parameter of the EXEC
statement, you can select one or more of
the optional facilities available with the
linkage loader; these are described in
'Optional Facilities,' below. The use of
the other parameters of the EXEC statement~
is as described in Chapter 7, 'Executing
the Load Module.'

DD STATEMENTS

Job Control Language for Link-Loading
For most purposes, the IBM-supplied
cataloged procedures are sufficent to
provide the job control statements required
for link-loading. 'However, you may want to
supply your own job control statements or
you may want to know which job control
statements are required in order to
construct your own cataloged procedures;
therefore a brief discussion of the
statements required or used by the linkage
loader is given below.
The IBM-supplied cataloged procedures
for the linkage loader are:
PL1LFG
PL1LFCG

Load-and-execute
Compile, load-and-execute

These are fully described in Chapter 8,
'Cataloged Procedures,'which also includes
a description of the methods used to modify
or override the statements in them.

The linkage loader always requires one
standard data set. You must define this
data set in a DD statement with the
standard name SYSLIN.
Three other standard data sets are
optional and if you use them/, you must
define them in DD statements with the
standard names SYSLOUT, SYSPRINT, and
SYSLIB. The four standard data sets are
summarized in Figure 6";'10. The ddnames
SYSLIN, SY3LIB and SYSLOUT for the loader
data sets are those specified at system
generation. Other ddnames for these data
sets may have been specified at system
generation for your installation; if they
have, your job control statements must use
these ddnames in place of those given
above. The IBM-supplied cataloged
procedures PL1LFCG and PL1LFG use the
ddnames shown above; your system programmE~r
will have to modify these procedures if the
ddnames that apply at your installation are
different.

primary Input (SYSLIN)
EXEC STATEMENT
The name of the linkage loader program is
I EWLDRGO; it also has the alias name
LOADER. Either of these can be used in the
basic EXEC statement:

Input to the linkage loader must be
sequential and may be one of the followinq:
1.

// EXEC PGM=IEWLDRGO
// EXEC PGM=LOADER
2.

The alias name LOADER is used in the
IBM-supplied cataloged procedures; this
name will be used for references to the
80

Object module:
a.

Output from the compiler.

b.

One member of a partitioned data
set containing object modules.

Load Module:
One member of a partitioned data set
containing load modules.

r-----------T--'--------------------------------T----------------------------,
ddna:me
I
Function
I possible Device Classes~
I

I

~------.-----+-----------------------------------+----------------------------~

I SYSLIN
I

I Primary input data, normally
I the output from the compiler

I SYSSQ or the input job
I
I stream (specified by DD .) I

~------,-----+----------------------------------+----------------------------~

I SYSLOUT
I

.

I Loader messages and module map
I listing

I SYSSQ, SYSDA.

I

or SYSOUT=A I

I

~------ -----+----------------------------------+-------.---------------------~

I SYSPRINTI PL/I execution-time messages and
I
I problem program output listing'

...

I

I SYSSQ, SYSDA, or SYSOUT=A
I

I

~------ ----+----------------------------------+----------------------------~

.I SYSLIJ3
I
~------

I Automatic call library (usually
I the PL/I subroutine library)

I SYSDA
I

I
. I

...----.L----------------------------------.L----________________________

~

11 SYSSQ

Magnetic-tape or direct-access device
I
I SYSDA Direct-access device
I
____._____________________________________________________________________
JI
Normal printed output class for system output
I SYSOU:P=A
L_~

Figure 6-10.
3.

Linkage-Loader Data sets

A concatenation of object modules,
load modules or a mixture of both
types.

The IBM-supplied cataloged procedure
PL1LFCG includes a SYSLIN DD statement; if
you want. to modify this statement. you must
refer to it by the qualified ddname
GO.SYSLIN. The IBM-supplied cataloged
procedul:e PL1LFLG does not include a SYSLIN
DD statE~ment: you must supply one. using
the qualified ddname GO.SYSLIN.

Loader Listing '(SYSLOUT)
The messages produced by the linkage
loader, the module map that can be produced
by the MAP option (see 'Optional
Facilities,' below). and other information
related to the linkage loader program can
be written onto this data set. The SYSLOUT
data set must be CONSECUTIVE organization
and must have been specified at system
generation; otherwise. all the loader
information will be put out on SYSPRINT. A
printed listing can be produced by
allocating this data set to the system
output class associated with a printer.
This is usually designated by:
//SYSLOUT DD SYSOUT=A

Automatj!c Call Library (SYSLI,B)
The SYSI.IB data set. is searched to resolve
those external references that remain when
all the external symbols that refer to
locations within the program module have
been resolved. This data set is always a
partitioned data set; usually it is the
PL/I subroutine library, SYS1.PL1LIB. but
any library can be used provided it has the
correct ddname. Libraries can be
concatenated; the first library DD
statement must have the ddname SYSLIB. the
others must appear immediately after i t in
the job stream and must have the name field
blank. The concatenated libraries can
contain object or load modules but not a
mixture of both.

The IBM-supplied cataloged procedures
PL1LFCG and PL1LFG include this statement;
if you want to modify the statement, you
must refer to it with qualified ddname
GO.SYSLOUT.

PL/I Execution-Time Messages and Problem
Program Listing (SYSPRINT)
PL/I execution-time messages and output
produced by the problem program are written
on this data set. The data set must be of
CONSECUTIVE organization. A printed
listing can be obtained in the same way as
for the loader information:
//SYSPRINT DD SYSOUT=A

The IBM-supplied cataloged procedures
PL1LFCG and PL1LFG both include a SYSLIB DD
statement. If you want to modify this
statement, you must refer to it using the
qualified ddname GO.SYSLIB.

The IBM-supplied cataloged procedures
PL1LFCG and PL1LFG both include this
statement; if you want to modify it, you
must refer to it using the qualified ddname
GO.SYSPRINT.
Chapter 6: Linkage Editor and LQader

81

Examples
A typical sequence of job control
statements for a compile-load-and-go job
is:

Here the input data sets are:
1.

OBJMOD: An uncataloged data set
containing the object module output
from a compilation.

2.

MODLIB: A cataloged data set
containing a library of load modules;
the member to be included here has the
name MOD55.

3.

IN: An object deck to be included in
the job stream.

//PGEX1 JOB

// EXEC PGM=LOADER
//SYSLIN DD DSNAME=*.PL1L.SYSLIN,
//
DISP=(OLD,DELETE)
//SYSLIB DD DSNAME=SYS1.PL1LIB,DISP=SHR
//SYSLOUT DD SYSOUT=A
//SYSPRINT DD SYSOUT=A
Here a PL/I program has been compiled in a
job step with the step name PL1L: the
resultant object module has been placed in
the SYSLIN data set. Because this module
is to be loaded and executed in the same
job as the compilation, the SYSLIN
statement can use the backwards reference
as shown. If the compilation and
load-and-go steps were in different jobs,
the SYSLIN reference would have to specify
a permanent data set, cataloged or
uncataloged.
'The IBM-supplied cataloged procedure
PL1LFCG includes SYSLIN statements in both
the compile and the load-and-go steps: you
do not need to specify this statement
unless you want to modify it. The
IBM-supplied cataloged procedure PL1LFG
does not include a SYSLIN statement: you
must supply one, using the qualified ddname
GO.SYSLIN.

A more complicated example is given
below; it has three concatenated input data
sets (one of which is an object deck), and
two libraries to be searched for external
references. The job control statements
differ slightly, according to the control
program used:
PCP
// EXEC PGM=LOADER
//SYSLIN DD DSNAME=OBJMOD,
//
UNIT=SYSSQ,
//
VOLUME=SER=30103,
//
DISP=COLD,KEEP)
// DO DSNAME=MOOLIBCMOD55},OISP=SHR
// DO DDNAME=IN
//SYSLIB DD OSNAME=SYS1.PL1LIB,
//
DISP=SHR
// DD DSNAME=PRIVLIB,DISP=SHR
//SYSLOUT DD SYSOUT=A
//SYSPRINT DO SYSOUT=A
//IN DO *
Object deck to be input to the linkage
loader

82

The two libraries to be searched for
external references are the PL/I subroutine
library (SYS1.PL1LIB) and a private
library, PRIVLIB.
The IN DD statement shown here is only
required if you want to include in the job
stream an object deck for input to the
linkage loader. The statement
// DD ODNAME=IN
specifies that the IN data set is to be
concatenated with other data sets to form
the SYSLIN data set. The statement
//IN DO

*

specifies that the IN data set is to be
read from the job stream. Because PCP does
not permit the use of more than one data
set in the input stream for a single job
step" you therefore cannot assign the input
stream data to more than one data set.
This means that you cannot have execution
data in the input stream when there is an
object deck, concatenated as shown, in the~
input stream.
Note: If execution data in the input strealm
is required when using an object deck, the!
linkage editor must be used so that each
input stream data set is in a separate job
step.
If you use the cataloged procedures
PL1LFCG and PL1LFG, you can modify or add
to the statements in these procedures to
generate the sequence described above.
Modified or added statements must be
ref erred to in the correct order; this is::
PL1LFCG:
PL1L.SYSLIN (if you want to modify the
data set for the output from
the compiler)
GO.SYSLIB
GO.SYSLIN
GO.SYSIN
GO.IN

PL1LFG:

Optional Facilities

GO.SYSLIB
GO.SYSLIN
GO.SYSIN
GO.IN
MFT or

CONTROL STATEMENTS

j~VT

// EXEC PGM=LOADER
//SYSLIN DD DSNAME=OBJMOD,
//
UNIT=SYSSQ,
//
VOLUME=SER=30104,
//
DISP=(OLD,KEEP)
// DD DSNAME=MODLIB(MOD55),DISP=SHR
// DD DDNAME=IN
//SYSLIB DD DSNAME=SYS1.PL1LIB,
//
DISP=SHR
// DD DSNAME=PRIVLIB,DISP=SHR
//SYSLOUT DD SYSOUT=A
//SYSPRINT DD SYSOUT=A
//IN DD *

The linkage loader does not support the
linkage editor control statements (ALIAS,
CHANGE, ENTRY, INCLUDE, INSERT, LIBRARY,
NAME, OVERLAY, REPLACE, SETSSI). The
presence of any of these in the job stream
will not be treated as an error; the job
will continue to be processed, and the name
of the statement is printed on SYSLOUT
together with a diagnostic message.
The linkage loader compensates for the
absence of the facilities provided by these
control statements by allowing the
concatenation of both object and load
modules in SYSLIN, and by allowing an entry
point to be specified in the EP option of
the PARM parameter (see below).

Object deck for input to linkage loader
/*

//SYSIN DD

OPTIONS IN THE PARM PARAMETER

*

Execution data, if any, to be placed here

'The input data sets and the two
librarices are as described above.
If you want to include" in the job
stream, both an object deck' and execution
data~ the job control language is less
complicated than with PCP because both MFT
and MVT permit the use of more than one
data set in the, input stream for the same
job step. Hence both IN and SYSIN can have
the DD * notation.
If you use the cataloged procedures
PL'lLFCG or PL1LFG, you can modify or add to
the statements in those procedures to
generatce the sequence described above.
Modified or added statements must be
referred to in the correct order; this is:

The linkage loader provides a number of
optional facilities that you can select by'
including the appropriate keywords from the
following list in the PARM parameter of the
EXEC statement that invokes it:
CALL I NOCALL I NCAL
EP
LET I NOLET
MAP I NOMAP
PRINT I NOPRINT
SIZE
RES I NORES
If any other keywords appear in the PARM
parameter, they will be ignored and when
processing is complete the keywords and a
diagnostic message will be printed on
SYSLOUT.

PARM Parameter Format
PL1LFCG:;.
PL1L.SYSLIN (if you want to modify the
data set for the output from
the compiler)
G9·SYSLIB
GO.SYSLIN
GO.IN
these can be in any order
GO.SYSIN
PL1LFG:
GO.SYSLIB
GO. SY~3LIN
GO.IN
GO.SYSIN

these can be in any order

The basic format of the PARM parameter
field is:
PARM=' [option list] [/pgmparm] ,
where 'option list' is a list of linkage
loader options, and
'pgmparm' is a parameter to be passed
to the main procedure of the PL/I
program to be executed.
The conventions for passing a parameter
to the main procedure of a PL/I program are
described in Chapter 7. In the examples
Chapter 6: Linkage Editor and Loader

83

given below, the program parameter is
referred to as PP.
If both loader options and a program
parameter occur in the PARM parame'ter, the
loader options are given first and are
separated from the program parameter by a
slash. If there are loader options but no
program parameter, the slash is omitted.
If there is more than one option, the
option keywords are separated by commas.
The PARM parameter field can have one of
three formats:
1.

If the special characters '/' or '='
are used, the field must be enclosed
in single quotes:
PARM=' MAP, EP=FIRST/PP'
PARM='MAP,EP=FIRST'
PARM='/PP'

2.

If these characters are not included,
and there is more than one loader
option, the options must be enclosed
in parentheses:
PARM= (MAP, LET)

3.

If these characters are not included,
and there is only one loader option,
neither quotes nor parentheses are
required:
PARM=MAP

If you want to modify the PARM parameter
options specified in a cataloged procedure,
you must refer to the PARM parameter by the
qualified name PARM.procstepname, for
example, PARM.GO.
CALL I NOCALL I NCAL
The CALL option specifies that an attempt
to resolve external references will be made
by an automatic search of the data set
named in the SYSLIB DD statement. If this
statement does not exist in the job stream,
the option is ignored.,
The NOCALL and NCAL options specify that
no automatic search will be made. The term
'NCAL' is included to preserve
compatibility with the linkage editor.

LET I NOLET
The LET option specifies that the linkage
loader will try to execute the problem
program even if a severity 2 error
condition has been found.
The NOLET option specifies that, if a
severity 2 error condition has been found,
the linkage loader will not execute the
problem program.

MAP I NOMAP

The MAP option specifies that the linkage
loader will produce, on SYSLOUT, a map of
the load module to be executed. This map
includes a list of the external names and
their absolute addresses, a list of the
pseudo-registers, the total length of the
module, and the absolute address of its
entry point. If there is no SYSLOUT DD
statement, the option will be ignored. The
module map is described fully in 'Listing'
below.

PRINT I NOPRINT
The PRINT option specifies that the SYSLOUT
data set will be opened and used for
diagnostic messages and other linkage
loader information.
The NOPRINT option specifies that the
SYSLOUT data set will not be opened.

SIZE
The SIZE option specifies the maximum
amount of main storage, in bytes, that can
be used by the linkage loader to process
and execute the problem program. Code the
option in one of the following formats:

EP
The EP option specifies the entry-point
name.
EP=epname
84

where 'epname' is an external name which is
to be assigned as the entry point of the
program to be executed. If all the input
modules are load modules, you must specify
EP=IHENTRY.

SIZE=10K
SIZE=(lOK)
SIZE=10240
SIZE=(10240)

RESINORES

MODULE MAP

The RES option specifies that an attempt to
resolve external references will be made by
an automatic search of the link-pack area.
This search will be made after the primary
input has been processed but before the
SYSLIB data set is opened.

If the MAP option is specified, a module
map appears in the SYSLOUT listing. The
map lists all the control sections in the
module to be executed, and all the entry
names (other than the first one) in each
contrbl section. The information for each
reference is:

'I'he NORES option specifies that the
link-pack area will not be searched.

1.

The control-section or entry-point
name.

2.

An asterisk, if the control section is
in a module loaded from the SYSLIB
data set.

3.

An

DEFAULT OPTIONS
Defaults for all the options except EP can
be established at system gemerati'on. If no
such de:faults were specified, the linkage
loader i:lSsumes defaults as follows:
CALJ["
RES

SD

Section definition: the name of
the control section.

LR

Label reference: identifying an
entry point in the control
section other than the primary
entry point.

CIM

Common area: an EXTERNAL file,
or a non-string element variable
declared STATiC EXTERNAL without
the INITIAL attribute.

NOLET, NOMAP, PRINT, SIZE=100K,

It is your responsibility to find out the
defaults in operation at your installation.

4.

Listing
The linkage loader can provide listings on
the SYSI,OUT data set: the SYSPRINT data set
is used by the problem program. The
contents; of each is:
Data Set

identifier, as follows:

Absolute address of the control
section or entry point.

Each reference is printed left to right
across the page and starts at a tab
position. This gives the impression that
the references are arranged in columns, but
the correct way to read the map is
line-by-line, not down each column.

Contents

SYSLOUT

Linkage loader explanatory
messages and diagnostic
messages, and (optionally)
a module map

SYSPRINT

PL/I execution-time diagnostic
messages: problem program
output

The SYSLOUT listing is described here;
the SYSPRINT listing is described in
Chapter 7, 'Executing the Load Module.'

The module map is followed by a similar
listing of the pseudo-registers. The
identifier used here is PR, and the address
if the offset from the beginning of the
pseudo-register vector (PRV). The total
length of the PRV is given at the end.
The total length of the module to be
executed, and the absolute address of its
primary entry point, are given after the
explanatory messages and before the
diagnostic messages.

'l'he items in the SYSLOUT listing appear
in the following sequence:
EXPLANATORY ERROR OR WARNING MESSSAGES
1.

A statement identifying the level of
linkage loader used.

2.

Module map (if specified).

3.

Explanatory error or warnjng messages.

4.

Diaqnostic messages.

The linkage loader always lists details of
any error or warning conditions that it
discovers during processing. The format of
the messages is given in 'Control
Statements and Errors,' in the linkage
editor section of this chapter.
Chapter 6: Linkage Editor and Loader

85

DIAGNOSTIC MESSAGES

probable cause of the errors noted in them,
and suggests how to rectify these errors.

When the module to be executed has been
processed, the linkage loader prints out in
full all the diagnostic messages referred
to above. IBM System/360 Operating Syst~~
Linkage ditor and.Loader contains
explanations of these messages and the

The warning message IEW100l almost
always appears in the listing. The
explanation for this is the same as that
for IEW0461, described above in 'Diagnostic
Message Directory,' in the linkage editor
section of this chapter.

86

Chapter 7:

Executing the Load Module

Introduction

Jobs Using the Linkage Editor

To execute a program, it must be in the
form of a load module or an object module.
If in load-module form you must use an EXEC
statemE~nt to request the job scheduler to
load and execute. If in object-module form
you must use an EXEC statement to request
the job scheduler to load and execute the
loader which will process the module and
pass control to it.

The data set exists in a library created in
a previous job step of the same job, 'or in
a previous job.
Library Created' in' a ,Previous Job Step:
The basic reference is:
//stepname EXEC PGM=*.prevstepname.ddname
where 'prevstepname' is the name of the job
step in which the library is created.

~jodules for execution are selected from
one of two sources:

1.

2.

A partitioned data set which is a
module library. The modules are
either object modules created by the
compiler or load modules created by
the linkage editor.
A sequential data set which is an
object module created by the compiler.

partitioned data sets and module
librariles are des cribed in Chapter 12,
sequential data sets are described in
Chapter 9.

If the data set is the output data set
created by the linkage editor, code:
//stepname EXEC PGM=*.linkname.SYSLMOD
where 'linkname' is the link-edit stepname.
If you use the cataloged procedures
PL1LFCLG or PL1LFLG, the code generated is:
//GO EXEC PGM=*.LKED.SYSLMOD
Library, Created'inaPrevious'Job: If the
library is a system library (SYS1.LINKLIB),
code:
//stepname EXEC PGM=progname

This chapter describes the selection of
the object or load module for execution,
the job control statements required for
load module execution, and the messages and
other da.ta printed on the output listing.

where 'progname' is the member name of the
module in the system library.

Load M()dule Processing

If the library is a private library used
as a step library, the syntax is the same
as for the system library. The private
library must be identified in a STEPLIB DD
statement which follows the EXEC statement
that initiates the job step.

IDENTIFYING THE MODULE

If the library is a private library used
as a job library, the syntax is the same as
for the system library. The private
library must be identified in a JOBLIB DD
statement placed immediately after the JOB
statement.

The data. set containing the module to be
selected for execution is identified in one
of two ways:
1.

2.

Jobs using the linkage editor: The
data set is identified in the PGM
parameter of the EXEC statement for
the execution job step.
Jobs using the linkage loader: The
data set is identified in a DD
statement with the name SYSLIN in the
execution job step.

Jobs Using the Linkage Loader
The data set exists in a library or is a
single module, created in a previous job
step of the same job or in a previous job.
Library Created' in' a-Previous Job step:
The basic reference is:
Chapter 7: Executing the Load Module

87

//SYSLIN DD DSNAME=*.stepname.ddname,
//
DISP=(disp)

//SYSIN DD DSNAME=dsname,DISP=(disp)

where '*.stepname.ddname' refers to the
name of the DD statement that
describes the data set in which the
member of the library is created.
'disp' is the set of terms for the
disposition of the data se1:: before
and after the job step.
If you use the cataloged procedure
PL1LFCG with input from a library, you must
override the SYSLIN DD statements in both
job steps. The ddnames for the input data
set you are using must be qualified as
PL1L.SYSLIN and GO.SYSLIN respectively. If
you use the cataloged procedure PL1LFG, you
must supply the SYSLIN DD statement, using
//GO.SYSLIN.

where 'dsname' is the name of the temporary
or permanent dat~ set.
., disp' is as defined previously in
this chapter.
The cataloged procedure PL1LFCG generates
the appropriate SYSLIN DD statement. If
you use the cataloged procedure PL1LFLG,
you must supply this statement, using the
qualified ddname //GO.SYSLIN.
Module Created ina Previous Job: The
reference for the SYSLIN DDstatement
depends on whether the data set is
cataloged or not.. For a cataloged data
set, code:
//SYSLIN DD DSNAME=dsname,DISP=(disp)

Library Createdina.PreviousJob: If the
library is the system library, code:
//SYSLIN DD DSNAME=dsname,DISP=(disp)

where 'dsname' is the name of the catalog led
data set.
'disp' is as defined previously in
this chapter.

where 'dsname' is the name of the member of
the library.
'disp' is as defined previously in
this chapter.
If the library is a private library, the
syntax is the same as for the system
library.

If the data set is uncataloged, code:
//SYSLIN DD DSNAME=dsname,
//
DISP=(disp),
//
VOLU~volume,
//
UNIT=unit
where 'dsname' is the name, of the data set.

If the library is neither cataloged nor
in a job library, it must be described
fully in the SYSLIN DD statement.
(A
cataloged data set, which can be a library
or a single module, has its name in the
system catalog and can be called by
specifying the name only.) Code:

'disp', 'volume', and 'unit' are as
defined previously in this chapter.
If you use the cataloged procedures
PL1LFCG or PL1LFG, the same considerations
apply ap for libraries created in a
previous job step.

//SYSLIN DD DSNAME=dsname(mbname),
//
DISP=(disp),
//
VOLUME=volume,
//
UNIT=unit

Job Control Language for Execution

where 'dsname' is the name of the library.
'mbname' and 'disp' are as defined
previously in this chapter.
'volume' is the set of terms defining
the volume and its usage.
'unit' specifies the storage device.
If yo~ use the cataloged procedure
PL1LFCG or PL1LFG, the same considerations
apply as for a library created in a
previous job step.
Module Created ina.Previous·Job step:
basic reference is:
88

The

You can use a cataloged procedure to
generate the job control statements or you
can supply them yourself. The IBM-supplied
cataloged procedures that apply to this
step are:
PL1LFCG
PL1LFCLG
PL1LFG
PL1LFLG

Compile, load-and-execute
Compile, link-edit, and execute
Load-and-execute
Link-edit, and execute

These procedures are described in
Chapter 8, 'Cataloged procedures,' which
includes an account of the methods used to
modify or overwrite any of the statements
in the procedures.

If you want to supply your own job
control statements, the statements required
for thE:! execution job step are described
below.

EXEC

S'.l~ATEMENT

PARK ,Parameter
The PL/I CF) compiler provides a facility
for passing, in this job step, a single
parameter to the main procedure of the PL/I
program. The data specified in the PARM
parameter field can be up to 100 characters
long and must be enclosed in quotation
marks. Any character in the character set
available can be specified. The associated
parameter in the main procedure should be
declared CHARACTER(100) VARYING.

The basic form of the EXEC statement
require~s only the PGM parameter:
// EXEC PGM=reference
where 'reference' has one of two forms:
1.

Jobs using the linkage editor: a
reference to the data set containing
the load module. This has already
be'en described in 'Identifying the
Load Module' in this chapter.

2.

Jobs using the linkage loader: the
n~ne of the loader program:

The PARM parameter is a useful means of
passing data to a load module. For
example, if the SYSIN file is already
associated with a user data set, any extra
data required can be quickly inserted by
being specified in this parameter. Another
use is to pass data that can be employed to
determine how the program will be executed
and which category or categories of output
will be produced. Both the PL/I CF)
compiler and the linkage editor use the
PARM parameter in this way; the characters
passed represent various options which
determine, for example, the information to
be printed on the output listing.

PGM=LOADER
ThE:! use of the linkage loader is
described in Chapter 6, 'Linkage
Editor and Loader.'
WhilE~ the PGM parameter is the only
mandatOl:Y parameter as far as the operating
system is concerned, some or all of the
other parameters available may be mandatory
at your installation. The use of these
parametE~rs is discussed here.

ACCT

PaI:~ameter

The accounting procedure at your
installation may require you to provide
information here, if each job step is to be
charged separately.

COND Parameter
This is a useful parameter if your
execution job step is dependent on the
successful completion of a previous job
step. The use of the EVEN and ONLY
subparam,eters allows you precise control
over the conditions under which this job
step can be executed.
'

If you want to use the PARM parameter
for the second of these purposes, you
should include, at the beginning of your
PL/I program, code to convert the parameter
characters to variables, and code to set a
series of program switches. For example:
STOCK: PROCCINPARM) OPTIONS(MAIN);
DCL INPARM CHAR(100) VAR,
1 VALUES BASEDCP),
2 (TERMA,
TERMB,
TERMC,
TERMO,
TERME) ,CHAR C1) ,
2 NUMBER PIC'9999',
2 SPEC CHAR(l),
2 CTCHAR CHAR(3),

P=ADDR (INPARM) ;
Ll:IF TERMA=TERMB THEN GO TO ••• ;
ELSE IF CTCHAR='I/M' THEN ••• ;
L2:IF TERMC,=TERMD THEN GO TO ••• ;
ELSE GO TO ••• ;
L3:IF TERMA=TERME THEN GO TO ••• ;
ELSE IF SPEC='.' THEN ••• :
L4:IF NUMBER~1000 THEN ••• :
ELSE IF NUMBER<10 THEN ••• :

END STOCK:

Chapter 7: Executing the Load MO,dule

89

If this program, once compiled and
link-edited (or loaded), is executed wit:h
the following EXEC statement:
I I EXEC PGM= ••• ,PARM='ABCDE1414*I/M'

then the elements of the structure variable
VALUES will have the following values:
TERMA
TERMB
TERMC
TERMD
TERME
NUMBER
SPEC
CTCHAR

=
=
=
=

=
=
=

'A'
'B'

'c'

'D'
, E'
'1414'
' *'
'11M'

REGION Parameter
If your load module is executed using the
MVT control program, you can specify a
region size for the job step. For details
of this usage, see 'MVT Control Program' in
Chapter 4, 'Job Initialization.'
A region size specified in the EXEC
statement is always overriden by a region
size specified in the JOB statement. If a
region size is not specified in the JOB
statement, the size specified in the EXEC
statement is assumed.
If neither is
specified, the installation default (if
any) is applied.

ROLL Parameter
These values will then be used in the four
switching statements to determine which
parts of the program will be executed and
therefore what output the program will
produce.
The result of the pointer assignment
statement is that the elements in VALUES
now have the appropriate values from the
parameter field.
If any character in the
parameter field is omitted for a particular
job, it must be replaced by a blank: this
will create a blank in the corresponding
VALUES element. The existence of a blank
or blanks in these variables must be
considered when the switching statements
are coded, in order to avoid erroneous
switching.
GET STRING or SUBSTR could be used in
place of the pointer assignment, if the
context was such that they offered an
advantage.

If your load module is executed using the
MVT control program, you can obtain extra
space dynamically in main storage by means
of this parameter.

TIME Parameter
If your load module is executed using the
MVT control program, you can specify the
maximum time that this job step can use the
CPU, by means of this parameter. The time
specified here overrides the default time
for the job class. This parameter is
useful if there is a possibility that your
program might go into a permanent loop or'
if your program requires a long execution.
time.

STANDARD DD STATEMENTS
DPRTY Parameter
If your load module is executed using the
MVT control program, you can specify the
priority for each job step. For details of
this usage, see 'MVT Control Program' in
Chapter 4, 'Job Initialization.'
The priority value specified in the EXEC
statement is always overridden by a
priority value specified in the JOB
statement; if no priority is specified in
the JOB statement, the value specified in
the EXEC statement is assumed.
I:f neither
statement includes a priority parameter,
the installation default (if any) is
applied.
90

Three standard data sets can be used for
the execution job step. These are:
Purpose
Input
Output
Dump

ddname
SYSIN
SYSPRINT
SYSABEND, SYSUDUMP,
or PL1DUMP

Of these, only SYSPRINT is necessary in
every job. If it is omitted, the system
messages will be put out on the operator" s
console and the other output data will he
lost. If your installation has
multiple-console support (MCS), you must
find out on which console or consoles the
system messages will appear.

Input

~SYSIN)

Dump (SYSABEND, SYSUOUMP, '" or PL1DUMP)

If you want to include data in the input
stream., you can do so by means of a DD
statemE:!nt of the form: / /ddname DO *
immediately preceding the data.
(A data
set in the input stream does not have to be
called SYSIN; it can have any name.) The
data should be 80-byte F-format unblocked
records (for example, punched cards).
Code:
//SYSIN DD

*

input: data

If you want to obtain a printed listing of
any of these dumps, code one of the
following:
/

/SYS}~BEND

DO SYSOUT=A

//SYSUDUMP DD SYSOUT=A
//PL1DUMP DD SYSOUT=A
For further information on DD statements
for dumps, see Chapter 14, 'other
Facilities of the Operating System'.

/*

The SYSIN DD statements with this notation
must be: the last statement in the job
control statements for the job step for
PCP.
If the data includes the characters
// in col.umns 1 and 2 replace //SYSIN DD *
by //SYSIN DD DATA.
The IBM-supplied cataloged procedures
PL1LFCG# PL1LFCLG, PL1LFG, and PL1LFLG do
not include a SYSIN DD statement. If you
want to use one, you must qualify the
ddname 1with the step name, that is, code
//GO.SYSIN.

Output (SYSPRINT)
System a.nd problem program output can be
put out through the system output streams.
The advantage of this is that each output
stream can be associated with an output
device, such as a printer; this device is
speci f,ied in the SYSOUT parameter of the DD
statement for the output data set. If, as
is usual, output stream A is associated
with a printer, the statement
//SYSPRINT DD SYSOUT=A
will result in all SYSPRINT data appearing
in a printed listing.
The SYSPRINT data can include both
system output (for example, diagnostic
messages. from job control statements) and
problem program output. If you want system
and' problem program ouput to'be on separate
listings, you can arrange this by means of
the MSGCLASS parameter in the JOB
statement, see Chapter 4, 'Job
Initialization.'

USER DD STATEMENTS
In execution of your program, you can
create data sets or you can access data
sets already created. For the types of
data set that can be Qsed with a PLiI
program, see Chapter 9, 'Data sets and PL/I
Files.' For the methods of creating or
accessing these data sets, see Chapter 10,
'stream-Oriented Transmission,' and Chapter
11, 'Record-Oriented Transmission.'
The IBM-supplied cataloged procedures
PLILFCG, .PL1LFCLG, PLILFG, and PL1LFLG do
not include statements for user data sets.
If you want to include such statements, you
must code them with the ddname qualified
with the step name, that is, code
//GO.ddname.

Listing
CONTENTS OF SYSPRINT LISTING
The SYSPRINT listing that you obtain with
your job consists of some or all of the
following entries, usually in the sequence
given:
1.

Job output, in the format established
by any PUT FILE(SYSPRINT) statements
in your PL/I source program.

2.

Execution-time diagnostic messages
produced by the PL/I library. These
have the format:
lHEdddI

Message text

where'ddd' is a decimal number.
The IBM-supplied cataloged procedures
PL1LFCG, PL1LFCLG, PL1LFG, and PLILFLG
include this statement in the execution job
step.

3.

Dump of part of or all main storage.
The important information here for you
is the completion codes.

Chapter 7: Executing the Load Module

91

4.

Diagnostic messages from any operating
system facility which has an interface
with your PL/I program. For example,
checkpoint or sort messages would be
printed here.

5.

Job scheduler messages, showing the
final disposition of the data sets
used in the job. These messages are
printed in pairs, as follows:
IEFdddI
IEFdddI

Data set name Disposition
Volume serial number of
data set

where 'ddd' is a decimal number. The
two messages numrrers are always the
same for each pair.
6.

7.

Step completion information. This
depends on your installation but will
probably contain the step name, step
time, clock time, date and return
code. The return code is always zero
unless you include statements in your
PL/I program to create a return code.
Job completion information (if this is
the last step). This depends on your
installation but will probably include
job name, job time, clock time, and
date.

Of these, only the job scheduler messages
and the step and job completion information
will appear in every job. The other items
will depend on the nature of the source
.program and how successfully it executes.

RETURN CODES
The COND parameter causes the job scheduler
to test the return codes put out at the end
of every job step. These codes indica·te
the degree of success of the job step: they
show, for example, whether the program can
be expected to complete normally and
whether the output data will be as
required. Such codes are returned as a
matter of course at the end of the
compilation and linkage-editor job steps
(see Chapters 5 and 6 respectively),
therefore you do not have to take any
action to supply them.
When the execution job step terminates,
a return code is produced to indicate
whether or not it terminated successfully.
Termination

92

Zero

Normal

Non-zero (value depends
on cause)

Abnormal

The return code is provided by the PL/J[
library error~handlingsubrbutines. You
can generate a return code in your program
by coding the statements shown below; this
code is added to the value provided by the
PL/I library and is printed on the listing.
Single-task processing:
DCL IHESARCENTRY(FIXED BINARY(31,O»;

CALL IHESARC(expression):
Multitask processing:
DeL IHETSAC ENTRY(FIXED BINARY(31,O»;

CALL IHETSAC(expression):
Note: The entry point IHETSAC is applicable
to the major task only.
On evaluation, the expression supplies the
required value for the return code.
IHESARC and IHETSAC must be declared as
fullword binary, otherwise errors may occur
in the returned code because of the
halfword binary feature.

Communication with Program during Execution
The DISPLAY statement provides a means of
communicating with the load module for the
PL/I program during execution. The program
can put out, on the operator's console, aL
message of up to 72 characters in length •..
If a reply is expected, the syntax of thE~
reply message must use a 2-digit code
provided by the operating system. The
operator uses this code as a prefix to the
reply message.
If your installation has
multiple-console support (MCS), you must
find out on which console your messages
will appear. The PL/I implementation of
the route and descriptor codes in MCS is
restricted to:
PL/I Statement

Route
Code

DISPLAY
DISPLAY with REPLY

2
1

Descriptor
Code
7

7

If SYSPRINT is not available, the consol.e
on which error messages will appear is
designated by route code 11 and descriptor
code 7. These error messages will be
truncated to 72 characters if they exceed
this length.

Chapter 8:

Introduction

Cataloged Procedures

The standard PL/I cataloged procedures
are:

A cataloged procedure is a set of job
control statements stored in a system
library, the procedure library
(SYS1.PROCLIB). It comprises one or more
EXEC statements, each of which may be
followed by one or more DD statements. You
can retrieve the statements by naming the
catalog,ed procedure in the PROC parameter
of an EKEC statement in the input job
stream. When the job scheduler encounters
such an EXEC statement, it replaces it in
the input stream with the statements of the
catalogced procedure.
The use of cataloged procedures saves
time and obviates errors in coding
frequent:.ly used sets of job control
statements. Even if the statements in a
catalogE:!d procedure .do not match your
requirements exactly, you can easily modify
them or add new statements for the duration
of a job.
This chapter describes seven cataloged
supplied by IBM for use with the
(F) compiler, and explains how to invoke
them and how to make modifications to them ..

procedw~es

PL/I Cat:aloged Procedures supplied by IBM
The following paragraphs do not fully
describe: the individual statements of the
IBM cataloged procedures, since all the
parameters are discussed elsewhere in this
manual. Note that the cataloged procedures
described here are the standard PL/I
cataloged procedures. It is recommended
that each installation review these
procedur~~s and modify them to obtain the
most efficient use of the facilities
available and to allow for installation
conventions: refer to 'Permanent
Modification,' at the end of this chapter.

PL1DFC

Compile and punch object deck

PL1LFC

compile and place object
module on magnetic-tape or
direct-access device

PL1LFCL

Compile and link-edit

PL1LFCLG

Compile, link-edit, and execute

PL1LFLG

Link-edit and execute

PL1LFCG

Compile"

PL1LFG

Load-and-execute

load-and-execute

COMPILE AND PUNCH OBJECT DECK (PL1DFC)
The cataloged procedure PL1DFC (Figure 8-1)
comprises only one job step, in which the
(F) compiler is executed with the DECK
option.
(IEMAA is the symbolic name of the
compiler.) In common with the other
cataloged procedures that include a
compilation job step, PL1DFC does not
include a DD statement for the compiler
input data set; you must always supply an
appropriate statement with the qualified
ddname PL1D.SYSIN. Because the EXEC
statement includes the options DECK and
NOLOAD, the compiler will place the object
module in card-image form in the data set
defined by the DD statement SYSPUNCHi
conventionally, the system output device of
class B is always a card punch.

COMPILE AND WRITE OBJECT MODULE (PL1LFC)
The cataloged procedure PL1LFC (Figure 8-2)
is similar to PL1DFC: it differs only in
that the options specified for the
compilation are LOAD and NODECK, and the DD

//PL1D EXEC PGM=IEMAA,PARM='DECK,NOLOAD',REGION=52K
//SYSPRINT DD SYSOUT=A
//SYSPUNCH DD SYSOUT=B
//SYSUT3 DD DSNAME=&&SYSUT3,UNIT=SYSDA,SPACE=(80,C250,250»,
//
DCB=BLKSIZE=80
//SYSUTl DD DSNAME=&&SYSUT1,UNIT=SYSDA,SPACE=(1024,(60,60)"CONTIG),
//
SEP=(SYSUT3,SYSPUNCH),DCB=BLKSIZE=1024
F-igure 8--1.

cataloged Procedure PL1DFC (Compile and Punch Object Deck)
Chapter 8: Cataloged Procedures

93

//PL1L EXEC PGM=IEMAA,PARM='LOAD,NODECK',REGION=52K
//SYSPRINT DO SYSOUT=A
//SYSLIN DO DSNAME=&&LOADSET,DISP={MOD,PASS),UNIT=SYSSQ,
//
SPACE=(SO,(250,100»
//SYSUT3 DO DSNAME=&&SYSUT3,UNIT=SYSDA,SPACE=(SO,(250,250»,
//
DCB=BLKSIZE=SO
//SYSUT1 DD DSNAME=&&SYSUT1,UNIT=SYSDA,SPACE=(1024, (60,60) ,.CONTIG),
//
SEP=(SYSUT3,SYSLIN),DCB=BLKSIZE=1024
Figure S-2.

Cataloged Procedure PL1LFC (Compile and Write Object Module)

//PL1L EXEC PGM=IEMAA,PARM='LOAD,NODECK',REGION=52K
//SYSPRINT DO SYSOUT=A
//SYSLIN DD DSNAME=&&LOADSET,DISP= (MOD., PASS) , UNIT=SYSSQ,
//
SPACE=(SO,(250,100»
//SYSUT3 DD DSNAME=&&SYSUT3,UNIT=SYSDA,SPACE=(SO,(250,250»,
//
DCB=BLKSIZE=80
/ /SYSUT1 DD DSNAME=&&SYSUT1, UNIT=SYSDA,SPACE= (1024, (60,,60) , ,CONTIG),
//
SEP=(SYSUT3,SYSLIN),DCB=BLKSIZE=1024
//LKED EXEC PGM=IEWL,PARM='XREF,LIST',COND=(9,LT,PL1L),REGION=96K
//SYSLIB DD DSNAME=SYS1.PL1LIB,DISP=SHR
//SYSLMOD DD DSNAME=&&GOSET(GO),DISP=(MOD,PASS),UNIT=SYSDA,
//
SPACE= (1024, (50,20,1) ,RI.SE)
//SYSUT1 DD DSNAME=&&SYSUT1,UNIT=SYSDA,SPACE=(1024,(200,20»,
//
SEP=(SYSLMOD,SYSLIB),DCB=BLKSIZE=1024
//SYSPRINT DD SYSOUT=A
//SYSLIN DO DSNAME=&&LOADSET,DISP=(OLD,DELETE)
//
DD DDNAME=SYSIN
Figure 8-3.

Cataloged Procedure PL1LFCL (Compile and Link-Edit)

statement SYSLIN replaces SYSPUNCH. The
LOAD option causes the compiler to place
the object module, in a form suitable for
input to the linkage editor, in the data
set defined by the DD statement SYSLIN.
This DD statement defines a temporary data
set named &&LOADSET, since the cataloged
procedure assumes that a link-edit job step
will follow. If you want to retain the
load module, you must substitute your own
DD statement for the one supplied. Input
data for this cataloged procedure requires
the qualified ddname PL1L.SYSIN.
COMPILE AND LINK-EDIT (PL1LFCL)
The cataloged procedure PL1LFCL (Figure
8-3) comprises two job steps: PL1L, which
is identical with cataloged procedure
PL1LFC, and LKED,'which invokes the linkage
editor (symbolic name IEWL) to link-edit
the object module produced in the first
step.
Input data for the compilation job step
requires the qualified ddname PL1L.SYSIN.
The COND parameter in the EXEC statement
LKED specifies that this job step should be
bypassed if the return code produced by the
compiler is greater than 9 (that is, if a
severe or termination error occurred during
compilation) •
94

The DD statement SYSLIB specifies the
PL/I subroutine library, from which the
linkage editor will read appropriate
modules for inclusion in the load module.

The linkage editor always places the
load modules it creates in the library
defined by the DO statement SYSLMOD. This
statement in the cataloged procedure
specifies a new temporary library &&GOSET,
in which the load module will be placed Clnd
given the member name GO (unless you
specify the OBJNM option for the
compilation). In specifying a temporary
library, the cataloged procedure assumes
that you will execute the load module in
the same job; if you want to retain the
module, you must substitute your own
statement for the DO statement SYSLMOD.

The sta temen-t DDNAME=SYSIN following it.he
DD statement SYSLIN allows you to
concatenate a data set defined by a DD
statement with the name SYSIN with the
primary input to the linkage editor; for
example, you could place linkage-editor
control statements in the input stream by
this means.

//PL1L EXEC PGM=IEMAA,PARM='LOAD,NODECK',REGION=52K
//SYSPRINT DD SYSOUT=A
//SYSLIN DD DSNAME=&&LOADSET,DISP=(MOD,PASS),UNIT=SYSSQ,
//
SPACE=(80,(250,100»
//SYSUT3 DD DSNAME=&&SYSUT3,UNIT=SYSDA,SPACE=(80,(250,250»,
//
DCB=BLKSI ZE=8 0
//SYSUTl DD DSNAME=&&SYSUT1,UNIT=SYSDA,SPACE=(1024,(60,60)"CONTIG),
//
SEP=(SYSUT3,SYSLIN),DCB=BLKSIZE=1024
/ /LKED I~XEC PGM= IEWL, PARM= I XREF, LIST' , COND= ( 9, LT, PL1L), REGIONc:96K
//SYSLIB DO DSNAME=SYS1.PL1LIB,DISP=SHR
//SYSLMOD DD DSNAME=&&GOSET(GO),DISP=(MOD,PASS),UNIT=SYSDA,
//
'SPACE=(1024,(50,20,1),RLSE)
//SYSUTl DD DSNAME=&&SYSUT1, UNIT=SYSDA, SPACE = (1024, (200,20»,
//
SEP=(SYSLMOD,SYSLIB),DCB=BLKSIZE=1024
//SYSPRl:NT DD SYSOUT=A
//SYSLIN DD DSNAME=&&LOADSET,DISP=(OLD,OELETE)
//
DO DDNAME=SYSIN
/ /GO EXEC PGM=*. LKEO. SYSLMOD, COND= ( (9; LT, LKED) " (9, LT, PLlL) )
//SYSPRINT DO SYSOUT=A
Figure 8,-4.

Cataloged Procedure PL1LFCLG (Compile, Link-Edit, and Execute)

COMPILE, LINK-EDIT, ANO EXECUTE (PL1LFCLG)
The cataloged procedure PL1LFCLG (Figure
8-4) comprises three job steps, PL1L and
LKED, which are identical with the two job
steps of PL1LFCL, and GO, in which the load
module created in the step LKEO is
executede The third step will be executed
only if no severe or termination errors
occur in the preceding steps.
Input data for the compilation job step
requires the qualified ddname PL1L.SYSIN;
input data for the execution job step
requires the name GO.SYSIN.

LINK-EDIT AND EXECUTE (PL1LFLG)
The cataloged procedure PL1LFLG (Figure
8-5) comprises two job steps, LKED and GO,
which arE~ similar to the steps of the same
names in PL1LFCLG.
In the job step LKED,
the DD statement SYSLIN does not define a
data set, but merely refers the job
scheduler to the DD statement SYSIN, which
you must supply with the qualified ddname
LKED.SYSIN. This DO statement defines the

data set from which the linkage editor will
obtain its primary input. Execution of the
step GO is conditional on successful
execution of the step LKED only.

COMPILE, LOAD AND EXECUTE (PL1LFCG)
The cataloged procedure PL1LFCG (Figure
8-6) achieves the same result as PL1LFCLG.
However, instead of using three job steps
(compile" link-edit, and execute), it has
only two (compile, and load-and-execute).
In the second job step of PL1LFCG, the
operation system loader program is
executed; this program link-edits the
object program produced by the compiler and
then executes the load module immediately.
Input data for the compilation job step
requires the qualified ddname PL1L.SYSIN.
Note that the REGION parameter of the
EXEC statement GO speoifies 96K bytes.
Since the loader requires about 17K bytes
of main storage, there are about 79K bytes
for your program: if this is likely to be
insufficient, you must modify the REGION
parameter.

//LKED EXEC PGM=IEWL,PARM='XREF,LIST',REGION=96K
//SYSLIB DO DSNAME=SYS1.PL1LIB,DISP=SHR
//SYSLMOD DD DSNAME=&&GOSET(GO),DISP=(MOD,PASS),UNIT=SYSDA,
//
SPACE=(1024,(50,20,1),RLSE)
//SYSUT1 DD DSNAME=&&SYSUT1, UNIT=SYSDA,SPACE= (1024, (200,20»,
//
SEP=(SYSLMOD,SYSLIB),DCB=BLKSIZE=1024
//SYSPRINT DD SYSOUT=A
//SYSLIN DD DDNAME=SYSIN
//GO EXEC PGM=*.LKED.SYSLMOD,COND=(9,LT,LKED)
//SYSPRINT DD SYSOUT=A
Figure 8-5.

cataloged Procedure PL1LFLG (Link-Edit and Execute)
Chapter 8: cataloged Procedures

95

//PL1L EXEC PGMFIEMAA,PARM:'LOAD,NODECK',REGION=52K
//SYSPRINT DD SYSOUT=A
//SYSLIN DD DSNAME=&&LOADSET,DISP=(MOD,PASS),UNIT=SYSSQ,
//
SPACE=(80, (250,100»
//SYSUT3 DD DSNAME=S&SYSUT3,UNIT=SYSDA,SPACE=(80,(250,250»,
//
DCB=BLKSIZE=80
//SYSUT1 DD DSNAME=SSSYSUT1,UNIT=SYSDA,SPACE=(1024,(60,60)"CONTIG),
//
SEP=(SYSUT3,SYSLIN),DCB=BLKSIZE=1024
//GO EXEC PGM=LOADER,PARM='MAP,PRINT';REGION=96K,COND=(9,LT,PL1L)
//SYSLIB DD DSNAME=SYS1.PL1LIB,DISP=SHR
//SYSLIN DD DSNAME=&&LOADSET,DISP=(OLD,DELETE)
//SYSLOUT DD SYSOUT=A
//SYSPRINT DD SYSOUT=A
Figure 8-6.

Cataloged Procedure PL1LFCG (Compile, Load-and-Execute)

//GO EXEC PGM=LOADER,PARM='MAP,PRINT';REGION=96K
//SYSLIB DD DSNAME=SYS1.PL1LIB,DISP=SHR
//SYSLOUT DD SYSOUT=A
//SYSPRINT DD SYSOUT=A
Figure 8-7.

Cataloged Procedure PL1LFG (Load-and-Execute)

The use of the loader imposes certain
restrictions on your PL/I program; before
using this cataloged procedure, refer to
Chapter 6, which explains how to use the
loader.

job step include DDstatements that permit
the substitution of dedicated workfiles 'for
these data sets.. In such a DD statement.,
the dsname is coded:
DSNAME=&&ddname

LOAD AND EXECUTE (PL1LFG)
The cataloged procedure PL1LFG (Figure 8-7)
achieves the same result as PL1LFLG.
However, instead of using two job steps
(link-edit and execute), i t has only one.
In this job step, the operating system
loader program is executed. This program
link-edits and executes an object program
placed in a data set defined by a DD
statement with the name SYSLIN; you must
supply this DD statement with the qualified
ddname GO.SYSLIN.
Note that the REGION parameter of the
EXEC statement specifies 96K bytes. Since
the loader requires about 17K bytes of main
storage, there are about 79K bytes for your
program; if this is not likely to be
sufficient, yqu must mOdify the parameter.
The use of the loader imposes certain
restrictions on your PL/I program; before
using this cataloged procedure, refer to
Chapter 6, which explains how to use the
loader.

DEDICATED WORKFILES
All the cataloged procedures that: require
the use of workspace data sets in any
96

where 'ddname' is the ddname of the
dedicated workfile that is to be
substituted for the workspace data set.
This substitution only occurs if:
1.

The job is being processed under MVT.

2.

An initiator that generates dedicabed

workfiles is used to select the job.
Dedicated workfiles may be used for the
SYSUTl and SYSUT3 work data sets for the
PL/I (F) compiler. Dedicated workfiles :may
also be used for the SYSLIN data set in
compile-link-edit-and-go or compile-Ioadand-go jobs. However, care should be taken
to specify a block size (which must be a
multiple of 80 bytes) for this data set, as
the compiler will not override an
unsuitable block size left in the dedicated
workfile DSCB by a previous job (this is
because the compiler cannot know if SYSLIN
is a permanent data set, perhaps
erroneously specified, for which the blo,ck
size may not be overriden). This block
size may be specified either in user JCl, or
the cataloged procedure used. If it is
specified in a cataloged procedure, care!
must be taken to ensure that the block size
is overridden by user JCL when the
procedure is used to update a permanent
SYSLIN data set with a block size different
to that specified in the procedure.
Note that the standard cataloged
procedures PLlJ..FC, PL1LFCL, PL1LFCLG, and

PL1LFCG use the dsname LOADSET and specify
UNIT=SYSSQ for SYSLIN. They assume that
SYSLIN 'will not use a dedicated workfile.
These may be modified to do so subject to
the above restrictions on block size, and
provided UNIT is changed to specify
UNIT=SYSDA.
For'a complete description of the use of
dedicabed workfiles, see IBM System/360
Operatil~g system: system Programmer's
Guide.

U sing

C~ataloged

Procedures

'l'o invoke a cataloged procedure, specify
i ts nam(~ in the PROC parameter of an EXEC
statement. For example, to use the
cataloged procedure PL1DFC, you could
include the following statement in the
appropriate position among your other job
control statements in the input stream:
// EXEC PROC=PL1DFC
Note that you need not code the keyword
PROCi if the first operand in the EXEC
statement does not begin PGM= or PROC=, the
job schE~duler interprets it as the name of
a cataloged procedure. Thus, the following
statement is equivalent to that given
above:
// EXEC PL1DFC
when the job scheduler encounters the
name of a cataloged procedure in an EXEC
statement, it extracts the statements of
the cataloged procedure from the procedure
library and substitutes them for the EXEC
statement in the input job stream.
If you
include the parameter MSGLEVEL=l in your
JOB stat~ement, the job scheduler will
include the original EXEC statement in its
listing, and will append the statements of
the cataloged procedure.
In the listing,
catalogE!d procedure statements are
identifi.ed by XX or X/ as the first two
charactE!rS; X/ signifies a statement that
has been modified for this invocation of
the cataloged procedure.
An EXEC statement identifies a job step.
which can require either the execution of a
program or the invocation of a cataloged
procedure. A cataloged procedure includes
one or more EXEC statements, which identify
procedu:r:e steps. However, an EXEC
statement in a cataloged procedure cannot
invoke a.nother cataloged procedure: it must
request ,the execution of a program. Thus a
job comprises one or more job steps, each
of which involve one or more procedure
steps.

It will usually be necessary for you to
modify the statements of a cataloged
procedure for the duration of the job step
in which i t is invoked, either by adding DO
statements to it or by overriding one or
more parameters in the EXEC or DD
statements. For example, all the cataloged
procedures that involve compilation require
the addition of a DD statement with the
name SYSIN to define the data set that
contains the source statements. Also,
whenever you use more than one standard
linkage-editor procedure step in a job, you
must modify all but the first cataloged
procedure that you invoke if you want to
execute more than one of the load modules:
this sp'ecial case is discussed in 'Altering
Cataloged procedures,' below.

Altering Cataloged Procedures
You can modify a cataloged procedure
permanently by rewriting the job control
statements that are stored in the procedure
library. Alternatively, you can make
temporary changes by including parameters
in the EXEC statement that invokes the
cataloged procedure or by placing
additional DO statements after the EXEC
statement.
Permanent alterations should be made
only by system programmers responsible for
maintaining the procedure library. Some of
the considerations that may influence their
decisions as to whether and how to modify
the standard cataloged procedures are
discussed below.
Most programmers find it necessary to
make temporary modifications whenever they
use a cataloged procedure.
Such changes
apply only for the duration of the job step
in which the procedure is invoked and only
to that job step: they do not affect the
copy of the cataloged procedure stored in
the procedure library.

TEMPORARY MODIFICATION
Temporary modifications can apply to EXEC
or DO statements in a cataloged procedure.
To change a parameter of an EXEC statement,
you must include a corresponding parameter
in the EXEC st~tement that invokes the
cataloged procedure: to change one or more
parameters of a DO statement, you must
include a corresponding DO statement after
the EXEC statement that invokes the
cataloged procedure. Although you may not
add a new EXEC statement to a cataloged
procedure. you can always include
additional DO statements.
Cha.pter 8: Cataloged Procedures

97

EXEC stat ement
If a parameter of an EXEC statement that
invokes a cataloged procedure has an
unqualified name, that parameter applies to
all the EXEC statements in the cataloged
procedure. The effect on the cataloged
procedure depends on the parameter:
PARM applies to the first procedure
step and nUllifies any ot:her PARM
parameters.
COND and ACCT apply to all the
procedure steps.
TIME and REGION apply to all the
procedure steps and override existing
values.
For example, the statement
// EXEC PLiLFCLG,PARM='SIZE=999999',
//
REGION=144K
invokes the cataloged procedure PL1LFCLG,
substitutes the option SIZE=999999 for LOAD
and NODECK in the EXEC statement PLiL, and
nullifies the PARM parameter in the EXEC
statement LKED; i t also specifies a
regional size of i44K for all threE!
procedure steps.
'10 change the value of a parameter in
only one EXEC statement of a catalc)ged
procedure, or to add a new parameter to one
EXEC statement, you must identify the EXEC
statement by adding its name as a suffix to
the parameter name; separate the parameter
name and the step name with a period.
For
example, to alter the region size for
procedure step PLiL only in the preceding
example, code:

// EXEC PROC=PLiLFCLG,
//
PARM='SIZE=999999',
//
REGION.PLiL=144K
A new parameter specified in thE;!
invoking EXEC statement overrides
completely the corresponding paramE:lter in
the procedure EXEC statement. This is
particularly important with the PAI~
parameter. For example, the statement
// EXEC PLiDFC,PARM.PLiL='SIZE=999999,
//
EXTREF'
would bE:! in error if the standard compiler
default options applied. The default
options NODECK and LOAD would apply, rather
than the options DECK and NOLOAD specified
in the procedure EXEC statement.
Consequently, the compiler would attempt to
open the data set defined by the DD
statement SYSLIN, which does not exist in
the cataloged procedure PL1DFC.
98

You can suppress all the options
specified by a parameter by coding the
keyword and equal sign without a value.
For example, to suppress the bulk of the
linkage-editor listing when invoking the
cataloged procedure PLiLFCLG, code:
// EXEC PLiLFCLG,PARM.LKED=

DD statement
To add a new DD statement to a cataloged
procedure, or to modify one or more
parameters of an existing DD statement, you
must include, in the appropriate position
in the input stream, a DD statement with a.
name of the form 'procstepname.ddname'. If
'ddname' is the name of a DD statement
already present in the procedure step
identified by 'procstepname,' the
parameters in the new DD statement override
the corresponding parameters in the
existing DD statement; otherwise, the new
DD statement is added to the procedure
step. For example, the statement
//PLiD.SYSIN DD

*

adds a DD statement to the step PLiD of
cataloged procedure PLiDFC, and the effect
of the statement
//PL1D.SYSPRINT DD SYSOUT=C
is to modify the existing DD statement
SYSPRINT (causing the compiler listing to
be transmitted to the system output devicE!
of class C).
overriding DD statements must follow the
EXEC statement that invokes the cataloged
procedure in the same order as the
corresponding DD statements of the
cataloged procedure. DD statements that
are being added must follow the overriding
DD statements for the procedure step in
which they are to appear.
If you are using
an operating system with PCP, an overriding
or additional DD statement with the operand
* or DATA must be the last DD statement for
the procedure step.
To override a parameter of a DD
statement, code either a revised form of
the parameter or a replacement parameter
that performs a similar function (e.g.,
SPLIT for SPACE)., To nullify a parameter II
code the keyword and equal sign without a
value. You can override DCB subparameters
by coding only those you wish to modify;
that is, the DCB parameter in an overriding
DD statement does not necessarily overrid4~
the entire DCB parameter of the
corresponding statement in the cataloged
procedure.

Multiple Invocation of Cataloged Procedures
You can invoke different cataloged
procedures, or invoke the same procedure
several times, in the same job. No special
problems are likely to arise unless more
than one of these cataloged procedures
involves a link-edit step, in which case
you must take precautions to ensure that
all your load modules can be executed.

of the cataloged procedure by adding a
DD statement of the form:
//
2.

//GO.SYSLMOD DD DSNAME=&&GOSET,
DISP=(OLD,DELETE)
Modify the DD statement SYSLMOD in the
second and subsequent invocations of
the cataloged procedure so as to vary
the names of the load modules. For
example:
//LKED.SYSLMOD DO OSNAME=&&GOSET(G01)

'The linkage editor always places a load
module that it creates in the library
identified by the DD statement SYSLMOD. In
the absence of a linkage editor NAME
statement (or the compiler OBJNM parameter
option), it uses the member name specified
in the DSNAME parameter as the name of the
module. In the standard cataloged
procedures, the DD statement SYSLMOD always
specifi,es a temporary library named
&&GOSET, and gives the member name GO.
Consider what will happen if, for
example, you use the cataloged procedure
PL1LFCLG twice in a job to compile,
link-edit, and execute two PL/I programs,
and do not individually name the two load
modules that will be created by the linkage
editor. The linkage editor will name the
first module GO, as specified in the first
DD statement SYSLMOD. It will not be able
to use ,the same name for the second module,
since the first module still exists in the
library &&GOSET; therefore it will allocate
a temporary name to the second module (a
name that is not available to your
program). step GO of the cataloged
procedure requests the job scheduler to
initiat,e execution of the load module named
in -the DD statement SYSLMOD in the step
LKED, that is, to execute the module named
GO' from the library &&GOSET. Consequently,
the first program module will be executed
twice and the second not at all.
You can use one of the following methods
to obviate this difficulty:
1.

Delete the library &&GOSET at the end
of the step GO of the first invocation

and so on.
3.

Use the OBJNM· option to give a
different name to each load module.

Example
Figure 8-8 is an example of the use of the
cataloged procedure PL1LFLG. It assumes
that an object module 'already exists in the
data set SOURCE1, which is on the 2311 disk
pack with the serial number 0186.
The PARM parameter in the EXEC statement
nullifies the corresponding parameter of
the first EXEC statement in the cataloged
procedure,; its effect is to suppress most
of the linkage-editor listing.
Two of the DD statements in the example
refer to the procedure step LKED; one of
them overrides the existing statement
SYSLMOO, and the other adds a new statement
SYSIN. The overriding statement SYSLMOO
causes the linkage editor to place the load
module in the existing private library PLIB
and give it the name CAT. The new
statement SYSIN defines the data set that
contains the object module that is to be
link-edi ted,.
(The ddname SYSIN is equated
with the name SYSLIN by the DDNAME
parameter of the DD statement SYSLIN in the
cataloged procedure.)
Data to be processed when the program
CAT is executed is introduced in the input
stream and is identified by the DD
statement SYSIN, which is added to the job
step GO.

//J070PGEX JOB
// EXEC PL1LFLG,PARM=
//LKED.,sYSLMOD DD UNIT=2311,VOLUME=SER=D186,DSNAME=PLIB(CAT),
//
DISP=(OLD,PASS)
//LKED.SYSIN DD UNIT=2311,VOLUME=SER=0186,DSNAME=SOURCE1,DISP=OLD
//G0.Sy,sIN DD *
17324
259
7312
841
977
2193
21

37052

/*

Figure 8-8.

Invoking Cataloged Procedure PL1LFLG
Chapter 8: cataloged Procedures

99

PERMANENT MODIFICATION
To make permanent modifications to a
cataloged procedure, or to add a new
cataloged procedure, use the system utility
program IEBUPDTE, which is described in IBM
system/360 Operating system: utilities. --The following paragraphs discuss some of
the factors you should have in mind when
considering whether to modify the standard
cataloged procedures for your installation.
For further information on writing
installation cataloged procedures, see IBM
system/360 Operating System: Syste~
Programmer's Guide.
In general, installation conventions
will dictate the options that you include
in the PARM, UNIT, and SPACE paramE~ters of
the cataloged procedures, and also the
blocking factors for output data sets.
If your installation is using the MVT
option of the operating system, you may
need to modify some or all of the REGION
parameters and SYSPRINT DD statements in
the cataloged procedures.
'The minimum region size for compilation
should be at least 8K bytes larger than the
largest value that will be specified in the
compiler SIZE option (excluding
SIZE=999999) •
In those cataloged procedures that
invoke the linkage editor, a region size of
96K is specified for the link-edit step.
You can reduce this value if you are using
the E-Ievel linkage edi-tor o.r the 44K
F-level linkage editor. The minimum region
sizes for the E-level linkage editor are:

Linkage Editor
E15
E18
E44

Note that, under MVT the operating
system requires 52K bytes of main storage
within a region when initiating or
terminating a job step. If you specify a
region size of less than 52K bytes,
completion of a job may be held up until
52K bytes are available.
If your installation does not use MVT,
you can delete the REGION parameter from
all cataloged procedures .•
If the data set defined by a DD
statement with the name SYSPRINT may be OIl
a direct-access device, you should add a
SPACE parameter to the statement.
A modified cataloged procedure can be
tested by converting it to an in-stream
procedure and executing it any number of
times during a job. Figure 8-9 shows how
to convert PL1DFC to an in-stream procedure
and execute it twice.
For further information about in-stream
procedures and symbolic parameters, refer
to the publication IBM System/360 Operatil~
System: Job Control Language Reference.

//PL1COMPL PROC (Symbolic parameters are optional)
(PL1DFC procedure as it exists in the procedure library)
//ENDCOMPL PEND
//
EXEC PL1COMPL
//PL1D.SYSIN DO *
(Input Data)
/*

//
EXEC PL1COMPL
//PL1D.SYSIN DD *
(Input Data)
L ____________________________________________________________ J
1/*

100

24K
26K
54K

For the F-Ievel linkage editor, the region
size should be at least 8K bytes larger
than the largest value to be specified in
the SIZE option. You must alter the REGION
parameter if you are using the 128K bytes I'
F-Ievel, linkage editor,.

r------------------------------------------------------------,
//CONVERT JOB PL1PROG,MSGLEVEL=1

Figure 8-9,

Region

Executing PL1DFC as an In-Stream Procedure

Chapter 9: Data Sets and PL/I Files

Introduction
This chapter describes briefly the nature
and orc:ranization of data sets, and the da'ta
management services provided by IBM
System/360 Operating System, and explains
how thea compiled program produced by the
PL/I Or> compiler uses them.

In IBM System/360 operating System, a data
set is any collection of data that can be
created and accessed by a program. A data
set may be a deck of punched cards; it may
be a sE2!ries of items recorded on magnetic
tape OJ: paper tape; or it may be recorded
on a direct-access device such as magnetic
disk, drum, or data cell. A printed
listinq produced by a program is also a
data SE~t, but it cannot be read by a
program. A PL/I compiled program uses the
data management routines of the operating
system to create and access data sets.
A data set resides on one or more
volume£3. A volume is a standard unit of
auxiliary storage that can be written on or
read by an input/output device (for
exampIE~, a reel of tape, a disk pack, or a
card dE!ck); a unique serial number
identifies each volume (other than a
punched-card or paper-tape volume or a
magnetic-tape volume with either no labels
or nonstandard labels).
A magnetic-tape or direct-access volume
can contain more than one data set;
conversely, a single data set can span two
or more magnetic-tape or direct-access
volumes.

DATA

SE~

NAMES

A data set on a direct-access device must
have a name so that the operating system
can refer to it. A data set on magnetic
tape must have a name if the tape has
standard labels (see 'Labels,' below>. A
name consists of up to eight characters,
the first of which must be alphabetic ..
Data sE~ts on punched cards, paper tape,
unlabeled magnetic tape or nonstandard
labeled magnetic tape do not have names.

You can place the name of a data set,
with information identifying the volume on
which it resides, in a catalog that exists
in the volume that contains the operating
system. Such a data set is termed a
cataloged data set. To retrieve a
cataloged data set, you do not need to give
the volume serial number or identify the
type of device; you need only specify the
name of the data set and its disposition...
The operating system searches the catalog
for information associated with the name
and uses this information to request the
operator to mount the volume containing
your data set ..
If you have a set of related data sets,
you can increase the efficiency of the
search for a particular member of the set
by establishing a hierarchy of indexes in
the catalog. For example, consider an
installation that groups its data sets
under four headings: ENGRNG, SCIENCE,
ACCNTS, and INVNTRY (Figure 9-1). In turn,
each of these groups is subdivided; for
instance, the SCIENCE group has subgroups
called PHYSICS, CHEM, MATH, and BIOLOGY.
The MATH group itself contains three
subgroups: ALGEBRA, CALCULUS, and BOOL. To
find the data set BOOL, the names of all
the indexes of which it is part must be
specified, beginning with the largest group
(SCIENCE)" followed by the next largest
group (MATH), and finally the data set name
BOOL. The names are separated by periods.
The complete identification needed to find
the data set BOOL is SCIENCE.MATH.BOOL;
such an identifier is termed a qualified
~,.
The maximum length of a qualified
name is 44 characters, including the
separating periods; each component name has
a maximum length of eight characters. (Do
not use data set names that'begin with the
letters SYS and have a P as the nineteenth
character.. The names assigned by the PCP
operating system to unnamed temporary data
sets are of this form. They are deleted
when the operating system utility IEHPROGM
is used with a SCRATCH statement that
includes the keywords VTOC and SYS.>
Some data sets are updated periodically,
or are logically part of a group of data
sets, each of which is related to the
others in time.. You can relate such data
sets to each other in what is termed a
generation data group.. Each data set in a
generation data group has the same name
qualified by a unique parenthesized
generation number (for example, STOCK(O),
STOCK(-l), STOCK'(-2». The most recently
cataloged data set is generation 0, and the
Chapter 9: Data Sets and PL/I Files

101

preceding generations are -1, -2, and so
on. You specify the number of generations
to be saved when you establish the
generation data group.

I
I

T
r---------T------.L----------------,I
I
I

I
I

ENGRNG

I

I

SCIENCE

I

ACCNTS

INVNTRY

I
I

r------T--~---T-------,

I
I

I
I

I
I

PHYSICS CHEM

I
I

MATH BIOLOGY

I
I

r----~-----T--------,

I
I

ALGEBRA
Figure 9-1.

I
I

CALCULUS

I
I

BOOL

A Hierarchy of Indexes

~'or example, consider a generation data
group that contains a series of data sets
used for weather reporting and forecasting;
the name of the data sets is WEATHER. The
generations for the group (assuming that
three generations are to be saved) are:

WEATHER (0)
WEATHER (-1)
WEATHER (-2)
When WEATHER is updated, the new d,ata set
is specified to the operating system as
WEATHER(+1). When it catalogs the new data
set, the operating system changes ·the name
to WEATHER(O), changes the former
WEATHER(O) to WEATHER(-1), the former
WEATHER(-1) to WEATHER(-2), and deletes the
former WEATHER(-2).
For instructions on how to crea·te a
generation data group, refer to IBM
system/360 Operating system: Job-COntrol
Language and IBM System/360 operating
system: Utilities.

RECORD FORMATS
The items of data in a data set are
arranged ~~ blocks separated by interblock
gaps (IBG)1; a block is the unit of data
transmitted to and from a data set. Each
block contains one record, part of a record

or several records; a record is the unit of
data transmitted to and from a program.
When writing a PL/I program, you need
consider only the records that you are
reading or writing; but when you describe
the data sets that your program will crea1:e
or access, you must be aware of the
relationship between blocks and records.
If a block contains two or more records,
the records are said to be blocked.
Blocking conserves storage space in a
volume because it reduces the number of
interblock gap's, and it may increase
efficiency by reducing the number of
input/output operations required to process
a data set. Records are blocked and
deblocked automa·tically with the aid of the
data management routines of the operating
system.
The records in a data set must be in one
of three formats: fixed-length,
variable-length, or undefined-length.
Fixed-length and variable-length records
can be blocked .or unblocked;
undefined-length records cannot be blocked.
The following pa:ragraphs describe the thrlee
record formats.

Fixed-Length Records
In a data set with fixed-length (F-format
and FB-format) records, (see Figure 9-2)
all records have the same length. If the
records are blocked, each block contains .an
equal number of fixed-length records
(although the last block may be truncated
if there are insufficient records to fill
it). If the records are unblocked, each
record constitutes a block.
Because it can base blocking and
deblocking on the constant record size, the
operating system can process fixed-length
records faster than variable-length
records. The use of 'standard" FS-format
and FBS-format further optimizes the
sequential processing of a data set on a
direct-access device.. A standard format
data set contains fixed-length records and
must have no embedded empty tracks or short
blocks (apart from the last block). With a
standard format data set, the operating
system can predict whether the next block
of data will be on a new track, and, if
necessary, can select a new read/write head
in anticipation of the transmission of that
block.
Note~

1Although the term 'interrecord gap' is
widely used in operating system manuals, it
is not used here; it has been replaced by
the more accurate term 'interblock gap.'
102

1.

PL/I program never places embedded
short blocks in a data set with
fixed-length records.

A

Unbloc:ked records (F-format):
r--Block--,

r-----'----,

I

.Reco:rd
L _____
,•• ___ JI

r--Block--,

r--Block--,

r---------,

r--------,

r---

lBG LI _________
Record JI lBG IL _________
Record JI lBG IL __ _

Blocked records (FB-format):
r-'------------Block------------,

r----------T--------T---------,

I __________
RecOJrd .LI_______
Record .LI _________
Record JI
L

Figure 9-2.
2.

r--------T---

lBG LI ________
Record J., __ _

Fixed-Length Records

A data set can be processed as a
st.andard data set even if it was not
cl:eated as such, providing it contains
no embedded short blocks or empty
t~:acks.

VariabJLe..,.Length Records
V-format permits both variable-length
records and variable-length blocks. The
first four bytes of each record and of each
block contain control information for use

by the operating system (including the
length in bytes of the record or block).
Variable-length records can have one of
four formats: V, VB, VS, or VBS (Figure
9-3).

V-format signifies unblocked
variable-length records. Each record is
treated as a block containing only one
record, the first four bytes of the block
contain block control information, and the
next four contain record control
information.

V-format:

r--T--'·----------,
lelle21

Record 1

r--T--T----------------,

I lBG le11e21

,L__ J.I __ J.I ___________ JI

Record 2

r-""--T--

'lBG ,e1Ie2,
IL__ .L-_.L
I
, _______________ J' IL-._.LI __.L, __

VB-format:

r--T--T----------T--T---------------,

r--T---r----------

lellc21 Record 1
IC2,
Record 2
'lBG ,e1,e2, Record 3
I __ .LI __ .1.I ___________ .LI __ .L, ________________ JI
IL__ .LI __.L, _________ _
L

VS-format:

r--T--T'----------,

r--T-~-----------------,

r--T--T------------,

le11e21 Record 1 I lBG IC11e21
Record 2
, lBG lelle2,
Record 2
I lBG
I __ .LI __ .L.I __________
(entire) JI
IL __ .LI __.LI _________________
(first segment) JI
I __ .LI __ J.,(last
segment),J
L
L
______________

VBS-format:

r--T--T----------T--T-----------------,

r--T--T----------------,...--T---------

le11c21 Record 1 le21
Record 2
I lBG lel1e21
Record 2
le21Record 3
L
I __ .LI __ .LI __________
(entire) J.I __ J.I _________________
(first segment) JI
IL__ J.I __ .LI ________________
(last segment) J.I __ .LI ________ _

el:
c2:

Block control information
Record or segment control information

Figure 9-3.

Variable-Length Records
Chapter 9: Data sets and PL/l Files

103

VB-format signifies blocked
variable-length records. Each block
contains as many complete records as it can
accommodate. The first four bytes of the
block contain block control information,
and the first four bytes of each record
contain record control information~

are recognized by the PL/I (F) compiler ill
the data set organizations CONSECUTIVE,
INDEXED, and REGIONAL; and the file
attribute TRANSIENT respectively; the fift:h
type, partitioned, has no corresponding
PL/I organization~.

VS-format is similar to V·-format, but
differs in that the length of a record can
exceed the block length; if necessary, a
record is segmented and continued in
consecutive blocks. Each block contains
only one record or segment of a record.
The first four bytes of the block contain
block control information, and the next
four contain record or segment control
information (including an indicati()n of
whether the record is complete or is a
first, intermediate, or last segment).

In a sequential (or CONSECUTIVE) data
set, records are placed in physical
sequence. Thus, given one record, the
location of the next record is determined
by its physical position in the data set.
Sequential organization is used for all
magnetic tapes, and may be selected for
direct-access devices. Paper tape, punchE:!d
cards, and printed output are sequentially
organized.

VBS-format differs from Vs-format in
that each block contains as many complete
records or segments as it can accommodate;
each block is, therefore, approximately the
same size (although there can be a
variation of up to four bytes, since each
segment must contain at least one byte of
data).

An indexed sequential (or INDEXED) data
set must reside in a direct-access volume '.
Records are arranged in collating sequenc.:!,
according to a key that is associated with
every record. An index or set of indexes
maintained by the operating system gives
the location of certain principal records,.
This permits direct retrieval, replacement,
addition, and deletion of records, as well
as sequential processing.

VS-format and VBS-format records are
known as spanned records because they can
start in one block and be continued in the
next. Segmentation and reassembly are
handled automatically by the PL/I (F)
compiler. The use of spanned records
allows you to select a block size,
independently of record size, that will
combine optimum usage of auxiliary storage
space with maximum efficiency of
transmission. Note that spanned records
cannot be specified for stream-oriented
files.

A direct (REGIONAL) data set must be in
a direct-access volume. The records with:in
the data set can be organized by a PL/I
program in three ways: REGIONAL(l),
REGIONAL(2), and REGIONAL(3): in each case,
the data set is divided into regions, each
of which contains one or more records. A
key that specifies the region number and,
for REGIONAL(2) and REGIONAL(3), identifies
the record, permits direct access to any
record; sequential processing is also
possible. There are no indexes.

Undefined-Length Records
U-format permits the processing of records
that do not conform to F- and V-formats.
The operating system and the PL/I (F)
compiler treat each block as a record; your
program must therefore perform any blocking
or deblocking that you require.

A telecommunications data set
(associated with a TRANSIENT file in a PL/I
program) is an input or output message
queue set up by the message control
program. A key embedded in the record
provides identification of the sending
terminal.

DATA SET ORGANIZATION

In a partitioned data set, independent
groups of sequentially organized data, each
called a member, are stored in a
direct-access volume. The data set
includes a directory that lists the
location of each member. Partitioned data
sets are often called libraries.

The data management routines of the
operating system can handle five types of
data set, which differ in the way data is
stored within them and in the permitted
means of access to the data. Four of these
types of data set, sequential, indexed
sequential, direct, and telecommunications

~Do not confuse the operating system data
set organizations 'sequential' and 'direct'
with the PL/I file attributes SEQUENTIAL
and DIRECT. The attributes refer to how
the file is to be processed, and not to the
way the corresponding data set is
organized.

104

'I'he PL/I (F) compiler includes no
special facilities for creating and
accessing partitioned data sets; however,
there is ready access to the operating
system :facilities for partitioned data sets
through job control language. Chapter 12,
'Libraries of Data sets,' is a guide to the
use of partitioned data sets for the PL/I
programmer.

LABELS
The operating system uses recorded labels
to identify magnetic-tape and direct-access
volumes and the data sets they contain, and
to store data set attributes (record size,
block size, etc.). The attribute
information must originally come from a DO
statement or from your program. Once the
label is written, however, you need not
specify the information again.
Magnetic-tape volumes can have standard
or nonstandard labels, or they can be
unlabeled. Standard labels have two parts:
the ini,tial volume label, and header and
trailer labels. The initial volume label
identifies a volume and its owner; the
header and trailer labels precede and
follow each data set on the volume. Header
labels contain system information,
device-dependent information (for example,
recording technique), and data-set
characteristics. Trailer labels are almost
identical with header labels, and are used
when maqnetic tape is read backwards.
Direct-access volumes have standard
labels. Each volume is identified by a
volume label, which is stored in a standard
location in the volume. This label
contains a volume serial number and the
address of a volume table of contents
(VTOC). The table of contents, in turn,
contains a label (termed a data set control
block (DSCB» for each data set stored in
the volume.

DATA DEFINITION (DO) STATEMENT
A data definition (DD) statement is a job
control statement that describes a data set
to the operating system, and is a request
to the operating system, for the allocation
of input/output resources.
Each job step
must include a DO statement for each data
set tha't is processed by the step.
Chapter 1 describes the format of job
control statements. The operand field of
the DD statement can contain keyword
parameters that describe the location of

the data set (for example, volume serial
number and identification of the unit on
which the volume will be mounted) and the
attributes of the data itself (record
format, etc.).
The DO statement enables you to write
PL/I source programs that are independent
of the data sets and input/output devices
they will use. You can modify the
parameters of a data set or process
different data sets without re-compiling
your program; for example, you can modify a
program that originally read punched cards
so that it will accept input from magnetic
tape merely by changing the DO statement.

Name of DD Statement
The name that appears in the name field of
the DO statement (ddname) identifies the
statement so that other job control
statements and the PL/I program can refer
to it. A ddname must be unique within a
job step; if two DD statements in one job
step have the same name, the second
statement is ignored. With the two
exceptions noted below, a DD statement must
always, have a name.
If the job step in which the DD
statement appears is part of a cataloged
procedure, the ddname must be qualified by
the name of the procedure step. For
example, a DO statement that describes a
data set to be processed in step GO of the
cataloged procedure PL1LFCLG might have the
ddname GO.MSTR.
(Note that the PL/I source
program would refer to this DD statement
only by its unqualified name MSTR.)
For input only you can concatenate two
or more sequential or partitioned data sets
(that is, link them so that they are
processed as one continuous data set) by
omitting the ddname from all but the first
of the DO statements that describe them.
For example, the following DO statements
cause the data sets LIST1, LIST2, and LIST3
to be treated as a single data set for the
duration of the job step in which the
statements appear:
//GO.LIST DD DSNAME=LIST1,DISP=OLD
//
DO DSNAME=LIST2,DISP=OLD
//
DD DSNAME=LIST3,DISP=OLD
When read from a PL/I program the
concatenated data sets need not be on the
same volume, but the volumes must be on the
same type of device, and the data sets must
have similar characteristics (block size,
record format, etc.). You cannot process
concatenated data sets backwards.
Chapter 9: Data Sets and PLII Files

105

Parameters of DD statement
The operand field of the DD statement
contains keyword parameters that you can
use to give the following information:
1.

The name of the data set
parameter) •

2.

Description of the device and volume
that contain the data set (UNIT,
VOLUME, SPACE, LABEL, and SYSOUT
parameters).

3.

Disposition of the data set before and
after execution of the job step (DISP
parameter) •

4.

(DSN1~

Data set characteristics (DCB
parameter) •

1he following paragraphs summarize the
functions of these groups of parameters.
Appendix B describes the essential
parameters and explains how to use them.
For full details of all the parameters,
refer to IBM svstem/360 op'erating System:
Job Control Language User's Guide, and Job
Control Language Reference
Naming the Data Set
The DSNAME parameter specifies the name
of a newly defined data set or refers to
the name of an existing data set. You need
not specify the DSNAME parameter for a
temporary data set (one that exists only
for the duration of the job step in which
it is created); the operating system will
give it a temporary name.
Describing the Device and Volume
The UNIT parameter specifies the type of
input/output device to be allocated for the
data set. You can specify the type by
giving the actual unit address, the type
number of the unit (e.g., 2400 for magnetic
tape), or by naming a group of uni-ts
established at system generation.
The VOLUME parameter identifies the
volume on which 'the data set resides. It
can also include instructions for mounting
and demounting volumes.
The SPACE parameter specifies the amount
of auxiliary storage required to
accommodate a new data set on a
direct-access device.

device. A system output device is any unit
(but usually a printer or a card punch)
that is used in common by all jobs. The
computer operator allocates all the system
output devices to specific classes
according to, device type and funct,!on. The
usual convention is for class A to refer 1:.0
a printer and class B to a card punch; thE~
IBM-supplied cataloged procedures assume
that this convention is followed.. If you
use the SYSOUT parameter, the only other
information you may have to supply about
the data set is the block size, which you
can specify either in the DCB parameter or
in your PL/I program.
Disposition of the Data Set
The DISP parameter indicates whether a
data set already exists or is new, and
specifies what is to be done with it at the
end of the job step. At the end of a job
step, you can delete a data set, pass it to
the next step in the same job, enter its
name in the system catalog or have it
removed from· the catalog, or you can retain
the data set for future use without
cataloging it.
The REWIND option of the ENVIRONMENT
attribute allows you to use the DISP
parameter to control the action taken when
the end of a magnetic-tape volume is
reached or when a magnetic-tape data set is
closed. Refer to IBM System/360 Operatin.

The LABEL parameter specifies the type
and contents of the data set labels for
magnetic tape.
The SYSOUT parameter allows you to route
an output data set through a system output
106

4.

5.

The number of data management buffers
that are to be used (BUFNO
slJlbparameter> •
The printer or card punch control
characters (if any> that will be
inserted in the first byte of each
rE!cord (RECFM subparameter).

You can specify BLKSIZE, BUFNO, LRECL,
NCP, RE:CFM, and TRKOFL in the ENVIRONMENT
attribute of a file declaration in your
PL/I program instead of in the DCB
parameter.
You cannot use the DCB parameter to
overrid.e information already established
for the data set in your PLII program (by
the file attributes declared and the other
attribu.tes that are implied by them).
DCB
subparameters that attempt to change
informa"tion already supplied are ignored.
You can use only the DCB subparameters
given above; if you specify any others,
they will be ignored.
Data in the Input Stream
You can introduce data to your program
by including it in the input job stream
with your job control statements. The data
must be- in the form of 80-byte records
(usually punched cards), and must be
immediately preceded by a DO statement with
the single parameter * in the operand
field, for example:
//GO.SYSIN DO *
To indicate the end of the data, include
the delimiter job control statement /*;
this delimiter is not essential if you are
using an operating system with MFT or MVT
because the operating system will generate
//SYSIN DO * statements for other data sets
in the input stream.

FILES AND DATA SETS
When you write a PL/I program, you do not
need to know which data sets you will use
or where the volumes that contain them will
be mounted. PL/I uses a conceptual 'file'
as a means of accessing a data set. When
an OPEN statement is executed, the file is
associated with a data set through the
TITLE option, which refers to the name of
the DO statement (ddname) that describes
the data set; if the OPEN statement does
not include the TI~LE option, the compiler
takes the DO name from the first eight
characters of the file name, padding it
wi th bl anks if necessary .•
The OPEN statement indicates the name of
the DO statement that describes the data
set to be associated with the file that is
being opened; the DO statement specifies
the type of device that will access the
data set, the serial number of the volume
that contains the data set, and the name of
tbe data set (see Figure 9-4).
If the DO
statement refers to a cataloged data set,
i t need supply only the name of the data
set and its disposition; the operating
system can use the name to obtain unit and
volume information from the system catalog.
Since the link between the PL/I file and
the data set exists only while the file is
open, the same file can be associated with
different data sets during the execution of
a single program; and the same data set can
be accessed through different files.
Furthermore, the use of a 00 statement to
define the data set, the volume that
contains it, and the device on which they
will be placed, enables you to defer your
choice until execution time; and you can
use the same program to process different
data sets on different devices' without
re-compiling the program.

If your data includes records that
commence //, use the parameter DATA
instead., for example:
//GO.SYSIN DO DATA
In this case, the delimiter (/*> is always
necessary.
when using an operating system with PCP,
you can include only one data set in the
input stream for a job step, and the DO
statement that defines i t must be the last
DD statement in the job step; for MFT and
MV'l', you can include more than one such
data se:"t in a job step. All three variants
of the operating system supply full DCB
subparameters for data sets in the input
stream.

Operating System Data Management
The object program produced by the PL/I (F)
compiler uses the data management
facilities of the operating system to
control the storage and retrieval of data.
The compiler translates each input and
output statement in a PL/I source program
into a sequence of machine instructions
that includes a branch to the appropriate
PL/I library interface subroutine; this
subroutine initiates the flow of control
through any other PL/I library subroutines
that are required. These subroutines issue
Chapter 9: Data sets and PL/I Files

107

Figure 9-4.

108

Associating a File with a Data Set

operating system assembler language macro
instructions:l.. that request the data
management routines of the operating system
to peri:ormthe required input or output
operations. Most of the library
subrout:ines required by a PL/I program are
includE~d with the object program in the
load m()dule produced by the linkage editor.
Howevel~, some library subroutines,
including those that handle the opening and
closinq of files, are loaded dynamically
during the execution of the object program;
the storage they occupy is released as soon
as they have finished their work.

a buffer available to a program. In the
move mode, the data is actually transferred
from the buffer into the area of main
storage occupied by the program. In the
locate ~ode, the program can process the
data while it is still in the buffer; the
data management routines pass the address
of the buffer to the program to enable it
to locate the data. Similarly a program
can move output data into the buffer or it
can build the data in the buffer itself.

ACCESS METHODS
operating system data management
routinE!S control the organization,
location, and cataloging of data sets, as
well as the storage and retrieval of the
records they contain. They create and
maintain data set labels, indexes, and
catalo
For a direct-access device, the ideal
block size is the capacity of one track;
this combines maximum transmission
efficiency with optimum use of auxiliary
storage. A block can exceed the capacity
of one track only if your installation has
the track overflow feature; this allows the
block to be continued on the next track.
Although track overflow can increase
data-packing efficiency, it reduces
transmission speed. The use of small
blocks wastes storage space because a block
of system information follows each block of
data (except the last on the track). For
example, there are more than 60 bytes of
system information for each block in the
2311 disk drive; a track can contain one
block of 3625 bytes, but only 55 blocks of
5 bytes (i.e., 275 bytes of data).
(Refer
to the reference cards listed under
'Direct-Access Devices,' in Chapter 10, for
further information.)
Unit record devices (card readers and
punches, and printers) and paper-tape
readers do not support blocked records.
With a unit record device, each record
begins on a new card or line regardless of
the blocking factor. For example, if you
specify LRECL=20, BLKSIZE=SO for a card
punch, only the first 20 columns of each
card will be punched.. If the record size
exceeds the capacity of a card (SO bytes)

or the maximum length of a line (132
characters for the 1403 printer), the
record is truncated.
In general, fixed-length records are
transmitted faster than variable-length or
und~fined-Iength records.
For maximum
efficiency in sequential processing of a
data set on a direct-access device, specify
'standard' format records (RECFM=FS or
RECFM=FBS). If you use variable-length
records u VBS-format allows you to specify
block size independently of record size
(and thus to select the optimum block
size).

program,. The following sections indicate
the essential information that you must
supply when processing CONSECUTIVE,
INDEXED., REGIONAL, and teleprocessing data
sets, and discuss some of the optional
information you may supply. The
discussions do not refer to data sets in
the input stream, which are covered in
Chapter 10. Appendix B describes the
parameters referred to, and explains how to
code them; the ENVIRONMENT attribute is
described in IBM System/360 Operating
system: PL/I (F) Language Reference Manual.

CONSECUTIVE Data Sets
Buffers

CREATING A CONSECUTIVE DATA SET

When YOll use a SEQUENTIAL BUFFERED file to
process a data set, you can specify the
number of data management buffers to be
used eiither in your PL/I program (in the
ENVIRONI~NT attribute) or in the DD
statemelt (BUFNO subparameter). If you
omit this information or specify zero
buffers the operating system will allocate
two buffers. Tw:o buffers are sufficient
for efficient transmission in most cases,
but you may gain some advantage by
specifying three buffers for a low-speed
device such as a printer. You should
specify at least three buffers if you use
chained scheduling. Blocked records are
not supported for UNBUFFERED files.
l,

Although a buffer specification for a
DIRECT file will be ignored, and even if
the filE~ is declared UNBUFFERED, the data
managemEmt routines of the PL/I library
sometimE~s use work buffers termed hidden
buffers., Hidden buffers are used for:
1.

In a CONSECUTIVE data set, records are
stored sequentially in the order in which
you write them; there are no keys. Figure
11-1 summarizes the essential information
you must pass to the operating system when
creating a CONSECUTIVE data set. You must
specify:
1.

Device that will write or punch your
data set (UNIT, SYSOUT, or VOLUME
parameter of DD statement).

2.

Block size: you can give the block
size in the DD statement (BLKSIZE
subparameter of DCB parameter), or in
your PL/I program (in the ENVIRONMENT
attribute).
Note: If you do not specify a record
size, unblocked records are assumed
and the record size is determined from
the block size. If you do not specify
a record format, U-format is assumed.

UNBUFFERED access of CONSECUTIVE data
set:s with V-format records (the buffer
contains the V-format control bytes
and the data).

2.

INDEXED data sets (the buffer contains
a lO-byte control field and the data) ..

3.

SEC!UENTIAL access of a REGIONAL (2) or
REGIONAL (3) data set declared KEYED
(so that the key and the record can be
tralnsmi tted from contiguous storage
arE!as) •

If you want to keep a magnetic-tape or
direct-access data set (that is, you do not
want the operating system to dnlete it at
the end of your job), the DD statement must
name the data set and indicate how it is to
be disposed of (DSNAME and DISP
parameters) .• The DISP parameter alone will
suffice if you want to use the data set in
more than one job step but will not need it
after the end of your job.
If you are creating a data set on a
direct-access deVice, you must specify the
amount of space required for it (SPACE
parameter of DD statement).

CREATING AND ACCESSING DATA SETS
To creat.e or access a data set, you must
gi ve thE! operating system certain
informat.ion, either in the DD statement
that defines the data set or in your PL/I

If you want your data set written on a
particular magnetic-tape or direct-access
volume, you must indicate the volume serial
number in the DD statement (SER or REF
subparameter of VOLUME parameter). If you
do not supply a serial number of a
Chapter 11: Record-Oriented

Transmi~sion

125

1r---------------------T--~--------------------------------------------------------------,
I
Parameters of DD statement
,
I

Storage Device

,

~---------------------T---------------------~--------------------~

,

When required

I What you must state I

Parameters

,

I~---------------------+---------------------+---------------------+---------------------~
I
, output device
1 UNIT= or SYSOUT= or I
I Always
I
1 VOLUME=REF=
1

, All

1
,
r---------------------+---------------------~
,
I
, Block size1.
1 DCB=BLKSIZE=
I
r---------------------+---------------------+---------------------+_--------------------~
, Direct access only 1 Always
, storage space
, SPACE:
,
,

,

I

, required

I

~---------------------+---------------------+----------------~----+---------------------~
, Magnetic tape only ,Data set not first ,sequence number
I LABEL=
,

I

I in volume and for
,
, magnetic tapes that ,
, do not h a v e '
, standard labels
I

,

, but not required at ,
, end of j o b ,

,
,

Direct access and
standard labeled
magnetic tape

I

,

I
I
I
,
,
~---------------------+---------------------+---------------------+---------------------~
, Data set to be used ,
I
I
I by another job step , Disposition
, DISP=
I

,
,

,

,
,

~-------------.--------+---------------------+---------------------~
, Data set to be kept , Disposition
, DISP=
,
, after end of job

·1

~---------------------+---------------------~
,DSNAME=
,

, Name of data set

1~---------------------+---------------------+---------------------~
Data set to be on
I volume serial number, VOLUME=SER= or
1

1 particular volume

1

, VOLUME=REF=

I

~--------_------------~-------------.------ __ ~--------------- ______ L-____________________ ~

I1.Alternatively, you can specify the block size in your PL/I program by using the

1

L
.________________________________________________ J,
, _______________________________________
ENVIRONMENT attribute.

Figure 11-1.

Creating a CONSECUTIVE Data Set: Essential Parameters of DD Statement

magnetic-tape data set that you want to
keep, the operating system will allocate
one, inform the operator, and print the
number on your program listing.

r----------,.--------------------------1i
ISubparameterl
Specifies
II
~----------+---------------------------~I

BLKSI ZE

1Maximum number of bytes per I
Ihl~k

If your data set is to follow another
data set on a magnetic-tape volume, you
must use the LABEL parameter of the DD
statement to indicate its sequence number
on the tape.
Figure 11-2 lists the DCB subparameters
that are applicable to CONSECUTIVE data
sets; they are described in Appendix B.
You can specify record format (RECFM),
block size (BLKSIZE), record size (LRECL),
and number of buffers (BUFNO) in the
ENVIRONMENT attribute instead of in a DD
statement.

ACCESSING A CONSECUTIVE DATA SET
You can access an existing CONSECTUIVE data
set in three ways. You can open the
associated file for input, and read the
records the data set contains; you can open
the file for output, and extend the data
126

~

I Number of data management
I
I buffers
I
CODE
IPaper tape: code in which
II
Ithe tape was punched
~I
DEN
IMagnetic tape: tape
il
,recording density
,I
LRECL
,Maximum number of bytes per I
I record
MODE
ICard reader or punch: mode
lof operation (column binary
lor EBCDIC)
OPTCD
IOptional data-management
Iservices and data-set
1attributes
PRTSP
,printer line spacing (0, 1,
12, or 3)
RECFM
IRecord format and
I characteristics
TRTCH
,Magnetic tape: tape
Irecording technique for
,7-track
tape
___________ J.
___ .______________________
_
BUFNO

Figure 11-2.

DCB SUbparameters for
CONSECUTIVE Data Sets

r--------------------------------~------------------------------------------------------,

I
Parameters of DD statement
I
~------·-----------------------------T-------------------------T-------------------------~
I

When required

I

What you must state

I

Parameters

I

~-----------------------------------+-------------------------+-------------------------~
I
I Name of data set
I DSNAME=
I
~-------------------------+-------------------------~

I Always
I

I Disposition of data set I DISP=
I
~------·-----------T-----------------+-------------------------+-------------------------1
I
IAII devices
I Input device
I UNIT= or VOLUME=REF=
I
I If dat·a set not ~-----------------+------------------------+-------------------------~
I cataloged
IStandard labeled I
I
I

I
I

I magnetic tape and I Volume serial number
Idirect access

..

I

~------ ---------J.~----------------+-:...----------------

I Magnetic tape: if data set not

I Sequence number

I first in volume or which does not
I have s·tandard labels

I
I

I

I VOLUME=SER=

I

______ +-___________________---__ I
~

I LABEL=
I

I
I
I

I

~-----------------------------------+-----------------------+-------------------------~
IIf data set does not have standard I Block size~
I DCB=BLKSIZE=
I
t
I
I
I labels
~------._----------------------------J.--------------------

_____

L _________________________ ~

I :l.Alternatively, you can specify the block size in your PL/I program by using the
I
L
•_________________________________________________________________________________
JI
I ______
ENVIRONMENT
attribute.
Figure 11-3.

Accessing a CONSECUTIVE Data Set: Essential Parameters of DD statement

set by adding records at the
end; or you can open the file for update,
and read and rewrite each record in turn.
(The opE:!rating sY,stem does not permit
updatinq a CONSECUTIVE data set on magnetic
tape; you must read the data set and write
the updated records into a new data set.)
'1'0 access an existing data set, you must
identify it to the operating system in a DD
statement. The following paragraphs, which
are su~rnarized in Figure 11-3, indicate the
essential information you must include in
your DD statement,. and discuss some of the
other information you may supply; this
discussion does not apply to data sets in
the input stream., which are dealt with in
Chapter 9 'Data Sets and PL/I Files'.
Appendi>~ B describes the DD parameters
referred to, and tells you how to code
them.

Essentia~l'

Confirmation that the data set already
exists (DISP parameter)
If you open
the data set for output with the
intention of extending it by adding
records at the end, code DISP=MOD;
otherwise, to open the data set for
output will result in it being
overwritten.
oW

If the data set is not cataloged, you
must, in addition, specify the device that
will read the data set, and, for
magnetic-tape and direct-access devices,
give the serial number of the volume that
contains the data set (UNIT and VOLUME
parameters) '.
If the data set is on paper tape or
punched cards, you must specify the block
size either in the DD statement (BLKSIZE
subparameter), or in your PL/I program
(ENVIRONMENT attribute).
If the data set follows another data set
on a magnetic-tape volume, you must use the
LABEL parameter of the DD statement to
indicate its sequence number on the tape.

Information

If the data set is cataloged, you need
supply only the following information in
the DD statement:
1.

2.

MaglieticTape without Standard Labels

The! name of the data set (DSNAME
paI~ameter) •
The operating system will
locate the information that describes
the! data set in the system catalog,
and, if necessary, will request the
operator to mount the volume that
contains it.

If a magnetic-tape data set has nonstandard
labels or is unlabeled, you must specify
the block size either in the DD statement
(BLKSIZE subparameter) or in your PLII
program (ENVIRONMENT attribute). The
DSNAME parameter is not essential if the
data set is not cataloged.

Chapter 11: Record-Oriented Transmission

127

PL/I data management includes no
facilities for processing nonstandard
labels. To the operating system, such
labels appear as data sets preceding or
following your data set. You can either
process the labels as independent data sets
0r use the LABEL parameter of the DD
statement to bypass them; to bypass the
labels code LABEL=(2,NL) or LABEL=(~BLP).
Record Format
If you give record-format information, it
must be compatible with the actual
structure of the data set. For example, if
a data set was created with F'-format
records, a record size of 600 bytes f and a
block size of 3600 bytes, you can access
the records as if they were U-format wit.h a
maximum block size of 3600 bytes; but if
you specify a block size of 3S00.bytes,
your data will be truncated.

EXAMPLE OF CONSECUTIVE DATA SETS

Figure 11-4 illustrates both creation and
accessing of CONSECUTIVE data sets on
magnetic tape. The program merges the
contents of two existing data sets, DSl and
DS2, and writes them onto a new data set,
DS3; each of the original data sets
contains lS-byte fixed-length records
arranged in EBCDIC collating sequence. Th-9
two input files, INl and IN2, have the
default attribute BUFFERED, and locate mode
is used to read records from the associated
data sets into the respective buffers. The
output file, OUT, is not buffered, allowing
move mode to be used to write the output
records directly from the input buffers.

//J034PGEA JOB
//COLEEX EXEC PL1LFCLG,PARM.PLIL=" SIZE=999999, ,PARM.LKED="LIST'
//PLlL.SYSIN DD •
MERGE: PROC OPTIONS(MAIN):
DCL (IN1,IN2,OUT) FILE RECORD SEQUENTIAL,
(ITEMl BASED(A),ITEM2 BASED(B» CHAR(lS);
ON ENDFILECIN1) BEGIN;
ON ENDFILE(IN2) GO TO FINISH:
NEXT2:
WRITE FILE(OUT) FROM(ITEM2);
READ FILE(IN2) SET(B);
GO TO NEXT2;
END;
ON ENDFILE(IN2) BEGIN;
ON ENDFILE(IN1) GO TO FINISH;
NEXTl:
WRITE FILE(OUT) FROM(ITEM1);
.READ FILE (IN1) SET (A) ;
GO TO NEXT1;
END;
OPEN FILE(IN1) INPUT,
FILE(IN2) INPUT,
FILE (OUT) OUTPUT ;
READ FILE(IN1) SET(A);
READ FILE(IN2) SET(B);
NEXT:
IF ITEM1>ITEM2 THEN DO;
WRITE FILE(OUT) FROM(ITEM2):
READ FILE(IN2) SET(B);
GO TO NEXT;
END;
ELSE DO;
WRITE FILE(OUT) FROM(ITEM1);
READ FILE(IN1) SET(A);
GO TO NEXT;
END;
FINISH:
CLOSE FILE(IN1),FILE(IN2),FILE(OUT):
END MERGE:
/*

//GO.INl
//GO.IN2
//GO.OUT

DO
DO
DO

//

Figure 11-4.
128

DSNAME=DS1,DISP=(OLD,KEEP),UNIT=2400,VOLUME=SER=33731
OSNAME=DS2 ,DISP= (OLD ,KEEP) , UNIT=2400" VOLUME=SER=9876S5
DS~AME=DS3,DISP=(NEW,KEEP),UNIT=2400,

OCB= (RECFM=F, BLKSIZE=lS)
Creating

and Accessing a CONSECUTIVE Data Set

r------y----------------------------------,
I Code I
Action
I
~------+---------------------------------~
b
'-

o

+

1
2
3
4
5
6
7
8
9
A
B
C
V
W

II

Space one line before
printing (blank code)
Space two lines before printing
Space three lines before printing
Suppress space before printing
Skip to channel 1
Skip to channel 2
Skip to channel 3
Skip to channel 4
Skip to channel 5
Skip to channel 6
Skip to channel 7
Skip to channel 8
Skip to channel 9
Skip to channel 10
Skip to channel 11
Skip to channel 12
Select stacker 1
Select stacker 2

~--_--~L----------------------------------~

IThe channel numbers refer to the printer I
Icarriage control tape.
(See IBM 1403
I
I printel:-Component'
Description.)
L
____________________________
...;. _____________ JI

Figure 11-5.

ANS Printer and Card Punch
Control Characters

SKIP, etc). Nevertheless, you can still
exercise some control over the layout of
printed output by including a printer
control code as the first byte of each of
your output records: you can also use
similar control codes to select the stacker
to which cards punched by your program are
fed.
The operating system recognizes two
types of code for printer and card punch
commands, ANS code and machine code. You
must indicate which code you are using,
either in the RECFM subparameter of your DO
statement or in the ENVIRONMENT attribute
in your PL/I program. If you specify one
of these codes, but transmit your data to a
device other than a printer or a card
punch, the operating system will transmit
the control bytes as part of your records.
If you use an invalid control character,
'space one line' or 'stacker l ' will be
assumed.
The ANS control characters (Figure 11-5)
cause the specified action to occur before
the associated record is printed or
punched.
The machine code control characters
differ according to the type of device.
Figure 11-6 lists the codes for the 1403
printer, and Figure 11-7 gives those for
the 2540 Card Read Punch. There are two
types of command for the printer, the one
causing the action to occur after the
record ,has been transmitted, and the other
producing immediate action but transmitting

PRINTING AND PUNCHING CARDS
You cannot use a PRINT file for
record-oriented transmission, and
record-oriented transmission statements
cannot include the printing options (PAGE,

r-----------------T-----------------------T-----------------,
I
I Act immediately I

I Print and then
act
I

I

Action

~------------------~

I

Code byt e

I

(no printing>

I

I------------------~

I

I

Code byte

I

~------------------+-----------------------+----------------~

00000001
00001001
00010001
00011001
10001001
10010001
10011001
101.00001
101.01001
101.10001
101.11001
11000001
110101001
110110001
110111001
11100001

~--_----

Print only (no space) i
Space 1 line
i
Space 2 lines
!
Space 3 lines
Skip to channel 1
Skip to channel 2
Skip to channel 3
Skip to channel 4
Skip to channel 5
Skip to channel 6
Skip to channel 7
Skip to channel 8
Skip to channel 9
Skip to channel 10
Skip to channel 11
Skip to channel 12

00001011
00010011
00011011
10001011
10010011
10011011
10100011
10101011
10110011
10111011
11000011
11001011
11010011
11011011
11100011

. ---------.L-----------------------.L-----------______ ~

I'l.'he cha.nnel numbers refer to the printer carriage control I
IL _______
tape. (see
IBM 1403 Printer Component '____________________
Description.>
.._______________________________
JI
Figure 1.1-6.

1403 Printer Control Codes
Chapter 11: Record-Oriented

Transmis~ion

129

no data (i.e., you must include the second
type of command in a blank record).

The essential requirements for producing
printed output or punched cards are exactly
the same as those for creating any other
CONSECUTIVE data set (described above).
For a printer, if you do not use one of the
control codes, all data will be printed
sequentially, with no spaces between
records; each block will be interpreted as
the start of a new line. When you specify
a block size for a printer or card punch,
and are using one of the control codes.,
include the control bytes in your block
size; for example, if you want to print
lines of 100 characters, specify a block
size of 101.

Example
The program in Figure 11-8 uses
record-oriented transmission to read and
print the contents of the data set SINES,
which was created by the PRINT file in
Figure 10-5. since the data set SINES was
cataloged, only two parameters are requ:ired
in the DD statement that defines it. The
output file PRINTER is declared with the
ENVIRONMENT option CTLASA, ensuring that
the first byte of each record will be
interpreted as an ANS printer control code.
The information given in the ENVIRONMENT
attribute could alternatively have been
given in the DD statement as follows:
DCB=(RECFM=UA,BLKSIZE=94)

r------------T------------------,

I Code bytes I
Action
I
~---~--------+------------------~
I 00000001 I Select stacker 1 I
I 01000001 I Select stacker 2 I
IL____________
1000qOOl I __________________
Select stacker 3 JI
~

Figure 11-7.

2540 Card Read Punch Control
Codes

INDEXED Data Sets
A data set with INDEXED organization can
exist only on a direct-access device. Each
record in the data set is identified by a
key that is recorded with the record. A
key is a string of not more than 255
characters; all the keys in a data set must
have the same length. The records in the
data set are arranged according to the
collating sequence of their keys. Once an
INDEXED data set has been created, the keys
facilitate the direct retrieval, addition,
and deletion of records.

INDEXES
To provide faster access to the records in
the data set, the operating system creates:
and maintains a system of indexes to the
records in the data set,. The lowest level
of index is the track index. There is a
track index for each cylinder in the data
set; it occupies the first track (or
tracks) of the cylinder, and lists the keys
of the last records on each track in the
cylinder.. A search can then be directed t:o
the first track that has a key that is
higher than or equal to the key of the
required record.

//J036PGEX JOB
//COLEEX EXEC PL1LFCLG,PARM.PL1L='SIZE=999999'iPARM.LKED='LIST'
//PL1L.SYSIN DD *
PRT:
PROC OPTIONS(MAIN);
DCL TABLE FILE RECORD INPUT SEQUENTIAL,
PRINTER FILE RECORD OUTPUT SEQUENTIAL ENV(V(102) CTLASA),
LINE CHAR(94);
ON ENDFILE(TABLE) GO TO FINISH;
NEXT:
OPEN FILE(TABLE), FILE(PRINTER);
READ FILE(TABLE) INTO(LINE);
WRITE FILE(PRINTER) FROM(LINE)J
GO TO NEXT;
FINISH: CLOSE FILE(TABLE),FILE(PRINTER);
END PRT;
/*

//GO.TABLE DD DSNAME=SINES,DISP=OLD
//GO.PRINTER DD SYSOUT=A

Figure 11-8.
130

Printing with Record-Oriented Transmission

If the data set occupies more than one
cylinder, the operating system develops a
higher level index called a cylinder inder.
Each entry in the cylinder index identifies
the key of the last record in the cylinder.
To incrle~ase the speed of searching the
cylinder index, you can request in a DO
statemeat that the operating system develop
a maste:~ index for a specified number of
cylinde:r.s; you can have up to three levels
of mastcer index.
Figure 11- 9 illustrates
the ind4ex structure. The part of the data
set that contains the cylinder and master
indexes is termed the index area.
When a INDEXED data set is created, all
the re<;()rds are written in what is called
the prime data area. If more records are
added la.ter, the operating system does not
rearranqe the entire data set; it inserts
each ne~v record in the appropriate position
and mOVE~S up the other records on the same
track. Any records forced off the track by
the insertion of a new record are placed in
an Qverj:low area. The overflow area can
consist "either of a number of tracks set
aside in each cylinder for the overflow
records from that cylinder (cylinder
overf lmi area), or a separate area for all
overflo~i records (independent overflow
area).
Figure 11-10 shows how the records in
the overflow area are chained together and

to the track index so as to maintain the
logical sequence of the data set. Each
entry in the track index consists of two
parts:
1.

The normal entry, which points to the
last record on the track.

2.

The overflow entry, which contains the
key of the first record trans~erred to
the overflow area and also points to
the last record transferred from the
track to the overflow area.

If there are no overflow records from the
track, both index entries point to the last
record on the track. An additional field
is added to each record that is placed in
the overflow area. It points to the
previous record transferred from the same
track; the first record from each track is
linked to the corresponding overflow entry
in the track index.

CREATING AN INDEXED DATA SET
When you create an INDEXED data set, your
program must write the records in the data
set sequentially in the order of ascending
key values; the associated file must be
opened for SEQUENTIAL OUTPUT.
Master Index

Cylinder Index
. - - - -..- - - - - - - - -... 200

300

375

450

500

600

700

900

1000

1200

1500

2000

Cylinder 1

Cylinder 11

100

100

200

200

Track
Index

Oat a
10I

Data
20

Data
40

Data
100

Prime
Data

Oat a
1510

Data
175

Data
190

Data
200

Prime
Data

1500

2000

Overflow

Figure 11-9.

Index Structure of INDEXED Data Set
Chapter 11: Record-Oriented Transmission

131

Overflow Entry

Normal Entry
Track
1

100

Initial Format

Track

200

2

I

200

Track
TrOlck
2_ _....J Index

---JL..-_ _ _- - L_ _

----1OO
20_ _ _ _ _--'-_ _ _ _ _40
_ _ _ _ _...L-_ _ _ __ _ _ _ _....J1 Prime

10

Data
150

175

I

200

190

.....JI Overflow

L...-_ _ _ _ _ _ _ _ _' - - _ ._ _ _ _ _ _ _---l_ _ _ _ _ _ _ _ _ _- - '_ _ _ _ _ _ _ _ _

Add Records
25 and 101

Track
1

40

Track
Index

100

10

20

25
Prime
Data

150

101

Add Records
26 and 199

100

Track
1

200

26

Track
1

100

10

175

190

Track

Overflow

2

Track 3
Record 3

Track
2

190

20

25

Track 3
Record 4

200

TI"1::lck
Index

26

Prime
DOlta
101

150

175

190

r---l~o::::l~0--~:--T-ra-lc-k--~---2~~--------r-----~-------~----~~------~
Overflow

Figure 11-10.

Adding Records to an INDEXED Data Set

Once an INDEXED data set has been
created, it can be extended if the file is
reopened for SEQUENTIAL OUTPUT. However,
it is your responsibility to ensure that
the key of the first record to be added to
the data set is higher than the highest key
already contained in the data set. Failure
to ensure this will cause diagnostic
message IHE031I to be printed and the
program will terminate abnormally with a
system completion code of 031.
You can use a single DD statement to
define the whole of the data set (index
area, prime area, and overflow area), or
132

you can use two or three statements to
define the areas independently. If you use
two DD statements, you can define either
the index area and the prime area together,
or the prime area and the overflow area
together.
If you want the whole of the data set to
be on a single volume, there is no
advantage to be gained by using more than
one DD statement except to define an
independent overflow area (see 'Overflow
Area,' below). But, if you use separate DD
statements to define the index and/or
overflow areas on volumes separate from

that which contains the prime area" you
will increase the speed of direct access to
the rea)rds in the data set by reducing the
nUItlber of access mechanism movements
required.
When you use two or three DD statements
to define an INDEXED data set, the
statements must appear in the order: index
area; prime area; overflow area. The first
DD state!ment must have a name (ddname), but
the name! fields of a second or third DD
statement must be blank. The DD statements
for the prime and overflow areas must
specify ,the same type of unit (UNIT
paramete!r) • You must include all the DCB
informat,ion for the data set in the first
DD state:ment; DCB=DSORG=IS will suffice in
the other statements ..

Essential Information
In general, all the information given above
for the creation of a CONSECUTIVE data set
on a direct-access d.evice applies equally
to an INDEXED data set. The following
paragraphs discuss only the constraints
imposed by the use of INDEXED organization
and the additional information you must
supply or may want to give. Figure 11-11
summarizes all the essential parameters
required in a DD statement for the creation
of an INDEXED data set, and Figure 11-12
lists the DCB subparameters needed.

Appendix B contains a description of all
the parameters of the DD statement.

You cannot place an INDEXED data set on
a system output (SYSOUT) device.

You must request space for the prime
data area in the SPACE parameter. Your
request must be in units of cylinders
unless you place the data set in a specific
position on the volume (by specifying a
track number in the SPACE parameter). In
the latter case, the number of tracks you
specify must be equivalent to an integral
number of cylinders, and the first track
must be the first track of a cylin.der other
than the first cylinder in the volume. You
can also use the SPACE parameter to specify
the amount of space to be used for the
cylinder and master indexes (unless you use
a separate DD statement for this purpose).
If you do not specify the space for the
indexes, the operating system will use part
of the independent overflow area; if there
is no independent overflow area, it will
use part of the prime data area.
In the DCB parameter, you must always
state the data set organization (DSORG=IS),
and in the first (or only) DD statement you
must also give the length of the keys
(KEYLEN).

r-------'--------------------------------------------------------------------------------,
Parameters of DD Statement
I

I

~-------,·---------------------------T------------------------T------------------------~

I

When required

I

What you must state

I

Parameters

I

1--------..----------------------------+------------------------+-------------------------i
I

I Output device

I UNIT= or VOLUME=REF=

I

i--------------------------+-------------------------i
I storage space required
I SPACE=
I

I

I
I Always

t-------------------------+-------------------------~
I Data control block
I
I
I information: refer to
I DCB=
I
I
I
I
I Figure 11.12
I--------.----------------------------+-~-----------------------+-------------------------i
I
I Name of data set and
I
I
IMore than one DD statement
I area (index, prime,
I DSNAME=
I
I
I overflow)
I
I
t-------·----------------------------+-------------------------+--------------------~----i
IData set to be used in another job I
I
I
I Disposition
I DISP=
I
I step but:. not required after end
lof job
I
I
I

I
I

t------------------------------------+-------------------------+-------------------------i
I Data se1: to be kept after end
I Disposition
I DISP=
I
lof job
t-------------------------+-------------------------i
I
I Name of data set
I DSNAME=
I
~------------------------------------+--------------~----------+-------------------------i
I Volume serial number
I VOLUME=SER= or
I
____________________________________ I _________________________ I _________________________
JI
ILvolume
VOLUME=REF=

I Data se1: to be on particular

~

,F'igure 11-11.

~

creating an INDEXED Data Set:: Essential Parameters of DD Statement
Chapter 11: Record-Oriented Transmission

133

Name of Data Set

If the data set is temporary, prefix its
name with &&. If you use one DD statement
to define the prime and index or prime and
overflow areas, code DSNAME=name(PRIME)i if
you use only one DD statement, code
DSNAME=name(PRIME), or simply DSNAME=name.

If you use only one DD statement to define
your data set, you need not name the data
set-unless you intend to access it in
another job. But, if you include two or
three DD statements, you must specify a
data set name, even for a temporary data
set.

Record Format and-Keys

The DSNAME parameter in a DD statement
that defines an INDEXED data set not only
gives the data set a name, but it also
identifies the area of the data set to
which the DD statement refers:

An INDEXED data set can contain both fixedand variable-length records, blocked or
unblocked.
You must always include the
subparameter RECFM in your DD statement Ol~
specify the record format in your PL/I
program (ENVIRONMENT attribute).

DSNAME=nameCINDEX)

The key associated with each record can
be contiguous with or embedded wi thin'- the
data in the record; you can save s~orage
space in the data set if you use blocked
records with embedded keys.

DSNAME=nameCPRIME)
DSNAME=nameCOVFLOW)

r--------------------------.------------------------------------------------------------,

I

I

DCB Subparameters

~---------------------------T-------------------------------------~---------------------~

I

I

To specify

I

subparameters

I

~--------------------------+--------------------------------.-----+--------------------~

I

I Record format j.
I

I

I

I RECFM= F, FB, FBS"
I V2 , or VB2

I
I

~-------------------------------------+-------------------.-~

I
I These are always required
I

I Block siz ej.

I

~-----.--------------------------------+-------------------.-~

I

I BLKSIZE=

I

~-----.--------------------------------+-------------------.-~

IData set organization
IKey length

I DSORG=IS
IKEYLEN=

I
I

~-------------------------+-----.--------------------------------+-------------------.-~

I
I
I Include at least one of
I these if overflow is
I required

ICylinder overflow area and
I number of tracks per cylinder f or
loverflow I-'ecords

I
I
IOPTCD=Y and CYLOFL= I
I
I

l-----.-----.-----------------------------+-------------------~

IIndependent overflow area

IOPTCD=I

I

~-------------------------+-----------.---------------------------+-------------------~

IRecord lengthj.

ILRECL=

I

.-------------------------------------+--------------------~
IEmbedded key (relative key position)

Thes e are optional

IRKP=

I

~--------------------------------------+--------------------~

I Master inclex
I OPTCD=M
I
~--------------------------------------+--------------------~
IAutomatic processing of dummy records IOPTCD=L
I
~--------------------------------------+--------------------~
I Number of data management buffersj.
I BUFNO=
I
~-------------------------------------+--------------------~
I Number of tracks in cylinder index
I NTM=
I
Ifor each master index entry
I
I

~---------------------------~--------------------------------------~--------------------~

Ij.Alternatively, can be specified in ENVIRONMENT attribute.

I

I2
1 For V or VB format records, it is essential that RKP is specified with a value that

I

I

LI _______________________________________________________________________________________
is equal to or greater than 4.
JI

Note: Full DCB information must appear in the first, or only, DD statement. Subsequent
statements require only DSORG=IS.
• Figure 11-12.

134

DCB Subparameters for INDEXED Data set

If the records are unblocked, the key of
each record is recorded in the data set in
front o,f the record even if it is also
embedded within the record (Figure 11-13,
(a) and (b», If blocked records do not
have embedded keys, the key of each record
is recorded within the block in front of
the record, and the key of the last record

in the block is also recorded in front of
the block (Figure 11-13(c». When blocked
records have embedded keys, the individual
keys are not recorded separately in front
of each record in the block; the key of the
last record in the block is recorded in
front of the block (Figure 11-13(d».

(a) Unblocked records, non-embedded keys
r--~

--'------,

LIKeYI
___.L __Data
.•• _____ JI

r---T--------,
IKeYI Data I
L ___ .L ________ J

r---T-------,
IKey I Data I
L___ .L ________ J

(b) Unblocked records, embedded keys
r----- Data ------,

r---T--·---T---T-----'
IKeYI

IKeYI

I

L __ --L ______ .L ___ .L _____ J

A

r----- Data ------,

r----- Data ------,

r---T-----T---T----'

r---T-----T---T-----'

IKeYI
IKey
I _____ JI
L
___.L _____ .L
___ .L

IKeYI
IKeYI
L ___ .L _____ .L
___ .L_____ JI

A

I

L-samE~

I

key-J

(c) Blocked records, non-embedded keys

r--T--T----

r"---T---T----------T---T----------T---T---------,

IKeylKeYI
Data
IKeYI
Data
IKeYI
Data
L ___ .L ___•.L _________
.L
___ .L __________
.L
___ .L _________
JI
A

A

I

I

IKeylKeYI
L
___ .L ___ .L _ _ _

L-----·-------same key-------------J

Cd) Blocked records, embedded keys
r-----Data-----, r-----Data-----'r-----Data------,

r---T---·'--T---T-----T-----T---T-----T-----T---T-----,
IKeYI

I

IKeYI

IKeYI

I

I

IKeYI

L ___ .L ___,__ .L ___ .L_____ .L _____ .L ___ .L _____ .L ____ .l.- __ .L _____ J

A

A

I

I

r---T-----T----

IKeYI
I
L
___ .L __ .... __ .L-__
_

L----------------same key----------------·-J

(e) Unblocked variable length records, RKP>4

r----- Data ------,

r---T--T·--T-----T---T-----'

LIKeYIBllRll
___ .L __.L. __ .L ____ .LIKeYI
___ .L _____ JI

A

A

I

I

L----same key---J

Cf> Blocked variable length records, RKP>4
r------Data-----,

r------Data-----,

r------Data-----,

r--~-~·--T----T---T-----T--T-----T---T-----T--T-----~--T-----'

IKeYIBllJRll

IKeYI

IRII

IKeYI

IRII

IKeYI

I

L ___ .L __ .L. __ .L _ _ _ .L ___ .L _____ .L __ .L _____ .L ___ .L _____ .L __ .L _____ .L ___ .L ____ J

A

A

I

I

L-----···-----------------same key----------------------J

Chapter 11: Record-Oriented Transmission

135

(g) Unblocked variable length records, RKP=4
r- Data,
r---T-~--T--~-----'
~

~

~

IKeylBIIRIIKeYI
L ___ __ __ ___ L- ____ JI

A

A

I

I

L-same keyJ

Ch) Blocked variable length records, RKP=4
r- Data,

r- Data,

r- Data,

r---T--T--T---T-----T--T---T-----T--T---T-----'
\Key \BI\RIIKeYI
IRII Key I
I RIIKey\
I
L ___ J. __ J. __ J. ___ _____
~

~

__

~

__ -.l. ____ __L_._.J. __ ._J. ____ J

A

A

I

I

L--------------same key-------------J

Figure 11-13.

Record Formats in all INDEXED Data Set

If you use blocked records with
non-embedded keys, the record size that you
specify must include the length of the key,
and the block size must be a multiple of
this combined length. Otherwise, record
size and block size refer only to the data
in the record.
(See Figure 11-14.)

r-----------T-------~-----~-------------,

I

I

RKP

I LRECL\

BLKSIZE

I

~-----------+---.-----+-----+-------------~

I

I

I

I

I Not zero I

Blocked
records

R

I

R * B

I

~--------+------+-------------~

IZero or I R + KI
lomitted I
I

B * (R+K)

I

\

~----------+--------+------+------------.-~

If you use records with embedded keys,
you must include the DCB subparameter RKP
to indicate the position of the key within
the record. For fixed-length records the
value specified in the RKP subparameter is
one less than the byte number of the first
character of the key: that is, if RKP=1.,
the key starts in the second byte of the
record. The value assumed if you omit this
subparameter is RKP=O, which specifies that
the key is not embedded in the record but
is separate from it.

I
I Not zero I
R I
R
I
I Unblocked ~---.---+------+-------------~
I records I Zero or I
R I
R
I
I
lomi·tted I
\
I
~----------+---.-----+------+-------------~

I V-Blocked I
I

records

>4

I

I
I

~R+4

I
I

~1*(R+4)+4

\

I

~----------+--------+------+-------------~

I V-Unblocked I
I

records

>4

I

I
I

~R+4

I

~R+8

I

I
I

~-----------+--------+------+------------~

I V-Blocked \
I

records

=4

I

I~R+K+41~1*(R+K+4)+4

I

\

\
I

~-----------+--------+------+-------------~

For variable-length records, the value
specified in the RKP subparameter must be
the relative position of the key within the
record plus four. The extra four bytes
takes into account the 4-byte control field
used with variable-length records. For
this reason you must never specify RKP less
than four. When deleting records you must
always specify RKP equal to or greater than
five, since the first byte of the data is
used to indicate deletion.

IV-Unblocked I
I records
\

=4

1~+K+41

I

~R+K+8

\

~-----------~------~------~-------------~
IR = Size of data in record

I

\K = Length of keys (as specified in
\
KEYLEN subparameter)

I

IB = Blocking factor
\
I Example: For blocked records,
I
non-embedded keys, 100 bytes of
I
data per record, 10 records per
I
block, key length = 20:
LI __________________________________________
LRECL=120,BLKSIZE=1200,RECFM=FB J

Note: For unblocked records, the key, even
if embedded, is always recorded ill a
position preceding the actual data.

Figure 11-14.

Consequently, the RKP subpa.rameter need not
be specified for fixed length unblocked

records as the default RKP value is o.
Under these circumstances the key is only

136

\
\

Record Format Information
for an INDEXED Data Set

once in the block. For variable
length records the minimum RKP value is 4
and the RKP must always be specified.

Dummy Records

record~~d

You cannot change the specification of an
INDEXED data set after you have created it.
Therefore, you must foresee your future
needs where the size and location of the
index, prime, and overflow areas are
concerned, and you must decide whether you
want the operating system to identify and
skip dummy (deleted) records ..

overf19w Area
I·f you intend to add records to the data
set on a future occasion, you must request
either a cylinder overflow area or an
independent overflow area, or both.

If you code OPTCD=L, the operating
system will flag any record that is named
in a DELETE statement by placing the bit
string (8)'l'B 'in the first byte.
Subsequently, during SEQUENTIAL processing
of the data set, such records will be
ignored: if they are forced off a track
when the data set is being updated, they
will not be placed in the overflow area.
Do not specify OPTCD=L when you are using
blocked records with non-embedded keys; if
you do, the string (8) "1" B will overwrite
the key of the Udeleted' record.

For a cylinder overflow area, include
the DCB sUbparameter OPTCD=Y and use the
subparc~eter CYLOFL to specify the number
of trac~s in each cylinder to be reserved
for oVE!rflow records. A cylinder overflow
area hals the advantage of a short search
time fc)r overflow records, but the amount
of spac:e available for overflow records is
limited, and much of the space may be
unused if the overflow records are not
evenly distributed throughout the data set.
For an independent overflow area, use
the DCE: subparameter OPTCD=I to indicate
that ov'erflow records are to be placed in
an area. reserved for overflow records from
all cylinders, and include a separate DD
statement to define the overflow area. The
use of an independent overflow area has the
advantage'of reducing the amount of unused
space for overflow records, but entails an
increased search time for overflow records.
It is good practice to request cylinder
overflow areas large enough to contain a
reasonable number of additional records and
an independent overflow area to be used as
the cylinder overflow areas are filled.
If the prime data area is not filled
during creation, you cannot use the unused
portion for overflow records, nor for any
records subsequently added during direct
access (although you can fill the unfilled
portion of the last track used). You can
reserve space for later use within the
prime da.ta area by writing 'dummy' records
during creation: see 'Dummy Records,'
below.

Master l;ndex;
If you ~1ant the operating system to create
a mastel~ index for you, include the DCB
subparameter OPTCD=M, and indicate in the
NTM subparameter the number of tracks in
the cylinder index you wish to be referred
to by each entry in the master index. The
operating system will automatically create
up to three levels of master index, the,
first two levels addressing tracks in the
next. lower level of master index.

You can include a dummy record in an
INDEXED data set: by setting the first byte
of data to (8)' l"B and writing the record
in the usual way.

ACCESSING AN INDEXED DATA SET
You can open an existing INDEXED data set
for sequential or direct access, and for
input or update in each case. sequential
input allows you to read the records in
ascending key sequence, and in sequential
update you can read and rewrite each record
in turn: during sequential access, if
OPTCD=L was specified when the data set was
created, dummy records are ignored. Using
direct input, you can read records using
the READ statement, and in direct update
you can read or delete existing records or
add new ones.
Note that only one DIRECT UPDATE file
should be open at anyone time to add
records to an INDEXED data set. Further,
if two files are open simultaneously, one
for sequential and one for direct
processing of the same INDEXED data set,
some records might become inaccessible to
the SEQUENTIAL file due to changes to track
indexes made for the DIRECT file when it
adds records to the data set. The records
that may be inaccessible are those added to
the INDEXED data set in the following ways:
1.

Records added to the end of the data
set.

2.

Records written directly into the
overflow area of the data set.

Chapter 11:'Record-Oriented Transmission

137

r----------------------------------------------------------------------------------------,
Parameters of DD statement
I

I

~--------------------------------·-T--·--------------~------T--·-----------------------·~

I

When required

I

What you must state

I

Parameters

,

~---------------------------------.-+-----------------------+-------------------------~

I
I Al ways
I
I
I

I Name of data set

I DSNAME=

I

~--------------.--------+--------------------------~

I Disposition of data set I DISP=

I

~-----------------------+--------------------------~

I Data Set Organization

I DCB=DSORG=IS

I

~--------------------------------+------------------------+-------------------------~

I
I Input device
I UNIT= or VOLUME=REF=
I
I If data set not cataloged
~------------------------+_-----------------------.-~
JI
IL __________________________ .________ iI _________________________
Volume serial number
I _________________________
VOLUME=SER=
~

• Figure 11-15.
3.

Accessing an INDEXED Data Set: Essential Parame·ters of DO statement

Records·· written on -the overflow area
when forced out of the prime data area
by records being added to the prime
data area.

large, and reorganize the data set at
regular intervals (see below).

REORGANIZING AN INDEXED DATA SET
access an existing INDEXED data set,
you must identify it to the operating
system in one, two or three DD statements;
the DO statements must correspond 'with
those used when the data set was created.
The following paragraphs indicate the
essential information you must include in
each DD statement, and Figure 11-15
summarizes this information. Appendix B
describes the parameters referred to, and
tells you how to code them.
'1'0

If the data set is cataloged, you need
supply only the following information in
each DD statement:
1.

The name of the data set (DSNAME
parameter). The operating system will
locate the information that describes
the data set in the system catalog
and, if necessary, will request the
operator to mount the volume that
contains it.

2.

Confirmation that the data set already
exists (DISP parameter).

3.

Confirmation that the data set
organization is INDEXED (DSORG
subparameter'of the DCB parameter).

If the data set is not cataloged, you
must, in addition, specify the device ·that
will process the data set and give the
serial number of the volume that contains
it (UNIT and VOLUME parameters).

It is necessary to reorganize an INDEXED
data set periodically because the addition
of records to the data set results in an
increasing number of records in the
overflow area. Therefore, even if the
overflow area does not eventually become
full, the average time required for the
direct retrieval of a record will increase.
The frequency of reorganization depends on
how often the data set is updated, on how
much storage is available in the data set,
and on your timing requirements.
Reorganizing the data set also
eliminates records that are marked as
• deleted,' but are still present within the
data set.
There are two ways to reorganize an
INDEXED data set:
1.

Read the data set into an area of ma:in
storage or onto a temporary
CONSECUTIVE data set, and then
recreate it in the original area of
auxiliary storage.

2.

Read the
write it
storage;
original

data set sequentially and
into a new area of auxiliaI~y
you can then release the
auxiliary storage.

EXAMPLES OF INDEXED DATA SETS
Note: If you add a new record to a data set
whose overflow areas are already full, the
new record will not be added to the data
set and the file will remain unchanged; the
KEY condition will be raised. To reduce
the likelihood of this occurrence, ensure
that your overflow areas are sufficiently
138

Figure 11-16 illustrates the creation of a
simple INDEXED data set. The data set
contains a telephone directory, using the
subscribers' names as keys to the telephone
numbers.

/ /J0021)GEX JOB
//CREA'l?E EXEC PL1LFCLG,PARM.LKED='LIST'
//PL1L.SYSIN DD *
TELNOS: PROC OPTIONS(MAIN);
'DCL DIREC FILE RECORD SEQUENTIAL KEYED ENV(INDEXED),
CARD CHAR (80) ,
NAME CHAR(20) DEF CARD,
NUMBER CHAR(3) DEF CARD POS(21),
IOFIELD CHAR(3);
ON ENDFILE(SYSIN) GO TO FINISH;
OPEN FILE(DIREC) OUTPUT;
NEXTIN: GET FILE(SYSIN) EDIT(CARD)(A(80»;
IOFIELD=NUMBER;
WRITE FILE(DIREC) FROM (IOFIELD) KEYFROM(NAME),
GO TO NEXTIN;
FINISH: CLOSE FILE(DIREC);
END TELNOS;
/*

/ /GO. DIREC DD UNIT=2 311, SPACE= (CYL, 1) , DCB: (RECFM=F" BLKSI ZE=3" DSORG=IS,
KEYLEN=20,OPTCD=LIY,CYLOFL=2),DSNAME=TELNO(INDEX),
//
DISP=(NEW,KEEP),VOLUME=SER=D186
//
DD UNIT=2311, SPACE= (CYL,4) , DCB=DSORG=IS"DSNAME=TELNO(PRIME) "
//
DISP=(NEW,KEEP),VOLUME=SER=D186
//
//
DD UNIT=2 311" SPACE= (CYL" 4) , OCB=DSORG=I S,
DSNAME=TELNO(OVFLOW),DISP=(NEW,KEEP),VOLUME=SER=D186 .
//
//GO.SYEiIN DD
*
ACTION,(3.
162
BAKER,R ..
152
248
BRAMLEY"O.H.
CHEESEM1\N , L.
141
CORY,G.
336
875
ELLIOTT I' D•
413
FIGGINS., S •
205
HARVEY,C.D.W.
391
HASTINGS,G.M.
294
KENDALL"J .G.
624
LANCAS TE~R, W. R •
233
MILES,R.
450
NEWMAN,l-i. W.
515
PITT,W.H.
114
ROLF,D.E:.
241
SHEERS,C:.D.
472
SUTCLIFFE,M.
TAYLOR,G.C.
407
404
WILTON ,I•• W.
WINSTONE,E.M.
307
/*

Figure 1.1-16.

Creating an INDEXED Data Set

The program in Figure 11-17 updates this
data set and prints out its new contents.
The input data includes codes to indicate
the operations required:
A:
C:
D:

Add a new record
Change an existing record
Delete an existing record

REGIO:NrAL Data Sets
A dpta set with REGIONAL organization can
exist only on a direct-access device. A

REGIONAL data set is divided into regions
that are numbered consecutively from zero.
The following paragraphs briefly describe
the three types of REGIONAL organization.

In a REGIONAL(l) data set, a region is a
record. Each record in the data set is
identified by its region number, an
unsigned decimal integer not exceeding
16777215. Region numbers start from 0 at
the beginning of the data set. There are
no recorded keys.

Chapter 11: Record-Oriented Transmission

139

//J041PGEX JOB
/ /COLEEX EXEC PL1LFCLG, PARM. PL1L=' SIZE=999999',~ PARM. LKED=" LIST'
//PL1L.SYSIN DO *
DIRUPDT:PROC OPTIONS(MAIN);
DCL DIREC FILE RECORD KEYED ENV(INDEXED),
NUMBER CHAR (3) ,
NAME CHAR(20),
CODE CHAR(l);
ON ENDFILE(SYSIN) GO TO PRINT;
ON KEY(DIREC) BEGIN;
IF ONCODE=51 THEN PUT FlLE(SYSPRINT) SKIP EDIT
('NOT FOUND: ',NAME) (A(15),A);
IF ONCODE=52 THEN PUT FlLE(SYSPRINT) SKIP EDIT
('DUPLICATE: ',NAME) (A(15),A);
END;
OPEN FILE(DIREC) DIRECT UPDATE;
NEXT:
GET FILE(SYSIN) EDIT(NAME,NUMBER,CODE)(A(20),A(3),X(56),A(1»;
IF CODE='A' THEN WRITE FlLE(DlREC) FROMCNUMBER) KEYFROM(NAME);
ELSE IF CODE='C' THEN REWRITE FlLE(DIREC) FROM (NUMBER)
KEY (NAME) ;'
ELSE IF CODE='D' THEN DELETE FlLE(DIREC) KEY(NAME);
ELSE PUT FILE(SYSPRINT) SKIP EDITe'INVALID CODE:';
NAME) (A(15),A);
GO TO NEXT;
PRINT: CLOSE FILE(DIREC);
PUT FILE(SYSPRINT) PAGE;
OPEN FILE(DIREC) SEQUENTIAL INPUT;
ON ENDFlLE(DlREC) GO TO FINISH;
NEXTIN: READ FILE(DIREC) INTO(NUMBER) KEYTO(NAME);
PUT FILE(SYSPRINT) SKIP EDIT (NAME, NUMBER) (A);
GO TO NEXTIN;
FINISH: CLOSE FILE(DIREC);
END DIRUPDT;
/*

//GO.DIREC DO DSNAME=TELNO(INDEX),DISP=(OLD,KEEP),UNIT=2311,
//
VOLUME=SER=D186,DCB=DSORG=IS
//
DO DSNAME=TELNO (PRIME) , DISP= (OLD, KEEP) " UNIT=2311,
//
VOLUME=SER=D186,DCB=DSORG=IS
//
DO DSNAME=TELNO(OVFLOW) ,DISP=(OLD,KEEP) ,UNIT=2311"
//
VOLUME=SER=D186.DCB=DSORG=IS
//GO.SYSIN DO *
NEWMAN,M.W.
516450
GOODFELLOW,D.T.
889
MILES,R ..
233
HARVEY,C.D.W.
209
BARTLETI',S.G.
183
336
CORY,G.
READ,K.M.
001
PITT,W.H.
515
ROLF,D.F.
114
ELLIOTT,D.
291875
HASTINGS,G.M.
391
BRAMLEY,O.H.
439248
/*

• Figure 11-17.

140

Updating an INDEXED Data Set

C
A

o
A
A

o
A

o
C

o
C

REGJCONAL(2) organization is similar to
but differs in that a key is
recordE~d with each record.
The record key
is a st:ring of not more than 255
charact:ers. A record is written in the
first ~racant space after the beginning of
the track that contains the region number
specified in the WRITE statement: for
retrieval, the search for a record begins
on the track that contains the region
number specified in the READ statement, and
may continue through the data set until the
record has been found.

CREATING A REGIONAL DATA SET

REGION}~(l),

A REGIONAL(3) data set is similar in
organization and in operation to a
REGIONA:L(2) data set, with the difference
that each region corresponds to one track
of the direct-access device and is not a
record position. Therefore, depending on
the record size, a region can contain one
or more records.
The major advantage of REGIONAL
organizcltion over other types of data set
organizCltion is that it allows you to
control the relative placement of records;
by judicious programming, you can optimize
record access in terms of device
capabili.ties and the requirements of
particular applications. REGIONAL (1)
organization is most suited to applications
where there will be no duplicate region
numbers, and where most of the regions will
be filled (obviating wasted space in the
data set). REGIONAL (2) and REGIONAL(3) are
more appropriate where records are
identified by numbers that are thinly
distributed over a wide range. You can
include in your program an algorithm that
derives the region number from the number
that identifies a record in such a manner
as to optimize the use of space within the
data set; duplicate region numbers will
occur, but their only effect might be to
lengthen the search time for records with
duplicabe region numbers.
REGIONAL(l) and REGIONAL(2) data sets
can contain only F-format unblocked
records, but a REGIONAL(3) data set can
have unblocked records of all three
formats, F, V, and U. The examples at the
end of this section illustrate typical
applications of all three types of REGIONAL
organizat:ion.

You can use either sequential or
direct-access to create a REGIONAL data
set.

In sequential creation, you must present
records in order of ascending region
numbers: for REGIONAL(l) and REGIONAL(2)
the region number for each record must
exceed that of the preceding record since
each region can contain only one record.
In all cases, dummy records (identified by
( 8) .• 1" B in the first byte) are placed
automatically in regions whose numbers are
skipped.

For direct creation, one of the PL/I
library subroutines formats the whole of
the data set when you open the
corresponding file. For REGIONAL(l) and
(2), and for REGIONAL(3) with F-format
records, formatting involves filling the
data set with dummy records; for
REGIONAL (3) with U-format or V-format
records, a record, called the capacity
record, is written at the start of each
track to indicate an empty track. During
creation, you can present records in any
order.

Essential Information

In general, all the information given above
for the creation of a CONSECUTIVE data set
on a direct-access device applies equally
to a REGIONAL data set. The following
paragraphs discuss only the constraints
imposed by the use of REGIONAL organization
and the additional information you must
supply or may want to give. Figure 11-18
summarizes all the essential parameters
required in a DD statement for the creation
of a REGIONAL data set, and Figure 11-19
lists the DCB subparameters you will need
to use. Appendix B contains a description
of all the parameters of the DD statement.
You cannot place a REGIONAL data set on
a system output (SYSOUT) device.

Chapter 11: Record-Oriented Transmission

141

r---------------------------------------------------------------------------------------,
Parameters of DD statement
I

I

~-----------------------------------T-------------------------~------------------------~
I
When required
I
What you must state
I
Parameters
,
~--------------------------------+-----------------------+-------------------------,~
I
, Output device
, UNIT= or VOLUM$=REF=
I
~------------~----------r-'------------..:.---------~
I
I
I storage space required ,S'PACE=
,I I Always
r----------------------+----------------------.~
I
, Data control block
,
I
I
, information:refer to
I DCB=
I
I
I Figure 1 1 - 1 9 ,
I
~-----------------------------------+-------------------~-----+-------------------------~
IData set to be used in another job I
I
I
Istep but not required in another
,Disposition
I DISP=
I
I job
I
I
I
~----------------------------------+--.--------------------+-------------------------.~
IData set to be kept after end
I of j ob

I

I Disposition

I DISP=

I

~-----------------------+--------------------------~

i DSNAME=

I Name of data set

..

I

~-----------------------------------+-----------------------+------------------------ ~
I VOLUME=SER= or
,

,Data set to be on particular
I volume serial number
IL volume
__________________________________ I

J. _______________________ I

Figure 11-18.

VOLUME=REF=
.L _________________________
.JI

Creating a REGIONAL Data Set: Essential Parameters of DD Statement

In the DCB parameter, you must always
state the data set organization (DSORG=DA).
For REGIONAL(2) and REGIONAL(3), you must
also state the length of the recorded key
(KEYLEN): refer to IBM System/360 operating
system: PL/I (F) Language Reference Manual
for a description of how the recorded key
is derived fro~ the source key supplied in
the KEYFROM option.

For REGIONAL(2) and REGIONAL(3), if you
want to restrict the search for space to
add a new record, or the search for an
existing record, to a limited number of
tracks beyond the track that contains the
specified region, use the LIMCT
subparameter of the DCB parameter. If you
omit this parameter, the search will
continue to the end of the data set, and
then from the beginning back to the
starting point.

r----------------------------------------------------------------------------------------,
DCB Subparameters
I

I

~---------------------------~------------------------------------~--------------------~
I

I

To specify

I

Subparameters

I

~----------------------------+--------------------------------------+--------------------~
I
I
IRECFM=F or
I
IRecord format~
IRECFM=V REGIONAL(3) I
I
I
I
IThese are always required
I

I
I or
only
I
IRECFM=U
I
I
~--------------------------------------+--------------------~
I Block siz e~
I BLKSI ZE= .
I

I
I
I
I

~--------------------------------------+--------------------~
IData set organization

I DSORG=DA

I

~--------------------------------------+-------------------.-~

IKey length (REGIONAL(2) and (3) only) IKEYLEN=

I

~---------------------------+--------------------------------------+-------------------.-~
I
,Limited search for a record or space I
I
Ito add a record (REGIONAL (2) and (3)
ILIMCT=
I
I
IThese are optional

I only)

II

INumber of data management

I

I

~--------------------------------------+--------------------~

I
_________--J.I BUFNO=
__________________ • __

buffers~

~--_------------------------J.----_----------------------

~

I

L______________________________________________________________________________________
•__ J
I~Alternatively,
can be specified in ENVIRONMENT attribute.

Figure 11-19.

142

DCB Subparameters for REGIONAL Data Set

statement. The following paragraphs
indicate the minimum information you must
include in the DD statement; they are
summarized in Figure 11-20. Appendix B
describes the parameters referred to and
explains how to code them.

ACCESSING A REGIONAL DATA SET

You can open an existing REGIONAL data set
for sequential or direct access, and for
inputoJt." update in each case. Using
sequential input with a REGIONAL(l) data
set you can read all the records in
ascending region-number sequence; and in
sequential update you can read and rewrite
each record in turn. sequential access of
a REGIONAL(2) or REGIONAL(3) data set will
give you the records in the order in which
they appear in the data set, which is not
necessaz:ily region-number order. Using
direct j.nput, you can read any record by
supplying its region number and, for
REG IONAI, (2) and REGIONAL (3), its recorded
key; in direct update, you can read or
delete €!xisting records or add new ones.
The opez'ating system ignores dummy records
in a.REGIONAL(2) or REGIONAL(3) data set:
but a pZ'ogram that processes a REGIONAL(l)
data set must be prepared to recognize
dummy records.

If the data set is cataloged, you need
supply only the following information in
your DD statement:

To access a REGIONAL data set, you must
identify it to the operating system in a DD

1.

The name of the data set (DSNAME
parameter). The operating system will
locate the information that describes
the data set in the system catalog
and, if necessary, will request the
operator to mount the volume that
conta ins it.•

2.

Confirmation that the data set already
exists (DISP parameter).

If the data set is not cataloged, you
must, in addition, specify the device that
will read the data set and give the serial
number of the volume that contains the data
set (UNIT and VOLUME parameters).

r-------.··------------------------------------------------------------------------------,
,
Parameters' of DD Statement
I
~-------···--------------------------T----------.--------------~------------------------~

,

...

When required

I

What you must state

I

Parameters

I

~------- --------------------------+-----------------------+------------------------~

I

'Always
,
,
~-------

I.

I Name of data set

I DSNAME=

,

~-----------------------+_------------------------~

, Disposition of data
, set

I DISP=
I

I

,

. ---------------------------+------------------------+_------------------------1
, Input device
I UNIT= or VOLUME=REF=
,

IIf data set not cataloged
~-------------------------+-------------------------~
JI
,l _______ __________________________ , ________________________
Volume serial number
I _________________________
VOLUME=SER=
~

Figure 11-20.

~

~

Accessing a REGIONAL Data set: Essential Parameters of DD Statement

Chapter 11: Record-Oriented Transmission

143

EXAMPLES OF REGIONAL DATA SETS

programs in these figures perform the same
functions as those given for REGIONAL(3),
with which they can usefully be compared.

REGIONAL(1) Data Sets
Figures 11-21 and 11-22 illustrate the
creation and updating of a REGIONAL(l) data
set.
Figure 11-21 uses the same data as
Figure 11-16, but interprets it in a
different way: the data set is effectively
a list of telephone numbers with the names
of the subscribers to whom they are
allocated. The telephone numbers
correspond with the region numbers in the
datp set, the data in each occupied region
being a subscriber's name. The SPACE
parameter of the DD statement requests
space for 1000 twenty-byte records (i.e.,
for 1000 regions); since space is never
allocated in units of less than one track
and one 2311 track can accommodate 45
twenty-byte records, there will in fact be
1035 regions. Note that there are no
recorded keys in a REGIONAL(l) data set.
The data read by the program in Figure
11-22 is identical with that used in Figure
11-17, and the codes are interpreted in the
same way. Like Figure 11-17,. this program
updates the data set and then lists its
contents. Note that before each new or
updated record is written the existing
record in the region is tested to ensure
that it is a dummy~ this is necessary
because a WRITE statement can overwrite an
existing record in a REGIONAL(l) data set
even if it is not a dummy. Similarly,
during the sequential reading and printing
of the contents of the data set, each
record is tested and dummy records are not
printed.

REGIONAL(2) Data Sets
Figures 11-23, 11-24, and 11-25 illustrate
the use of REGIONAL(2) data sets. The

144

The figures depict a library processing
scheme, in which loans of books are
recorded and reminders are issued for
overdue books. Two data sets, STOCK2 and
LOANS2 are involved. STOCK2 contains
descriptions of the books in the library,
and uses the 4-digit book reference numbers
as recorded keys; a simple algorithm is
used to derive the region numbers from the
reference numbers. (It is assumed that
there are about 1000 books, each with a
number in the range 1000-9999.) LOANS 2
contains records of books that are on loan;
each record comprises two dates, the date
of issue and the date of the last reminder.
Each reader is identified by a 3-digit
reference number" which is used as a region
number in LOANS2; the reader and book
numbers are concatenated to form the
recorded keys.

In Figure 11-23, the data sets STOCK2
and LOANS2 are created. The file LOANS,
which is used to create the data set;
LOANS2, is opened for direct output merely
to format the data set; the file is closed
immediately without any records being
written onto the data set. It is assumed
that the number of books on loan will not
exceed 100; therefore the SPACE parameter
in the DD statement that defines LOANS2
requests 100 blocks of 19 bytes (12 bytes
of data and a 7-byte key: see Figure
11-24). Direct creation is also used fox'
the data set STOCK2 because, even if the
input data is presented in ascending
reference number order, identical region
numbers might be derived from successive
reference numbers.

//J010PGEX JOB
/ /COLE:E~X EXEC PL1LFCLG, PARM. PL1L=' SIZE=999999' , PARM. LKED=' LIST'
//PL1L.SYSIN DD *
CRR1:
PROC OPTIONS(MAIN):
DCL NOS FILE RECORD OUTPUT DIRECT KEYED ENV(REGIONALC1»,
CARD CHAR(80),
NAME CHAR C20) DEF CARD,
NUMBER CHAR(3) DEF CARD POS(21),
IOFIELD.CHAR(20):
ON ENDFILE CSYSIN) GO TO FINISH:
OPEN FILE CNOS) :
NEXT:
GET FILE(SYSIN) EDIT(CARD)CAC80»:
IOFIELD=NAME:
WRITE FILECNOS) FROMCIOFIELD) KEYFROMCNUMBER):
GO TO NEXT:
FINISH: CLOSE FILECNOS):
END CRR1:
/*

//GO.NOS DD UNIT=2311,SPACE=C20,1000),DCB=CRECFM=F,BLKSIZE=20,
//
DSORG=DA),DISP=CNEW,KEEP,DELETE),DSNAME=NOS,
//
VOLUME=SER=D186
//GO.S;{SIN DD *
ACTIONI,G.
162
BAKER,H.
152
BRAMLEY,O.H.
248
CHEESM1~N, L.
141
CORY,G ..
336
ELLIOT~~, D.
875
FIGGINS,E.S.
413
HARVEY II C • D. W.
205
HASTINGS,G.M.
391
KENDALl., J • G.
294
LANCAS~rER, W.R.
624
MILES,n.
233
450
NEWMAN I' M. W•
PIT'.r,W .. H.
515
ROLF,D .. E.
114
SHEERS.,C.D.
241
SUTCLI]~FE ,M.
472
TAYLORI,G.C.
407
404
WILTON"L.W.
WIN3TONE,E.M.
307
/*

Figure 11-21.

Creating a REGIONAL(1) Data Set

Figure 11-24 illustrates the updating of
the dat.a set LOANS2. Each item of input
data, read from a punched card, comprises a
book number, a reader number, and a code to
indica1:e whether it refers to a new issue
(I), a returned book (R), or a renewal. (A).
The position of the reader number on the
card allows the 8-character region number
to be derived directly by overlay defining.
The DA~m built-in function is used to
obtain the current date. This date is
wri tten in both the issue-date and
remindE~r-date portions of a new record or
an updated record.
The program in Figure 11-25 uses a
sequen1:ial update file CLOANS) to process
the records in the data set LOANS2, and a
direct input file (STOCK) to obtain the
book d~:!scription from the data set STOCK2
for USE~ in a reminder note. Each record

from LOANS2 is tested to see whether the
last reminder was issued more than a month
ago: if necessary, a reminder note is
issued and the current date is written in
the reminder-date field of the record.

REGIONAL(3) Data Sets
Figure 11-26, 11-27, and 11-28, which
illustrate the use of REGIONAL(3) data
sets, are similar to the REGIONAL(2)
figures, above: only the important
differences are discussed here.
To conserve space in the data set
STOCK3, U-format records are used.
In each
record, the author's name and the title of

Chapter 11: Record-Oriented Transmission

145

//J042PGEX JOB
//COLEEX EXEC PL1LFCLG,PARM. PL1L=' SIZE=999999 ',PARM.LKED=/'LIST'
//PL1L.SYSIN DD *
PROC OPTIONS(MAIN)~
ACR1:
DCL NOS FILE RECORD KEYED ENV(REGIONAL(l»,
NAME CHAR(20),
CNEWNO,OLDNO) CHAR(3),
CODE CHAR(l),
IOFIELD CHAR(20),
BYTE1 CHAR(l) DEF IOFIELD;
ON ENDFILE(SYSIN) GO TO PRINT;
OPEN FILE(NOS) DIRECT UPDATE;
GET FILECSYSIN) EDIT(NAME,NEWNO,OLDNO,CODE)
NEXT:
(A(20),2 A(3),X(53),A(1»;
IF CODE='A' THEN GO TO RITE;
ELSE IF CODE='C' THEN DO;
DELETE FILE(NOS) KEY (OLDNO) ;
GO TO RITE;
END;
ELSE IF CODE='D' THEN DELETE FILE(NOS) KEY(OLDNO);
ELSE PUT FILE(SYSPRINT) SKIP EDIT('INVALID CODE:',
NAME) (A(15),A);
GO TO NEXT:
READ FILE(NOS) KEY (NEWNO) INTO(IOFIELD);
RITE:
IF UNSPEC(BYTE1)=(8)'l'B THEN WRITE FlLE(NOS) KEYFROM(NEWNO)
FROM (NAME) ;
ELSE PUT FILE(SYSPRINT) SKIP EDIT
('DUPLICATE:',NAME) (A(15),A);
GO TO NEXT;
PRINT: CLOSE FlLE(NOS)i
PUT FILECSYSPRINT) PAGE;
OPEN FILE (NOS) SEQUENTIAL INPUT;
ON ENDFlLE(NOS) GO TO FINISH;
NEXTIN: READ FILE(NOS) INTO(IOFIELD) K~~TO(NEWNO);
IF UNSPEC(BYTE1)=(8)'l'B THEN GO TO NEXTIN;
ELSE PUT FILE(SYSPRINT) SKIP EDIT(NEWNO,IOFIELD)(A(5),A);
GO TO NEXTIN;
FINISH: CLOSE FILE(NOS);
END ACR1;
/*

//GO.NOS DD DSNAME=NOS,DISP=(OLD,KEEP),trnIT=2311,VOLUME=SER=D186
//GO.SYSIN DO *
NEWMAN,M.W.
516450
GOODFELLOW,D.T.
889
233
MILES,R.
aARVEy,C.D.W.
209
183
BARTLETT,S.G.
336
CORY,G.
001
READ,K.M.
PITT,W.H.
515
114
ROLF,D.F.
ELLIOTT,D.
472875
HASTINGS,G.M.
391
BRAMLEY,O.H.
439248

C
A
D
A
A
D
A
D
C
D
C

/*

Figure 11-22.

Accessing a REGIONAL(1) Data Set

the book are concatenated in a single
character string, and the lengths of the
two parts of the string are written as part
of the record. CONTROLLED storage is used
for the structure in which the records are
built because varying-length strings are
'not penni tted by the PL/I (F) compiler in
structures that are referred to in
record-oriented transmission statements.
146

The average record
key) is assumed to
the average number
(i.e., per region)
40 regions.

(including the recorded
be 60 bytes; therefore
of records per track
is 25, and there will be

In Figure 11-26, the data set STOCK3 is
created sequentially; duplicate region

/ /JOll1?GEX JOB
/ / COLE1~X EXEC PL1LFCLG, PARM. PL1L=' 81 ZE= 99 9 99 9' • PARM. LKED=" LIST'
//PL1L~SYSIN DD *
CRR2:
PROC OPTIONS(MAIN);
DCL (LOANS,STOCK) FILE RECORD KEYED ENV(REGIONAL(2»,
NUMBER CHAR(4),
1 BOOK,
2 AUTHOR CHAR(2S),
2 TITLE CHAR(SO),
2 QTY FIXED DEC(3),
INTER FIXED DEC(S),
REGION CHAR (8):
ON ENDFILE(SYSIN) GO TO FINISH;
OPEN FILECLOANS) DIRECT OUTPUT:
CLOSE FILE(LOANS);
OPEN FILE(STOCK) DIRECT OUTPUT;
NEXT:
GET FILE(SYSIN) LIST(NUMBER,BOOK);
INTER=(NUMBER-l000)/9;
REGION=INTER;
WRITE FILE(STOCK) FROM (BOOK) KEYFROM(NUMBERIIREGION):
GO TO NEXT:
FINISH: CLOSE FILE(STOCK);
END CRR2;
/*

//GO.LOANS DD UNIT=2311,SPACE=(19,100),DCB=(RECFM=F,BLKSIZE=12,
,
DSORG=DA,KEYLEN=7),DISP=(NEW,KEEP,DELETE),DSNAME=LOANS2,
//
VOLUME=SER=D186
'
//
/ /GO. S,]~OCK DD UNIT=2311,SPACE=(81,(100,20»,DCB=(RECFM=F,BLKSIZE=77, ,
//
//

DSORG=DA,KEYLEN=4),DISP=(NEW,KEEP,DELETE),DSNAME=STOCK~,

VOLUME=SER=D186

//GO.SYSIN DD *
'1015' 'W.H.AINSWORTH' 'THE ADMIRABLE CRICHTON' 1
'1214' 'L.CARROLL' 'THE HUNTING OF THE SNARK' 1
'3079' 'G.FLAUBERT' 'MADAME BOVARY' 1
, 3083' 'V. M. HUGO' 'LES MISERABLES'
2
'3085' 'J.K.JEROME' 'THREE MEN IN A BOAT'
2
'4295' 'W.LANGLAND' 'THE BOOK CONCERNING PIERS THE PLOWMAN' 1
'5998' 'W.SHAKESPEARE' 'MUCH ADO ABOUT NOTHING' 3
'6591' 'F.RABELAIS· 'THE HEROIC DEEDS OF GARGANTUA AND PANTAGRUEL'
'8362' 'H.D.THOREAU' 'WALDEN, OR LIFE IN THE WOODS' 1
'9765' 'H.G.WELLS' 'THE TIME MACHINE'
3

i

1

/*

Figure 11-23.

creating a REGIONAL(2) Data Set

numbers are acceptable since each region
can contain more than one record.
In E'igure 11-21 ,the region number for
the dat,a set LOANS3 is obtained simply by
testin9 the reader number: there are only
three l:,'egions, since a 2311 track can hold
36 ninE~teen-byte records.

The only notable difference between
Figure 11-28 and the corresponding
REGIONAL (2) figure is in the additonal
processing required for the analysis of the
records read from the data set STOCK3. The
records are read into a varying-length
character string and a based structure is
overlaid on the string so that the data in
the record can be extracted.

r

Chapter 11: Record-Oriented Transmission

147

//J043PGEl JOB
//COLEEX EXEC PL1LFCLG,PARM.PL1L='SIZE=99999',PARM.LKED='LIST'
//PL1L.SYSIN DD
DUR2:
PROC OPTIONSCMAIN):
DCL 1 RECORD,2CISSUE,REMINDER) CHAR(6),
SYSIN FILE RECORD INPUT SEQUENTIAL,
LOANS FILE RECORD UPDATE DIRECT KEYED ENVCREGIONAL(2»,
CARD CHAR(80),
BOOK CHAR C4) DEF CARD,
READER CHAR(3) DEF CARD POS(10),
CODE CHAR(1) DEF CARD POS(20),
REGION CHAR(8) DEF CARD POS(5);
ON ENDFILECSYSIN) GO TO FINISH;
OPEN FILECSYSIN),FILE(LOANS);
ISSUE,REMINDER=DATE;
READ FILE(SYSIN) INTOCCARD);
NEXT:
IF CODE='I' THEN WRITE FILE (LOANS) FROMCRECORD)
KEYFROM(READERIIBOOKIIREGION)1
ELSE IF CODE='R' THEN DELETE FILE(LOANS)
KEY(READERIIBOOKIIREGION);
ELSE IF CODE='A' THEN REWRITE FILE(LOANS) FROM(RECORD)
KEY (READER I I BOOK I I REGION) :
ELSE PUT FILE(SYSPRINT) SKIP LIST
('INVALID CODE:' ,BOOK, READER) ,
GO TO NEXT:
FINISH: CLOSE FILE(SYSIN),FILE(LOANS):
END DUR2;

*

/*

//GO.LOANS DO DSNAME=LOANS2,DISP=(OLD,KEEP),UNIT=2311,VOLUME=SER=D186
//GO.SYSIN DO *
3517
095
X
5999
003
A
3083
091
R
1214
049
I
/*

Figure 11-24.

148

REGIONAL(2) Data Sets: Direct Update

/ /J0431?GE3 JOB
//COLEI~X EXEC PL1LFCLG,PARM.PL1L=' SIZE=999999 '"PARM. LKED= 'LIST'
//PL1L.SYSIN DD *
SU~2:
PROC OPTIONS(MAIN);
DCL LOANS FILE RECORD SEQUENTIAL UPDATE KEYED ENV(REGIONAL(2»,
STOCK FILE RECORD DIRECT INPUT KEYED ENV(REGIONALC2»,
(TODAY,LASMTH) CHAR(6),
YEAR PIC '99' DEF LASMTH,
MONTH PIC '99' DEF LASMTH POS(3),
1 RECORD,2(ISSUE,REMINDER) CHAR(6),
LOANKEY CHAR(7),
READER CHAR(3) DEF LOANKEY,
BKNO CHAR(4) DEFLOANKEY POS(4),
INTER FIXED DEC(S),
REGION CHAR(8),
1 BOOK,
2 AUTHOR CHAR(2S),
2 TITLE CHAR(SO),
2 QTY FIXED DEC(3);
TODAY,LASMTH=DATE;
IF MONTH='Ol' THEN DO;
MONTH= '12' ;
YEAR=YEAR-1;
END;
ELSE MONTH=MONTH-1;
OPEN FILE(LOANS),FILE(STOCK);
ON ENDFILE(LOANS) GO TO FINISH;
NEXT:
READ FILE(LOANS) INTO (RECORD) KEYTO(LOANKEY);
IF REMINDER: 256)

Member
Entry A

Member
Entry N

Member
Entry B

'--V.~~~------------------------~
V r--------------------~~

2~

2

Figure 12-2.
8

3

A Partitioned Data set Directory Block
62(max}

1

Bytes

r-------·-T---T~-------------------------------------------------------------,

I Membel: I TTR I C I
Optional user data
I
IL_______
name ._iI ___ i_i
I I ______________________________________________________________ JI
A

A

I

IL- _______________________________________ ,

I
I

I
I

Pointer to start of
member:
TT - track number relative
to start of data set
R

- relative block number
on track

Figure 12-3.

Bit
---0

If set to 1, name is an alias

1,2

Number of pointers in user data field

3-7

Binary value indicating number of halfwords
of user data (including pointers)

Contents of Directory Entry

For E!xample, the DD statement:
//PDS DD UNIT=2311,VOLUME=SER=3412,
//
DSNAME=ALIB,
//
SPACE=(CYL,(50,,10}},
//
DISP=(,CATLG}
requests the job scheduler to allocate 50
cylindel:s of the 2311 disk pack with serial
number 3412 for a new partitioned data set
named ALIB, and to enter this ·name in the
system catalog. The last term of the SPACE
parametE~r requests that part of the space
allocated to the data set be reserved for
ten dirE~ctory blocks; it is the presence of
this term that indicates to the job
scheduler that the request is for a
partitioned data set:l...
If you want to insert the first member
in the data set at the time you create it,
you must. include the DD statement in the
job step that writes the member, and the
DSNAME parameter must include the member
1The SP1\CE parameter in a DD statement that
defines an INDEXED data set can include a
term in this position to indicate the size
of the index, but the DD statement must
also include ·the DCB subparameter DSORG=IS.

name in parentheses. For example,
DSNAME=ALIBCMEM1} names the member MEMl in
the data set ALIB. If the member is placed
in the data set by the linkage editor, you
can use the linkage-editor NAME statement
or the compiler OBJNM option instead of
including the member name in the DSNAME
parameter.

SPACE PARAMETER
The SPACE parameter in a DD statement that
defines a new partitioned data set must
always be of the form SPACE=(units,
(quantity,increment,directory}). Although
you can omit the third term (increment),
indicating its absence by a comma, the last
term, which specifies the number of
directory blocks to be allocated, must
always be present.
The amount of space required for a
partitioned data set depends on the number
and sizes of the members to be stored in it
and on how often members will be added or
replaced.
(Space occupied by deleted
members is not released.) The number of
directory blocks required depends on the
Chapter 12: Libraries of Data

S~S

157

number of members and the number of
aliases. Although you can specify an
incremental quantity in the SPACE parameter
that will allow the operating SystE:mt to
obtain more space for the data set if
necessary, both at the time of creation and
when new members are added, the number of
directory blocks is fixed at the time of
creation and cannot be increased.
If the data set is likely to be large or
you expect to do a lot of updating, i t
might be best to allocate a full volume.
Otherwise, make your estimate as accurate
as possible to avoid wasting space or time
recreating the data set.
The number of entries that a 2S6-byte
directory block can contain depends on ·the
amount of user data included in the
entries. The maximum length of an entry is
74 bytes, but the entries produced by the
linkage editor vary in length between 34
bytes and 52 bytes, which is equivalent to
between four and seven entries per block.

Processing a Member
When proqramming in PL/I, you will
ordinarily use partitioned data sets only
for storing source, object, or load
modules, and the modules themselves will be
created by the compiler or the linkage
editor. You need only include an
appropriately named DD statement to
indicate the names of the partitioned data
set and the new member.
(Note that: you
should restrict the use of a particular
library to the storage of one type of
module, since all members of a partitioned
data set must have identical
characteristics.)

Figure 12-4 illustrates the use of the
cataloged procedure PL1LFC to compile a
simple PL/I program and place the object
module in a new library named EXLIB. The
DD statement that defines the new library
and names the object module overrides the
DO statement SYSLIN in the cataloged
procedure.
(The PL/I program is a function
procedure that, given two values in the
form of the character string produced by
the TIME built-in function, returns the
difference in milliseconds.)
Figure 12-5 illustrates ·the use of the
cataloged procedure PL1LFCL to compile and
link-edit a PL/I program and place the load
module in the existing library 'FLM'.
(The
PL/I program lists the names of the membel~s
of a library.)
You can delete a member of a parti tionE~d
data set by means of the SCRATCH statement:
of the operating system utility program
IEHPROGM, which is described in IBM
System/360 Operatinq.Sytem: UtilItItes.
The SCRATCH statement deletes only the
directory entry that refers to the member;
you cannot free the space occupied by the
member unless you reorganize the entire
data set. Do not attempt to delete a
member by including the parameter
DISP= (OLD, DELETE) in the DD statement that~
defines it; this would result in the
deletion of the entire data set.
TO reorganize a partitioned data set,
you must copy the members into a temporarlr
partitioned data set, delete and recreate
the original data set, and copy the members
back into it. The system utility programs
include facilities for copying members of
partitioned data sets.

//JOS7PGEX JOB
//CO EXEC PL1LFC,PARM.PL1L='SIZE=999999'
//PL1L.SYSLIN DO UNIT=2311,VOLUME=SER=D186,DSNAME=EXLIB(ELAPSE),
//
SPACE=(CYL,(10,,2»,OISP=(NEW,KEEP)
//PL1L.SYSIN DO *
ELAPSE: PROC(TIME1,TIME2);
DCL (TIME1,TIME2) CHAR(9),
Hi PIC '99' OEF TIME1,
Ml PIC '99' DEF TIMEl POS(3),
MSl PIC '99999' DEF TIME1 PoseS),
H2 PIC '99' DEF TIME2,
M2 PIC '99' DEF TIME2 POS(3),
MS2 PIC '99999' DEF TIME2 POses),
ETIME FIXED DEC(7);
IF H2

LENGTH=(11",1~)

ENTRY POINT IHESRTA
Entry point IHESRTA is used for sorting
records from one data set to another. The
format of the CALL statement is:
CALL, IHESRTA (argument3., ,argument 2

,

argumenta,argument~):

where:
argument3.,

a character-string expression
representing the SORT
statement.

argument 2

a character-string expression
representing the RECORD
statement.

argument a

argument~

an arithmetic expression that
on evaluation g1ves a
fixed-point binary integer of
precision (31,0) specifying
the amount of main storage
available to the sort
program.
a fixed-point binary integer
variable of precision greater
than 15, that will contain
the value of the return code
returned by the sort program:
o sort successful, 16 sort
unsuccessful.

IHESR'rA must be declared as an entry
name with the appro~riate parameters.
The value of the character-string
expression for the SORT and RECORD
statemen't has the form:

The blanks at the beginning and the end of
the expression are always required. An
embedded blank must occur between SORT and
FIELDS, and between RECORD and TYPE: no
other embedded blanks are permitted.

When character-string constants are used
that are too long for one record of the.
PL/I source program, they are continued in
the following record.
You must take care
that embedded blanks are not inadvertently
inserted at the beginning and end of such
records: the ·value of the SORMGIN parameter
must be taken into conF-ideration.

A PLVI program that uses IHESRTA
requires both the SORTIN and SORTOUT DO
statement, as well as any others that are
necessary.

An example of such a program is given in
Figure 14-4. This program sorts 80-byte
records into an ascending sequence
according to the alphanumeric data
contained in two control fields.
The major
control field is in bytes 75 to 80: the
minor control field is in bytes 16 to 21.
The input records are obtained from the
input stream. The sorted records are
written onto a new temporary data set from
which they are retrieved and printed by the
PL/I program in job steps STEP3 and STEP4.
Included in the output for this job are
sort program diagnostic messages. These
messages include the number of records that
are in the input data set, and the number
of records transmitted to the output data
set. These numbers should be identical.

'bstatementb'

Chapter 14: Other Facilities of the Operating System

189

//R20A JOB
//STEPl EXEC PL1LFCL
//PL1L.SYSIN DD *
/* PL/I PROGRAMMING EXAMPLE USING IHESRTA */
SORTA:

PROC OPTIONS(MAIN):
/* ESTABLISH ENTRY POINTS TO THE SORT PROGRAM */
DCL IHESRTA ENTRY(CHAR(3S),CHAR(27),FIXED BIN(31,0),
FIXED BIN(31,0»,
RETURN_CODE FIXED BIN(31,0):

/* INVOKE THE SORT PROGRAM */
CALL IHESRTA (' SORT FIELDS=(75,6,CH,A,16,6,CH,A) .,
, RECORD TYPE=F, I..ENGTH= ( 80) ",
25000, /*MAIN STORAGE FOR SORT PROGRAM */
RETURN_CODE) ;
/* TEST RETURN CODE */
IF RETURN_CODE = 16 THEN PUT SKIP EDIT ('SORT FAILED') (A);
ELSE IF RETURN_CODE = 0 THEN PUT SKIP EDIT ('SORT COMPLETE')
(A) ;

ELSE PUT SKIP EDIT ('INVALID SORT RETURN CODE.
RETURN_CODE) (A);
END SORTA;

CODE=',

/*

//STEP2 EXEC PGM=*.STEP1.LKED.SYSLMOD
//SYSOUT DD SYSOUT=A
//SYSPRINT DD SYSOUT=A
//SORTLIB DD DISP=SHR,DSN=SYS1.S0RTLIB
//SORTWK01 DD UNIT=2314,SPACE=(TRK,(60 w20)"CONTIG)
/ /SORTWKO 2 DD UNIT=2314, SPACE= (TRK. (60 1,20) "CONTIG)
//SORTWK03 DD UNIT=2314,SPACE=(TRK, (60 1,20) "CONTIG)
//SORTWK04 DD UNIT=2314,SPACE=(TRK,(60,20)"CONTIG)
//SORTWK05 DD UNIT=2314,SPACE=(TRK,(60,20)"CONTIG)
//SORTWK06 DD UNIT=2314,SPACE=(TRK,{60,20)"CONTIG)
//SORTOUT DD DSNAME=&&TEM,DISP=(NEW,PASS),
// SPACE=(TRK,(1,1»,UNIT=2314,DCB=(RECFM=F,LRECL=80,BLKSIZE=80)
//SORTIN DD *
AAAAAA

AAAAAA

ZZZZZZ
444444
CCCCCC
XXXXXX
CCCCCC
CCCCCC
CCCCCC
CCCCCC
333333

ZZZZZZ
444444
ZZZZZZ
999999
888888

VVVVVV

EEEEEE
333333
/*

//STEP3 EXEC PL1LFCL
/ /PL1L.DUMP DD DSNAME=&&GOSET(GO) ,DISp:= (OLD, DELETE)
//PL1L.SYSIN DD *
/* PL/I ROUTINE TO PRINT OUTPUT FROM SORT PROGRAM EXAMPLES */
P: PROC OPTIONS(MAIN);
DCL SORTOUT FILE INPUr RECORD,
CHARS CHAR (80) VAR;
ON ENDFILE(SORTOUT) GOTO ENDP;
L: READ FILE (SORTOUT) INTO (CHARS);
PUT SKIP EDIT (CHARS) (A)i
GOTO L;

190

AAAAAA

ZZZZZZ
ZZZZZZ
ZZZZZZ
AAAAAA
AAAAAA

ZZZZZZ

ENDP: END P;
/*

//STEP4 EXEC PGM=*.STEP3.LKED.SYSLMOD
//SYSPRINT DO SYSOUT=A
//SORTOU'J~ DO DSNAME=&&TEM, DISP= (OLD, DELETE) If UNIT=2314
Figure

1l1~-4..

PL/I Program Invoking IHESRTA

ENTRY POINT IHESRTB

Return Codes fromPL/I to sort

Entry point IHESRTB is used for sorting
records constructed or updated in a PL/I
procedure! and placing the sorted records in
a data se!t. The format of the CALL
statement is:

In addition to the return code supplied by
the sort program to the PL/I program, the
PL/I program must pass a return code to the
sort program to indicate whether there are
any more records to be passed for sorting.
This return code is set by one of the
following statements:

CALL IHESRTB(argument:l., argument 2 ,argument 3

"

argument~,arguments);

where:
argumen"ts:l. arguments

CALL IHESARC(n);
CALL IHETSAC(n);
~

(single-task programs)
(multitasking programs)

as for IHESRTA
entry name of the PL/I
procedure supplying the
records to the sort
program.

The PL.lI records are passed to an entry
point in the sort program called a user
exit E15.
(A user exit is a point in the
executable code of the sort program at
which control can be received from or
passed to a user program.)
A PL/I procedure invoked from user exit
E15 uses .a RETURN statement to pass to the
sort program a character-string
representation of the record to be sorted.
If the record is not in character-string
form, it lMust be defined on a character
string and then passed. This may lead to
difficulties in the PL/I program. The
language :rules specify that the attributes
of the defined and the base items must
match exacctly except for their lengths, and
that string overlay defining on an
aggregate parameter is not permitted. The
implementation of the PL/I (F) compiler
permits the use of differing attributes and
of this type of overlay defining, and
produces E:!rror (E) diagnostics when these
situations occur. successful link-editing
and execu1:ion are possible, provided the
condition codes in the appropriate EXEC
statements allow the step conce'rned to be
executed.

where n has the values:
8
12

No more records will be passed
Sort the next record to be passed

If the CALL IHETSAC(n) statement is to
be used, the TASK option must be specified
in the· main PROCEDURE statement.
IHESARC or IHETSAC must be declared as
an entry of precision (31,0), for example:
DCL IHESARC ENTRY(FIXED BINARY(31,0»;

Example
An example of a PL/I program that uses
IHESRTB is given in Figure 14-5. This
program sorts records similar to those in
the example in Figure 14-4. The PL/I
procedure E15A is invoked from the sort
program user exit E15. This procedure
returns a character string that is inserted
by the sort program into the sort. The
sorted records are transmitted by the sort
program to a temporary data set defined by
the DO statement SORTOUT, from which they
are retrieved and printed by the PL/I
program in job steps STEP3 and STEP4.

Chapter 14: Other Facilities of the Operating System

191

//R20B JOB
//STEP1 EXEC PL1LFCL
//PL1L.SYSIN DD *
/* PL/I PROGRAMMING EXAMPLE USING IHESRTB */
SORTB: PROC OPTIONS (MAIN);
/* DECLARE SORT PROGRAM ENTRY AND EXIT POINTS */
DeL IHESRTB ENTRY(CHAR(35),CHAR(27),FIXED(31,0),
FIXED BIN(31,0),ENTRY),
IHESARC ENTRY(FIXED BIN(31,0»,
E15A ENTRY RETURNS(CHAR(80»,
RETURN_CODE FIXED BIN(31,O);
/* INVOKE THE SORT PROGRAM */
CALL IHESRTB (. SORT FIELDS:= (75,6 ,CH,A, 16, 6,CH,A) .,
, RECORD TYPE=F,LENGTH=(SO) "
\
25000, /* MAIN STORAGE FOR SORT PROGRAM */
RETURN_CODE,E15A):
/* TEST RETURN CODE */
IF RETURN CODE = 16 THEN PUT SKIP EDIT (' SORT FAILED") (A) :
ELSE IF RETURN CODE = 0 THEN PUT SKIP EDIT ('SORT COMPLETE') (A):
ELSE PUT SKIP EDIT ('INVALID SORT RETURN CODE.
CODE=',
RETURN_CODE) (A);
E15A:

/* THIS PROCEDURE OBTAINS RECORDS FROM THE INPUT STREAM
/* AND CHECKS FOR NUMERIC OR ALPHABETIC CODES BEFORE
/* PASSING ONLY THOSE WITH ALPHABETIC CODES TO THE SORT
/* PROGRAM. RECORDS WITH NUMERIC CODES ARE LISTED.
PROC RETURNS(CHAR(SO»;
DCL SYSIN FILE RECORD INPUT;
ON ENDFILE(SYSIN) BEGIN;
PUT SKIP(3) EDIT ('END OF SORT PROGRAM INPUT') (A);
CALL lHESARC(S); /* SIGNAL END OF SORT INPUT */
GOTO ENDE15:
END:
DCL INFIELD CHAR(SO), FIELDl CHAR(6) DEF INFIELD
POS(75):
NEXT: READ FILE (SYSIN) INTO (INFIELD);
IF FIELDl > 'ZZZZZZ' THEN DO;
PUT SKIP EDIT (INFIELD) (A);
GOTO NEXT:
END;
CALL IHESARC(12); /* INPUT TO SORT CONTINUES */
RETURN (INFIELD);
ENDE15: END E15A:

END SORTB;
/*

//STEP2 EXEC PGM=*.STEP1.LKED.SYSLMOD
//SYSOUT DD SYSOUT=A
//SORTOUT DD DSNAME=&&TEM,DISP=(NEW,PASS),
// SPACE=(TRK,(1,1»,UNIT=2314,DCB=(RECFM=F,LRECL=SO,BLKSIZE=SO)
//SYSPRINT DO SYSOUT=A
//SORTLIB DD DISP=SHR,DSN=SYS1.S0RTLIB
//SORTWKOl DD UNIT=2314, SPACE= (TRK, (60,20)"CONTIG)
//SORTWK02 DO UNIT=2314,SPACE=(TRK,(60,20)"CONTIG)
//SORTWK03 DO UNIT=2314,SPACE=(TRK, (60,20) "CONTIG)
//SORTWK04 DD UNIT=2314,SPACE=(TRK,(60,20)"CONTIG)
//SORTWK05 DO UNIT=2314,SPACE=(TRK, (60,20) "CONTIG)
//SORTWK06 DD UNIT=2314,SPACE=(TRK,(60,20)"CONTIG)
//SYSIN DO *
192

*/
*/
*/
*/

AAAAAA

AAAAAA

ZZZZZZ
444444
CCCCCC
XXXXXX
CCCCCC
CCCCCC
CCCCCC
CCCCCC
CCCCCC
333333

ZZZZZZ
444444
ZZZZZZ
999999

ZZZZZP
888888
AAAAAA

ZZZZZZ
ZZZZZA
ZZZZZZ

VVVVVV

AAAAAA
AAAAAA

EEEEEE
333333

ZZZZZZ

/*

//STEP3 EXEC PL1LFCL
//PL1L.,DUMB DD DSNAME=ggGOSET(GO) ,DISP= (OLD, DELETE)
/ /PL1L., SYSIN DD *
/* PI~I ROUTINE TO PRINT OUTPUT FROM SORT PROGRAM EXAMPLES */
P: PROC OPI'IONS(MAIN) 1
DCL SORTOUT FILE INPUT RECORD,
CHARS CHAR (80) VAR,
ON ENDFILE(SORTOUT) GOTO ENDP;
L: READ FILE(SORTOUT) INTO (CHARS);
PUT SKIP EDIT (CHARS) (A);
GOTO L;

ENDP: END P,
/*

/ /STEPL!~ EXEC PGM= *. STEP3 • LKED. SYSLMOD
//SYSPJITNT DD SYSOUT=A
//SORTOUT DD DSNAME=ggTEM,DISP=(OLD,DELETE),UNIT=2314
Figure 14-5.

PL/I Pregram Inveking IHESRTB

ENTRY l'OI NT IHESRTC

difficulties can be expected here as for
IHESRTB.

Entry point IHESRTC is used fer serting
records frem a data set and then passing
them ene-by-one te a PL/I precedure. The
fermat .of the CALL statement is:
CALL IIIESRTC(argument:l,.,argument 2 ,argument 3
argument~,argument6);

where:
argullllents:l,. - ...
argull(\ent 6

Return Codes frem PL/I te Sert
,

A return cede may be passed by the PL/I
precedure te the sort pregram, using the
CALL IHESARC(n) or CALL IHETSAC(n)
statement. The return cede'values are:

as for IHESRTA
= entry name .of the PL/I
procedure te which the
sorted records are to be
passed.

when IHESRTC is used, each record that
appearfJ in the sorted .output is passed te
user elcit E35. The PL/I procedure
associated with this user exit is invoked
fer each record that it receives as a
paramet:er ..
The records passed by the sert pregram
must bE~ in a character-string form. If
this form is net the .one required by the
PL/I pl:ogram, then the PL/I record must be
defined en a character string. The same

4

the record passed has been accepted,
pass the next record

8

stop passing recerds, even if there
are still mere te ceme.

IHESARC and IHETSAC must be declared as an
entry of precision (31,0).
If ne return code is passed the sert
pre gram continues te pass records until all
have been passed.
An example .of a PL/I pregram that uses
IHESRTC is given in Figure 14-6. This
program sorts recerds similar te these in
the previous examples. The PL/I procedure
E35A is inveked from the sert program user

Chapter 14: Other Facilities .of the Operating System

193

//R20C JOB
//STEP1 EXEC PL1LFCL
//PL1L.SYSIN DD *
/* PL/I PROGRAMMING EXAMPLE USING IH:ESRTC */
SORTC:

PROC OPTIONS (MAIN);

/* DECLARE SORT PROGRAM ENTRY AND EXIT POINTS */
DeL lHESRTC ENTRY(CHAR(35),CHAR(27),FIXED BIN(31,0),
FIXED BIN(31,0),ENTRY),
IHESARC ENTRY(FIXED BIN(31..,0»,
E35A ENTRY,
RETURN_CODE FIXED BIN(31,O);
/* INVOKE THE SORT PROGRAM */
CALL IHESRTC (' SORT FIELDS=(75,6,CH,A,16,6,CH,A) "
, RECORD TYPE=F,LENGTH=(SO) "
25000, /* MAIN STORAGE FOR SORT PROGRAM */
RETURN_CODE, E35A)i
/* TEST RETURN CODE */
IF RETURN CODE = 16 THEN PUT SKIP EDIT ('SORT FAILED')(A);
ELSE IF RETURN_CODE = 0 THEN PUT SKIP EDIT ('SORT COMPLETE') ( A)i
ESLE PUT SKIP EDIT ('INVALID SORT RETURN CODE.CODE=',
RETURN_CODE) (A) ;

E35A:

/* THIS PROCEDURE OBTAINS SORTED RECORDS FROM THE
/* SORT PROGRAM AND LISTS THEM. DUPLICATE RECORDS
/* ARE IGNORED.

*/
*/

PROC (INREC)i
/* PRINT HEADING FOR SORTED OUTPUT ON SYSPRINT */
DCL I STATIC INIT(O)i
IF I = 0 THEN DO;
PUT SKIP EDIT (' OUTPUT FROM E35 SUBROUTINE') (A) ;
1=1;
END~

/* PROCESS SORTED RECORDS */
DCL INREC CHAR(SO),
PREVREC CHAR(SO) STATIC INIT(' I ) ;
IF INREC=PREVREC THEN GOTO NEXT; /* IGNORE THIS RECORD */
ELSE DO;
PREVREC=INRECi /* STORE CURRENT RECORD */
PUT SKIP EDIT (INREC) (A);
END;
NEXT: CALL IHESARC(4); /* REQUEST NEXT RECORD FROM SORT */
END E35A;
END SORTCi
/*

//STEP2 EXEC PGM=*.STEP1.LKED.SYSLMOD
//SYSOUT DD SYSOUT=A
//SYSPRINT DD SYSOUT=A
//SORTLIB DD DISP=SHR,DSN=SYS1.S0RTLIB
//SORTWK01 DD UNIT=2314 f SPACE=(TRK,(60,20)"CONTIG)
//SORTWK02 DD UNIT=2314,SPACE=(TRK,(60,20)"CONTIG)
//SORTWK03 DD UNIT=2314 f SPACE=(TRK,(60,20)"CONTIG)
//SORTWK04 DD UNIT=2314,SPACE=(TRK,(60,20)"CONTIG)
194

//SORT1WKOS DD UNIT=2314,SPACE=(TRIS, (60,20) "CONTIG)
//SORT1NK06 DD UNIT=2314, SPACE= (TRK, (60,20) "CONTIG)
//SORTIN DD =Ie
AAAAAA

AAAAAA

ZZZZZZ
444444
CCCCCC
XXXXXX
CCCCCC
CCCCCC
CCCCCC
CCCCCC
CCCCCC
333333

ZZZZZZ
444444
ZZZZZZ
999999
ZZZZZZ
AAAAAA
AAAAAA

ZZZZZP
ZZZZZZ
ZZZZZZ
AAAAAA
AAAAAA

VVVVVV

EEEEEE
333333
Figure 14-6.

ZZZZZZ

PL/I Program Invoking IHESRTC

exit E3S. This procedure receives a
charact,er-string representing -a sorted
record from the sort program. The input to
the sort program is in the input stream.

arguments

arguments
ENTRY POINT IHESRTD
Entry point IHESRTD is used for sorting
records constructed or updated by a PL/I
function and then passing them one-by-one
to anot~her procedure. The format 'of the
CALL st~atement is:

CALL IHESRTD(argument 1 ,argument 2 ,argument 3

,

argument~,arguments,argument6);

where:
arguments1-~

= as for IHESRTA

= entry name of the PL/I
procedure supplying the
:r:,~cords to the sort program

= entry name of the PLII
procedure to which the
sorted records are to be
passed

An example of a PL/I program that uses
IHESRTD is given in Figure 14-7. This
program sorts records similar to those in
the previous examples. The PL/I procedure
ElSA is invoked from the sort program user
exit E1S. This procedure return a
character string that is inserted by the
sort program into the sort. At the end of
the sort, the sorted' records are associated
with a character string parameter in the
PL/I procedure E3SA, which is invoked from
the sort user exit E3S for each record
emerging from the sort.

Chapter 14: other Facilities of the operating System

195

//R20D JOB
//STEPl EXEC PL1LFCL
//PL1L.SYSIN DD *
/* PL/I PROGRAMMING EXAMPLE USING IHESRTD */
SORTD:

PROC OPTIONS (MAIN);

/* DECLARE SORT PROGRAM ENTRY AND EXIT POINTS */

DCL

IHESRTD ENTRY(CHAR(35),CHAR(27),FIXED BIN(31,0),
FIXED BIN(3l,0),ENTRY,ENTRY),
IHESARC ENTRY(FIXED BIN(3l,0»,
E15 ENTRY RETURNS(CHAR(SO»,
E35 ENTRY,
RETURN_CODE FIXED BIN(3l,0);

/* INVOKE THE SORT PROGRAM */

CALL IHESRTD C' SORT FIELD=(75,6,CH,A,16,6,CH,A) 0'
, RECORD TYPE=F,LENGTH=(SO) "
25000, /* MAIN STORAGE FOR SORT PROGRAM */
RETURN_CODE, E15A,E35A);
/* TEST RETURN CODE */

IF RETURN CODE = 16 THEN PUT SKIP EDIT ('SORT FAILED') (A);
ELSE IF RETURN CODE = 0 THEN PUT SKIP EDIT ('SORT COMPLETE') (A);
ELSE PUT SKIP EDIT C' INVA:LID SORT RETURN CODE. CODE=' ,
RETURN_CODE)CA);
E15A:

/* THIS PROCEDURE OBTAINS RECORDS FROM THE INPUT STREAM */
/* AND CHECKS FOR NUMERIC OR AI,PHABETIC CODES BEFORE
*/
/* PASSING ONLY THOSE WITH ALPHABETIC CODES TO THE SORT */
/* PROGRAM.
RECORDS WITH NUMERIC CODES ARE LISTED.
*/

PROC RETURNSCCHARCSO»;
DCL SYSIN FILE RECORD INPUT;
ON ENDFILE(SYSIN) BEGIN;
PUT SKIP(3) EDIT (':END OF SORT PROGRAM INPUT.',
'SORTED OUTPUT SHOULD FOLLOW')CA);
CALL IHESARC(S); /* SIGNAL END OF SORT INPUT */
GOTO ENDE15;
END;
DCL INFIELD CHAR(SO), FIELDl CHAR(6) DEF INFIELD
POS(75);
NEXT: READ FILE (SYSIN) INTO (INE'IELD);
IF FIELDl > 'ZZZZZZ' THEN DO;
PUT SKIP EDIT (INFIELD) (A);
GOTO NEXT;
END;
CALL IHESARC(12); /* INPUT TO SORT CONTINUES */
RETURN (INFIELD); .
ENDE15: END E15A;
E35A:
/* THIS PROCEDURE OBTAINS SORTED RECORDS FROM THE
*/
/* SORT PROGRAM AND LISTS THEM.
DUPLICATE RECORDS */
/* ARE IGNORED.
*/
PROC ( INREC) ;
/* PRINT HEADING FOR SORTED OUTPUT ON SYSPRINT */

DCL I STATIC INI'!' (0) ;
IF I = 0 THEN DO;
PUT SKIP EDIT ('OUTPUT FROM E35 SUBROUTINE') (A);
1=1;
END;
/* PROCESS SORTED RECORDS */

196

DCL INREC CHAR(80),
PREVREC CHAR(80) STATIC INIT(~ .);
IF INREC=PREVREC THEN GOTO NEXT; /* IGNORE THIS RECORD */
ELSE DO~
PREVREC=INRECi /* STORE CURRENT RECORD */
PUT SKIP EDIT (INREC) (A);
END;
NEXT: CALL IHESARC(4); /* REQUEST NEXT RECORD FROM SORT */
RETURN;
END E35A;
END SORTD;
/*

//STEP2 EXEC PGM=*.STEP1.LKED.SYSLMOD
//SYSot~ DD SYSOUT=A
//SYSPHINT DD SYSOUT=A
/ /SORT][JIB DO DISP=SHR, DSN=SYS1. SORTLIB
/ /SORTWK01 DO UNIT=2314, SPACE= (TRK, (60,20) "CONTIG)
/ /SORTl~02 DO UNIT=2314, SPACE= (TRK, (60,20) , ,CONTIG)
//SORTlil1K03 DD UNIT=2314,SPACE=(TRK, (60,20) "CONTIG)
//SORTl~04 DD UNIT=2314,SPACE=(TRK,(60,20)"CONTIG)
//SORTl~05 DD UNIT=2314,SPACE=(TRK,(60,20)"CONTIG)
//SORTl~06 DO UNIT=2314,SPACE=(TRK,(60,20)"CONTIG)
//SYSIN DD *

zzzzzz

AAAAAA

ZZZZZZ
444444
CCCCCC
XXXXXX
CCCCCC
CCCCCC
CCCCCC
CCCCCC
333333

ZZZZZZ
444444
ZZZZZZ
999999
ZZZZZZ
888888
AAAAAA

ZZZZZP
ZZZZZZ

VVVVVV

AAAAAA
AAAAAA

EEEEEE
333333

ZZZZZZ

/*

Figure 14-7.

PL/I Program Invoking IHESRTD

SORTING VARIABLE-LENGTH RECORDS

3.

Varying-length strings passed from a
PL/I user exit E15 procedure will have
the length field added to the record
automatically; the length will be the
current length of the character string
plus four bytes for the field itself.
The same applies if 'fixed-length
strings of different lengths are
returned from the E15 procedure.

4.

The four-byte length field is removed
from variable-length records passed to
a PL/I user exit E35 routine.

When you wish to use the PL/I sorting
facili 1:ies to sort variable-length records,
you should note the following points:
1.

2.

The portion of a variable-length
rE~cord that contains the control field
01: fields on which the sort is to be
pE~rf ormed must be present and of the
SClme length for every record to be
sorted. A sort cannot be performed on
control fields whose length or
position within a record is liable to
alter. Thus the control fields would
bE~ expected wi thin the minimum length
given for the records in the RECORD
control statement.
The length of each record is recorded
in the first four bytes of the record.
P1:ovision for this length field should
bE~ made when you specify the sort
control fields in the SORT control
s1:atement.

An example of a PL/I program that uses
IHESRTA to sqrt variable-length records is
given in Figure 14-8. This example
includes a PL/I program to create a data
set of variable-length records from data
items obtained from the input stream. The
sort is performed on alphanumeric data in
the first six bytes following the length
field in each record. A third PL/I program
retrieves the sorted variable-length
records from a temporary data set and lists
them. Note that the maximum record length
includes four bytes for the length field,

Chapter 14: Other Facilities of the Operating System

197

and corresponds to the maximum length given
in the LRECL subparameter.

OSE OF PL/I SORT IN A MULTITASKING
ENVIRONMENT
When the sort program is invoked from
different PL/I tasks, so that two Ol~ more
sorting operations are to be performed
asynchronously by separate subtasks, the
following should be noted if -the sort
program diagnostic messages are to be
printed on the line printer:

198

If the DD statement for the SYSOUT data
set contains SYSOUT=A in the operand field,
some sort program messages may be
overwritten in the data management buffers
and therefore not printed.
FUrther, the
program in some cases will terminate
abnormally or go into a wait state. These
problems are caused by the inability to
modify the ddname for the SYSOUT data set
in the additional tasks that use the sort
program: they give rise to synchronization
conflicts within data management.
This problem does not apply if, when thE!
system is generated, the sort program
messages are specified to be printed on the
console.

/ /R20V ,JOB
//STEPl EXEC PL1LFCLG
//PL1L.SYSIN DO *
VAR2::
PROC OPTIONS (MAIN) ;
ON ENDFILE(SYSIN) GOTO END;
DCL OUT FILE RECORD OUTPUT,
OUTREC CHAR (80) VAR;
NEXT: GET LIST (OUTREC);
PUT SKIP EDIT (OUTREC) (A);
WRITE FILE (OUT) FROM (OUTREC);
GOTO NEXT;
END: END VAR2;
/*
//GO.otn~ DD DSNAME=&&TEMP,DISP=(NEW,PASS),SPACE=(TRK,(l,l»,
//DCB=(,RECFM=V,LRECL=84),UNIT=2314
//GO.DIDIlB DO DSNAME=&&GOSET(GO) ,DISP=(OLD,DELETE)
//GO.SYSIN DO
'003329HOOKER S.W. RIVERDALE, SATCHWELL LANE, BACONSFIELD'
'002886ElOOKER R.R. ROTORUA, MILKEDGE LANE, TOBLEY'
'003077HOKKER & SON, LITTLETON NURSERIES, SHOLTSPAR'
'059334HOOK E.H. 109 ELMTREE ROAD, GANNET PARK, NORTHAMPTON'
'73872HOME TAVERN, WESTLEIGH'
'000931:E'OREST, IVER, BUCKS'

*

/*

//STEP2 EXEC PL1LFCL
//PL1L.SYSIN DD *
VARY1.: PROC OPTIONS(MAIN);
DCL IHESRTA ENTRY (CHAR(24),CHAR(3S),
FIXED BIN(31,0),FIXED BIN(31,0»,
RETURN CODE FIXED BIN(31,O);
CALL lHESRTA(' SORT FIELDS=(5,6,CH,A) ,
, RECORD TYPE=V,LENGTH=(84",20,40)
25000, /* MAIN STORAGE FOR THE SORT
RETURN CODE);
IF RETURN CODE=O THEN PUT SKIP EDIT
('SORT-COMPLETE') (A);
ELSE IF RETURN CODE=16 THEN
('SORT FAILED') (A);
ELSE PUT SKIP EDIT
('INVALID SORT RETURN
END VARY1;

"
PROGRAM */

PUT SKIP EDIT
CODE') (A);

/*

//STEP3 EXEC PGM=*.STEP2.LKED.SYSLMOD
/ /SYSOU'I' DD SYSOUT=A
//SYSPRINT DO SYSOUT=A
//SORTLIB DO DISP=SHR,DSN=SYS1.S0RTLIB
//SORTWl<:Ol DO UNIT=2314, SPACE= (TRK, (60,20) "CONTIG)
//SORTWK02 DO UNIT=2314, SPACE= (TRK, (60,20) "CONTIG)
//SORTWl<:03 DD UNIT=2314,SPACE=(TRK, (60,20) "CONTIG)
/ /SORTWK04 DO UNIT=2314, SPACE= (TRK, (60,20) "CONTIG)
//SORTWR05 DD UNIT=2314,SPACE=(TRK, (60,20) "CONTIG)
/ /SORTWK06 DD UNIT=2314, SPACE= (TRK, (60,20) "CONTIG)
//SORTINI DO DSNAME=&&TEMP,DISP=(OLD,DELETE),
//
DCB=: (BLKSI ZE= 8 8, LRECL= 84, RECFM=V)
//SORTOUT DO DSNAME=&&TEM,DISP=(NEW,PASS),
/ / SPACE:= (TRK, (1,1) ) , UNIT=2314, DCB= (RECFM=V, LRECL=84, BLKSI ZE=88)
//STEP4 EXEC PL1LFCL
//PL1L.DUMB DO DSNAME=&&GOSET(GO),DISP=(OLD,DELETE)
//PL1L.SYSIN DO *
/* PL/t ROUTINE TO PRINT OUTPUT FROM SORT PROGRAM EXAMPLES */
P:
PR:OC OPTIONS (MAIN) ;
DeL SORTOUT FILE INPUT RECORD,
CHARS CHAR (80) VAR;
ON ENDFILE(SORTOUT) GOTO ENDP;
L: READ FILE(SORTOUT) INTO (CHARS);
PUT SKIP EDIT (CHARS) (A);
GOTO L;

Chapter 14: Other Facilities of the operating System

199

ENDP: END Pi
/*

//STEP5 EXEC PGM=*.STEP4.LKED.SYSLMOD
//SYSPRINT DD SYSOUT=A
//SORTOUT DD DSNAME=&&TEM,DISP=(OLD,DELETE),UNIT=2314
Figure 14-8.

200

Using IHESRTA to Sort

Variable~length

Records

Chapter 15: PL/I and Other Languages

Introdu(~tion

This chapter is presented as two main
sections. The first is concerned with the
subject of data set interchange (i.e.,
sharing data sets between programs written
in diffE~rent languages); the second is
concernE~d with the more complex subject of
linkage (i.e., direct communication)
between modules written in different
languagE~s but forming one program.

output, and the elements will not be
aligned unless written in a particular
order.
3.

PL/I arrays are stored in row major
order, while FORTRAN arrays are stored
in column major order.

Equivalent Data Types

Data Se1: Interchange
In general, a PL/I program can use data
sets produced by programs written in other
languagE~s, and can produce data sets that
can be used by these other programs. There
are somE~ limitations, caused mainly by
differences in the way in which PL/I data
is handled, in particular the way in which
it is mapped and stored, and by the large
number of different data types available in
PL/I that are not available in the other
languagE~s.
However, there are many data
types and modes of storage in PL/I that
have equivalents in other high-level
languagE~s.
There are also ways in which
most of the incompatibilities can be
overcome. A previous incompatibility has
been removed in the fifth version of the
PL/I (F) compiler by the use of halfword
storage for data that is FIXED BINARY and
has a pI:ecision of less than 16.

Figure 15-1 shows FORTRAN-PL/I data
equivalents. Note that PL/I numeric
character data has no direct equivalent in
FORTRAN. However, it is possible to treat
a FORTRAN array as a PL/I character string.

Structures and Alignment
The safest course when PL/I structures are
to be associated with FORTRAN records is to
declare the structures UNALIGNED. However,
if the elements of the FORTRAN record have
been forced into correct alignment (using
techniques such as writing out the
variables that form the record in
descending order of data type length), the
PL/I structure can be declared ALIGNED.
Note that unaligned data is less efficient
than aligned data, often requiring extra
execution time when acc~ssed.
Example:

PL/I-FOHTRAN DATA SET INTERCHANGE
The major areas of incompatibility between
PL/I and FORTRAN are as follows:

FORTRAN
Main storage: INTEGER*2A
LOGICAL*lB
REAL*SC
Output:

1.

2.

WRITE(6) C,A,B

PL.lI has more data types; therefore
some PL/I data types have no
equivalent in FORTRAN, notably
character-string data.
PLlI records can be organized as
stl:uctures in main storage (with the
elE~ments aligned or unaligned).
FOHTRAN records are built up on

Main storage: DCL 1
2
2
2
Input:

R
U
S
T

UNALIGNED,
FLOAT(16),
FIXED BIN,
BIT(S);

READ FILE(FILE6) INTO(R);

Chapter 15: PL/I and Other Languages

201

r-------------------------------T--------------------------------------------------------,
I
PL/I
I

I FORTRAN (Unformatted Record)

~-----------T--------T------·----+----------------------T--------T-----------------------~
I
I
I
I
I
Alignment
,
, Data Type
Length I Alignment1I
Data Type
Length ~-----------------------1
I
I (bytes) I
I
I (bytes), Aligned
Unaligned I
~-----------+--------+----------+----------------------+--------+-----------------------~
I INTEGER*2 I
2
I
Byte
I FIXED BINARY(15)
I
2
'Halfword
Byte
I
I INTEGER*4 I
.4
I
Byte
I FIXED BINARY(31)
I
4
I Fullword
Byte
I
I REAL*4
I
4
I
Byte
I REAL FLOAT(short)
I
4
I Fullword
Byte
I
I REAL*S
I
S
I
Byte
I REAL FLOAT (long),
I
S
I Doubleword
Byte
I
S
I
Byte
I COMPLEX FLOAT(short) I
S
I Fullword
Byte
I
I COMPLEX*S I
I COMPLEX*16 I
16
I
Byte
I COMPLEX FLOAT(long) I
16
I Doubleword
Byte
I
I LOGICAL*l I
1
I
Byte
I BITCS)
,1
,Byte
Bit2
I
4
I
Byte
I BIT(32)
I
4
I Byte
Byte
I
I LOGICAL*4 I
,
I
,
I CHARACTER
I
any
I Byte
Byte
I
~-----------~--------~-.---------~----------------------~--------~-----------------------~
,Notes: 1When allocated, the data types generally have the same alignment as listed
I
,
under the PL/I equivalents, but after more than 'one data item has been written I
,
out in one record (equivalent to writing a PL/I structure), this alignment may I
I
be lost, and therefore all items should be considered to be byte-aligned for
I
input/output.
I
I
2The fact that the alignment requirement of unaligned bit strings is bit rather I
I
than byte does not affect PL/I-FORTRAN data interchange, since the FORTRAN
I
I
I
string will always ·take up an integral number of bytes.
I
L __________________________________________________________

I

I

I

-----------------------------J

Figure 15-1.

FORTRAN-PL/I Data Equivalents

In the above example, S, T, and U are
equivalent data types to A, B, and C
respectively. As alignment of the elements
has been forced in the FORTRAN WRITE
statement, R could have been declared
ALIGNED in this case.

Example:
FORTRAN
REAL A(2,5,7)
PL/I
DCL A(7,5,2)

The record format will be either VS or
VBS, since the FORTRAN object-time library
automatically uses a spanning technique.
. The record format specified in the PL/I
ENVIRONMENT attribute (or in the DD
statement associated with the PL/I file)
must match that specified in the DD
statement associated with the FORTRAN data
set reference number.

The disadvantage of this method as it
stands is that a reference to the array
using the same subscripts in the two
different programs will access different
elements. A(1,3.6) in FORTRAN would be
A(6,3,1) in PL/Ii the likelihood of program
error may be increased. This problem can
be avoided by using iSUB defining in the
PL/I program.
Example:
FORTRAN

Arrays
REAL A(2,5,7)
Arrays of one dimension are stored in the
same way in both PL/I and FORTRAN, but
arrays of two or more dimensions are stored
differently (row major order for PL/I,
column major order for FORTRAN). The
solution to this problem is to declare the
array in one language with subscripts in
reverse order to the declara·tion in the
other language. The record will then be
correctly associated with the array in
either program on transmission.
202

DeL Al(7,5,2),
A(2,5,7) DEF Al(3SUB,2SUB,lSUB);
Now, if the record is transmitted to or
from A1 in the PL/I program, a reference to
a particular element in the FORTRAN program
will be identical to the PL/I reference to
that element •..

Extern.al Representation of Floating-point
Numbers
The prlE~ceding discussions are concerned
with the internal representation of
equivalent data types in FORTRAN and PL/I,
and thlE~ interchange of record-oriented data
sets. The following notes describe an
incompatibili ty between PL/I and FORTRAN in
the ex'ternal representation of
floating-point numbers in stream-oriented
data slats.
1•

2.

Fc:)r PL/I, the exponent of any
floating-point number is indicated by
the character "E". For FORTRAN, the
exponent of a short-precision
floating-point number is indicated by
the character "E" and the exponent of
a long-precision floating-point number
is indicated by the character "0".
For PL/I, if the exponent of a
floating-point number is positive, it
may optionally have a "+" sign. If a
sign is not present, the exponent
immediately follows the character "E".
For example:
0.018737E22
or
0.018737E+22

For FORTRAN, if the exponent of a
floating-point number is positive, a blank
charact.er rather than a • +' sign may
sometimes be present between the "E" or "0"
and the exponent. For example:
0.0187370 22

start of the structure, and that the record
length may differ from that of the COBOL
record.

ANS COBOL data can be SYNCHRONIZED
(i.e •. ., aligned) or unsynchronized (i.e.,
unaligned). COBOL records prior to USASI
COBOL were always SYNCHRONIZED, and the
fifth version of the PL/I (F) compiler
assumes that structures in a file with the
COBOL option are SYNCHRONIZED. Note that
for ANS COBOL the default is
unsynchronized, while for PL/I the default
is aligned for all data types except
bit-string, character-string, and numeric
character.

You can use the COBOL option in the
ENVIRONMENT attribute for a PL/I file that
is to be associated with a COBOL data set.
This indicates that any structure in the
data set associated with this file is
mapped according to the COBOL algorithm
(i.e., starting at a doubleword boundary
and, proceeding left to right, aligning
elements on the first available correct
boundary).
If a structure name appears in
a READ INTO or WRITE FROM statement for a
fil~ with the COBOL option, a temporary
COBOL-type structure for transmission to or
from the data set is created. Before
output (or after input), the elements of
the PL/I-mapped structure are assigned to
(or from) the temporary.
If the PL/I
structure and the COBOL record have
identical mapping, the data sets will be
directly compatible and there will .be no
need to use the COBOL option. Note that
the following restrictions apply to files
with the ENVIRONMENTCCOBOL) attribute.

These differences prevent the direct use of
PL/I sitream-oriented transmission
facili·ties to read or write floating-point
numbers that can be interchanged with a
FORTRAN program.

1.

The file can be used only for READ
INTO, WRITE FROM, and REWRITE FROM
statements. The file name cannot be
passed as an argument.

PL/I-COBOL DATA SET INTERCHANGE

2.

The variable named in the INTO option
cannot be used in the on-unit for an
ON-condition raised during execution
of a READ statement.

3.

The EVENT option can be used only if
the compiler can determine that the
PL/I structure and the COBOL record
have identical mapping.
(For further
details see the PL/I CF) Language
Reference Manual.)

PL/I has data types and organizations that
correspond to most COBOL iteins, but there
are some differences. For example, PL/I
data may be either aligned or unaligned,
but records produced by a program compiled
by a non-ANS COBOL compiler are always
aligned (for ANS COBOL, see below). Also,
PL/I s·tructure mapping differs from COBOL
record mapping in that the PL/I (F)
cqmpil1er minimizes the amount of unused
storag,e within the structure. This means
that corresponding elements may occupy
differ,ent storage locations .relative to the

Figure 15-2 shows COBOL-PL/I data
equivalents.
Chapter 15: PL/I and other Languages

203

Linkage with Other Languages

familiar with
interlanguage
discussion of
and suggested

The information so far presented in this
chapter has dealt with data set interchange
between PL/I and non-PL/I modules run as
separate jobs or job steps laddress
of parameterJI
L ____________________

IHETSAP
parameter from EXEC statement.

I
I

IHETSAA
normal parameter conventions.

V

r---T----------------,
1 1 11
byte parameter I
________________
J

L_~

"I "I

IHENTRY

r---------------,
IL 15,VCIHESAPx)I

I

Halfword
boundary

L
IBR
_______________
15
JI

I

Fullword
boundary

I
I

V

IHESAPA (IHETSAP for
tasking environment)

r---------------,
IENTRY IHESAPA
IENTRY IHESAPB
IENTRY IHESAPC
IENTRY IHESAPD

1
I
I

IL 15,VCIHEMAIN)
I'L 15,0 (15)
IBR 15

The maximum length of the argument is 100
bytes and should be declared as CHAR(100)
VARYING in the main procedure. The
housekeeping module IHESAP/IHETSA builds a
string dope vector to describe the argument
as a varying character string so that on
entry to the main procedure the set up will
be:

r--------------------,
address of SDV
I
l---------T---------1

Register 1-->1

J

1
I
L
I _______________ J

SDV

r-~address

I ~---------T----------~
1I Il _________
X' 64'
I __________
1
JI

V

IHEMAIN

~

r---------------,
I DC VCENTRY A) I

I
I
I
I
I r--~----------------,
l>1L ___
1 11
byte parameterJI
________________

L _______________ J

I
I

V

PL/I program

~

r---------------,
IENTRY ENTRY A 1

length

L _______________ J

Initial Entry to Procedures
with the MAIN Option.

V

r--------------------,
of parameter 1

I
I

Figure 15-3.

I
I

data

Example:
PL/I PROGRAM

Passing Arguments to a Main Procedure: If
the entry points IHESAPA, IHESAPC or
IHETSAP are called the procedure will
expect a single character string argument
from the PARM field of the EXEC statement.
Register 1 should be pointing at the
address of the parameter, as shown below.

206

MYFROC: PROC C:PARAM) OPTIONS (MAIN) i
DCL PARAM CHAR (100)VARYINGi

END MYPROCi

ASSEMBLER LANGUAGE CALLING PROGRAM
L
L

BALR

SAPA
PARM
ADDR
LIST

Example:

1,PARM
15,SAPA
14,15

DC
DC
DS
DC
DC

PYI PROGRAM
MYPROC: PROC
DCL
DCL
DCL

V (IHESAPA)
A (ADDR)
H
AL2(L'LIST)
C 'THIS IS PARAMETER'

(A,B,C)
A CHAR
B CHAR
C CHAR

OPTIONS(MAIN)i
(10);
(20);
(30);

END MYPROC;
Register 1 will now be set up as follows:

END

ASSEMBLER LANGUAGE·CALLING PROGRAM
1,PARM
15,SAPB
14,15

L

If entry points IHESAPB, IHESAPD or
IHETSAA are called the procedure mayor may
not be ,expecting an argument list,
dependant on whether one was specified in
the procedure statement. Register 1 is not
examined by the housekeeping module
IHESAP/IHETSA, but simply passed on to the
main procedure. If no parameters have been
declared in the main procedure Register 1
will be ignored, but if parameters are
declared Register 1 will be expected to
point to a parameter list. The parameters
must be in a form acceptable to PL/I.

L

BALR

SAPB
PARM

DC
DC
DC
DC
DC
SDVA DC
DC
PARMA DC
SDVB DC
DC
PARMB DC
SDVC DC
DC
PARMC DC

Note: I·t is dangerous to assign to the
parameter of the EXEC statement.
(If
length is greater than the current length
job may fail).

V (IHESAPB)
A(SDVA)
A(SDVB)
X, 80'
AL3(SDVC)
A (PARMA)
2AL2(L'PARMA)
CL10 • PARAMETERA '
A (PARMB)
2AL2 (L" PARMB)
CL20'PARAMETERB'
A (PARMC)
2AL2(L'PARMC)
CL3 O' PARAMETERC'

END

As an e:2~ample, consider passing three fixed
length character-string arguments to the
main procedure.•

PARAMETER LIST

Registe:l:

The procedure prologue for each
procedure:

SDV of A

,------------------,
1--> I address of SDV of

r-------------,
address of A

A~------>I

~-------------------i

laddress of SDV of

B~----,

~-------------------~

laddress
of SDV of C~-,
L___________________
J
I

I
I
I
II
I

I

I

I
II

~---->

~----~-T------;

I

10

I

10

I

r-----'
I A I
L_____ J

L _____________ J

SDV of B

r-----'

I r-------~-----,
L->Iaddress of B ~---->I B I
. ~-----T------~
L_____ J
IL ______
20 I ____
20 JI
~_~

SDV of C

r-------------,

r-----'
C I

~---->I
f------T------~

L---->Iaddress of C

I

I

I

L_____ J

30
30 J
L ______
______
~

Chapter 15: PL/I and other Languages

207

1.

Sets general register 11 to point to
the static internal control section.

2.

Allocates a dynamic storage area (DSA)
for the procedure. The length is 100
bytes plus the lengths of the
automatic variables, parameter lists,
and dope vectors for that procedure.
The 100 bytes contains a register save
area plus interrupt and environment
information and the field used to
provide statement numbers in
object-time error messages.

3.

Chains the DSA back to the original
DSA or VDA. Sets flags indicating DSA
characteristics. Stores the address
of the DSA in the PR for that block.
The pseudo-register name is one of
those generated by extending the
procedure name to the left with
asterisks if necessary to make seven
characters and then appending, in
order, a single character from B
through Z and the special characters,
corresponding to the order of the
blocks in the compilation.

Manual. This section briefly discusses how
the blocks are used and how they are
related to the system and each other. No
attempt is made to cover all control
blocks, but only those that a programmer
might need to refer to. None of these
control blocks can be accessed usefully in
FORTRAN or COBOL, but an assembler language
subroutine, or an assembler language
routine that was acting as an interface
between PL/I and FORTRAN or COBOL, could
make use of their contents. The control
blocks discussed are:
1.

Library and data generated control
blocks
• string dope vector (SDV)
• Array dope vector (ADV)
• String array dope vector (SADV)
• Structure dope vector

2.

Input/output control blocks
• Declare control block (DCLCB)

4.

Initializes any automatic variables
having the INITIAL attribute.
Initialize all dope vectors for
automatic strings, structures, and
arrays.

• Open control block

~OCB)

• File control block (FCB)
• Input/output control block (IOCB)

5.

Obtains secondary dynamic storage for
variables that depend on the results
of step 4.. These areas are called
variable data areas (VOA). VDAs may
also be required for temporary work
space.

The procedure epilogue is initiated by a
call to the library routine IHESAF (an
entry point in IHESAP). This routine frees
the current DSA and any associated VDAs. A
request to free the DSA of a MAIN procedure
results in the raising of the FINISH
condition, closing all files still open,
and freeing all automatic storage for the
program. Control is passed from IHESAF via
general register 14, which, for MAIN
procedures is a transfer to the calling
program (usually the operating-sys'tem
supervisor). For other procedures, return
is to the statement following the call to
the procedure being terminated, except in a
shared library system, when there is
another level of control between the PL/I
environment and the operating system.

storage Organization.and Control Blocks
Detail formats and field descriptions of
the PL/I control blocks are contained in
the PL/I Subroutine Library Program Logic

208

• Record dope vector (RDV)
• Dope vector descriptor (DVD)
3.

Storage management control block
• Dynamic storage area (DSA)

string Dope Vector' (SDV): The string dope
vector is primarily necessary to support
such features as varying-length strings,
adjustable strings, and string arguments.
For example, the use of a dope vector
allows the SUBSTR function to operate
without duplicating the actual data that
makes up the substring. The result of this
function is simply an additional dope
vector that describes part of the original
string. Since this additional dope vector
exists only during the life of the
statement in which it occurs, it is creabed
in library workspace.
Array Dope Vector (ADV): The array dope
vector allows the bounds of the array to be
dynamically defined by the values of
expressions evaluated by the program, and
allows arrays to be passed as arguments; it
also provides the reference for the
SUBSCRIPTRANGE condition.
The main contents of the array dope
vector are the virtual origin, the

multipliers, and the bounds of the array.
The virtual origin (i.e., the location that
the element with all zero subscripts has or
would ha.ve if it existed) and the
multipliers are used, together with the
appropriate subscripts, in the address
calculation for a given element, thus:
n

addrel3s = virtual origin +

E

Si

i=l

*

positive or negative.
It is a 3-byte
field, and this must be considered when the
virtual origin is loaded into a register
for address arithmetic. For all except
bit-string arrays, the first eight bits in
the register will be zero after the virtual
origin has been loaded, and will thus
represent a positive number even though the
offset might be negative.

Mi

where n = number of dimensions
Si = value of ith subscript
Mi = value of ith multiplier
From the viewpoint of dope vector
construction, in contrast to dope vector
usage, it is best to think of the virtual
origin a.s a location relative to the start
of the actual array. You can calculate the
necessa:r-y virtual origin as follows:

=

VO
where

n

(first element address) - ~
i=l

~Bi=

M·

1

*LB.

LBOUND(array,i)

The mul-tipliers are calculated as follows:
n

* ,-r

M= 1

r=i+l

where I

(HB

r

- LB + 1)
r

= distance between the starts of
two consecutive single elements
(i.e., generally, the length of
a single element)

HBr= HBOUND(array,r)
LB = LBOUND(array,r)

r

For ex~mple, take an array of three
dimensions (10,5,6), with elements 5 bytes
long, the first of which is located at
12288.
M~

M2

5
5

M3

5

*
*

5
6

and
virtual origin

*

6 = 150
30

12288 - (150 + 30 + 5)
= 12103

The dope vector for based arrays is
slightly different from that for nonbased
arrays. The virtual origin, instead of
containing an actual address, contains the
offset of the virtual origin from the first
element declared. It can be calculated
from the above formula, but setting the
address of the first element to zero since
it is not known. Because the virtual
origin is not necessarily part of the array
itself, this offset could be either

1

String Array Dope-Vector (SADV): The
string array dope vector takes one of two
forms, depending on whether the strings are
varying or fixed-length.
If the L'Strings
are fixed, the SADV is an ADV with two
halfwords appended, each of which contains
the length of the strings in the array. If
the strings are varying, the format of the
SADV is the same, but certain meanings are
different.. To determine which format SADV
is being used, test the 'current length'
field in the SADV. If it is nonzero, the
strings are fixed-length, and normal ADV
processing can be used to access the
string. If the 'current length' field is
zero, normal ADV processing will point to
secondary dope vectors for each of the
varying strings and each element would then
be processed as an element variable. This
is necessary because each element in the
array could have a different current
length.
Structure Dope Vector:
The structure dope
vector is a concatenation of the dope
vectors or addresses of all the elements in
the structure. If an element has no dope
vector (i.e,., it is an element variable of
arithmetic type), a single fullword address
constant points to the element.
Declare Control Block (DCLCB): The DCLCB
is the primary compiler-generated control
block for input/output operations. It is a
read-only block and contains only the
information declared for the file (or
implied b¥ the declared 'attributes). Its
address is constant throughout the
execution of the program and it can be used
as the source of all information about the
file by any module requiring the
information.
A pseudo-register is used for
communication with other related control
blocks; the DCLCB contains the offset of
the file pseudo-register in the PRV.
Another pseudo-register, IHEQFOP is used to
identify all files open for the program.
open Control Block (OCB): When a file is
opened, the parameter list passed to the
PL/I open interface is called the open
control block. This block combined with
the DCLCB provides the PL/I attributes for
opening the file. The result of the
opening p~ocess is the file control block
Chapter 15: PL/I and other Languages

209

(FCB) and the input/output control blocks
(IOCBs).
File Control Block (FCB): The FCB contains
the PL/I information about the current
opening of the file, plus the DCB
associated with the file.

stored in the pseudo-register by the
routine. The routine name (the CSECT namle)
should be seven characters long, in
accordance with the naming convention for
pseudo-registers. You can request the DS;A.
by the following code:
L

Input/Output Control Block (IOCB): The
main purpose of the IOCB is to fill the
operating system requirement for data event
control blocks (DECBs) used by the BSAM and
BDAM/BISAM interfaces. The number of IOCBs
created varies with the data set
organization and access technique.
For BSAM, the number of IOCBs generated
is equal to the NCP value specified in the
DD statement for the data set or the
ENVIRONMENT file attribute. Unless the
EVENT option is used, only one IOCB is
required. If the EVENT option is used, one
IOCB should be created for each
input/output operation that could be
outstanding at a given point in time.
An
attempt to use more IOCBs than requested at
open time will raise the ERROR condition.
For BDAM and BISAM, only one loeB is
created at open time, and others are
created when needed. The IOCB also
contains the hidden buffer area if one is
required for BSAM or BDAM.
Record Dope Vector (RDV): Whenever a
record-oriented input/output operat.ion is
requested, one of two control blocks will
be passed to the PL/I library. If the
variable involved is a varying character
string, the parameter is an SDV; for all
other variables, an RDV is passed to the
PL/I library. Its contents depend on the
type of operation, but, basically, it
contains the address of the input/output
area for READ or WRITE operations, or t~he
buffer address after a LOCATE statement.
It also contains the aggregate length of
the specified variable.
Dope Vector Descriptor (DVD): The compiler
generates a DVD for use when an aggregate
has to be mapped at execution time rather
than compile time~ This occurs primarily
for aggregates specified with adjustable
bounds.
Dynamic storage Area (DSA): If you wish to
incorporate a non-PL/I routine into a PL/I
program, the main item of consideration in
the area of storage management will be the
DSA. If the routine is to be used in a
multitasking environment, the code should
be reentrant and should look like any other
PL/I routine. You should ensure that PL/I
conventions are followed, in particular
setting the proper flags in the DSA and
providing a pseudo-register for the
routine. The DSA of the routine must be
210

LA

BALR
MVI

15,=V(IHESADA)
0,100
14,15
o (13) , X' 80'

The second load instruction loads the
length of the DSA (note that 72 bytes is
not enough; the minimum length of the DSA
is 100 bytes).
On return from IHESADA, general regisber
13 will contain the address of the DSA.
The reason for using IHESADA is that the
DSA is now chained to the other DSA's and
the PRV in the standard PL/I way. The flag
byte will be used by IHESAFA in returning
control. The coding for returning control
is shown belOW':
L
BR

15,=V(IHESAFA)
15

When the above instructions are executed,
the DSA is freed and control is returned 1to
the caller.
To request a pseudo-register for the
routine, append a 'B' to the CSECT name as
an eighth character and use the result as
the label of a DXD instruction. For
example:
SUBRUTN CSECT
SUBRUTNB DXD A
Code the SAVE register macro-instruction
thus:
SAVE (14,12),,*
The asterisk causes the CSECT name to be
coded into the program for easy
identification in a main storage dump or
snapshot. For intermodule trace routines,
you should use the chain-back and
chain-forward of the OSAs.

Arguments and Parameters
The (F) compiler generally conforms to th4e
IBM System/360 Operating System standard
calling sequence, as follows:
1.

Arguments are passed by name, not by
value.

2.

General register 1 contains the
address of the first address constant

i.n the parameter list, except when the
main procedure is called.
3.

'jlhe caller provides a register save
area addressed via general register
1.3. The invoked program stores the
contents of the general registers of
t:he invoking program in this area.

4.

'I'he invoked program loads into general
Z:'egister 13 the address of a save area
t:hat can be used by any program that
i t invokes.

5.

On return to the invoking program,
g'eneral registers 2 through 13, the
p.rogram mask, and the PICA will appear
unchanged.
General register 14 will
point to the return address in the
invoking program (set by a BALR
instruction). General registers 0, 1,
a.nd 15, the floating-point registers,
and the condition code may be changed.

The main difference between PL/I argument
passing and that of other languages is that
the addresses in the list addressed by
general register 1 do not necessarily point
to the! data items that each represents.
The list passed by thePL/I module is the
same a.s t'hat of other languages only for
arithmetic element data items.
In all
other cases, the address in the list points
to a dope vector.
(The various dope
vectors are discussed briefly above.)
In ·the following example, these
abbrev'iations are used:
SDV
ADV
S'I'DV
SA.DV

String Dope Vector
Array Dope Vector
Structure Dope Vector
String Array Dope Vector

Exainpl.e:
DCL A
B
C
D

FIXED DECIMAL,
FIXED BINARY,
FLOAT DECIMAL,
FLOAT BINARY,
E PICTURE '999V99',
F PICTURE 'XXXAAA',
G CHARACTER(10),
H BIT(16);
DCL 1 1(10),
2 J FIXED DECIMAL,
2 K CHAR(12);
DCL 1 L,
2 M CHAR(4),
2 N CHAR (5);
DCL :P ( 5) FI XED,
Q(S) CHAR(2),
R(S,4) FIXED;
CALL, SUB(A,B,C,D,E,F,G,H,I,I.J,I.J(l) ,L,
L.M,P,P(l),Q,Q(l),R,R(l,l»;
The fi.rst DECLARE statement above refers to
element variables. A through E are

arithmetic; the rest are strings. The
second DECLARE statement defines an array
of structures; the third a structure, and
the fourth a number of arrays. The CALL
statement generates the following parameter
list; general register 1 will contain the
address of the first address constant in
the list:
PARM DC A(A)
DC A(B)
DC A(C)
DC A(D)
DC A(E)
DC A(SDV of F)
DC A(SDV of G)
DC A(SDV of H)
DC A(STDV of I)
DC A(ADV of I. J)
DC A(I.J(l»
DC A(STDV of L)
DC A(SDV of L.M)
DC A(ADV of P)
DC A (P (1»
DC A(ADV of Q)
DC A(SDV of Q(l»
DC A(ADV of R)
DC A (R (1,1»
There are several points to note about this
param~ter list.
For variables A, B, C, D,
and E, the parameter list is identical to
those of object programs for other
languages compiled under the IBM System/360
Operating System: this is because each is
an arithmetic element variable.
Similarly,
even though they belong to arrays, I •.J(l),
P(l), and R(l,l) are passed by their actual
addresses; their subscripts are included in
the argument list of the CALL statement and
they each identify a single element of an
arithmetic array, so they are treated as
elements.
(This would be so even if the
subscripts were expressions instead of
constants; at execution time, a specific
element would be referred to.)
None of the
other arguments represents an arithmetic
element, and so they are represented by
their respective dope vectors.
Note particularly the array of
structures, I. The dope vector for I
consists of two dope vectors: the ADV for
I.J and the SADV for I.K..
I itself,
therefore, is not really treated as an
array, but more as a structure with its
dimensionality carried down to the elements
of the structure.
In this case, the
multipliers used in the dope vectors will
be the same for both I.J and I.K, and will
be the length of a single J (3 bytes) plus
the length of a single K (12 bytes), i.e.,
lS.
The virtual origin of K is 3 bytes
from the virtual origin of J. Had the item
I been declared:
Chapter lS: PL/I and other Languages

211

DCL 1 I,
2 J(10} FIXED DECIMAL,
2 K(10} CHAR(12};
then I would be a structure of arrays
:rather than an array of structures.. The
!format of the dope vector for I would bE~
~he same, but the multipliers and virtual
origins would be different. The multiplier
for J would be 3, that for K would be 12,
and the virtual origin of K would be 30
bytes from that of J.
If you are writing assembler language
modules that will be called from PL/I
~rograms, note the following points:
1.

2.

3.

When a dope vector is passed for a
string element, only another load
register instruction is required to
get the address of the actual data.
As shown in the examples of I.J(l},
P(l}, and R(l,l} above, passing the
first element of an array or s·tructure
rather than the array or structure
itself will avoid calculations and
additional manipulation that would
otherwise be necessary to obtain the
actual data. This is possible only if
the data characteristics are known in
the called program.
An ADV contains the virtual or1g1n of
the array, not the actual origin;
also, arrays are stored in row major
order, not column major order.

COMMUNICATION WITH OTHER LANGUAGES
This·section deals with ·the problems of
palling non-PL/I modules from PL/I programs
and vice versa. The main topics are
passing data items between modules written
in different languages and establishing the
~ppropriate environment; also discussed are
the use of function references between
languages, and the invocation of
~ser-defined PL/I ON-units from assembler
language subroutines and func·tions.

Passing Data Items
When data items are to be passed from PL/I
~odules to non-PL/I modules and vice versa,
the main considerations are:
1.

The use of PL/I dope vectors

2.

Data format differences

3.

Data mapping differences

212

Only the first item is discussed in this
section, since the other two have been
discussed earlier in the chapter, under the
heading 'Data Set Interchange.'
One way to solve the problem of dope
vectors is to overlay arithmetic based
variables in the PL/I program onto the
beginning of items that require dope
vectors (i.e., all items except arithmetic
elements); thus the parameter can be made
to look like an arithmetic element in the
parameter list.. Note that a based variabl1e
used in this way should not normally be
referred to anywhere except in a call to a
non-PL/I module. For example, if a
character string is to be passed from a
PL/I module:
DCL STRINGA CHAR(20),
PARMA FIXED DEC(l,O} BASED(P};
P=ADDR(STRINGA);
CALL SUB (PARMA) ;
In this case, the parameter list will
consist of an address constant that
directly addresses PARMA, an arithmetic
element variable. But since the pointer P
points to the first character position of
STRINGA, the routine SUB will have access
to STRINGA wi thou·t concern for the STRINGA
dope vector.
Similarly, if ·the string is to be passed
to a PL/I module from a non-PL/I module,
the PL/I coding could be as follows:
PL1SUB: PROC(PARMA);
DCL PARMA FIXED DEC(l,O),
STRINGA CHAR(20) BASED(P);
P=ADDR (PARMA) ;
Now the dope vector for STRINGA will point
to PARMA.. since PARMA is an arithmetic
element, the PL/I program will expect the
parameter list to contain the address of
PARMA.
Another way of communicating data items
between FORTRAN and PL/I modules is to use
named common storage for the item. You can
do this by declaring the identifier STATIC
EXTERNAL in the PL/I module and COMMON in
the FORTRAN module. This results in an
external control section. For example:
FORTRAN
COMMON/COMAR/DVAR,I,A,CHR,IRAY
DIMENSION DVAR(7),CHR(3),IRAY(100)
PL/I
DCL 1 COMAR STATIC EXTERNAL,
2 I FIXED BIN(31,0),
2 A FLOAT DEC,
2 CHR CHAR(12),
2 IRAY(100) FIXED BIN(31,0);

The act:ual storage layout would be as shown
in Figure 15-4.

using the linkage editor CHANGE statement
immediately before the FORTRAN module or
its INCLUDE statement.)

Note the following. points in connection
with this method of communication:

If more than one PL/I procedure is to be
called from non-PL/I routines or if FORTRAN
or COBOL subroutines or FORTRAN functions
are to be invoked from PL/I, an assembler
language interface routine must be used.
The main purpose of this interface routine
is to save the environment of the language
that called it and to establish the
environment of the language to which it is
to give control.

1.

2.

There may be padding between the PL/I
dope vector and the start of the
st:ructure. The dope vector is always
at the start of the control section
and is therefore always located on a
dcmbleword boundary; it will consist
of a number of fullwords. Therefore
there could be up to seven unused
bytes between the dope vector and the
st:ructure if the member having the
highest alignment requirement is not
the first member of the structure. In
the above example, there is no
padding, since the structure is
word-aligned and starts with a
full word. If I had been halfword
binary, there would be two bytes of
pcldding between the dope vector and
the structure. This could be
accommodated by a dummy variable of
IE!ngth two in the FORTRAN COMMON
st:atement immediately after DVARi
alternatively, DVAR could be declared
as INTEGER*2 and its dimension
increased to 15.
When there are two or more identical
eJl:ternal references, the linkage
editor acts on the first one
encountered. Since the PL/I dope
VE!ctor must be completed, the PL/I
mc)dule must precede the FORTRAN module
on input to the linkage editor.
(It
nE~ed not necessarily be executed
first; you can use the ENTRY statement
a1: the end of the JCL for the
link-edit to ensure that the correct
module gets initial control.)

If you are calling multiple PL/I
procedures from COBOL or FORTRAN, your
interface routine should perform certain
functions:

1.

Assuming that calls to PL/I modules
from other languages will not be
nested, a 'first-time-through' routine
can be executed to call the library
module IHESAP, which establishes the
PL/I environment, at entry-point
IHESAPD. This would require that the
interface routine contain a control
section called IHEMAIN that contains
the address to which IHESAP is to
transfer control after initializing
the environment.

2.

The pointer to the PRV, returned by
IHESAP in general register 12, should
be saved for future executions of the
interface routine. Note that the
address returned in register 1 by the
SPIE macro instruction issued by
IHESAP has been saved by the PL/I
library.
If it is required, in order
to reissue the SPIE macro instruction
of the calling program, i t may be
obtained by the following code:
L
ORG
DC
L

Establishing the Environment
If one procedure only is to be called from
a non-PL/I routine, and if releasing the
PL/I environment on exit from the procedure
does n(~ adversely affect the execution of
the pr(~ram, the PL/I procedure should be
gi ven 1:he MAIN option. The PL/I procedure
will bE~ entered by the statement CALL
IHESAPD.
(Since the name IHESAPD has more
than six characters, FORTRAN programs must
have a dummy name for IHESAPD that is six
or less characters long. You can change
this nc~e to IHESAPD at link-edit time

3.

Rx,O(12)
*-2
QL2(IHEQLSA)
Rx,12(Rx)

For all executions after the first,
the parameter list pointer in general
register 1 should be saved and the
SPIE macro instruction for PL/I should
be issued, specifying IHEERRA as the
routine for handling interrupts. The
address returned by the SPIE macro
instruction in register 1 should be
saved as it will be required to reset
the COBOL or FORTRAN SPIE macro
instruction on return from the PL/I
procedure.

Chapter 15: PL/I and other Languages

213

COMAR---> r-------;------------------·--------~-------,
I A(I)
1 word
I
r-------------------·---------------------~

I A(A)
1 word
I
I.-----------------------------------------~
SDV of CHR
2 words
I
I
I
r----------------------------------------~
I
I
I ADV of IRAY
3 words
I
I
I

PL/I Structure Dope
Vector (storage
reserved in FORTRAN
by DVAR)

.-----------------------------------------~

I

I

I

1 word

.--------------------.--------------------~

I

A

I

1 word

.-----------------------------------------~
I
I

I
I

CHR

I

IRAY(l)

12 bytes (3 words)

I
I

.--------------------.-----.----------------~

I

r-------------------·--------------------~

I

IRAY(2)
I
.-----------------------------------------~
I lRAY(3)
I
r-------------------·-------------------~

I
I

I
I

1 word each

I
I
I
I
I.-----------------------------------------~
IRAY(100)
I

j
L ____________________ .____________________
J

Figure 15-4.
4.

PL/I-FORTRAN: Example of Named Common storage

Provided that general register 12
points to the PRV, the PL/I entry
point can be called. If the,a.rgument
list from COBOL or FORTRAN was of the
form:

2.

In calling a FORTRAN module,
initialization of the environment is
carried out by invoking the FORTRAN
library as follows:
L 15,=V(IBCOM#)

(PL/I-entry-point, parm-l, parm-2, ••• )
BAL 14,64(15)
then general register 1 (whose
contents were saved in step 3) will
point to the PL/I entry address
constant. If the value 4 is now added
to general register 1, the result will
be the address of the parameter list
that the PL/~ module expects.
5.

On return from the PL/I module, the
COBOL or FORTRAN SPIE is reset and
control is passed back to the original
calling module.

If a FORTRAN or COBOL modul e is ·to be
called from a PL/I program, basically the
same procedure as outlined above can be
used as an interface, the difference being:
1.

In calling a COBOL module no
initialization of an environment is
required except that the SPIE macro
instruction must be re-issued.

Conununication between assembler languag1e
and PL/I modules is subject to the same
interface problems, and the above concepts
apply. However, additional conventions
should be observed by an assembler routine
that invokes a PL/I routine and is itself
invoked by another.PL/I routine. The
conventions are given in the preceding
section "Storage organization and Control
Blocks" under the sub-heading "Diagnostic
Storage Area (DSA)"e

Function References
The basic difference between a subroutine
and a function is that a subroutine is
invoked by a CALL statement and does not
actually return a value (although it may
\.)

214

change the value of a variable known to the
calling program), whereas a function is
invoked by a function reference which can
be used in the same way as an expression;
the function always returns a value, and
this value is represented by the function
reference. COBOL does not have function
references, and so the following discussion
does not apply to COBOL-PL/I communication.
A function written in another language
can be declared with the ENTRY and RETURNS
attributes in a PL/I program. Then,
whenever the function name occurs in the
program. control will be passed to the
user-written function of that name. On
entry to the function, normal linkage
should be performed.
At execution time, the difference
between a PL/I function reference and a
subroutine call is that th~ function
parameter list will have an extra item
representing a temporary into which the
function is to place its result. The
address~ depending on the data
characteristics declared in the RETURNS
attribute in the invoking program, will
either be direct or will be that of a dope
vector (according to the same rules as for
normal parameters). Just as with entry
declarations for PL/I-written procedures,
you could use the GENERIC attribute to
specify alternative entry points to an
assembler language function, based on the
declared attributes of the arguments. The
assembler language function need only
specify each name as an entry point.
The method employed to return the value
from a function to the invoking procedure
differs between FORTRAN and PL/I. A
FORTRAN function returns its value in
general register 0 (if integer or logical),
floating-point register 0 (if real), or
floating-point registers 0 and 1 (if
complex). In PL/I, as already mentioned,
an additional argument is automatically
provided for the returned value. To
resolve this difference in function
communication, an assembler language
interface routine must be used. When a
FORTRAN program invokes a PL/I function,
this routine would create a new argument
list consisting of the original list and an
additional argument. The routine would
pick up the value returned in this
additional argument when the function is
complete, and place the value in the
appropriate register(s) before passing
control back to the FORTRAN program. When
a PL/I program invokes a FORTRAN function,
the assembler language routine would obtain
the result from the register and place it
in the additional argument. Separate entry

points to the assembler language interface
routine would be necessary for different
data types since the location of the result
depends on its characteristics.

User-Defined Conditions in Assembler
Language Subroutines and Functions
When you write a PL/I program, you can
provide an ON-unit for any circumstance you
wish to test for. The ON-unit is defined
by any ON CONDITION(condition-name)
statement, the condition name being one of
your own choosing.
(Note that since a
user-defined condition is given the
EXTERNAL attribute, the name must be no
more than seven characters long.) The
ON-unit can be invoked by a SIGNAL
statement naming the condition.
If a PL/I program invokes an assembler
language module, and such a user-defined
condition occurs during the execution of
the module, the equivalent of the
appropriate SIGNAL statement will be needed
in the module in order to invoke the
ON-unit.. To provide this. the assembler
language routine must generate a parameter
list of one word; byte one of the word
contains X'50' and the second through
fourth bytes are an identifying field
containing the address of an external
control section that has the same name as
the user-defined condition. General
register 1 is then set to point to this
parameter list, and the routine calls the
PLiI library entry IHEERRD. After
execution of the ON-unit, control will be
returned to the instruction following the
IHEERRD call. An example of a 'SIGNAL' to
a use~-defined condition named COND would
be as follows:
15,=V(COND)
15,PARM
PARM,X'50'
1,PARM
LA
15,=V(IHEERRD)
L
BALR 14,15
L

ST
MVI

PARM DS

F

The register save area for the routine
should look like a PL/I DSA. That is, the
first byte of the first word should contain
X'80', and bytes two through four should
contain the save area length. The second
and third words should be used for the
chain-back and chain-forward addresses
respectively.
Chapter 15: PL/I and Other Languages

215

216

PART 3: Appendixes

Part 3: Appendixes

217

218

Appendix A:

Programming Examples

Each of the following examples reproduces
the cOl1nplete printed listing. Each listing
is preceded by a description of the example
and thE~ listing, including references to
parts of the manual that deal with the
featurE~S being illustrated.
All the source
statemEmts, job' control statements, and
data ccrrds are listed as they would appear
in the job stream.

LISTING

For easy reference to the listing, the
description uses the circled numbers that
haye bE~en added to the top right-hand
corner of ,each page of the listing.

Pages 2-4:

The listing produced by the
PL/I (F) compiler, which is
described fully in Chapter S.
The PL/I source statements appear
on page 3 of the full listing
(page 2 of the compiler listing).

Page

The disposition of the data sets
used by the compiler in the first
job step, and a list of the
addresses of the units to which
the data sets for the second job
step (LKED) were assigned.

Page

1:

The JOB statement, and a list of
the addresses of the units to
which the data sets for the first
job step (PL1L) were assigned.

Example 1: Simple PL/I Program
5:

This e)~ample illustrates the use of the
catal0ged procedure PL1LFCLG to compile,
link-edit, and execute a simple PL/I
program that uses only punched-card input
and printed output. The job control
statemEmts it includes are described in
Chapter 2.
Pages 6-8:

The listing produced by th~
linkage editor; this is described
fully in Chapter 6.

,=

Page

The disposition of the data sets
used by the linkage editor in the
second job step, and a list of
the addresses of the units to
which the data sets for the third
job step (GO) were assigned.

*

Page 10:

The printed output p~oduced by
the example program.

Page 11:

The disposition of the data sets
used by the example program in
the third job step.

//J013PGEA JOB
// EXEC PL1LFCLG
//PL1L.SYSIN DD *
EX001: PROCEDURE OPTIONS(MAIN);
DECLARECA,B,C) FIXED DECIMAL(3);
NEXT:
GET FILE(SYSIN) DATA(A,B):
IF A
999 THEN DO;
C=A+B;
PUT FILE(SYSPRINT) SKIP
DATA(A,B,C);
GO TO NEXT;
END;
END EX001;
/*

//GO.SYSIN DO
A=131 B=75;
A=2 B=907;
A=-14 B=14;
A=341 B=429;
A=-245 B=102;
A=999 B=100;
/*

9:

~ppendix

A: Programming Examples

219

IIJ013PGEA Joe
JOB LOGGED ON AT IBM'S HURSLEY LABS
IEF236I ALLOC. FOR J013PGEA PL1L
IEF237I SYSPRINT ON 293
IEF237I SYSLIN
ON 342
IEF237I SYSUT3
ON 343
IEF,37I SYSUTl
ON 344
IEF237I SYSIN
ON 290

VERSION 5.0

OS/360

CLOCK=13.38.18

MVT 1&

OS/360

DATE=69.273

PL/I COMPILER IFl

MACHINE=Jl

PAGE
l{";;'\
DATE 69.2730

PL/I F COMPILER OPTIONS SPECIFIED ARE AS FOLLOWS-LCAD.NOCECK.SIZE-100K
THE COMPLETE LIST OF OPTIONS USED DURING THIS COMPILATION IS--

*OPTIONS IN EFFECT*
*OPTIONS IN EFFECT*
*OPTIONS IN EFFECT*

EX001:
. STMT LEVEL NEST
1
2
3
It

1

6

1
1

1

7
8

1
1

1
1

9

1

1

10

220

1

EBCDI C,CHAR60. NOMAC RO, SOURCE2. NOMACDCK. COMP, SOURCE. NOATR. NOXREF, NOEXTREF, NOll ST, LOAD.
NODECK,FLAGW,STMT,SIZE-0102400,LINECNT-055,OPT=02,SORMGIN=1002,072,OOll,NOEXTDIC,
NEST,OPLIST

PROCEDURE OPTIONSIMAINl;

EX001:
NEXT:

1

EBCDIC
CHAR60
NOMACRO
SOURCE2
NOMACDCK
COMP
SOURCE
NOATR
NOXREF
NOEXTREF
NOLlST
LOAD
NODECK
FLAGW
STMT
SIZE=0102400
LINECNT=055
OPT-02
SORMGIN=1002.072.00ll
NOEXTDIC
NEST
OPU ST

PROCEDURE OPTIONS(MAIN);
DECLARE IA,B,C) FIXED DECIMALI3Ji
GET FILEISYSINl DATAIA,B)i
IF A..... 999 THEN DO i
C-A+Bi
PUT FILE(SYSPRINT) SKIP DATA(A,B,C);
GO TO NEXT;
ENDi
END EX001;

PAGE

Exa01:

PAGE

PROCEDURE OPTIONSCMAIN);

STORAGE REQUIREMENTS.
THE STORAGE AREA FOR THE PROCEDURE LABELLED EX001 IS 192 BYTES LONG.
THE PROGRAM CSECT IS NAMED EX001
THE STATIC
*STATISTIC.S*

AND IS 200 BYTES LONG.

CSECT IS NAMED **EXC01A AND IS 219 BYTES LONG.

SOURCE RECORDS =

10, OBJECT BYTES

9,PROG TEXT STMNTS =

200

NO ERRORS OR WARNINGS DETECTED.
AUXILIARY STORAGE WILL NOT BE USED FOR DICTIONARY WHEN SIZE

65K

COMPILE TIME
.02 MINS
ELAPSED
______
____________________________________________________________________________________
TJ:~ME~

~.3~8~M~I~N~S

SYSOUT
IEF285I
SYS69213.T132652.SVOCO.J013PGEA.R0000027
IEF2851
VOL SER NOS= M65293.
IEF2851
SYS69273.T132652.RVOCO.J013PGEA.LOADSET
PASSED
IEF2851
VOL SER NOS= 231422.
DELETED
I EF2851
SYS69273 .Tl32652 .RVOOO .J013PGEA .R0000028
IEF2851
VOL SER NOS= 231423.
IEF2851
SYS69273.T132652.RVOOO.J013PGEA.R0000029
DELETED
IEF2851
VOL SER NOS= 231424.
IEF2851
SYS69273.T132652.RVOOO.J013PGEA.S0000030
SYSIN
I EF285 I
VOL SER NOS= M65295.
DELETED
SYS69273.T132652.RVOOO.J013PGEA.S0000030
IEF2851
IEF2851
VOL SER NOS= M65295.
END OF STEP 'PL1L
'
JOB 'J013PGEA'
STEPTIME=00.00.02
tEfl.3el AI.I,.OC. FOR J013PGEA LKED
IU2"37I S'YSUB
ON 295
IEF2371
ON 295
IEF237I
ON 1CO
IEF2371 SYSLMOD ON 342
ON 343
IEF2371 SYSUT1
I EF237 I S'fSPRINT ON 294
IEF2371 SYSLIN
ON 342'

~

®
CLOCK~13.38.55

DATE=69.273

~ppendix ~:

RETURN

CODE=OO~O

programming Examples

221

F88-LEVEL LINKAGE EDITOR OPTIONS SPECIFIED MAP,LIST
VARIABLE OPTIONS USED - SIZE=ll04448,59392)
IEW0461
IHEDDJA
I EW0461
IHEDDPA
IEW046l
IHEDDPB
IEW046l
IHEDCPC
I EW046l
IHEDDPD
IEW046l IHEUPBA
IEW046l
IHEUPBB
I EW046l
IHEVPAA
IEW046l
IHEVPCA
I EW046l
IHEVFBA
IEW0461 I HE VFDA
I EW0461
IHEVFEA
IHEVKBA
IEW0461
IEW046l IHEVKCA
I EW0461
IHEVKFA
I EW0461
IHEVKGA
I EW046l
IHEVSBA
I EW0461
IHEVSFA
IEW0461 IHE VSEB
I EW0461
IHEM91A
. I EW046l
IHEM91B
IEW0461 IHEM91C
IHETERA
IEW0461
I HE VCSA
I EW0461
IEW046l
IHEKCDB
IEW0461
IHEDNBA

®

DEFAULT OPTIONIS) USED

MODULE MAP
CONTROL SECTION
NAME

ENTRY

ORIGIN

LENGTH

EXOOl
**EXOOlA
IHEMAIN
IHENTRY
IHE SPRT
SYSIN
IHEDDI *

00
C8
1A8
1BO
1CO
1F 8
230

C8
DB
4
C
38
38
53C

IHEDDO

770

288

*

IHEIOA

*

9F8

16A

IHEIOB

*

B68

1E4

IHESAP

*

050

AB8

222

NA.ME

LOCATION

NAME

LOCAT ION

NAME

LOCATION

NAME

LOCATION

IHEDDIA

230

IHEODIB

232

I HEODOA
I HEDDOE

770
778

IHEDDOB

772

I HEDDOC

774

IHEDDOD

776

I HE IOAA
IHEIOAT

9F8
AE8

IHEIOAB

9FA

IHEIOAC

9FC

I HE ICAD

9FE

I HE IOBA
IHEIOBE

B68
!:l88

IHEIOBB
IHEIOBT

B70
C74

IHEIOBC

B78

IHE I CBO

B80

NAME

IHEDCN

ORIGIN

LENGTH

>0:

1808

lEF

*

19F8

F8

IHEDNC

>{<

lAFO

284

IHEUPA

>0:

1078

E8

IHEDMA

IHEVFA
IHEVPB
I HEVPO
IHEVPE

*

lE60

>0:

1FOO

lA2

*
*

2178

105

2280
24FO

50

IHEVSC

*

2540

AC

>0:

2020

20C

IHELOI

>0:

3000

858

IHEVFC

.4<

3858

26

I HEVPG

3880

229

IHEVPH

3A60

64

IHEVQB
IHE VQC
I HEBEG

'4<

:+:

IHEIOP
IHELOO
IHEOCL
I HE PRT

LOCATION

IHESAPC
IHESADF
IHESAFA
IHESAFQ

D6A
D8A
DAA
DCA

IHEDCNA

1808

IHEDCNB

180A

I HE OMAA

19F8

IHEUPAB

10E2

I HEDNCA

lAFO

I HE UPAA

1D78

I HEVFAA

lE60

IHEVPBA

lFOO

NAME
IHESAPO

LOCATION

NAME
IHES~PA

LOCA'T ION

IHESAF&
I HE:SARC

072
D92
DB2
1566

IHESADE
IHESAFD
I HE SADD

D7A
D9A
DBA
1674

IHES~DB

CD

I HEVPDA

2178

I HEVPEA

2280

IHEVPFA

24FO

I HEVSCA

2540

I HEERRO
IHEERRE

25FO
2C86

IHEERRC

25FA

I HEERRB

2604

IHEERRA

260E

I HE IOFB
IHEITAA

2020
2FOE

IHE IOFA

2022

IHE ITAZ

2FBE

IHE ITAX

2FCA

IHELOI B

3002

IHELOIC

3004

IhELOIO

3006

IHEOCLO

48F6

729

IHElOF

'"

NAME

D50
D82
DA2
OC2
16AE

26C

>0:

25FO

LOCATI ON

16C

IHEVPF

IHEERR

NAME
I HE:SADA
I HESAPB
IHESAFC
I HESARA
I HESAFF

3B68

494

4000

268

4268

80

42E8

1EB

*

4408

*

48FO

554

4E48

2C8

I HE~O IA

3000

I HEVFCA

3858

I HEVPGA

3880

I HEVPHA

3ABO

I HEVQBA

3B68

IHEVQCA

4000

I HEBEGN

4268

IHEBEGA

42A8

I HE IOPA

42E8

IHEIOPB

42EA

IHEIOPC

42EE

I HELDOA

4408

IHELDOB

440A

IHELOOC

440E

I HEOCLA

48FO

IHEOCLB

48F2

IHEGCLC

48F4

418

Appendix A: Programming Examples

223

NAME

ORIGIN

LENGT H

l.OCATION

IHEPRTA

IHESIZ

*

5110

C

IHETAB

*

5120

C

IHEVCA

*

5130

lOA

IHEVQA

*

5240

Ec

*

532E

IHEVSD

NAME

lAO

4E48

I HESIZE

5110

I HETABS

5120

I HEVCAA

5130

I HEVQAA

5240

I HEVSDA

5328

NAME

LOCATION

IHEPRTB

4E4A

IHE: VSDB

532A

NAME

LOCATION

LOCAT ION

NA"E

@

PSEUCO REGISTERS
NAME
IHEQINV
IHEQSPR
IHEQLW1
IHEQLWE
IHEQFOP
IHEQSLA
IHEQSFC

ORIGIN
00
10
20
30
40
54
64

LENGT H

'NAME
IHEQERR
SYSIN
IHEQLW2
IHEQLCA
IHEQCFL
IHEQS AR
IHEQXLV

4
4
4
4
4
4
4

TOTAL LENGTH OF PS EUDO REGISTERS
ENTRY ADORE SS
180
TOTAL LENGTH
54C8
****GO

ORIGIN

LENGTH

4
14
24
34
44
58
68

4
4
4
4
8
4
8

NAME

ORIGIN

LENGTH

8
18
28
38
4C
5C
70

4
4
4
4
4
4
8

IHEQTIC
IHEQLSA
IHEQLW3
IHEQVDA
IHEQADC
I HEQLWF
IHEQEVT

NAME
**EX001B
IHEQLWO
IHEQLW4
IHEQFVD
IHHLPR
I HEQRTC

OR IGIN

·LE:NGTH

C
1C
2C
3C
50
60

4
4
4
4
4
4

78

DOES NOT EX 1ST BUT HAS BEEN ADDED TO DATA SET
DIAGNOSTIC MESSAGE DIRECTORY

IEW0461 WARNING - SYMBOL PRINTED IS AN UNRESOLVEO EXTERNAL REFERENCE, NCAL WAS SPECIFIED.

KEPT
tEF2851
SYS1.PL1LIB
IEF285I
VOL SER NCS.IC 2301CO.
IEF2851
SYS69273.T132652.RVOCO.J013PGEA.GOSET
PASSED
IEF285I
VOL SER NOS= 231422.
IEF2851
SYS69273.T132652.RVOOO.J013PGEA.R0000031
DELETED
IEF285I
VOL SER NOS= 231423.
IEF285I
SYS69273.T132652.SVCOO.J013PGEA.R0000032
SYSOUT
IEF285I
VOL SER NOS- M65294.
IEF285I
SYS69273.T132652.RVOOO.J013PGEA.LOADSET
DELETED
IEFZ851
VOL SER NOS= 23142Z.
END OF STEP 'LKED
'
JOe 'J013PGEA'
STEPTIME-00.00.02
IEFZ361 ALLOC. FOR J013PGEA GO
IEF237I PGM=*.DD ON 342
IEF237I SYSPRINT ON 294
ON 290
IEF237I SYSIN

A=
AAA=
A=

224

131
2
-14
341
-245

eB=
B=
B=

s=

75
907
14
1t29
102

CC=
C..
CC=

206
909
0
770
-143

®
CLOCK-13.39.33

DATE=69.273

RETURN

COOE~OOOIt

@I

IEF2851
IEF2851
lEF2851
IEF2851
IEH85!
IEF2851:
IEF285JI
I EF285J:
END OF
IEF285l1
I EF285J:
END OF

SYS69273.T132652.RVOCO.J013PGEA.GOSET
PASSED
VOL SER NOS- 231422.
SYS69273.T132652.SVOCO.J013PGEA.ROOOO033
S YSOUT
VOL SER NOS= M65294.
SYS69273.T132652.RVOOO.J013PGEA.SOOOO034
SYSIN
VOL SE R NOS= M65295.
SYS69273.T132652.RVOCO.J013PGEA.SOOOO034
DELETED
VOL SER NOS= M65295.
STEP 'GO
JOB 'J013PGEA'
STEPTIME=OO.OO.Ol
SYS69273.T132652.RVOOO.J013PGEA.GOSET
DELETED
VOL SER NOS= 231422.
CPUTIME=00.00.06
JOB 'J013PGEA' 110 TIME=00.00.08

®
CLOCK=13.40.47

DATE=69.273

RETURN CroE -0000

CLOCK=13.40.48

DATE=69.273

SYSTEM P"CKS 300 AND 311

Appendix A: Programming Examples

225

Example 2: .Compiler and Linkage Editor Listings
//J063PGEX JOB
//COLEEX EXEC PL1LFCLG,PARM.PL1L='L,E,A,X,M,S2,NT',
//
PARM.LKED='LIST,XREF,OVLY~,
//
COND.GO=( (9,LT,LKED), (15,I.. T,PL1L»
//PL1L.SYSIN DO *
Pi:
PROC OPTIONS(MAIN);
%DCL AA CHAR, (Vl,V2,V3,V4) FIXED;
%AA='IF ANS>COMP THEN WORDS="GREArER THAN";
ELSE IF ANS •

pseudo~registers.

2.

Statement of the disposition
of the load module GO.
(Refer to 'Control statements
and Errors' in Chapter 6.>

3.

Diagnostic Message Directory.
The only message refers to
the list of modules external
references that were not to
be resolved.
(See above.>

This is the end of the
linkage-editor listing.
Page 3:1L:

1.

2.

The disposition of the data
sets used by the linkage
editor. Only the data set
that contains the load module
is passed to the last· job
step; it is identified by a
system generated name that
ends with the temporary name
GOSET assigned to it in the
DO statement SYSLMOD.
(The
load module is the member GO
of the temporary library
GOSET. >
Job scheduler END OF STEP
message, including the return
code supplied by the linkage
editor. The code 0004
indicates that the linkage

3.

The job control statements of
the cataloged procedure step
GO (execution of the load
module>.
Each of these
statements is prefixed xx.

4.

A list of the addresses of
the units to which the data
sets required during
execution of the load module
are assigned.

Page 32:

The printed output from the PL/I
program.

Page 33:

1.

The disposition of the data
sets used during execution of
the load module. Note that
the data set GOSET is not
deleted until after the end
of the job because step GO
does not contain a DD
statement that specifies its
disposition.

2.

The job scheduler END OF STEP
message for the step GO.

3.

statement of the disposition
of the data set GOSET.

4.

Job scheduler END OF JOB
statement.

Appendix A: programming Examples

229

IIJ063PGEX JOB (4056,NI09),R.SMALL.MSGLEVEL-l,MSGCLASS-0.CLASS-0
IICOLEEX EXEC PLILFCLG,PARM.PLILm'L,E,A,X,M,S2,NT',
PARM.LKEO-'LIST,XREF,O\lLY',

II
II

CONo.Gb-«9,LT,LKED),(~5,LT,PL1L)1

EXEC PGM-IEMAA,PARMc'LOAD,NODECK,SIZE-100K',REGION c 10SK

XXPL1L

XXSYSPRINT DD SYSOUT-~,DCBc(RECFM-VBA,LRECL-125,eLKSIZEu629)
XXSYSLIN
DO DSNAME=&&LOAOSET,DISP=(MOD,PASS),UNIT-SYSDA,
XX
SPACEm(~OO,(50,50J),DCB.BtKSIZE.~OO
XXSYSUT3
DO UNIT-SYSDA,SPACE=(SO,(250,250)),DCe-BLKSIZE-SO
XXSYSUTI
DD UNIT.SYSOA,SPACE=(102~,(60,601"CONTIG),
XX
DCB-BLKSIZEc102~
IIPL1L.SYSIN DO *
JOB LOGGED ON AT IBM'S HURSLEY LABS
OS/360 MVT 18
IEF236I ALLOC. FOR J063PGEX PL1L
COLEEX
IEF2371 SYSPRINT UN ~91t
IEFZ371 SYSLIN
ON 3~2
IEF2371 SYSUT3
ON 343
lEFZ37I SYSUT1
ON 3~~
l-EFZ37I SYSIN
ON 290

VERSION 5.0

0002.0000
OOO~OOOO

*00060000
OOOSOOOO
00100000
*00120000

Note: The cataloged procedure
shown in this example is that
in use at the Hursley Laboratories,
and varies slightly from the
standard cataloged procedure
shown in Chapter 8.

001~0000

CLOCK=11.55.04

DATE"69.273

MACHINE=-J1

PAGE
10
DATE 69.273

OS/360 PL/I COMPILER (F)

PL/I F COMPILER OPTIONS SPECIFIED ARE AS

FOLLO~S--

L,E,A,X,M,S2,NT
THE COMPLETE LIST OF OPTIONS USED DURING THIS COMPILATION IS--

*OPTIONS IN EFFECT*
*OPTIONS IN EFFECT*
*OPTIONS IN EFFECT*

P1 z

EBCDIC
CHAR60
MACRO
SOURCE2
NOMACDCK
COMP
SOURCE
ATR
XREF
EXT REF
LIST
LOAD
NODECK
FLAGW
STMT
SI ZE=0090112
LINECNT=055
OPT=02
SORMGIN=(002,072,001)
NOEXTDIC
NEST
qPLI ST

EBCDIC,CHAR60,MACRC~SOURCE2,NOMACDCK,COMF,SOURCE,ATR,XREF,EXTREF,LIST,LOAD,

NODECK,FLAGW,STMT,SIZE=0090112,LINECNT=055,OPT=02,SORMGIN=(002,072.001),NOEXTDIC,
NEST ,OPLIST

PROC OPT IONS (MAIN) ;

COMPILE-TIME MACRO PROCESSOR
MACRO SOURCE2 LISTING
1
2
3
~

5
6

7
8
9

10
11

12
13
14
15
16
17
18
19
20

230

P1:

PR'OC OPT! ONS (MAl N) ;
IDCL AA CHAR, (Vl,V2,V3,V4) FIXED;
IAA-'IF ANS)COMP THEN WCRCS·"GREATER THAN";
ELSE IF ANSCOMP THEN WORDS·'GREATER THAN';
ELSE IF ANSCOMP THEN WORDS='GREATER THAN';
ELSE IF ANS,.E

LOCAT ION

1 HECNCA

908

I HEOOB/>

C60

IHEOOBB

C62

IHEDOBC

C64

I HE IOBA
I HEIOBE

DA8
DC8

IHEIOBB
IHEIOBT

DBO
EB4

IHE IOBC

DB8

IHEICBO

DCO

I HESAOA
I HESAPB
I HESAFC
I HESARA
IHESAFF

F90
FC2
FE2
1002
lLBEE

IHE SAPC
IHESADF
IHESAFA
IHESAFQ

FAA
FCA
FEA
100A

IHESAPO
lliESADB
IHESAFB
I HE SARC

FB2
F02
FF2
17C6

IHESI>PA
IHESI>OE
IHES/>Fo
IHESADo

FBA
FDA
FFA
1864

IHEITAZ

lODE

IHEITAX

IDEA

IHEERRA

2616

IHEOCLD

31 BE

I HEOMAA

:LA48

IHEIOFB
I HE IT AA

:LB40
10FE

IHE IDFA

1B42

IHEPRTA

lE20

IHEPRTB

1E22

IHEVPBA

.lOE8

IHEVPFA

2290

I HEVQCA

22EO

IHEVSCA

2548

IHEERRD
IHEERRE

25F8
.2C8E

IHEERRC

2602

IHEERRB

260C

I HE IODG

2028

IHE l'OoP

2DZA

IHEIODT

2E22

IHEIOPA

.lFC8

I HE IOPB

2FCA

I HE IOPC

2FCE

IHECCLA

31 B8

IHEOCLB

31BA

IHEOCLC

31BC

IHEBEGN

3710

I HE BEGA

3750

I HESIZE

:3790

IHETABS

37AO

AC

IHEERR

IHECCL

NAME

AB8

1E20

2548

SEG. NO.

554

3710

80

3790

C

37AO

C

37BO
37B8
37CO

2
2
3C

1
1
1

@

LOCATION
34
354
35C
380
388
390
360
39C
3A4
414
420
42C
438
461
488
4F8
500
51D
524
52C
508
538
540
570
66C
674
678
690
9BC
9C4
9CC
C40
C48
C50
D88
090
D98
OAO
F6C
F68
F84
UFO
196C
1974
19F8
lAOO
lA38
lA40
1AB4
1ACO
lAC8
lA~O

REFERS TO SYMBOL
*****PIA
IHESAOB
PI
IHEOOOC
IHEOOBB
IHEIGBT
IHESAFA
ANS
P3
IHESPRT
IHESPRT
IHESPRT
IHESPRT
COMP
PI
IHESADA
P2
P2
P2
IHEIOBT
IHESAFA
ANS
IHESPRT
P2
IHESADB
P3
I HESAFA
COMP
IHELDOC
IHEDDPA
lHEOOPC
IHEDMAA
IHEVSCA
IHEVQCA
IHEIODP
IHEONCIl
IHEVSEA
IHEVSFA
IHEIOPA
IHEIOPC
IHEERRB
IHEERRA
IHEOCLO
I HEBEGA
IHEERRB
IHETABS
IHEPRTA
IHEDOOD
IHEVFBA
IHEVFAA
IHEVKGA
lHEVKFA

IN CONTROL SECTION
*****PlA
I HES ~P
PI
IHEOCO
IHEOOB
IHElCB
lHESAP
ANS
P3
I HES PRT
IHESPRl
IHES PRT
IHESPRT
COMP
PI
IHESAP
P2
P2
P2
IHEIGB
IHESAP
ANS
IHESPRT
P2
IHESAP
P3
IHESAP
CGMP
IHELlJO
$NEVER-CALL
$NEVER-CALL
IHEOMA
IHEVSC
IHEVQC
IHEIGD
IHEONC
$NEVER-CALL
$NEVER-CALL
IHEIGP
IHEIOP
IhEERR
IHEERR
lHEOCL
IHEBEG
IHEERR
I HET AB
IHEPRT
IHEDDO
$NEVER-CALL
$NEVE R-CALL
$NEVE R-CALL
$NEVER-CALL

SEG. NO.
I
I
1
1
1
1
1
1
3
1
1
1
1
1
I
I
2
2
2
I
I
1
1
2

I
3
1
1
2
1
1
1
1

1
I
1
1
1
1
1
1
1
1
1

LOCAT ION
350
358
37C
384
38C
394
398
3AO
3A8
418
424
430
43C
479
498
4FC
504
520
528
530
534
53C
56C
668
670
688
68C
9B8
9CO
9C8
900
C44
C4C
D84
08C
094
D9C
F60
F64
F70
F88
194C
1970
19F4
19FC
1A04
1A3C
1A44
1AB8
lAC4
lACC
1AD4

REFERS TC SYMBOL
IHE SAOA
PI
PI
IHEOOOA
IHEDOBB
IHEIOBC
COMP
P2
IHE SPRT
PI
PI
PI
PI
ANS
IHESAPC
IHESAOB
P2
P2
IHELDOB
I HE 10BC
IHESAFC
COMP
IHESPRT
IHESADA
P3
P3
ANS
IHEIOF,A
lHEPRTB
IHEDDPB
IHEDDPO
lHEUPAB
IHE VSEB
IHEERRC
IHEIODT
IHEVSCA
IHEVSBA
IHEIOPA
IHE IOPB
IHEOCLC
IHEERRC
IHEMAIN
IHESIZE
.IHEITAX
IHEERRC
IHEITAZ
IHEPRTB
IHEOCLC
lHEVFCA
IHEVPAA
lHEVPDA
IHE VPBA

IN CCNTRGL SECT ION

SEG. NO.

IHESAP
PI
PI
IHEOOO
IHEDCB
IHEICB
COMP
P2
IHESPR r
PI
PI
PI
PI
ANS
IHESAP
IHESAP
P2
P2
IHELDO
IHEIOB
IHESAP
COMP
IHESPRT
IHES~P

P3
P3
ANS
IHEIOF
IHEPRT
$NEVER-CALL
$NEVER-CALL
$NEVER-C ALL
$NEVER-CALL
IHEERR
IHEIOO
IHEVSC

I
1

@

1

1
1
1
1
2
1
1

1
1
1
I
I
1
2
2
2
I
1
1
I
1
3
3
1
1
1

1

1
1

$NEVER-C~LL

IHEIOP
IHEIOP
IHEOCL
IHEERR
IHEMAIN
IHESIZ
IHEIGF
IHEERR
IHEIOF
IHEPRT
IHEOCL
$ NE VE R-C IlLL

1
1

I
I
I
1
1
1
1
1
I

$NEVER-C~LL

$NEVER-CIlLL
IHEVPB

Appendix A: Programming

1

Exampl~s

245

LOCATION

REFERS TO SYMBOL

lA08
lB08
1B14
lB1C
1B24
lElO
20B8
2268
2430
24DO
2C04
2COC
2FBO
2FB8
319C
36EC
36F8
LOCH ION

IHEVPCA
IHEVFEA
IHEVPGA

IN CONTROL SECT ION

CONTROL SECTION
NAME
P2
IHE LOO

*

LENGTH

3800
39CO

1BA
418

SEG. NO.

NAME

IN CONTROL SECTION

*****P2A
IHEERRC
IHEVSBA
IHEONCA

P3

LOCATI ON

246

IN CONTROL SECTION

IHE \/FuA
lliEVPIiA
IHE VKCA
IHEVKBA
IHEERRB
IHEOCLA
IHESPRT
IHEERRB
IHEERRC
IHEVSCA
IHEM91B
IHETERA
IHEERRB
IHEIOFA
IHEERRC
IHEERRB

SNEVER-CALL
SNEVER-CALL
SNEVER-CALL
SNE VER-C AL L
IHEERR
IHEOCL
IHESPRT
IHEERR
IHEERR
lliEVSC
$NEVER-CALL
$NE VER-C ALL
IHEERR
IHEICF
IIiEERR
IHEERR

SEG. NO.

1
1
1
1
1
1
1
1
1
1

NAME

LOCAT ION

NAME

LOCATION

NA,...E

LOCAT ION

39CO
SEG. NO.

IHELDOB
LCCAT ION

39C2

IHELCOC

REFERS TO SYMBOL

38B8
'30C8
3000

39C6
IN CONTROL SECTION

*****P2A
IHE I OFA
IHEVSCA

*****P2 A
IHEICF
IHEVSC

SEG. NC.
1
1
1

E I\T RY

ORIGIN

L ENGT Ii

3800

F6

SEG. NO.

REFERS TO SYMBOL

380C
PSEUCO REGISTERS

LOCATION

*****P2A
IHEERR
$NEVER-CALL
IHEONC

CONTROL SECTION
NAME

REFERS TO SYMBOL

lB04
1 B10
1B1B
1820
1EOC
20B4
20BC
2278
2484
2524
2CD8
2000
2FB4
3198
31AO
3l:F4

2
2

RE FE RS TO SYMBOL

380C
30C4
30CC
30D4

1
1
1
1
1
LEt-.GTH

LOCATI CN

ENTRY

ORIGIN

I HELOOA
LOCATI ON

SEG. NC.

Sf';E:VE R-CALL
SNE VE R-CAL L
SNEVE R-CALL
IHEVPF~
IHEVPF
IHEVPEA
SNEVER-CALL
IHEERRC
lliEE RR
IHEIOFA
IHEIOF
IHEERRC
lliEERR
$NEVER-CA'LL
IHEVSEB
IHEERRB
IHEE RR
IHEM9lA
$NEVER-CALL
$NEVER-CALL
IHEM91C
IHEIOFA
IHEICF
IHEERRC
IIiEE RR
IHEERRB
IHEERR
IHEIOFA
IHEIOF
IHEERRC
IHEERR
8 REQUESTS CUMULATIVE PSEUDO REGISTER

*****P3A

NAME

IN CONTROL SECT ION
*****P3A

LOCATION

SEG. NO.

NAME

LOCATION

LOCA TI ON

NAME

REFERS TO SYMBOL

LOCATION

NAME

IN CONTRCL SECTION

LOCAT ION

SEG. NO.

@

NAME
IHEQINV
IHEQSPR
*****P2B
IHEQCFL
IHEQLW2
IHEQLCA
IHEQSAR
IHEQEVT

ORIGIN

LENGTH

00
10
20
30

4
4
4
8
4

~4

54
64
78

It

4
8

NAME
IHEQERR
IHEQLWF
*****P2C
IHEQADC
IHEQLW3
IHEQVDA
IHEQRTC

TOTAL LENGTH OF PSEUDO REGISTERS
ENTRY ADDRESS
490
TOTAL LENGT H
3008
****GO

ORIGIN

LENGTH

4
14
24
38
48
58
68

4
4
4
4
4
4
4

NAME

ORIGIN

LENGTH

8
18
28
3C
4C
5C
6e

4
4
4
4
4

IHEQTIC
IHEQSLA
*****P3B
IHEQLSA
IHEQLW4
IHEQ.FVD
IHEQSFC

It
It

NAME
*****Pl B
IHEQLWO
IHEQFOP
IHEQLWl
IHEQLWE
IHE'LPR
IHEQXLV

OR IGIN

LENGTH

C
lC
2C
40
50
60
70

4
4
4
4
4

@

It

8

. 80

DOES NOT EXIST BUT HAS BEEN ACDEC TO DATA SET
DIAGNOSTIC MESSAGE 01 RECTORY

IEW046:l WARNINr. - SYMBOL PRINTED IS AN

U~RESCLVED

EXTERNAL REFERENCE, NCAL WAS SPECIFIED.

lEF21l5I
SYS1.PLl LIB
KEPT
IEF285I
VOL SER NOS= 2301CO.
IEf285I
SYS69273.T115427.RVOOO.J063PGEX.GOSET
PASSED
IEF285I
VOL SER NOS= 231422.
IEF285I
SYS692i3.T115427.RVOOO.J063PGEX.ROOOC013
DELETED
IEF285I
VOL SER NOS= 231423.
IEF285I
SYS69273.T115427.SVOOO.J063PGEX.R0000014
SYSOUT
IEF2851
VOL SER NOS= M65293.
IEF2851
SYS69273.T115427.RVOOO.J063PGEX.LOACSET
DELETED
IEF2851
VOL SER NOS= 231422.
IEF2851
SYS69273.Tl15427.RVOOO.J063PGEX.SC000015
SYSIN
IEF2851
VOL SER NOS= 'M65295.
IEF285I
SYS69273.Tl15427.RVOOO.J063PGEX.SC000015
DELETED
IEF285I
VOL SER NCS= M65295.
END OF STEP 'LKEC
JOB 'J063PGEX'
STEPTIME=00.00.02 CLOCK=11.57.14
XX GO
EXEC PGM=*.LKED.SYSLMOD,COND=((9,LT,LKEDI ,(16,EQ~PL1LI),
*00340000
XX
REGICN=108K
00360000
XXSYSPRINT DC SYSOUT=A
00380000
I EF2361 ALLOC. FOR J063PGEX GO
CCLEEX
IEF2371 PGM=*.DD eN 342
IEF2371 SYSPRINT ON 294

DATE=69.273

RETUR~

CODE=0004

Appendix A: Programming Examples

247

ANS- 2.0
COMPANSWER GREATER THAN CCMPARATOR
ANS= 0.2
COMP=
ANSWER LESS THAN CCMPARATOR
NEXT COMMENT INvALID
ANS= 0.0
COMP=
ANSWER EQUAL TC CCMFARATOR
ANS: 0.0
COMP=
ANSWER EQUAL TG CCMPARATOR
ANS= 1.0
COMP=
ANSwER EQUAL TO CCMPARATOR
ANS= 1.0
COMP=
ANSWER EQUAL TC CCfrmed if the job step terminates
abnprmally.
If in the event of abnormal termination
you wish to have a data set cataloged,
code:

apply if a 'STEP WAS NOT EXECUTED' message
is given, either due to a JCL error or a
condition code setting.

Id~ntifying

the Data Set (DSNAME)

The DSNAME parameter identifies the data
set to which the DO statement refers. You
need not code this parameter if the data
set is te~porary or resides on a
unit.-record device or on an unlabeled
magnetic tape; the system automatically
assigns a temporary name. You can specify
the DSNAME parameter in one of three ways:
1.

r---------------------------------------,

IL _____DISP=(status,disposition,CATLG)
.__________________________________ JI

To name or retrieve a data set that
will be identified in later jobs by
name, or that was assigned a name in
an earlier job or job step, code:

r----------------------------------,
I
OSNAME= ds name
I
L __________________________________ J

'status' and 'disposition' show the status
and disposition of the data set at normal
end of job, as discussed above.

The word DSNAME can be abbreviated to
OSN. Replace 'dsname' with the
cataloged or tabulated name of the
data set. If the catalog has more
than one level of index, you must give
a fully qualified name (e.g.,
1\..B.LINKFILE).

If in the event of abnormal termination
you wish to uncatalog a data set, code:

r----·----------------------------------,
I
I

L ____________________________
~ __________ J
DISP=(OLD,disposition,UNCATLG)

If the DO statement refers to a
particular generation of a generation
data group, you must code the
generation number in parentheses,
i.e., DSNAME=dsname(number).

'Disposition' refers to the disposition you
want made of the data set upon normal
termina·tion of the job step.
If in the event of abnormal termination
you wish a data set to be deleted, code:

If the DD statement refers to a member
of a partitioned data set, you must
code the member name in parentheses
after dsname, i.e.,
DSNAME=dsname(membername).

r-----'---------------------------------,

IL _____
DI:8P=
(status, disposition,
DELETE)
,______________
- - - - - -______________
JI

If the DO statement is one of a group
of DO statements that detine an
INDEXED data set, you must code one of
the terms INDEX, PRIME, or OVFLOW in
parentheses after dsname (e.g.,
DSNAME=dsname(PRIME».

If in the event of abnormal termination
you wish a data set to be kept, code:

Ir---------------------------------------,I

L _______________________________________
J
DISP=(status, disposition, KEEP)

The second subparameter can be omitted.
If you code

Ir---------------------------------------,
OISP=(OLD"DELETE)
I

2.

To obtain the data set name from an
earlier DO statement~ code:

r----------------------------------,

JI
IL __________________________________
DSNAME=*.stepname.ddname

L _____ •__________________________________ J

the default for the second subparameter
follows the rule established above.
The third (conditional disposition)
subparameter applies only if the job step
is terminated abnormally. It does n2~

Replace 'stepname' and 'ddname' with
the job step name and DD statement
name, respectively, where the data set
was first defined.

~

If the earlier 00 statement is
contained in a cataloged procedure
AppendiK B: Parameters of 00 Statement

255

step, you must include the procedure
step name, i.e.,
DSNAME=*.stepname4procstepname.ddname.
3.

A data set that exists only within the
boundaries of a job can be assigned
any temporary name. To assign a
temporary name, code:

r----------------------------------,

IL_______________________
DSNAME=&&name .____ •_______ JI
Replace 'name' with any name of not
more than eight characters not used by
another temporary data set in the job
(e.g., DSNAME=&&TEMPDSET). The system
replaces the &&nam'e wit.h a name of the
form 'jobname.dsname'.
If the DD statement refers to a member
of a temporary partitioned data set,
you must code the member name in
parentheses, i.e.,
DSNAME='&name(membername).
If the DD statement is one of a group
of DD statements that define a
temporary INDEXED data set, you must
code one of the terms INDEX, PRIME, or
OVFLOW in parentheses after the &&name
(e.g., DSNAME=&&nameCPRIME».

Data Set Label CLABEL)
Magnetic-tape volumes can contain standard
or nonstandard volume labels and data set
header and trailer labels, or they may have
no labels at all. Direct-access devices
have standard labels. The LABEL parameter
indicates the position of a data set
· relative to the other data sets on a tape
· reel, and the type of labels; it can also
specify the retention period for a data set
· on magnetic tape or direct-access device,
and whether a password is required before
it can be accessed. Only the sequence
number and label type are described here.

To create or retrieve a data set that
does not have standard labels, you must
include the LABEL parameter. To specify
the type of labels, code:

r---------------------------------------,

IL _______________________________________
I.ABEL= (, t y p e ) .
JI
Replace 'type' with:
SL

- if the data set has standard
labels

NL

- if the data set has no labels

NSL - if the data set has nonstandard
labels
SUL - if the data set has both standard
and user labels
BLP - to bypass label processing
If you specify SUL, SL, or omit the
label type (in which case standard labels
are assumed), the operating system will
ensure that the correct volumes are
mounted. If you specify NSL, your
installation must have incorporated label
processing routines into the operating
system.
If you specify NL, the data set
must have no labels.
(Specifying NL for an
output data set on a labeled volume can
cause the volume label to be erased.)
The feature that allows you to bypass
label processing is a system generation
option (OPTIONS=BYLABEL).
If this option
was not requested at system generation and
you have coded BLP, the system assumed NL.
Note that the two L~BEL subparameters
are positional.
(If you omit the first,
indicate its absence by placing a comma in
front of the second.)

Optimizing Channel Usage (SEP and AFF)
For a magnetic-tape volume, if a data
set !s not first in sequence on the reel,
the LABEL parameter must include a data set
sequence number to position the tape
properly. The sequence number describes
the position of the data set relative to
other data sets on the volume or group of
volumes. Code:

r----------------------------------------,

IL________________________________________
LABEL=seq#
JI
Replace 'seq#1 with the sequence n,~er
(1-4 decimal digits) of the data set on the
reel.

256

A job step that requires several input and
output operations might be performed more
efficiently by balancing the channel
requirements of its data sets.
To obtain
optimum channel usage, you can request that
a data set be assigned a separate channel
from the ones assigned to earlier data
sets. ~ later DO statement can express the
same separation requirements by requesting
affinity.
TO request channel separation from as
many as eight other data sets in the job
step, code:

r-----·----------------------------------,

I

I

SEP=(ddname, ••• ,ddname)
L _____ ._________________________________
J
Replace 'ddname' with the names of up to
eight earlier DO statements in the job
step.

To obviate writing identical SEP
for different data sets, you can
request affinity with an earlier data set
that re~uested channel separation by coding
paramet'E~rs

whichever is most convenient. In the last
case the system will compute the number of
tracks or cylinders required. To allocate
space using this technique, code:

r---------------------------------------,

IL_______________________________________
SPACE=(units,quantity)
JI
Replace 'units' with:
TRK - if you want space in tracks

r-----'"---------------------------------,

CYL - if you want space in cylinders

IL _____,"__________________________________
AFF=ddname
JI
in a later DO statement. Replace 'ddname'
with the name of the earlier DD statement.
The data set that requests affinity is also
allocated a separate channel from those
identified in the SEP parameter of the
earlier statement (but not necessarily the
same channel as the data set to which the
SEP parameter referred).

Average block length in bytes - if you
want space in terms of blocks
Replace 'quantity' with the. amount of space
you need in the units you have chosen
(e.g., SPACE=(TRK,200) for 200 tracks,
SPACE=(CYL,10) for ten cylinders, and
SPACE=(400,100) for 100 blocks with an
average length of 400 bytes).
Notes:

The operating system will comply with
your requests for separation and affinity
only if enough channels are available.
Note: Do not confuse the SEP and AFF
parameters with the subparameters SEP and
AFF of the UNIT parameter.

1.

For most efficient performance,
request space in units of cylinders
(CYL), or in units of blocks with the
ROUND subparameter.

2.

The average block length cannot exceed
65,535 bytes.

3.

If you request space in units of
blocks, and the blocks have keys, you
should specify an average block
requirement which includes the key.

4.

Space allocation by blocks allows
device independence.

Allocating Direct-Access Space (SPACE,
SPLIT, and SUBALLOC)
When creating a new data set on a
direct-access volume, you must indicate in
your DO statement how much space the data
set will need. You can allocate space:
1.

By requesting the amount of space and
letting the system assign specific
tracks.

2.

By requesting specific tracks.

3.

By splitting cylinders with other data
se,·ts.

4.

By suballocating space from an earlier
da:ta set.

If the possibility exists that the data set
might at some time exceed the amount of
space you requested, you can ensure that
extra space will be made available by
denoting an incremental 'quantity. Code:

r---------------------------------------,
I SPACE=(units,(quantity,increment»
I
L _______________________________________ J

The most frequently used technique of
space a,llocation allows you to specify the
amount of space you need and let the system
assign specific tracks. Options permit you
to specify the manner in which the space is
to be arranged, to release unused space,
and to request that the space begin and end
on cylinder boundaries.

Replace 'increment' with a decimal number.
Each time the data set exhausts its space,
additional space will be allocated on the
same volume in the amount of the increment.
For example, if you code
SPACE=(TRK,(200,10», the data set would be
initially allocated 200 tracks. If it
later exceeded 200 tracks, ten additional
tracks would be made available. This
incrementing by ten tracks would take place
each time the data set exhausted its total
space (up to a maximum of 15 times).

You can specify the amount of space in
units of tracks, cylinders, or blocks,

If the data set for which you are
allocating space has partitioned
Appendix B: Parameters of DD Statement

257

: organization, you must indicate the size of
:its directory in the SPACE parameter.
Code:

SUBALLOC parameter. Suballocation allows
you to place a number of data sets in
contiguous order on a direct-access device.

r-------------------------------------·--,

IL_______________________________________
SPACE=(units, (quantity"directory»
JI
Routing Data sets through an output Stream
(SYSOUT)
Replace 'directory' with the numbeI~ of
256-byte blocks in the directory. If you
wish to give an incremental quantity, code
SPACE=(units, (quantity, increment,
directory».
If the data set has INDEXED
organization, you can indicate the size of
its index in the SPACE parameter. Code::

r---------------------------------------,I

The operating system provides output
streams through which you can route data
sets destined for unit record devices. To
route a data set through any output stream,
code:

r---------------------------------------,

JI
IL _______________________________________
SYSOUT=x

I

L _______________________________________
J
SPACE=(units,(quantity"index»

;Replace 'index' with the size of the index,
'in cylinders.
If you do not allocate space
:for the index , the operating system will
'use part of the independent overflow area
'or prime data area for the cylinder and
:master indexes.
You cannot give an incremental quantity
for an INDEXED data set, but you can do so
for a REGIONAL data set only for SEQUENTIAL
'creation.

Replace 'x' with an alphabetic (A-Z) or
numeric (0-9) character. The character you
select specifies an output class and a
corresponding output stream.
(The computer
operator allocates ,the output classes; a
usual convention is that class A refers to
a printer and class B to a card punch.)
When using an operating system with PCP,
to route a data set through the output
stream that carries system messages, code:

r---------------------------------------,
IL_______________________________________
SYSOUT=A
I
J

you can release unused space when you
,have finished writing a data set by
'including the positional subparameter RLSE
'in the SPACE parameter. Code

r---------------------------------------,I

I

SPACE=(units,(quantities),RLSE)
L _______________________________________
J
,where 'quantities' represents 'quantity,
iincrement,directory' or 'quantity,
iincrement,index' as used above. RLSE
cannot be used with ISAM data sets.

The SPACE parameter also allows you to
request that the data set be placed on
contiguous tracks or cylinders, and to
place a data set in a specific position on
the volume.

You can also route both data sets and
system messages through the same output
stream when using a system with MFT or MVT.
To do this, you mus't specify in the SYSOUT
parameter the output class that you
selected for the MSGCLASS parameter in your
JOB statement.
Operating systems with MFT and MVT have
two additonal options for the SYSOUT
parameter. They allow you to name your own
special program to handle ouput operations,
and to select a specific type of output
form for a printed or punched data set.

g~cify!~g

When a job step involves one or more
data sets that have corresponding records,
,you can minimize access-arm movement by
using the SPLIT parameter instead of the
SPACE parameter. The SPLIT parameter
:requests that each data set be given a
:proportion of the tracks on every cylinder
'allocated, allowing access to corresponding
:records in the data sets without movement
of the access arm.
l>.nother method of obtaining
direct-access space is through the
technique of suballocation, using the
258

a Character Set (Ucs)

The Universal Character Set (UCS) parameter
allows you to have your output printed with
a specified character set on a printer with
the UCS feature. This character set is
selected from a library of the character
sets available at your installation; such a
library would only exist if your
installation had a UCS printer. Each
character set is held in the library as an
image of the appropriate subset of the
universal character set of 240 graphic
symbols. The selected image is loaded into

the UCS buffer of the control unit for the
printe'r, which must be equipped with the
appropriate print chain or train.

TO specify a required character set
code:

r----·-----------------------------------,

number (e.g., UNIT 2400-2). The following
are valid unit type numbers:
Tape Units
2400

2400 series 9-track magnetictape drive that can be allocated
to a data set written or to be
written with a density of BOO
bpi.

2400-1

2400 series magnetic-tape drive
with 7-track compatibility and
without data conversion.

2400-2

2400 series magnetic-tape drive
with 7-track compatibility and
data conversion.

2400-3

2400 series 9-track magnetictape drive that can be allocated
to a data set written or to be
written with a density of 1600
bpi.

2400-4

2400 series 9-track magnetictape drive having an BOO and 1600
bpi (density) capability.

IL ____ .__________________________________
UCS=character set code
JI
Replace 'character set code' with one of
the twelve identification codes for the IBM
standa.rd character sets or with a code for
your own character set. These codes must
be one, to four bytes long; those for the
PL/I character sets are:
PN

Alphameric (PL/I)

QNe

Alphameric (PL/I commercial)

QN

Alphameric (PL/I scientific)

If you. omit the UCS parameter when using a
with the UCS feature. there may be
a defa.ult character set for your
installation. If not. a message will be
put on. the console asking the operator to
specify a character set.

printe~r

other UCS features available allow you
to tra.nspose certain EBOle characters with
others, and to request the operator to
verify that the character set chosen is the
right one.

Regues~ting

a Unit (UNIT)

The UNIT parameter of the DO statement
allows you to specify information about the
input or output unites) used by a data set.
You ca.n identify a specific unit or group
of uni.ts by its address, its type number,
or its group name.
To identify a unit by its address. code:

r----'-----------------------------------,

IL ____,.___________________________________
UNIT=address
JI
Replace 'address' with the 3-byte address
of thE! unit (e.g., UNIT=lBO for channell,
control unit B., unit 0).
To identify a unit by its type number,
code:

r----·-----------------------------------,
UNIT=type
I
--.-----------------------------------J

I

L __

Replace 'type' with a valid unit type

Direct-Access Units
2301

2301 drum storage unit

2302

2302 disk storage drive

2303

2303 drum storage unit

2311

2311 disk storage drive

2314

2314 direct-access storage
facility

2321

Bin mounted on 2321 data cell
drive

Unit Record Equipment
1052

1052 printer keyboard

1403

1403 printer or 1404 printer
(continuous form only)

1442

1442 card read punch

1443

1443 printer

2501

2501 card reader

2520

2520 card read punch

2540

2540 card read punch (read feed)

2540-2

2540 card read punch (punch feed)

2671

2671 paper-tape reader

Appendix B: Parameters of DO statement

259

Graphic Units
1053

1053 model 4 printer

2250-1

2250 display unit, model 1

2250-3

2250 display unit, model 3

2260-1

2260 model 1 display station
(local attachment)

To identify volumes by their serial
numbers. code:

r----------------·-----------------------,
I
VOLUME=SER=(sern ••••• ser#)
JI
L ______________________________________

2260-2

2260 model 2 display station
(local attachment)

2280

2280 film recorder

2282

2282 film recorder/scanner

At system generation, your installation
can designate names for individual units or
collections of units (for example, to
classify collections of magnetic-tape and
direct-access units under the same name).
To identify such a group of units in a DO
statement. code:

r---------------------------------·-----,

IL______________________________________
UNIT=group
JI
Replace 'group' with a valid unit group
name (e.g., UNIT=TAPE).
If your
installation uses IBM-supplied cataloged
procedures, the following group names must
have been established at system generation:
±Y,pes of Devices
SYSSQ
SYSDA
SYSCP

There are two ways of requesting the
volumes used by an earlier data set. If
the data set is cataloged or passed. and
you wish to refer to it. code:

r---------------------------------------,

IL _____________________________________
VOLUME=REF=dsname
-_.JI
Replace 'dsname' with the name of the data
set. If the data set is not cataloged or
passed. and you wish to refer to the DO
statement that defines it, code:

r---------------------------------------,

IL_______________________________________
VOLUME=REF=*.stepname.ddname
JI

Magnetic tape. direct access
Direct access
Card punch

other subparameters of the UNIT
parameter allow you to specify the number
o·f units you need, defer mounting of
volumes until the da.ta set is opened. and
request that the data set not be retrieved
or stored by access mechanisms used by
certain other data sets.
Specifying Volume Information (VOLUME)
To request specific volumes. you can either
identify the volumes by their serial
numbers or use the volumes used by an
earlier data set in the job.

260

VOLUME can be abbreviated to VOL. Replace
'sern' with the serial numbers associated
with the volumes; a serial number may
consist of up to six characters. You must
use this form of the VOLUME parameter when
retrieving noncataloged data sets.
If only
one volume is involved. you can omit the
parentheses. i.e., code VOLUME=SER=ser#.

Replace 'stepname' and 'ddname' with the
name of the job step and DD statement where
the earlier data set is defined~ If the
earlier data set is part of a cataloged
procedure. you must include the procedure
step name, i.e.,
VOLUME=REF=*.stepname.procstepname.ddname.

Other subparameters of the VOLUME
parameter allow you to request private
volumes. request that private volumes
remain mounted until the end of the job.
select volumes when the data set resides on
more than one, and request more than one
nonspecific volume.

Appendix C: Versions of the PL/I (F) Compiler

This edition, Form C28-6594-6 of the PL/I
(F) Programmer's Guide, documents the fifth
version of the compiler with the
improvements incorporated for Release 19 of
the operating system.
Earlier versions are:
1st
2nd
3rd
4th
4th
5th

version:
version:
version:
version:
version,
version:

LIST/DATA-DIRECTED OUTPUT: ~lignment of
data on preset tab positions.
RECORD FORMAT: The use of
undefined-format source records.
, PAPER

Form C28-6594-0
Form C28-6594-1
Form C28-6594-2
Form C28-6594-3
release 17: Form C28-6594-4
Form C28-6594-5

The more important differences between
these versions of the compiler are listed
below. There then follows a statement
concerning the compatibility between
compiled code and library modules of
various versions.

T~PE:

Paper tape as input to the
compiler and object program.

OPERATORS: The operators ,> and ,<, and
their 48-character set equivalents
NG and NL.
QUALIFIED NAMES: The resolution of
apparently ambiguous name
qualification.
OBJECT PROGRAM LISTING: Double-column
format for the object program
listing.
OBJECT-TIME ERROR H~NDLING: Optional
inclusion of the statement number
in object-time diagnostic messages.

Chanqe~

at Second Version

Combination of SNAP output with
SYSTEM action for ON statements.

The most significant changes for the second
version of th.e compiler are:
RECORD I/O: The statements: READ, WRITE,
REWRITE, and DELETE.
The attributes: RECORD, UPDATE,
SEQUENTIAL, DIRECT, BACKWARDS,
BUFFERED, UNBUFFERED, and KEYED.

RECURSION ENVIRONMENTS: A change in the
interpretation of ENTRY parameters
and ON units in recursive contexts.
CATALOGED PROCEDURES: A new cataloged
procedure (PL1LFLG) for
link-editing and execution.

The ON-conditions: RECORD and KEY.
The built-in functions: ONFILE and
ONKEY.

Changes at Third Version

Note: The usage UPDATE SEQUENTIAL
was not supported except for
INDEXED data set organization.

The most significant changes for the third
version of the compiler are:

COMPILE-TIME PROCESSING: The compile-time
processing feature of PL/I.
COMPILER OPTIONS: Abbreviated names as
alternatives to the full names for
compi.ler options.
ARRA.Y INITIALIZATION: Initialization of
arrays of STATIC variables by means
of the INITIAL attribute.
STRE:AM I/O: The options PAGESIZE and
LINESIZE.

OBJECT PERFORMANCE: Changes in the object
code generated by the compiler will
result in considerable imprOVements
in the object-time performance.
The most significant improvements
are in the following areas: data
conversions, the SUBSTR function
and pseudo-variable, the INDEX
function, the UNSPEC function,
object-time error handling and
procedural housekeeping, and the
us e of GO TO label va'riabl es •
~RRAY

The ON-condition NAME.
~ppendix

INITIALIZATION: Initialization of
arrays of AUTOMATIC or CONTROLLED

C: Versions of the PL/I (F) Compiler

261

variables by means of the INITIAL
attribute.

AREA to AREA
POINTER/OFFSET to POINTER/OFFSET

UPDATE SEQUENTIAL: The use of UPDATE
SEQUENTIAL for CONSECUTIVE and
REGIONAL data set organizations.
ASYNCHRONOUS OPERATION: The EVENT option
on IIO statements, the COMPLETION
built-in function and
pseudo-variable, and the WAIT
statement.

Attributes:
AREA[(expression)]
BASEDCpointer)
OFFSETCbased-variable)
POINTER
REFERCidentifier)
Built-in functions:

BATCHED COMPILATION: The facility for
batched compilation of programs and
a new compiler option, OBJNM.
LINK-EDITING: A changed method of
link-editing library routines into
an object program, facilitating
both the link-editing of PLII
object modules from a library and
the use of overlay technique with
PLII object modules.
MIXED DEFINING: The severity of
diagnostic messages for defined
data of type different from the
type of the base is reduced from
terminal to error, permitting the
compilation of programs using mixed
defining.

AD DR
EMPTY
NULL
NULLO
Condition:
AREA
Operation:

-> in 60-character set

PT in 48-character set

ASYNCHRONOUS OPERATIONS AND MULTITASKING:
The following language is now
supported:
Statements and options:

Changes at Fourth Version
The most significent changes for the fourth
version of the compiler are:
LOCATE I/O AND LIST PROCESSING: The
following language is now
supported:
Statements and options:
READ FILECfilename)
SETCpointer-variable)
[KEYCexpression)IKEYTO
(character-string-variable)];

CALL statement with TASK, EVENT,
and PRIORITY options in any
combination
WAIT statement extended to allow
array names in the event list
DISPLAY statement with REPLY and
EVENT opt.ions
UNLOCK statement
NOLOCK option in READ statement
Assignment:
EVENT to EVENT
Attributes:

LOCATE based-variable
FILECfilename)
[SET(pointer-variable)]
[KEYFROMCexpression)];
REWRITE FILECfilename);
ALLOCATE based-variable
[inCarea-variable)]
(SETCpointer-variable)];
FREE based-variable
(INCarea-variable)]J
Assignment:
262

EVENT
EXCLUSIVE
TASK
Built-in functions/pseudo-variables:
COMPLETION
PRIORITY
STATUS
Mul titasking is supported by the
system
Multiprocessing

r1VT

DATi~

INTERCHANGE: The COBOL option in the
ENVIRONMENT attribute: the
ALIGNED/UNALIGNED attributes (for
FORTRAN data interchange).

ASSJ~MBLER

SUBROUTINES: A variable-length
argument list can be passed to
assembler subroutines invoked by a
PUI program.

STRING HANDLING: The STRINGRANGE
condition for use with SUBSTR: the
STRI~G function.
STR~~AM

I/O: LINESIZE, SKIP, and COLUMN in
non-PRINT files: PUT DATA with no
data list.

RECORD I/O: Some types of VARYING string
may be used with the INTO or FROM
options: the KEY option in the
DELETE statement is now optional.
The DELETE statement is now
supp0rted for INDEXED data sets
using SEQUENTIAL access. The new
ENVIRONMENT options (INDEXAREA,
NOWRITE, and REWIND) provide
improved performance.
COMPILER OPTIONS: SIZE and SORMGIN have
been changed, and four new options
(OPLIST, EXTDIC, MACDCR, and NEST)
have been 'added.

EVALUATION OF EXPRESSIONS:
priority is changed:
now comes before the
logical operators in
of priority.

The order of
concatenation
comparison and
the sequence

PL/I SORT: The operating system sort
program is available for use with
PL/I programs.
Note: In multitasking the action taken by
the conditions ERROR and FINISH, and the
statements .EXIT and STOP vary significantly
between the third and fourth versions. The
following descriptions refer to the fourth
version.
ERROR condition: if raised in a major
task, FINISH is raised: if in any
other task, that task is
terminated.
FINISH condition: execution of the
interrupted statement is resumed.
EXIT statement: causes immediate
termination of the task containing
this statement, and all tasks
attached by this task. If in a
major task, it has the same effect
as STOP.
STOP statement: raises FINISH and causes
immediate termination of the major
task and all subtasks.

COMl)ILE-TIME OPTIMIZATION:
Macro-processor concatenations are
improved.
Changes at Fourth Version, Release 17
OBJ:~CT

PROGRAM OPTIMIZATION: Constant
subscript and constant expression
evaluation; some instances of .
VARYING strings in assignment:
in-line code for some VARYING
string operations: prologue
optimization: in-line handling of
certain data conversions and some
bit-string assignments:
rounding-off (instead of
truncation) for E- and F-format
outptlt:dope vector initialization
impr9ved: optimization of some IF
statements

LIs/rING IMPROVEMENTS: More details in
attribute listings: aggregate
listing in alphabetical order:
sizes of the STATIC and program
control sections are given; the
size of each DSA is given;
statement number provided in
diagnost;i.c m~ssage for invalid
pictures; improvements in aggregate
length table for BASED items.
PROGRAM RESTARt,,: The operating system
checkpoint/restart facility is
available under PCP.

The most significant changes for the fourth
version at Release 17 are:
RECORD I/O: Spanned records (VS- or
VBS-format) can be specified to
span blocks.
Generic keys (GENKEY option) can be
specified to access groups of
records on an INDEXED data set.
PL/I SORT: User control or SORT ddnames
for multiple use of PL/I SORT
within a single job step is
provided.
MULTIPROCESSING: More than one PUI task
may be executed simultaneously by a
multiprocessing system.
PROGRAM RESTART: Improved
checkpoint/restart facilities are
supported by PCP and MVT systems.
CATALOGED PROCEDURES: Changes to some
condition codes and to the dsnames
for temporary data sets have been \

Appendix C: Versions of the PL/I (F) Compiler

263

incorporated into the PL/I
cataloged procedures.

Protection between tasks when
executing 'soft' code in a
multiprocessing environment
PRTY parameter in the EXEC
statement

Changes at Fourth Version, Release 18
PRIORITY pseudo-variable enables
priority of any task to be changed
The.most significant changes for the fourth
version at Release 18 are:
COMPILER STATISTICS: Additional
information is given in the listing
to facilitate the automatic
collection of statistics about the
use of the operating system.
DEDICATED WORKFILES: With the MVT control
program, a dedicated workfile can
be substituted for workspace data
sets.
LINKAGE LOADER: A new operating system
service program, the linkage
loader, can be used as an
alternative to the linkage editor.
CATALOGED PROCEDURES: Two new cataloged
procedures are introduced: P:L1LFCG
and PL1LFG; both for use with the
linkage loader.
MULTIPLE CONSOLE SUPPORT (MCS): Fo:r an
installation that has MCS, system
messages can be displayed on one or
more consoles.
MESSAGE LEVEL PARAMETER: The MSGLEVEL
parameter in the JOB stateme:nt can
have additional values.

OBJECT PROGRAM OPTIMIZATION: Optimization
of DO-loops for faster operations;
implementation of halfword binary;
some in-line conversions; improved
assignment code for fixed decimal
data; improved edit I/O for F- and
E-formats; improved register
allocation.
OBJECT PROGRAM TERMINATION: The specified
task asynchronous exit (STAE)
feature for abnormal terminations
in single and multitasking.
DATA SET DESCRIPTION: TRKOFL (track
overflow) and NCP (number of
channel programs) have been added
to the list of options in the
ENVIRONMENT attribute.
PROGRAM RESTART: The operati:ng system
checkpoint/restart facility is now
available under PCP, MFT, and MVT.
IMPROVED FLOATING-POINT ENGINEERING
CHANGE (IFPEC): Implementation of
this feature has produced increased
precision and faster execution for
computational subroutines.
DATA EDITING:
Built-in functions:

Changes at Fifth Version
The most significant changes for the fift.h
version are:
TELEPROCESSING: The following language is
now supported:
File attributes:
ENVIRONMENT Options: G(max.
length) R(max. length)
TRANSIENT

TRANSLATE
VERIFY
PL/I LIBRARY: Selected library modules
may now,be stored permanently in
main storage for MFT and MVT.
STRING HANDLING: STRING pseudo-variable.
FUNCTION REFERENCES: Mandatory RETURNS
attribute on PROCEDURE and ENTRY
statements.
BASED STRUCTURES: Improved precision for
FIXED BINARY data used with the
REFER option.

ON-conditions:
PENDING
ASYNCHRONOUS OPERATIONS AND MULTITASKING:
The following is now supported:
Task management:
264

CATALOGED PROCEDURES: New cataloged
procedures (PL1LFG and PL1LFCG):
dedicated ·workfiles.
ABBREVIATIONS: The following
abbreviations for file attribute
keywords are accepted:

Keyword
BUFFERED
EXCLUSIVE
SEQUENTIAL
UNBU~"FERED

Abbreviations

1.

Fixed binary variables with a
precision less than 16 are now aligned
on half word boundaries and are two
bytes long. Fixed binary variables
with a precision of 16 or more are
aligned. as before. on fullword
boundaries and are four bytes long.
Therefore. the boundary alignments
obtained in this version of the
compiler for fixed binary data with a
precis'ion of less than 16 may differ
from those obtained in a previous
version. Programs based on previous
versions may have to be recompiled if
they contain fixed binary data. or
make calls to modules IHESRT. IHEDUM.
IHESAR. and IHETSA. These modules
should have their fixed binary
arguments re-declared with a precision
greater than 15.

2.

A change to the multitasking support
in this version will provide faster
execution for the PL/I user in a
multiprocessing environment.
Re-compilation is not necessary:
re-link-edit is.

3.

If a function reference returns a
value. the entry-point name for the
function reference must be declared
with the RETURNS attribute. Programs
compiled by earlier versions of the
compiler without such a declaration
will generate a warning message.

4.

The restrictions on fixed binary
variables in the REFER option have now
been lifted. and such variables may be
fixed binary integer variables of any
precision. Both variables must be of
the same precision.

BUF
EXCL
SEQL
UNBUF

Changes at Fifth Version, Release 19
The mos·t significant changes for the fifth
version at Release 19 are:
In-stream procedure: Provision to test
programmer-written procedures as
in-stream procedures before being
placed in the procedure library.
Model 195 support: New compiler options
to support Model 195.
Step Ilbend facility: Enables system to
issue a STEP ABEND after an
abnormal termination from any task
when the termination is caused by
the ERROR condition, and no ERROR
on-unit is established.
Synta}c Check option: Provision made to
terminate compilation after the
syntax checking is completed.
conditional on the error severity
specified.
7 tra<::k tape default: Default changed
from 200 b.p.i •• to 800 b.p.i.

Changes at Fifth Version, Release 20
All chrulges at the fifth version for
Release 20
are minor changes resulting
from maintenance of the compiler and this
publicat.ion.

Compatil?ility between Different Versions of
the PL/j~ Library and compiled Code
Certain changes and improvements have been
made to PL/I. the compiler. and the library
between the five versions of the compiler.
As a result. certain incompatibilities have
unavoida.bly arisen between library modules
of the different versions." The purpose of
this compatibility statement is to make
clear to the user what incompatibilities
exist. and how the problems raised by them
can be overcome.
Sevelral changes in the fifth version
prevent this version from being completely
compatible with earlier versions:

Two definite compatibility statements
can be made about the compilers in general:
1.

compiled code from any version of the
compiler must always be executed using
a library of the same version or a
later version.

2.

Library modules of different versions
can be mixed only in the following
circumstances:
a.

All link-edited modules must be of
the same version as each other.
and

b.

All dynamically linked or loaded
modules must be of the same
version as each other and must be
of at least as late a version as
the link-edited modules.

Unless a user has link-edited PL/I
external procedures with modules from a
PL/I library and placed them in a private

Appendix C: Versions of the PL/I (F)

Comp~ler

265

library modules are present, then
every time a main program needs to use
the external procedure, it should be
link-edited with it. using INCLUDE
cards naming the library modules which
are to be replaced (i.e., all of them)
and an INCLUDE card naming the
external procedure itself.
(The
latter must be a separate card and it
must follow the INCLUDE card for the
library modules.) This will result in
the incorporation of the correct
later-version library modules and then
the external procedure itself. This
method is temporary.

library for future use with main programs
compiled by a later version of the
compiler, these incompatibilities should
cause no problems. Provided the user has
installed the latest compiler and library
components, all future link-editing
operations will result in the incorporation
of the correct library modules. If,
however, he has link-edited some of his
external procedures, then, if he intends to
use them in conjunction with a main program
containing later- version library modules,
he must remove the earlier-version library
modules from them.
Two methods may be employed to carry
this out, one temporary and the other
permanent:
1.

266

The linkage editor map for the
external procedure is examined to see
whether any library modules have been
incorporated in the load module; t.hese
can be identified by the initial
letters IHE.
If there are no library
modules present in the load module, no
further action is required. If

2.

The permanent method is to link-edit
the external procedure using the
replace facility on the NAME card.
In
other words, the linkage editor is
executed using the INCLUDE cards
naming the library modules which are
to be replaced, followed by an INCLUDE
card naming the external procedure,
followed by a NAME card naming the
external procedure with the replace
option.

Appendix D: System Requirements

Control Progra,m Options

Machine Requirements

Figure 1)-1 shows the control program
options which may be added in order to
provide greater performance and/or
programning flexibility for the various
features of PL/I. These exclude
input/output features.

The PL/I (F) compiler requires an IBM
System/360 Model 30 or higher with at least
64K bytes of main storage, of which at
least 44K bytes should be allocated to the
compiler by means of the SIZE compiler
option. The PL/I (F) compiler also
requires at least one direct-access device,
and an operator console.

r------------T'----------------------------,
Control Program Option2. I

I PL/I Ffeature I

~------.------+,----------------------------~

I WAIT
I
I Taskin«;r
I

I
I
I
I
ITIME, DATE I
I
I
ITlME, DATE, I
I DELAY
I

I
I
M\TT
I
I
Timing: A. Time
I
I
Timing: B. Interval timing I
I
Multiple WAIT

The use of certain operating system
features requires additional main storage
and resources. A table listing the minimum
requirements of such features is given
below (Figure 0-2).

~--_--._-----.L----------------------------"

I2.See tllle publication IBM Systeml360
I
I
I Opera·tinq System: .StoraqeEstimates
for further
details of these options.
IL ______
.___________________________________
JI
Figure :0-1.

Control Program Options

Appendix D: System Requirements

267

r------------------T-------------T-------------T-------------T'--------------------------,
,
Facilities
,
Control
IMain storage ,Systeml360,
Resources required
1
1

,

program

1

required

1

model

,

I

~------------------+-------------+-------------+-------------+-------------------------.-~

r
I

,
,

I

I
I
I

I
I

PCP

I

,

,
I

,
,

64K

1

30F

I
I

I
I

IBatched processing 1

,i.
I

I
I
I

I

I

central processing uni1t.1
Operator's console
,
Card reader punch
I
Direct-access storage I
device
I
printer
I

1

.-------------+-------------+-------------+--------------------------~

1

- ~---,-----,-----+-------------+-------------+-------------------------.-~
I
MVT
I
256K
I
40H
13. As for 1, with interval,

,

'MFT

I

,

,

I

128K

I

,

40G

I

1.2. As for 1
I

timer

I
I

~------------------+-------------+-------------~-------------~--------------------------~

Teleprocessing

1
PCP
I
Not available: QTAM requires MFT or MVT
I
~----·---------+·-------------T-------------T--------------------------~
,
,
,
14. As for 2, with
,
I
I
I
,
Direct-access storage I
I
I
1
,
device for message
I
,
MFT
I
128K
1
40G
I
queues
I
I
I (see Fig.O-3)I
I
Communication terminals I
,
,
,
I
with adapter or control I
units
I
,
I
I
I
~--------,-----+-------------+-------------+---------------------------~

I
I

MVT

I
256K
I
I (see Fig.D-3)I

40H
SOl

15. As for 4, with interval I
I

timer

I

.------------------+-------------+-------------~-------------~--------------------------i
I
I
PCP
I
Not available: ,MCS requires MFT or MVT
I

~-------------+------------T-------------T---------------------------~
IBatched processing,
MFl'
,
128K
I
40G
16. AS for 2, with up to 3:JLI
Iwith multiple
I
I
I
I
extra operator's
I
Iconsole support
,
I
I
I
consoles
I
, (MCS)
.-------------+--------------+------------+----------------------------i
I
I
MVT
. I
256K
,
40H
1"l.AS for 6
I

I

.----------------+-------------+--------------+-------------+---------------------------i
I Multiprocessing
I
I
,

I

18. As for 3 except that
I
,
two CPUs and two
I
,
,
,
operator's consoles
I
,
,
I
,
are required
I
~------------------~-------------~-------------~-------------~--------------------------·i
,Notes on resources:

I

I

MVT

I
I

2x256K

I
I
I

2x40H

11.

,

Direct-access storage devices for PCP, MFT, and MVT.

12.

Printer: 1403 and 1443, with chain (HN, PN, or QN) or bar (S2H or 63-character).

I

13.

I

14.

Character set: EBCDIC or USACII-8.
Operator's console: 1052 print:er keyboard model 7 (with dual case printing element)

I
with 2150 console or with 1052 adapter; composite consoles currently supported;
IL _______________________________________
2250 console; model 85 integrated operator's
console 220C.
.________________________________________________
.
Figure 0-2.

268

Minimum System Requirements

PCP (64K)

DYNAMIC

AREA

'--.---"'----' \.'--------.. . . r----------',
T

y

12 K

52 K

MFT (128K)

/
DYNAMIC

AREA

WRITER I

PARTITION
0"'-

V

POSSIBLY USED
FOR
TELEPROCESSING

32 K

50K

30K

16K

MVT ,(256K +)

,

/

J

I
I

AREA)
I

l I
"L--. _ _ _.....y,--____...J, \.\....-------..

POSSIBLY USED FOR TELEPROCESSING

REGION 0

WRITER I

WRITER 2

MASTER
SCHEDULER

(52 K)

Y

qOK
lAPPROX)

I04K

16K

16K

32K
(APPROX)

Note: the MFTand MVT diagram show the possible configurations with the teleprocessing
facili~f. As teleprocessing requires a minimum of two partitions or regions, the space
available in the dynamic area may not be sufficient w-ith the minimum configurati9n.
Figure ]0-3.

possible Minimum Configura"tions of Main storage

Appendix D: System Requirements

269

Appendix E:

PL/I Library Subroutines

The following list comprises all the library modules provided for Version 5 of the PL/I
(F) compiler. It gives the length in bytes of each module; and a brief description of
its function.
All the modules are resident in system libraries in auxiliary storage,
either in the PL/I subroutine library (SYS1.PL1LIB), or in the link library
(SYS1.LINKLIB). Those modules marked * reside in the link library.

Module

Length

IHEABN

12

IHEABU

184

ABS (complex fixed-point binary)

IHEABV

544

ABS (complex fixed-point decimal)

IHEABW

128

ABS (complex short floating-point)

IHEABZ

128

ABS (complex long floating-point)

IHEADD

216

ADD (real fixed-point decimal)

IHEADV

96

IHEAPD

360

Conversion (real fixed-point decimal)

IHEATL

536

ATAN and AT AND (real long

I HEATS

408

ATAN and ATA,ND (real short floating-point)

IHEATW

304

ATAN and ATANH (complex short floating-point)

IHEATZ

296

ATAN and ATANH (complex long floating-point)

IHEBEG

136

Messages to operator

IHEBSA

296

AND (byte-alignej bit strings)

IHEBSC

272

Comparison (byte-aligned bit strings)

IHEBSD

192

CompariBon (bit strings, any alignment)

IHEBSF

480

Boot

IHEBSI

296

INDEX (bit strings)

IHEBSK

472

Bit-string (assignment, concatenation, REPEAT)

IHEBSM

384

Bit-string (assignment, padding)

IHEBSN

192

NOT (byte-aligned bit string)

IHEBSO

312

OR (byte-aligned bit strings)

IHEBSS

240

SUBSTR (bit string)

IHEBST

512

TRANSLATE (bit string)

IHEBSV

408

VERIFY (bit string)

IHECFA

160

ONLOC

270

ABEND option

ADD (complex fixed-point decimal)

floating~point)

Length

*
*

*

Description

IHECFB

576

IHECFC

88

IHECKP

184

Checkpoint (CALL IHECKPT)

IHECLS

922

Closing files (Versions 1, 2, and 3 only)

IHECLT

1298

IHECNT

72

IHECSC

200

Comparison (two character strings)

IHECSI

168

INDEX (character string)

IHECSK

320

Character string (concatenation, REPEAT)

IHECSM

280

Character string (assignment, HIGH, LOW)

IHECSS

224

SUBSTR (character string)

IHECST

304

TRANSLATE (character string)

IHECSV

198

VERIFY (character string)

IHEC'rT

1718

IHEDBN

344

Conversion (bit string to arithmetic)

IHEDCN

495

Conversion (character string to arithmetic)

IHEDDI

1248

IHEDDJ

448

Array handling

IHEDDO

648

Data-directed output

IHEDDP

640

Array handling

IHEDDT

760

Data-directed output

IHEDIA

584

Edit-directed input

IHEDIB

280

Edit-directed input

IHEDID

448

Edit-directed input

IHEDIE

456

Edit-directed input

IHEDIL

48

Edit-directed input

IHEDIM

528

Edit-directed input

IHEDIMA

248

Conversion (arithmetic data)

IHEDNB

248

Conversion (arithmetic to bit string)

IHEDNC

632

Conversion (arithmetic to character string)

IHEDOA

224

Edit-directed output

IH~D()B

328

Edit-directed output

IHEDOD

296

Edit-directed output

ONCODE
ONCOUNT

Closing files
COUNT/LINENO

Closing files

Stream-oriented transmission

Appendix E: PL/I Library Subroutines

271

Module
IHEDOE

224

Edit-directed output

IHEDOM

584

Edit-directed output

IHEDSP

612

Messages to operator

IHEDUM

280

Main storage dump (CALL IHEDUMC, IHEDUMJ, IHEDUMP, IHEDUMT)

IHEDVU

408

DIVIDE (complex fixed-point binary)

IHEDW

576

DIV'IDE (comp1ed fixed-point decimal)

IHEDZW

104

Division (complex short floating-point)

IHEDZZ

104

Division (complex long floating-point)

IHEEFL

736

ERF, ERFC (real long floating-point)

IHEEFS

384

ERF, ERFC (real short floating-point)

*
*
*
*
*

IHEERD

720

Execution-time error messages

IHEERE

1704

Execution-time error messages

IHEERI

896

Execution-time error messages

IHEERN

4096

IHEERO

856

Execution-time error messages

*

IHEERP

1208

Execution-time error messages

IHEERR

1816

Error and interrupt handling

*
*

IHEERS

848

Execution-time messages (SNAP)

IHEERT

712

Execution-time error messages

*

IHEESM

1768

Execution-time messages (SNAP, CHECK)

*

IHEESS

1960

Execution-time messages (SNAP, CHECK: Version 2 only)

IHEEXL

456

EXP (real long floating-point)

IHEEXS

256

EXP (real short floating-point)

IHEEXW

136

EXP (complex short floating-point)

IHEEXZ

136

EXP (complex long floating-point)

IHEHTL

272

ATANH (real long floating-point)

IHEHTS

192

ATANH (real short f10atifig-point)

IHEIBT

576

stream-oriented output (PUT)

IHEIGT

1340

Record-oriented transmission (multitasking)

IHEINT

436

Record-o:rient.ed transmission (multitasking)

IHEIOA

360

Stream-oriented input (GET)

IHEIOB

480

Stream-oriented output (PUT)

IHEIOC

288

stream-oriented transmission (STRING)

272

Execution-time error messages (Versions 1 and 2 only)

Length

*

*
*
*
*
*
*
*
*
*
*
*

Description

IHEIOD

640

Edit-directed transmission

IHEIOE

176

Implicit OPEN (Versions 1,2,3 only)

IHEIOF

736

Stream-oriented input

IHEIOG

1104

IHEIOH

200

IHEIOJ

1992

IHEION

248

Record I/O transmitter

IHEIOP

488

PAGE option/format

IHEIOX

328

SKIP option

IHEI'rB

3772

BSAM/CONSECUTIVE or REGIONAL UNBUFFERED interface

IHEI'l~

2604

BSAM/REGIONAL SEQUENTIAL (output) interface

IHEI'I'D

2270

QISAM/INDEXED SEQUENTIAL interface

IHEI'rE

1760

BISAM/INDEXED DIRECT interface

IHErrF

1845

BDAM/REGIONAL DIRECT interface

IHEI'I'G

1122

QSAM/CONSECUTIVE RECORD BUFFERED interface

IHEI~I'H

2610

BISAM/I~DEXED

IHEI'I'J

2650

BDAM/REGIONAL DIRECT (multitasking) interface

IHEI~rK

622

QSAM/READ spanned records

IHEI'l"'L

492

QSAM/WRITE spanned records

IHErrp

874

QTAM/teleprocessing interface

IHEJXI

320

Initialize and address arrays

IHEJXS

104

Finds first and last elements of array

IHEKCA

1560

Checks decimal picture specifications

IHEKCB

1464

Checks sterling picture specifications

IHEKCD

256

IHELlDI

2072

List-directed input director

IHELOO

1048

List-directed output director

IHEL1~

360

LOG (x)

(real long floating-point)

IHELlNS

256

LOG (x)

(real short floating-point)

IHEVNW

268

LOG(z)

(complex short floating-point)

IHELlNZ

288

LOG(z)

(complex long floating-point)

IHEL:SP

1064

IHEM'91

344

Record-oriented transmission
BDAM/BISAM housekeeping (Version 2 only)
BSAM housekeeping (Versions 2,3 only)

DIRECT (multitasking) interface

Checks character picture specifications

List processing storage management
Model 91 execution-time error routines
Appendix E: PL/I Library subroutines

273

Module

Length

I HEMAl

8

lHEMPU

240

MULTIPLY (complex fixed binary)

IHEMPV

288

MU:LTIPLY (complex fixed decimal)

IHEMSI

32

'STIMER unavailable' message

IHEMST

32

'TIMER wlavailable' message

IHEMSW

136

IHEMXB

96

IHEMXD

120

MAX (real fixed-point decimal)

IHEMXL

96

MAX (real long floating-point)

IHEMXS

96

MAX (real short floating-point)

IHEMZU

240

Z1. *z:,a (c<:>mplex fixed-point binary

IHEMZV

672

z1.*z:,a (complex fixed-point decimal)

IHEMZW

64

z1.*z:,a (complex short

lHEMZZ

64

Z1.*z:,a (complex long floating-point)

IHENL1

280

ALL or ANY for simple array

IHENL2

192

ALL or ANY for interleaved array

IHEOCL

1338

Explicit/implicit open/close (non-multitasking)

IHEOCT

2190

Explicit/implicit open/close (multitasking)

* IHEOPN

920

Implicit/explicit open routine

* IHEOPO

1828

Implicit/explicit open routine

* IHEOPP

1874

Implicit/explicit open routine

* IHEOPQ

1296

Implicit/explicit open routine

* IHEOPZ

992

Format director: REGIONAL DIRECT output

lHEOSD

216

Obtain current date

IHEOSE

80

Terminate current task abnormally

lHEOSI

72

Invoke STIMER (with WAIT if required)

IHEOSS

56

Terminate job step abnormally

IHEOST

88

Obtain time of day

lHEOSW

1060

IHEPDF

144

IHEPDL

88

PROD (real long floating-point) interleaved array

IHEPDS

88

PROD (real short floating-point) interleaved array

IHEPDW

120

274

Addresses IHEBEG if no main procedure

I/O event counter (multitasking)
MAX (real fixed-point binary)

floating~point)

EVENT counter (non-multitasking)
PROD (real fixed-point binary/decimal) interleaved array

PROD (complex short floating-point) interleaved array

Length

Description

IHEPDX

272

PROD (complex binary or decimal) interleaved array

IHEPDZ

120

PROD (complex long floating-point) interleaved array

IHEPRT

656

COPY/error message via SYSPRINT

IHEPSF

160

PROD (real fixed-point binary/decimal) simple array

IHEPSL

72

PROD (real long floating-point) simple array

IHEPSS

72

PROD (real short floating-point) simple array

IHEPSW

96

PROD (complex short floating-point) simple array

IHEPSX

256

lHEPSZ

96

IHEPTT

768

COPY/error message via SYSPRINT (multitasking)

IHEFtES

100

Checkpoint/restart interface

IHESAP

2488

IHESHL

248

SINH (real long

IHESHS

192

SINH (real short floating-point)

IHESIZ

16

IHESMF

136

SUM (real binary or decimal) interleaved array

IHESMG

128

SUM (real short floating-point) interleaved array

IHESMH

128

SUM (real long floating-point) interleaved array

IHESMX

224

SUM (complex binary or decimal) interleaved array

IHESNL

416

SIN (real long

IHESNS

320

SIN (real short floating-point)

IHESNW

320

SIN (complex short floating-point)

IHESNZ

368

SIN (complex long floating-point)

IHESQL

160

SQRT (real long floating-point)

IHE8QS

168

SQRT (real short floating-point)

IHESQW

152

SQRT (complex short floating-point)

IHES:QZ

144

SQRT (complex long floating-point)

IHESRC

344

Passes data to condition functions

IHESRD

128

Passes data to ONKEY function

IHESRT

1348

IHESSF

168

SUM (real fixed-point binary/decimal) simple array

IHESSG

104

SUM (real short floating-point) simple array

IHESSH

104

SUM (real long floating-point) simple array

PROD (complex binary or decimal) simple array
PROD (complex long floating-point) simple array

storage management (non-multitasking)
\

floating~point)

Length of PRV in Register 1

floating-~oint)

Sort/merge interface

Appendix'E: PL/I Library Subroutines

275

Description

Module

Length

IHESSX

216

IHESTA

1124

Abnormal termination error message

IHESTG

1108

Length of structure string

IHESTP

1432

Assigns bit/character string to string pseudo-variable

IHESTR

1592

structure address and length

• IHESUB

16

Subtask initialization interface

I HE TAB

16

Default table for tabulation

IHETCV

208

Controlled variable storage (multitasking)

IHETEA

248

Event variable assignment

IHETER

272

ON-field search (multitasking)

IHETEV

240

COMPLETION pseudo-variable

IHETEX

1464

IHETHL

280

TANH (real long floating-point)

IHETHS

200

TANH (real short floating-point)

IHETNL

344

TAN (real. long floating-point)

IHETNS

272

TAN (real. short floating-point)

IHETNW

184

TAN (complex short floating-point)

IHETNZ

184

TAN (complex long floating-point)

• IHETOM

493

Operator messages

IHETPB

56

IHETPR

268

IHETSA

5720

IHETSE

88

Abnormally terminates current task

IHETSS

72

Terminates PL/I program abnormally (multitasking)

IHETSW

1520

IHEUPA

192

Complex data item

IHEUPB

232

Complex numeric field

IHEVCA

272

Defines attributes of arithmetic data in character form

IHEV'CS

480

Conversion director (complex data-string)

IHEVFA

232

Radix conversion: binary to decimal

IHEVFB

224

Conversion (long-float to fixed-point binary)

IHEVFC

40

Conversion (long-float to floating-point variable)

IHEVFD

88

Conversion (fixed-point binary to long floating-point)

*

276

SUM (complex fixed-point binary/decimal) simple array

Active task terminated message

PRIORITY built-in function
PRIORITY pseudo-variable
object program management (multitasking)

EVENT counter (multitasking)

Length

Description

IHEVFE

32

IHEVKB

736

Conversion (float-point decimal to packed decimal)

IHEVKC

720

Conversion (sterling to packed decimal)

IHEVKF

1504

Conversion (packed decimal to

IHEV.KG

1248

Conversion (packed decimal to sterling)

lHEV~PA

352

Conversion (packed decimal to long floating-point)

IHEVPB

408

Conversion (packed decimal to F-format)

IHEVPC

492

Conversion (packed decimal to E-format)

264

Conversion (packed decimal to decimal)

IHEVPE

616

Conversion (F-, E-format to packed decimal)

IHEVPF

72

IHEVPG

560

Conversion (binary fixed/floating-point to 10n9
floating-point)

IHEVPH

184

Conversion (bit string to long floating-point)

IHEVQA

208

Conversion (floating-point to binary)

IHEVQB

1004

IHEVQC

600

Conversion (coded arithmetic to F-. E-format/character string)

IHEVSA

320

Assignment (bit string to bit string)

IHEVSB

208

Conversion (bit string to character string)

IHEVSC

176

Assignment (character string to character string)

IHEVSD

416

Conversion (character string to bit string)

IHEVSE

352

Assignment (character string to picture string)

IHEVBF

240

conversion (bit string to picture string)

IHEVTB

136

Float-point table for conversions

IHEXIB

88

IHEXID

136

X**n (decimal to integer)

IHEXIL

152

X**n (long floating-point to integer)

IHF.XIS

152

X**n (short floating-point to integer)

IHEXIU

120

Z**n (complex binary to integer)

lHEXIV

192

Z**n (complex decimal to integer)

IHEXIW

256

Z**n (complex short floating-point to integer)

IHEXIZ

256

Z**n (complex long floating-point to integer)

lHEXXL

152

x**y (long floating-point)

IHEXXS

144

x**y (short floating-point)

Conversion (float-point to long floating-point)

fixed/floating~point)

Conversion (decimal to packed decimal)

Conversion (decimal constant to coded arithmetic)

X**n (binary to integer)

Appendix E: PL/I Library subroutines

277

Module

Length

IHEXXW

280

Z~**Z2

(complex short floating-point)

IHEXXZ

280

Z~**Z2

(complex long floating-point)

IHEYGF

432

POLY (binary or decimal)

lHEYGL

240

POLY (long floating-point)

IHEYGS

240

POLY (short floating-point)

IHEYGW

280

POLY (complex short floating-point)

IHEYGX

688

POLY (complex binary or decimal)

IHEYGZ

280

POLY (complex long floating-point)

* IHEZZA

1296

SNAP dump index (I)

* IHEZZB

1704

SNAP dump index (II)

* IHEZZC

2960

SNAP dump cont.rol routine

* IHEZZF

1596

Save-area trace for SNAP

278

Qescr!.Etion

(Version 3 only)
(Version 3 only)

Appendix F: Shared Library

Introduction

1.

The sheared library feature enables certain
presel1ected PL/I subroutine library modules
to be ishared between two or more PL/I
progralrklS being executed under the control
of an l~T or MVT control program of the
operat:ing system.

By using standard IBM-supplied
cataloged procedures and overriding
the link-edit and loader job steps.

2.

By providing your own cataloged
procedures.

The presel~cted group of modules is made
resident in main storage (in the resident
access method area for MFT" and in the
link-pi:tck area for MVT).
To create a shared library you must
specify the modules that you require when
you generate your operating 'system. You do
this by means of a system generation macro
instruction. The system generation process
will link-edit these modules together with
a tranl3fer vector module, into a load
module which is given the entry-point name
IHELTV1\, and stored in auxiliary storage in
the link library, SYS1.LINKLIB.
The load module can be subsequently
loaded permanently into main storage during
initial program load. This load module is
a reent.rant load module and your
installation must be able to make this type
of module resident during initial program
load1..
To .:!xecute a PL/I program using the
shared library, you must ensure that a
dummy t.ransfer vector module is link-edited
to YOUJc program in order to resolve all
references to the shared library modules.
You do this by specifying the entry-point
name IHELTTA for your PL/I program. This
dummy 1:.ransfer vector module is also
created during system generation and is
also stored in auxiliary storage in the
PL/I subroutine library, SYS1.PL1LIB.

You can use the shared library by either of
two me1:.hods:
1.For mc)re information on making reentrant
load modules resident during initial
program load refer to IBM System/360
Operating System: System Generation, and
IBM "SYBtem/360 Operating system: system
Programmer's ,Guide.

These methods and their required coding are
described below.

How to Create a Shared Library
The PL1LIB System Generation Macro
Instruction
To create a shared library, you must
specify the modules that you require when
you generate your operating system. You do
this by means of a system generation macro
instruction, PL1LIB2.
To facilitate selection of modules
required for your shared library, the PL/I
subroutine library modules have been
divided into 36 groups. Each group
comprises modules that have associated
functions, as shown in Figure F-1.
You cannot specify modules in Group 1
because these are housekeeping, string
function, or stream input/output modules
that cannot be used in a shared library;
they are termed 'non-shareable' modules.
Group 2 modules will be included
automatically during system generation if
you have specified a multitasking shared
library, or group 3 modules if you have
specified a non-multitasking shared
library.
You can specify any of the remaining
groups (Groups 4 through 36) in any
combination to form a shared library to fit
your needs. You should specify only
frequently used groups of modules to make
best use of the shared library feature.
2 For more information on the PL1LIB macro
instruction refer to IBM System/360
Operating system: system Generation

Appendix F: Shared Library Cataloged Procedures

279

r-------T----------------------------------------------,
I GROUP I
MAIN FUNCTIONS OF GROUP
I
~-------+----------------------------------------------~
1
Non-shareable modules
2
Multitasking storage management
3
Non-multitasking storage mangement
4
Error handling (ON-units)
5
List processing and struc·ture mapping
6
Basic conversion package
7
Edit conversions
8
Complex conversions
9
Bit-string conversions
10
Character-string conversions
11
Picture conversions
12
Sterling conversions
13
optimization=l special conversions
14
Bit-string built-in functions
15
Character-string built-in functions
16
STRING built-in function and pseudo-variable
17
Real non-interleaved arrays
18
Real interleaved arrays
19
Complex non-interleaved arrays
20
Complex interleaved arrays
21
Real arithmetic operators
22
Complex arithmetic operators
23
Real short arithmetic built-in functions
24
Real long arithmetic built-in functions
25
Complex short artihmetic built-in functions
26
Complex long arithmetic built-in functions
27
Non-multitasking data-directed I/O
28
Non-multitasking list-directed I/O
29
Non-multitasking edit-directed I/O
30
Multitasking data-directed I/O
31
Multitasking list-directed I/O
32
Multitasking edit-directed I/O
33
Non-multitasking record I/O
34
Multitasking record I/O
35
Non-multitasking record I/O wait
36
Multitasking record I/O wait
_______
i _____________________________________________
_

Figure F-l.

Shared-Library Module Groups

IEBUPDTE~ utility program; the method of
specifying its use by the system is given
in the following paragraph. For
illustration purposes, the ~xample has been
given the user list name IEAIGG01.

Initial Program Load (IPL)

//BLDLIST EXEC
//SYSPRINT DD
DD
//SYSUT2

Once created, your shared library load
module is given the entry-point name
IHELTVA and is stored in auxiliary storage
in the link library, SYS1.LINKLIB. To
store this load module permanently in main
storage you must first build a new
reentrant load module user list for it in
the parameter library, SYS1.PARMLIB; and
second, you must ensure that the use of
this list by the system is specified during
initial program load. You can give this
user list a name of the form IEAIGGxx,
where xx are any two digits other than 00.
The following example of coding suggests
how you create such a list by means of the

//
//
//

280

PGM=IEBUPDTE,PARM=NEW
SYSOUT=A
DSN=SYS1.PARMLIB,
UNIT=2314,
VOL=(,RETAIN,SER=MVTll1),
DISP=OLD

DD
*
ADD
NAME=IEAIGG01,LIST=ALL
NUMBER NEW=01,INCR=02
SYS1.LINKLIB IHELTVA
ENDUP

//SYSIN
./
./
./
/*

~For more information about the IBM utility
program IEBUPDTE refer to IBM System/360
Operating system: U·tilities

The AD)) statement identifies your shared
librar~{ load module, IHELTVA, in the new
reentrclnt load module list (IEAIGG01).:I.
When the nucleus initialization program
(NIP) J::equests the system parameters, the
operator reponds by specifying 'RAM=Ol'
(the digits 01 correspond to the last two
digits of the user list name IEAIGG01).
This rE:lSpOnSe causes your load module to be
loaded into the relevant area of main
storagE:l.
If you require both the standard and
shared library load module lists, you must
instru(~ the operator to respond to the NIP
request: for system parameters by specifying
'RAM=OO,Ol'. You should note the following
points::
• If your installation standard reentrant
load module list (IEAIGGOO) refers to
SYS1.LINKLIB and not SYS1.SVCLIB, you
can add your module entry-point name
(IlIELTVA) to this list. In this case
you do not need to create a new
procedure library list; your
shelred-library load module will be
aut:omatically stored in main storage at
initial program load.
• If your installation standard reentrant
load module list (IEAIGGOO) does not
re1:er to SYS1. LINKLIB, your system must
have been generated with the ability to
conwunicate with the operator during
initial program load. This is because
thE! operator must specify the use of
thE~ alternative list as described
above.

How

tOI

Use a Shared Library

When e:ll:ecuting programs using the shar ed
library you must ensure that the first
module ,to be processed by the linkage
editor or loader is the dummy transfer
vector module IHELTTA. Also ensure that
the entry-point name of the resulting load
module is specified as IHELTTA. You should
note the following points:
:l.For mClre information about reentrant load
module lists refer to IBM/360 Operating
System: system Programmer's Guide.

• You can have a shared library for
either non-multitasking or multitasking
programs. You cannot, however, use a
multitasking program with a
non-multitasking shared library and
conversely, you cannot use a
non-multitasking program with a
multitasking shared library. You
should find out whether your
installation has a multitasking or
non-multitasking shared library.
• A load module created for use with one
shared library will not execute with a
different shared library. You will
have to link-edit the object module
again, including the dummy transfer
vector module IHELTTA for the different
shared library.
• You must remember that the linkage
editor or loader require a large amount
of main storage for external symbol
dictionary tables while processing the
dummy transfer vector module IHELTTA.
If you specify SIZE=200K in the PARM
field of your EXE~ statement for the
linkage editor or loader (and use a
region or partition of equivalent
size), you will get sufficient main
storage for processing with the largest
possible shared library.
• Your PL/I program may take slightly
longer to execute when using a shared
library, because all library calls have
to pass through the transfer vectors.
However, your main storage requirements
for a region will be greatly reduced if
you have carefully selected your shared
library modules to suit the operating
environment.
• The address of your shared library
module in the link-pack area of main
storage is found by IHELTTA issuing a
LO~D macro instruction.
If the
shared-library load module IHELTVA was
not made resident in main storage at
initial program load, and you try to
run your program with shared-library
job control statements, the
shared-library module will be loaded
into the region or partition. Your job
will still execute, but you will need
to specify a larger region size(MVT),
or use a larger partition (MFT).

AppendiK F: Shared Library Cataloged Procedures

281

USING STANDARD IBM CATALOGED PROCEDURES
In this method you make use of standard IBM-supplied cataloged procedures that contain a
link-edit job step or that use the linkage loader. If you use this method you must
override certain statements in ·the link-edit or loader job step of the cataloged
procedure to ensure that the shared.-library transfer module (IHELTTAJ is the first module
to be included by the linkage editor or loader. and that its entry point in the resulting
load module has the name IHELTTA.
The methods for doing this for each individual cataloged procedure differ slightly and
are described below.

Cataloged Procedures using the

Lin~~gg_~ditQ~

Compile and Link-Edit (PL1LFCL)
You may use this cataloged procedure by reversing the order of concatenation of the
data sets defined in the DO statement with the name SYSLIN. This ensures that the first
module specified is IHELTTA. The suggested method of doing this is as follows:
//S

//LKED.SYSLIN
//LKED.OBJ
//LKED.LIN
INCLUDE
INCLUDE
ENTRY

EXEC
PL1LFCL
DD
DDNAME=LIN
DO
DSN=&&LOADSET,DISP=(OLD,DELETE)
DD
*
SYSLIB (IHELTTA)
OBJ
lHELTTA
(add further input here)

/*

You can add other linkage-editor control statements by placing them as indicated. If,
for example, you wish to give the resulting load module the name MINE, you should add the
statement:
NAME

MINECIU

between the ENTRY and /* statements.
Note: You must not use DDNAME=SYSIN in the LKED.SYSLIN DD statement as this would be
concatenated with an identical DD statement provided by the cataloged procedure and cause
the input stream to be processed twice.
Compile, Link-Edit and Execu·te (PL1LFCLG)
This cataloged procedure can be modified for use with a shared library in exactly
same way as described for PL1LFCL above.

thE~

Link-Edit and Execute (PL1LFLG)
You may use this cataloged procedure by specifying the compiled object module as the
member DECK of the partitioned data set PL1. OBJECT, as follows,:

282

//S

//LKED.OBJ
//LKED.SYSIN
INCLUDE
INCLUDE
ENTRY

EXEC
PL1LFLG
DO
DSN=PL1.OBJECTCDECK),DISP=SHR
DO
*
SYSLIB(IHELTTA)
OBJ
IHELTTA
(add further input here)

/*

Note: Since PL1LFLG does not specify a concatenated data set for the SYSLIN DO statement
of the l~KED step, but only specifies DDNAME=SYSIN, you can specify all the link-edit
control statements by the LKED.SYSIN DO * statement.

CatalogE~d

Procedures using the Linkage Loader

Compile, Load-and-Execute CPL1LFCG)
You may use this cataloged procedure by overriding the PARM parameter of the GO step
to add t;he specified entry-point IHELTTA. You must also override the SYSLIN DO statement
to pernrl.t the transfer vector module IHELTTA to be processed by the compiler object
module. The suggested method for doing this is as follows:
//S

//GO.SYSLIN
//

EXEC
DO
DO

PL1LFCG,PARM.GO='MAP,PRINT,EP=IHELTTA'
DSN=SYS1.PL1LIBCIHELTTA),DISP=SHR
DSN=&&LOADSET,DISP=(OLD,DELETE)

Load-and.·- Execute (PL1LFG)

You may use this cataloged procedure by specifying the compiled object module as the
member DECK of the partitioned data set PL1.OBJECT, as follows:
//S

//GO.SYSLIN
//

EXEC
DD
DD

PL1LFG,PARM. GO=' MAP, PRINT, EP=IHELTTA'
DSN=SYS1.PL1LIBCIHELTTA),DISP=SHR
DSN=PL1.OBJECT(DECK),DISP=SHR

PROVIDING YOUR OWN CATALOGED PROCEDURES
You can provide your own cataloged procedures for use with a shared library. The
followinq examples suggest how you might write these, basing them on the standard
IBM-supplied cataloged procedures.
For illustration purposes, the names PL1LSCL, PL1LSCLG, etc., have been chosen, but
you. could use any names you choose. Once you have written your cataloged procedures you
add them to the procedure library (SYS1.PRO~LIB) at your installation by using the IBM
utility program IEBUPDTE.
Appendix F: Shared Library cataloged Procedures

283

Cataloged Procedures using ·the Li9kage Editor
compile and Link-Edit (PL1hSCL)
when you write this cataloged procedure, you should remember that it needs a special
member in the procedure library to hold the input control data to the linkage editor. In
the example, this member is called PL1LSLD and includes the following linkage editor
statements:
INCLUDE
ENTRY

SYSLIBCIHELTTA)
IHELTTA

Your cataloged procedure might look like this:
//PL1L
//SYSPRINT
//SYSLIN

EXEC
DD
DD

//

//SYSUT3

DD

//

//SYSUT1

DD

//

//LKED

EXEC

//

//SYSLIB
//SYSLMOD

DO
DD

//

//SYSUT1

DD

//

//SYSPRINT
//SYSLIN
//
//

DD
DO
DD
DD

PGM=IEMAA,PARM='LOAD,NODECK',REGION= 52K
SYSOUT=A
DSN=&&LOADSET,DISP=,MOD,PASS.,UNIT=SYSDA,
SPACE=CSO,<250,100»
DSN=&&SYSUT3,UNIT=SYSDA,SPACE=CSO,C250,250»,
DCB=BLKSIZE=SO
DSN=&&SYSOT1,SPACE=C1024,C60,60)"CONTIG),
ONIT=SYSDA,SEP=CSYSnr3,SYSLIN),DCB=BLKSIZE=1024
PGM=IEWL,PARM='XREF,LIST',COND=C9,LT,PLIL),
REGION=96K
DSN=SYS1.PLILIB,DISP=SHR
DSN=&&GOSETCGO),UNIT=SYSDA,DISP=CMOD,PASS),
SPACE=C102 14, (50, 20,1) ,RLSE)
DSN=&&SYSUT1,UNIT=SYSDA,SPACE=C1024,C200,20»,
SEP=CSYSLMOD,SYSLIB),DCB=BLKSIZE=1024
SYSOOT=A
DSN=SYS1.PROCLIBCPL1LSLD),DISP=SHR
DSN=&&LOADSET,DISP=COLD,DELETE)
DDNAME=SYSIN

Compile, Link-Edit and. Execute (PL1LSCLG)
You can write this cataloged procedure in a similar way to that described above for
PL1LSCL, remembering that again you require the special member PL1LSLD.
//PL1L
//SYSPRINT
//SYSLIN

EXEC
DO
DO

//

//SYSUT3

DO

//

//SYSUTl

DD

//

//LKED

EXEC

//

//SYSLIB
//SYSLMOD

DD
DO

//

//SYSUTl

DO

//

//SYSPRINT
//SYSLIN
//
//

//GO
//SYSPRINT
2S4

DD
DO
DO
DD
EXEC
DO

PGM=IEMAA,PARM='LOAD,NODECK',REGION=52K
SYSOOT=A
DSN=&&LOADSET,DISP=CMOD,PASS),UNIT=SYSSQ,
SPACE=CSO,(250,100»
DSN=&&SYSUT3,UNIT=SYSDA.SPACE=CSO,250,250».
DCB=BLKSIZE=SO
DSN=&&SYSUT1,SPACE=C1024,C60,60)"CONTIG),
UNIT=SYSDA,SEP=CSYSUr3,SYSLIN).DCB=BLKSIZE=1024
PGM=IEWL,PARM='XREF,LIST',COND=C9,LT,PL1L),
REGION=96K
DSN=SYS1. P:L1LIB, DISP=SHR
DSN=&&GOSET(GO),UNIT=SYSDA,DISP=CMOD,PASS),
SPACE=C1024.C50.20,1),RLSE)
DSN=&&SYSUrl,UNIT=SYSDA,SPACE=C1024,C200,20»,
SEP=CSYSLMOD,SYSLIB),DCB=BLKSIZE=1024
SYSOUT=A
DSN=SYS1.PROCLIBCPL1LSLD),DISP=SHR
DSN=&&LOADSET,DISP=,OLD,DELETE.
DDNAME=SYSIN
PGM=* • LKED. SYSI,MOD, COND= CC9 , LT , LKED) , C9 , LT, PL1L) )
SYSOUT=A

Link-Edi"t and Execute (PL1LSLG)
Again you need the special member PL1LSLO in SYS1.PROCLIB.
//LKED
//SYSLIB
//SYSLMOD

EXEC
DD
DD

PGM=IEWL,PARM='XREF,LIST',REGION=96K
OSN=SYS1.PL1LIB,DISP=SHR
DSN=&&GOSET(GO),UNIT=SYSOA,DISP=(MOD,PASS),
SPACE=(1024,(50,20,1),RLSE)

DD

OSN=&&SYSUT1,SP~CE=(1024,(200,20»,

DO
DD
DD
EXEC
DO

UNIT=SYSDA,SEP=(SYSLMOD,SYSLIB),DCB=BLKSIZE=1024
SYSOUT=A
DSN=SYS1.PROCLIB(PL1LSLD),DISP=SHR
DDNAME=SYSIN
PGM=*.LKED.SYSLMOD,=(9,LT,LKEO)
SYSOUT=A

//

//SYSUTl
//

//SYSPRINT
//SYSLIN
//

//GO
//SYSPRINT

Cata10qel~

Proceduresusinq the -Linkage Loader

In cataloged procedures that use the linkage loader, SYSLOUT is the ddname of the
diagnostic message output data set. This name should have been specified at system
generation; if i t has not, you should specify PARM = 'NOPRINT' in your EXEC statement.
If you do not specify this, and the loader was generated without the ddname SYSLOUT, the
system gives the loader diagnostic message output data set the default name SYSPRINT,
which is also the standard diagnostic message output data set name for PL/I programs. If
both the loader and a PL/I program attempt to execute DO statements with this ddname
under an MFT or MVT control program, you may lose your output or input/output errors may
occur whcen an output writer attempts to print it.
You do not need the special member PL1LSLO in the procedure library because you must
name the entry point of the resulting load module in the PARM parameter of your EXEC
statement:. •
Compile, Load-and-Execute (PL1LSCG)
In this cataloged procedure, your compiled object module is stored in the temporary data
set &&L01\DSET which is concatenated with the transfer vector module IHELTTA.
//P][,lL
//SYSPRINT
//SYSLIN

EXEC
DD
DD

//

//SYSUT3

DD

//

//SYSUTl

DD
EXEC

//

//SYSLIB
//

//SYSLOUT
//SYSPRINT

SYSOUT=A
DSN=&&LOADSET,DISP=(MOD,P~SS),UNIT=SYSSQr

SPACE=(SO,(250,100»
DSN=&&SYSUT3,UNIT=SYSDA,SPACE=(SO,(250,250»,
DCB=BLKSIZE=SO
DSN=&&SYSUT1,SPACE=(1024,(60,60)"CONTIG),
UNIT=SYSD~,SEP=(SYSUr3,SYSLIN),OCB=BLKSIZE=1024

//

//GO

PGM=IEMAA,PARM='LO~OrNODECK',REGION=52K

DD
DD
DD
DD

PGM=LOADER,PARM='MAP,PRINT,EP=IHELTTA',
REGION=96K,COND=(9,Lr,PL1L)
DSN=SYS1.PL1LIB,DISP=SHR
DSN=&&LOADSET,DISP=(OLD,DELETE)
SYSOUT=A
SYSOUT=A

Load-and--Execute (PL1LSG)
In this cataloged procedure, your compiled object module is the member DECK in the
partitioned data set PL1.0BJECT, and you may define this in the GO step as follows:
//GO.L01\'DIN DD OSN=PL1.0BJECT(OECK) ,DISP=SHR
Note: You might use the ddname LOADIN instead of SYSIN to define input to the loader,
because BYSIN may be required to define the PL/I (F) default input data set for the
program being loaded.
Appendix F: Shared Library Cataloged Procedures

2S5

Your cataloged procedure may look like this:
//GO

EXEC

//

//SYSLIB
//SYSLIN
//

//SYSOUT
//SYSPRINT

286

DO
DO
DD
DO
DO

PGM=LOADER,PARM='MAP,PRINT,EP=IBELTTA',
REGION=96K
DSN=SYS1.PL1LIB"DISP=SHR
DSN=SYS1.PL1LIB(IHELTTA),DISP=SHR
DDNAME=LOADIN
SYSOUT=A
SYSOUT=A

Appendix G: IBM System/360 Model 91

Note: In the following discussion, the
terms exception and interrupt are used. An
exceptio]} is a hardware occurrence (such as
an overflow error) which can cause a
program interrupt. An interrupt is a
suspension of normal program activities.
There are many possible causes of
interrupt:s, but the following discussion is
concerned only with interrupts resulting
from hardware exceptions.
IBM System/360 Models 91 and 195 are
processing systems in which more
than one instruction is executed
concurrently. As a result, an exception
may be dE~tected and an interrupt occur when
the addrE?!ss of the instruction which caused
the exception is no longer held in the
central processing unit. Consequently, the
instruction causing the interrupt cannot be
precisely identified.
Interrupts of this
type are termed imprecise. When an
exception occurs, the machine stops
decoding further instructions and ensures
that all instruct10ns which were decoded
prior to the exception are executed before
honoring the exception. Execution of the
remainin parameter of the EXEC statement.

STEP ABEND FACILITY
Using the standard default module IHEABND
in the PL/I library (data set SYS1.PLILIB),
error handling will be as stated above.
The STEP ABEND facility is available
however by using a user-written module
IHEABND.; Replacing the standard module
results in a STEP ABEND being issued whenever the ERROR condition is raised or
signallE;!d in the absence of an ERROR
ON-unit.,

Changing Standard Module IHEABNn
To change the standard module IHEABND to
obtain the STEP ABEND facility the return
code in register 15 must be set to
non-zero. TO become an installation
standard this module must be link-edited
into the PL/I library (data set
SYS1.PLILIB) to replace the standard module
IHEABND. For use in one program only, the
object deck is link-edited with that
program.
The purpose of this module is to set a
non-zero return code in register 15. The
error handling module IHEERR calls IHEABND
and examines the return code held in
register 15 to decide whether STEP ABEND or
normal action is required.
(The standard
default module IHEABND in SYS1.PLILIB sets
a zero return code in register 15). If the
return code is non-zero then a STEP ABEND
is issued.

RETURN CODES
Return codes are set by use of the
statement CALL IHESARC, or CALL IHETSAC
(multitasking).

Module form:
IHEABN
IHEABND

CSECT
ENTRY
USING
EQU
L

NONZERO

BR
DC
END

IHEABND
*,15

* NONZERO
15,
14
F'l'

Define entry
Addressability
Entry point
Set return code in register 15
Return on register 14
Non-zero return code

Appendix I: ON, Return, and User completion Codes

295

296

Appendix J:

Implementation Conventions and Restrictions

AREA At"tribute

The BASED attribute must be followed by
a pointer identifier in parentheses.

The size of an area is limited to 32,767
bytes. In this implementation, the AREA
size is provided by the value associated
with thle AREA attribute or by the default
value o:f. 1000 bytes.

The OFFSET attribute must be followed by
an identifier in parentheses.
The variable named in the OFFSET
attribute must be an unsubscripted level 1
based area.

Aggregat:es

Offset variables 'may not be used in any
SET option or in any explicit or implicit
based variable qualifier.

The lenqth of an aggregate is limited to
8 , 388 , 607 byt es •

A based variable may not have the
INITIAL attribute.
A based label array cannot be
initialized by means of subscripted label
prefixes.

Array Bounds

A based structure can have either:
Arrays a.re limited, for each dimension, to
a lower bound of -32,768 and to an upper
bound of 32,767.

BASED

1.

One adjustable array bound, or

2.

One adjustable-length bit or character
string.

A1~tribute

The implementation of offsets and pointers
does nOi: support bit address ing. This
restric1:ion has no practical effect on
ALIGNED bit strings. With UNALIGNED bit
strings belonging to arrays or structures,
however., only offset or pointers to major
structw:es or minor structures with byte
(or higher) alignment should be used.

Based Structure with-One Adjustable Array
Bound: This is permitted only when there
are no adjustable strings in the structure.
The bound must conform to the following
rules:

1.

It must be of the form:
X REFER (Y)
where X is an unsubscripted fixed
binary integer variable,

Based

Vc~riable

Declaration

Y is an unsubscripted fixed
binary integer variable, of the
same precision as X, which is:

A pointE~r variable must be included in a
based variable declaration.
(This is the
pointer that will be set in the absence of
a SET option from a LOCATE or an ALLOCATE
statemeIit referring to the based variable.)

part of the structure, and

b.

not associated with an
explicit pointer qualifier.

2.

It must be the upper bound of the
leading dimension (including inherited
dimensions) of the element with which
it is declared.

3.

The structure member with which the
bound-is declared must be, or must
contain, the last base element in the
structure.

Based Variables
The pointer variable explicitly or
implici"t:ly qualifying a based variable must
be a non-based unsubscripted scalar pointer
:i.dentifier.

a.

Appendix J: Implementation Conventions and Restrictions

297

Example:

Buffers

DCL 1
2
2
2

The number of buffers must not exceed 255"

PARTS LIST BASED(P),
FIRM_NAME CHAR(40),
REF_NO FIXED BINARY,
FIRM ADDRESS,
3 STREET TOWN CHAR (50),
3 COUNTRY CHAR(30),
2 STOCK(20:N REFER(REF NO), 100:200),
3 NUMBER,
4 HERE FIXED(10,0),
4 ORDERED,
5 PROVISIONAL FIXED(10,O),
5 CONFIRMED FIXED(10,0),
3 COST FIXED(5,0);

Based Structure with.One Adjustable-Len~h
Bit or Character String: This is permitted
only when there are no adjustable array
bounds in the structure.. The string must
conform to the following rules:
1.

It must be an element.

2.

It must be the last element in the
structure.

Built-In Functions
The default value for the second argument
of the FIXED built-in function is 15 for
binary data, and 5 for decimal data.
The default value for the second
argument of the FLOAT built-in function iB
21 for binary data, and 6 for decimal data.
The length of the bit string which is
the value returned by the UNSPEC built-in
function is defined by the type of the
argument.
Argument Type

3.

The length must be declared in the
form:
X REFER (Y)
where X and Yare as described above.

Example:
DCL 1
2
2
2

TYPE OF HOUSE BASED(P),
NUMBER_OF_FLOORS FIXED(2,0),
AREA FIXED BINARY,
RATES_CODE CHAR(N REFER(AREA»i

Note: Pointer and area data types must be
aligned.

Length of Bit String

FIXED BINARY (p,q)

16 if p < 16
32 if P > 15
FIXED DECIMAL (p,g) 8*FLOOR ( (p+2)/2)
FLOAT BINARY (p)
32 if p :$ 21
64 if P ~ 22
FLOAT DECIMAL (p)
32 if P :$ 6
64 if p ~ 7
CHARACTER (n)
8*n
BIT (n)
n
32
POINTER
32
OFFSET
(Number of bytes
AREA
allocated + 16)*8
The length of the string returned by the
ONSOURCE and DATAFIELD built-in functions
is subject to an implementation maximum of
255 characters.

Character Code
Block Size
The maximum size of a block must not exceed
32,760 bytes.
See IBM System/360 Operating System:
PL/I (F) Language Reference Manual for
details of data aggrega·te size requirements
necessary in calculating the block size for
data sets using RECORD I/O.

Blocks in a Compilation
The number of PROCEDURE, BEGIN, and
iterative DO-groups, plus the number of
ON-statements, must not exceed 255.
298

Input to the object program is assumed to
be in EBCDIC mode.

CHECK Condition
If an identifier that is read in by a GET
DATA statement is 'included in a CHECK lis1t
anywhere in the program, then the CHECK
condition is raised, and will be treated as
enabled unless the block containing the GET
DATA statement has an explicit NOCHECK
prefix. If the CHECK condition is raised,
system action will be taken unless the GE'r
DATA statement lies within the dynamic
scope of an ON CHECK statement for the
identifier in question .•

If Cil READ statement with the EVENT
option has a KEYTO or an INTO variable for
which t~he CHECK condition is enabl,ed, the
value of the variable will be printed
immedialtely after execution of the READ
statemEmt, not after the WAIT statement.
consequently, the printed values of the
variable will be the old, not the new
values.
The CHECK condition is not raised for
the name of a procedure when:
1.

The procedure that enables the CHECK
condition also invokes the named
procedure, and

2.

The invoking procedure and the named
procedure hav'e been placed in
di.fferent program segments (overlays)
by the linkage editor.

COLUMN Format Item in Non-Print Files
For input files, if the value of the
expression is greater than the current
record length, a value of 1 is assumed.
For both input and output files, if the
value is less than the current position on
the line, the file is positioned at
COLUMN (value) on the next line.
For output files, all characters from
the current position in the line to the
next position are blanked out. For U- or
V-format records, if another record is
required, a short record is put out subject
to the rules described under the SKIP
,
format item.

Concatenated Data Sets

The maJ!:imum number of entries in a CHECK
conditi.on, whether in a prefix list or in
an ON-s:tatement, is 510.
The maximum number of data items being
at any point in the compilation
varies between 2078-2n and 3968-2n, where n
is the number of currently checked items
which have the attribute EXTERNAL.
ch~cked

If at structure or part of a structure is
in a CHECK condition, the number of items
in this: restriction must include all
element~s of the structure.

Concatenation of data sets with 'unlike
attributes' (device type, record format,
etc.,) is not supported at object time.

Constants
The precision or length of constants may
not be greater than the precision or length
of the corresponding type of variable.

Constants, Floating-Point
COBOL Option

The exponents of floating-point numbers are
restricted to a maximum of 2 digits for
decimal or 3 digits for binary.

If an ON-condition arises during a READ
INTO, t~hen:
1.
2.

The INI'O variable may not be used in
the ON-unit.

Constants Returned by Procedures

If: the completed INTO variable is
must be a normal
ON-unit.

If a procedure has more than one entry
point, and each entry point returns a
value, code is generated to convert each
value returned to each of the data types
for the entry points. If any of these
values is a constant., it is possible that
this constant cannot be converted to all
the data types specified. A severe error
message will be put out, and execution will
be unsuccessful.

r€~quired, there
r€~turn from the

In the execution of PL/I programs,
compari.sons of character data will observe
the collating sequence resulting from the
represe~ntations of characters in bytes of
IBM&System/360 storage in extended binary
coded decimal interchange code (EBCDIC).

This situation can be avoided by
assigning the constant to a variable of the
same data type, and then returning this
variable. For example:

Appendix J: Implementation Conventions and Restrictions

299

DCL A ENTRY RETURNS(CHAR(S»,
B ENTRY RETURNS(FIXED DECIMAL(lS»,
C ENTRY RETURNS(BIT(64»,
ATEMP CHAR(S);

A: ENTRY CHAR(S);
ATEMP= , AOS ' ;
RETURN (ATEMP) ;
B: ENTRY FIXED DEClMAL(lS);
RETURN(10S);
C: ENTRY BIT(64);
RETURN ('10101' B) ;
The use of ATEMP aVioids the interrupt
caused by the CHARACTER->FIXED DECIMAL and
the CHARACTER->BIT conversions. However,
execution may still be unsuccessful, and a
warning message is put out to remind the
user.

DE CLARE statement, (compile-time)
No more than three levels of factoring are!
permitted in a compile-time DECLARE
statement.

DEFINED

Attribut~

The DEFINED attribute is always evaluated
on entry to the declaring block.
Overlay defining is not permitted if the
base is either subscripted or is declared
CONTROLLED. Correspondence defining is nClt
permitted if the base is declared
CONTROLLED.
Example:
DCL B CONTROLLED"

Constants, Sterling
The maximum number of digits allowed in the
pounds field of a sterling constant is 13.
The number of digits following the
decimal point in the pence field must not
exceed 13 minus the number of digits in the
pounds field.

C(10) AUTOMATIC;

DCL A DEFINED B,
E DEFINED C(I),
F(10) DEFINED C;

/*INVALID*/
/*INVALID*/
/*VALID*/

No correspondence defining may be used
with arrays of structures.
Example:
DCL 1 A(10), 2

B~

2 C;

DCL 1 0(5) DEFINED A, 2 E, 2 F; /*INVALID*/
DCL D(S) DEFINED B;
/*VALID*/
Constants, String
The number of characters in a string
constant, after expansion of iteration
'factors, may not exceed the size of a
dictionary block minus 14. The size of a
dictionary block will vary with the storage
available to the compiler in the same way
as does text block size, but will not be
less than 1,024 bytes.

Dimensions
The maxiumum number of dimensions
permitted, including dimensions inherited
from containing structures, is 32.

DISPLAY Statement
Data-Directed Input/Output

';Jt'

The maximum lengtH'o~ a qualified name,
including the separating periods, is 255
characters.

Data~Directed

The maximum lengths of character string
acceptable are 72 characters for the
message and 126 characters for the reply.
The reply string's current length is set
equal to its maximum length and padded with
blanks if necessary.

List
Dummy Arguments

The maximum number of elements permitted in
a list for data-directed input is 320.
Each base element of a structure counts as
a separate list~element.
300

The maximum number of dummy arguments
permitted at each invocation of a procedure
is 64.

Edi t- Dj:rected Input/Output

Example:

In the output format item E(w,d,s), s must
be less than 17 digits. In the output
format item E(w,d), d must be less than 16
digits.
If t~he number of significant digits in
E- formcLt is greater than 16, then:
E-format input:

CONVERSION condition
raised

E-format output: ERROR Condition raised
when either a repetitive specification
appears in an edit-directed format list or
an iteI~ation factor is used in a format
list, t:he data items are associated with
their format items during execution rather
than compilation. The compiler will
therefore include library modules that can
handle all the possible pairings of data
and fOI~mat items. Some of these modules,
however, will never be invoked should the
circumstances that demand their use never
arise.

ENTRY Names as Arguments and ON-Statements
in Rect~sive Contexts
In the first version of the (F) 'compiler,
ENTRY parameters were invoked with the
enviror~ent existing at the time of
invoca"t:ion. In subsequent versions, they
will bE~ invoked with the environment
existing at the time when the ENTRY name
was passed as an argument.
ExamplE~:

Pi:: PROC RECURSIVE:
B=l-;
CALL P4(P3);
RETURN;
P4:: ENTRY (PP) ;
B=2;
CALL PP:
P3:: PROC:
PUT DATA(B);
END:
END:

P: PROC RECURSIVE;
DCL I STATIC INIT(O),M AUTOMATIC;
I=I+l:
M=I:
IF I=l THEN DO:
ON OVERFLOW PUT DATA(M):
END:
IF I=3 THEN SIGNAL OVERFLOW:
ELSE CALL P:
END:
Note: In the first version, the procedure
gave M=3:. subsequent versions give M=l:.
These modifications of semantics can
affect only those programs which contain
both recursive procedures and either entry
parameters or ON-statements.

EVENT Option
The EVENT option is implemented for RECORD
input/output statements used as follows:
Access

Data~Set

Organization

SEQUENTIAL
UNBUFFERED

CONSECUTIVE, REGIONAL

DIRECT

CONSECUTIVE, INDEXED
or REGIONAL

Note: The EVENT option should not be used
on a WRITE statement if V- or U- format
records are being added to a REGIONAL(3)
data set which is being accessed in a
direct update mode. If the EVENT option is
specified in the DISPLAY statement, it must
follow the REPLY option.

Exponentiation

Note: Ii"or the first version, the above
procedltte gave B=2;, for subsequent
versions it gives B=l;.
In t.he first version of the (F)
compilE:lr, ON-units in recursive contexts
were entered with the environment existing
when the condition occured. In subsequent
versions, the ON-unit will be entered with
the en"ironment which was in existence when
the ON··statement was executed.

The expression X**(-N) for N>O is evaluated
by taking the reciprocal of X**N. This may
cause the OVERFLOW condition to occur as
the intermediate result is computed, which
corresponds to UNDERFLOW in the original
expression.

Expression Evaluation
The maximum number of temporary results
which may exist during the evaluation of an
expression or during an assignment
statement is 200.

Appendix J: Implementation Conventions and Restrictions

301

An estimate of the number of temporary
results which may exist during the
evaluation of an expression can be obtained
from the following:
At each level of parenthesis, count one
for each operator which is forced to be
evaluated before an inner level of
parentheses.
For each such operator,
count one for each operand which
requires conversion before use, count
one for each nested function, count one
for each subscripted variable used as a
target in a assignment statement, and
finally, count one for each
pseudo-variable and each argument of a
pseudo-variable.

GENERIC Attribute
There is a limitation on the number of
family members and argumants which may he
associated with a GENERIC entry name. the!
value given by evaluating the following
formula must not exceed 700:
n

3n + 8I:a. + 8MAX(a 1 ,a2, ••• an) + 3d
1

I

where n = the number of family members.
aj = the number of arguments relating
to the ith family member.
d
the greatest function nesting
depth at which an invocation of
the GENERIC entry name appears.

Factoring of Attributes
The total number of pairs of parentheses
used for factoring attributes in DECL~RE
statements within a compilation is
dependent upon the SIZE option, as follows:
Text Block Size

Factor Bracket Limit

1K
2K
4K
8K
16K

146
292
585
1171
2340

For relationship between SIZE option and
block size, see "Control Options" in
Chapter 5: Compilation.

FLOAT Attribute

Halfword Binary Facilities
With previous versions of the compiler,
fixed binary variables of any precision
were always mapped as fullwords (requiring
four bytes of storage). The fifth version.
of the compiler will map fixed binary
variables of precision less than 16 as
halfwords (requiring only two bytes of
storage), and will use IBM System/360
halfword instructions to process them.
Note that variables of default precision
will be mapped as half words.
The change does not apply to fixed
binary constants or fixed binary
intermediate targets (i.e., compiler
created temporaries for holding
intermediate results of operations). These
will continue to occupy fullwords.

Floating-point precision specified as
FLOAT (*) in a parameter description within
the GENERIC attribute, is not permitted~
Identifiers, Length
Floating-point Magnitude
The magnitude of a normalized
floating-point variable or intermediate
result must lie in the range from
2.4 * 10- 78 to 7.2 * 10 75 •

The following types of identifiers should
contain not more than seven characters:
EXTERNAL data identifiers
EXTERNAL PROCEDURE and ENTRY labels
ExrERNAL Files
CONDITION identifiers

Function Values

If this restriction is exceeded, the
first four characters are concatenated with
the last three to form an abridged
identifier.

The maximum number of different dat.a types
or precisions returned by one function may
not exceed 256.

In, addition, such identifiers must not
start with the letters IHE, in case they
conflict with the names of library modules.

302

Identifiers, Subscripted

INTO Option of READ Statement

For subscripted identifiers, the maximum
number of characters in the subscript is
limited to 255 characters. This figure
includes the first left parenthesis, the
commas, and the final right parenthesis: it
excludes redundant characters such as
blanks and plus signs.

When the record variable of a READ
statement is a variable length bit-string,
the byte count, not the bit count, is
stored as the current length. This is
because all variable length bit-strings are
not both byt'e aligned and multiples of
eight.

INCLUDE statement (compile-time)

LABEL Attribute

Included text must be from a member of a
partitioned data set. If a single
identifier is specified, either as
(identifier) or identifier then it is
assumed to be the name of a member of the
partitioned data set with the ddname
SYSLIB. If identifier~ (identifier2) is
written, then identifier~ is the ddname and
identifier2 is the member name. DD
statements must be provided for partitioned
data sets used. Records in these data sets
must have a fixed length of not more than
100 characters. The maximum blocking
factor is 5. The source margin and
character set options on the EXEC statement
also apply to included text.

The number of statement-label constants
specified by the LABEL attribute is limited
to 125 in any particular label list.
Qualified names may not be used as label
prefixes. Reference to arrays of label
variables initialized by means of
subscripted labels must not require
explicit structure qualification.
Example:
DCL Z(3) LABEL,
1 5'1

2 Y(3) LABEL,

1 51.

2 Y(3) LABEL,

1 52,

2 X(3) LABEL:

INDEXAREA option
The index-area-size parameter to this
option is a decimal constant and must not
exceed 32,767.

INITIAL Attribute
An INITIAL attribute given for CHARACTER or
BIT data of STATIC storage class may not
specify 'complex expressions' as initial
values.
Example:
DCL C CHAR(10)
STATIC INITC3+4I),

/+INVALID+/

DCL C CHAR(10)
STATIC INITC'3+4I'):

/+VALID+/

on~y the INITIAL CALL form of the
INITIAL, attribute is allowed in pointer
declarations.

Z Cl): :
S.Y(1):
X(1): :

/*VALID*/
/*INVALID*/
/*VALID*/

LABEL Variables in Structures with the LIKE
Attribute
Initialization of LABEL variables in these
structures requires careful handling
particularly as the implementation does not
provide the result specified by the
language. A structur.e A is declared, using
the LIKE attribute, to ~e identical to a
structure B. Structure B' contains a LABEL
variable that is initialized, using the
INITIAL attribute, to the value of a LABEL
constant~
The initial value of the
corresponding LABEL variable in A is the
initial value of the LABEL constant known
in the block containing the declaration of
B, not A.

Appendix J: Implementation Conventions and Restrictions

303

CALL ACB);

. ExamEle:
DCL 1 B,
2 L LABEL INITCL1);

L:

.

END A;
Ll:

.

;

/*B.L=Ll*/

END X:

BEGIN;
DeL A LIKE B:
Ll:

.

,

/*A.L IS GIVEN THE VALUE OF
Ll IN STRUCTURE B*/

END;

Label constants in Recursive Procedures
When a label constant in a recursive
:procedure is the object of a GOTO
statement, the branch will be taken to the
label in the most recent invocation of -the
.procedure. The most recent invocation is
used irrespective of the environment that
invoked the recursive procedure and of -the
environment that invoked the procedure
containing the GOTO statement.
Consequently, if the GOTO statement: is in a
procedure which was passed as an entry name
parameter, the branch will be to the most
recent invocation rather than to the
invocation that, was active when the entry
name parameter was passed.
In the following example, the first
invocation of A invokes A recursively: the
second invocation of A invokes procedure B.
The GOTO statement in procedure B causes a
branch to the label L in the most recen-t
:invocation of procedure A rather than to
'the previous invocation.
X: PROC OPTIONS(MAIN):

Label Variables in Recursive Procedures
If a label variable is assigned a label
constant in a particular invocation of a
recursive procedure, a GOTO statement
associated with the invocation will
transfer control to the label constant
within that invocation. Consequently, if
the GOTO statement is in a procedure which
was passed as an entry name parameter, thE~
branch will be to the label constant
assigned to the label variable in the
environment that was active when 'the entrl!'
name was passed.

In the following example, the first
invocation of procedure A invokes A
recursively; the second invocation of A
invokes procedure B. The GOTO statement in
procedure B causes a transfer to the label
L in the invocation of A that was active
when the entry name parameter B was passecl,
i.e., the first invocation of A.

X: PROC OPTIONSC'MAIN):

CALL A (A) :
A: PROC (E) RECURSIVE:
DCL E ENTRY:
DCL SW BIT(1) STATIC INIT( 'O'B):
DCL LAB LABEL INIT(L):

CALL A(A):

A: PROC(E) RECURSIVE;

DCL E ENTRY,
SW BIT(l) STATIC INIT('O'B)i

B: PROC:
GOTO LAB
END B:

IF SW THEN CALL E;
SW='l'B:
CALL A(B):

B: PROC
GOTO L;
END B:
IF SW THEN CALL E
SW='l'Bi
304

L:

•

END A;
END X;

Level Numbers

ENVIRONMENT attribute.
Short lines are
padded with blanks for F-format records
only.

The maximum declared level number permitted
in a structure is 255. The maximum true
level number permitted in a structure is
63.

The MACRO option should be included among
the complete set of options for the
compiler invocation if the program contains
compile-time statements ..

Line Nmnberinq (Compile-Time)
Where constants or comments span more than
one linc=, the output line numbering refers
to the :Eirst input line number of the
string or comment.

MAIN Option

LINESI Z]~ Format Item
The maximum amd minimum line size depend on
the record format.
r------·~-T--------------------------------,

I
I
LINESI ZE
I
I Record ~------------------T-------------~
I Format: I
Minimum
I
Maximum
I

...

MACRO Compiler Option (compile-time)

A single parameter may be passed by the
EXEC statement for the execution job step
to the MAIN procedure.
If this facility is
used, the first parameter to the MAIN
procedure should be declared as a VARYING
character string; the maximum length is
100, and the current length is set equal to
the parameter length at object time. The
parameter can also be a fixed-length
character string.

~------ -+-----------------+-------------~

I
I

V

...

INon-PRINT file: 101
I PRINT file: 9
I

32,751

I

I

MA~MIN,MOD,

Built-In Functions

~------ -+------------------+-------------~

I

I
11

I
I

I
I

I ______
U,F ... _J.. __________________ J.. _____________
32,759
L
J

If a line size is not specified, the
default values are:
PRINT file: 120 characters
Non-PRINT output file: no default value
The I,INESIZE value determines the
logical·mrecord length in the data set
(i.e., ithe value of LRECL):
F- and U-format records: LRECL = LINESIZE
V-format records: LRECL = LINESIZE + 4
For PRINT files, an extra byte (for the
ANS conitrol character) is added to each of
the above LRECL values.
If BLKSIZE is specified, its value and
the LRECL value must be compatible.. If
BLKSIZE is not specified, its value is
calcula1:ed from the LINESIZE value ..
Evaluation of the expression gives an
inteqer that must be within the limits
described above.
For V- and U-format
records" LINESIZE is the maximum size of a
line.
If a variable LINESIZE is required,
the maximum value must be specified as the
BLKSIZE in the DD statement or in the

When the arguments to these functions have
different attributes" all the arguments are
converted, before the function is invoked,
to the highest characteristics. Contrary
to the language specification, both the
precision and the scale factor of an
argument will be adjusted.
If all the
arguments are FIXED, application of the
highest-characteristics rule may, in
conjunction with the maximum precision
defined by the implementation, cause
truncation and hence an inaccurate result.
For example:
DCL X FIXED DECIMAt(12,l),
Y FIXED DECIMAL(12,9);
Z=MOD(X,Y);
Here Z (whateVer its attributes) will be
wrong.
X and Yare stored in a temporary
field which would have, according to the
precisions of the operands, a precision
larger than the implem.entation permits.
Therefore the implementation-defined
maximum is applied, resulting in a
precision of (15,9). Y can be stored
satisfactorily inside such a field but X is
truncated, with the loss of its five
high-order digits.
When the MOD built-in function is used
with FIXED arguments of different scale
factors, the results may be truncated. If

Appendix J: Implementation Conventions and Restrictions

305

SIZE is enabled, an error message will be
printed; if SIZE is disabled, no error
message will be printed and ,the result is
undefined.

Multiple Assignments and Pseudo-Variables
Multiple assignments are limited by the
following rule:
count 11 for each target of a multiple
assignment, add 3 for each
pseudo-variable, and then add 11 for
each argument of a pseudo-variable.
The total must not exceed 4,085.

Names Generated by the Compiler
The number of names generated by the
compiler must not exceed 11,264 in a
compilation. One name is generated for
each PROCEDURE, BEGIN, or ON-block u for
,each variable declared as CONTROLLED
INTERNAL, and for each INTERNAL file.

'Names, Qualified
The number of characters in a qualified
name, which is to be used either for
,data-directed input/output or in CHECK
lists, must not exceed 256.
Note that if the DATA option without a
list is used for data-directed input, this
will include all structure elements in the
compilation.

Nesting Limitations
There must not be more than 50 levels of
nesting at any point in the compilation.
The degree of nest~ng at any pOint is the
number of PROCEDURE, BEGIN or DO
statements, without a corresponding END
statement, plus the number of currently
active IF compound statements, plus the
number of currently unmatched left
parentheses, plus the number of dimensions
in each active array expression, plus the
,maximum number of dimensions in each active
,structure expression.
The number of nested iteration factors
in a format list must not exceed 20. The
maximum nesting of ENTRY attributes within
an ENTRY or GENERIC attribute'is 3~
306

Nesting and Depth of Replacement
At any point in the program the combined
level of nesting and depth of replacement
is restricted to 50. However, since not
all nested or replacement items require the
same amount of space, a program may run
with a greater actual nesting or
replacement depth than 50 levels. Depth of
replacement is self-defining, but nesting
level requires some clarification. A
nesting level is required for:
1.

Each pair of parentheses, either
explicit or implied by hierarchy of
operation.

2.

~ach

3.

Each member of a parenthesized list,
such as factor lists in DECLARE
statements or argument lists of
procedures.

IF, DO or PROCEDURE statement.

OFFSET and POINTER Built-In Functions
The OFFSET and POINTER built-in functions
cannot be specified expl~citly. However,
if the value of an offset variable is
assigned to a pOinter variable, or a
pointer value to an offset variable, the
necessary conversion is implicit in the
assignment.

ON-Units and Entry Parameter Procedures
There is an implementation limit to the
number of ON-units and/or entry parameter
procedures which can be active at any timE~.
An entry parameter procedure is one that
passes an entry name as parameter to a
procedure it calls. rhe total permissible
number of these ON-units and/or entry
parameter procedures is 127.

ONCOUNT Built-In Function
This built-in function is supported only
for Model 91 requirements.

PAGESIZE Option
The maximum size of a page is 32,767 lineB;
the minimum is 1 line.
If the page size is
not specified a value of 60 lines is
assumed.

Parame"ters

aggregate size requirements necessary in
calculating the record size for data sets
using RECORD I/O.

The ma:lcimum number of parameters permitted
at any entry point is 64.
REFER Option
PICTUR:~

Attribute

The ma:lcimum length of a PICTURE describing
a numeric field, after expansion of
iteration factors, is 255.
, The maximum length of a PICTURE
describing a character string, after
expansion of iteration factors, is the size
of a dictionary block, less 14. The size
of a dictionary block will vary with the
storag1e available to the compiler in the
same way as does, text block size, but will
not be less than 1,024 bytes (or 768 bytes
if the EXTDIC option is in use).

The restriction on the two variables in the
REFER option of the BASED attribute~ has
been eased to permit fixed binary integer
variables of the same precision as each
other. This will allow the user the choice
of either continuing to use fullword binary
or using halfword binary for the
controlling fields in self-defining
structures.

Scale Factor
The scale factor of a variable, or of an
intermediate result of type FIXED, must be
in the range -128 arid +127.

POSITION 1\ttribute
The ma:tdmum value of the integer constant
in the POSITION attribute is 32,767.

Precision
The pr1ecision, N, for a compile-time
variable declared FIXED is restricted to' 5.
The maximum precision of a variable or
of an intermediate result is:
53
16
31
15

for
for
for
for

FLOAT
FLOAT
FIXED
FIXED

BINARY
DECIMAL
BINARY
DECIMAL

Size of Compile-Time Processor Input
The use~'s program is maintained internally
as blocks of text. Block size is assigned
at the start of processing and is a
function of machine size as specified by
the SIZE option on the EXEC card. The total
size of internal text is restricted to 90
times the size of a text block. The
minimum system configuration results in a
block size of lK, so a total of 90K is
allowed for internal text. This minimum
figure is roughly equivalent to 1000 source
input statements.

Size of Individual Statement
Proced~res

(compile-time)

There may be no more than 254 compile-time
procedures per compilation. Further, each
procedure is limited to a maximum of 15
parame"ters.

Record Size
The ma:,dmum size of a record must not
exceed 32,760 bytes. See IEMSystem/360
Operating System: PL/I (F) Language
Refere:!lce Manual, for details of data

All statements, other than a DECLARE
statement, are limited to 3,500 source
characters, i.e." equivalent to 50 cards.
The 'content' of any statement, other than
a DECLARE statement, is limited by the size
of a text block; this varies, as described
in the preceding paragraphs, with the
storage available, but will not be less
than 1,024 bytes.
The contect of a statement can be
calculated by ignoring nonsignificant
blanks and comments, expanding iteration
factors in string constants and pictures,
and then adding one byte for each
occurrence of an identifier, and three
bytes for each occurrence of a constant.

Appendix J: Implementation Conventions and Restrictions

307

To this, for binary constants add the
iterations of any CHARACTER or BIT strings
(note that at this point BIT strings are
treated as characters, not bits), since the
(F) compiler expands the strings as if the
programmer had ~ritten then in full, and
two decimal digits for decimal constants.
At most, these restrictions will limit a
statement to six cards, but the limit will
normally he between 20 and 30 cards. even
for a text block of 1,024 bytes.
These restrictions also apply to a
DECLARE statement for the text between any
two commas which are not contained within
parentheses.

SKIP Format Item in Non-Print Files
For output files, SKIP action depends on
the record format:
F-format: On a short line. SKIP fills
out the remainder of the line with
blanks.
V-format: SKIP puts out the current
line as a short record. If the byte
count of the line is less than 14 (18
with control bytes), the line will be
blanked up to that size. Successive
lines will be of the same minimum
length, padded with blanks.

STRING Built-In Function
The argument may be an element array, or
structure variable that consists of one of
the following:
1.

Bit strings

2.

Character strings

3.

Decimal numeric pictures

4.

~

mixture of (2) and (3)

It cannot be an operational expression.
The argument can be ALIGNED or
UNALIGNED; if it is ALIGNED, padding is not:
included in the result.
The concatenated string in the result
has a maximum length of 32,767 bytes.

String Lengths
The length, in characters or bits, of a
string variable or intermediate string
result is limited to 32,767.

String Lengths in Intermediate Result
Fields

U-format: SKIP will put out the current
line as a short record.

Statements
The total size of the internal text, at any
point in the compilation, is restricted ·to
90 times the size of a text block. The
size of a text block is itself dependent on
the amount of main storage available to ·the
compiler, as specified by the SIZE option.
The minimum block size is 1,024 bytes (lK),
giving a maximum size for the internal text
of 92 r 260 C90K). This is equivalent to
roughly 280 executable statements.
The maximum block size is 16,382 bytes,
giving a maximum of 1,474,560 bytes for ·the
size of internal text. This is equivale:nt
to roughly 14,000 executable statements.
The figures given for numbers of
statements are necessarily approximate,
since the number of bytes per statement
will vary between different types of source
programs.
308

When non-adjustable V~RYING strings, or
functions which return non-adjustable
VARYING strings, are used in an expression,
the lengths of the intermediate result
fields are calculated from the maximum
lengths of the operands. If these lengths
are at or near the maximum permi tt ed by thE~
implementation (32767 bytes or bits), the
length of the intermediate fields may be
greater than the implementation maximum; if
so, they will be truncated on the left.
This situation can occur with
concatenation, the UNSPEC function with a
character-string argument, the REPEAT
function., and the STRING function.
The use of adjustable VARYING strings
can create a similar problem. When an
operand of the concatenate operator or the
argument of the UNSPEC function is an
adjustable VARYING string, the length of
the intermediate result field is not
tested, and execution will fail. This
situation can also occur with SUBSTR if thE~
third argument is not a constant, because
in this case the result is an adjustable
VARYING string.

Sim:i.larly, when a VARYING string is
passed as an argument to a fixed-length
string parameter, the length of the
temporary argument created is the maximum
length..
If the user wishes to pass the
currenit;. length of the VARYING string (in,
for ex(~ple, Y=X(A», a possible method is:
DC]C, ATEMP CHAR(*) CTL;
ALLOCATE ATEMP CHAR(LENGTH(A»;
AT1!;MP=A;
Y=X(ATEMP) ;
FRlm ATEMP;

ALLOCATION), or to a procedure declared
with the attribute GENERIC.
Example:
DCL 1 A(10), 2 B:
A=SIN(A) ;
B=SIN(B):

/* INVALID */
/*VALID*/

No reference may be made to both a
structure and an array of structures in the
same expression or assignment.
Example:

structure and Ar'ray Expressions
The le"el of nesting in structure and array
expressions is limited' by the following
rule:
FOl:- each level of nesting of structure
or array expressions, add 2 for the
maximum number of dimensions in the
stJcucture or array, add 2 for the
ma~dmum level in a structure
expression, add 3 for each subscript or
arqument list in the expression or
assignment., and finally, add 15.
The tot.al for the whole nest should not
exceed 900 ..

DCL 1 A(10), 2 B, 2 C,
1 F(10), 2 B~ 2 C,
1 p" 2 Q, 2 R;
A=P;
A=F;
A(I)=P;
A=F. BY NAME:
A=F(I), BY NAME:

/*INVALID*/
/*VALID*/
/*VALID*/
/*VALID*/
/*INVALID*/

TITLE Option
If the TITLE option specified exceeds eight
characters, then the first eight are used.
If there is no TITLE option. the file name
(padded or truncated to eight characters)
is used as the ddname.

structures
TRANSIENT Attribute
NO refE:!rences can be made to cross sections
of arrays of structures; the whole of an
array of structures may be referenced, or a
single element of the array may be
referenced, but not a cross section ..

The following rules apply specifically to
the use of TRANSIENT with the (F) compiler:
1.

The TRANSIENT attribute can be
specified only for RECORD KEYED
BUFFERED files with either the INPUT
or the OUTPUT attribute.

2.

The ENVIRONMENT attribute with one of
the two teleprocessing format options
(G and R) must be declared for
TRANSIENT files.

3.

Input can be specified only by a READ
statement with the KEYTO option and
either the INTO option or the SET
option.

DCL EV~['(10,10,2) EVENT;
WAIT (EVIl') 200;
/*VALID*/
WAIT(EVT(I,J,2» 100:
/*VALID*/
WAIT(EVI'(l,*,l» 10:
/*INVALID*/

4.

output can be specified only by a
WRITE statement or a LOCATE statement,
either of which must have the KEYFROM
option.

No structure or array of structures may
be passed as an argument to either a
built-in function (except STRING, ADDR, and

5.

The EVENT option is not permitted
since TRANSIENT files are always
BUFFERED.

ExamplE~:

DCL 1 A(10,10), 2 B, 2 C(10,10);
DCL 1 X ( 1 0), 2 Y, 2 Z ( 10" 1 0) ;
A (* ,J) ==X;

A=A+l;
A (I, J) ==X ( I) ;

/*INVALID*/
/*VALID*/
/*VALID*/

A cross-section of an EVENT array is not
permitt.ed to appear in a WAIT statement ..
ExamplE~:

Appendix J: Implementation Conventions and Restrictions

309

6.

The 'data set' associated with a
TRANSIENT file is in fact a queue of
messages maintained automatically in
main storage by a separate message
control program using the QTAM (Queued
Telecommunications Access Method)
facilities of the operating system.
The queue is always accessed
s equentiall y •

7.

The name 01: title of a TRANSIENT INPUT
file must be the name of a recognized
queue set up by the message control
program. For TRANSIENT OUTPUT files,
any name can be declared, since the
file is reassociated for each output
operation with a queue determined by
the terminal name.

8.

The element expression specified in
the KEYFROM option must have as its
value a recognized terminal or process
queue identification.

Variables
The maximum number of variables in -the
source program depends on the total size of
the dictionary, which (for NOEXTDIC) is
restricted to approximately 65,000 bytes.
This is equivalent t~ a restriction of
roughly 1,200 variables for a scientific
user and to 1,000 for a commercial user.
In computing these figureas a reasonable
allowance has been made for constants,
statement labels, and other items which may
require dictionary entries.

identifier, macro label, and unique
compile-time constant. In addition, two
dictionary entries are created for each
iterative DO, one for each THEN or ELSE
clause, and one for each compile-time
procedure. Error message references are
also entered into the dictionary. The
dictionary is cleared at the end of
compile-time processing; it is therefore
unnecessary to keep the above
considerations in mind if estimating
available dictionary space during actual
program compilation. Under EXTDIC the
number of variables can be increased by a
factor of 1.5 for 1K blocks, or 3.5 for
larger block sizes.

VARYING Attribute
The only form of 'varying strings permitted
in the INTO or FROM options in RECORD I/O
are unsubscripted level 1 varying strings
that are not members of arrays or
structures.

Varying Strings passed as Arguments
If a structure passed as an argument
includes a varying string, the length of
the string cannot be changed within the
invoked procedure unless a dummy argument
is created.
Example:

If the EXTDIC option is specified, the
maximum size of the dictionary is
approximately 1.5 times 65,000 bytes for a
block size of 1K, and approximately 3.5
times 65,000 bytes for other block sizes.

DCL 1 P(lO),
2 Q(10),
3 R FIXED(5,0),
3 S CHAR(S) VAR,
2 T FlXEO(5,0);

The figures for variables are
necessarily approximate, since the size of
a dictionary entry varies with the type of
variable, length of identifier, whether it
is a structure element, and so on.

CALL PROC1(P.Q(4,4»;
CALL PROC1(P.Q,4,4);

Variables at Compile-Time

WAIT Statement

The maximum number of compile-time
variables which can be used in a program
depends on the total size of the
dictionary, which (for NOEXTDIC) is
restricted to 65,000 bytes. Assuming an
?l,verage dictionary entry size of 28 bytes,
this restricts the processor to
approximately 2,300 items. An entry is
~ade in the dictionary for each macro
variable, macro procedure name, INCLUDE

If the user wishes to specify more than onte
event name in a WAIT statement, the
multiple-wait option must have been
specified at SYSGEN time.

310

/*INVALID*/
I*VALID; ARRAY OF
STRUCTURES PASSED
WITH REQUIRED
SUBSCRIPTS*/

If a WAIT statement is executed and the
events requited to satisfy the WAIT contain
a mixture of 1/0 and non-I/O events all
non-I/O events will be set complete before
any of the 1/0 events.

4 8-Chal~acter Set

is undefined and may not, therefore, be
what the user intended.

48-character set 'reserved' words (e.g.,
GET, Ll~, CAT, etc.,) must be preceded and
followed by a blank or a comment. If they
are not:, the interpretation by the compiler

A record containing part or all of a
48-character-set reserved word must be 3
characters or more in length.

Appendix J: Implementation Conventions and Restrictions

311

312

Appendix K:

Source! Program Diagnostic Messages
All

so,~ce program diagnostic messages
producE~d are written in a group following

the sOlttce program listing and any other
listin9s specified as a par.ameter on the
EXEC s1:.atement card.
Each message number is of the form
IEMnnnnI, where the code IEM indicates the
PL/I (]!') compiler, and nnnn the number of
the message. The letter I is a system
standal:d action code indicating an
informative message for the programmer.
TheJce are four types of diagnostic
warning, error, severe error, and
termination error.
messag~:!:

A W(~rninq is a message that calls
attention to a possible error, although the
statemE;!nt to which it refers is
syntac1:.ically valid. In addition to
alerting the programmer, it may assist him
in writ'.ing more efficient programs in the
future ..
An ]!:rror message describes an attempt to
correc1:. an erroneous statement; the
programmer is informed of the correction.
Errors do not normally terminate processing
of the text.
A S4:!vere error message indicates an
error lliThich cannot be corrected by the
compiI4~.
The incorrect section of the
program is deleted, but compilation is
continued. Where reasonable, the ERROR
condition will be raised at object time, if
execution of an incorrect source statement
is att4~mpted.

T4:!rmination error message describes an
error 1M'hich, when discovered, forces the
termination of the compilation.
A

The choice of the severity level at and
above 1M'hich diagnostic messages appear on
the out,put is an option which may be
select4~d by the programmer.
FLACW is
assumed if no level is specified.
In t:he list of diagnostic messages
below, the abbreviations W, E, 5, and T,
respectively, are used to indicate the
severit.y of the message, and appear
immediately before the number of the
messag~e.
They do not appear in this way in
the compiler output listings; instead, the
messag~es are printed in separate groups
according to severity.

Diagnostic Messages

In the following·text, messages are
followed where necessary by an explanation,
a description of the action taken by the
system, and the response required from the
user. "Explanation" and "System Action"
are given only when this information is not
contained in the text of the message. When
no "Programmer Response" is stated
explicitly, the p~ogrammer should assume
that he must correct the error in his
source program unless the action taken by
the system makes it unnecessary for him to
do so. Rowever, even when system action
successfully corrects an error, the
programmer should remember that if he
subsequently recompiles the same program,
he will get the same diagnostic message
again unless he has ~orrected the source
error.
If a problem arises in using the PL/I
(F) Compiler, do the following before
calling IBM for programming support:
• If the compiler preprocessor has been
used and the problem occurs in the
processor stage, use the 'MACDK' option
to obtain the macro deck output; this
ensures that source code from INCLUDE
libraries is available. Otherwise,
retain the source input to the
compiler.
(Note: if the problem occurs
in the preprocessor stage, ensure that
all source data in libraries as well as
the primary input is available.)
• Obtain listings of SYS1.LINKLIB and of
SYS1.PL1LIB, and listings of program
temporary fixes (PTF's) using lMAPTFLS
against these libraries.
• Specify MSGLEVEL=(l,l) on the job
statement.
• Include a SYSUDUMP DO statement for the
failing job step.
• If the problem is associated with a
compiler termination message, recompile
with compiler options 'S,DP=(PIE,ZZ)'
to obtain a formatted dump of the
compiler.
It may be necessary to override the
default queue space for SYSOUT for the
SYSPRINT data set in order to prevent a
'B37' ,abend.
Not~

e.g.

//PL1L.SYSPRINT DO SYSOUT=A,
SPACE=(629,(2000,20»
Appendix K: Diagnostic Messages

313

E IEM00021

INVALID PREFIX OPERATOR IN
STATEMENT NUMBER xxx. REPLACED
BY PLUS.

• Have the source program
listing available.
S IEM00011

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following beforE~
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00031

RIGHT PARENTHESIS INSERTED IN
STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs" do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00081

OPERATOR. NOT.
IN STAT]~MENT
NUMBER xxx USED AS AN INFIX
OPERATOR. IT HAS BEEN REPLACED
BY .NE.
programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
W IEM00091

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

RIGHT PARENTHESIS INSERTED
AFTER SINGLE PARENTHESIZED
EXPRESSION IN STATEMENT NUMBER
xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

E IEM00061

314

A LETTER IMMEDIATELY FOLLOWS
CONSTANT IN STATEMENT NUMBER
xxx. AN INTERVENING BLANK IS
ASSUMED~

• Have the source program
listing available.
E IEM00051

RIGHT PARENTHESIS INSERTED AT
END OF CALL ARGUMENT LIST OR
OTHER EXPRESSION LIST IN
STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00041

IDENTIFIER MISSING IN STATEMEN~L
NUMBER xxx. A DUMMY
IDENTIFIER HAS BEEN INSERTED.

• Have the source program
listing available.
E IEM00101

IMPLEMENTATION RESTRICTION.
IDENTIFIER yyyy IN OR NEAR
STATEMENT NUMBER xxx IS TOO
LONG AND HAS BEEN SHORTENED.
Explanation:
Implementation
restriction. Identifiers may
not exceed 31 characters in
length.

RIGHT PARENTHESIS INSERTED AT
END OF SUBSCRIPT, ARGU~NT OR
CHECK LIST IN STATEMENT NUMBER
xxx

§ystem Action: Identifier has
been shortened by concatenating
first 16 characters with last
15.

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source p~ogram
listing available.
W IEM00111

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

CONSTANT IMMEDIATELY FOLLOWS
IDENTIFIER IN STATEMENT NUMBER
xxx. AN INTERVENING BLANK IS
ASSUMED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have ,the source program
listing available.
E IEM00161

• Have the source program
listing available.
E IEM00121

Programmer Response: Probable
user errore correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

EXPONENT MISSING IN
FLOATING-POINT CONSTANT
BEGINNING yyyy IN STATEMENT
NUMBER xxx. ZERO HAS BEEN
INSERTED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00171

INTEGER yyyy TOO LONG IN
STATEMENT NUMBER xxx. IT HAS
BEEN TRUNCATED ON THE RIGHT.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00181

EXPONENT TOO LONG IN
FLOATING-POINT CONSTANT
BEGINNING yyyy IN STATEMENT
NUMBER xxx. IT HAS BEEN
TRUNCATED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following·before
calling IBM for programming
support:
• Have the source program
listing·available.

E IEM00151

SOLITARY DECIMAL POINT FOUND IN
OPERAND POSITION IN STATEMENT
NUMBER xxx. A FIXED-POINT
ZERO HAS BEEN INSERTED.

ZERO INSERTED IN PENCE FIELD OF
STERLING CONSTANT BEGINNING
yyyy IN STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00141

ZERO INSERTED IN FLOATING-POINT
CONSTANT BEGINNING .E IN
STATEMENT NUMBER xxx
Programmer Response: Probable
user error. correct program
and recompile. If the problem
recurs r do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00131

FLOATING-POINT CONSTANT
BEGINNING yyyy IN STATEMENT
NUMBER xxx IS TOO LONG AND HAS
BEEN TRUNCATED ON THE RIGHT.

• Have the source program
listing available.
EIEM00191

POUNDS FIELD IN STERLING
CONSTANT BEGINNING yyyy IN
STATEMENT NUMBER xxx IS TOO
LONG AND HAS BEEN TRUNCATED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

Appendix K: Diagnostic Messages

315

E IEM00201

calling IBM for programming
support:

ZERO INSERTED IN POUNDS FIE:LD
OF STERLING CONSTANT BEGINNING
yyyy IN ST~TEMENT NUMBlffi xxx

• Have the source program
listing available.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs" do the following before
calling IBM for programming
support:

E IEM00251

Programmer Response: ProbablE!
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00211

DECIMAL POINT IN EXPONENT FIELD
OF CONSTANT BEGINNING yyyy IN
STATEMENT NUMBER xxx. FIE:LD
TRUNCATED AT DECIMAL POINT.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00261

DECIMAL PENCE TRUNCATED IN
STERLING CONSTANT BEGINNING
yyyy STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs" do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00271

LETTER L MISSING FROM STERLING
CONSTANT BEGINNING yyyy IN
STATEMENT NUMBER xxx
system Action:

None

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM00281

SHILLINGS FIELD TRUNCATED IN
STERLING CONSTANT BEGINNING
yyyy IN STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If -the problem
recurs, do the following before

316

LABEL REFERENCED ON END
STATEMENT NUMBER xxx CANNOT BE
FOUND. END TREATED AS HAVING
NO OPERAND.
Programmer Response: ProbablE!
user error. Correct program
and recompile. If the problem
recurs-~ do the following befol~e
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00241

FIXED-POINT CONSTANT BEGINNING
yyyy IN STATEMENT NUMBER xxx
HAS BEEN TRUNCATED ON THE
RIGHT.
Programmer Response: ProbablE~
use~ error.
Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00231

ILLEGAL CHARACTER IN APPARENT
BIT STRING yyyy IN STATEMENT
NUMBER xxx.
STRING TREATED J~
A CHARACTER STRING.
Eroqrammer Response: ProbablE!
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00221

ZERO INSERTED IN SHILLINGS
FIELD OF STERLING CONSTANT
BEGINNING yyyy IN STATEMENT
NUMBER xxx

• Have the source program
listing available.
S IEM00291

INVALID CHARACTER IN BINARY
CONSTANT IN STATEMENT NUMBER

calling IBM for programming
support:

xxx. CONSTANT TREATED AS
DECIMAL CONSTANT.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
.

• Have the source program
listing available.
W IEM003L~I

• Have the source program
listing available.
S IEM0030I

Proqrammer Response: Probable
user error. Check that the
system action will have the
required effect. If the
problem recurs, do the
following before calling IBM
for programming support:

POINTER QUALIFIER FOLLOWS
EITHER A SUBSCRIPT OR ANOTHER
POINTER QUALIFIER IN STATEMENT
NUMBER xxx.
System Action: As stated in a
further message referring to
the same statement.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs" do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM0035I

OPERAND MISSING IN OR FOLLOWING
STATEMENT NUMBER xxx. DUMMY
OPERAND INSERTED.

• Have the source program
listing available.

~anation:

something invalid
has been found in an
expression, or where an
expression was expected but no·t
found.
In order that further
diagnosis can be made, the
compiler has inserted a dummy
operand. This may cause
further error messages to
appear for this statement.

E IEM0037I

• Have the source program
listing available.
E IEM0038I

E IEM0033I

AN INVALID PICTURE CHARACTER
IMMEDIATELY FOLLOWS TEXT yyyy
IN STATEMENT NUMBER xxx. THE
PICTURE HAS BEEN TRUNCATED AT
THIS POINT.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before

ZERO INSERTED IN SCALING FACTOR
IN PICTURE yyyy IN STATEMENT
NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

LETTER F IS NOT FOLLOWED BY
LEFT PARENTHESIS IN PICTURE IN
STATEMENT NUMBER xxx. ONE HAS
BEEN INSERTED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM0031I

A LETTER IMMEDIATELY FOLLOWS A
CONSTANT AT nnnn SEPARATE
POSITION(S> IN STATEMENT NUMBER
xxx. AN INTERVENING BLANK HAS
BEEN ASSUMED IN EACH CASEa

RIGHT PARENTHESIS INSERTED
AFTER SCALING OR REPLICATION
FACTOR IN PICTURE yyyy IN
STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

Appendix K: Diagnostic Messages

317

E IEM00391

NO CHARACTER FOLLOWS
REPLICATION FACTOR IN PICTURE
yyyy IN STATEMENT NUMBER xxx.
THE PICTURE HAS BEEN TRUNCATED
AT THE LEFT PARENTHESIS OF THE
REPLICATION FACTOR.

• Have the source program
listing available.
E IEM00451

Programmer Response: Probablfe
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Respo~ Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programmdng
support:

• Have the source program
listing available.

• Have the source program
listing available.
E IEM00401

A REPLICATION FACTOR OF 1 HAS
BEEN INSERTED IN PICTURE yyyy
IN STATEMENT NUMBER xxx

E IEM00461

• Have the source program
listing available.

• Have the source program
listing available.
RIGHT PARENTHESIS INSERTED IN
STATEMENT NUMBER xxx

E IEM00481

Explanation: Right parenthesis
missing from length attached to
character or bit string.

E IEM00441

IN STATEMENT NUMBER XX:K
PRECISION NOT AN INTEGER
Explanation: Precision should
be an un~igned integer
system Action: The ac·tion
taken depends on whether the
precision is found in a DECLARE
statement or a PROCEDURE
statement. A further message
will be produced.
Programmer Response: Probable
user error. Correct program
and recompile. I.f the problem
recurs, do the following before
calling IBM for programming
support:

318

RIGHT PARENTHESIS INSERTED IN
FILE NAME LIST IN STATEMENT
NUMBER xxx
Programmer Response: Probablfe
user error. Correct program
and :recompile. If the problem
recurs, do the following befo:re
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

RIGHT PARENTHESIS INSERTED
AFTER PRECISION SPECIFICATION
IN STATEMENT NUMBER xxx
Prog:rammer Response: Probablfe
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

S IEM00431

ZERO INSERTED IN FIXED
PRECISION SPECIFICATION IN
STATEMENT NUMBER xxx

• Have the source program
listing available.
E IEM00491

THE COMMENT FOLLOWING THE
LOGICAL END OF PROGRAM HAS NOT
BEEN TERMINATED.
Explanation: A /* was found
following the logical end of
the program and was interpret fed
as the start of a comment, but
end-of-file was reached beforle
the comment was terminated.
system Action: All text
following the/* is read as a
comment.
Programmer Response: Probabl1e
user error. Check if this is a
delimiter in the wrong column
of the record. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM00501

INVALID STATEMENT LABEL
CONSTANT IN LABEL ATTRIBUTE IN
STATEMENT NUMBER xxx. THE
STATEMENT LABEL CONSTANT LIST
HAS BEEN DELETED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
W IEM00551

Programmer Response:' Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
W IEM00511

MISSING RIGHT PARENTHESIS
INSERTED FOLLOWING STATEMENT
LABEL CONSTANT IN LABEL
ATTRIBUTE IN STATEMENT NUMBER
xxx
Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00561

INVALID ATTRIBUTE IN RETURNS
ATTRIBUTE LIST IN STATEMENT
NUMBER xxx. THE INVALID
ATTRIBUTE HAS BEEN DELETED FROM
THE LIST.
Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
E IEM00571

• Have the source program
listing available.
W IEMO Cl531

SURPLUS COMMA HAS BEEN FOUND IN
DECLARE OR ALLOCATE STATEMENT
NUMBER xxx. THIS COMMA HAS
BEEN DELETED.

S IEM00541

ILLEGAL FORM OF CALL STATEMENT.
STATEMENT NUMBER xxx DELETED.

INVALID CHARACTER FOLLOWING
ITERATION FACTOR IN PICTURE
BEGINNING yyyy IN STATEMENT
NUMBER xxx. THE PICTURE HAS
BEEN TRUNCATED AT THE LEFT
PARENTHESIS OF THE ITERATION
FACTOR.
Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

NULL PICTURE FORMAT ITEM IN
STATEMENT NUMBER xxx. THE
CHARACTER 9 HAS BEEN INSERTED
IN THE PICTURE.
Explanation:
The null picture
may be the result of the
compiler truncating an invalid
picture.

• Have the source program
listing available.
S IEM00521

LABEL OR LABELS ON DECLARE
STATEMENT NUMBER xxx HAVE BEEN
IGNORED.

• Have the source program
listing available.
E IEM00581

ITERATION FACTOR IN PICTURE
BEGINNING yyyy NOT AN UNSIGNED
INTEGER IN STATEMENT NUMBER
xxx. THE PICTURE HAS BEEN
TRUNCATED AT THE LEFT

Appendix K: Diagnostic Messages

319

alignment defaults will be
compa'tible with those of
earlier versions of the
compiler., except for bit string
arrays that are not members of
structures.

PARENTHESIS OFTSE ITERATION
FACTOR.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct source,
and recompile if necessary. If
the problem recurs, do the
following before calling IBM
for programming support:

• Have the source program
listing available.
E IEM00591

MISSING RIGHT PARENTHESIS
INSERTED IN POSITION ATTRIBUTE
IN STATEMENT NUMBER xxx.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs. do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00631

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM0060I

POSITION MISSING IN POSITION
ATTRIBUTE IN STATEMENT NUMBER
xxx.
POSITION OF 1 INSERTED.
Programmer Respop~ Probable
user error. Correct program
and recompile. If the problem
recurs, do the,fo110wing before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM00641

MISSING LEFT PARENTHESIS
INSERTED IN POSITION AT'TRIBUTE
IN STATEMENT NUMBER xxx.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
'

• Have the source program
listing available.
E IEM00671

THE ATTRIBUTE • PACKED' IN
DECLARATION STATEMENT NUMBER
xxx IS NOW OBSOLETE, AND HAS
BEEN IGNORED.

• Have the source program
listing available.
T IEM00691

Explanation:
PACKED has been
removed from the language: the
complementary attribute to
ALIG~ED is now UNALIGNED.
system Action:. ,since PACKED
applied only td~rrays and
major structures, the new
320

EQUAL SYMBOL HAS BEEN INSERTED
IN DO STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following befor,e
calling IBM for programming
support:

• Have the source program
listing avai.lab1e.

W IEM00621

ILLEG.AL STATEMENT FOLLOWS THE
THEN IN STATEMENT NUMBER xxx.
SEMICOLON HAS BEEN INSERTED
AFTER THE THEN.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following befor,e
calling IBM for programming
support:

• Have the source program
listing available.
E IEM00611

MISSING LEFT PARENTHESIS
INSERTED IN RETURNS STATEMENT
NUMBER xxx.

IMPLEMENTATION RESTRICTION.
SOURCE PROGRAM CONTAINS TOO
MANY BLOCKS.
System Action:
terminated

Compilation is

Programmer Response: Probable
user error. Rewrite program

with fewer blocks, or divide
into more than one separate
compilation. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the associated job
stream and source program
listing available.
S IEM00721

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the .following before
calling IBM for programming
support:

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)
• Have the associated job
stream and source program
listing available.
T IEM00701

• Have the source program
listing available.
E IEM00741

BEGIN STATEMENT NUMBER xxx IS
NESTED BEYOND THE PERMITTED
LEVEL. COMPILATION TERMINATED.

• Have the source program
listing available.
S IEM00751

TOO MANY PROCEDURE, BEGIN,
ITERATIVE 00, ON. STATEMENTS IN
THIS PROGRAM. COMPILATION
TERMINATED.

• Have the source program
listing available.
S IEM00761

• Recompile the program with
compiler options
'S,DP=(PIE~ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

NO STATEMENT FOLLOWS ELSE IN OR
FOLLOWING STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

Explanation: There is an
implementation restriction on
the number of blocks in a
compilation. Refer to Appendix
J of this publication for
details.
Programmer Response: Probable
user error. subdivide program
into two or more compilations.
If the problem recurs, do the
following before calling IBM
for programming support:

NO STATEMENT FOLLOWS THEN IN IF
STATEMENT NUMBER xxx
Programmer Response:
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the associated job
stream and source program
listing available.
T IEM00711

THEN INSERTED IN IF STATEMENT
NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Reduce level of
nesting of blocks to 50 or
less. If the problem recurs,
do the following before calling
IBM for programming support:
• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IE~nnnnI messages.)

DO STATEMENT NUMBER xxx
REPLACED BY BEGIN STATEMENT.

• Have the source program
listing available.
S IEM00771

ELSE DELETED IN OR FOLLOWING
STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

Appendix K: Diagnostic

Mess~ges

321

E IEM007BI

IMPLEMENTATION RESTRICTION.
TOO MANY CHARACTERS IN INITIAL
LABEL ON STATEMENT NUMBER xxx.
LABEL IGNORED.

S IEMOOB31

System Action: ON ERROR
inserted in place of invalid
condition

Explanation: There is an
implementation restriction on
the number of character:s in the
subscript of a subscripted
identifier. The maximum
permissible number is 225.

Pr.ogrammer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following befor1e
calling IBM for programming
support:

Programmer Response: P:robable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.

• Have the source program
listing available.
E IEMOOB41
E IEMOOBOI

EQUAL SYMBOL HAS BEEN INSERTED
IN ASSIGNMENT STATEMENT NUMBER
xxx

THE 1/0 ON-CONDITION IN
STATEMENT NUMBER xxx HAS NO
FILENAME FOLLOWING IT. SYSIN
IS ASSUMED.

Programmer Respo~~ Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

• Have the source program
listing available.
S IEMOOB11

LABELS OR PREFIX OPTIONS BEFORE
ELSE TRANSFERRED TO STATEMENT
NUMBER xxx

E IEMOOB51

Explanation: Labels or prefix
options illegal before ELSE and
therefore transferred to
following statement.

• Have the source program
listing available.
T IEM00901

• Have the source program
listing available.
OPERAND MISSING IN CHECK LIST
IN OR FOLLOWING STATEMENT
NUMBER xxx. DUMMY INSERTED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
322

COLON MISSING AFTER PREFIX
OPTION IN OR FOLLOWING
STATEMENT NUMBER xxx. ONE HAS
BEEN ASSUMED.
Programmer Response: Probable
user errore Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

S IEMOOB21

ON-CONDITION INVALID OR MISSING
IN STATEMENT NUMBER xxx. ON
ERROR HAS BEEN ASSUMED.

THERE ARE NO COMPLETE
STATEMENTS IN THIS PROGRAM.
COMPILATION TERMINATED.
Programmer Response: Probable
user error. If the problem
recurs, do the following before
calling IBM for programming
support:
• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

• Have the associated job
stream and source program
listing available.
W IEM0094I

RECORD IN OR FOLLOWING
STATEMENT NUMBER xxx IS SHORTER
THAN THE SPECIFIED SOURCE
START. THE OUTPUT RECORD HAS
BEEN MARKED WITH AN ASTERISK
AND IGNORED.

• Have the source program
listing available.
S IEM0099I

Explanation: Although the
compiler has detected the end
of the program, there is more
text following it. The
programmer appears to have made
an error in matching END
statements with PROCEDURE,
BEGIN, DO or ON statements.

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
E IEMO()95I

~stem

Action: The END
statement is ignored

LABEL ON STATEMENT NUMBER xxx
HAS NO COLON. ONE IS ASSUMED '"

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

Explanation: The compiler has
encountered an identifier which
appears to be a statement
label, but without a colon.
system Action:
inserted

A colon is

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs" do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM0100I

END OF FILE FOUND IN OR AFTER
STATEMENT NUMBER xxx, BEFORE
THE LOGICAL END OF PROGRAM.
system Action:
If the
statement is incomplete, it is
deleted. Whether or not the
statement is incomplete, the
required number of END
statements are added to the
program so that compilation can
continue.

• Have the source program
listing available.
E IEM0096I

LOGICAL END OF PROGRAM OCCURS
AT STATEMENT NUMBER xxx. THIS
STATEMENT HAS BEEN IGNORED SO
THAT SUBSEQUENT STATEMENTS MAY
BE PROCESSED.

SEMI-COLON NOT FOUND WHEN
EXPECTED IN STATEMENT NUMBER
xxx. ONE HAS BEEN INSERTED.

Programmer Response: Probable
user error. Correct the source
code. possible causes of this
error include:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

1.

Unmatched quote marks

2.

Insufficient END
statements

3.

Omission of final
semicolon.

• Have the source program
listing available.
E IEM0097I

INVALID ,CHARACTER HAS BEEN
REPLACED BY BLANK IN OR
FOLLOWING STATEMENT NUMBER xxx.
THE CONTAINING OUTPUT RECORD IS
MARKED BY AN ASTERISK.
Programmer Response: probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

If the problem recurs, do the
following before calling IBM
for programming support:
• Have the source program
listing available.
S IEM0101I

PARAMETER MISSING IN STATEMENT
NUMBER xxx. A DUMMY HAS BEEN
INSERTED.

~ppendix

K: Diagnostic Messages

323

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

T IEM01061

IMPLEMENTATION RESTRICTION.
SOURCE PROGRAM CONTAINS TOO
MANY BLOCKS.
system Action:
terminated

compilation is

• Have the source program
listing available.
S IEM01021

Programmer Response: Probable
user error. Rewrite program
with fewer blocks, or divide
into more than one separate
compilation. If the problem
recurs" do the following before
calling IBM for programming
support:

LABEL MISSING FROM PROCEDURE
STATEMENT NUMBER xxx. A DUMMY
LABEL HAS BEEN INSERTED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Recompile the program with
compiler options
·S,DP=(PIE.ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

• Have the source program
listing available.
S IEM01031

LABEL MISSING FROM ENTRY
STATEMENT NUMBER xxx
programmer Response: Probable
user error. correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the associated job
stream and source program
listing available.
T IEM01071

• Have the source program
listing available.
S IEM01041

Programmer Response: ProbablE~
user error. subdivide
statement and recompile. If
tHe problem recurs, do the
following before calling IBM
for programming support:

ILLEGAL STATEMENT FOLLOWS ELSE
IN STATEMENT NUMBER xxx
System Action:
inserted

Null statement

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Recompile the program with
compiler options
'S,DP=(PIE.ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

• Have the source program
listing available.
S IEM01051

• Have the associated job
stream and source program
listing available.

ILLEGAL STATEMENT FOLLOWS ON IN
STATEMENT NUMBER xxx
S IEM01081
system Action:
inserted

Null statement

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs,. do ,the following before
calling IBM for programming
suppo+t:
• Have the source program
listing available.
324

IMPLEMENTATION RESTRICT~N.
STATEMENT NUMBER XXX f I5 ~OO
LONG,. THIS STATEMEN(I' MAY
CONTAIN UNMATCHED QUOTE MARKS ..

ENTRY STATEMENT NUMBER xxx IN
AN ITERATIVE DO GROUP HAS BEEN
DELETED.
Programmer Response: Probabl.e
user error. Correct program
and :recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
"
• Have the source program
listing available.

S IEMOl.091

Programmer Response: P~obable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

TEXT BEGINNING yyyy IN OR
FOLLOWING STATEMENT NUMBER xxx
HAS BEEN DELETED.
Explanation: The source error
is detailed in another message
referring to the same
statement.
Programmer Response: Probable
user error. Correct program
,{;lnd recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEMOl151

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM01111

FIRST STATEMENT NOT A PROCEDURE
STATEMENT. A DUMMY PROCEDU~E
STATEMENT HAS BEEN INSERTEp'.

• Have the source program
listing available.
E IEM01161

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
•
S IEM01:l21

program
ava1lable.

t

ENTRY STATEMENT NUMBER xxx IN
BEGIN BLOCK HAS BEEN DELETED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEMOl171

RIGHT PARENTHESIS INSERTED IN
STATEMENT NUMBER xxx
Explanation:
Parenthesized
list in ON statement is either
not closed or contains an error
and has been truncated.

• Have the source program
listing available.
S IEMOl181

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
E IEMOl1.41

RIGHT PARENTHESIS INSERTED IN
PREFIX OPTION IN OR FOLLOWING
STATEMENT NUMBER xxx

DATA ATTRIBUTE LIST IN
PROCEDURE OR ENTRY STATEMENT
NUMBER xxx IS NOT PRECEDED BY
RETURNS ATTRIBUTE AND IS NOT
PARENTHESIZED.
RETURNS AND
PARENTHESES HAVE BEEN ASSUMED.
Programmer Response:
Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM01:ll31

PREFIX OprION FOLLOWS LABEL IN
STATEMENT NUMBER xxx. PREFIX
OPTION IS IGNORED.
Programmer Response:
Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

H~ve.tpe ~o~rce
l1st1~g

LEFT PARENTHESIS INSERTED AFTER
WHILE IN STATEMENT NUMBER xxx

OFFSET ATTRIBUTE NOT FOLLOWED
BY PARENTHESIZED BASED VARIABLE
IN STATEMENT NUMBER xxx. THE
ATTRIBUTE IS IGNORED.
Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

Appendix K: Diagnostic Messages

325

E IEMOl191

PARENTHESIS.
ASSUMED.

THE RETURNS ATTRIBUTE IN
PROCEDURE OR ENTRY STATEMENT
NUMBER xxx IS NOT FOLLOWED BY A
PARENTHESIZED DATA ATTRIBUTE
LIST. RETURNS HAS BEEN
IGNORED.

Programmer Respons e: ProbablE!
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer R~nse: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
E IEM01201

• Have the source program
listing available.
S IEM01241

DATA ATTRIBUTE LIST FOLLOWING
RETURNS IN PROCEDURE OR ENTRY
STATEMENT NUMBER xxx IS NOT
PARENTHESIZED. PARENTHESES
HAVE BEEN ASSUMED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM01251

System Action:
ignored.

• Have the source program
listing available.
S IEM01261

THE ATTRIBUTE NORMAL OR
ABNORMAL IN STATEMENT NUMBER
xxx IS OBSOLETE AND HAS BEEN
IGNORED.

• Have the source program
listing available.

• Have the source program
listing available.
S IEM0127I

326

IMPLEMENTATION RESTRICTION.
STATEMENT NUMBER xxx HAS TOO
MANY ERRORS TO BE INTERPRETED.,
THE STATEMENT HAS BEEN DELETED.
Programmer Response: ProbablE~
user errors. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs. do the following before
calling IBM for programming
support:

THE DATA ATTRIBUTE LIST IN
PROCEDURE OR ENTRY STATEMENT
NUMBER xxx HAS NO CLOSING

The label is

Programmer Response: ProbablE~
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.

E IEM0123I

INVALID USE OF LABEL yyy ON
ON-UNIT BEGINNING AT S TATE MEm?
xxx. LABEL HAS BEEN DELETED.
Explanation: An on-unit cannot
be referenced by a label.

THE ATTRIBUTE USES OR SETS IN
STATEMENT NUMBER xxx IS
OBSOLETE AND HAS BEEN IGNORED
TOGETHER WITH ITS PARENTHESIZED
ITEM LIST.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
.,

E IEM01221

INVALID ATTRIBUTE IN DECLARE OR
ALLOCATE STATEMENT NUMBER xxx.,
ATTRIBUTE TEXT DELETED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM01211

ONE HAS BEEN

INVALID TEXT IN PREFIX OPTIONS
THE TEXT BEGINNING yyy
TO THE END OF THE OPTIONS LIs~r
HAS BEEN IGNORED.

LIST~

and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
S IEM01.281

• Have the source program
listing available.
S IEM01341

LENGTH OF BIT OR CHARACTER
STRING MISSING IN STATEMENT
NUMBER xxx. LENGTH 1 INSERTED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
re!curs, do the following before
calling IBM for programming
support:

Explanation: The
implementation restriction on
levels of nesting has been
contravened. For details,
refer to Appendix J of this
publication.

• Have the source program
listing available.
S IEM01291

Programmer Response: Probable
user error. Rewrite INITIAL
attribute with lower level of
replication. If the problem
recurs, do the following before
calling IBM for programming
support:

INVALID WAIT STATEMENT NUMBER
xxx DELETED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM01351

• Have the source program
listing available.
E IEM01301

OPERAND MISSING. COMMA DELETED
IN WAIT STATEMENT NUMBER xxx

S IEM0131I

RIGHT PARENTHESIS INSERTED IN
STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

S IEM01321

DUMMY OPERAND INSERTED IN
STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program

AN EXPRESSION APPEARS ILLEGALLY
ON THE LEFT HAND SIDE OF AN
ASSIGNMENT STATEMENT.
STATEMENT DELETED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer.Response: probable
user error. Correct program
and recompile'. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

IMPLEMENTATION RESTRICTION.
TOO MANY LEVELS OF REPLICATION
IN INITIAL ATTRIBUTE IN
STATEMENT NUMBER xxx. THE
ATTRIBUTE HAS BEEN DELETED.

• Have the source program
listing available.
E IEM0136I

'IN' CLAUSE IN STATEMENT NUMBER
xxx HAS NO ASSOCIATED 'SET'
CLAUSE.
Explanation: An IN clause must
be accompanied by a SET clause
in the same statement.
system Action:
is ignored

The IN clause

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
Appendix K: Diagnostic Messages

327

E IEM01381

.§ystem Action:
assumed ..

SOLITARY I FOUND WHERE A
CONSTANT IS EXPECTED IN INITI~L
ATTRIBUTE IN STATEMENT NUMBER
xxx.
FIXED DECIMAL IMAGINARY
11 HAS BEEN ASSUMED.

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Explanation: The programmer
has initialized an element
using the variable I where the
constant 11 was expected.
System Action:

• Have the source program
listing available.

11 is assumed

Programmer.Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

S IEM01441

TEXT IMMEDIATELY FOLLOWING yyyy
IN INITIAL ATTRIBUTE IS
ILLEGAL. INITIAL ATTRIBUTE
DELETED IN STATEMENT NUMBER xxx
Explanation: A language
feature has been used that is
not supported by this version
of the compiler. For details,
refer to Appendix J of this
publication. Although the
message states that the error
follows the quoted text, the
quoted text may itself be
invalid, and the compiler may
have attempted to correct the
source error. In this case,
there will usually be another
diagnostic message associated
with the statement.

• Have the source program
listing available.
S IEM01451

• Have the source program
listing available.
W

IEM01401

328

DUMMY IDENTIFIER INSERTED IN
GENERIC ATTRIBUTE LIST IN
STATEMENT NUMBER xxx
Programmer Response: ProbablE!
user error. correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

S IEM01411
Programmer Response: Probable
user error.
Correct program
and recompile. If the problem
recurs, do the following be:fore
calling IBM for programming
support:

RETURNS ATTRIBUTE IS NOT
FOLLOWED BY A DATA DESCRIPTION
IN STATEMENT NUMBER xxx. THE
RETURNS ATTRIBUTE HAS BEEN
DELETED.
Programmer Response:
Probable!
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM01391

Null statement

THE USE OF REFER IN STATEMENT
NUMBER xxx IS EITHER INVALID OR
IS NOT IMPLEMENTED IN THIS
RELEASE
Explanation:
The
implementation of the REFER
option is restricted; see
Appendix J, 'Implementation
Conventions and Restrictions'.

NO IDENTIFIER FOUND IN DECLARE
STATEMENT NUMBER xxx.
STATEMENT REPLACED BY NULL
STATEMENT.

system Action:
Ignore the
REFER clause. A further
message identifying the invalid
text will usually accompany
this message.

Explanation: Either no
identifiers appear in t.he
DECLARE statement or. as a
result of previous compiler
action, all identifiers have
been deleted from the
statemept.

Programmer Response: Probabl~~
user error. Correct program
and recompile. If the problem
recurs, do the following befOl:e
calling IBM for programming
support:

Explanation: The source error
may be detailed in another
message referring to the same
statement.

• Have the source program
listing available.
E IEM01481

LEFT PARENTHESIS MISSING IN
STATEMENT NUMBER xxx

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recUJ;s, do the following before
calling IBM for programming
support:

system Action: See further
messages relating to this
statement
Programmer Response: Probable
user ercor. Correct program
and recompile. If the problem
recurs, do the follqwing before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM01531

Explanation: The PL/I feature
CONtROLLED (pointer) has been
changed to BASED (pointer).

• Have the source program
listing available.
E IEM01.491

COMMA HAS BEEN DELETED FROM
LIST IN STATEMENT NUMBER xxx

programmer Response: Probable
user' error. Correct program
and recompile. If the problem
requrs, do the following before
calling IBM for programming
support:

Programmer Response: probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
E IEM01.501

• Have the source program
listing available.
S IEM01541

STATEMENT NUMBER xxx IS AN
INVALID FREE STATEMENT. THE
STATEMENT HAS BEEN DELETED.

System Action: Text is
deleted. See further error
message for this statement.

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct source
statement. If the problem
re·<::urs, do the following before
calling IBM for programming
support:

SEMI-COLON INSERTED IN
STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

S IEM01521

IMPLEMENTATION RESTRICTION IN
STATEMENT NUMBER xxx. BASED
~UST BE FOLLOWED BY AN
IDENTIFIER IN PARENTHESIS.

Explanation: The format of the
statement is invalid

• Have the source program
listing available.
S IEM01511

THE ATTRIBUTED BASED HAS BEEN
ASSUMED IN STATEMENT NUMBER xxx
WHERE CONTROLLED WAS SPECIFIED.

TEXT BEGINNING yyyy IN
STATEMENT NUMBER xxx HAS BEEN
DELETED.

• Have the source program
listing available.
E IEM01581

ZERO STRUCTURE LEVEL NUMBER
DELETED IN DECLARE STATEMENT
NUMBER xxx
Explanation:
not allowed

Zero level number

Programmer Response: Probable
uSer error. Correct program
and' recompile. If the problem
recwrs, do the following before
ca~ling IBM for programming
support:
.'Have the source program
listing available.
Appendix ·K:. Diagnostic Messages

329

E IEM01591

and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

SIGN DELETED PRECEDING
STRUCTURE LEVEL NUMBER IN
DECLARE STATEMENT NUMBER xxx
Explanation: The level number
must be an unsigned integer
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM01811

Explanation: An error has been
discovered. A semi-colon is
therefore inserted and the rest
of the statement is skipped.

• Have the source program
listing available.
S IEM01631

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

FqRMAT LIST MISSING, (A)
INSERTED IN STATEMENT NUMBER
xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM01821

• Have the source program
listing available.
S IEM01661

Explanation:· The source error
is detailed in another message~
referring to the same
statement.

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable~
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

LEFT PARENTHESIS INSERTED IN
DELAY STATEMENT NUMBER xxx

• Have the source program
listing available.
S IEM018S1

Explanation: The exprE~ssion in
a DELAY statement should be
contained in parentheses

• Have the source program
listing available.
EQUAL SYMBOL HAS BEEN INSERTED
IN DO SPECIFICATIONS IN
STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
330

OPTION IN GET/PUT STATEMENT
NUMBER xxx IS INVALID AND HAS
BEEN DELETED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

E IEM01801

TEXT BEGINNING yyyy SKIPPED IN
OR FOLLOWING STATEMENT NUMBER
xxx

OPERAND MISSING IN GO TO
STATEMENT NUMBER xxx. DUMMY IS
INSERTED.

• Have the source program
listing available.
E IEM01721

SEMICOLON INSERTED IN STATEMENT
NUMBER xxx

• Have the source program
listing available.
S IEMOla7!

DATA LIST MISSING IN STATEMEN,]~
NUMBER xxx. OPTION DELETED.
Programmer Response:
ProbablE~
user error. Correct program
and recompile. If the problem
recurs, do the following befol::-e
calling ISM for programming
support:

• Have the source program
listing available.
S IEM01911

DUMMY OPERAND INSERTED IN DATA
LIST IN STATEMENT NUMBER xxx

• Have the source program
listing available.
S IEM02021

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Explanation: The statement
referred to is of a type not
supported by this version of
the compiler. For details,
refer to Appendix J of this
publication.

• Have the source program
listing available.
E IEM019131

system Action:
continues

RIGHT PARENTHESIS INSERTED IN
DATA LIST IN STATEMENT NUMBER
xxx

E IEM01941

• Have the source program
listing available.
E IEM02071

MISSING RIGHT PARENTHESIS
INSERTED IN FORMAT LIST IN
STATEMENT NUMBER xxx

S IEM01951

.• Have the source program
listing available.
E IEM02081

INVALID FORMAT LIST DELETED IN
STATEMENT NUMBER xxx.
(A),
INSERTED.

S IEM01981

COMPLEX FORMAT ITEM yyyy IN
STATEMENT NUMBER xxx IS INVALID
AND HAS BEEN DELETED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programmdng
support:

LEFT PARENTHESIS INSERTED IN
CHECK'LIST IN STATEMENT NUMBER
xxx
Programmer Response:
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programmdng
support:
• Have the source program
listing available.

COMMA REPLACED BY EQUAL SYMBOL
IN ASSIGNMENT STATEMENT NUMBER
xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

Compilation

Programmer Response: Probable
user error. Rewrite source
program avoiding use of
unsupported feature.
If the
problem recurs, do the
following before calling IBM
for programming support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

DEFERRED FEATURE. STATEMENT
NUMBER xxx NOT IMPLEMENTED IN
THIS VERSION.

• Have the source program
listing available.
T IEM02091

IMPLEMENTATION RESTRICTION.
STATEMENT NUMBER xxx IS TOO
COMPLEX
Explanation: The level of
nesting exceeds the
implementation restriction.
Refer to Appendix J of this
publication for details.
system Action:
compilation

Terminates

Appendix K: Diagnostic Messages

331

Programmer Response:
Probable
user error. Divide statement
into two or more statements.
If the problem recurs, do the
following before calling IBM
for programming support:

E IEM02141

system Action:
Ignores options
other than the first
Programmer Response:
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)
• Have the associated job
stream and source program
listing available.
E IEM02111

• Have the source program
listing available.
E IEM02161

• Have the source program
listing available.
E IEM02171

• Have the source program
listing available~
E IEM02121

system Action:
Ignorf~s options
other than the first

• Have the source program
listing available.
W IEM02181

MULTIPLE EVENT OPTIONS
SPECIFIED IN STATEMENT NUMBER
xxx. THE FIRST ONE IS USED.

• Have the source program
listing available.

System Action: Ignores options
other than the first
S IEM02191
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
list\ng available.
332

REPETITION FACTOR MISSING AF.rER
ITERATION FACTOR IN STATEMEN~r
NUMBER xxx. REPETITION FACTOR
OF 1 INSERTED.
Programmer Response: Probable
user error. Correct program
and recompile. If the probl,em
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM02131

INVALID PRIORITY OPTION IGNORED
IN STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problE~m
recurs, do the following before
calling IBM for programming
support:

MULTIPLE TASK OPTIONS SPECIFIED
IN STATEMENT NUMBER XJCX. THE
FIRST ONE IS USED.

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

INVALID EVENT OPTION IGNORED IN
STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problE~m
recurs, do the following before
calling IBM for programming
support:

LEFT PARENTHESIS INSERTED IN
STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

MULTIPLE PRIORITY OPTIONS
SPECIFIED IN STATEMENT NUMBER
xxx. THE FIRST ONE IS USED.

KEYWORD 'CONDITION' NOT
SPECIFIED IN SIGNAL STATEMENT
NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following bef'ore
calling IBM for programming
support:

calling IBM for programming
support:

• Have the source program
listing available.
S IEM02201

IDENTIFIER MISSING OR INCORRECT
AFTER OPTION IN STATEMENT
NUMBER xxx. OPTION DELETED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM02241

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM02211

NUMBER OF LINES NOT GIVEN AFTER
LINE OPTION IN STATEMENT NUMBER
xxx.
(1) INSERTED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM02251

DEFERRED FEATURE. THE IDENT
OPTION ON OPEN/CLOSE STATEMENT
NUMBER xxx IS NOT IMPLEMENTED
BY THIS VERSION.

• Have the source program
listing available.
S IEM02261

Explanation: A language
feature has been used that is
not supported by this version
of the compiler. Refer to
Appendix J of this publication
for details.
system Action:

• Have the source program
listing available.
W IEM02271

• Have the source program
listing available.
S IEM02231

NO FILE/SrRING OPTION SPECIFIED
IN ONE OR MORE GET/PUT
STATEMENTS. SYSIN/SYSPRINT HAS
BEEN ASSUMED IN EACH CASE
Explanation: One or more GET
or PUT statements have appeared
in the program with no
specified FILE option or STRING
option.

EXPRESSION MISSING AFTER
IDENT/TITLE/LlNESIZE/PAGESIZE
OPTION IN STATEMENT NUMBER xxx.
OPTION DELETED.
Explanation: No left
parenthesis found following
keyword
Erogrammer Res~~~ Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before

EXPRESSION MISSING AFTER FORMAT
ITEM IN STATEMENT NUMBER xxx.
ITEM DELETED.
Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

Option ignored

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

OPTION AFTER OPEN/CLOSE IN
STATEMENT NUMBER xxx IS INVALID
OR MISSING.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM02221

INVALID OPTION DELETED IN I/O
STATEMENT NUMBER xxx

system Action:
The compiler
has assumed the appropriate
default file (SYSIN for GET,
SYSPRINT for PUT).
S IEM02281

EXPRESSION MISSING AFTER' OPTION
IN STATEMENT NUMBER xxx.
OPTION DELETED.

Appendix K: Diagnostic Messages

333

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

S IEM02331

programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following befo're
calling IBM for programming
support:

• Have the source program
listing available.
S IEM02291

FORMAT ITEM IN STATEMENT NUMBER
xxx IS INVALID AND HAS BEEN
DELETED.

• Have the source program
listing available.
S IEM02351

Programmer Response:
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

INVALID DATA LIST IN STATEMENT
NUMBER xxx..
STATEMENT DELETED.
Programmer Response: Probable
user error.. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM02361

MISSING COMMA INSERTED IN DATA
LIST IN STATEMENT NUMBER xxx
Explanation:
Comma missing
between elements of a data list

• Have the source program
listing available.
S IEM02371

Programmer Response: Probable
user error.
Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

KEYWORD DO MISSING IN DATA LIST
IN STATEMENT NUMBER xxx. DO IS
INSERTED.

• Have the source program
listing available.
S IEM023BI

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

334

INSUFFICIENT OPTIONS SPECIFIED
IN STATEMENT NUMBER xxx. TH]!:
STATEMENT HAS BEEN REPLACED BY
A NULL STATEMENT.
Programmer Response: Probable
user error. Correct program
and recompile.
If the problc~m
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available,.
E IEM02321

THE OPTION yyyy IN STATEMENT
NUMBER xxx IS UNSUPPORTED OR
INVALID.
Programmer Response: Probable
user error. Correct program
and recompile.
If the problE~m
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM02311

ARGUMENT OMITTED FOLLOWING yyyy
OPTION IN STATEMENT NUMBER xxx.
OPTION DELETED.
Programmer Response:
Probable
user error. Correct program
and recompile.
If the problE!m
recurs, do the following before
c~lling IBM for programming
support:

• Have the source p:r-ogram
listing available.
S IEM02301

RETURN STATEMENT NUMBER xxx IS
WITHIN AN ON-UNIT. IT IS
REPLACED BY A NULL STATEMENT.

THE LOCATE-VARIABLE IN LOCATE
STATEMENT NUMBER xxx IS OMITTED
OR SUBSCRIPTED. THE STATEMENT
HAS BEEN DELETED.
Explanation:
The omission o:f
the locate variable renders ·the
sta'tement meaningless.
subscripted locate variables
are invalid.

system Action: Replaces
invalid statement with a null
statement.

• Have the source program
listing available.
T IEM02431

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

System Action:
terminated

IEM02~~OI

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments Which precede all
the IEMnnnnI messages.)

COMPILER ERROR IN PHASE CV.
SCAN CANNOT IDENTIFY DICTIONARY
ENTRY.
Explanation: The main scan of
fifth pass of read-in has found
something in the dictionary
which it cannot recognize
system Action:
terminated

• Have the associated job
stream and source program
listing available.

Compilation is
E IEM02441

Programmer Response: Do the
following before calling IBM
for programming support:
• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)
• Have the associated job
stream and source program
listing availablen
E IEM02411

• Have the source program
listing available.
E I,EM02451

MULTIPLE USE OF A PREFIX OPTION
HAS OCCURRED IN STATEMENT
NUMBER xxx. THE LAST NAMED
OPTION IS USED.

• Have the source program
listing available.
PREFIX OPTION INVALID OR
MISSING IN STATEMENT NUMBER
xxx.
INVALID OPTION DELETED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

CHECK PREFIX OPTION IN
STATEMENT NUMBER xxx IS NOT
FOLLOWED BY A PARENTHESIZED
LIST. THE OPTION HAS BEEN
IGNORED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

A CHECK PREFIX OPTION IS GIVEN
FOR STATEMENT NUMBER xxx WHICH
IS NOT A PROCEDURE OR BEGIN.
THE OPTION HAS BEEN IGNORED.
Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

S IEM02421

Compilation is

Programmer Response: . Do the
following before calling IBM
for programming support:

• Have the source program
listing available.
T

COMPILER ERROR. PHASE CS HAS
FOUND AN UNMATCHED END.

• Have the source program
listing available.
S IEM02471

ALL SUBSCRIPTED LABELS
PREFIXING PROCEDURE OR ENTRY
STATEMENT NUMBER xxx HAVE BEEN
IGNORl.~D.

Explanation: subscripted
labels may not be used as
prefixes on PROCEDURE or ENTRY
statements.
Programmer Response: Probable
user error. Correct program
Appendix K: Diagnostic Messages

335

and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the associated job
stream and source program
listing available.
S IEM02571

• Have the sou:['ce program
listing available.

DATA DIRECTED I/O LIST IN
STATEMENT NUMBER xxx CONTAINS
BASED ITEM zzzz
System Action: Statement will
be deleted by later phases.

T IEM02541

COMPILER UNABLE TO RECOVER FROM
I/O ERROR - PLEASE RETRY JOB.
System 1Ction:
compilation

Programmer Response: Probablle
user error. Correct program
and :['ecompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Terminates

Proq:r:arnmer Response: Re-attempt
compilation. If the
input/output error persists, do
the following before calling
IBM for programming support:

• Have the source program
listing available.
S IEM02581

• Recompile the program ~dth
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

System Action: Statement will
be deleted by later phases.
Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

• Make sure that
MSGLEVEL=(l,l) was
specified in the job
statement, and that a
SYSUDUMP DO statement was
included for the failing
job step.
• Have the associated job
stream and source program
listing available.
T IEM02551

• Have the source program
listing available.
W IEM05101

THERE ARE NO COMPLETE
STATEMENTS IN THIS PROGRAM

Compilation is
System Action: The TASK option
is correctly applied

Programmer Response: Check
source for completed
statements.
If these are
present then do the following
before calling IBM for
programming support:
• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

336

THE TASK OPTION HAS BEEN
ASSUMED TO APPLY TO THE
EXTERNAL PROCEDURE STATEMENT
NUMBER xxx
Explanation: TASK, EVENT or
PRIORITY options have been
detected in a CALL statement"
but the TASK option has not
been speci fied in the externall
procedure.

Explanation: Compiler cannot
reconcile END statements with
stack entries. Usually caused
by a progranl containing only
comments.
system Action:
terminated

NUMBER OF SUBSCRIPTS SPECIFIED
FOR zzzz IN STATEMENT NUMBER
xxx CONFLICTS WITH
DIMENSIONALITY. DUMMY
REFERENCE INSERTED.

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following bef()re
calling IBM for programming
support:
• Have the source program
listing available.
W IEM05111

OPTIONS MAIN AND/OR TASK ARE
NOT ALLOWED ON THE INTERNAL
PROCEDURE STATEMENT NUMBER xxx

System Action: The invalid
options are ignored

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
S IEM05121

• Have the source program
listing available.
S IEM05161

IDENTIFIER yyyy IN STATEMENT
NUMBER xxx IN INITIAL ATTRIBUTE
LIST IS NOT A KNOWN LABEL
CONSTANT AND HAS BEEN IGNORED.

System Action: Compiler scans
for next right bracket. If
this is not the bracket closing
the illegal options list, a
compiler error will probably
follow.

system Action: Identifier
changed to * in the list.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
re'curs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM05131

REPEATED LABEL IN SAME BLOCK ON
STATEMENT NUMBER xxx. LABEL
DELETED.

• Have the source program
listing available.
S IEM05171

Explanation: A label may not
be used more than once in the
same block.

• Have the source program
listing available.
S IEM05181

S IEM05141

PARAMETER yyyy IN STATEMENT
NUMBER xxx IS SAME AS LABEL.
PARAMETER REPLACED BY DUMMY.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

S IEM05151

IMPLEMENTATION RESTRICTION.
CHARACTER STRING LENGTH IN
STATEMENT NUMBER xxx REDUCED TO
32,767.

CONFLICTING ATTRIBUTE DELETED
IN STATEMENT NUMBER xxx
Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

ILLEGAL OPTIONS LIST ON
STATEMENT NUMBER xxx. LIST
IGNORED.

IMPLEMENTATION RESTRICTION.
PRECISION TOO LARGE IN
STATEMENT NUMBER xxx. DEFAULT
PRECISION GIVEN.
Explanation: If later a valid
preC1S10n is given, this will
be accepted in place of the
default.
System Action: Attribute
ignored. Attribute test mask
restored so that later
attribute will not be found to
conflict with deleted one.
Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

Appendix K: Diagnostic Messages

337

• Have the source program
listing available.
S IEM05191

S IEM05221

ILLEGAL ATTRIBUTE ON STATEMENr
NUMBER xxx IGNORED.
Programmer Response: Probable!
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

Explanation:
Only data
attributes allowed on procedure
or entry statements.
(No
dimensions allowed).
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM05231

• Have the source program
listing available.
T IEM05201

COMPILER ERROR CODE nnnn

system Action:
immediately

Terminates

Programmer Response: Do the
following before calling IBM
for programming support:

• Have the source program
listing available.
S IEM05241

system Action: Assumes length
of 1 and skips to next
attribute
Programmer ResP.Qns~.!. Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
338

Ignores

Programmer Response: Probable!
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the associated job
stream and source program
listing available.

Explanation:
Either no length
has b~en given or s·tring length
* has been used in source code.

IDENTIFIER yyyy IN LABEL LIST
IN STATEMENT NUMBER xxx IS NO'l'
A LABEL OR IS NOT KNOWN.
system Action:
identifier

• Recompile the progz'am with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

INVALID STRING LENGTH IN
STATEMENT NUMBER xxx. LENGTH
OF 1 ASSUMED.

PARAMETER zzzz IN STATEMENT
NUMBER :XXK APPEARS TWICE.
SECOND ONE REPLACED BY DUMMY.
Programmer Response:
Probable!
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

Explanation: A compiler error
has occurred.

S IEM05211

IMPLEMENTATION RESTRICTION.
NUMBER OF PARAMETERS IN
PROCEDURE OR ENTRY STATEMENT
NUMBER .xxx TRUNCATED TO 64.

• Have the source program
listing available.
T IEM05251

IMPLEMENTATION RESTRICTION.
TOO MANY PAIRS OF FACTORED
ATTRIBUTE BRACKETS FOR THIS
SIZE OPTION.
ExplanatioQ: Factor bracket
table has overflowed.
~stem

Action:
terminated

Compilation

PrQ.gFammer Response: ProbablE~
user error. Recompile using Sl
SIZE sufficient to provide a
larger block size or reduce
factoring by expanding
declarations.
If the problem
recurs, do the following before
calling IBM for programming
support:

calling IBM for programming
support:

• Recompile the program with
compiler opti!ons
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

• Have the source program
listing available.
S IEM05301

• Have the associated job
stream and source program
listing available.
W IEM05261

S IEM05271

-.·i

OPTION MAIN HAS NOT BEEN
SPECIFIED FOR THE EXTERNAL
PROCEDURE STATEMENT NUMBER xxx

Explanation: There is an
implementation restriction
limiting the number of label
constants following the LABEL
attribu'\:e to 125.

IMPLEMENTATION RESTRICTION.
ARRAY BOUND IN STATEMENT NUMBER
xxx IS TOO LARGE AND HAS BEEN
REPLACED BY THE MAXIMUM
PERMITTED VALUE (32767 OR
-32768) •

Progra~ner Response:
Probable
user error. Correct program
and rec()mpile.
If the problem
recurs, do the following before
calling IBM for programming
support::

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM05321

• Have the source program
listing available.
T IEM05.281

COMPILER ERROR CODE nnnn IN
STATEMENT NUMBER xxx

Progra~ner Response:
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Terminates

Programmer Response: Do the
following before calling IBM
for programming support:

• Have the source program
listing available.

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

S IEM05331

IMPLEMENTATION RESTRIGTION.
STRUCTURE LEVEL NUMBER IN
STATEMENT NUMBER xxx REDUCED
255.

-·Programmer Response:
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

ro

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before

IMPLEMENTATION RESTRICTION.
I-SUB VALUE IN STATEMENT NUMBER
xxx TOO LARGE. REDUCED TO 32.
EXplanation: There is an
implementation restriction
limiting the number of
dimensicms to "a maximum of 32.

• Have the associated job
stream and source program
listing available.
S IEM05291

ILLEGAL ASTERISK AS SUBSCRIPT
IN DEFINING LIST IN STATEMENT
NUMBER :ICXX.
LIST TRUNCATED.
System l\ction: Compilation
continUt:~s with truncated iSUB
list, p()ssibly causing cascade
errors.

Explanation: Compiler error
found in processing a DECLARE
statement
system-Action:
compilation

IMPLEMENTATION RESTRICTION.
TOO MANY LABELS IN LABEL LIST
IN STATEMENT NUMBER xxx. THE
LABEL zzzz AND ANY FOLLOWING IT
HAVE BEEN IGNORED.

• Have the source program
listing available.
S IEM05341

IMPLEMENTATION RESTRICTION.

Appendix K: Diagnostic Messages

339

STRING LENGTH IN STATEMENT
NUMBER xxx REDUCED TO 32,767.

and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following be:Eore
calling IBM for programming
support:

• Have the source program
listing available.
S IEM05401

• Have the source program
listing available.
S IEM05361

IDENTIFIER yyyy IN STATEMENT
NUMBER xxx IS NOT A LABEL
CONSTANT OR IS NOT KNOWN.
IT
IS IGNORED.

Programmer Response:
ProbablE~
user error. Correct program
and recompile. If the problem
recurs, do the following befo)~e
calling IBM for programming
support:

Explanation:
Identifiers
following the LABEL attribute
must be LABEL constants and
must be known.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM05411

IMPLEMENTATION RESTRICTION.
POSITION CONSTANT IN ST~TEMENT
NUMBER xxx REDUCED TO 32,767.
Programmer Respon?e: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM05421

IMPLEMENTATION RESTRICTION.
PRECISION SPECIFICATION IN
STATEMENT NUMBER xxx TOO L~RGE.
DEFAULT PRECISION GIVEN.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

E IEM05391

340

IMPLEMENTATION RESTRICTION.
NUMBER OF DIMENSIONS DECLARED
TRUNCATED TO 32 IN STATEMENT
NUMBER xxx
Programmer Response: Probabl~~
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM05381

LOWER BOU~D GREATER THAN UPPER
BOUND IN DECLARE OR ALLOCATE
STATEMENT NUMBER xxx. THE
BOUNDS ARE INTERCHANGED.
Programmer Response:
ProbablE~
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM05371

* BOUNDS ARE MIXED WITH NON-*
BOUNDS IN DECLARE STATEMENT
NUMBER XXK.
ALL THE BOUNDS
ARE MADE *.
.

• Have the source program
listing available.
T IEM05431

COMPILER ERROR. ILLEGAL
STATEMENT FOUND IN THE DECLARE
CHAIN.
Explanation:
Compiler error
found in scanning chain of
DECLARE statements

ILLEGAL NEGATIVE PRECISION IN
STAT.EMENT NUMBER xxx. DEFAULT
PRECISION GIVEN.

System Action:
terminated

Compilation

Programmer Response: Probable
user error. Correct program

Prog:E:'ammer Response: Do the
following before calling IBM
for programming support:

T IEMOS44I

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comment~ which precede all
the IEMnnnnI messages.)

CHARACTER FOUND AFTER LEVEL
NUMBER IN DECLARE STATEMENT
NUMBER xxx

• Have the associated job
stream and source program
listing available.

system Action:
terminated

Explanation: Compiler error
found after structure level
number in DECLARE statement

programmer Response: Do the
following before calling IBM
for programming support:

COMPILER ERROR. INITIAL CODE
BYTE QF DECLARE STATEMENT IS
NEITHER STATEMENT NUMBER NOR
STATEMENT LABEL.

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

Explanation: Compiler error
found in first byte of DECLARE
statements
system Action:
terminated

Compilation

• Have the associated job
stream and source program
listing available.

Programmer Response: Do the
following before calling IBM
for programming support:
W IEM0547I

T IEMOS45I

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

THE IDENTIFIER yyyy DECLARED IN
STATEMENT NUMBER xxx IS A
NON-MAJOR STRUCTURE MEMBER AND
HAS THE SAME NAME AS A FORMAL
PARAMETER OR INTERNAL ENTRY
POINT.
ALL REFERENCES TO THE
STRUCTURE MEMBER SHOULD BE
QUALIFIED.

• Have the associated job
stream and source program
listing available.

system Action:
Same BCD
treated as different
identifiers

COMPILER ERROR. ILLEGAL
INITIAL CHARACTER TO DECLARED
ITEM IN STATEMENT NUMBER xxx

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Explanation: Compiler error
found in scanning start of
declared item
system Action:
terminated

• Have the source program
listing available.

Compilation
T IEM054BI

Programmer Responsg;.. Do the
following before calling IBM
for programming support:
• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)
• Have the associated job
stream and source program
listing available.
T IEll.10S46I

Compilation

COMPILER ERROR.

ILLEGAL

COMPILER ERROR. ILLEGAL
CHARACTER FOUND IN DECLARATION
LIST.
Explanation: Compiler error
found in list of declarations
in DECLARE statement
system Action:
terminated

Compilation

Programmer Response: Do the
following before calling IBM
for programming support:
• Recompile the program with
compiler option's
'S,DP=(PIE,ZZ), to obtain a
Appendix K: Diagnostic Messages

341

formatted dump of t:he
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

system Action:
terminated

Programmer Response: Do the
following before calling IBM
for programming support:

• Have the associated job
stream and source program
listing available •.
E IEM05491

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

THE DECLARED LEVEL OF
IDENTIFIER yyyy IN STATEMENT
NUMBER xxx SHOULD BE ONE.
THIS
HAS BEEN FORCED.
system Action: Illegal level
number treated as 1
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the associated job
stream and source program
listing available.
E IEM05531

THE IDENTIFIER yyyy HAS BEEN
DECLARED IN STATEMENT NUMBER
xxx WITH A TRUE LEVEL NUMBER
GREATER THAN THE IMPLEMENTATION
RESTRICTION OF 63. THE
DECLARATION OF THE IDENTIFIER
IS IGNORED.

Programmer Response:
ProbablE:!
user error. Correct program
and recompile. If the problem
recurs, do the following befOJ::e
calling IBM for programming
support:

Programmer R~ns~~ Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
E IEM05511

• Have the source program
listing available.
T IEM05541

THE IDENTIFIER yyyy HAS BEEN
DECLARED IN STATEMENT NUMBER
xxx WITH ZERO PRECISION. THE
DEFAULT VALUE HAS BEEN ASSUMED.

342

Compilation

Programmer Response: Do the
following before calling IBM
for programming support:
• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
:formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

• Have the source program
listing available.
COMPILER ERROR. ILLEGAL
CHARACTER FOUND IN FAC'rORED
ATTRIBUTE LIST IN DECLARE
STATEMENT NUMBER xxx
Explanation: Compiler error
found in factored attribute
list

COMPILER ERROR. ILLEGAL
CHARACTER FOUND IN PARAMETER
LIST FOLLOWING 'GENERIC'
ATTRIBUTE.
system Action:
terminated

Programmer Response: Probable
user error. Cor:rect program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

T IEM05521

THE IDENTIFIER yyyy HAS HAD A
CONFLICTING ATTRIBUTE IGNORED
IN DECLARE STATEMENT NUMBER Xlt:X
Explanation: The two
attributes may conflict as a
result of a feature not
supported by this version of
the compiler. For details of
these features, refer to
Appendix J of this publication.

• Have the source program
listing available.
S IEM05501

Compilation

• Have the associated job
stream and source program
listing available.
E IEM05551

STORAGE CLASS ATTRIBUTES ~~y
NOT BE SPECIFIED FOR STRUCTURE

MEMBER yyyy.
IGNORED.

ATTRIBUTE

• Have the source program
listing available.
E IEM05591

Programmer Response~ Probable
user error. Delete illegal
storage class attribute for the
structure member. If the
problem recurs, do the
following before calling IBM
for programming support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
T IEM05S61

COMPILER ERROR. ILLEGAL
CHARACTER FOUND IN PARAMETER
LIST FOLLOWING AN 'ENTRY'
ATTRIBUTE IN DECLARE STATEMENT
NUMBER xxx
System Action:
terminated

• Have the source program
listing available.
E IEM05601

Compilation

Programmer Response: Do the
following before calling IBM
for programming support:

• Have the source program
listing available.
S IEM05611

• Have the associated job
stream and source program
listing available.
THE MULTIPLE DECLARATION OF
IDENTIFIER yyyy IN STATEMENT
NUMBER xxx HAS BEEN IGNORED.

S IEM05581

IMPLEMENTATION RESTRICTION.
NUMBER OF PARAMETER
DESCRIPTIONS DECLARED FOR
PROCEDURE OR ENTRY NAME yyyy IN
STATEMENT NUMBER xxx TRUNCATED
TO 64.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

IN STATEMENT NUMBER xxx THE
IDENTIFIER yyyy IS A MULTIPLE
DECLARATION OF AN INTERNAL
ENTRY LABEL. THIS DECLARATION
IS IGNORED.
Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

IN STATEMENT NUMBER xxx A
CONFLICTING ATTRIBUTE HAS BEEN
IGNORED IN THE DECLARATION OF
THE RETURNED VALUE OF ENTRY
POINT yyyy
Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

E IEM05571

THE IDENTIFIER yyyy HAS BEEN
DECLARED IN STATEMENT NUMBER
xxx WITH CONFLICTING FACTORED
LEVEL NUMBERS. THE ONE AT
DEEPEST FACTORING LEVEL HAS
BEEN CHOSEN.

• Have the source program
listing available.
S IEM05621

THE IDENTIFIER yyyy IS DECLARED
IN STATEMENT NUMBER xxx AS AN
INTERNAL ENTRY POINT. THE
NUMBER OF PARAMETERS DECLARED
IS DIFFERENT FROM THE NUMBER
GIVEN AT THE ENTRY POINT.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

Appendix K: Diagnostic Messages

343

S IEM05631

THE IDENTIFIER yyyy DECLARED
'BUILTIN' IN STATEMENT NUMBER
xxx IS NOT A BUILT-IN FUNCTION.
DECLARATION IGNORED.

THE VALUE RETURNED WILL
CONFLICT WITH THE ATTRIBUTES IN
THE PROCEDURE OR ENTRY
STATEMENT FOR THAT VALUE.

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Explanation: The data type to
which a result will be
converted at a RETURN
(expression) will not be the
same as that expected at an
invocation of the entry label
as a function.

• Have the sou:rce program
listing available.

system Action:
E IEM05641

THE IDENTIFIER yyyy HAS BEEN
DECLARED IN STATEMENT NUMBER
xxx WITH PRECISION GREATER THAN
THE IMPLEMENTATION LIMITS. THE
MAXIMUM VALUE HAS BEEN TAKEN.

Programmer Respons e: Probablle
user error. Write an
entry-point declaration Cusin,:}
the ENTRY or RETURNS attributte>
in the containing block, giving
the same data attributes as
those on the PROCEDURE or ENTRY
statement. If the problem
recurs, do the following before
calling IBM for prograrmnin.g
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
E IEM05651

THE IDENTIFIER yyyy IS DECLARED
IN STATEMENT NUMBER xxx AS A
MEMBER OF A GENERIC LIST, BUT
ITS ATTRIBUTES DO NOT MAKE IT
AN ENTRY POINT. THE
DECLARATION OF THE IDENTIFIER
HAS BEEN IGNORED.

• Have the source program
listing available.
S IEM05681

Programmer Response: Probabl,e
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
ONE OF THE PARAMETERS DECLARED
FOR ENTRY POINT yyyy IN
STATEMENT NUMBER xxx SHOULD BE
AT LEVEL ONE. THIS HAS BEEN
FORCED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
W IEM05671

344

IF FUNCTION yyyy IN ST.ATEMENT
NUMBER xxx IS INVOKED, THE
DEFAULT ATTRIBUTES ASSUMED FOR

THE IDENTIFIER zzzz IS CALLED
BUT IS ElrHER A BUILTIN
FUNCTION OR IS NOT AN ENTRY
POINT.
system Action: The erroneous
statement is deleted.

Programmer Respo~~~ Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

, E IEM05661

None

• Have the sdurce program
listing available.
T IEM05691

COMPILER ERROR NUMBER nnnn IN
MODULE EP.
Explanation: Compiler error
found in s can of chain of CALI..
statements
System Action:
terminated

Compilation

Programmer Response: Do the
following before calling IBM
for programming support:
• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the

comments which precede all
the IEMnnnnI messages.)

S IEM05731

• Have the associated job
stream and source program
listing available.
W IEM051'OI

THE ENTRY POINT yyyy HAS BEEN
DECLARED IN STATEMENT NUMBER
xxx TO HAVE A RETURNED VALUE
DIFFERENT FROM THAT GIVEN ON
THE PROCEDURE OR ENTRY
STATEMENT.
system Action:

Explanation: The usage
referred to is not supported by
this version of the compiler.
For details, refer to Appendix
J.

None

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Change the
declaration, or the PROCEDURE
or ENTRY statement. If the
problem recurs, do the
following before calling IBM
for programming support:
• Have the source program
listing available.
S IEM05i'11

• Have the source program
listing available.
T IEM05741

IMPLEMENTATION RESTRICTION.
IDENl'IFIER yyyy IN STATEMENT
NUMBER xxx HAS MORE THAN 32
DIMENSIONS. DIMENSION
ATTRIBUTE IGNORED.

• Recompile the program with
compiler options
'S,DP={PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

• Have the source program
listing available.
THE IDENTIFIER yyyy HAS BEEN
DECLARED IN STATEMENT NUMBER
xxx WITH THE ATTRIBUTE "NORMAL"
OR "ABNORMAL". THE APPLICATION
OF THIS ATTRIBUTE IS AN
UNSUPPORTED FEATURE OF THE
FOURTH VERSION, AND IT HAS BEEN
IGNORED.

• Have the associated job
stream and source program
listing available.
W IEM05751

• Have the source program
listing available.

TH~ REPEATED ATTRIBUTE IN THE
DECLARATION OF FILE yyyy IN
STATEMENT NUMBER xxx HAS BEEN
IGNORED.

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

Explanation: A language feature
has been used which is not
supported by this version of
the compiler. Refer to
Appendix J of this publication
for details.
Programmer Response;. Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

THE MULTIPLE DECLARATION OF
IDENTIFIER yyyy IN STATEMENT
NUMBER xxx HAS BEEN IGNORED.
Programmer Response: Probable
user error.
If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

S IEM05721

THE SELECTION OF GENERIC FAMILY
MEMBERS WHOSE PARAMETERS HAVE A
STRUCTURE DESCRIPTION IS
DEFERRED. ENTRY NAME yyyy,
DECLARED IN STATEMENT NUMBER
xxx, IS SUCH A MEMBER AND HAS
BEEN DELETED.

• Have the source program
listing available.
E IEM05761

THE EXTERNAL FILE yyy DECLARED
IN STATEMENT NUMBER xxx HAS THE
SAME NAME AS THE EXTERNAL
PROCEDURE, DECLARATION IGNORED.
Programmer Response: Probable
user error. Correct program

Appendix K: Diagnostic Messages

345

and recompile.
If the problem
recurs, do the following before
calling IBM for programming
,. support:

• Have the source program
listing available.
S IEM05801

• Have the source program
listing available.
E IEM05771

Programmer Response:
ProbablE~
user error. Correct program
and recompile.
If the problem
recurs, do the following befol~e
calling IBM for programming
support:

INCORRECT SPECIFICATION OF THE
ARRAY BOUNDS, STRING LENGTH OR
AREA SIZE OF THE NON-CONTROLLED
PARAMETER yyyy IN DECLARE
STATEMENT NUMBER xxx; THOSE OF
THE CORRESPONDING ARGUMENT WILL
BE ASSUMED.
Explanation:
In the
declaration of a non-controlled
array, string or area
parameter, the bounds, length
or size must be given by a
constant or by an asterisk.

• Have the source program
listing available.
S IEM05891

• Recompile the program with
compiler options
wS,DP=(PIE,EV)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the associated job
stream and source program
listing available.

• Have the source program
listing available.
UNDIMENSIONED VARIABLE yyy
DECLARED IN STATEMENT NUMBER
xxx HAS INITIAL ATTRIBUTE WITH
CONFLICTING SPECIFICATION FOR A
DIMENSIONED VARIABLE.
INITIAL
ATTRIBUTE IGNORED.

S IEM05901

Programmer Response:
Probable
user error. Cor:rect source
program and recompile.
If the
problem recurs, do the
following before calling IBM
for programming support:

THE PARAMETER OF THE MAIN
PROCEDURE SHOULD BE A FIXED
LENGTH CHARACTER STRING OR HAVE
THE ATTRIBUTES CHARACTER(lOO)
VARYING.
Programmer Response:
Probable
user error. Correct source
program and recompile. If the
problem recurs, do the
following before calling IBM
for programming support:

346

STRUCTURE ELEMENT zzzz WHICH
HAS LIKE ATTRIBUTE ATTACHED TO
IT, IS FOLLOWED BY AN ELEMENT
WITH A NUMERICALLY GREATER
STRUCTURE LEVEL NUMBER. LIKE
ATTRIBUTE IS IGNORED.
System Action:
Self
explanatory: may result in
cascade errors.
Programmer Response:
ProbablE~
user error. Correct program
and recompile~
If the problem
recurs, do the following before
calling IBM for programming
support:

.,Have the source program
listing available.
W IEM05791

COMPILER ERROR.
ITEM zzzz IN
LIKE CHAIN IS NOT A STRUCTURE.,
ITEM IS IGNORED.
Programmer Response: Do the
following before calling IBM
for programming support:

system Action: The bounds,
length or size of the array,
string or area passed as an
argument will be takenu

E IEM05781

INVALID USE OF FILE yyy IN
STATEMENT NUMBER xxx. IT HAS
BEEN REPLACED BY A DUMMY
REFERENCE.

• Have the source program
listing available.
S IEM05911

STRUCTURE ELEMENT zzzz IS
LIKENED TO AN ITEM WHICH IS NOT
A STRUCTURE VARIABLE. LIKE
ATTRIBUTE IS IGNORED.
system Action:
Self
explanatory: may result in
cascade errors.

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

system Action: The erroneous
statement is deleted.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM05921

STRUCTURE ELEMENT zzzz IS
LIKENED TO A STRUCTURE WHICH
CONTAINS ELEMENTS walCH HAVE
ALSO BEEN DECLARED WITH THE
LIKE ATTRIBUTE. LIKE ATTRIBUTE
ON ORIGINAL STRUCTURE IS
IGNORED.

• Have the source program
listing available.
S IEM05961

system Action: Self
explanatory: may result in
cascade errors.

System Action: Self
explanatory: may result in
cascade errors.

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the followipg before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM05931

STRUCTURE NAME TO walCH zzzz IS
LIKENED IS NOT KNOWN. LIKE
ATTRIBUTE IGNORED.

• Have the source program
listing available.
S IEM05971

System Action: Self
explanatory: may result in
cascade errors.
~~~rammer

Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

AMBIGUOUS QUALIFIED NAME yyyy
USED AS A BASE IDENTIFIER.
MOST RECENT DECLARATION USED.
Pro~rammer Response:
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEMOS951

QUALIFIED NAME yyyy USED AS A
BASE IDENTIFIER CONTAINS MORE
THAN ONE IDENTIFIER AT THE SAME
STRUCTURE LEVEL.

IDENTIFIER zzzz WHICH IS NOT A
FORMAL PARAMETER OR OF STORAGE
CLASS CONTROLLED HAS BEEN
LIKENED TO A STRUCTURE
CONTAINING * DIMENSIONS OR
LENGTH. * DIMENSIONS OR LENGTH
HAVE BEEN IGNORED IN THE
CONSTRUCTED STRUCTURE.
System Action: Self
explanatory: may result in
cascade errors from later
phases.

• Have the source program
listing available.
E IEM05.941

MAJOR STRUCTURE yyyy HAS BEEN
LIKENED TO AN ITEM walCH IS NOT
A VALID STRUCTURE. DECLARATION
OF STRUCTURE IGNORED.

• Have the source program
listing available.
S IEM05981

QUALIFIED NAME TO WHICH·zzzz
HAS BEEN LIKENED IS AN
AMBIGUOUS REFERENCE. LIKE
ATTRIBUTE HAS BEEN IGNORED.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Appendix K: Diagnostic Messages

347

System Action:
terminated

• Have the source program
listing available.
S IEM05991

Programmer Response:
ProbablE~
user error. If the problem
recurs, do the following befol:e
calling IBM for programming'
support:

zzzz WHICH IS A PARAMETER OR A
BASED VARIABLE, HAS BEEN
DECLARED (USING THE LIKE
ATTRIBUTE) AS A STRUCTURE WITH
THE INITIAL ATTRIBUTE. THE
INITIAL ATTRIBUTE IS INVALID
AND HAS BEEN IGNORED.
Programmer Response: Probable
user error. Declare the
parameter or based variable
with the LIKE attribute
specifying a structure without
the INITIAL attribu,te.
If the
problem recurs, do the
following before calling IBM
for programming support:

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IeMnnnnI messages.)
• Have the associated job
stream and source program
listing available.
T IEM06031

• Have the source program
listing available.
S IEM06001

System Action:
is terminated

Programmer Response: Probable
user er:r:or. Correct pz."ogram
and recompile.
If the problem
recurs, do the following before
calling IBM for progranwing
support:

• Have the source program
listing available.
T IEM06021

348

IDENTIFIER IN BASED ATTRIBUTE
ON ZZZZ DECLARED IN STATEMENT
NUMBER xxx IS NOT A NON-BASED
POINTER

The compilation

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

• Have the source program
listing available.

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for progranwing
support:

it~

Programmer Response:
ProbablE~
user error. If the problem
recurs, do the following befol~e
calling IBM for programming
support:

system Action: All bounds on
the offending variable are set
to zero

OFFSET ATTRIBUTE ON PROCEDURE
STATEMENT NUMBER xxx IS NOT
BASED ON A BASED AREA. IT HAS
BEEN CHANGED TO POINTER.

INVALID POINTER EXPRESSION IN
BASED ATTRIBUTE ON zzzz IN
STATEMENT NUMBER xxx
Explanation:
The pointer
associated with the based
variable does not obey the
implementation rules (e. g.,
may be subscripted).

STATIC STRUCTURE zzzz HAS BEEN
DECLARED BY MEANS OF Tlm LIKE
ATTRIBUTE TO HAVE ADJUSTABLE
EXTENTS. THE EXTENTS HAVE BEEN
IGNORED.
Explanation: A STATIC variable
cannot have adjustable extents

S IEM06011

Compilation is.

• Have the associated job
stream and source program
listing available.
T IEM06041

LENGTH OR SIZE DECLARED FOR
BASED STRING OR BASED AREA ZZ2:Z
IN STATEMENT NUMBER xxx IS
INVALID
Explanation:
The declaration
violates the compiler
implementation rules.
(See
Appendix J, 'Implementation
Conventions and Restrictions').
System Action:
compilation

Terminates

Programmer. Response:
ProbablE~
user error.
If the problem

recurs, do the following before
calling IBM for programming
support:
• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

following before calling IBM
for programming support:
• Have the source program
listing available.
W IEM06071

• Have the associated job
ptream and source program
listing available.
T IEM06051

Explanation: For
correspondence defining not
involving iSUB's, the bounds of
the defined array must be a
subset of the bounds of the
base. In this case the bounds
declared for the base do not
satisfy this requirement.
However, the base is of
CONTROLLED storage class and if
it is allocated with different
bounds the defining may be
legal.

BOUNDS DECLARED FOR BASED ARRAY
zzzz IN STATEMENT NUMBER xxx
ARE INVALID
Explanation: The adjustable
bounds declared are outside
those permitted by this
implementation.
System Action:
compilation

Terminates

System Action:

Prog~er Respo~~e:
Probable
user error. If the problem
recurs, do the following before
calling IBM for programming
support:

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)
• Have the associated job
stream and source program
listing available.
S IEM06061

OFFSET VARIABLE zzzz HAS BEEN
DECLARED IN STATEMENT NUMBER
xxx RELATIVE TO AN IDENTIFIER
WHICH IS NOT A LEVEL 1 BASED
AREA.
IT HAS BEEN CHANGED TO A
POINTER VARIABLE.
system Action: The offset is
changed to a pointer to prevent
the compiler from producing
further error messages.
Programmer Response: Probable
user error. Consider assigning
the ADDR of the required area
to the pointer named in the
declaration of a level 1 based
area; this area can be validly
named in the OFFSET attribute,
and offset values for it will
be correct for the other area.
If the problem recurs, do the

IF THE BASE OF zzzz
CORRESPONDENCE DEFINED IN
STA'l'EMENT NUMBER xxx IS
ALLOCATED WITH THE DECLARED
BOUNDS ·THE DEFINING WILL BE IN
ERROR.

Nothing further

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
T IEM06081

ILLEGAL DEFINING IN STATEMENT
NUMBER XXK. BASE IDENTIFIER
zzzz IS A MEMBER OF A
DIMENSIONED STRUCTURE.
Explanation: In the case of
string class overlay defining
where the base is an array, it
is an error if it is a member
of an array of structures.
system Action:
is terminated.

The compilation

Programmer Response:
Probable
user error. Refer to the PL/I
(F) Language Reference Manual "The DEFINED Attribute" - and
correct error.
If the problem
recurs, do the following before
calling IBM for programming
support:
'
• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
AppendiK K: Diagnostic Messages

349

formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

comments which precede all
the IEMnnnnI messages.)
• Have the associated job
stream and source program
listing available.
T IEM0609I

DEFERRED FEATURE. DEFINING OF
zzzz DECLARED IN STATEMENT
NUMBER xxx WITH A SUBSCRIPTED
BASE.

• Have the associated job
stream and source program
listing available.
T IEM0611I

Explanation: Overlay defining
on a subscripted base is not
supported by this version of
the compiler.

SCALAR zzzz DECLARED IN
STATEMENT NUMBER xxx IS
ILLEGALLY DEFINED WITH ISUBS.
Explanatio~:

Only arrays may

be correspondence defined using

iSUB notation.
System Action:
is terminated.

The compilation
System Action:
is terminated.

Programmer Response:
Probable
user error. Replace all
references to the defined item
by appropriate subscripted
references to the base. If the
problem recurs, do the
following before calling IBM
for programming support:

Programmer Response: ProbablE~
user error. Refer to the PL/J
(F) Language Reference Manual nThe DEFINED Attribute n - and
correct error.
If the problem
recurs, do the following befol~e
calling IBM for programming
support:

• Recompile the progl~am with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messaqes.)

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

• Have the associated job
stream and source program
listing available.
T IEM0610I

DEFERRED FEATURE~ DEFINING OF
zzzz DECLARED IN STATEMENT
NUMBER xxx ON A BASE OF
CONTROLLED STORAGE CLASS.

• Have the associated job
stream and source program
listing available.
E IEM0612I

Explanation:
If the base is
declared CONTROLLED, neither
overlay defining nor
correspondence defininq is
supported by this release of
the compiler.
system Action:
is terminated.

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
350

INITIAL ATTRIBUTE DECLARED FOR
DEFINED ITEM zzzz IN STATEMEN,]~
NUMBER xxx WILL BE IGNORED.
EXplanation:
DEFINED items may
not have the INITIAL attributE~.
system Action:
INITIAL
attribute ignored
Programmer Response:
ProbablE~
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

The compilation

Programmer R~nse: Probable
user error. Replace all
references to the defined item
by appropriate references to
the base. If the problem
recurs, do the following before
calling IBM for programming
support:

The compilaticm

• Have the source program
listing available.
S IEM0613I

ELEMENT VARIABLE SPECIFIED IN
REFER OPTION IN STATEMENT
NUMBER xxx IS NOT AN INTEGER.
Explanation:
Both I and N in
(I REFER(N»
must be fixed

binary integers; they must also
be of the same precision.

• Recompile the program with
compiler options
'S,DP::;:(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

system Action: Compilation
continues. Any reference to
the element variable may result
in an execution error.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming.
support:

• Have the associated job
stream and source program
listing available.
T IEM06241

• Have the source program
listing available.
S IEM06141

Explanation: The base of
DEFINED data may not itself be
DEFINED.

ELEMENT VARIABLES SPECIFIED IN
REFER OPTION IN STATEMENT
NUMBER xxx DO NOT HAVE THE SAME
PRECISION.

System Action:
terminated

Explanation: Both I and N in
(I REFER(N» must be fixed
binary integers of the same
precision.

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
cOmments which precede all
the IEMnnnnI messages.)

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
THE BASE SUBSCRIPT LIST USED
WITH THE DEFINED VARIABLE zzzz
IN STATEMENT NUMBER xxx
ILLEGALLY REFERS TO OR IS
DEPENDENT ON THE DEFINED
VARIABLE.

Compilation

Programmer Response: Probable
user error. Replace the
specified base by an
appropriate reference to its
base. If the problem recurs,
do the following before calling
IBM for programming support:

System Action: Compilation
continues. Any reference to
either element variable may
result in an execution error.

T IEM06231

THE BASE IDENTIFIER FOR zzzz
DECLARED IN STATEMENT NUMBER
xxx IS DEFINED OR BASED.

• Have the associated job
stream and source program
listing available.
T IEM06251

THE DEFINING BASE FOR zzzz
DECLARED I N STATEMENT NUMBER
xxx HAS THE WRONG NUMBER OF
SUBSCRIPTS.

Explanation: It is illegal for
a base subscript list in the
DEFINED attribute to refer
directly, or via any further
level of defining, to the
defined item.

Explanation: If the base
reference in a DEFINED
attribute is subscripted, it
must have the same number of
subscr~pt expressions as the
dimensionali.ty of the base
array.

System Action:
is terminated.

System Action:
is terminated.

The compilation

Programmer Response: Probable
user error. Refer to the PL/I
(F) Language Reference Manual nThe DEFINED Attribute n - and
correct error. If the problem
recurs, do the following before
calling IBM for programming
support:

The compilation

Programmer Response: Probable
user error. Correct the
subscript list, or declaration
of the base, whichever is
appropriate. If the problem
recurs, do the following before
calling IBM for programming
support:
Appendix K: Diagnostic Messages

351

formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler. (Refer to the
comments which precede all
the IEMnnnnI messages.)
• Have the associate<] job
stream and source program
listing available.
T IEM0626I

• Have the associated job
stream and source program
listing available.
T IEM06291

THE DEFINING BASE FOR zzzz
DECLARED IN STATEMENT NUMBER
xxx IS NOT DATA.

Explanation: The POS attribut:e
may not be specified for
correspondence defining.

Explanation: The only legal
data types that may be used for
defining bases are String,
Arithmetic, Task, Event:, and
Label.
system Action:
is terminated.

System Action:
is terminated.

Programmer Response: Probable
user error. Check that: the
defining base is correctly
written and declared. If the
problem recurs, do the
following before calling IBM
for programming support:

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
1:.he IEMnnnnI messages.)

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler. (Refer to the
comments which precede all
the IEMnnnnI messa~res .. )

• Have the associated job
stream and source program
listing available.
T IEM06301

T IEM0628I

IMPLEMENTATION RESTRICTION.
THE NESTING OF REFERENCES TO
DATA DEFINED WITH A SUBSCRIPTED
BASE IS TOO DEEP~
Explanation: The complexity of
defining has resulted in a
level of nesting which is too
great for the compiler.
system Action:
is terminated.

352

The compilation

The compilation

Programmer Response: ProbablE~
user error. Delete POS
attribute If the problem
recurs, do the following befol:e
calling IBM for programming
support:

The compilation

• Have the associated job
stream and source program
listing available.

ARRAY zzzz DECLARED IN
STATEMENT NUMBER xxx ILLEGALLY
HAS THE pas ATTRIBUTE WITH ISUB
DEFINING.

THE DESCRIPTION OF zzzz
CORRESPONDENCE DEFINED IN
STATEMENT NUMBER xxx DOES NOT
MATCH THAT OF THE DEFINING
BASE ..
Explanation: For
correspondence defining, if
either the base or the defined
item are arrays of structures.,
then both must be arrays of
structures.
System Action:
is terminated.

The compilaticm

Programmer Response: Probable
user error. Reduce complexity
of defining. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: ProbablE~
user error. Correct the
program. Note that POS (1) may
be used to force overlay
defining. If the problem
recurs, do the following befol:e
calling IBM for programming
support:

• Recompile the progl~am with
compiler options
'S,DP=(PIE,ZZ), to obtain a

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a

formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

Programmer Response: Probable
user error. Refer to the PL/I
(F) Language Reference Manual "The DEFINED Attribute" - and
correct program. Note that POS
(1) may be used to force
overlay defining. If the
problem recurs, do the
following before calling IBM
for programming support:

• Have the associated job
stream and source program
listing available.
T IEM06311

IMPLEMENTATION RESTRICTION.
THE CORRESPONDENCE DEFINING OF
yyyy AN ARRAY OF STRUCTURES
DECL~RED IN STATEMENT NUMBER
xxx.

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

Explanation: correspondence
defining with arrays of
structures is not supported by
the compiler.
System Action:
is terminated.

• Have the associated job
stream and source program
listing available.

The compilation
S IEM06331

Programmer Response: Probable
user error. Declare the base
arrays of the defined structure
as correspondence defined on
the matching base arrays of the
base structure. Note that for
this to be valid, the base
arrays of the defined structure
must have unique names and be
declared at level 1. This
alternative method precludes
structure operations with the
defined item, but achieves the
desired mapping. If the
problem recurs, do the
following before calling IBM
for programming support:

Explanation: An identifier
specified in an ALLOCATE
statement must refer to a major
structure or data not contained
in a structure. A major
structure identifier may
optionally be followed by a
full structure description.
system Action: The ALLOCATE
statement is deleted
Programmer Response: Probable
user error. Replace erroneous
identifier by that of the
containing major structure. If
the problem recurs, do the
following before calling IBM
for programming support:

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)
• Have the associated job
stream and source program
listing available.
T IEM06321

THE BOUNDS OF zzzz
CORRESPONDENCE DEFINED IN
STATEMENT NUMBER xxx ARE NOT A
SUBSET OF THE BASE.
Explanatiq!!: For
correspondence defining not
involving iSUB's, the bounds of
the defined array must be a
subset of the corresponding
bounds of the base array.
system Action:
is terminated.

The compilation

ITEM TO BE ALLOCATED IN
STATEMENT NUMBER xxx IS NOT AT
LEVEL 1. THE STATEMENT HAS
BEEN IGNORED.

• Have the source program
listing available.
S IEM06341

ITEM TO BE ALLOCATED IN
STATEMENT NUMBER xxx HAS NOT
BEEN DECL~RED.
THE STATEMENT
HAS BEEN IGNORED.
Explanation: Only CONTROLLED
data may be allocated. Data
may only obtain the attribute
CONTROLLED from an explicit
declaration.
System Action: The ALLOCATE
statement is deleted
Programmer Response: Probable
user error. Construct a
DECLARE statement for the

~ppendix

K: Diagnostic Messages

353

Programmer Response:
ProbablE!
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

identifier. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
S IEM06361

ITEM TO BE ALLOCATED IN
STATEMENT NUMBER xxx WAS NOT
DECLARED CONTROLLED. THE
STATEMENT HAS BEEN IGNORED.

• Have the source program
listing available.
S IEM06401

Explanation: Only CONTROLLED
data may be specified in
ALLOCATE statements.

Explanatio~:

Only CHAR, BIT,
INITIAL, and Dimension
attributes are permitted in
ALLOCATE statements.

system Action: The ALLOCATE
statement is deleted

§ystem Action: The ALLOCATE
statement is deleted

Programmer Response: Probable
user error. Declare the
identifier CONTROLLED. If the
problem recurs, do the
following before calling IBM
for programming support:

Proqramme~ Response:
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
E IEM06371

A CONFLICTING ATTRIBUTE WAS
GIVEN FOR zzzz IN STATEMENT
NUMBER xxx. THE ATTRIBUTE HAS
BEEN IGNORED.

• Have the source program
listing available.
E IEM06411

~~!anatio~:

Attributes given
for an identifier in an
ALLOCATE statement may not
conflict with those given
explicitly or assumed by
default from the declaration.

System .Action: All attributes
after the first in a particular
class are ignored.

Programmer ResE2ns~l Probable
user error. correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response:
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
THE STRUCTURE DESCRIPTION GIVEN
ON STATEMENT NUMBER xxx DIFFERS
FROM THAT DECLARED. THE
STATEMENT HAS BEEN IGNORED.

• Have the source program
lis·ting available.
S IEM06421

~~lanation:

If a description
of a major structure is given
on an ALLOCATE statement, the
description must match that
declared.
System Action: The ALLOCATE
statement is deleted
354

CONFLICTING ATTRIBUTES HAVE
BEEN GIVEN FOR zzzz IN
STATEMENT NUMBER xxx. THE
FIRST LEGAL ONE HAS BEEN USED.
Explanation:
At most, one
attribute in the following
classes may be given for an
identifier in an ALLOCATE
statement: Dimension,
String(CHAR or BIT), INITIAL.

system Acti2~: Ignores the
attribute from the ALLOCATE

S IEM06381

AN INVALID ATTRIBUTE WAS GIVEN
IN S'I'ATEMENr NUMBER xxx. THE
STATEMENT HAS BEEN IGNORED.

DIMENSIONALITY GIVEN IN
STATEMENT NUMBER xxx DIFFERS
FROM THAT DECLARED. THE
STATEMENT HAS BEEN IGNORED.
Explanation:
If a dimension
attribute is given for an
identifier in an ALLOCATE
statement, the identifier must

have been declared with the
same dimensionality.

Explanations: Based variable
may not be specified with
attributes

system Action: The ALLOCATE
statement is deleted
Programmer Response: Probable
user error. Correct ALLOCATE
statement. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Respon~~~ Probable
user error. Correct
declaration or ALLOCATE
statement w whichever
applicable.
If the problem
recurs w do the following before
calling IBM for programming
support:
• Have the source program
listing available.
W IEM06431

• Have the source program
listing available.
S IEM06461

THE LEVEL NUMBER DECLARED FOR
zzzz IS NOT 'l'HE SAME AS THAT
GIVEN IN STATEMENT NUMBER xxx.
THE FORMER HAS BEEN USED.

System Action: The identifier
is replaced by a dummy
dictionary reference; a later
phase will delete the
statement.

Explanation: If a structure
description is 'given in an
ALLOCATE Statement w it must
match the declaration. The
indicated level number
discrepancy may be an error.
system Action:

Response: Probable
user error. Correct the
invalid statement. If the
problem recurs w do the
following before calling IBM
for programming support:

~Eoqrammer

Nothing further

Programmer Response: Probable
user error. Check that
ALLOCATE statement is as
intended. If the problem
recurs w do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM06471

IEM061~41

STAl'EMENT NUMBER xxx CONTAINS
AN ILLEGAL PARENTHESIZED LIST.
THE STATEMENT HAS BEEN IGNORED.

Programmer Response: Probable
user error. Correct the
invalid statement. If the
problem recurs, do the
following before calling IBM
for programming support:

Explanation: Factored
attribures are not allowed on
ALLOCATE statements.
system Action:
ignored

Statement

Programmer Response: Probable
user error. Remove parentheses
and any factored attributes.
If the problem recurs w do the
following before calling IBM
for programming support:
• Have the source program
listing available.
S IEM06451

POINTER-QUALIFIED IDENTIFIER
zzzz IN STATEMENT NUMBER xxx IS
NOT A BASED VARIABLE
system Action: Identifier is
replaced by a dummy dictionary
reference; a later phase will
delete the statement.

• Have the source program
listing available.
S

IDENTIFIER yyyy PRECEDING
POINTER QUALIFIER IN STATEMENT
NUMBER xxx IS NOT A NON-BASED
POINTER VARIABLE

ATTRIBUTE GIVEN WITH BASED
VARIABLE zzzz IN ALLOCATE
STATEMENT NUMBER xxx HAS BEEN
IGNORED.

• Have the source program
listing available.
T IEM06531

COMPILER ERROR. ILLEGAL ENTRY
IN STATEMENT NUMBER xxx
Explanation: compiler error
found in scan of statement
§ystem Action:
terminated

Compilation

Programmer Response: Do the
following before calling IBM
for programming support:
Appendix K: Diagnostic Messages

355

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of the
compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

S IEM06581

system Action:
Statement will
be deleted by later phase
Programmer Response:
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the associated job
stream and source program
listing available.
S IEM06551

QUALIFIED NAME BEGINNING yyyy
USED IN STATEMENT NUMBER xxx
BUT NO PREVIOUS STRUCTURE
DECLARATION GIVEN.. DUMMY
REFERENCE INSERTED.

• Have the source program
listing available.
S IEM06591

System.Action: Reference to
the illegal variable or the
whole statement will be deleted
by later phases.

UNSUPPORTED FEATURE. STRING
PSEUDO-VARIABLE APPEARS IN
REPLY, KEYTO OR STRING OPTION
IN STATEMENT NUMBER xxx.
STATEMENT WILL BE DELETED BY A
LATER PHASE.

Programmer Response: Probable
user error. Correct program by
inserting DECLARE statement.
If the problem recurs, do the
following before calling IBM
for programming support:

Programmer Response:
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following befor1e
calling IBM for programming
support:

• Have the source program
listing available.
E IEM06561

MOST RECENT DECLARATION USED OF
AMBIGUOUS QUALIFIED NAME OR
STRUCTURE MEMBER BEGINNING yyyy
IN STATEMENT NUMBER xxx

• Have the source program
listing available.
S IEM06601

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

system Action: The statement
will be deleted by a later
phase.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

QUALIFIED NAME BEGINNING yyyy
I N STATEMENT NUMBER xxx
CONTAINS MORE THAN ONE
IDENTIFIER AT THE SAME
STRUCTURE LEVEL.
system Action:
is deleted

• Have the source program
listing available.

The sta'tement
S IEM06611

Programmer Response: P:robable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
356

PSEUDO-VARIABLE yyyy IN
STATEMENT NUMBER xxx IS INVALID
BECAUSE Ir IS NESTED IN ANOTHER
PSEUDO-VARIABLE.
Explanation:
Language
restriction. Pseudo-variables
cannot be nested.

• Have the source program
listing available.
E IEM06571

QUALIFIED NAME BEGINNING yyyy
IN STATEMENT NUMBER xxx IS AN
AMBIGUOUS REFERENCE. DUMMY
REFERENCE INSERTED.

INVALID USE OF THE
PSEUDO-VARIABLE 'PRIORITY' IN
STATEMENT NUMBER xxx~ THE TASK
OPTION HAS NOT BEEN SPECIFIED
IN THE EXTERNAL PROCEDURE.
Explanation: The PRIORITY
pseudo-variable can be used
only in a multitasking
environment.

system Action:
is deleted.

calling IBM for programming
support:

The statement

Pro~rammer Response:
Probable
user error. Recompile Vlith the
TASK option in the external
procedure options list. If the
problem recurs, do the
following before calling IBM
for programming support:

• Have the source program
listing available.
S IEM06751

• Have the source program
listing available.
E IEM06621

§ystem Action: Statement
deleted by later phases.

IN STATEMENT NUMBER xxx CHECK
LIST CONTAINS DEFINED ITEM yyy.
IT HAS BEEN REPLACED BY ITS
BASE IDENTIFIER.

Programmer Response: Probable
user error. correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Explanation: Defined items are
not permitted in CHECK lists.
system Action: The base item
is assumed to replace the
reference to the defined item
in the CHECK list. References
in the text to the defined item
will not be checked.

• Have the source program
listing available.
S IEM06761

Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
Pro~rammer

System Action:
Statement
deleted by later phases

INVALID USE OF FUNCTION NAME ON
LEFT HAND SIDE OF EQUAL SYMBOL,
OR IN REPLY KEYTO OR STRING
OPTION, IN STATEMENT NUMBER xxx

Programmer Response: Probable
user error. Correct statement
by removing reference to
function in error. If the
problem recurs, do the
following before calling IBM
for programming support:

system Action: Statement will
be deleted by later phases
Programmer Respon~g~ Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM06771

• Have the source program
listing available.
SIEM06'141

STATEMENT NUMBER xxx CONTAINS
ILLEGAL USE OF FUNCTION yyyy
system Action: Reference to
function or whole statement
Vlill be deleted by later phases
Rrog~ammer_E~~PQnsel

Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before

DEFERRED FEATURE. IDENTIFIER
yyyy NOT ALLOWED AS A BUILT-IN
FUNCTION OR PSEUDO-VARIABLE •
DUMMY REFERENCE INSERTED IN
STATEMENT NUMBER xxx
Explanation: A language
feature has been used that is
not supported by this version
of the compiler. For details,
refer to Appendix J of this
publication.

• Have the source program
listing available.
S IEM06731

IN STATEMENT NUMBER xxx
IDENTIFIER yyyy AFTER GO TO IS
NOT A LABEL OR LABEL VARIABLE
KNOWN IN THE BLOCK CONTAINING
THE GO TO.

ILLEGAL PARENTHESIZED LIST IN
STATEMENT NUMBER xxx FOLLOWS AN
IDENTIFIER WHICH IS NOT A
FUNCTION OR ARRAY.
LIST
DELETED.
Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

Appendix K: Diagnostic Messages

357

S IEM06821

calling IBM for programming
support:

IN STATEMENT NUMBER xxx GO TO
TRANSFERS CONTROL ILLEGALLY ro
A FORMAT STl~TEMENT.
Programmer Response: Probable
user error. Correct program
and recompile. If -the problem
recurs, do the following before
calling IBM for programming
support:

• Have the, source program
listing available.
S IEM06861

• Have the source program
listing available.
S IEM06831

i

System Action~ A dummy
reference is inserted. The
sta tement will be deleted by
later phase

zzzz WAS FOUND WHERE A FILENAME
IS REQUIRED IN STATEMENT NUMBER
xxx. DUMMY DICTIONARY
REFERENCE REPLACES ILLEGAL
ITEM.

• Have the source program
listing'available.
E IEM06871

IN STATEMENT NUMBER xxx
DICTIONARY REFERENCE zzzz
TRANSFERS CONTROL ILLEGALLY TO
ANOTHER BLOCK OR GROUP.
EXECUTUION ERRORS MAY OCCUR.

B IEM06881

COMPILER ERROR. TOO FEW LEFT
PARENTHESES IN STATEMENT NUMBE~R
xxx

• Have the source program
listing available.
W IEM06841

USE OF LABEL VARIABLE zzzz MAY
RESULT IN AN ILLEGAL BRP1NCH IN
STATEMENT NUMBER xxx
Explanation: It is possible
that the label variable may
contain a value which would
cause control to branch
illegally into a block.

Explanation: This is a
compiler error
system Action: None taken.
Cascade errors may result.
Programmer Response: Do the
following before calling IBM
for programming support:

Proqrammer Response! Probable
user error. Check validity of
possible branches. If the
problem recurs, do the
following before calling IBM
for progra~ning support:

• Recompile the program with
compiler options
'S,DP=(PIE,FI), to obtain a
formatted dump of the
compiler. (Refer to the
comments which precede all
the IEMnnnnI messages.)

• Have the source program
listing available.
S IEM06851

zzzz IS NOT A STATEMENT LP1BEL
ON AN EXECU1'ABLE STATEMENT.
DUMMY REFERENCE INSERTED ~FTER
GO TO IN STATEMENT NUMBER xxx
system Action: statement will
be deleted by later phases
ProqrammerResponse: Probable
user error. Correct pl:ogram
and recompile. If the problem
recurs, do the following before

358

SL

Programmer Response: ProbablE!
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

System Action: statement will
be deleted by later phases
Proqrammer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

zzzz APPEP1RS IN A FREE OR
ALLOCATE STP1TEMENT BUT HAS NO'l'
BEEN DECLARED CONTROLLED.
DUMMY REFERENCE INSERTED IN
STP1TEMENT NUMBER xxx.

• Have the associated job
stream and source program
listing available.
S IEM06891

zzzz WAS FOUND WHERE A TASK
IDENTIFIER IS REQUIRED IN
STATEMENT NUMBER xxx. DUMMY
REFERENCE INSERTED.
§.ystem Action: Statement will
be deleted by later phases

Programmer Respons·e: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

System Action:
Statement will
be deleted by later phases
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM06901

zzzz WAS FOUND WHERE EVENT
VARIABLE IS REQUIRED IN
STATEMENT NUMBER xxx. DUMMY
REFERENCE INSERTED.

• Have the source program
listing available.
S IEM06941

System Action: Statement will
be deleted by later phases
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

System Action: Format item
deleted by later phase
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM06911

INVALID ITEM zzzz IN DATA LIST,
OR 'FROM' OR 'INTO' OPTION, IN
STATEMENT NUMBER xxx
system Action: Statement will
be deleted by later phases

• Have the source program
listing available.
S IEM06951

~rogrammer ResPQ~~~~

Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Action:
Statement will
be deleted by later phases

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

DATA DIRECTED I/O LIST OR FROM
OR INTO OPTION IN STATEMENT
NUMBER xxx CONTAINS A
PARAMETER, DEFINED OR BASED
ITEM zzzz.
System Actio~: Statement will
be deleted by later phases
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

S -IEM06931

ILLEGAL USE OF FUNCTION zzzz IN
INPUT LIST IN STATEMENT NUMBER
xxx.
DUMMY REFERENCE INSERTED.

LABEL ARRAY zzzz IS NOT
FOLLOWED BY A SUBSCRIPT LIST
AFTER GO TO IN STATEMENT NUMBER
xxx. DUMMY REFERENCE REPLACES
REFERENCE TO ARRAY.
~stem

• Have the source program
listing available.
S IEM06921

IN THE FORMAT LIST IN STATEMENT
NUMBER xxx A REMOTE FORMAT ITEM
REFERENCES zzzz, WHICH IS NOT A
STATEMENT LABEL IN THE CURRENT
BLOCK. DUMMY REFERENCE
INSERTED.

• Have the source program
listing available.
W IEM06961

IN STATEMENT NUMBER xxx IT IS
AN ERROR IF THE PARAMETER zzzz
IN A REMOrE FORMAT ITEM REFERS
TO A FORMAT STATEMENT WHICH IS
NOT INTERNAL TO THE SAME BLOCK
AS THE REMOTE FORMAT ITEM.
Explanation: Remote formats
become executable code, but not
internal procedures. Therefore
they must appear in the same
block in which they are used.
system Action: Object-time
error message is compiled

Appendix K: Diagnostic Messages

359

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

OR VARYING STRING zzzz AS
ARGUMENT OF FROM OR INTO OPTION
IN STATEMENT NUMBER xxx. DUMMY
REFERENCE INSERTED.
system Action:
statement
deleted by later phase

• Have the source program
listing available.
S IEM06971

Programmer Response: ProbablE~
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

STATEMENT LABEL zzzz ATTACHED
TO STATEMENT NUMBER xxx IS USED
AS A REMOTE FORMAT ITEM IN TH~T
STATEMENT. A DUMMY REPLACES
THE REMOTE FORMAT ITEM.

• Have the source program
listing available.

System Action: statement will
be deleted by a later phase
S IEM07011
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

system Action:
statement
deleted by later phase.
Programmer Response: ProbablE!
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM06981

THE BASED VARIABLE zzzz IN
LOCATE STATEMENT NUMBER xxx IS
NOT AT LEVEL 1. DUMMY
REFERENCE INSERTED.
System Action: The statement
will be deleted by a later
phase.

• Have the source program
listing available.
W IEM07021

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

STRUCTURE ARGUMENT zzzz OF FROM
OR INTO OPTION IN STATEMENT
NUMBER xxx IS NOT A MAJOR
STRUCTURE. DUMMY REFEREN:E
INSERTED
System Action: statement
deleted by later phase
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

S IEM07001
360

ILLEGAL USE OF FUNCTION, LABEL

TASK OR EVENT VARIABLE
zzzz USED IN FROM OR INTO
OPTION IN STATEMENT NUMBER xxx
MAY LOSE ITS VALIDITY IN
TRANSMISSION
L~BEL,

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM06991

ARGUMENT zzzz OF SET OPTION IS:
NOT A POINTER VARIABLE. DUMMY
REFERENCE INSERTED.

• Have the source program
listing available.
S IEM07031

INVALID IDENTIFIER zzzz FREED
IN STATEMENT NUMBER xxx
Explanation: The identifier in
the FREE statement is not:
1.

A BASED or a CONTROLLED
variable, or

2.

A major structure with the
BASED or CONTROLLED
attribute.

System Action:
Invalid
identifier replaced by dummy.
Programmer Response:

Probable

user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct the
invalid statement. If the
problem recurs, do the
following before calling IBM
for programming support:

• Have the source program
listing available.
S IEtvl07041

• Have the source program
listing available.

STArEMENT NUMBER xxx CONTAINS
INVALID USE OF FUNCTION zzzz
S IEM07151
system-Actio~:
del~ted

statement
by later phase

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

Explan~io!!:

The INITIAL
attribute has been used
incorrectly.

system Action: The INITIAL
attribute is deleted

• Have the source program
listing available.
W IEM07051

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

IF THE LABEL VARIABLE IN GO T::>
STATEMENT NUMBER xxx ASSUMES
THE VALUE OF ITS VALUE-LIST
MEMBER zzzz, THE STATEMENT WILL
CONSTITUTE AN INVALID BRANCH
INTO AN ITERATIVE DO GROUP.
system Action:

• Have the source program
listing available.

None
S IEM07181

Programmer Response: Probable
user error. Check that branch
will be valid at execution
time. If the problem recurs,
do the following before calling
IBM for programming support:

VARIABLE zzzz IN LOCATE
STATEMENT IS NOT A BASED
VARIABLE~
DUMMY REFERENCE
INSERTED.

• Have the source program
listing available.
S IEM07191

System Action: The statement
is deleted by a later phase.
Programmer Response: Probable
user error. Correct the
invalid Btatement. If the
problem recurs, do the
following before calling IBM
for programming support:

Label is

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

ARGUMENT zzzz OF IN OPTION IS
NOT AN AREA VARIABLE. DUMMY
REFERENCE INSERTED.

• Have the source program
listing available.
S IEM07201

§.Y2.!::gm A9tiog: The statement
is deleted by a later phase.

ELEMENT OF LABEL ARRAY zzzz
walCH IS DECLARED WITH INITIAL
ATTRIBUTE USED AS STATEMENT
LABEL ON STATEMENT NUMBER xxx
System Action:
deleted

• Have the source program
listing available.
S IEM07071

INVALID CHECK LIST IN STATEMENT
NUMBER xxx. STATEMENT HAS BEEN
CHANGED TO 'ON ERROR'.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM07061

TEXT yyyy ASSOCIATED WITH THE
INITIAL ATTRIBUTE IN STATEMENT
NUMBER xxx IS ILLEGAL AND HAS
BEEN IGNORED.

SUBSCRIPTED IDENTIFIER zzzz
USED AS LABEL ON STATEMENT
NUMBER XXK IS NOT A LABEL ARRAY

Appendix K: Diagnostic Messages

361

system Action:
deleted

compiler.
(Refer to the
comments which precede all
the IEMnnnnI messages.)

Label iB

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the associated job
stream and source program
listing available.
S IEM07241

• Have the source proc]'ram
listing available.
S IEM07211

Explanation: The identifier
list of a CHECK prefix must not.
contain formal parameters

ELEMENT OF STATIC LABEL ARRAY
zzzz USED AS LABEL ON S~rATEMENT
NUMBER xxx
system Action:
deleted

Programmer Response:
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following befor(~
calling IBM for programming
support:

Label is

Pro~~er Response:.
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
S IEM07251

• Have the source program
listing available.
S IEM07221

ELEMENT OF LABEL ARRAY zzzz
USED AS LABEL ON STATEMENT
NUMBER xxx IN BLOCK OTHER TF~N
THE ONE IN WHICH IT IS
DECLARED.

Programmer Response:
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
S IEM07261

COMPILER ERROR IN STATEMENT
NUMBER xxx
Explanation: Compiler error
found in scan of text
System Actio!!:
terminated

IDENTIFIER zzzz IN STATEMENT
NUMBER xxx IS NOT A FILE NAME.
THE STATEMENT IS DELETED.
Explanation: The identifier
has been used previously in a
different context and is
therefore not recognized as a
file name.

• Have the source program
listing available.
T IEM07231

STATEMENT NUMBER xxx HAS BEEN
DELETED DUE TO A SEVERE ERROR
NOTED ELSEWHERE.
System Action: The whole
statement is replaced by an
error statement.

system Action: An error
statement is inserted in the
text in place of the offending
label.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

FORMAL PARAMETER zzzz IN CHECK
LIST. PARAMETER IS IGNORED.

Programmer Response:
Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:

Compila.tion

Respon2!H. Do the
following before calling IBM
for programming support.:
Prog~er

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ)' to obtain a
formatted dump of t.he
362

• Have the source program
listing available.
S IEM07271

IDENTIFIER zzzz IN STATEMENT
NUMBER xxx IS NOT A CONDITION
NAME. THE STATEMENT IS
DELETED.

Explanation: The identifier
has been used previously in a
different context and is
therefore not recognized as a
condition name

S IEM01301

MORE THAN ONE SIGN CHARACTER
PRESENT IN A SUBFIELD OF
PICTURE yyyy. THIS PICTURE
OCCURS IN STATEMENT NUMBER xxx,
AND POSSIBLY IN OTHER
ST~TEMENTS.

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

system Action: Scan of picture
terminated; picture ignored by
later phases.
Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:

• Have the source program
listing available.
T IEM07281

COMPILATION TERMINATED DUE TO A
PREVIOUSLY DETECTED SEVERE
ERROR IN STATEMENT NUMBER xxx
Explanatioh: A previous module
has inserted a dummy dictionary
reference into the second file.
The compiler cannot recover.

• Have the source program
listing available.
S IEM01311

Programmer ReSpOnSe! Probable
user error. If the problem
recurs, do the following before
calling IBM for progra~ng
support:

PICTURE CHARACTER M APPEARS IN
NON-STERLING PICTURE yyyy.
THIS PICTURE OCCURS IN
STATEMENT NUMBER xxx, AND
POSSIBLY.IN OTHER STATEMENTS.
system Action: Scan of picture
terminated; picture ignored by
later phases.

• Recompile the program with
compiler options
'S,DP=(PIE,ZZ), to obtain a
formatted dump of the
compiler~
(Refer to the
comments which precede all
the IEMnnnnI messages.)

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.

• Have the associated job
stream and source program
listing available.
S IEM01321
S IEM07291

COMPILER ERROR IN SCALE F~CTOR
IN PICTURE BEGINNING yyyy.
THIS PICTURE OCCURS IN
STATEMENT NUMBER xxx, AND
POSSIBLY IN OTHER ST~TEMENTS.

.l

system ~ction: Scan of picture
terminated; picture ignored by
later phases.

System Action: Scan of picture
halted. ~ll references to
picture deleted.

Programmer Response: Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
calling IBM for progra~ng
support:

Programmer Response: Do the
following before calling IBM
for programming support:
• Recompile the program with
compiler options
'S,DP=(PIE,FO), to obtain a
formatted dump of the
compiler. (Refer to the
comments which precede all
the IEMnnnnI messages.)
• Have the associated job
stream and source program
listing available.

FIELD MISSING IN STERLING
PICTURE yyyy. THIS PICTURE
OCCURS IN STATEMENT NUMBER xxx,
AND POSSIBLY IN OTHER
STATEMENTS.

• Have the source program
listing available.
S IEM01331

ILLEG~L EDIT CHARACTERS AT
START OF STERLING PICTURE yyyy.
THIS PICTURE OCCURS IN
STATEMENT NUMBER xxx, AND
POSSIBLY IN OTHER STATEMENTS.

~ppendix

K: Diagnostic Messages

363

System Action: Scan of picture
terminated; picture ignored by
later phas es •
Programmer Response: Probable
user error. correct program
and recompile.
If the problem
recurs, do the followinq before
calling IBM for programming
support:

Programmer Response: Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following before
calling IBM for programming
support:
• Have the source program
listing available.
S IEM07371

• Have the source program
listing available.
S IEM07341

ILLEGAL CHARACTER OR ILLEGAL
NUMBER OF CH.ARACTERS IN POUNDS
FIELD OF S~~ERLING PICTURE yyyy.
THIS PICTURE OCCURS IN
STATEMENT NUMBER xxx, AND
POSSIBLY IN OTHER STATEMENTS.

system Action:
Scan of pictur1e
terminated; picture ignored by
later phases.
Programmer Response:
Probable
user error. Correct program
and recompile.
If the problem
recurs, do the following beforle
calling IBM for programming
support:

system Action: Scan of picture
terminated; picture ignored by
later phases.
Programmer Response:
Probable
user error. Correct program
and recompile. If the problem
recurs, do the following before
callin9 IBM for programming
support:

• Have the source program
listing available.
S IEM07391

• Have the source program
listing available.
S IEM0735I

ILLEGAL CHARACTER OR ILLEGAl.
NUMBER OF CHARACTERS IN
SHILLINGS FIELD OF STERLI