SC28 6478 3_DOS_VS_COBOL_Compiler_and_Library_Programmers_Guide_Feb79 3 DOS VS COBOL Compiler And Library Programmers Guide Feb79

SC28-6478-3_DOS_VS_COBOL_Compiler_and_Library_Programmers_Guide_Feb79 SC28-6478-3_DOS_VS_COBOL_Compiler_and_Library_Programmers_Guide_Feb79

User Manual: SC28-6478-3_DOS_VS_COBOL_Compiler_and_Library_Programmers_Guide_Feb79

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

Download
Open PDF In Browser	View PDF

SC28-6478-3

Program Product

IBM DOS/VS COBOL
Compiler and Library
Programmer's Guide
Program Numbers: 5746-CB1 (Complier and Library)
5746-LM4 (Library)

Fourth Edition (February 1979)
This is a major revision of, and obsoletes, SC28-6478-0, -1, and -2. It also obsoletes their
technical newsletters SN28-1063, SN20-9121, SN20-9141, SN20-9180, and SN20-9235.
This edition corresponds to Release 2 of the IBM DOS/VS COBOL Compiler and Library,
program numbers 5746-CBl and 5746-LM4.
Changes are continually made to the information herein; before using this publication in
connection with the operation of IBM systems, consult the latest IBM System/370
Bibliography, GC20-0001, for the editions that are applicable and current.
Publications are not stocked at the address given below; requests for IBM publications
should be made to your IBM representative or to the IBM branch office serving your locality.
Comments may be addressed to IBM Corporation, P.O. Box 50020, Programming Publishing,
San Jose, California U.S.A. 95150. IBM may use or distribute any of the information you
supply in any way it believes appropriate without incurring any obligation whatever. You
may, of course, continue to use the information you supply.

PREFACE;

This publication describes how to
compile a COBOL program using the Program
Product IBM DOS/VS COBOL Compiler. It also
describes how to link edit the resulting
object module, and execute the program.
Included is a description of the output
from each of these three steps: compile,
link edit, and execute. This publication
explains features of the DOS/VS Compiler
and Library, and available options of the
operating system.
This publication is logically and
functionally divided into four parts. Part
I contains information useful to
programmers who are running COBOL programs
compiled on the DOS/VS Compiler, under the
control of the IBM Disk Operating system
Virtual storage. Part I covers such topics
as job control language, library usage, and
interpreting output.
Part II contains supplemental
information on the use of the language as
specified in the publication IBM DOS Full
American National Standard COBOL,
GC28-6394, and should be used in
conjunction with this publication for
coding COBOL programs. Part II covers
in detail such topics as file organization,
file label handling, and record formats.
Part II is intended as reference material
for language features that are primarily
system-dependent.
Part III contains information on
programming techniques useful to the
programmer running COBOL programs compiled
on the DOS/VS Compiler. Topics such as
coding considerations, table handling
considerations, and formatting data are
covered in Part III.
Part IV contains error determination
information. This part covers such topics
as program debugging and program testing.
Diagnostic messages generated by the
DOS/VS Compiler and Library and their
accompanying documentation can be found in
this publications
Information on installing the DOS/VS
Compiler and Library can be found in the
following publication:
IBM DOS/VS COBOL Compiler and LibrarYL
Installation Reference Material,
SC28-6479
Wider ranging and more detailed
discussions of the DOS/VS System are given
in the following publications:

Introduction to
GC33-5370

DO~,

DOS/yS System Generation,
GC33-5377
DOS/yS SY2tem Management Guide,
GC33-5371
DOS/VS Data-Management-Concepts,

GC24-S138

DOS/yS Supervisor a~O Ma£[Q
Reference, GC33-5373
System Control Statements,
GC33-5376

DOS/yS Access Method Services,
GC33-5382
DOS/VS System Utilities Reference,
GC33-5381
DO~Messages,

GC33-5379

The following publications provide
detailed information on the IBM 3886
Optical Character Reader:
IBM 3886 Optical Character Reader
General Information Manual,
GA2l-9l46
IBM 3886 optical Character Reader Input
Document Design and Specifications,
GA2l-9148
DOS~lanning Guide for the IBM 3886
Optical Character Reade~del-1,
GC2l-5059

The following publications provide
information on the IBM DOS/VS Sort/Merge
Program Product, Program Number 5746-SM1,
and the DOS Sort/Merge Program Product,
Program Number 5743-SM1:
IBM DOS/yS SortlMerge General
Information, GC33-4030
IBft DOS/vS Sort/Merge Program Product
Design Objectives, GC33-4027
IBM DOSIVS Sort/Merge Installation
Reference Material, SC33-4026
IBM DOS Sort/Merge Programmer's Guide,
SC33-40l8
The titles and abstracts of related
publications are listed in IBM System/360
and System/370 Bibliography, GA22-6822.

Summary of Amendments

Number 5

Form of Publicationo· Revision SC28-6478-3
New: Programming Function
Support for ftxed block devices is provided under DOS/VSE with
VSE/ Advanced Function, Release 1.

Maintenance: Documentation
Clariftcations and corrections have been made in various areas
of the text.

Editorial changes that have no technical significance are not noted here.
Specific changes to the text made as of this publishing date are indicated by a vertical bar to the
left of the text. These bars will be deleted at any subsequent republication of the page affected.

Summary of Amendments

Number 4

Form of Publication: TNL SN20-9235 to SC28-6478-O, -1,-2

New: Programming Function
Support has been added for the 3330-11 Disk Storage and 3350
Direct Access Storage devices.
Maintenance: Documentation
Minor technical changes and additions have been made to
t!1e text.

Summary of Amendments

Number 3

Date of Publication: December 3, 1976
Form of Publication: TNL SN20-9180 to SC28-64 78-0, -1, -2
IBM DOSNS COBOL

Maintenance: Documentation
Minor technical changes and additions have been made to
the text.

Editorial changes that have no technical significance are not noted here.
Specific changes to the text made as of this publishing date are indicated by a vertical bar to the
left of the text. These bars will be deleted al any subsequem republication of the page affected.

Summary of Amendments

Number 2

Date of Publication: January 9, 1976
Form of Publication: SN20-9141 to SC28-6478-0, -1

Support has been added to run DOS!VS COBOL under control of VM/370 CMS Release 3.
DOS/VS COBOL programs can be compiled in CMS and then executed in a DOS virtual machine, or
under a DOS system.
The following restrictions apply to execution of DOS!VS COBOL programs in CMS:
1. Indexed mes (DTFIS) are not supported. Various clauses and statements are therefore invalid:
RECORD KEY, APPLY CYL-OVERFLOW, NOMINAL KEY, APPLY MASTER/CYL-INDEX,
TRACK-AREA, APPLY CORE-INDEX, and START.
2. Creating direct files is restricted as follows:
-For U or V recording modes, access mode must be sequential.
-For ACCESS IS SEQUENTIAL, track identifier must not be modified.
3. None of the user label-handling functions are supported. Therefore, the label-handling format of
USE is invalid. The data-name option of the LABEL RECORDS clause is invalid.
4. There is no Sort or Segmentation feature.
5. ASCII-encoded tape files are not supported.
6. Spanned records (S-mode) processing is not available. This means that the S-mode default (block
size smaller than record size) cannot be specified, and that the RECORDING MODE IS S clause
cannot be specified.
In addition, multitasking, multipartition operation, and teleprocessing functions are not supported
when executing under CMS.
For a more detailed description of VM/370 CMS for DOS/VS COBOL, see IBM VM/370 eMS User's
Guide for COBOL. order number SC28-6469.

Summary of Amendments
Date of Publication: March 22, 1974
Form of Publication: TNL SN28-1063 to SC28-6478-0
New: Addi tiona! Compiler Capabilities

lister feature
Execution Statistics and
Verb summary feature
SOR T-OPTION

Maintenance: Documentation Only

Minor technical changes and corrections.
Editorial changes that have no technical significance are not noted here.
Specific changes to the text made as of this publishing date are indicated by a .vertical bar to the
left of the text. These bars will be deleted at any subsequent republication of the page affected.

Number 1

CONTENTS

FEATURES OF THE PROGRAM PRODUCT DOS/VS
COMPILER .. •

PART I ..

INTRODUCTION ..
• 11
.. 11
Control Program
11
Supervisor .. ..
Job Control Processor
11
11
Initial Program Loader
11
Processing Programs
.. 11
System Service Programs
Application Programs .. ..
.. .. .. .. .. 12
IBM-Supplied processing Programs .. .. .. 12
.. 12
Data Management .. .. .. • .. .. .. ..
12
Multiprogramming .. .. .. .. .. .. .. .. ..
Background vs. Foreground Programs .. .. 12
JOB DEFINITION • .. .. .. .. .. ..
Job steps
.. .. .. .. ..
Compilation Job Steps
Multiphase Program Execution ..
Types of Jobs .. .. .. .. .. .. .. .. • .. ..
Job Definition Statements
.. .. _
Other Job Control Statements

13
.. 13
13
.. 13
.. 14
.. 15

........ 17
JOB PROCESSING
.. .. .. ..
.. 17
Compilation
.. 17
Editing
.. .. .. .. ..
Phase Execution
18
Multiphase Programs ........
.. 18
PREPARING COBOL PROGRAMS FOR PROCESSING
Assignment of Input/Output Devices .. _ ..
Job Control . . . . . . . . . . . . . . . .. .. .. .. _ ..
Job Control Statements .. .. .. .. .. .. .. ..
Comments in Job Control Statements ..
Statement Formats ...... .. .. .. .. .. •
Sequence of Job Control Statements ..
Description and Formats of Job
Control Statements ..
.. .. .. .. ..
JOB Statement
.. .. .. .. ..
ASSGN Statement
'... _ ..
CLOSE Statement
.. .. .. .. ..
DATE Statement .. ..
TLBL Statement .. ..
..
DLBL Statement .. ..
.. .. .. .. .. ..
EXTENT Statement
.. .. .. ..
VOL, DLAB, TPLAB and XTENT Statements ..
LBLTYP Statement ..
.. .. .. ..
LISTIO Statement ..
..
MTC Statement
OPTION Statement ..
PAUSE Statement
.. .. .. ..
..
RESET Statement ...... _ ..
RSTRT Statement ...... ..
UPSI Statement .. ..
..
..
EXEC Statement ..
CBL Statement -- COBOL Option
Control Card .. .. _
.. .. .. .. ..
LST Statement -- New Compiler
Option Card
.. .. .. .. .. ..

19
19
22
22
22
22
23
23
23

24
26
26

27
28
28
30
30
31
31
32
34
34
34
35
35
36
40

Mutually Exclusive Options .. .. ....
Changing the Installation Defaults
Significant Characters for Various
Options .... .. .. • .. • • .. • .. •
Job Control Commands • • • • • ..
Linkage Editor Control Statements
Control Statement Placement
PHASE Statement
INCLUDE Statement .. • .. •
ENTRY Statement
ACTION Statement ..
Autolink Feature .. ..
Relocating Loader Feature
LIBRARIAN FUNCTIONS
Planning the Libraries • ..
Librarian ... • •
Core Image Library .. ..
Cataloging and ~etieving Program
Phases -- Core Image Library .. .. _
Relocatable Library
• • • .. .. •
Maintenance Functions .. • • .. .. ..
Cataloging a Module -- Relocatable
Library .. • .. .. • .. ..
Source Statement Library ..
.. .. ..
Maintenance Functions .. .. .. • ..
Cataloging a Book
Source
Statement Library
Updating Books -- Source Statement
Library • • .. .. • .. .. • .. .. .. • ..
UPDATE Function -- Invalid Operand
Defaults .. • .. • .. .. ..
The Procedure Library
MAINT, Procedure Library ~
Catalog
PSERV, Procedure Library ..
Calling Cataloged Procedures ..
Private Libraries . . . . . . . • ..
Determining the Location of the
Libraries .. .. .. .. .. .. ..
.. .. ..
Source Language Considerations ..
Extended Source Program Library
Facility .. .. .. • • • •
.. .. ..
Reformatted Source Deck .. .. .. .. ..
Q

•

• 40
• 40
40
• 40
• 40

· 41
I, ...

... .L

42
'. 42
42
• 43
43
45
• 45
• 45
45
• 45
.. 46
46

46
• 47
• 48
48
• 50

• 52
53
53
53

54
54
55
• 55
• 56
.. 57
• 57

INTERPRETING OUTPUT
Compiler Output
Object Module
Linkage Editor Output
comments on the Phase Map ..... ~
Linkage Editor Messages
• • .. .. .. ..
DOS ANS COBOL Unresolved External
.. .. .. .. .. •
References • .. .. .. ..
. .. .. .. •
COBOL Execution Output
..
Operator Messages .. .. .. ..
STOP Statement • .. ..
.. ..
ACCEPT Statement •
= .. _ . . .
System output
CALLING AND CALLED PROGRAMS
Linkage
.. .. .. ..
Linkage In A Calling Program

59
59
69
69
71
71

72
72
73
73
73

• 75
• 75
.. 75

Linkage In A Called Program
•
Entry points • • • • • • • .. • • • • •
Correspondence of Arguments and
Parameters • • • • • • • .. • ..
Link Editing Without Overlay • •
• •
Assembler Language Subprograms •
•
Register Use .. • • • • • • • •
• •
Save Area • • • • .. • • • • •
• •
Argument List • • • • • • • •
•
File-Name and Procedure-Name
Arguments . . . . . . • • • •
..
In-Line Parameter List •
Lowest Level Program
Overlays • • • • • .. • .. • ..
•
Special Considerations When Using
Overlay Structures • • • • • • .. .. • • ..
Assembler Language Subroutine for
Accomplishing Overlay .. • e _ • • .. ..
Link Editing with Overlay . . . . . .
Job Control for Accomplishing Overlay

76
76
77
77
78
78
79
79
79
81
81
81
81
82
83
84

.. .. 89
USING THE SEGMENTATION FEATURE •
Operation ... • • • .. • • • _
• 90
Output From a Segmented program • _ .. • 91
Compiler Output • • • •
91
Linkage Editor Output • • • •
92
Cataloging a segmented ~rogram ..
92
Determining the Priority of the
Last Segment Loaded into the
Transient Area • • • • .. • .. • ..
92
Sort in a Segmented Program
93
Using the PERFORM Statement in a
segmented Program
• 93
PART II

• 95

PROCESSING COBOL FILES ON MASS STORAGE
DEVICES . . . . .
97
File Organization
97
Sequential Organization
97
Direct Organization
• 97
Indexed Organization • • ..
97
Data Management Concepts • ..
98
Sequential Organization (DTFSD)
. . . . . 99
Processing a Sequentially Organized
File • • .. • • • • • • .. • .. • • • .. .. 99
Direct Organization CDTFDA)
• • .. .. 99
Accessing a Directly Organized File .100
ACTUAL KEY Clause • • .. ..
.101
Randomizing Techniques. • •
.102
Actual Track Addressing
Considerations for Specific Devices .116
Randomizing for the 2311 Disk Drive 116
Randomizing for the 2321 Data Cell .117
Indexed Organization (DTFIS)
• • 118
Prime Area. • •
.118
Indexes • .. .. • •
.. .119
Track Index
• • .. •
.119
Cylinder Index. • • • .. •
• .119
Master Index.
• ~119
Overflow Area
• .. • •
• .119
Cylinder Overflow Area =
... 119
Independent Overflow Area . . . . . . 119
Adding Records to an Indexed File 4120
Accessing an Indexed File CDTFIS) • • 121
Key Clauses . . . . . .
• .121
Improving Efficiency . . . . . . .
122
Q

••

PROCESSING 3540 DISKETTE UNIT FILES
File Processing .. • .. ..
DTFDU • • • • • • .. .. ..
Job Control Requirements •
DLBL Statement .. ..
EXTENT Statement •
3540 File . • • •

_ ,.123
.123
,.124
... 124
.125
.125
.. '" 125

VIRTUAL STORAGE ACCESS METHOD (VSAM) ... 127
File Organization
. . . . . . . 127
Key-Sequenced Files
. . . . . . . 127
Entry-Sequenced Files
.127
Data Organization
. . . . . . . . . . . 128
Data Access . . . . . . . . . . . . . . . . . 128
VSAM Catalog • • • • •
• ,.128
File and Volume Portability
.130
service Programs.
.130
Device Support. ..
• . . . . . . 130
Security. • • • ..
• . . . . . . 130
Error processing..
• . . . . . . . 130
VSAM Messages
. . . . . . . 130
Access Method Services. • • .. • •
.130
Functional C o m m a n d s . 1 3 0
The DEFINE Command. •
.130
Specification of the DEFINE Command 131
Defining a VSAM Master Catalog:
DEFINE MASTERCATALOG . . . . . . . . . . . 131
Defining a VSAM Data Space: DEFINE
SPACE
• • • .. .. • • • •
.132
Defining a VSAM File: DEFINE
CLUSTER • • • .. .. • • .. • • .. • • • 133
File Processing Techniques •
.134
1 ... ··
Current Record Pointer • • •
Error Handling • • • • • • • • .
.. .13b
Record Formats for ?SAM Files
.. 136
Ini tial Loc' -li. "'lg of Recc .. u£ l:1to a
File. • • • • .. .. • .. • ..
.. .137
File Status Initialization
• • 137
Opening a VSAM File
... 137
Writing Records into a VSAM File • • • 139
Entry-Sequenced File
Considerations for the WRITE
Statement . . . . . . . . . . ..
.139
Key-Sequenced File Considerations
for the WRITE Statement • • • • • • 139
Rewriting Records on a VSAM File
.139
Entry-Sequenced File
Considerations for the REWRITE
.139
Statement '. .. • • • • '. .. ....
Key-Sequenced File Considerations
for the REWRITE Statement
• • 140
Reading Records on a VSAM File
.. 140
Entry-Sequenced File
Considerations for the READ
Statement • • • • .. • .. • •
,.140
Key-Sequenced File Considerations
for the READ Statement
• • 140
READ NEXT Statement
• ,.140
READ Statement. •
• .141
Using the START Verb • • .. • .. ,. ..
.141
DELETE Statement. • •
. . . . . . 141
COBOL Language Usage With vsm~
.141
Creating a VSAM File
.141
Retrieving a VSAM File • •
• • 143
Job Control Language for a VSAM
File • • .. • • • .. • .. • • • • • • .144

Converting Non-VSAM Files to VSAM
Files
.. .. • • .. • _ • .. .• • .. ..144
Using ISAM Programs to Process
VSAM Files. • • • • • .. • • •
.144
DETAILED FILE PROCESSING CAPABILITIES .145
COBOL VSAM Control blocks . . . . . . . . . . . 145
Control Blocks For VSAM . . . . . . . . . . 146
VSAM File Information Block (FIB)
• • 146
VSAM File Control Block
. . . . . . 148
DTF Tables . . . . . . . . . . . . . . . . . . . . . 150
Pre-DTF Switch • • • • • • • • • • • 155
Error Recovery for Non-VSAM Files . . . . 155
Volume and File Label Handling
... 162
Tape Labels . . . . . . . . . . . . . . 162
Volume Labels
.162
Standard File Labels.
.. .162
User Standard Labels
• • 162
Nonstandard Labels . . . . . . . . . . . . . 162
Label Processing Considerations
.. 165
Sample Programs
. . . . . . 166
Mass Storage File Labels.
• • • 174
Volume Labels
. . . . . . . . . . 174
Standard File Labels . . . . . . . . . 174
User Labels • •
.174
Label processing Considerations
.174
Files on Mass Storage Device
Opened as Input . . . . . . . . . . . . 174
Files on Mass Storage Devices
Opened as Output
.175
Unlabeled Files .. • • • .. ..
• .175
0

•

PROCESSING ASCII TAPE FILES
COBOL Language Considerations
•
File Handling • • • • .. • •
Operational Considerations •
•
Obtaining an ASCII Collating Sequence
on a Sort
• • • • ..
•

• 177
.177
.177

.178
.178

RECORD FORMATS FOR NON-VSAM FILES _ • • 179
Fixed-length (Format F) Records . . . . . . 179
Undefined (Format U) Records.
.. .180
Variable-Length Records
. . . . . . . 180
APPLY WRITE-ONLY Clause
.183
Spanned (Format S) Records..
• . . . . 183
S-Mode Capabilities • • .. ..
• .184
Sequentially Organized S-Mode Files
on Tape or Mass Storage Devices
.185
Source Language Considerations .. _ .. 185
processing Sequentially Organized
S-Mode Files . . . . . . . . . . . . . . . . 185
Directly Organized S~Mode Files
.187
Source Language Considerations
.187
Processing Directly Organized
S-Mode Files. •
.188
PART III •

• .189

PROGRAMMING TECHNIQUES •
• .191
Coding Considerations for DuS/v3
... 191
General Considerations
.191
COpy .. • • • • .. • • • • • • • • • • • • 191
SyntaxChecking • • • .. • .. • ..
.191
Formatting the Source Program
Listing
.... 191
• . . . . 192
Environment Division • • • ..
RESERVE Clause • • .. • • • • • .. _ .192
APPLY WRITE-ONLY Clause . . . . . . . . 192

Data Division • • • • • •
.193
OVerall Considerations ..
.193
FD Entries • •
• . . . . . 193
Prefixes .. • •
• • • •
.193
Level Numbers
• • • •
.. .. 193
File Section • ..
• • • • .194
RECORD CONTAINS Clause • • '. .. .. • .194
BLOCK CONTAINS Clause
• .194
Working-Storage Section
.194
Separate Modules • .. •
• .. .. • .194
Locating the Working-Storage
Section in Dumps •
.194
REDEFINES Clause ..
.194
PICTURE Clause • "
.196
USAGE Clause • • ..
• .. 197
SYNCHRONIZED Clause
• .200
Special Considerations for DISPLAY
and COMPUTATIONAL Fields.
.200
Data Formats in the Computer ...
.200
Procedure Division . . . . . . . . . . . . . 202
Modularizing the Procedure Division .202
Main-Line Routine • • • '.
• .203
Processing Subroutines. ..
.203
Input/Output Subroutines.
• .203
Overall Considerations.
• .203
OPTIMIZE Option
.203
Intermediate Results.
• • • 203
Intermediate Results and Binary
Data Items • • • .. •
.203
Intermediate Results and COBOL
Library Subroutines
• .203
Intermediate Results Greater Than
30 Digits . . . . . •
.204
Intermediate Results and
Floating-point Data Items . . . . . . .204
Interme9iate Results and the ON
SIZE ERROR Option • • • • •
.204
Exponentiation.. • • • • • •
.... 204
Optimization Based on Execution
Frequency • • • • • • ~ . . . . . . . . . 204
Procedure Division Statements
.204
COMPUTE Statement
• • • • • • 204
IF Statement.
.205
MOVE Statement. ..
• .205
NOTE Statement. •
• .205
PERFORM Statement
,.205
READ INTO and WRITE FROM Options
... 205
TRANSFORM Statement
. . . . . . . . 206
•

'. . .

USING THE SORT/MERGE FEATURE . . . . . . ,.207
Sort/Merge Job Control Requirements • • 207
Sort Input and Output Control
Statements . . . . . . . . . . . . . . . 207
Sort Work File Control Statements ... 208
Amount of Intermediate Storage
Required. • .. • • • ..
.208
Improving Performance
.208
SORT-OPTION Clause.
.208
PRINT Option •
• • .. • ,.208
LABEL Option. •
• . . . . . . 208
STORAGE Option
.208
ALTWK Option •
~ .208
ERASE Option.
• .. 208
ROUTE Option.. • ..
.208
SORTWK Option
. . . . . . . 208
SORT-OPTION Clause Examples . . . . . 208
Output File Statements
. . . . . . . 208
Sort Diagnostic Messages. • • •
• .209

Linkage with the Sort/Merge Feature • • 209
completion Codes.
209
Cataloging a Sort Program
• ~209
Checkpoint/Restart During a Sort • ~ • • 210
Using Sort in a Multiphase Environment .210
0

• • • • • • • •

USING THE REPORT WRITER FEATURE
• .211
REPORT Clause in a File
Description (FD) Entry
• • • • • 211
Summing Techniques •
• ....... 211
Use of SUM .. • • • •
• . . . . . . 211
SUM Routines • • • •
.212
output Line Overlay
.213
Page Breaks
• • .. ..
.213
Control Footings and Page Format • • 213
WITH CODE Clause • •
• .. 214
. . . . . . 214
NEXT GROUP Clause
.. 215
Floating First Detail
Report Writer Routines
• .. 215
TABLE HANDLING CONSIDERATIONS
• .217
..... 217
Subscripts • .. • ..
.. 217
Index-names
. . . . . . . . 217
Index Data Items •
OCCURS Clause
• .. 217
DEPENDING ON Option .. • • •
.. 217
OCCURS Clause with the DEPENDING ON
Option • • • • .. • _ ..
.. 218
SET Statement
• .. 221
SEARCH Statement •
.. 224
SEARCH ALL Statement •
• .. 224
... 225
Building Tables
PART IV

• .227

LISTER FEATURE..
• .. 228
Overall Operation of the Lister
.... 228
The Listing
• • • •
.228
The Output Deck
• • • •
• 228
Reformatting of Identification and
Environment Divisions . . . . . . . . . 228
Data Division Reformatting • • • • • 228
Procedure Division Reformatting .... 228
Summary Listing
• • 228
The Source Listing. • •
.228
General Appearance . . . . . . . . . . . . 228
Format Conventions. ..
• . . . . . . 228
Type Indicators
• • • •
• .228
The Summary Listing . . . . . . . . . . . . . 228
General Appearance . . . . . . . . . . . . 228
The Output Deck
.. 228
Using the Lister. • • ..
.228
Options • • • • ..
.. .228
Programming Considerations
.228
G

Debug Language . . . . . . . . ~ . . . . . . . . . . 247
Flow of control
• • ...
.. .. 247
Displaying Data Values During
Execution .. • • .. .. . • • • • •
.248
Testing a Program Selectively
.250
Testing Changes and Additions to
Programs
• • .. ..
• • • _ .. .250
Dumps ... • .• .. • • • • .. • •
• 251
How to Use a Dump .. .. .. • •
... 251
Errors That Can Cause a Dump ..
• .. 252
Locating a DTF ..
.252
Locating Data
... 253
EXECUTION STATISTICS.
• ....... 260
Obtaining Execution Statistics..
.260
Debugging and Testing ............. 260
Optimization Methods . . . . . . . . . . . . . . 260
Resequencing the Program . . . . . . . 260
Insight into SYMDMP output • • • _ .260
Common Expression Elimination
.. 260
Backward Movement
.260
Unrolling
.260
Jamming • • • .. • • .. .. •
• .260
Unswitching
• _ . . . . 260
Incorporating Procedures Inline ... 260
Tabling • • • .. • • ..
.260
Efficiency Guidelines • • .. •
.260
Diagnostic Messages
• • • •
.260
Working with Diagnostic Messages
.260
Generation of Diagnostic Messages • • 260
Linkage Editor Output
... 261
Execution Time Messages
. . . . . . . 261
Recording Program Status
• • 262
RERUN Clause. • • ..
.262
Taking a Checkpoint
... 262
Restarting a Program.
.263
APPENDIX A: SAMPLE PROGRAM OUTPUT

.265

APPENDIX B: STANDARD TAPE FILE LABELS

.279

SYMBOLIC DEBUGGING FEATURES
....... 229
Use of the Symbolic Debugging Features .229
Statement Number Option
.229
Flow Trace Option • .. • • •
.. .. 229
Symbolic Debug Option .......
.. .. 229
Object-Time Control Cards . . . . . . . 230
Overall Considerations ... _ •
.232
Sample Program -- Testrun
.... 232
Debugging TESTRUN
.233
PROGRAM CHECKOUT. • •
.247
Syntax-Checking Compilation
.247
Identification of Program Versions . . . . 247

APPENDIX C: STANDARD MASS STORAGE
DEVICE LABELS
• • • ••

• ... 281

APPENDIX D: TRACK FORMATS FOR
DIRECT-ACCESS STORAGE DEVICES

.287

APPENDIX E: COBOL LIBRARY SUBROUTINES .289
Input/Output Subroutines . . . . e ~ . . . 289
Printer Spacing . . . . . . . . . . . . 289
Tape and Sequential Disk Labels
.289
CLOSE WITH LOCK Subroutine.
• .. 289
WRITE Statement Subroutines
.289
READ Statement Subroutines.
..289
REWRITE Statement Subroutines
.290
DISPLAY (EXHIBIT and TRACE)
Subroutines • • .. • .. • • • .•
.290
ACCEPT and ST0P (literal) Statement
Subroutines
• • • • • • • 290
CLOSE Subroutine.. • • • • .. •
.290
Multiple File Tape Subroutine
.290
Tape Pointer Subroutine
. . . . 290
Input/Output Error Subroutines
.290
Disk Extent Subroutines
.290
3886 OCR Subroutine
.290
VSAM Subroutines • • • • • .. • • • .290
Auxiliary Subroutines
..... _ .291
ASCII Support Subroutines . . . . . . . . 291
n

separately Signed,Numeric
Subroutine . . . . . . . ~ •
n291
Conversion Subroutines. • • ..
.291
Arithmetic Verb Subroutines • • • 0 .293
Sort/Merge Feature Interface Routine .293
Checkpoint (RERUN) Subroutine
.293
Segmentation Feature Subroutine
.293
Other Verb Routines
_
293
Compare Subroutines
• • • 0293
MOVE Subroutines. • •
.294
TRANSFORM Subroutine..
.294
Class Test Subroutine
• • 294
SEARCH Subroutine
• • 294
Main Program or Subprogram
Subroutine • • •
• .294
Object-Time Debugging Subroutines • .. 294
Debug Control Subroutine • _
. . . 294
Statement Number Subroutine . . . . . . 294
Flow Trace Subroutine
.295
Symbolic Debug Subroutines _ •
.295
Object-Time Execution Statistics
Subroutines . . . . . . . . . . . _ • • 295
COUNT Initialization Subroutine • • 295
COUNT Frequency Subroutine. •
.295
COUNT Termination Subroutine..
.295
COUNT Print Subroutine
.295
Optimizer Subroutines •
.295
GO TO ••• DEPENDING ON Subroutine .295
Optimizer DISPLAY Subroutine
• • 296
Transient Subroutines • • •
296
Symbolic Debug Subroutines • • • • • 296
SYMDMP Error Message Subroutine • • 296
Error Message Subroutine. _ •
.296
Error Message Print Subroutine • • • 296
Reposition Tape Subroutine
.296
6

•

. . . . . .

•

...

APPENDIX F: SYSTEM AND SIZE
CONSIDERATIONS • • • • • • .. •
.297
Minimum Machine Requirements for the
Compiler • .. • • • • • • .. •
.. 297
Source Program Size Considerations • • 297
Compiler Capacity • • • _ • • _ .. a297
Effective Storage Considerations • • 298
Execution Time Considerations
_ 0299
Multiprogramming Considerations • • • 300
Sort Feature Considerations
.... 300
APPENDIX G: COMMUNICATION REGION
_ .301
Communication Region.
• • • _ ... 301
APPENDIX H: SAMPLE JOB DECKS •
Direct Files .. • • •
creating a Direct File ..

• .303
.304
.304

Retrieving and Updating a Direct
File.. • .. • • • • • .. • •
.. .304
Indexed Files • • .. • .. • •
• .305
Creating an Indexed File.
• .305
Retrieving and Updating an Indexed
File.. • • • • • • • • • •
• .306
Files Used in a Sort Operation ..
306
Sorting an Unlabeled Tape File • • • 306
d

...

APPEaDIX I: DIAGNOSTIC MESSAGES
• • 307
Compile-Time Messages
• • 307
Operator Messages • • a ..... _ • • • 307
Object-Time Messages • • • ..'. • • • • 309
COBOL Object Progra~ Unnumbered
Messages
.318
APPENDIX J: ~OBOL 3886 OPTICAL
CHARACTER READER SUPPORT _ • •
.319
3886 OCR Processing .... • •
.319
Implementing an OCR Operation
• • 319
Document Design .. • • • • • • .. . ' . 319
Document Description
. . . . . . 320
COBOL support
• .. '. 320
File Description
.320
Record Description.
• .320
Procedural Code
. . . . . . . . 321
JCL Considerations
. . . . . . . . 321
Subprogram Interface _
• __ ... 321
Statements for Invoking 3886 I/O
Functions . . . . . . . . . .
.324
OPEN Function (Equivalent to OPEN
Macro) . . . . . . . . . . . ~ . . . . . . . 324
CLOSE Function (Equivalent to DOS
CLOSE Macro) . . . . . . _ .. • •
.324
READ Function (Equivalent to DOS
READ and WAITF Macros) • _ • • __ .324
READO Function (Equivalent to DOS
READ Macro) . . . . . . . . . .
.324
WAIT Function (Equivalent to DOS
WAITF Macro). • • .. • • • • • .. • .324
MARKL Function (Equivalent to DOS
CNTRL Macro with LMK Option) . . . . . . 324
MARKD Function (Equivalent to DOS
CNTRL Macro with DMK Option) • • _ .325
EJECT Function (Equivalent to DOS
CNTRL Macro, with ESP Option)
.325
SETDV (Set Device by Load.ing a
Format Record) Function
(Equivalent to DOS SETDEV Macro) ... 325
COBOL 3886 Library Routine . . . . . . . 325
Processing Tapes from the OCR 388£,
Model 2 • • • •
• . . . . . 326
0

INDEX

.333

ILLUSTRATIONS
TABLES
Table 1. Job Control Statements
• 16
Table 2. Symbolic Names, Functions,
and Permissible Device Types • _ • • _ _ 21
Table 3. Significant Characters for
Various Options • • • • • _ _
40
Table 4. Glossary Definition and
Usage • • • • _ • .. • • • • .. • ..
65
Table 5. Symbols Used in the Listing
and Glossary to Define
Compiler-Generated Information
66
Table 6. System Message
Identification Codes • • • • • • • _ _ • 73
Table 7. Conventional Use of Linkage
Registers .. • • • _ .. • _ • • .. .. _ .. • 78
Table 8. Save Area Layout and Word
Contents .. • • • • • • • • _ • • •
• 79
Table 9. Recording Capacities of Mass
Storage Devices
• _ .. • 97
Table 10. Partial List of Prime
Numbers . . . . . . . . _ • • • •
.. .105
Table 11. File Status Values and
Error Handling _ • • •
_ . . . . . . . . 136
Table 12. File Status ~ey ?alues at
OPEN • • • .. • • • • .. • • _ • • .. .. • .138
Table 13. File Status at Action
Request Time _ ... _ • • • • _ . . . . . . . 138
Table 14. COBOL Statements for
Creating a VSAM File • • _ .. • ..
.141
Table 15. COBOL Statements for
Retrieving a VSAM File __ .. _ ..
.143
Table 16. Fields Preceding DTFMT and
DTFSD
. . . . . . . . . . . . _ • _ ... _ .151
Table 17. Fields Preceding DTFDA -ACCESS IS RANDOM -- Actual Track
Addressing . . . . . . . . . . . . . . . __ .151
Table 18. Fields Preceding DTFDA -ACCESS IS RANDOM -- Relative Track
Addressing . . . . . . . . . . . . . . . . 152
Table 19. Fields Preceding DTFDA -ACCESS IS SEQUENTIAL -- Actual Track
Addressing . . . . . . . . . . . . . . . . . . . ~153

Table 20. Fields Preceding DTFDA -ACCESS IS SEQUENTIAL -- Relative Track
Addressing . . . . . . . . . . . . . . . . . . . 154
Table 21. Fields Preceding DTFIS . . . . 154
Table 22. Fields Preceding DTFDU
.155
Table 23_ Meaning of Pre-DTF Switch _ .• 155
Table 24. Errors Causing an Invalid
Key Condition • • • • • • • • • • • • • 156
Table 25. Meaning of Error Bytes for
GIVING Option of Error Declarative
(Part 1 of 2)
••• _ • _ • • • •
.157
Table 26. Location and Meaning of
Error Bits for DTFMT
.159
Table 27. Location and Meaning of
Error Bits for DTFSD • • • • • • •
.159
Table 28. Location and Meaning of
.160
Error Bits for DTFDA _ • • .. • • •
Table 29. Location and Meaning of
Error Bits for DTFIS . . . . . . . . . . . 160
Table 30. Location and Meaning of
Error Bits for DTFDU • .. • • • • ..
.161
Table 31. Data Format Conversion
(Part 1 of 2)
.............
.198
Table 32. Relationship of PICTURE to
Storage Allocation. • • • • • • •
.202
Table 33. Rules for the SET Statement .223
Table 34. Individual Type Codes Used
in SYMDMP Output • • • • • . • • • • • • 234
Table 35. Functions of COBOL Library
Conversion Subroutines . . . . . . . . _ .292
Table 36. Functions of COBOL Library
Arithmetic Subroutines. .. • • •
.293
Table 37. OCR Status Key Values and
User Actions • .. • • _ • • • .322
Table 38. Possible Status Key Values,
By Operation • • • • • • _ • • • • • • . 322
Table 39. User Responses to Status Key 323
Table 40. CALL Statements for
Invoking 3886 I/O Functions • • • • • • 326
fl

•

FIGURES

Figure 1. sample structure ot Job Deck
for compiling, Link Editing. and
Executing a Main Program and Two
Subprograms • • • • • • .. .. • • • • .. • 13
Figure 3. Possible Specifications for
X'ss' in the ASSGN Control statement
• 25
Figure 4. Sample Label and File
Extent Information for Mass Storage
Files • • • • • • • • • • • • • • •
30
Figure 5. Job Definition -- Use of
the Librarian • • • • • • _ • • • ..
41
Figure 6. Options Available During
Link-Editing
•••••••••••
44
Figure 7. The Relative Location of
the Four system Libraries • • • • •
56
Figure 8. Sample Coding to Calculate
FICA
• • • • • • • • • • • • ..
58
Figure 9. Altering a program from
the Source Statement Library Using
INSERT and DELETE Cards
• • 58
Figure 10. Effect of INSERT and
DELETE Cards
• • • •
58
Figure 11. Examples of Compiler
Output (Part 1 of 4)
• __ ..
60
Figure 12. A Program that Produces
COBOL Compiler Diagnostics
••••
69
Figure 13. Linkage Editor Output
• 70
Figure 14. Output from Execution Job
Step
.. • • • • • • • • _ • • .. _ • 72
Figure 15. Calling and Called
Programs
. . . . . . . . . . . . . . . . . 75
Figure 16. Example of Data Flow Logic
in a Call Structure • • • • • •
78
Figure 17. Sample Linkage ~outines
Used with a Calling Subprogram • • •
80
Figure 18. sample In-line Parameter
List
••••
81
Figure 19. sample Linkage Routines
Used with a Lowest Level Subprogram
81
Figure 20. Example of an Assembler
Language Subroutine for Accomplishing
Overlay • • • • • • • • • .. • • • •
82
Figure 21. Flow Diagram of Overlay
Logic
• • • • • • • • • •
84
Figure 22. Job Control for
Accomplishing Overlay • •
84
Figure 23. Calling Sequence to Obtain
Overlay Between Three COBOL
subprograms (Part 1 of 3) • • • • • • • 85
Figure 24. segmenting the Program
SAVECORE
.........
89
Figure 25. Storage Layout for SAVECORE 91
Figure 26. Compiler Output for
SAVECORE
• • • • •
• • • • • 92
Figure 27. Link Editing a Segmented
Program • • • .. • • • • • .. • • • •
94
Figure 28. Location of Sort Program
in a Segmentation Structure . . . . .
94
Figure 29. Structures of the Actual
Key . . . . . . . . . . . . . . . . . . . . 102
0

•

Figure 30. Permissible Specifications
for the First Eight Bytes of the
Actual Key
. . . . . . . . . . . . . . . 102
Figure 31. Creating a Direct File
Using Method B (Part 1 of 4)
• • • 107
Figure 32. Creating a Direct File
with Relative Track Addressing Using
Method B (Part 1 of 4)
... 112
Figure 33. Formats of Blocked and
.118
Unblocked Records • • • • '. • • ..
Figure 34. Adding a Record to a Prime
Track
•••••••••••
• .120
Figure 35_ VSAM Data Organization
• .129i
Figure 36_ Defining a VSAM Master
Catalog • • • • • • • • • • • • •
.131
Figure 37. Defining a VSAM Data Space 132
Figure 38. Defining a Key-Sequenced
Suballocated VSAM File
• .133
Figure 39. Standard Tape File Label
and TLBL Card (Showing Maximum
Specifications) . . . . . . . . . .
• .163
Figure 40. Standard Tape File Label
and TLBL Card (Showing Minimum
Requirements)
....._
• .164
Figure 41. Standard, User Standard,
and Volume Labels • • '. • • • • • • • .165
Figure 42.. Nonstandard Labels '. • • • .165
Figure 43. Processing an Unlabeled
Multifile Volume (Part 1 of 2)
. . . . .168
Figure 44. Readrng a Multivolume File
with Standard Labels; Creating a
Multifile VolUme with Standard Labels
(Part 1 of 2) _ . . . . . . . . . . . . . . 170
Figure 45G Creating an Unlabeled
Multivolume File (Part 1 of 2)
.172
Figure 46. Fixed-Length (Format F)
Records _ • • • .. .. .. • • • • •
.179
Figure 47.. Undefined (Format U)
Records • • • • • • • • .. • • •
.180
Figure 48. Unblocked V-Mode Records
.180
Figure 49. Blocked V-Mode Records
... 181
Figure 50.. Fields in Unblocked V-Mode
Records . . . . . . . . . . . . . . . . . . . . . 182
Figure 51. Fields in Blocked V-Mode
Records • • • • • • • • .. •
• 182
Figure 52. First Two Blocks of
VARIABLE-FILE-2 . . . . . . . . '. • ..
.183
Figure 53.. Control Fields of an
S-Mode Record • • • • • • • •
.. .184
Figure 54. One Logical Record
Spanning Physical Blocks
. . . . . . 185
Figure 55. First Four Blocks of
SPAN-FILE • • '. .. • • • ... • •
.186
Figure 56. Advantage of S-Mode
Records Over V-Mode Records
• • • • 186
Figure 57. Direct and Sequential
Spanned Files on a Mass Storage Device 187
Figure 58. Treatment of Varying
Values in a Data Item of PICTURE S9 • • 202
Figure 58 .. 1. OPTION Control Statement
to SORT/MERGE . . . . . . . . . . . . . . . 208

Figure 58.2ft File Name and Default
Symbolic Unit Names
• • • • •
.208
Figure 58.3.
SUMMARY OF SO~T-OPTION
Operands
••
208
Figure 59.
Sample of GROUP INDICATE
Clause and Resultant Execution Output .213
Figure 60.
Format of a Report Record
when the CODE Clause is Specified
.214
Figure 61. Activating the NEXT GROUP
Clause
ft • • • • • • •
215
Figure 62. Calculating Record Lengths
When Using the OCCURS Clause with the
DEPENDING ON Option • • • • • _ • • • • 220
n

••••••••••••

•

• • • •

Figure 63.
Table Structure in Virtual
Storage _ • • • • • • • • • • • • • • • 221
Figure 64. Using the Symbolic
Debugging Features to Debug the
Program TESTRUN (Part 1 of 12)
_ .235
Figure 65.
Sample Output of EXHIBIT
Statement With the CHANGED NAMED
Option
• • • • • • • • • • • • • • • • 249
Figure 66.
Sample Dump Resulting from
Abnormal Termination (Part 1 of 6)
• • 254
Figure 67. Track Format
.288
Figure 68.
Communication Region in
the Supervisor
• • • • • __ • • 302
Figure 69.
Sample OCR ~rogram (part 1
of 5)
••••••
_ • _ •
• .327

FEATURES OF THE PROGRAM PRODUCT DOS/VS COMPILER

The IBM DOS/vS COBOL Compiler includes
the following features:
• Object Code:
(1) Optimized Object Code -- which
results, when specified, in up to
30% space saving in object program
generated code and global tables
as compared with Version 2 of the
IBM DOS Full American National
Standard COBOL Compiler. The
space saved depends on the number
of referenced procedure-names and
branches, and on 01-level data
names.
(2) Double-Buffered ISAM -- allows
faster sequential processing of
indexed files.
(3) The MOVE Statement and Comparisons
-- when a MOVE statement or a
comparison involves a one-byte
literal, generated code for the
move and the comparison saves
object program space and
compilation time.
(4) DISPLAY
routine
subsets
program

Routines -- the DISPLAY
has been split into
for efficient object
code.

• Alphabetized Cross-Reference Listing
(SXREF) -- for easier reference to
user-specified names in a program.
SXREF performs up to 25 times faster
than the source-ordered cross-reference
(XREF) feature of Version 2 of the IBM
DOS Full American National Standard
COBOL Compiler. The larger the source
program, the more that performance is
improved. Total compilation time is up
to 2 times faster.
• Debugging Facilities:
(1) Symbolic Debug Feature -- which
provides a symbolic formatted dump
at abnormal termination, or a
dynamic dump during program
execution.
(2) Flow Trace Option -- a formatted
trace can be requested for a
variable number of procedures
executed before abnormal
termination.
(3) Statement Number Option -identifies the COBOL statement
being executed at abnormal
termination.

(4) Expanded CLIST and SYM -- for
detailed information about the
Data Division and Procedure
Division.
(5) Relocation Factor -- can be
requested to be included in
addresses on the object code
listing, for easier debugging.
(6) Working-storage Location and Size
-- When CLIST and SYM are in
effect, the starting address and
size of Working-Storage are
printed.
(7) Syntax-Check Feature -- optionally
provides a quick scan of the
source program without producing
object code. Syntax checking can
be conditional or unconditional.
(8) WHEN-COMPILED Special Register -makes the date-and-time-compiled
constant carried in the object
module available to the object
program. This special register is
a programmer aid that provides a
means of associating a compilation
listing with both the object
program and the output produced at
execution time.
• Device Support -- the following devices
can be specified in addition to devices
supported by the IBM DOS Full lli~erican
National Standard COBOL coropilers:
5203,3203 -- line printers
3211 -- 150-character printer
3330,3340,3350 -- mass storage
(direct access) facilities
Fixed block direct access storage
devices
3540 -- Diskette input/output unit
3410,3420 -- tape utility devices
2560,3504,3505,3525,3881,3886,5425
advanced unit-record devices
• ASCII Suppor! -- allows creation and
retrieval of tape files written in the
American National Standard Code for
Information Interchange (ASCII).
• VSAM (Virtual Storage Access Method)
Support -- provides fast storage and

Features of the Program Product DOS/VS Compiler

retrieval of records, password
protection, centralized and simplified
data and space management, advanced
error recovery facilities, plus system
catalog. COBOL supports indexed
(key-sequenced) files and sequential
(entry-sequenced) files. Records can
be fixed or variable in length.
• FIPS (Federal Information processing
Standard) Flagger -- issues messages
identifying nonstandard elements in a
COBOL source program. The FIPS Flagger
makes it possible to ensure that COBOL
clauses and statements in a DOS/VS
COBOL source program conform to the
Federal Information Processing
Standard.
• Lister -- provides a specially
formatted source listing with embedded
cross-references for increased
intelligibility and ease of use. A
reformatted source deck is available as
an option.
• Generic Key Facility for ISAM Files
sequential record retrieval can be

requested using a search argument
comprised of a user-specified number of
high-order characters (generic portion)
of the NOMINAL KEY. The user need not
specify a full or exact search key.
This feature is supported via the START
verb.
• MERGE Support -- combines from two to
eight identically sequenced files on a
set of specified keys and makes records
available, in merged order, to an
output procedure or a sequential output
file.
• Verb profiles -- facilitates
identifying and locating verbs in the
COBOL source program. Options provide
a verb summary or a verb
cross-reference listing which includes
the verb summary.
• Execution-time statistics -- maintains
a count of the number of times each
verb in the COBOL source progr~m is
executed during an individual program
execution.

PART I
INTRODUCTION----------------------------------------------~)

JOB

DEFINITION--------------------------------------------~)

PROCESSING--------------------------------------------~. ~

PREPARING COBOL PROGRAMS FOR

LIBRARIAN

PROCESSING--------------------)~

FUNCTIONS----------------------------------------~;

INTERPRETING

OUTPUT----------------------------------------~. ~

CALLING AND CALLED

PROGRAMS--------------------------------~. ~

USING THE SEGMENTATION FEATURE------------------------------.:

COBOL has undergone considerable
refinement and standardization since 1959.
A standard COBOL has been approved by the
American National Standards Institute, an
industry-wide association of computer
manufacturers and users. This standard is
called American National Standard COBOL.
IBM Full American National Standard COBOL
is compatible with American National
Standard COBOL and includes a number lof
extensions to it as well.
An IBM COBOL program may be processed by
the IBM DOS/VS System. Under control of
the operating system, a set of COBOL source
statements is translated to form a module.
In order to be executed, the module in turn
must be processed to form a phase. The
reasons for this will become clear later.
For now it is sufficient to note that the
flow of a COBOL program through the
operating system is from source statements
to module to phase.
The DOS/VS System consists essentially
of a control program and a number of
processing programs, and data management.

statements. Job control statements
describe the jobs to be performed and
specify the programmer's reguirements for
each job. Job control statements are
written by the programmer using the job
control language. The use of job control
statements and the rules for ~pecifying
them are discussed later.
INITIAL PROGRAM LOADER
The Initial Program Loader (IPL) routine
loads the Supervisor into storage when
system operation is initiated. Detailed
information about the Initial Program
Loader need not concern the COBOL
programmer. Anyone interested in this
material, however, can find it in the
publication DOS/VS System Management Guide.

PROCESSING PROGRAMS
The processing programs include the
COBOL compiler, service programs, and
application programs.

CONTROL PROGRAM
The components of the control program
are: the Supervisor, Job Control
Processor, and the Initial Program Loader.

SUPERVISOR
The main function of the Supervisor is
to provide an orderly and efficient flow of
jobs through the operating system.
(A job
is some specified unit of work, such as the
processing of a COBOL program.)
The
Supervisor loads into the computer the
phases that are to be executed. During
execution of the program, control usually
alternates between the Supervisor and the
processing program. The Supervisor, for
example, handles all requests for
input/output operations.

JOB CONTROL PROCESSOR
The primary function of the Job Control
Processor is the processing of job control

SYSTEM SERVICE PROGRAMS
The system service programs provide the
functions of generating the system,
creating and maintaining the library
sections, and editing programs into disk
residence before execution. The system
service programs are:
1.

Linkage Editor. The Linkage Editor
processes modules and incorporates
them into phases. A single module can
be edited to form a single phase, or
several modules can be edited or
linke~ together to form one executable
phase. Moreover, a module to be
processed by the Linkage Editor may be
one that was just created (during the
same job) or one that was created in a
previous job and saved.
The programmer instructs the Linkage
Editor to perform these functions
through job control statements. In
addition, there are several linkage
editor control statements.
Information on their use is given
later.
Introduction

Librarian. The Librarian consists of
a group of programs used for
generating the system, maintaining and
reorganizing the disk library areas,
and providing printed and punched
output from the libraries. The system
libraries are: the core image
library, the relocatable library, the
source statement library, and the
procedure library. In addition, the
Librarian supports private core image,
relocatable, and source statement
libraries. Detailed information on
the Librarian is given later.

program concurrently by interleaving their
execution. This support is referred to as
fixed partitioned multiprogramming, since
the virtual address space is divided into a
fixed number of partitions. Each program
occupies a contiguous area of storage. The
amount of virtual storage allocated to
programs to be executed may be determined
when the system is generated, or it may be
determined by the operator when the program
is loaded into storage for execution.

APPLICATION PROGRAMS

BACKGROUND VS. FOREGFOUND PROGRAMS

Application programs are usually
programs written in a higher-level
programming language (e.g., COBOL). All
application programs within the Disk
Operating System/Virtual storage are
executed under the supervision of the
control program.

There are two types of problem programs
in multiprogramming: background and
foreground. Background and foreground
programs are initiated by the Job Control
Processor from batched-job input streams.

IBM-SUPPLIED PROCESSING PROGRAMS
The following are examples of
IBM-supplied processing programs:
1.

Language translators, e.g., DOS/VS
COBOL, which translate source programs
written in various languages into
machine (or object) language.

Sort/Merge

utilities

Background and foreground programs
initiate and terminate independently of one
another. Neither is aware of the other's
status or existence.
The system is capable of concurrently
operating one background program and four
foreground programs. Priority for CPU
processing is controlled by the Supervisor
with foreground programs normally having
priority over background programs. Control
is taken away from a high priority program
when that program encounters a condition
that prevents continuation of processing,
until a specified event has occurred.
Control is taken away from a lower priority
program when an event for which a higher
priority program was waiting has been
completed. Interruptions are received and
processed by the Supervisor.

DATA MANAGEMENT
A third important class of components is
data management routines. These are
available for inclusion in problem programs
to relieve the programmer of the detailed
programming associated with the transfer of
data between programs and auxiliary
storage.

MULTIPROGRAMMING
Multiprogramming refers to the ability
of the system to control more than one

In a multiprogramming environment, the
DOS/VS COBOL compiler can execute either in
the background or the foreground. In
systems that support the batched-job
foreground and private core image library
options, the Linkage Editor can execute in
any foreground partition as well as in the
background partition. To execute the
DOS/VS COBOL compiler for the linkage
editor in any foreground partition, a
private core-image library is reguired.
Additional information on executing the
compiler and Linkage Editor in the
foreground is contained in "Appendix F:
System and Size Considerations." COBOL
program phases can be executed as either
background or foreground programs.

JOB DEFINITION

A job is a specified unit of work to be
performed under control of the operating
system. A typical job might be the
processing of a COBOL program -- compiling
source statements, editing the module
produced to form a phase, and then
executing the phase. Job definition
the
process of specifying the work to be done
during a single job -- allows the
programmer considerable flexibility. A job
can include as many or as few job-2teps as
the programmer desires.

steps:
(1) compile (main program), (2)
compile (first subprogram), (3) compile
(second subprogram), (4) link edit (three
modules combined into one phase), and (5)
execute (phase). Figure 1 shows a sample
structure of the job deck for these five
job steps. Compilation and execution in
three job steps -- compile, link edit, and
execute -- is applicable only when the
COBOL source program is a single main
program.

III JOB PROG1

JOB STEPS
A job step is exactly what the name
implies -- one step in the processing of a
job. Thus, in the job mentioned above, one
job step is the compilation of source
statements; another is the link editing of
a module; another is the execution of a
phase. In contrast to a job definition,
the definition of a job step is fixed.
Each job step involves the execution of a
program, whether it be a program that is
part of the Disk Operating System/Virtual
Storage or a program that is written by the
programmer. A compilation requires the
execution of the DOS/VS COBOL compiler.
Similarly, an editing implies the execution
of the Linkage Editor Finally, the
execution of a phase is the execution of
the problem program itself.

Compilation Job Steps

I•
I•
I.
1// EXEC FCOBOL
{source deck - main program)
I

1/*
I•
I.
I•

III EXEC FCOBOL
I

{source deck - first subprogram}

1/*
I.
I•
I•

III EXEC FCOBOL
I

{source deck - second subprogram)

1/*
I•
I
I •

1•

1// EXEC LNKEDT
I.
1•
1•

III EXEC

Figure
The compilation of a COBOL program may
necessitate more than one job step (more
than one execution of the DOS/VS COBOL
compiler). In some cases, a COBOL program
consists of a main program and one or more
subprograms. To compile such a program, a
separate job step must be specified for the
main program and for each of the
subprograms. Thus, the DOS/VS COBOL
compiler is executed once for the main
program and once for each subprogram. Each
execution of the compiler produces a
module. The separate modules can then be
combined into one phase by a single job
step -- the execution of the Linkage
Editor.
For a COBOL program that consists of a
main program and two subprograms,
compilation and execution require five

Multiphase

Sample Structure of Job Deck
for Compiling, Link Editing,
and Executing a Main Program
and Two Subprograms

Pro~ram

Execution

The execution of a COBOL program has
thus far been referred to as the execution
of a phase. It is possible, however, to
organize a COBOL program so that it is
executed as two or more phases. Such a
program is known as a multiphase program.
By definition, a phase is that portion
of a program that is loaded into virtual
storage by a single operation of the
Supervisor. A COBOL program can be
Job Definition

executed as a single phase only if there is
an area of virtual storage available to
accommodate all of it.
A program that is
too large to be executed as a single phase
must be structured as a mUltiphase program.
The technique that enables the programmer
to use subprograms that do not fit into
virtual storage (along with the main
program) is called ~lay.
The number of phases in a COBOL program
has no effect on the number of job steps
required to process that program. As will
be seen, the Linkage Editor can produce one
or more phases in a single job step.
Similarly, both single-phase and multiphase
programs require only one execution job
step. Phase execution is the execution of
all phases that constitute one COBOL
program.
Detailed information on overlay
structures, as well as information on using
the facilities of the operating system to
create multiple phases and to execute them,
can be found in the chapter "Calling and
Called Programs."

TYPES OF JOBS
A typical job falls into one of several
categories. A brief description of these
categories follows; a complete discussion
is found in the chapter "Preparing COBOL
Programs for Processing."

Compile-Only: Thi~ type of job involves
only the execution of the COBOL compiler.
It is useful when checking for errors in
COBOL source statements. A compile-only
job is also used to produce a module that
is to be further processed in a subsequent
job.
A compile-only job can consist of one
job step or several successive job steps.

Edit-Only: This type of job involves only
the execution of the Linkage Editor. It is
used primarily to combine modules produced
in previous compile-only jobs, and to check
that all cross references between modules
have been resolved. The programmer can
specify that all modules be combined to
form one~phase; or he can specify that some
modules ~orm one phase and that others form
additional phases. The phase output
produced as the result of an edit-only job
can be retained for execution in a
subsequent job.
14

Compil~and Edit:
This type of job
combines the functions of the compile-only
and the edit-only jobs. It requires the
execution of both the COBOL compiler and
the Linkage Editor. The job can include
one or more compilations, resulting in one
or more modules. The programmer can
specify that the Linkage Editor process any
or all of the modules just produced; in
addition, he can specify that one or more
previously produced modules be included in
the linkage editor processing.

Execute-Only: This type of job involves
the execution of a phase (or multiple
phases) produced in a previous job. Once a
COBOL program has been compiled and edited
successfully, it can be retained as one or
more phases and executed whenever needed.
This eliminates the need for recompiling
and re-editing every time a COBOL program
is to be executed.

Edit and Execute: This type of job
combines the functions of the edit-only and
the execute-only jobs. It requires the
execution of both the Linkage Editor and
the resulting phase(s).

Compile, Edit, and Execute: This type of
job combines the functions of the compile
and edit and the execute-only jobs. It
calls for the execution of the COBOL
compiler, the Linkage Editor, and the
problem program; that is, the COBOL program
is to be completely processed.
When considering the definition of his
job, the programmer should be aware of the
following: if a job step is cancelled
during execution, the entire job is
terminated; any remaining job steps are
skipped. Thus, in a compile-edit-and
execute job, a failure in compilation
precludes the editing of the module{s) and
phase execution. Similarly, a failure in
editing precludes phase execution.
For this reason, a job usually should
(but need not) consist of related job steps
only. For example, if two independent
single-phase executions are included in one
job, the failure of the first phase
execution precludes the execution of the
second phase. Defining each phase
execution as a separate job would prevent
this from happening. If successful
execution of both phases can be guaranteed
before the job is run, however, the
programmer may prefer to include both
executions in a single job.

JOB DEFINITION STATEMENTS
Once the programmer has decided the work
to be done within his job and how many job
steps are required to perform the job, he
can then define his job by writing job
control statements. Since these statements
are usually punched in cards, the set of
job control statements is referred to as a
job deck.
In addition to job control
statements, the job deck can include input
data for a program that is executed during
a job step.
For example, input data for
the COBOL compiler
the COBOL program to
be compiled -- can be placed in the job
deck.

The inclusion of input data in the job
deck depends upon the manner in which the
installation has assigned input/output
devices. Job control statements are read
from the unit named SYSRDR (system reader),
which can be either a card reader, a
magnetic tape unit, or a disk extent.
Input to the processing programs is read
from the unit named SYSIPT (system input),
which also can be either a card reader, a
magnetic tape unit, or a disk extent. The
installation has the option of assigning
either two separate devices for these units
(one device for SYSRDR, a second device for
SYSIPT) or one device to serve as both
SYSRDR and SYSIPT. If two devices have
been assigned, the job deck must consist of
only job control statements; input data
must be kept separate.
If only one device
has been assigned, input data must be
included within the job deck.
There are four job control statements
that are used for job definition: the JOB
statement, the EXEC statement, the
end-of-data statement (/*), and the
end-of-job statement (/&).
In this
chapter, the discussion of these job
control statements is limited to the
function and use of each statement. The
rules for writing each statement are given
in the chapter "Preparing COBOL Programs
for Processing."
The JOB statement indicates the
beginning of control information for a job.
The specified job name is stored in the
communications region of the corresponding
partition and is used by job accountin~ and
to identify listings produced during
execution of the job.
The JOB statement may be omitted, in
which case the job name NONAME is stored in
the communications region.
If the JOB
statement is present, it must contain a job
name; otherwise, an error condition occurs.

The JOB statement is always printed in
positions 1 through 72 on SYSLST and
SYSLOG.
The time-of-day and date are also
printed. The JOB statement causes a skip
to a new page before printing is started on
SYSLST.
When a JOB statement is encountered, the
job control program stores the job name
from the JOB statement into the
communications region.
If the /& statement
was omitted, the next JOB statement will
cause control to be transferred to the
end-ai-job routine to simulate the /&
statement.
The EXEC statement requests the
execution of a program. Therefore, one
EXEC statement is required for each job
step within a job. The EXEC statement
indicates the program that is to be
executed (for example, the COBOL compiler,
the Linkage Editor). As soon as the EXEC
statement has been processed, the program
indicated by the statement begins
execution.
The end-of-data statement, also referred
to as the /* (slash asterisk) statement,
defines the end of a program's input data.
~When the data is included within the job
deck (that is, SYSIPT and SYSRDR are the
same device), the /* statement immediately
follows the input data. For example, COBOL
source statements would be placed
immediately after _the EXEC statement for
the COBOL compiler; a /* statement would
follow the last COBOL source statement.
Note:
For an input file on a 5425 MFCU,
the /* card must be followed by a blank
card.
When input data is kept separate (that
is, SYSIPT and SYSRDR are separate
devices), the /* statement immediately
follows each set of input data on SYSIPT.
For example, if a job consists of two
compilation job steps, an editing job step,
and an execution job step, SYSIPT would
contain the source statements for the first
compilati9n followed by a /* statement, the
source statements for the second
compilation followed by a /* statement, any
input data for the Linkage Editor followed
by a /* statement, and perhaps some input
data for the problem program followed by a
/* statement.
The end-of-job statement, also referred
to as the-/& (slash ampersand) statement,
defines the end of the job. A /& statement
must appear as the last statement in the
job deck.
Job Definition

OTHER JOB CONTROL STATEMENTS

Table

The four job definition statements form
the framework of the job deck. There are a
number of other job control statements in
the job control language; however, not all
of them must appear in the job deck. The
job control statements are summarized
briefly in Table 1.

r---------+-------------------------------~

The double slash preceding each
statement name identifies the statement as
a job control statement. Most of the
statements are used for data management
creating, manipulating, and keeping track
of data files.
(Data files are externally
stored collections of data from which data
is read and onto which data is written.)

Job Control Statements

r---------T-------------------------------,
1 Statement I
Function
I
// ASSGN

Input/output assignments.

// CLOSE

Closes a logical unit assigned
to magnetic tape.

// DATE

Provides a date for the
Communication Region.

// DLAB

Disk file label information.

// DLBL

Disk file label information
and VSAM file processing.

// EXEC

Execute program.

// EXTENT

Disk file extent.

// JOB

Beginning of control
information for a job.

// LBLTYP

Reserves storage for label
information.

// LISTIO

Lists input/output
assignments.

// MTC

Controls operations on
magnetic tape.

// OPTION

Specifies one or more job
control options.

// PAUSE

Creates a pause for operator
intervention.

// RESET

Resets input/output
assignments to standard
assignments.

// RSTRT

Restarts a checkpointed
program.

/ / TLBL

Tape label information.

/ / TPLAB

Tape label information.

/ / UPSI

Sets user-program switches.

VOL

/ / XTENT

1// ZONE
1/*
I
I
1/&
I
I*

Disk/tape label information.
Disk file extent.
Sets the zone for the date.
End-of-data-file or
end-of-job-step.
End-of-job=

I Corrments.

l---------~---------------------

__________ I
J

This chapter describes in greater detail
the three types of job steps involved in
processing a COBOL program. Once the
reader becomes familiar with the
information presented here, he should be
able to write control statements by
referring only to the next chapter,
"Preparing COBOL Programs for Processing.~

COMPILATION
Compilation is the execution of the
COBOL compiler. The programmer requests
compilation by placing in the job deck an
EXEC statement that contains the program
name FCOBOL, the name of the DOS/VS COBOL
compiler. This is the EXEC FCOBOL
statement. If the compiler is loaded
from a user program, that program must be
a cataloged phase. The name of the phase
must have as its first four characters
'FCOB' •
Input to the compiler is a set of COBOL
source statements, consisting of either a
main program or a subprogram. Source
statements must be punched in Extended
Binary-Coded-Decimal Interchange Code
(EBCDIC). The COBOL source statements are
read from SYSIPT. The job deck is read
from SYSRDR. If SYSRDR and SYSIPT are
assigned to the same unit, the COBOL source
statements should be placed after the EXEC
FCOBOL statement in the job deck.
Output from the COBOL compiler is
dependent upon the options specified when
the system is generated. This output may
include a listing of source statements
exactly as they appear in the input deck.
The source listing is produced on SYSLST.
In addition, the module produced by the
compiler may be written on SYSLNK, the
linkage editor input unit, and punched on
SYSPCH. separate Data and/or Procedure
Division maps, a symbolic cross-reference
list, and diagnostic messages can also be
produced. The format of compiler output is
discussed and illustrated in the chapter
"Interpreting output."
The programmer can override any of the
compiler options specified when the system
was generated, or include some not
previously specified, by using the OPTION
control statement in the compile job step.
Compiler options are discussed in detail in
the chapter "Preparing COBOL Programs for
Processing."

EDITING
Editing is the execution of the Linkage
Editor. The programmer requests editing by
placing in the job deck an EXEC statement
that contains the program name LNKEDT, the
name of the Linkage Editor. This is the
EXEC LNKEDT statement.
Input to the Linkage Editor consists of
a set of linkage editor control statements
and one or more modules to be edited.
These modules include any of the following:
1.

Modules that were compiled previously
in the job and placed at that time on
the linkage editor input unit, SYSLNK.

Modules that were compiled in a
previous job and saved as module
decks. The module decks must be
placed on SYSIPT. Linkage editor
control statements are read from
SYSRDR.

Modules that were compiled in a
previous job step and cataloged in the
relocatable library. The relocatable
library is a collection of frequently
used routines in the form of modules,
that can be included in a program
phase via the INCLUDE control
statement in the linkage editor job
step.

Output from the Linkage Editor consists
of one or more phases. A phase may be an
entire program or it may be part of an
overlay structure (multiple phases) •
A phase produced by the Linkage Editor
can be executed immediately after it is
produced (that is, in the job step
immediately following the linkage editor
job step), or it can be executed later,
either in a subsequent job step of the same
job or in a subsequent job. In either of
the latter cases, the phase to be executed
must be cataloged in the core image libary~
Such a phase can be retrieved in the
execute job step by specifying the phase
name in the EXEC statement, where phase
name is the name under which it was
cataloged. Otherwise, the phase output is
retained only for the duration of one job
step following the linkage editor job step.
That is, if the module that was just link
edited is to be executed in the next job
step, it need not have been cataloged. An
EXEC statement will cause the phase to be
brought in from the temporary part of the
Job Processing

core image library and will begin
execution. However, the next time such a
module is to be executed, the linkage
editor job step is required since the phase
was not cataloged in the core image
library.
If a private core image library is
assigned, output from the Linkage Editor is
placed in the private core image library
(either permanently or temporarily) rather
than in the resident system core image
library. When execution of a program is
requested and a private core image library
is assigned, this library is searched first
for the requested phase name and then the
system core image library is searched.
Tn addition to the phase, the Linkage
Editor produces a phase map on SYSLST.
Linkage editor diagnostic messages are also
printed on SYSLST. If the NOftAP option of
the linkage editor ACTION control statement
is specified, no phase map is produced and
linkage editor diagnostic messages are
listed on SYSLST, if assigned. Otherwise,
the diagnostic messages are listed on
SYSLOG. The contents of the phase map are
discussed and illustrated in the chapter
"Interpreting Output."
Linkage editor control statements direct
the execution of the Linkage Editor.
Together with any module decks to be
processed, they form the linkage editor
input deck, which is read by the Job
Control Processor from SYSIPT and written
on SYSLNK.
There are four linkage editor control
statements: the ACTION statement, the
PHASE statement, the ENTRY statement, and
the INCLUDE statement. These statements
are discussed in the next chapter.

PHASE EXECUTION
Phase execution is the execution of the
problem program, for example, the program
written by the COBOL programmer. If the
program is an overlay structure (multiple
phase), the execution job step actually
involves the execution of all the phases in
the program.

The phase(s) to be executed must be
contained in the core image library. The
core image library is a collection of
executable phases from which programs are
loaded by the Supervisor.
A phase is
written in the temporary part of the core
image library by the Linkage Editor at the
time the phase is produced. It is
permanently retained (cataloged) in the
core image library, if the programmer has
so requested, via the CATAL option in the
OPTION control statement.
The programmer requests the execution of
a phase by placing in the job deck an EXEC
statement that specifies the name of the
phase. However, if the phase to be
executed was produced in the immediately
preceding job step, it is not necessary to
specify its name in the EXEC statement.

MULTIPHASE PROGRAftS
A COBOL program can be executed as a
single phase as long as there is an area of
virtual storage available to accommodate
it. This area, known as the problem
program area, must be large enough to
contain the main program and all called
subprograms.
When a program is too large
to be executed as a single phase, it must
be structured as a multiphase program.
The overlay structure available to the
COBOL programmer for multiphase programs is
known as root phase overlay, and is used
primarily for programs of three or more
phases. One phase of the program is
designated as the root phase (main program)
and, as such, remains in the problem
program area throughout the execution of
the entire program. The other phases in
the program -- subordinate phas~ -- are
loaded into the problem program area as
they are needed. A subordinate phase may
overlay any previously loaded subordinate
phase, but no subordinate phase may overlay
the root phase. One or more subordinate
phases can reside simultaneously in storage
with the root phase.
Use of the linkage editor control
statements needed to effect overlay are
discussed in the chapter "Calling and
Called Programs."

PREPARING COBOL PROGRAMS FOR PROCESSING

This chapter provides information about
preparing COBOL source programs for
compilation, link editing~ and execution.
ASSIGNMENT OF INPUT/OUTPUT DEVICES
Almost all COBOL programs include
input/output statements calling for data to
be read from or written into data files
stored on external devices. COBOL programs
do not reference input/output devices by
their actual physical address, but rather
by their symbolic names. Thus, a COBOL
program is dependent on the device type but
not on the actual device address. Using
VSAM, it is not even dependent on the
device type. The COBOL programmer need
only select the symbolic name of a device
from a fixed set of symbolic names. At
execution time, as a job control function,
the symbolic name is associated with an
actual physical device. The standard
assignment of physical addresses to
symbolic names may be made at system
generation time. However, job control
statements and operator commands can alter
the standard device assignment before
program execution. This is discussed later
in this chapter.
Using DOS/VS, a logical unit may also be
assigned to another logical unit or a
general device class or specific device
type. For more information on this, see
DOS/VS System Management Guide and DOS/VS
System Control Statements.
The symbolic names are divided into two
classes: system logical units and
programmer logical units.

The system logical units are used by the
control program and by IBM-supplied
processing programs. SYSIPT, SYSLST,
SYSPCH, and SYSLOG can be implicitly
referenced by certain COBOL procedural
statements. Two additional names, SYSIN
and SYSOUT, are defined for background
program assignmentsft The names are valid
only to the Job Control Processor, and
cannot be referenced in the COBOL program.
SYSIN can be used when SYSRDR and SYSIPT
are the same device; SYSOUT must be used
when SYSLST and SYSPCH are assigned to the
same magnetic tape unit. A complete
discussion of the assignment of the logical
unit SYSCLB can be found in the publication
DOS/VS System Control Statements.
Programmer logical units are those in
the range SYSOOO through SYS240 (depending
on the number of partitions in the system)
and are referred to in the COBOL source
language ASSIGN clause.
A COBOL programmer uses the source
language ASSIGN clause to assign a file
used by his problem program to the
appropriate symbolic name. Although
symbolic names may be assigned to physical
devices at system generation time, the
programmer may alter these assignments at
execution time by means of the ASSGN
control statement. However, if the
programmer wishes to use the assignments
made at system generation time for his own
data files in the COBOL program, ASSGN
control statements are unnecessary.
Table 2 is a complete list of symbolic
names and their usage.

Preparing COBOL Programs for Processing

Table

Symbolic Names, Functions, and Permissible Device Types

ISymbolic
I Name
I
ISYSRDR
I
I
I
ISYSIPT
I
I
i

I
Function
I
,
IInput unit for control statements or commands.
I
,
I
,
IInput unit for programs.
I
I
i

Permissible
Device Types
Card reader
Magnetic Tape unit
Disk extent
3540 diskette
Card reader
Magnetic tape unit
Disk extent
3540 diskette

ISYSPCH
i
,
I
I
ISYSLST
I
,
,

IMain unit for punched output.
I
I
I
I
laain unit for printed output.
I
I

,
!
,
,
I
I
I
,
,

ISYSLOG
I
I

Card punch
Magnetic tape unit
Disk extent
3540 diskette
Printer
Magnetic tape unit
Disk extent
3540 diskette

,
,
I
I
,
I
I
I
I
I
I
!

I
I
I
,
I
,
I
I
I
,

IReceives operator messages and logs in job control 1 Printer keyboard
I
I sta tements.
I Printer
I
I
I Display operator console I

~--------~I--------------------------------------------~'--------------------~I

ISYSLNK
I
I
ISYSRES
I
I
I
ISYSCLB
I
ISYSSLB
I
ISYSRLB
I
ISYSIN
I
I
,

IInput to the Linkage Editor.
, Disk extent
I
,
I
I
I
I
I
IContains the operating system, the core image
I Disk extent
I
Ilibrary, relocatable library, source statement
I
I
,library, and procedure library.
I
I
I
I
,
IA private core image library.
I Disk extent
I
I
I
f
IA private source statement library.
I Disk extent
I
f
I
I
IA private relocatable library.
I Disk extent
I
I
------------~I~--------------------~I
IMust be used when SYSRDR and SYSIPT are assigned tol Disk
I
Ithe same disk extent. May be used when they are
,Magnetic tape unit
I
Isame disk extent. May be used when they are
, Card reader
I
lassigned to the same card reader or magnetic tape. , 3540 Diskette
I

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

ISYSOUT
I
I
I
SYSmax

SYSVIS

IThis name must be used when SYSPCH and SYSLST are ,Magnetic tape unit
lassigned to the same magnetic tape unit. It must I
Ibe assigned by the operator ASSGN command.
I
,
I
IThese units are available to the programmer as workl Any unit
Ifiles or for storing data files. They are called
lE£ogrammer logical units as opposed to the aboveImentioned names which are always referred to as
Isystem logical unitso The largest number of
I
'programmer logical units available in the system isl
1240 (SYSOOO through SYS240, depending on number of I
'partitions). The value of SYSmax is determined by I
Ithe distribution of the programmer logical units
I
lamong the partitions.
I
I
I
IHolds virtual storage page data set.
I Disk extent
I

ISYSREC

IHolds the VSAM catalog.
I
ILbgs error records.

I Disk extent
I
I Disk extent

Preparing COBOL Programs for processing

I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
f
I
f
I

JOB CONTFOL
The Job Control Processor for the Disk
Operating System/Virtual storage prepares
the system for execution of programs in a
batched job environment. Input to the Job
Control Processor is in the form of job
control statements and job control
£.2.!l!.,mands.

in the job deck. The remainder of the card
may contain any character from the EBCDIC
set. Comment statements are designed for
communication with the operator;
accordingly, they are written on the
console output unit, SYSLOG, in addition to
being written on SYSLST. If followed by a
PAUSE control statement, the comment
statement can be used to request operator
action.

JOB CONTROL STATEMENTS
Statement Formats
Job control statements are designed for
an aO-column punched card format. Although
certain restrictions must be observed, the
5tatements are essentially free form. Job
control statements conform to these rules:
1.

Two slashes (//) identify the
statement as a job control statement.
They ~ be in colu~ns 1 and 2. At
least one blank immediately follows
the second slash.

Exceptions: The end-of-job statement
contains /& in columns 1 and 2; the
end-of-data-file statement contains 1*
in columns 1 and 2; the comment
statement contains * in column 1 and a
blank in column 2.

Operation. This identifies the
operation to be performed. It can be
up to eight characters long. At least
one blank follows its last character.

Operand. This may be blank or may
contain one or more entries separated
by commas. The last term must be
followed by a blank, unless its last
character is in column 71.

~ent2.

The following notation is used in the
statement formats:
1.

All upper-case letters represent
specifications that are to appear in
the actual statement exactly as shown
in the statement format. For example,
JOB in the operation field of the JOB
sta tement sh ould be punched exactly as
shown.

All lOWer-case letters represent
generic terms that are to be replaced
in the actual statement. For example,
jobname is a generic term that should
be replaced by the name that the
programmer is giving his job.

Hyphens are used to join two or more
words in order to form a single
generic term. For example,
device-address is one generic tera.

Brackets are used to indicate that a
specification is optional and is not
always required in the statement. For
example, [type] indicates that the
programmer's replacement for the
generic term, type, mayor may not
appear in the statement, depending on
the programmer's requirements.

Braces enclosing stacked items
indicate that a choice of one item
~1 be made by the programmer.
For
example:

Optional programmer
comments must be separated from the
operand by at least one space.

Continuation cards are not recognized by
the Job Control Processor. For the
exception to this rule, see the
descriptions of the DLAB and TPLAB
statements.
All job control statements are read from
the device identified by the symbolic name
SYSRDR.

SYS
FROG
ALL
SYSxxx
Comment statements (i.e., statements
preceded by an asterisk in column 1
followed by a blank) may be placed anywhere
22

indicates that either SYS, PROG, ALL,
or SYSxxx must appear in the actual
statement.

Brackets enclosing stacked items
indicate that a choice of one item
may., but need not, be made by the
programmer. For example:

The label statements must be in the
order:
DLBL
EXTENT (one for each area or file in
the volume)

,X'ss'
,ALT
or
indicates that either ,X'ss' or .ALT
but not both, may appear in the actual
statement, or the specification can be
omitted entirely.
i.

All punctuation marks shown in the
statement formats other than hyphens,
brackets, and braces must be punched
as shown~ This includes periods,
commas, and parentheses. For example,
,[date] means that the specification.
if present in the statement, should
consist of the programmer's
replacement for the generic term date
preceded by the comma with no
intervening space. Even if the date
is omitted, the comma must be punched
as shown.

The ellipsis ( ••• ) indicates where
repetition may occur at the
programmer's option. The portion of
the format that may be repeated is
determined as follows:
a.

Scanning right to left, determine
the bracket or brace delimiter
immediately to the left of the
ellipsis.

TLBL
and must immediately precede the EXEC
statement to which they apply.

DESCRIPTION AND FORMATS OF JOB CONTROL
STATEMENTS
This section contains descriptions and
formats of job control statements.
Job control statements, with the
exception of /*. /&, and~, contain two
slashes in columns 1 and 2 to identify
them.

JOB Statement

Continue scanning right to left
and determine the logically
matching bracket or brace
delimiter.

The JOB control statement indicates the
beginning of control information for a job.
The JOB control statement is in the
following format:

The ellipsis applies to the words
and punctuation between the pair
of delimiters.

IL_________________________________________
/ / JOB jobname
JI

sequence of Job Control statements
The job deck for a specific job always
beains with a JOB statement and ends with a
/&~(end-of-job) statement. A specific job
consists of one or more job steps. The
beginning of a job step is indicated by the
appearance of an EXEC statement. When an
EXEC statement is encountered, it initiates
the execution of the job step, which
includes all preceding control statements
up to, but not including, a previous EXEC
statement.
The only limitation on the sequence of
statements within a job step is that which
is discussed here for the label information
statements.

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

jobname
is a programmer-defined na~e
consisting of from one to eight
alphanumeric characters. Any user
comments can appear on the JOB control
statement following the jobname
(through column 72). The time of day
and date appear in columns 73 to 80
when the JOB staterrent is printed on
SYSLST. The time of day and date are
also printed in columns 1 through 8 on
the next line of SYSLOG.
If a job is restarted, the jobname
must be identical to that used when
the checkpoint was taken.
Note: The JOB statement resets the effect
of all previously issued OPTION and ASSGN
control statements.
Preparing COBOL Programs for Processing

ASSGN

statement

The ASSGN control statement assigns a
logical input/output unit to a physical
device.
An ASSGN control statement must be
present in the job deck for each data file
assigned to an external storage device in
the COBOL program where these assignments
differ from those established at system
generation time.
Data files are assigned
to programmer logical units in COBOL by
means of the source language ASSIGN clause.
An ASSGN statement or command can also be
used

o;:;o.mmand, because ASSGN also opens the
file.

Before a tape unit is assigned to
SYSLST, SYSPCH, or SYSOUT, all
previous assignments to this tape unit
must be permanently unassigned.
This
may be done by using a DVCDN command
instead.

The assignment of SYSLOG cannot be
changed while a foreground partition
is active.

10.
• to unassign a logical unit to free it
for assignment to another partition
• to ignore the assignment of a logical
unit, that is, program references to
the logical unit are ignored
year (00 to 99)

The format to be used is the format
selected when the system was generated.
When the DATE statement is used, it
applies only to the current job being
executed. The Job Control Processor does
not check the operand except to ensure that
its length is eight characters.
If no DATE
statement is specified in the current job,
the Job control Processor supplies the date
given in the last SET command. The SET
command is discussed in detail in the
publication DOS/VS System Control
Statements.
A DATE statement should be included in
every job deck that has as one of its job
steps the execution of a COBOL program that
utilizes the special register CURRENT-DATE,
if the date desired is other than that
designated in the previous SET command.
The DATE statement should be used at
compile time so that the DATE-COMPILED
paraaraph is accurate and the WHEN-COMPILED
~pecial-register is effective.

TLBL statement
The TLBL control statement replaces the
VOL and TPLAB combination used in previous
versions of the system. However, the
current system will continue to support
these statements. The TLBL control
statement contains file label information
for tape label checking and writing.
Its
format follows:

.1// TLBL filename,
I

[, 'file-identifier'] [,date]
[,file-serial-number]
[,volume-sequence-number]
[,file-sequence-number]
[,generation-number]
[,version-number]

filename
identifies the file to the control
program. It can be from three to
seven characters in length. If the
following SELECT sentence appears in a
COBOL program:
SELECT NEWFILE ASSIGN TO
SYS003-UT-2400-S-0UTFILE
the filename operand on control
statements for this file must be
OUTFILE. If the SELECT clause were
coded:
SELECT NEWFILE ASSIGN TO
SYS003-UT-2400-S

omitted or if a retention period is
specified.
file-serial-number
consists of from one to six characters
indicating the volume serial number of
the first (or only) reel of the file.
If fewer than six characters are
specified, the field will be
right-justified and padded with zeros.
If this operand is omitted on output
files, the volume serial number of the
first (or only) reel of the file will
be used.
If the operand is omitted on
input files, no checking will be done.
volume-sequence-number
consists of from one to four
characters in ascending order for each
volume of a multivolume file.
This
number is incremented automatically by
OPEN and CLOSE routines as required.
If this operand is omitted on output
files, BCD 0001 will be used. If
omitted on input files, no checking is
done.
file-sequence-number
consists of from one to four
characters in ascending order for each
file of a multifile volume. This
number is incremented automatically by
OPEN and CLOSE routines as required.
If this operand is omitted on output
files, BCD 0001 will be used. If it
is omitted on input files, no checking
will be done.

the filename operand on the control
statement for the file must be SYS003.
'file-identifier'
consists of from 1 to 17 characters,
contained within apostrophes,
indicating the name associated with
the file on the volume. This operand
may contain embedded blanks. If this
operand is omitted on output files,
the filename will be used. If this
operand is omitted on input files, no
checking will be done.
date
consists of from one to six
characters, in the format yy/ddd,
indicating the expiration date of the
file for output or the creation date
for input.
(The day of the year may
consist of from one to three
characters.)
For output files, a one
to four character retention period
(d-dddd) may be specified. If this
operand is omitted, a O-day retention
period will be assumed for output
files. For input files, no checking
will be done if this operand is

generation-number
consists of from one to four numeric
characters that modify the
file-identifier.
If this operand is
omitted on output files, BCD 0001 is
used. If it is omitted on input
files, no checking will be done.
version-number
consists of from one to two numeric
characters that modify the generation
number. If this operand is omitted on
output files, BCD 01 will be used. If
it is omitted on input files, no
checking will be done.
~:

If a tape file with standard labels
is opened two different ways in the same
COBOL program, and that file resides on a
multifile volume, the programmer should use
two separate TLBL cards with different
filenames specified on each.

Preparing COBOL Programs for Processing

27'

for a file opened as INPUT or
is ignored.

DLBL statement

T_"

~-v,

':.L

.J..\.

codes
is a 2 to 4 character field indicating
the type of file label, as follows:

The DLBL control statement, in
conjunction with the EXTENT statement,
replaces the VOL, DLAB, and XTENT
combination used in previous versions of
the Disk Operating System. The DLBL
statement has the following format:

SD
DA
ISC

ISE

1// DLBL filename
I
,[ 'file-identifer' ],[ date ],[ codes]

II'-__,_[_B_L_K_S_I_Z_E_=_n_J_,_C_C_I_S_I_Z_E_=_n_>_______---'
filename
identifies the file to the control
program. It can be from three to
seven characters long. If the
following SELECT sentence appears in a
COBOL program:
SELECT INFILE ASSIGN TO
SYS005-DA-2314-A-INPUTA
the filename operand on control
statements for this file must be
INPUTA. If the SELECT sentence is
coded:
SELECT IN FILE ASSIGN TO
SYS005-DA-2314-A
the filename operand on control
statements for the file must be
SYS005.
'file-identifier'
is the name associated with the file
on the volume. This can consist of
from 1 to 44 alphanumeric characters
contained within apostrophes,
including the file-identifier and, if
used, generation-number and versionnumber of generation. If fewer than
44 characters are used, the field is
left-justified and padded with blanks.
If this operand is omitted, filename
will be used.
date
consists of from one to six characters
indicating either the retention period
of the file in the format d through
dddd (0-9999), or the absolute
e~piration date of the file in the
format yy/ddd. When the d through
dddd format is used, the file is
retained for the number of days
specified as dddd. For example, if
date is specified as 31, the file will
be retained a month from the day of
creation. When the yy/ddd format is
used, the file is retained until the
day (ddd) in the year (yy) specified.
For example, if date is specified as
90/200, the file will be retained
through the 200th day of the year 1990.
If date is omitted when the file is
created, a 7-day retention period is
assumed. If this operand is present
28

DU
VSAM

Sequential Disk
Direct Access
Indexed Sequential using Load
Create
Indexed Sequential using Load
Extension, Add, or Retrieve
3540 Diskette
VSAM file

If code is omitted, SD is assumed.
BLKSIZE=n
specifies the number of bytes in a
physical record. n must be less
than 32,768. This parameter is
valid for the 3330-11 and 3350 devices
only, and its use is limited to
sequential files.
If specified, it
overrides the BLKSIZE specification
in the definition of the file (DTF).
It permits reblocking of existing
files to a new physical record size
when they are transferred to a
3330-11 or 3350 device, without
requiring recompilation of the DTF.
If the BLKSIZE parameter is not
specified in the DLBL statement, the
new files are assumed to have the
blocksize specified in the DTF. This
parameter is not valid for the compile~
workfiles.
For further information, see DOS/VS
System Control Statements.

CISIZE=n
specifies the control interval size
for SAM files on fixed block devices,
~nd improves sp?ce allocation_9n such
devices. The size specified must
be a mUltiple of the value specified
in the BLKSIZE=noperand. This
operand is valid only for a DLBL
statement with the code SD. It is
not valid for compiler workfiles.
"Appendix H: Sample Job Decks" contains
illustrations of DLBL statement usage.
See the section "Processing 3540
Diskette Unit Files" for the use of DLBL
Cards for 3540 and the section "Virtual
Storage Access Method" for use of DLBL
cards for VSAM.
EXTENT Statement
The EXTE~T control statement defines
each area (or extent) of a DASD file -- a
file assigned to a mass storage device.
One or more EXTENT control statements must
follow each DLBL statement.
The EXTENT control statement replaces
the XTENT statement used in previous
versions of the Disk Operating System. For

more information on the XTENT statement,
see DO~VS~stem Control statements.
The format of the EXTENT control
statement is:
I

1// EXTENT [symbolic-unit],[serial-number]1
I
I
I

,[type],[sequence-number]
I
,[relative-track],[number-of-tracks] I
,[split-cylinder-track],[B=bins]
I
,

symbolic=unit
is a 6-character field indicating the
symbolic unit (SYSxxx) of the volume
for which this extent is effective.
If this operand is omitted, the
symbolic unit of the preceding EXTENT
statement will be used. When
specified, symbolic-unit may be any
SYSxxx assigned to the device type
indicated in the SELECT sentence for
the file.
For example, if the
following coding appears in a COBOL
program:
SELECT OUTFILE ASSIGN TO
SYS004-DA-2314-A
the symbolic unit in the EXTENT
control statement can by any SYSxxx
assigned to a 2314 disk pack. The
symbolic unit operand is not required
for an IJSYSxx filename, where xx is
IN, PH, LS, RS, SL, or RL. If SYSRDR
or SYSIPT is assigned, this operand
must be included.
serial-number
consists of from one to six characters
indicating the volume serial number of
the volume for which this extent is
effective. If fewer than six
characters are used, the field will be
right-justified and padded with zeros.
If this operand is omitted, the volume
serial number of the preceding EXTENT
control statement will be used.
If no
serial number was provided in the
EXTENT control statement, the serial
number will not be checked and it will
be the programmer's responsibility if
files are destroyed as a result of
mounting the incorrect volume.
type
consists of one character indicating
the type of the extent, as follows:
1
2

4
8

Data area (no split cylinder)
Overflow area (for an indexed
file)
Index area (for an indexed file)
Data area (split cylinder)

If this operand is omitted, 1 is
assumed.

sequence-number
consists of from one to three
characters containing a decimal number
from 0 to 255 indicating the sequence
number of this extent within a
multi-extent file.
Extent sequence 0
is used for the master index of an
indexed file.
If the master index is
not used, the first extent of an
indexed file has the sequence number
1. The extent sequence number for all
other types of files begins with O.
If this operand is omitted for the
first extent of ISAM files, the extent
will not be accepted.
For SD or DA
files, this operand is not required.
For DA files this operand should be
specified when using more than one
EXTENT for a file.
Direct files can
have up to five extents. Indexed
files can have up to eleven data
extents (nine prime~ one cylinder
index, one separate overflow).
relative-track
consists of from one to five
characters indicating the sequential
number of the track, relative to zero,
where the data extent is to begin.
If
this field is omitted on an ISAM file,
the extent will not be accepted. This
field is not required for DA input or
for SD input files (the extents from
the file labels will be used).
For fixed block devices, this operand
is a number from 2 to 2,147,483,645
that specifies the physical block
at which the extent should start.
Formulas for converting actual to
relative track addresses (RT) and
relative track to actual for the DASD
devices follow.
Actual to Relative:
2311 10 x cylinder number + track
number = RT
2314 20 x cylinder number + track
or
number = RT
2319
2321 1000 x subcell number + 100 x
strip number + 20 x block
number + track number = RT
3330 19 x cylinder number + track
number = RT
3340 12 x cylinder number + track
number = RT
3350 30 x cylinder number + track
number = RT
preparing COBOL Programs for Processing

Relative to Actual:

= quotient

2311

RT
10

is cylinder
remainder is track

2314
or
2319

RT
20

quotient is cylinder,
remainder is track

3330

RT
19

quotient is cylinder,
remainder is track

2321

RT
quotient is subcell,
1000 remainderl
remainderl
100

quotient is strip,
remainder2

rernainder2
20

quotient is block,
remainder is track

There is no need to specify a creating
bin for SD or 18AM files.
If this
operand is omitted, bin 0 is assumed
for both bins. If the operand is
included and positional operands are
omitted, only one comma is required
preceding the keyword operand. If any
operands preceding the bin
specification are omitted, one comma
for each operand is acceptable, but
unnecessary.
Figure 4 shows examples of using the
DLBL statement in conjunction with the
EXTENT statement.
"Appendix H: sample Job
Decks" contains illustrations of EXTENT
statement usage.
VOL, DLAB,'TPLAB AND XTENT STATEMENTS

3340

RT
12

quotient is cylinder,
remainder is track

3350

RT
quotient is cylinder,
30
remainder is track
number-of-tracks
consists of from one to five
characters indicating the number of
tracks to be allocated to the file.
For SD input files, this field may be
omitted. The number of tracks for a
split cylinder file must be a multiple
of the number of cylinders specified
for the file and the number of tracks
specified for each cylinder.
For fixed block devices, this operand
is a number from 1 to 2,147,483,645
that specifies the number of physical
blocks in the extent.
split-cylinder-track
consists of from one to two
characters, with a value of 0 through
19, indicating the upper track number
for the split cylinder in SD files.
bins
consists of from one to two characters
identifying the 2321 bin that the
extent was created for, or on which
the extent is currently located.
If
the field is one character, the
creating bin is assumed to be zero~

These statements have been replaced by
the DLBL, TLBL, and EXTENT statements, and,
although they are still supported by the
Disk Operating System, they cannot be used
for 3330 or 3340 disk files, or for VSAM
files.
Details as to their usage can be
found in DOS/vS System Control Statements.
For their use with respect to COBOL, see
IBM DOS Full American National Standard
COBOL Programmer's Guide. When new label
information statements are prepared, DLBL,
TLBL, and EXTENT should be used.
LBLTYP Statement
The LBLTYP control statement defines the
amount of storage to be reserved at linkage
edit time in the problem program area of
storage in order to process tape and
nonsequential DASD file labels. It applies
to both background and foreground object
programs, and is required if the file
contains standard labels.
The LBLTYP control statement immediately
precedes the // EXEC LNKEDT statement in
the job deck, with the exception of
self-relocating programs for which it is
instead submitted immediately preceding the
// EXEC statement for the program. The
format of the LBLTYP control statement is:

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

I
TAPE [ (nn)]
I
1// LBLTYP
I
IL _________________________________________
NSD(nn)
JI

r--------~------------------------------------------------------------------------------,

IDirect file:

The following DLBL and EXTENT statements describe a direct file occupying 840
I
I tracks, beginning on relative track 10.
// DLBL MASTER,,75/001,DA
I
// EXTENT SYS015,111111,1,0,10,840
I

I
I
I

IIndexed file:
1
I
The following DLBL and EXTENT statements describe an indexed file on a 2314
I
loccupying 100 tracks, beginning on relative track 1100. The first EXTENT allocates a
i
120-track cylinder index. The second EXTENT allocates a 80-track data area.
I
I
// DLBL MASTER,,7S/001 p ISC
I
// EXTENT SYS015,111111,4,1,1100,20
IL _______________________________________________________________________________________
// EXTENT SYS015,111111,l,2,1120,80
JI
Figure
30

Sample Label and File Extent Information for Mass Storage Files

TAPE [ (nn)]
is used only 1I tape L~~~~ requiring
label information are to be processed
and if no nonsequential DASD files are
to be processed. nn is optional and
is present only for future expansion.
It is ~gnored by the Job Control
Processor.

ALL
causes the physical units assigned to
all logical units to be listed.
SYSxx'x
causes the physical units assigned to
the logical unit specified to be
listed.

NSD(nn)
is used if any nonsequential DASD
files are to be processed, regardless
of other type files that are used. nn
specifies the largest number of
extents to be used for a single file.

UNITS

LISTIO Statement

DOWN

causes the logical units assigned to
all physical units to be listed.

causes all physical units specified as
inoperative to be listed.

The LISTIO control statement causes the
system to print a list of input/o~tput
assignments on SYSLST. The format o.f the
LISTIO control statement is:

UA
causes all physical units not
currently assigned to a logical unit
to be listed.

r--------------------------------------~--,

I
I

I
I
I
I

SYS
PROG
BG
F1

F2
F3

/ / LISTIO

F4
ALL
SYSxxx
UNITS
DOWN
UA
~u

X'cuu'

I
I
I
I
I
I
I
I
I

IL_______________
ASSGN _______________________
(ReI. 35 and up)
JI
~_~

cuu (Release 35 and up)
or
X'cuu'
causes the logical units assigned to
the physical unit specified to be
listed.
Ai:)SGN
causes all system and program logical
units assigned to the current partition
to be listed.

SYS
causes the physical units assigned to
all system logical units to be listed.
MTC Statement

PROG
causes the physical units assigned to
all background programmer logical
units to be listed.
BG
lists the physical units assigned to
all logical units of the background
partition.
F1

causes the physical units assigned to
all foreground-one logical units to be
listede
F2

causes the phySical units assigned to
all foreground-two logical units to be
listed.
F3

causes the physical units assigned to
all foreground-three logical units to
be listed.
F4

causes the physical units assigned to
all foreground-four logical units to
be listed.

The MTC control statement controls 2400
and 3400 series magnetic tape operations.
The format is as follows:

r--------------------------------------MTC opcode, {Sx~~~x~} [ , nn]
:
i

I / /

cuu
cuu ---.

...J

~---------------------------------------

opcode
specifies the operation to be
performed. opcode can be chosen from
the following:
BSF

Backspace to tapernark

BSR

Backspace to interrecord gap

ERG

Erase gap (write blank tape)

FSF

Forward space to tapemark

FSR

Forward space to interrecord
gap

RUN

Rewind and unload

Preparing COBOL Programs for Processing

REW
WTM

Rewind
Write tapemark

SYSxxx
represents any logical unit assigned
to magnetic tape upon which the MTC
control statement is to operate.

NODUIvlP
suppresses the DUMP option.
LINK
indicates that the object module is to
be link edited.
When the LINK option
is used, the output of the COBOL
compiler is written on SYSLNK. The
LINK option must always pre~ede an
EXEC LNKEDT statement in the job deck.
, a full comp1lat10n
OPTIMIZE
is produced so long as no messages
NCOPTIMIZE
exceed the C level. If one or more
OPT
E-level or higher severity messages
NOOPT
are produced, the compiler generates
the messages but does not generate
OPTIMIZE (OPT) causes optimized object
object text.
code to be generated by the compiler.
The more efficient code generated conNotes:
siderably reduces the amount of space
required by the object program.
If
1. When the SYNTAX option is in
neither LINK nor DECK is specified in
effect, all of the following
the OPTION statement, then optimized
compile-time options are
code is not generated by the compiler.
suppressed:
This option cannot be used if either the
symbolic debug option (SYMDMP), the statement number option (STATE), or the flow
trace option (FLOW!=nnJ) is requested.

OPTION control statement:
DECK, XREF

CBL statement: SXREF, CLIST,
COUNT, VERBREF, VERBSUM

FLOvl [=nnJ

provides the programmer with a ~ormatted
trace (i.e., a list containing the proaram identification and statement
~umbers) corresponding to a variable
number of procedures executed prior to
an abnormal termination. The value linn"
may range from a through 99. If "nn" is
not specified, a value of 99 is assumed.
FLOW and STXIT, and FLOW and OPT are
mutually exclusive options, i.e., only
38

LINK,

When CSYNTAX is requested and one
or more D- or E-Ievel messages
occur; then the preceding options
are suppressed and the CBL option
FLAGE is made active.

Unconditional syntax checking is
assumed if all of the following
compile-time options are
specified:

OPTION control statement:
NOXREF, NODECK

NOLINK,

CBL statement: SUPMAP. (and CLIST,
SXREF, VERBSUM, and VERBREF are
not specified)
4.

Some compiler diagnostics do not
appear when SYNTAX or CSYNTAX is
in effect. These are listed in
ftprogram Checkout. ft
SYMDMP[=filename]
indicates to the compiler that
execution-time dumps might be
requested for the program currently
being compiled. If dumps are desired,
the programmer must provide the
required control cards at execution
time. For storage considerations at
execution time, see Appendix F:
"System and Size Considerations."
Use of the symbolic debug option
necessitates the presence of an .
additional work file, SYS005, at
compile time. The nfilename ft
parameter enables the programmer to
specify a name for the SYS005 file
that he can retain. If no filename is
specified. IJSYS05 will be used. When
several COBOL programs are link edited
together, the nfilename n parameter
enables each to have a unique SYMDMP
name. Compile and execution must be
done in the same job stream. The
SYS005 file is deleted at end of job.
For a tape file, only unlabeled tapes
may be used, and the filename in
the SYMDMP=filename parameter is
ignored.
SYMDMP and STXIT, SYMDMP and STATE,
and SYMDMP and OPT are mutually
exclusive options, i.e •., no more than
one may be in effect during a given
compilation.
(However, the facilities
provided by STATE are automatically
included with SYMDMP.) In addition,
SYMDMP and STXIT are mutually
exclusive at execution-time.
Additional information on the symbolic
debug option and the required
execution-time control cards can" be
found in the chapter nSymbolic
Debugging. Features. n
Note: If NODECK and NOLINK are requested
on the OPTION control statement and either
SYMDMP or OPT is specified on the CBL card,
the SYMDMP or OPT specification is ignored.
CATALR
NOCATALR
causes the compiler to generate CATALR
card images on the SYSPCH file if
OPTION DECK is in effect during
compilation. This will allow
cataloging of the compiler produced
object modules into the relocatable
library. The module names in the
CATALR cards adhere to the same rules
as the phase names in the compiler

produced PHASE cards according to the
segmentation and sort phase naming
conventions (see the sections on Sort
and Segmentation Features).
LIB
NOLIB
-----indicates that BASIS and/or COpy
statements are in the source progra~.
If either COpy or BASIS is present~
LIB must be in effect. If COpy and/or
BASIS statements are not present., use
of the NOLIB option yields more
efficient compiler processing.
VERB
NOVERB
indicates whether procedure-names and
verb-names are to be listed with the
associated code on the "object-program
listing. VERB has meaning only if
LISTX" CLIST., VERBSUM, VERBREF, COUNT
or READY TRACE are in effect. NOVERB
yields more efficient compilation.
LVL=
NOLVL
-----indicates whether the compiler should
identify COBOL clauses and statements
in a DOS/VS COBOL source program that
do not conform to the Federal
Information Processing Standard. FIPS
recognizes four language levels: low,
low-intermediate, high-intermediate
and full. The FIPS Flagger provides
four levels of flagging from low (A)
to high (D) to conform to the four
levels of the FIPS.
Note: The FIPS Flagger needs a disk
workfile to be assigned to SYS006.
VERBSUM
NOVERBSUM
provides a brief summary of verbs used
in the program and a count of how
often each verb was used. This option
provides the user with a quick search
for specific types of statements.
VERBSUM implies VERB.
VERBREF
NOVERBREF
provides a cross reference of all
verbs used in the program. This
option provides the prograrrmer with a
quick index to any verb used in the
program. VERBREF implies VERB and
VERBSUM.
COUNT
NOCOUNT
generates code to produce verb
execution summaries at the end of
problem program execution. Each verb
is identified by procedure-name and by
Preparing COBOL Programs for Processing

statement number, and the number of
times it was used is indicated. In
addition, the percentage of verb
execution for each verb with respect
to the execution of all verbs is
given. A summary of all executable
verbs used in a program and the number
of times they are executed is
provided. COUNT implies VERB.
Note:
If COUNT and STXIT are desired,
then either STXIT must be requested in
the program unit requesting COUNT, or
the program unit requesting COUNT must
be entered before the program unit
requesting STXIT. See the chapter
entitled "Execution statistics" for
additional information on the COUNT
option.

LST statement -- New Compiler Option Card

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

In some of the preceding descriptions of
the CBL card options, restrictions have
been placed on the use of one option in
conjunction with others.
It should be
noted that if these restrictions are
violated, the compiler ignores all but the
last of the conflicting options specified.
For this reason, if after a CBL card is
coded the programmer decides to use a new
option that is mutually exclusive with an
option on the original CBL card, a new CBL
card can be added rather than changing the
original card.

[LSTCOMP'J fPROC=lcol~1
LSTONLY
2colJI

IL _________________________________________ JI
LST
must begin in column 2 (coluQn 1 must
be blank) and be followed by at least
one blank.
DECK
NODECK
indicates whether an updated source
deck is to be produced as a result of
the lister reformatting and/or the
update BASIS library.
COPYPCH
NOCOPYPCH
will punch updated and reformatted
copy libraries as a permanent part of
the Source when DECK is specified.
When no updated source deck is

PROC=lcol
2col
will list the Procedure Division in
either single- or double-column
format.
At least 132 print positions
are required on the printer for the
double-column' format.

Mutually Exclusive Options

The LST option card can be placed
anywhere between the EXEC statement and the
first statement of the COBOL program. It
may be placed between any other compiler
option cards. The options shown in the
following format may appear in any order.
Underscoring indicates the default case.

I[I DECK,
] [COPYPCH, ]
NODECK NOCOPYPCH

LSTONLY
LSTCOMP
when LSTONLY is specified, the prograrr
will not be compiled, but a
reformatted listing will be produced
along with a deck if DECK has been
specified. LSTCOMP will provide a
source listing and will compile the
program as part of the job step.
LSTCOMP does not suppress CLIST.

For more details on the lister program,
see the chapter entitled "Using the Lister
Feature" •

The LST statement is used to invoke the
lister, a portion of the compiler that
processes programs written in American
National Standard COBOL to produce a
reformatted source code listing containing
embedded cross-reference information, and
uniform indenting conventions.

requested, an updated and reformatted
COpy library will be punched out.

Changing the Installation Defaults
In order to change the compiler default
options to suit your installation, a new
member, C.CBLOPTNS, must be added to the
source statement library. This module must
contain CBL option cards specifying the
desired defaults. Resultant defaults may
be overridden at compilation tiroe by
supplying a eBL card in the compiler input
stream.

Significant Characters for Various Options
The DOS/VS COBOL compiler selects the
valid options for processing by looking for
three significant characters of each key"

option word. When the keyword is
identified, it is checked for the presence
or absence of the prefix ~O, as
appropriate. The programmer can make the
most efficient use of the CBL card by using
the significant characters instead of the
entire options Table 3 lists the
significant characters for each option.
Table

regular job deck for a job. Job control
commands tend to be effective across jobs.
whereas job control statements are confined
within a job.
Job control commands are discussed in
detail in the publication DOS/vS System
Control Statements.

Significant Characters for
Various Options

r------------------T----------------------,
I
Significant
!

i
I

Option
I
Characters
I
~------------------+----------------------~
i
SEQ
I
SEQ
!
1
FLAGE(W)
1
LAG,LAGW
I
BUF
I
BUF
I
SPACE
1
ACE
I
PMAP
I
PMA
I
SUPMAP
1
sUP
I
CLIST
I
CLI
I
~RUNC
I
TRU
I
APOST
I
APO
I
QUOTE
I
QUO
I
SXREF
I
SXR
STATE
I
STA
FLOW
I
FLO
LIB
I
LIB
SYMDMP
1
SYM
OPTIMIZE
I
OPT
SYN~AX
I
SYN
CSYNTAX
I
CSY
VERB
I
VER
ZWB
I
ZWB
LVL
I
LVL
COUNT
I
COU
VERBSUM
I
VERBSUM
VEREREF
I
VERBREF
STXIT
I
STX
DECK
I
DEC
COPYPCH
J
COP
LSTCOMP
I
S~C
LSTONLY
I
STO
PROC
PRO _____________ J
_______________
___ I ________
~

Note: SYM on the CBL card should not be
confused with SYM on the OPTION card.

JOB CONTROL COMMANDS
Job control commands are distinguished
from job control statements by the absence
of // blank in positions 1 through 3 of
each command. They permit the operator to
adjust the system according to day-to-day
operating conditions.
This is particularly
true in the area of device assignment,
where the operator may need to
{li communicate to the system that a device
is unavailable, or (2) designate a
different device as the standard for a
given symbolic unit.
Therefore, these
commands normally are not a part of the

LINKAGE EDITOR CONTROL

STATEMEN~S

Object modules used as input to the
Linkage Editor must include linkage editor
control statements. There are four linkage
editor control statements: PHASE. INCLUDE,
ENTRY, and ACTION.
Linkage editor control statements
initially enter the system through the
device assigned to SYSRDR as part of the
input job stream. PHASE and INCLUDE
statements may also be present on SYSIPT or
in the relocatable library. All four
statements are verified for operation
(INCLUDE, ACTION, ENTRY, or PHASE) and are
copied to SYSLNK to become input when the
Linkage Editor is executed.
Linkage editor control statements must
be blank in position 1 of the statement.
The operand field is terminated by the
first blank position. It cannot extend
beyond column 72.
The Linkage Editor is executed as a
distinct job step. Figure 5 shows how the
linkage editor function is performed as a
job step in three kinds of operations.
1.

Catalog Programs in Core Image
Library. The 1 ~.nkage editor function
is performed immed=ately preceding the
operation that catiilogs programs into
the core image library. When the
CATAL option is sp~~ified, programs
edited by the Linkage Editor are
cataloged in the core image library by
the Librarian after the editing
function is performed. The sequence
of this operation is shown in Part A
of Figure 5.
Note that the input for
the LNKEDT function could contain
modules from the relocatable library
instead of. or in addition to, those
modules from the card reader. tape
unit; or mass storage unit extent
aSSigned to SYSIPT. This is
accomplished by naming the module'(s)
to be copied from the relocatable
library in an INCLUDE statement.

Preparing COBOL Programs for Processing

40.1

Load-and-Execute.
The sequence of
this operation is shown in Part B of
Figure 5. Specifying OPTION LINK
causes the Job Control Processor to
open SYSLNK, and allows the Job
Control Processor to place the object
module(s) and linkage editor control
statements on SYSLNK.
As with the
catalog operation, the input can
consist of object modules from the
relocatable library instead of, or in
addition to, those modules from the
card reader, tape unit, or disk extent
assigned to SYSIPT. This is accomplished by specifying the name of the
module to be included in the operand
of an INCLUDE statement. After the
object modules have been edited and
placed in the core image library, the
program is executed. The blank
operand in the EXEC control statement
indicates that the program that has
just been link edited and temporarily
stored in the core image library is to
be executed.

single sequence of job steps.
In
order to do this, the COBOL compiler
is directed to write the object module
directly on SYSLNK. This is done by
using the LINK option in the OPTION
control statement. Upon completion of
this output operation, the linkage
editor function is performed. The
program is link edited and temporarily stored in the core image
library.
The sequence of this
operation is shown in Part C of Figure
5.
In each of the operations described in
Figure 5, if a private core image library
is assigned, output from the Linkage Editor
will be placed (either permanently or
temporarily) in the private core image
library rather than in the system core
image library.
If the Linkage Editor is
executed in a batched-job foreground
partition, a private core image library
must be assigned.
Private core image
libraries are a system generation option.

Compile-and-Execute.
Source modules
can be compiled and then executed in a

c
40.2

I
I

~----- EXEC FCOSOL - - - - - . . . ;

OPTION CATAL
PHASE PROGA, *
~_ _ _ _ _ _ INCLUDE
{object module}
ENTRY
EXEC LNKEDT

I
- - - - -_ _+010 - -_ _ _ _ _

EXEC PROGA

-----~

LOAD AND EXECUTE

Core
"Storage
execution

.....- - - - - EXEC FCOSOl

.1
I

OPTION LINK
I
INCLUDE
I
JI
{o bject module}
I
~I------------------ENTRY
----------------------~.I
EXEC LNKEDT
I
EXEC

COMPilE AND EXECUTE

Core
Storage
Execution

I
I
I
I

OPTION LINK
EXEC FCOSOl
,..-._ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ ENTRY

.. I

EXEC lNKEDT
EXEC

Figure

Job Definition -- Use of the Librarian

control statement Placement
The placement of linkage editor control
statements is subject to the following
rules:
1.

The ACTION statement must be the first
linkage editor control statement
encountered in the input stream;
otherwise r it is ignored.

The PHASE statement must precede each
object module that is to begin a
phase.

The INCLUDE statement must be
specified for each object module that
is to be included in a program phase.

A single ENTRY statement should follow
the last object module when multiple
object modules are processed in a
single linkage editor run.

ACTION and ENTRY statements, when
present r must be on SYSRDR.
PHASE and
INCLUDE statements may be present on
SYSRDR, SYSIPT, or in the relocatable
library.

PHASE Statement
The PHASE statement must be specified if
the output of the Linkage Editor is to
consist of more than one phase or if the
program phase is to be cataloged in the
core image library. Each object module
that begins a phase must be preceded by a
PHASE statement. Any object module not
preceded by a PHASE statement will be
included in the current phase.
The statement provides the Linkage
Editor with a phase name and an origin
point for the phase. The PHASE statement
is in the following format:

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

Il _________________________________________
PHASE narne,origin[,NOAUTO]
JI

Preparing COBOL Programs for Processing

name
is the symbolic name of the phase. It
is the name under which the program
phase is to be cataloged. This name
does not have to be the name specified
in the PROGRAM-ID paragraph in the
Identification Division of the source
program and, in the case of
segmentation and/or sort, it should
not be the same. It must consist of
from one to eight alphanumeric
characters. Phases that are to be
executed in a segmentation and/or sort
structure should have phase names of
from five to eight alphanumeric
characters. the first four of which
should be the same. An asterisk
cannot be used as the first character
of a phase name.
If no phase name is
specified, a dummy phase name of
PHASE*** is used and execution stops
at end of compilation. The job is
then cancelled.
origin
indicates to the Linkage Editor the
starting address of this specific
phase. An asterisk may be used as an
origin specification to indicate that
this phase is to follow the previous
phase. This origin specification
format of the PHASE statement covers
all applications that do not include
setting up overlay structures. See
the chapter "Calling and Called
Programs" for information on the PHASE
statement for overlay applications.
NOAUTO
indicates that the Automatic Library
Look-Up (AUTOLINK) feature is
suppressed for both the private
relocatable library and the system
relocatable library.
(The use of
NOAUTO causes the AUTOLINK process to
be suppressed for that phase only.)
The AUTOLINK feature is discussed
later in this chapter.
INCLUDE Statement
The INCLUDE statement must be specified
for each object module deck o~~ object
module in the relocatable library that is
to be included in a program phase. The
format of the INCLUDE statement is as
follows:

r-----------------------------------------,
I
INCLUDE [module-namel [.(namelist)]
I
l _________________________________________ J

The INCLUDE statement has two optional
operands. When both operands are used,
they must be in the prescribed order. When
the first operand is omitted and the second

operand is used, a comma must precede the
second operand.
module-name
must be specified when the object
module is in the relocatable library.
It is not specified when the module to
be included is in the form of a card
deck being entered from SYSIPT.
module-name is the name under which
the module was cataloged in the
library, and must consist of from one·
to eight alphanumeric characters.
(namelist)
causes the Linkage Editor to construct
a phase from the control sections
specified in the list. Since control
sections are of no interest to the
COBOL programmer, users interested in
this option should refer to the
description of the INCLUDE statement
in the publication DOS/VS System
Control Statements.

ENTRY Statement
The ENTRY statement is required only if
the programmer wishes to provide a specific
entry point in the first phase produced by
the Linkage Editor. When no ENTRY
statement is provided, the Job Control
Processor writes an ENTRY staterrent with a
blank operand on SYSLNK to ensure that an
ENTRY statement will be present to halt
link editing. The transfer address will be
the load address of the first phase. The
ENTRY statement is described further in the
publication DOS/vS System Control
Statements.

ACTION Statement
The ACTION statement is used to indicate
linkage editor options. When used, the
statement must be the first linkage editor
statement in the input stream. The format
of the ACTION statement is as follows:

r-----------------------------------------,
CLEAR

I
I
I
J

MAP
NOMAP
NOAUTO
NOREL

JI
Fl
BG
I
F2
I
F3
IL________________________________________
F4
_

CLEAR
indicates that the entire temporary
portion of the core image library will
be set to binary zero before the
beginning of the linkage editor
function. CLEAR is a time-consuming
function and should be used only when
necessary.
MAP
indicates that SYSLST is available for
diagnostic messages. In addition, a
storage map is output on SYSLST.
NOMAP
indicates that SYSLST is unavailable
when performing the link edit
function. The mapping of storage is
not performed, and all linkage editor
diagnostic messages are listed on
SYSLOG.
NOAUTO
suppresses the AUTOLINK function for
both the private and system
relocatable libraries during the link
editing of the entire program.
AUTOLINK is discussed later in this
chapter.
CANCEL
causes an automatic cancellation of
the job if any of the linkage editor
errors 21001 through 21701 occur.
These diagnostic messages can be found
in the publication DOSjVS System
Control Statements.
BG, F1, F2, F3, and F4
are options used to link edit a
program for execution in a partition
other than that in which the link edit
function is taking place. See the
publication DOS/VS System Control
Statements.
NOREL
suppresses the relocating

load~r.

Link editing for a specific address is
performed.

AUTOLINK FEATURE
If any references to external-names are
still unresolved after all modules have
been read from SYSLNK, SYSIPT, and/or the
relocatable library, AUTOLINK collects each
unresolved external reference from the
phase. It then searches the private
relocatable library (if SYSRLB has been
assigned) and the system relocatable
library for module names identical to the
unresolved names and includes these modules
in the program phase. This feature should
not be suppressed (via PHASE or ACTION
statements) in linkage editor job steps
which include COBOL subroutines cataloged
in the relocatable library. See the
chapter nCalling and Called Programs n for
additional details.

RELOCATING LOADER FEATURE
The relocating loader feature allows
users to load single-phase and multi-phase
programs at any valid problem program
address in the system. Under this option,
the linkage editor catalogs relocatable
phases into the core image library, and the
relocating loader in the supervisor assigns
the absolute machine addresses that are
necessary for program execution. This
means the user need retain only one copy of
the program in the core image library.
The relocating loader is an optional
feature, and must be specified at system
generation time.
Figure 6 illustrates options available
during link-editing.

Preparing COBOL Programs for Processing

YES

LINKAGE-EDITING FOR A
SPECIFIC PARTITION
-

Default: Addresses will be
adjusted for the specified
virtual partition.
Option: User may
specify linking for
the associated real
partition.

LINKAGE EDITOR
PRODUCES
RELOCATABLE
PHASES

Yes

This supervisor cannot
load relocatable phases.
The user should specify
ACTION=NOREL at
link-edit time,. or generate
another supervisor with
relocating loader.

System retains flexibility of
loading in any partition.
Program may be included in
job stream for any partition
when program is loaded.
Default: Program runs
in virtual mode.
Option: User may specify
execution in associated
real partition.

Figure

options Available During Link-Editing

LIBRARIAN FUNCTIONS

LIBRARIAN

DOS/VS supports four libraries: the
:ore image library, the relocatable
library, the source statement library, and
the procedure library. The core image,
relocatable, and source statement libraries
are classified as system libraries and
private libraries. The procedure library
exists only as a system library. The
system residence device (SYSRES) contains
the system libraries. Private libraries
can be contained on separate disk packs.
These libraries are discussed under
"Private Libraries" in this chapter.
Executable programs (core image format) are
stored in the core image library;
relocatable object modules are stored in
the relocatable library; source language
routines are stored in the source statement
library; catalogued procedures are stored
in the procedure library.

Maintenance functions are used to
catalog (that is, add), delete, or rename
components of the four libraries, condense
libraries and directories, set a condense
limit for an automatic condense function,
reallocate directory and library extents,
and update the source statement and
procedure libraries.

PLANNING THE LIBRARIES

The copy function is used either to
completely or selectively copy the disk on
which the system resides. Service
functions are used to translate information
from a particular library to printed
(displayed) or punched output.

The components of the DOS/VS system are
shipped in three system libraries: the
core image library, the relocatable
library, and the source statement library.
A fourth library -- the procedure library
-- is available but it does not contain any
information when the system is shipped.
Kost programs and procedures developed and
used by your installation will also be
stored in these libraries. In addition to
the system libraries, DOS/VS supports
private libraries which you can use to
either sUbstitute for or supplement the
corresponding system libraries.
Planning the size, contents, and
location of these libraries according to
the needs of your installation is an
essential part of the system generation
procedure. such detailed planning will
ensure that:

The Librarian is a group of programs
that perform three major functions:
1.

Maintenance

Service

Copy

Only the catalog maintenance function of
the Librarian is discussed in this
publication for the four system libraries.
In addition, the update function of the
source statement library is discussed. A
complete description of librarian functions
can be found in· the publication DOS/VS
System Control Statements.
4

CORE IMAGE LIBRARY
The core image library may contain any
number of programs. Each program consists
of one or more separate phases. Associated
with the core image library is a core image
directory which contains a unique
descriptive entry for each phase in the
core image library. These entries in the
core image directory are used to locate and
retrieve phases from the core image
library.

• No disk space is wasted by components
not required in your installation.
Cataloging and Retieving Program Phases -Core Image Library
• The libraries are large enough to allow
for future additions.
• The libraries are accessed by the
system with maximum efficiency.

If a program is to be cataloged in the
core image library, the job control
statement II OPTION with the CATAL option
Librarian Functions

must be specified pr~or to the first
linkage editor control card, and must
precede the first PHASE card of the program
to be cataloged. Upon successful
completion of the linkage editor job step,
output from the Linkage Editor is placed in
the core image library as a permanent
member. The program phase is cataloged
under the name specified in the PHASE
statement.

If a phase in the core image library is
to be replaced by a new phase having the
same name, only the catalog function need
be used. The previously cataloged phase of
the same name is implicitly deleted from
the core image directory by the catalog
function, and the space it occupies in the
library can later be released by the
condense function.
Note: The necessary ASSGN control
statements must follow the II JOB control
statement if the current assignments are
not the following:
1.

SYSRDR -- Card reader, tape unit, or
disk extent

SYSIPT

Card reader, tape unit, or
disk extent

SYSLST

Printer, tape unit, or disk
extent

SYSLOG

Printer keyboard

SYSLNK

Disk extent

EXEC LNKEDT

When the phase is executed in a
subsequent job, the EXEC statement that
calls for execution must specify FOURA,
i.e., the name by which the phase has been
cataloged.

II
II

JOB EXJOB
EXFC FOURA

Phases can be in either non-relocatable
or relocatable format. The non-relocatable
phases are loaded at the addres~ computed
at link-edit time into a real or virtual
partition. The load addresses and address
constants of relocatable phases can be
modified by the relocating loader. These
phases can be loaded at a ~al address
different from the one for which it was
link-edited.
RELOCATABLE LIBRARY

The following is an example of
cataloging a single phase, FOURA, into the
core image library.
(The program phase
FOURA can be executed in the next job step
by specifying the II EXEC statement with a
blank name field.)

II
II

JOB CATALOG
OPTION CATAL
PHASE FOURA,*
INCLUDE

The relocatable library contains any
number of modules. Each module is a
complete object deck in relocatable format.
The purpose of the relocatable library is
to allow the programmer to maintain
frequently used routines in residence and
combine them with other modules without
recompiling.
Associated with the relocatable library
is the relocatable directory. The
directory contains a uniaue, descriptive
entry for each module in the relocatable
library. The entries in the relocatable
directory are used to locate and retrieve
modules in the relocatable library.

~AINTENANCE

FUNCTIONS

{object deck}

II
II
II

LBLTYP TAPE
EXEC LIKEDT
EXEC

To compile, link edit, and catalog the
phase FOURA into the core image library in
the same iob. the followinq iob deck could
be used: - II JOB CATALOG
II OPTION CATAL
PHASE FOURA,*
II EXEC FCOBOL
46

To request a maintenance function for
the relocatable library, the following
control statement is used:

EXEC MAINT

Cataloqing a Module -- Relocatable Librarv
The catalog function adds a module to
the relocatable library. A module in the
relocatable library is the output of a
complete COBOL compilation.

The catalog function implies a delete
function. Thus, if a module exists in the
relocatable library with the same name as a
module to be cataloged, the module in the
library is deleted by deleting reference to
it in the relocatable directory.
The CATALR control statement is required
to add a module to the relocatable library.
The format of the CATALR control statement
is:

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

iL_________________________________________
CATALR module-name [,v.m]
JI
module-name
is the name by which the module is
known to the control program. The
module-name consists of from one to
eight characters , the first of which
must not be an asterisk.

on SYSPCH. The next job step catalogs the
object module (MOD9) into the relocatable
library. Since the object module must be
cataloged from SYSIPT. a message to the
operator instructs him to place the object
module on SYSIPT behind the CATALR
statement.
The following is an example of
cataloging two previously created object
modules in the relocatable library:
// JOB EIGHT
// EXEC MAINT
CATALR MOD8A
{object deck}
CATALR MOD8B
{object deck}
/*

/&
v.m
specifies the change level at which
the module is to be cataloged. ~ may
be any decimal number from 0 through
127. ~ may be any decimal number from
o through 255. If this operand is
omitted, a change level of 0.0 is
assumed. A change level can be
assigned only when a module is
cataloged.
All control statements required to
catalog an object module must be read from
SYSIPT.
Note: If SYSRDR and/or SYSIPT are assigned
to a tape unit, the MAINT program assumes
that the tape is positioned to the first
input record. The tape is not rewound at
the end of the job. If a tape mark is
found, MAINT assumes end-of-job.
The following is an example of compiling
a source program and cataloging the
resultant module in the relocatable
libra~y.
The job deck is read from SYSIPT.
// JOB NINE
// OPTION DECK
// EXEC FCOBOL

An additional capability of the system
permits a programmer to compile a program
and to catalog it to the system
relocatable, or private relocatable,
library in one continuous run. The
programmer inserts a CATALR statement in
his job control input stream preceding the
compiler execute statement. The CATALR
statement will be written on the SYSPCH
file (tape or mass storage device) ahead of
the compiler output when OPTION DECK is in
effect. The programmer then reassigns the
SYSPCH file as SYSIPT and executes the
MAINT program to perform the catalog
function. The output of the co~pilation
(on tape or mass storage device) may be
cataloged immediately or it may be
cataloged at some later time. It can also
be held after cataloging as backup of the
compilationo
The preceding method is recorrmended for
single-module object decks.
In programs
for which the compiler produces multimodule
object decks (when segmentation and/or SORT
are being used), it is necessary to use the
CBL card CATALR option. This option causes
a CATALR card to precede each object
module.

{source deck}
SOURCE STATEMENT LIBRARY

// PAUSE PLACE DECK AFTER CATALR CARD
// EXEC MAINT
CATALR MOD9
(punched deck goes here)
/*
/&

In the above example, as a result of the
compile step, the object module is written

The source statement library contains
any number of books. Each book in the
source statement library is composed of a
sequence of source language statements.
The purpose of the source statement library
is to allow the COBOL prograrrwer to
initiate the compilation of a book into the
source program by using the COPY statement
or BASIS card.
Librarian Functions

Each book in the source statement
library is classified as belonging to a
specific sublibrary.
Sublibraries are
defined for three programming languages:
Assembler, PL/I, and COBOL.
Individual
books are classified by sublibrary names.
Therefore, books written in each of these
languages may have the same name.

The operation field contains CATALS.
sublib
represents the sublibrary to which a
book is to be cataloged and can be:
Any alphanumeric character (0-9, A-Z,
#, $, and @) representing source
statement libraries. The characters
A, C, E, and P have special uses:

Associated with the source statement
library is a source statement directory.
The directory contains a unique descriptive
entry for each book in the source statement
library. The entries in the source
statement directory are used to locate and
retrieve books in the source statement
library.

A and E are used for the Assembler
sublibrary
C is used for the COBOL sublibrary
P is used for POWER in PL/I

MAINTENANCE FUNCTIONS
To request a maintenance function for
the source statement library, the following
control statement must be used:
// EXEC MAINT
Cataloging a Book -- Source Statement
Library

The sublib qualifier is required. If
omitted, the operand will be flagged as
invalid and no processing will be done on
the book.
library-name
represents the name of the book to be
cataloged. The library-name consists
of from one to eight alphanumeric
characters, the first of which must be
alphabetic. It is the name the
programmer uses to retrieve the book
when using the source language COpy
statement or BASIS card.
v.m
specifies the change level at which
the book is to be cataloged. v may be
any decimal number from 0 through 127;
~ may be any decimal· number from 0
through 255. If this operand is
omitted, a change level of 0.0 is
assumed. The v.m operand becomes part
of the entry in the directory for the
specified book. Its value is
incremented each time an update is
performed on the book.

The CATALS control statement is required
to add a book to a sublibrary of the source
statement library.
A book added to a sublibrary of the
source statement library is removed by
using the delete function.
When a book
exists in a sublibrary with the same name
as a book to be cataloged in that
sublibrary, the existing book in the
sublibrary is deleted. The following is
the format of the CATALS control statement:

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

IL _________________________________________
CATALS sublib.library-name[,v.m[,C]]
JI

indicates that change level
verification is required before
updates are accepted for this book.

See the UPDATE control statement,
discussed later in this chapter, for its
relationship to the v.m and C operands of
the CATALS control statement.
In addition to the CATALS control
statement, a control statement of the
following form must precede and follow the
book to be cataloged:

description of the Data Division or a
paragraph of the Procedure Division.
The following is an example of
cataloging a file description in the COBOL
sublibrary of the source statement library.

II JOB ANYNAME
II EXEC MAINT
CATALS C.PILEA
C.FILEA
BLOCK CONTAINS 13 RECORDS
RECORD CONTAINS 120 CHARACTERS
LABEL RECORDS AFE STANDARD
DATA RECORD IS RECA.
EKEND

BKEND [sublib.library-name],[SEQNCE],

B~END

[count],[C~PRSD]

All operand entries are optional.
When
used, the entries must be in the prescribed
order and need appear only in the oKEND
statement preceding the book to be
cataloged.
The first entry in the operand field is
identical to the operand of the CArALS
control statement.
SE:QNCE
specifies that columns 76 to 80 of the
card images constituting the book are
to be checked for ascending sequence
numbers. If an error is detected in
the sequence checking, an error message is printed.
The error can be
corrected, and the book can be
recataloged.
count
specifies the number of card images in
the book.
When the £QYni operand is
used, the card input is counted,
beginning with preceding E~END
statement and including the subseguent
BKEND statement.
If an error is
detected in the card count, an error
message is printed.
The error can be
corrected, and the book can be
reca taloged •
CMPRSD
indicates that the book to be
cataloged in the library is in
compressed format as a result of
CMPRSD having been specified when
performing a PUNCH or DSPCH service
function.
These functions are
described in the publication DOS/VS
~stem Control Statements.
Card input for the catalog function is
from the device assigned to SYSIPT. The
CATALS control statement is also read from
the device assigned to SYSIPT.

1&
Retrieving a Cataloged Book -- COBOL COPY
Statement:
The preceding file description
can be included in a COBOL source program
by writing the following statement:
FD PILEB COPY FILEA.
Note that the library entry does not
include PD or the file-name.
It begins
with the first clause that is actually to
follow the file-name.
This is true for all
options of the COpy statement.
Rowever,
data entries in the library may have a
level number t01 or 77) identical to the
level number of the data-name that precedes
the COpy statement.
In this case, all
information about the library data-name is
copied from th€ library and all references
to the l~brary data-name are replaced by
the data-name in the program if the
REPLACING option is specified. The change
is made only for this program. The entry
as it appears in the library remains
unchanged.
For example, assume the
following data entry is cataloged under the
library-name DATAR,
01

PAYFILE USAGE IS DISPLAY.
02 CALC PICTUKE 99.
02 GRADE PICTURE 9
OCCURS 1 DEPENDING ON CALC OF
PAYFILE.

and the following statement is written in a
COBOL source module:
01

GROSS COPY DATAR REPLA:ING PAYFILE
BY GROSS.

The compiler interprets this as:
Prequently used Environment Division,
Data Division, and Procedure Division
entries can be cataloged in the COBOL
sublibrary of the source statement library.
A book in the source statement library
might consist, for example, of a file

GROSS USAGE IS DISPLAY.
02 CALC PICTURE 99.
02 GRADE PICTURE 9
OCCURS 1 DEPENDING ON CALC OP
GROSS.
Librarian Functions

: .

Note also that the library-name is used
to identify the book in the library.
It
has no other use in the COBOL program.
Text cataloged in the source statement
library must conform to COBOL margin
restrictions.
The COBOL COpy statement is discussed in
detail in the section "Extended Source
Program Library Facility."

s.booki
provides a temporary update option.
The old book is renamed s.bookl and
the updated book is namea-----subliQ~ibra£y-name.
§. indicates the
sublibrary that contains the old,
renamed book.
It may be one of the
characters 0 through 9, A through Z,
#, $, or roo
If this operand is not
specified, the old book~is deleted.
v.m

Updatin~ks

represents the change level of the
book to be updated. y may be any
decimal number from 0 through 127; ~
may be any decimal number from 0
through 255.
This operand must be
present if change level verification
is to be performed.
U~e of the
optional entry C in the CATALS control
statement at the time the book is
cataloged in the library determines
whether change level verification is
reouired before updating.
If the
directory entry specifies that change
level verification is not required
before updating, the change level
operand in the UPDATE control
statement is ignored.

-- Source Statement Libra£y

The update function is used to make
changes to properly identified statements
within a book in the source statement
library. Statements are identified in the
identification field, columns 73 through
80, which is fixed in format as follows:
Columns 73-76

Program identification
which must be constant
throughout the book.

Columns 77-80

Sequence number of the
statement within the
book.

If the change level is verified, the
_change level in the book's directory
entry is increased by 1 by the system
for verification of the next update.
If ~ is at its maximum value and an
update is processed, m is reset to 0
and the value of y is increased by 1.
If both v and m are at their maximum
values and an update is processed,
both v and m are reset to O.

One or more source statements may be
added to, deleted from, or replaced in a
book in the library without the necessity
of replacing the entire book. The update
function also provides these facilities:
1.

Resequencing statements within a book
in the source statement library

Changing the
book

Adding or removing the change level
requirement

Copyin~ a book with optional retention
of the old book with a new name (for
backup purposes)

chan~e

level

(v.m)

of the
nn

The UPDATE control staterntnt is used for
the update function and has the following
format:

,
UPDATE sublib.library-name,[s.book1],1
[v.m],[nn]
I
---l

The operation field contains UPDATF.
sublib
represents the sublibrary that
contains the book to be updated.
It
may be any of the characters 0 through
9, A through Z, #, $, or ~.
50

represents the resequencing status
required for the update.
nn may be a
1- or 2-cha~acter decimal number from
1 through .0, or it may be the word
NO.
If nn is a decimal number, it
represents the increment that will be
used in reseguoncing the statements in
the book.
If nn is NO, the statements
will not be resequenced.
If nn is not
specified, the statements will be
resequenced with an increment of 1.
When a book is resequenced, the
sequence number of thefirst statement
is 0000.
For example, if a buok is
cataloged in the source statement
library with sequence numbErs ranging
from 0010 through 1001 with increments
of 5 for each statement:
and rrll is not specified when the
update function is performEd, the book
is resequenced with numbers 0000,
0001, 0002, ••• etc.

and NO is specified, insertions,
deletions, and/or replacements are
made with no effect on the original
sequence numbers.
and ~ is specified as 2, the book is
resequenced with numbers 0000, 0002,
0004, ••• etc., regardless of the
original sequencing of the book in the
library or the sequence numbers of the
added or replacement cards.
The UPDATE control statement is followed
by ADD, DEL (delete), and/or REP (replace)
control statements as required, followed by
the terminating END statement. The ADD,
DEL, REP, and END statements are identified
as update control statements by a right
parenthesis in the first position (column 1
in card format). This is a variation from
the general librarian control statement
format; thus, it clearly identifies these
control statements as part of the update
function.
ADD statement: The ADD statement is used
for the addition of source statements to a
book. The format is:

REP Statement: The REP statement is used
when replacement of source statements is
reguired in a book. The format is:
) REP first-seq-no[,last-seg-no]
REP indicates that source statements
following this statement are to replace
existing statements in a book.
first-seq-no
last-seg-no
represent the sequence numbers of the
first and last statements of a section
to be replaced. Each number may be a
decimal ;umber consisting of from one
to four characters. Any number of new
statements can be added to a book when
(The number of
a section is replaced.
statements added need not equal the
number of statements being replaced.)
Seguence number 9999 is the highest
number acceptable for a statement to be
updated. If the book is so large that
statement sequence numbers have "wrapped
around" (progressed from 9998, 9999, to
0000,0001), it will not be possible to
update statements 0000 and 0001.

) ADD seq-no
END Statement: This statement indicates
the end of updates for a given book. The
format is:
ADD indicates that source statements
following this statement are to be added to
the book.
seq-no
represents the sequence number of the
statement in the book after which the
new statements are to be added. It
may be any decimal number consisting
of from one to four characters.

) EN D [v. m[ , C ]

]

v.m
represents the change level to be
assigned to the book after it is
updated; y may be any decimal number
from 0 through 121. ~ may be any
decimal number from 0 through 255.
This operand provides an additional
means of specifying the change level
of a book in the library.
(The other
method is through the use of the ~
operand in the CATALS statement.)

DEL Statement: The DEL statement causes
the deletion of source statements from the
book. The format is:
DEL first-seq-no[ ,last-seq-no]
C

DEL indicates that statements are to be
deleted from the book.
first-seq-no
last-seq-no
represent the sequence numbers of the
first and last statements of a section
to be deleted. Each number may be a
decimal number consisting of from one
to four characters. If last-seg-no is
not specified, the statement
represented by first-seg-no is the
only statement deleted.

indicates that change level
verification is required before any
subsequent updates for a given book.·
If ~ is specified and £ is omitted,
the book does not require change level
verification before a subsequent update.
This feature removes a previously specified
verification requirement for a particular
book.
If both optional operands are omitted,
the change level in the book's directory
entry is increased as a result of the
Librarian Functions

update, and the verification requirement
remains unchanged.

ADD, DEL, or REP Statements:
1.

If there is an invalid operation or
operand in an ADD, DEL, or REP
statement, the statement is flagged,
the book is not updated, and the
remaining control statements are
checked to determine their validity.
All options of the UPDATE and END
statements are ignored.

The second operand must be greater
than the first operand in a DEL or REP
statement. If not, the statement is
considered invalid and is flagged, the
book is not upd~ted, and the remaining
control statements are checked to
determine their validity. All options
of the UPDATE and END statements are
ignored.

All updates to a book between an
UPDATE statement and an END statement
must be in ascending sequential order
of statement sequence numbers. The
first operand of a DEL or REP
statement must be greater than the
last operand of the preceding control
statement. The operand of an ADD
statement must be equal to or greater
than the last operand of the preceding
control statement. Consecutive ADD
statements must not have the same
operand. If these conditions are not
met, the default is the same as for
items 1 and 2.

control statement Placement: Control
statement input for the update function,
read from the device assigned to SYSIN,
must be in the following order:
1.

The JOB control statement.

The ASSGN control statements, if the
current assignments are not those
required. The ASSGN control
statements that can be used are SYSIN,
SYSLST, and SYSLOG.

The EXEC MAINT control statement.

The UPDATE control statement.

) ADD, ) DEL, or ) REP statements with
appropriate source statements.

) END statement.

The /* control statement.

The /& control statement, which is the
last control statement of the job.

The source statement library can also be
updated by using the DELETE and INSERT
cards. These are discussed in "Extended
Source Program Library Facility" in this
chapter, and in the publication IBM DOS
Full American National Standard COBOL.

UPDATE Function -- Invalid Operand Defaults

END Statement: If the first operand of the
END statement is invalid, the statement is
flagged, both operands are ignored, and the
book is updated as though no operands were
specified. If the second operand is
invalid, the statement is flagged, the
operand is ignored, and the book is updated
as though the second operand were not
specified.

UPDATE Statement:
1.

If the first or second operand is
invalid, the statement is flagged, the
book is not updated, and the remaining
control statements are checked to
determine their validity.

If change level verification is
required and the incorrect change
level is specified, the statement is
flagged, the book is not updated, and
the remaining control statements are
checked to determine their validity.

If the resequencing operand is
invalid, resequencing is done in
increments of 1.

Out-oi-Sequence Updates: If the source
statements to be added to a book are not in
sequence or do not contain sequence
numbers, the book is updated, and a message
indicating the error appears following the
END statement. If the resequencing option
has been specified in the UPDATE statement,
the book is sequenced by the specified
value, and subsequent updating is possible.
If the resequencing option is not
specified, the book is resequenced in
increments of 1, and subsequent updating
viII be possible. If the resequencing
option NO is specified, the book will be
out of sequence, and subsequent updating
may not be possible.

The Procedure Library
The procedure library is a new system
library that may be used to store -- in
card image format -• Frequently used sets w procedures, of
job control and linkage editor
statements (basic support).
• Procedures additionally containing
inline SYSIPT data, especially control
statements for system utility and
service programs (extended support).
The inline SYSIPT data must be
processed under control of the
device-independent sequential IOCS or
by IBM-supplied service programs and
language translators.
The procedure library is part of SYSRES,
so the maintenance and service functions
available for the other DOS/VS libraries
will also support the procedure library.
Cataloged procedures may be included in
the job control input stream by a job
control statement and temporarily modified
by overwrite statements. For more details
on cataloged procedures, see DOS/vS System
Control statements.

MAINT, PROCEDURE LIBRARY
To request a maintenance function for
the procedure library. use the following
EXEC control statement:

statement Format:
CATALP procedurename[,VM=v.m] [,EOP=yy]
NO
,DATA=YES
Each control statement in the procedure
library should have a unique identity •
This identity is required to modify the job
stream at execution time. Therefore, when
cataloging, identify each control statement
in columns 73-79 (blanks may be embedded) •
........ __ ..... ,....,.rl" ....... " ...... ~'I"Y'\.C't.
~L v\",~'Ir.A

u.,L

~.I..IU..ul-.;;::::

represents the name of the procedure
to be cataloged. The procedurename
consists of one to eight alphameric
characters, the first of which must be
alphabetic. It must not be ALL.
VM=v.m
specifies the change level at which
the procedure is to be cataloged. v
may be any decimal number from 0-127.
m may be any decimal number from
0-255. If this operand is omitted, a
change level of 0.0 is assumed.
A change level can be assigned only
when a procedure is cataloged. The
change level is displayed and punched
by the service functions.
EOP=yy
specifies a two-character
end-of-procedure delimiter. The EOP
parameter can be any combination of
characters except /*, /&, //; it must
not contain a blank or a comma. The
system assumes /+ as default
end-of-procedure delimiter. Otherwise
you can omit the EOP parameter.

// EXEC MAINT
One or more of the maintenance functions
(catalog, delete, rename, condense, set
condense limit, or reallocate) can be
requested within a single run. Any number
of procedures within the procedure library
can be acted upon in this run. Further &
one or more of the maintenance functions
for either of the other three libraries
(core image, source statement, or
relocatable) can be requested within this
run, for the same MAINT program maintains
all four libraries.

Catalog
The control statement required to add a
procedure to the procedure library is the
CATALP statement. Any number of procedures
may be cataloged in a single run. Each
procedure must immediately follow the
respective CATALP statement.

DATA=YES
specifies that a procedure contains
SYSIPT inline data.
These procedures can only be executed
in the extended procedure support.
A procedure to be cataloged into the
procedure library may consist of Job
Control and linkage editor statements and,
if the supervisor was generated with the
SYSFIL option, additional control
statements for IBM-supplied control and
service programs and data processed under
control of the device-independent
sequential IOCS. 'The end of a procedure is
indicated by the /+ end-of-procedure
delimiter or by the end-of-procedure
delimiter as specified in the EOP
parameter.
If SYSIN is assigned to a tape unit, the
MAINT program assumes that the tape is
positioned to the first input record. The
tape is not rewound at the end of job.
Librarian Functions

Control statement input for the catalog
function, read from the properly assigned
device (usually SYSIN), is:
1.

the JOB control statement, followed by

the ASSGN control statements, if the
current assignments are not those
required. The ASSGN statements that
can be used are SYSIN, SYSLST, and
SYSLOG. The ASSGN statements are
followed by

the EXEC MAINT control statement,
followed by

the CATALP control statement(s),
followed by

the module to be cataloged, followed
by

the /* control statement if other job
steps are to follow, or

EXEC statement. Conversely, if the
JOB statement is not cataloged, a JOB
statement must precede the EXEC
statement that retrieves the
procedure.

A cataloged procedure must not include
any of the following control
statements because they are not
accepted when the procedure is
processed:
ASSGN
RESET
RESET
RESET
CLOSE
ASSGN
/ / RESET

//
//
//
//
//

[//

SYSRDR,X'cuu'
SYS
ALL
SYSRDR
SYSRDR,X'cuu'

SYSIPT.x.cuu']

SYSIPT

only if SYSIPT
data is
included

/ / CLOSE SYSIPT,X'cuu·

the /& control statement, which is the
last control statement of the job.

For example:
// JOB CATPROC
ASSGN control statements,
if required

cataloged procedures cannot be nested,
that is, a cataloged procedure cannot
contain an EXEC statement that invokes
another cataloged procedure.

Note: Maintenance cannot be performed in
the background partition on the procedure
library while a foreground partition is
using the library.

PSERV, PROCEDURE LIBRARY

,
// EXEC MAINT
CATALP PROCA,EOP=AA,DATA=YES
control statements
SY3IPT inline data
/* END OF SYSIPT DATA

To request a service function for the
procedure library, use the following EXEC
control statement:
// EXEC PSERV
One or
functions
run. Any
procedure
run.

more of the three service
can be requested within a single
number of procedures within the
library can be acted upon in this

control statements
CALLING CATALOGED PROCEDURES
AA END OF PROCEDURE
The following restrictions apply when
you catalog procedures to the procedure
library:
1.

A cataloged procedure cannot contain
control statements or SYSIPT data for
more than one job.
If the cataloged control statements
include the JOB statement, you must
not have a JOB statement when you
retrieve the procedure through the

A cataloged procedure is called by a job
that appears in the input stream or via an
operator command. The job must consist of
a JOB statement and an EXEC statement that
specifies the cataloged procedure name.
For example:
// EXEC

PROC=VCOBCLG

The programmer can write cataloged
procedures which incorporate job control he
used frequently.
For example, the
programmer may wish to catalog a procedure

for compiling, link-editing, and executing
a program. It is particularly useful for
compiling in a low-priority test partition
to which no card reader has been assigned.
Using cataloged procedures, the operator
can execute via the EXEC statement a
cataloged procedure from the console.

PRIVATE LIBRARIES
Private libraries are desirable in the
system to permit some libraries to be
located on a disk pack other than the one
used by SYSRES.
Private libraries are supported for the
core image library, the relocatable
library, and the source statement library,
on the 2311, 2314, 2319, 3330, 3340, fixed
block devices, and mass storage devices.
However, the following restrictions apply:
1.

The private library must be on the
same type of disk device as SYSRES;
the private core-image library can be
on a type of device other than the one
SYSRES is on.

Reference may be made to a private
core image library only if SYSCLB is
assigned.
If SYSCLB is assigned, the
system core image library cannot be
changed.

Reference may be made to a private
relocatable library only if SYSRLB J.S
assigned.
If SYSRLB is assigned, the
system relocatable library cannot be
changed.

Reference may be made to a private
source statement library only if
SYSSLB is assigned. If SYSSLB is
assigned, the system source statement
library cannot be changed.

Private libraries cannot be
reallocated.

The COPY function is not effective for
private libraries except when they are
being created.

An unlimited nurrber of private libraries
is possible. However, each must be
distinguished by a unique file
identification in the DLBL statement for
the library. No more than one private
relocatable library and one private source
statement library may be assigned in a
given job.
The creation and maintenance of private
libraries is discussed in the publication
DOS/vS System Control Statements.

Determininq the Location of the Libraries
Having decided which libraries you want
in your system, you must determine where on
the available devices these libraries are
to be placed. All system libraries must
reside in the SYSRES extent of the systew
disk pack in a predefined sequence (Figure

~~·ha~!t~~~~~t;tlt~r!~~~~e~~c~~!Ys~~~:!.ble
pack (outside the SYSRES extent), this is
not recommended because it involves
increased movement of the disk arm.

Librarian Functions

Page of SC28-6478-0, revised 3/22/74 by TNL:

SN28-1063

....- end of SYSRES extent

Figure

The Relative Location of the Four System Libraries

The directory area for each library is
not shown in the Figure 7.
By definition,
all system libraries reside on the system
residence file (SYSRES).
If you have
additional disk drives, you can define
private core image, relocatable, and/or
source statement libraries on the extra
volumes. These volumes must be of the same
type as the SYSRES pack. The system
relocatable and system source statement
libraries can be removed from SYSRES and
established as private libraries; the
system core image library, however, must
always be present on SYSRES. It can be
supplemented but not replaced by a private
core image library. The procedure library
is supported only as a system library; you
cannot create a private procedure library.

SOURCE LANGUAGE CONSIDERATIONS
To use the private source statement
library for COPY, BASIS, INSERT, and
DELETE(see "Extended Source Program Library
Facility" for further details), the ASSGN,
DLBL, and EXTENT control state~ents that
define this private library must be present
in the job deck for compilation (unless
they are permanently set up by the
installation). When present, a search for
the book is ~ade in the private library.
If it is not there, the system library is
searched. If the state~ents for the
private library are not present, the system
library is searched. A prograrrmer may
create several private libraries, but only
one private library can be used in a given
job.

EXTENDED SOURCE PROGRAM LIBRARY FACILITY
A complete program may be included as an
entry in the source statement library by
using the catalog function. This program
can then be retrieved by a BASIS card and
compiled in a sUbsequent job.
The following control statements would
be used to catalog the program SAMPLE as a
book in the COBOL sublibrary of the source
statement library:
// JOB CATALOG
// EXEC MAINT
CATALS C.SAMPLE
BKEND C.SAMPLE

from the source statement library. The
name of the program is PAYROLL. During a
particular year, the old age insurance tax
(FICA) is deducted at the rate of 4-2/5%
each week for all personnel until earnings
exceed $7800. The coding to accomplish
this is shown in Figure 8.
Now, however, due to a change
age tax laws, tax is to be taken
earnings exceed $10800 and a new
is to be placed. The programmer
these changes as shown in Figure

in the old
out until
percentage
can code
9.

The altered program will contain the
coding shown in Figure 10.

{source program}
Reformatted Source Deck
BKEND
/*
/&

When compiling a program that has been
cataloged in the COBOL sublibrary of the
source statement library, a BASIS card
brings in an entire source program. The
following control statements could be used
to compile the cataloged program SAMPLE:
// JOB PGM1
// OPTION LOG,DECK,LIST,LISTX,ERRS
// EXEC FCOBOL
CBL LIB
BASIS SAMPLE

By specifying the DECK option on the LST
card, a new COBOL source deck can be
produced that reflects the reformatted
source listing. This deck may be saved in
a BASIS library, used directly as input to
the compiler, or punched onto cards.
Because of reformatting, the new deck may
contain more cards than the original, but
the difference is not great enough to cause
any appreciable increase in compilation
time. The. output deck differs from the
listing as follows:
1.

References, footnotes, and blank lines
are omitted.

Literals will be repositioned, if
needed, to assure proper continuation.

Statement numbers are converted to
card numbers.

/*
/&

INSERT or DELETE cards may follow the
BASIS card if the user wishes to modify the
book SAMPLE before it is processed by the
compiler. The original source program must
have been coded with sequence numbers in
columns 1 through 6 of each source card.
The INSERT statement will add new source
statements after the specified sequence
numbers. The DELETE statement will delete
the statements indicated by the sequence
numbers, or will delete more than one
statement when the first and last sequence
numbers to be deleted are specified,
separated by a hyphen. Source program
cards may follow a DELETE card for
insertion before the card following the
last one deleted. The sequence numbers in
columns 1 through 6 are used to update
COBOL source statements at compilation
time, and are in effect for the one run
only.
Assume that a company runs its payroll
program each week as a source program taken

The statement number is multiplied
by 10, and leading zeros are added
as necessary to fill columns 1
through 6.

Comment and continuation cards are
numbered one higher than the
preceding card.

Statement-beginning cards are
given the higher of the two
numbers produced by the first two
rules,.

The use of this feature avoids having to
resequence cards for permanent updating
after they have been tested by temporary
updating using the BASIS feature; it also
avoids the errors incurred during that
resequencing process.

Librarian Functions

r---------------------------------------------------------------------------------------,
IF ANNUAL-PAY GREATER THAN 7800 GO TO PAY-WRITE.
1

1000730
1000735
1000740
1000745
1000750
1000755
I

FICA-PAYR.
PAY-WRITE.

IF ANNUAL-PAY GREATER THAN 7800 - BASE-PAY GO TO LAST-FICA.
COMPUTE FICA-PAY = BASE-PAY * .044
MOVE TAX-PAY TO OUTPUT-TAX.
MOVE BASE-PAY TO OUTPUT-EASE.
ADD BASE-PAY TO ANNUAL-PAY.

I
I
I
I

1
1
1000850
STOP RUN.
L_______________________________________________________________________________________
JI
Figure

Sample Coding to Calculate FICA

r-------------------------------------~-------------------------------------------------,

1// JOB PGM2
1// OPTION LOGrDECK,LIST,LISTX,ERRS
1// EXEC FCOBOL
I CBL QUOTE, LIB

IBASIS PAYROLL
IDELETE 000730-000740
1000730
IF ANNUAL-PAY GREATER THAN 10800 GO TO PAY-WRITE.
1000735
IF ANNUAL-PAY GREATER THAN 10800 - BASE-PAY GO Tu LAST-T'AX.
1000740 TAX-PAYR. COMPUTE TAX-PAY = BASE-PAY * .0585

I
I
I
I
I
1

I
I

L _______________________________________________________________________________________ J1
1/*

Figure

Altering a Program from the Source Statement Library Using INSER'I' and DELETE
Cards

r---------------------------------------------------------------------------------------,
IF ANNUAL-PAY GREATER THAN 10800 GO TO PAY-WRITE.
1

1000730
1000735
1000740 TAX-PAYR.
1000750
1000760 PAY-WRITE.
1000770

IF ANNUAL-PAY GREATER THAN 10800 - BASE-PAY GO TO LAST-TAX.
COMPUTE TAX-PAY = BASE-PAY* .0585.
MOVE TAX-PAY TO OUTPUT-TAX.
MOVE BASE-PAY TO OUTPUT-BASE.
ADD BASE-PAY TO ANNUAL-PAY.

1
1

I
I

1000850
STOP RUN.
L _______________________________________________________________________________________
JI
Figure 10.

Effect of INSERT and DELETE Cards

INTERPRETING OUTPUT

The DOS/VS COBOL compiler, COBOL object
module, Linkage Editor, and other system
components can produce output in the form
of printed listings, punched card decks,
diagnostic or informative messages, and
data files directed to tape or to mass
storage devices. This chapter gives the
format of and describes this output. The
same COBOL program is used for each
example.
"Appendix A:
Sample Program
Output" shows the output formats in the
context of a complete listing generated by
the sample program.
COMPILER OUTPUT
The output of the compilation job step
may include:
• A printed listing of the job control
statements
• A printed listing of the statements
contained in the source program
• A glossary of compiler-generated
information about data
• Global tables, register assignments,
and literal pools

printed listing of the object code

• A condensed listing containing only the
relative address of the first generated
instruction for each verb
• Compiler statistics

The level of diagnostic message printed
depends upon the FLAGW or FLAGE option of
the CBL card.

All output to be listed is written on
the device assigned to SYSLST. If SYSLST
is assigned to a magnetic tape, COBOL will
treat the file as an unlabelled tape. Line
spacing of the source listing is controlled
by the SPACEn option of the CBL card and by
SKIP 1/2/3 and EJECT in the COBOL source
program.
(The lister feature ignores these
commands.) The number of lines per page
can be specified in the SET corrmand.
In
addition, a listing of input/output
assignments can be printed on SYSLST by
using the LISTIO control staterr.ent,.
On each page of the output, there is a
header which contains the PROGRAM-ID, date
and time of compilation~ as well as an
indication of the modification level of the
compiler which produced this listing.
Figure 11 contains the compiler output
listing shown in "Appendix A:
Sample
Program Output." Each type of output is
numbered, and each format within each type
is lettered. The text below and that
following the figure is an ex~lanation of
the figure.
The listinq of the job control
statements associated with this job
step. These statements are listed
because the LOG option was specified
at system generation time.

• Compiler diagnostic messages
• Cross-reference listings

Compiler options. The CEL card, if
specified, is printed on SYSLST unless
the LIST option is suppressed.

• System messages
• An object module
• FIPS diagnostic messages
The presence or absence of the
above-mentioned types of compiler output is
determined by options specified at system
generation time. These options can be
overridden or additional options specified
at compilation time by using the OPTION
control statement and the CBL card.

The source module listing. The
statements in the source program are
listed exactly as submitted except
that a compiler-generated card number
is listed to the left of each line.
This is the number referenced in
diagnostic messages and in the object
code listing. It is also the number
printed on SYSLST as a result of the
source language TRACE statement (if
NOVERB is in effect). The source
module is not listed when the NOLIST
option is specified.

Interpreting Output

/ / JOE SAMPLE

'// OFTIOil NODECK,L,INK,LIS'I,LI13'IX,SYM,ERRS

,II (':"1)

// EXEC FCOBOL

IBM DOS VS COBOL

REL l.Q

PP NO. 5746-CB1

(!)

CEL QUOTE,OP'I,SXREF,LVL=A
00001
000010 IDENTIFICATION DIVISION.
00002
00002,0 PROGRAM-ID. TES'IRUN.
AUTHOR. PROGRAMMER NAME.,
C0003
CC004
INSTALLATION. NEW YORK DEVEIOFMENT CEN'IER
00005
DATE-wRI'ITEN. FEBRUARY IS, 1974
00006
DATE-COMPILED. 03/u3/74'00007
REMARKS. THIS PROGRAM HAS BEEN WRITTEN AS A SAMPLE PROGRAM FOR
C0008
COBOL USERS. IT CREAT~S AN OUTPUT FILE AND READS IT BACK
C0009
AS INPUT.
00010
000100
00011
000110 ENVIRONMENT DIVISION.
00012
000120 CONFIGURATION SECTION.
00013
000130 SOURCE-COMPUTER. IBM-370.
00014
000140 OBJECT-COMPUTER. IBM-310:
00015
000150 INPUT-OUTPUT SECTION.
00016
000160 FILE-CONTROL.
000110
00011
SELECT FILE-l ASSIGN TO SYSOOS-UT-2400-S.
00018
000180
SELECT FILE-2 ASSIGN TO SYS008-UT-2400-S.
n0019
000190

00056
C0051
00058
00059
C0060

000550 PROCEDURE DIVISION.
BEGIN.
000570
NOTE THAT THE FOLLOWING OPENS THE OUTPUT FILE TO BE CREATED
000580
AND INITIALIZES COUNTERS,
000590 STEP-1. OPEN OUTPUT FILE-l. MOVE ZERO TO KOUNT, .mMBR.

C0013
C0014
00015
C0016
00017
00078
00019
00080

000720
000130
000140
000750
000160
000170
000180
000190

Figure II.

STEP-5. CLOSE FILE-l. OPEN IN.
NOTE THAT THE FOLLOWING REAU~ ~ACK THE FILE AND SINGLES
OUT EMPLOYEES WITH NO DEPENDENTS.
STEP-6. READ FILE-2 RECORD IN'IO wORK-RECORD AT END GO TO STEP-So
STEP-1. IF NO-OF-DEPENDENTS IS EQUAL TO ·0· MOVE ·Z· TO
NO-OF-DEPENDENTS. EXHIBI'I NA~ED WORK-RECORD. GO TO STEP-6.
STEP-So CLOSE FILE-2.
STOP RUN.

A\
1
f"l"+-"",,,+- (Part 1 of ....,
Examples of f"nmn;
--....1:'------1:'-CT

07.43.04

03/0}/74

.REt 1.0

IBM DOS VS COBOL

INTRN~NAME ~
DNM=1-1118
DNM=1-179
DNM=1-200
DNM=1-217
DNM=1-2118
DNM=1-269
DNM=1-289
DNM=1-308
DNM=1-323
DNl'.=1-341
DNM=1-359
DNM=1-3711
DNM=1-3911
DNM=1-410
DNM=1-11311
DNM=1-454
DNM=1-473
DNM=l-1192
DNM=2-000
DNM=2-01B
DNM=2-037
DNM=2-063

SOURCE

HAC[{

BASE

FD
01
02
FD
01
02
01
02
02
02
02
02
02
01
02
02
02
02
02

FILE-l
RECORD-l
FIELD-A
FILE-2
RECORD-2
FIELIl-A
FILLER
KOUNT
ALPHABET
ALPHA
NUMBR
DEPENDENTS
DEPEND
WORK-RECORD
NAME-FIELD
FILLER
RECORD-NO
FILLER
LOCATION

FI!.!.ER

02
02

NO-OF-DEPENDENTS
FILLER

DTF=Ol
BL=l
BL=l
DTF=02
8L=2
BL=2
IlL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3

07.43.04

PP NO. 5746-CBl

DISPL

000
000
000
000
000
000
002
002
01C
OlE

OU
038
038
039
03A
03E
03F
0112
043
0115

INTRNL NAME

DNM=I-1118
DNM=1-179
DNM=1-200
DNM=1-217
DNM=1-248
DNM=1-269
DNM=1-289
DNf'=1-308
DNM=1-323
DNM=1-3111
DNM=1-359
DNM=1-3711
DNM=1-394
DNM=I-410
DNM=1-434
DNM=1-4511
DNM=1-473
DNM=1-1192
DNM=2-000
DNM=2-018
DNM=2-037
DNM=2-063

DEFINITION

DS OCL2C
DS 20C
DS
DS
DS
DS
DS
DS
OS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS

OCL20
20C
OCL56
IE
26C
lC
lE
2bC
lC
OCL20
lC
lC
4C
lC
3C
lC
2C
7C

10/03/73

@
uSAGE

DTFMT
GROUP
DISP
DTF!>.T
GROUP
DISP
GROUP
COMP
DISP
DISP
COOP
DISP
DISP
GROUP
DISP
DISP
DISP-ill'.
DISP
DISP
DISP
IHSP
DIEF

o
!;;

MEMORY MAP

TGT

SAVE; Al DIAGNOSTIC MESSAGES

r."'ILINE~MBER
A
B

~COOO

00025
00034
C0054
C0060
C0062
C0062
C0064
00064
00068
C0068
C0068
C0070
C0076
C0078

I'-'

I
8003I-W
ILA8002I-W
ILA8002I-W
ILA8003I-W
ILA8003I-W
ILA8003I-W
ILA8003I-W
ILA8003I-W
ILA8003I-W
ILA8003I-W
ILA8002I-W
ILA8003I-W
ILA8003I-W
ILA8003I-W
ILA8002I-W

(!)

PAGE,

DATE-COMPILED PARAGRAPH IS AN EXTENSION TO i'IPS LEVEL A.
RECORDING MODE IS CLAUSE IS AN EXTENSION TO ALL FIPS LEVELS.
RECORDING MODE IS CLAUSE IS AN EXTENSION TO ALL FIPS LEVELS.
SPACES IS AN EX'IENSION TO FIPS LiVEL A.
COMMA OR SEMICOLON AS PUNCTUATION IS AN EXTENSION TO FIPS LEVEL A.
COMMA OR SEMICOLON AS PUNC'IUATION IS AN EXTBNSION TO FIPS LEVEL A.
COMMA OR SEMICOLON AS PU~CTUATION IS AN EXTENSION TO FIPS LEVEL A.
COMMA OR SEMICOLON AS PUNC'IUATION IS AN EXTENSION TO FIPS LiVEL A.
MULTIPLE RESULTS IN ADD STATEMENT IS AN EXTENSION TO FIPS k'"'VEL A.
UPON OP'IION OF DISPLAY STA'IEMENT IS AN EX'IENSION TO FIPS LEVEL A.
UPON CONSOLE OPTION OF DISPLAY S'IATEMEN'I' IS AN EXTENSION TO ALL LEVELS.
FROM OP'IION OF WRITE S'IATE~ENT IS AN EXTENSION TO FIPS LEVEL A.
UNTIL OPTION OF PERFORM S'IA'IEMEN'I IS AN EX'IENSION TO FIPS LEVEL A.
INTO OP'IION OF READ STATEMENT IS AN EXTENSION TO PIPS LEVEL A.
EXHIBI'I STATEMENT IS AN EX'IENSION 'IO ALL FIPS LEVELS.

END OF COMPILATION

Figure 11 ..

Examples of Compiler Output (Part 4 of 4)

Interpreting Output

The following notations roay appear on
the listing:

TER.COD

Used by coding for
TERMINATE clause.

Denotes that the statement was inserted
with a COpy statement.

FRS.GEN

Used by coding for
GENERATE clause.

Denotes that the card is out of
sequence. NOSEQ should be specified on
the CBL card if the sequence check is
to be suppressed.

-nnnn

Generated report record
associated with the file
on which the report is
to be printed,.

Denotes that the card was inserted with
an INSERT or BASIS card.

RPT.RCD

Build area for print
record ..

If DATE-COMPILED is specified in the
Identification Division, any sentences in
that paragraph are replaced in the listing
by the date of compilation. It is printed
in one of the following formats depending
upon the format chosen at system generation
time.

CTL_CHR

First or second position
of RPT.RCD. Used for
carriage control
character.

RPT.LIN

Beginning of actual
information which will
be displayed. Second or
third position of
RPT,.RCD.

CODECELL

Used to hold code
specified.

E.nnnn

Name generated from
COLUMN clause in
02-level statement.

S.nnnn

Used for elementary
level with SUM clause,
but not with data-name.

N.nnnn

Used to save the total
number of lines used by
a report group when
relative line numbering
is specified.

DATE-COMPILED.

month/day/year

DATE-COMPILED.

day/month/year

Glossary. The glossary is listed
when the SYM option is specified.
The glossary contains information
about names in the COBOL source
program.

® and(!)
The internal-name
generated by the compiler.
This name is used in the
compiler object code listing
to represent the name used in
the source program. It is
repeated in column F for
readability.
A normalized level number.
This level number is
determined by the compiler as
follows: the first level
number of any hierarchy is
always 01, and increments for
other levels are always by
one. Only level numbers 03
through 49 are affected;
level numbers 66, 77, and 88,
and FD, SD, and RD indicators
are not changed.

The data-name that is used in
the source module.

Note: The following Report Writer
internally-generated data-names
can appear under the SOURCE NAME
column:

CTL.LVL

Used to coordinate
control break
activities.

GRP.IND

Used by coding for GROUP
INDICATE clause.

@ and(§}

For data-names, these columns
contain information about the
address in the form of a base and
displacement. For file-names., the
column contains information about
the associated DTF or FIB (for
VSAM). An indication is also
given here if the FD is invalid.

This column defines storage for
each data item. It is represented
in assembler-like terminology.
Table 4 refers to information in
this column.
Usage of the data-name. For FD
entries, either VSAM is specified,
or the DTF type is identified
(e.g., DTFDA). For group items
containing a JSAGE clause, the
usage type is printede For group
items that do not contain a USAGE
clause~ GROUP is printed.
For
elementary items, the information
in the USAGE clause is printed.

Table

Glossary Definition and Usage

r----------------------------T-----------------------T----------------------------------,

Type

Definition

Usage

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

Group Fixed-Length
Alphabetic
Alphanumeric
Alphanumeric Edited
Numeric Edited
Index-Name
Group Variable-Length
Sterling Report
External Decimal
External Floating-Point
Internal Floating-point

I
I
I
I

Binary
Internal Decimal
Sterling Non-Report
Index-Name
File (FD)
Condition (88)
Report Definition (RD)
Sort Definition (SD)

DS OCLN
I
DS NC
I
DS NC
I
DS NC
I
DS NC
1
DS lH
I
DS VLI=N
I
DS NC
I
DS NC
I
DS NC
!
DS iF
I
DS lD
I
DS IH, IF, OR 2 F !
DS NP
I
DS NC
I
BLANK
I
BLANK
I
BLANK
I
BLANK
I
BLANK
I

I
I
I
I
I
I
I
I
I

GROUP
DISP
DISP
AN-EDIT
NM- EDIT
INDEX-NM
GROUP
RPT-ST
DISP-NM
DISP-FP
COMP-l
COMP-2
COMP
COMP-3
DISP-ST
INDEX-NAME
DTF TYPE
BLANK
BLANK
BLANK

~----------------------------~-----------------------~----------------------------------~

INote: Under the definition column, N = size in bytes, except in group variacle-Iength I
Iwhere
it is a variable cell number.
L
_______________________________________________________________________________________
JI

A letter under column:
R - Indicates that the data-name
redefines another data-name.

o -

Indicates that an OCCURS
clause has been specified for
that data-name.

Q - Indicates that the data-name
is or contains the DEPENDING
ON object of the OCCURS
clause.

encountered, or CSYNTAX is specified
and an E-Ievel error is encountered.
A global table contains easily
addressable information needed by the
object program for execution. For
example, in the Procedure Division
output coding (3), the address of the
first instruction under STEP-l (OPEN
OUTPUT FILE-i) is found in the
PROCEDURE NAME CELLS portion of the
Program Global Table (PGT).
The Task Global Table (TGT). This
table is used to record and save
information needed during the
execution of the object program.
This information includes
switches, addresses, and work
areas.

M - Indicates the record format.
This field is not applicable
to VSAM. The letters which
may appear under column Mare:
F - fixed-length records
U - undefined records
V - variable-length records

s - spanned records
The location and length of WORKINGSTORAGE are noted here when CLIST,
SYM or LSTX is specified, except under
the same conditions as noted below.
Global tables and literal pool:
Global tables and the literal pool are
listed when the CLIST, SYM, or LISTX
option is specified, unless SUPMAP is
specified and an E-Ievel error is

The Literal pool. This lists all
literals used in the program, with
duplications removed. These
literals include those specified
by the programmer (e. g •., MOVE
"ABC" TO DATA-NAME) and those
generated by the compiler (e.g.,
to align decimal points in
arithmetic computations). The
literals are divided into two
groups: those that are referenced
by instructions (marked "LITERAL
POOL") and those that are
parameters to the display object
time subroutine (marked "DISPLAY
LITERALS").

Interpreting Output

The Proqram Global Table (PGT).
This table contains literals and
the addresses of procedure-names,
generated procedure-names, and
procedure block locators
referenced by Procedure Division
instructions.

Register assignment: This lists the
permanent register assigned to each
base locator in the object program.
The remaining base locators are given
temporary register assignments but are
not listed. Register assignments are
listed when CLIST, SYM, or LISTX is
specified, and output is not overridden
by the same conditions as above.
Procedure block assignments:
Procedure block assignments are
printed when OPT is specified. The
procedure block assignments give the
location within the object program for
each block of code addressed by
register 11.
Object code listing. The object code
listing is p~oduced when the LISTX
option is specified, unless SUPMAP is
also specified and an E-Ievel error is
encountered, or unless CSYNTAX is
specified and an E-Ievel error is
encountered. The actual object code
listing contains:
The compiler-generated card
number. This number identifies
the COBOL statement in the source
deck which contains the verb that
generates the object code found in
column C. When VERB is speci~ied,
the actual verb or paragraph-name
is listed with the generated card
number.

The relative location, in
hexadecimal notation, of the
object code instruction in the
module.

The actual object code instruction
in hexadecimal notation.
The procedure-name number. A
number is assigned only to
procedure-names referred to in
other Procedure Division
statements.
The object code instruction in the
form that closely resembles
assembler language. (Displacements
are in hexadecimal notation.)

Cowpiler-generated information
about the operands of the
generated instruction. This
includes names and relative
locations of literals. Table 5
refers to information in this
column.

Table

Symbols Used in the Listing and
Glossary to Define
Compiler-Generated Information

r----------T------------------------------,
Symbol I
Meaning
I

t----------+------------------------------~

SOURCE DATA ~AME
SAVE AREA CELL
SWITCH CELL
TALLY CELL
WORKING CELL
TEMPORARY STORAGE CELL
VARIABLE LENGTH CELL
SECONDARY BASE LOCATOR
BASE LOCATOR
BASE LOCATOR FOR LINKAGE
I
SECTION
ION
ON COUNTER
IPFM
PERFORM COUNTER
IPSV
PERFORM SAVE
IVN
VARIABLE PROCEDURE NAME
ISBS
SUBSCRIPT ADDRESS
IXSW
EXHIBIT SWITCH
IXSA
EXHIBIT SAVE AREA
IPRM
PARAMETER
IPN
SOURCE PROCEDURE NAME
IPBL
Procedure Block Locator
IGN
GENERATED PROCEDURE NAME
IDTF
DTF ADDRESS
IFIB
File Information Block
I
(for VSAM)
IVNI
VARIABLE NAME INITIALIZATION
ILIT
LITERAL
ITS2
TEMPORARY STORAGE
I
(NON-ARITHMETIC)
IRSV
REPORT SAVE AREA
ISDF
Secondary DTF Pointer
ITS3
TEMPORARY STO~AGE
I
(SYNCHRONIZATION)
ITS4
TEMPORARY STORAGE
I
(SYNCHRONIZATION)
lINX
INDEX CELL
!V(BCDNAME) ADDRESS CONSTANT
lVIR
VIRTUAL
IOVF
Overflow Cell
L __________ i ______________________________
JI
IDNM
ISAV
ISWT
ITLY
!WC
ITS
IVLC
ISBL
IBL
IBLL

Statistics: The compiler statistics
lis~the options in effect for this
run, the number of Data Division
statements specified: ~nd the
Procedure Division size. Each level
number is counted as one statement in
the Data Division. The Procedure
Division size is approximately the
number of verbs in the Procedure
Division.

An indicator is also given here if
dictionary spill occurred during
compilation. If spill occurred, the
amount of storage assigned to the
compiler may be increased for better
performance. Statistics are not
listed if SYNTAX (or CSYNTAX and an
E-Ievel or higher error occurred) was
in effect.
Cross-reference dictionary: The
cross-reference dictionary is produced
when the XREF or SXREF option is
specified. It is suppressed if
CSYNTAX is in effect and an E-Ievel
error is encountered. It consists of
two parts:
The cross-reference dictionary for
data-names consists of data-names
followed by the generated card
number of the statement which
defines each data-name, and the
generated card number of statements on which the referenced
statement begins. For MOVE
CORRESPONDING, the data items
actually moved are referenced.
Report Writer data-names, wi~h
the exception of data-names 1n
the form "-nnn", are defined
with the generated card number
of their respective RD's.
The cross-reference dictionary for
procedure-names consists of the
procedure~names followed by the
generated card number of the
statement where each
procedure-name is used as a·
section-name or paragraph-name,
and the generated card number of
statements where each
procedure-name is referenced.
A reference will appear to a procedure
name if there is a reference to a
logically equivalent procedure-name; a
reference will also appear to a
procedure name, if, in a segmented
program, an implied branch to a
segment entry is made.
If XREF is specified, the names are
presented in the order in which they
appear in the source program. If
SXREFis specified~ the names are
presented alphabetically. The number
of references appearing in the
cross-reference dictionary for a given
name is based upon the number of times
the name is referenced in the code
generated by the compiler.
Since a SEARCH verb results in the
examination of the individual elements

in the named table, the XREF or SXREF
for a SEARCH will reference the
element name for the table rather than
the table itself. LISTER could
provide the source ~ross-reference
material that might be desired.
Diagnostic messages: The diagnostic
messages associated with the
compilation are always listed. The
format of the diagnostic rressage is:
Compiler-generated card number.
This is the number of a line in
the source program related to the
error.
Message identification. The
message identification for the
DOS/VS COBOL compiler always
begins with the symbols ILA.
The severity level. There are
four severity levels as follows:
(W) Warning
This level indicates that an
error was made in the source
program. However, it is not
serious enough to interfere
with the execu~ion of the
program. These warning
messages are listed only if
the FLAGW option is specified
in the CBL card or chosen at
system generation time.
(C) Conditional

This level indicates that an
error was made but the
compiler usually rrakes a
corrective assumption. The
statement containing the error
is retained. Execution can be
attempted.
(E) Error
This level indicates that a
serious error was made.
Usually the compiler makes no
corrective assu~ption. The
statement or option containing
the error is dropped.
Compilation is completed, but
execution of the program
should not be attempted.
(D) Disaster
This error indicates that a
serious error was rrade.
Compilation is not completed.
Results are unpredictable. If
this is a compiler error, the
job will terminate via the

Interpreting Output

CANCEL macro and produce a
dump.

The message text. The text
identifies the condition that
caused the error and indicates the
action taken by the compiler.

The message text is usually composed of
two sentences. The first describes the
error; the second describes what the
compiler has done as a result of the error.
~ote:

By specifying a PROGRAM-ID of ERRMSG
any source program, the user can
generate a complete listing of compiler
diagnostics and problem determination aids.
(See Figure 12.) In this case, a normal
compilation never takes place. Only a list
of all error messages and problem
determination information is produced. The
link option is reset if it was in effect.
~n

Since Report Writer generates a
number of internal data items and
procedural statements, some error
messages may reflect internal
names.
In cases where the error
occurs mainly in these generated
routines, the error messages may
indicate the card number of the RD
entry for the report under
consideration. In addition, there
are errors that may indicate the
number of the card upon which the
statement containing the error
--ends rather than the card upon
which the error occurs. Internal
name formats for Report writer are
discussed under "Glossary"
(heading 4, item C). statement
numbers are generated when a verb
or procedure name is encountered.

Some messages are not given if CSYNTAX
or SYNTAX is in effect. See "Program
Checkout" for the list of these messages.
FIPS Diagnostic Messaqes: The
diagnostic messages associated with
FIPS are listed separately from the
compiler diagnostic messages, with a
header identifying them as FIPS
diagnostics.
The format of the FIPS
diagnostic messages is:
Compiler-generated line number.
This is the nUIrber ofO a line in
the source program containing a
nonstandard element.

The COBOL-compile-time message that follows
serves a~an example of the format of COBOL
compiler messages:
CARD ERROR MESSAGE
00105 ILA1002I-W

*****

SECTION HEADER
MISSING.
ASSUMED PRESENT.

• The code "00105" at the left is the
card number of the statement in which
the error has occurred.
1
I
I
lCalling
I
I
Iprogram
I
1
lof C
I
Figure 15.

Whenever a program calls another
program, linkage must be·< established
between the two. The calling program must
state the entry point of the called program
and must specify any arguments to be
passed. The called program must have an
entry point and must be able to accept the
arguments. Further, the called program
must establish the linkage for the return
of control to the calling program.

ICalled
I program
I
lof B
1-->1
I
I
I
I

I
I

A calling COBOL program must contain the
following statement at the point where
another program is to be called:
i

ICALL literal-1 [USING identifier-l
I
[identifier-2] ••• ]

Calling and Called Programs

By convention, a called program may call
to an entry point in any other program,
except one on a higher level in the "path"
of that program. That is, A may call to an
entry point in B or C, and B may call C;
however. C should not call A or B.
Instead, C transfers control only to B by
issuing the EXIT PROGRAft or GOBACK
statements in COBOL (or its equivalent in
another language). B then returns to A.

literal-1
is the name specified as the
program-name in the PROGRAM-ID
paragraph of the called program, or
the name of the entry point in the
called program. When the called
program is to be entered at the
beginning of the Procedure Division,
literal-l is the name of the program
being called. When the called program
is to be entered at some point other
than the beginning of the Procedure
Calling and Called Programs

Division,' literal-1 should not be the
same as the name specified in the
PROGRAM-ID paragraph of the called
program. Since the program-name in
the PROGRAM-ID paragraph produces an
external reference defining an entry
point, this entry point name would not
be uniquely defined as an external
reference.

r--------------------------------~I ~

ENTRY literal-1 [USING identifier-1 I
[identifier-2] ••• ]
I
L

literal-1
is the name of the entry point in
the called program. It is the
same name that appears in the
CALL statement of the program
that calls this program.

If the first character of PROGRAM-ID
is numeric, the correspondence
algorithm is as follows:

o becomes J
1-9 become A-I

literal-1 must not be the name of
any other entry point or
program-name in the run unit.

Since the system does not include the
hyphen as an allowable character, the
hyphen is converted to zero if it
appears as the second through eigbth
character of the name.
identifier-1 [identifier-2] •••
are the arguments being passed to the
called program. Each identifier
represents a data item defined in the
File, Working-Storage, or Linkage
Section of the calling program and
should contain a level number 01 or
77. When passing identifiers from the
File Section, the file should be open
before the CALL statement is executed.
If the called program is an assembler
language program, the arguments may
represent file-names and procedurenames in addition to data-names. If
no arguments are to be passed, the
USING option is omitted.

identifier-1 [identifier-2] ••• ]
are the data items representing
parameters. They correspond to
the arguments of the CALL
statement of the calling program.
Each data item in this parameter
list must be defined in the
Linkage Section of the called
program and must contain a level
number of 01 or 77.
2.

Either of the following statements
must be inserted where control is to
be returned to the calling program:
I EXIT PROGRAM.
~

IL---____________________________________
GOBACK.

Both the EXIT PROGRAM and GOBACK
statements cause the restoration of
the necessary registers, and return
control to the point in the calling
program immediately following the
calling sequence.

LINKAGE IN A CALLED PROGRAM
A called COBOL program must contain two
sets of statements:
1.

One of the following statements must
appear at the point where the program
is entered.
If the called program is entered at
the first instruction in the Procedure
Division and arguments are passed by
the calling program:
I

IPROCEDURE DIVISION [USING
identifier-1 [identifier-2] ••• ].

-----J

If the entry point of the called
program is not the first statement of
the Procedura Division:
76

ENTRY POINTS
Each time an entry point is specified in
a called program, an external-name is
defined. An external-name is a name that
can be referenced by another program that
has been separately compiled or assembled.
Each time an entry name is specified in a
calling program, an external reference is
defined. An external reference is a symbol
that is defined as an external-name in
another separately compiled or assembled
program. The Linkage Editor resolves
external-names and external references, and
combines calling and called programs into a ~
format suitable for execution together,
~
i.e., as a single phase.

Note: Several different entry points may
be defined in one COBOL source module.
Different CALL statements in any module of
the phase may specify the same entry point,
but each definition of an entry point must
be unique in the same phase.

SUBPRGD.
Also assume that the module sizes
for the main program and subprograms are:

CORRESPONDENCE OF ARGUMENTS AND PARAMETERS
The number of identifiers in the
argument list of the calling program should
be~he same as the number of identifiers in
the parameter list of the called program.
If the number of identifiers in the
argument list of the calling program is
greater than the number of identifiers in
the parameter list of the calle~ program,
only those specified in the parameter list
of the called program may be referred to by
the called program. There is a one-for-one
correspondence. The correspondence is
positional and not by name. An identifier
must not appear more than once in the same
USING clause ..
Only the address of an argument is
passed. Consequently, both the identifier
that is an argument and the identifier that
is the corresponding parameter refer to the
same location in storage. The pair of
identifiers need not be identical, but the
data descriptions must be equivalent. For
example, if an argument is a level-77
data-name representing a 30-character
string, its corresponding parameter could
also be a level-77 data-name representing a
character string of length 30, or the
parameter could be a level-Ol data item
-with subordinate items representing
character stri~gs whose combined length is
30.
Although all parameters in the ENTRY
statement must be described with level
numbers 01 or 77, there is no such
restriction made for arguments in the CALL
statement. An argument may be a qualified
name or a subscripted name. When a group
item with a level number other than 01 is
specified as an argument, proper boundary
word alignment is required if subordinate
items are described as COMPUTATIONAL,
COMPUTATIONAL-l, or COMPUTATIONAL-2. If
the argument corresponds to an 01-level
parameter, doubleword alignment is
required.

Module Size
(inj!ytesl.
20,000
4,000
5,000
6,000
3,000

!:roqram.
COBMAIN
SUBPRGA
SUBPRGB
SUBPRGC
SUBPRGD

Through the linkage mechanism, all
called programs plus COBMAIN must be link
edited together to form one module of
38,000 bytes. Therefore, COBMAIN would
require 38,000 bytes of storage in order to
be executed. No overlay structure need be
specified at link edit time if 38,000 bytes
of virtual storage are available.

The following is an example of the job
control statements needed to link edit
these calling and called programs without
specifying an overlay structure. The
source decks for COBMAIN and SUBPRGA are
included in the job deck, whereas SUBPRGB,
SUBPRGC, and SUBPRGD are in the relocatable
library.

/ / JOB NOVERLAY

// OPTION LINK,LIST,DUMP
ACTION MAP
PHASE EXAMP1,*
INCLUDE

{object module COBMAIN}

INCLUDE SUBPRGB
INCLUDE SUBPRGC
INCLUDE SUBPRGD
INCLUDE
{object module SUBPRGAJ

ENTRY
/ / EXEC LNKEDT
// EXEC
{data for program}

/*
/&

LINK EDITING WITHOUT OVERLAY
Assume that a COBOL main program
(COBMAIN), at one or more points in its
logic executes CALL statements to COBOL
programs SUEPRGA, SUBPRGB, SUBPRGC, and

Figure 16 is an example of the dnta floy
logic of this call structure where all the
programs fit into virtual storage.

Calling and Called Programs

From these combinations, more
complicated structures can be formed.
In a COBOL program, the expansions of
the CALL and GOBACK or EXIT PROGRAM
statements provide the save and return
coding that is necessary to establish
linkage between the calling and called
programs in accordance with the linkage
conventions of the system. Assembler
language programs must be prepared in
accordance with the same linkage
conventions. These conventions include:
1.

Using the proper registers to
establish linkage.

Reserving, in the calling program, a
storage area for items contained in
the argument list. This storage area
can be referenced by the called
program.

Reserving, in the calling program, a
save area in which the contents of the
registers can be saved.

Execute

LNKEDT

Linkage
Editor

t - - - - - - - - - I - - - } Storage

layout

Figure 16.

Example of Data Flow Logic in a
Call structure

Note: For the example given, it is assumed
that SYSLNK is a standard assignment. The
flow diagram illustrates how the various
program segments are link edited into
storage in a sequential arrangement.

ASSEMBLER LANGUAGE SUBPROGRAMS
A main program written in COBOL can call
programs written in other languages that
use the same linkage conventions. Whenever
a COBOL program calls an assembler language
program, certain conventions and techniques
must be used.
There are three basic ways to use
assembler-written called programs with a
main program written in COBOL:
1.
2.
3.

A COBOL main program or called program
calling an assembler-writtem program.
An assembler-written program calling a
COBOL program.
An assembler-written program calling
another assembler-written program.

REGISTER USE
The Disk Operating System has assigned
functions to certain registers used in
linkages. Table 7 shows the conventions
for using general registers as linkage
registers. The calling program must load
the address of the return point into
register 14, and it must load the address
of the entry point of the called program
into register 15.
Table

Conventional Use of Linkage
Registers

IReg.IReg.
I
INo. IName
I
I
I
I 1 IArgument
Ilist
I
,register
I
I
ISave
113
larea
I
Iregister
I
I
I
I
I
I

I
114

I
I

Function

I
I
I

Address of the argument
I
list passed to the called I
program.
I
I
Address of the area reI
served by the calling pro-I
gram in which the contents I
of certain registers are I
stored by the called
I
program.
I

IReturn I Address of the location inl•
I register I the calling program to
I
I which control is returned I
after execution of t.he
I
i
called program.
1
I

1
I

115
I

I
I Entry

Address of the entry pointl
Ipoint
I in the called program.
Iregisterl

---'

SAVE AREA

ARGUMENT LIST

A calling assembler language program
must reserve a save area of 18 words,
beginning on a fullword boundary, to be
used by the called program for saving
registers; it must load the address of this
area into register 13. Table 8 shows the
layout of the save area and the contents of
~ch word.

The argument list is a group of
contiguous fullwords, beginning on a
fullword boundary, each of which is an
address of a data item to be passed to the
called program. If the program is to pass
arguments, an argument list must be
prepared and its address loaded into
register 1. The high-order bit of the last
argument, by convention, is set to 1 to
indicate the end of the list.

A called COBOL program does not save
floating-point registers. The programmer
is responsible for saving and restoring the
contents of these registers in the calling
program.

Table

Save Area Layout and Word
Contents

r--------------------------------------------,
i

AREA
(word 1)

AREA+4
(word 2)

AREA+8
(word 3)

AREA+12
(word 4)

!This word is a part of the
Istandard linkage convention
lestablished under the DOS/VS
ISystem. The word must be
Ireserved for proper
laddressing of the subsequent
lentries. However, an
lassembler subprogram may use
Ithe word for any desired
Ipurpose.

If one programmer writes both the
calling program and the called program, the
data format of the arguments should not
present a problem when passed as
parameters. However, when the programs are
written by different programmers, the data
format specifications for the arguments
must be clearly defined for the programmer.
The linkage conventions used by an
assembler program that calls another
program are illustrated in Figure 16.
linkage should include:

~---------------------------;

IThe address of the previous
I save area, that is, the save
jarea of the subprogram that
Icalled this one.
I
IThe address of the next save
I area, that is, the save area
lof the subprogram to which
Ithis subprogram refers.

Any assembler-written program must be
coded with a detailed knowledge of the data
formats of the arguments being passed.
Most coding errors occur because of the
data format discrepancies of the arguments.

i
I
,
I
I
I
I

The

The calling sequence.
The save and return routines.

The out-of-line parameter list.
(An
in-line parameter list may be used.)

A save area on a fullword boundary.

1r--------------------------1

IThe contents of register 14, I
Ithat is, the return address. I

FILE-NAME AND PROCEDURE-NAME ARGUMENTS

~------------------------~,

AREA+16
IThe contents
(word 15) Ithat is, the
I
AREA+20
IThe contents
(word 6) I
I
AREA+24
IThe contents
(word 7) I
I
I
I
I
AREA+68
IThe contents
(word 18) I
I

of register 15, I
entry address.
I
I
of register o.
I
I
I
of register 1.
I
I
I
I
I
,
of register 12. I
I
,

A callinq COBOL program that calls an
assembler-language program can pass
file-names and procedure-names, in addition
to data-names, as identifiers. In the
actual identifier-list that the compiler
generates, the procedure-name is passed as
the address of the procedure.
For a file,
the address of the DTF is passed, and the
user must ensure that the file is already
open. A VSAM file-name may not be passed.
Care must be taken when using these
The user must be thoroughly
familiar with the generated coding for each
option and statement, as well as the
structure of the object program.
op~10ns.

Calling and Called Programs

deck name

START

*
*

ENTRY
FXTRN
USING
* SAVE ROUTINE
STM
name 1

*
*
*

*
*
*
*
*
*
*
*
AREA

INITIATES PROGRAM ASSEMBLAGE AT FIRST
AVAILABLE LOCATION. ENTRY POINT TO THE
PROGRAM.

name1
name2
name'1 ,15
14,r 1 , 12 (13)

LR
DROP
USING
LR

r3,15
15
name1,r3
r2,13

13,AREA

13,8

r 2,4 (13)

BC
DS

15,prob 1
18F

DC
DC

Xf 80'
AL3 (arg n >

(r~)

THE CONTENTS OF REGISTERS 14, 15, AND
THROUGH r 1 ARE STORED IN THE SAVE
AREA OF THE CALLING PROGRAM (PREVIOUS
S AVE AREA). r 1 IS ANY NUMBER FROM 0 THROUGH 12.

WHERE r3 AND r2 HAVE BEEN SAVED
LOADS REGISTER 13, WHICH POINTS TO THE
SAVE AREA OF THE CALLING PROGRAM, INTO
ANY GENERAL REGISTER, r2' EXCEPT 0 AND 13.
LOADS THE ADDRESS OF THIS PROGRAM'S
SAVE AREA INTO REGISTER 13.
STORES THE ADDRESS OF THIS PROGRAM'S SAVE
AREA INTO WORD 3 OF THE SAVE AREA OF THE
CALLING PROGRAM.
STORES THE ADDRESS OF THE PREVIOUS SAVE
AREA (I.E., THE SAME AREA OF THE CALLING
PROGRAM) INTO WORD 2 OF THIS PROGRAM'S
SAVE AREA.

RESERVES 18 WORDS FOR THE SAVE AREA
THIS IS LAST STATEMENT OF SAVE ROUTINE.
{User-written program statements}
L
15,VCON
INDICATE COBOL PROGRAM IS
BALR
14,15
A SUBPROGRAM
CALLING SEQUENCE
*
LA
1,ARGLST
L
15,ADCON
BALR
14,15
{Remainder of user-written program statements}
* RETURN ROUTINE
L
13,4 (13)
LOADS THE ADDRESS OF THE PREVIOUS SAVE
AREA BACK INTO REGISTER 13.
*
THE CONTENTS OF REGISTER 2 THROUGH r1 ARE
LM
RESTORED FROM THE PREVIOUS SAVE AREA.
*
L
14,12(13)
LOADS THE RETURN ADDRESS, WHICH IS IN
WORD 4 OF THE CALLING PROGRAM'S SAVE AREA,
*
INTO REGISTER 14.
*
MVI
12 (13) ,X'FF' SETS FLAG FF IN THE SAVE AREA OF THE
CALLING PROGRAM TO INDICATE THAT CONTROL
*
HAS RETURNED TO THE CALLING PROGRAM.
*
BCR
15,14
LAST STATEMENT IN RETU&N ROUTINE
VCON
DC
V (ILBDSETO)
ADCON
DC
CONTAINS THE ADDRESS OF SUBPROGRAM
A (name 2)
* PARAMETER LIST
ARGLST
DC
AL4(arg 1 )
FIRST STATEMENT IN PARAMETER AREA SETUP
DC
AL4 (arg 2)

*
prob 1

L _ _ _ __

Pigure

17~

FIRST BYTE OF LAST ARGUMENT SETS BIT 0 TO 1
LAST STATEMENT IN PARAMETER AREA SETUP

Sample Linkage Routines Used with a Calling Subprogram

OVERLAYS
ADCON

•

A (prob 1 )

LA
L
CNOP
BALR
DC
DC

14,RETURN
15,ADCON
2,4
1,15
AL4 (arg 1)
AL4 (arg 2 )

DC
TI.'"

X'80 1
AL3 (argni

EQU

.IJ\..

RETURN
Figure 18.

If a program is too large to be
contained in the number of bytes available
in virtual s_tp.page, it can still be
executed by means of an overlay structure.
An overlay structure permits the re-use of
storage locations previously occupied by
another program.
In order to use an
overlay structure, the programmer must plan
his program so that one or more called
programs need not be in storage at the same
time as the rest of the program phase. The
programmer should reassess, when going to
VS, whether progra~s which used to require
an overlay structure still do.

Sample In-line Parameter List

The following is a diagram of the basic
form of a program to be overlaid:

In-Line Parameter List
The assembler programmer may establish
an in-line parameter list instead of an
out-of-line list.
In this case, he may
sUbstitute the calling sequence and
parameter list illustrated in Figure 18 for
that shown in Figure 17.

LOWEST LEVEL PROGRAM
If an assembler called program does not
call any other program (i.e., if it is at
the lowest level), the programmer should
omit the save routine, calling sequence,
and parameter list shown in Figure 17. If
the assembler called program uses any
registers, it must save them.
Figure 19
illustrates the appropriate linkage
conventions used by an assembler program at
the lowest level.
deckname

name

START
ENTRY

name

USING
STl!

*,15
14,r 1 ,12(13)

I
I
IROOT PHASE

I
I
I
r·-----L.-----,

I
I
I
I
I

ISUBA

ISUBE

The root phase consists of the COBOL
main program and an assembler language
subroutine which handles the overlay
structures. SUBA and SUBB are the called
programs that are to be overlaid in
storage.
In using the overlay technique, the
programmer specifies to the Linkage Editor
which programs are to overlay each other.
These programs are processed by the Linkage
Editor so they can be placed automatically
in storage for execution when called by the
main program. The resulting output of the
Linkage Editor is called an overlay
structure.

User-written program statements
Lft

MVI

BCR

2, r 1 , 28 ( 13)
12 (13) , X • FF '
15, 14

I
INote:
lin the
Ishr-:a
Icalled

SPECIAL CONSIDERATIONS WHEN USING OVERLAY
STRUCTURES

,
If registers 13 and/or 14 are used;
called subprogram, their contents I
be saved and restored by the
subprogram.

Figure 19.

Sample Linkage Routines Used
with a Lowest Level Subprogram

There are three areas of special concern
to the programmer who decides to use the
overlay feature.
These problems concern
the use of the assembler language
subroutine, proper link editing, and job
control statements.
Calling and Called Programs

ASSEMBLER LANGUAGE SUBROUTINE FOR
ACCOMPLISHING OVERLAY
The CALL statement is used for "direct"
linkage; that is, the assistance of the
Supervisor is not required (as it is when
loading or fetching a phase). There are no
COBOL statements that will generate the
equivalent of the LOAD or FETCH assembler
macro instructions. For this reason, one
must call an assembler program to effect an
overlay of a COBOL program. This routine
must be link edited as part of either a
root phase or permanently resident phase.
The sample overlay subroutine shown in
Figure 20 is governed by the following
restrictions:
1.

It can be used for assembler overlays
if the programmer has a desired'entry
point in his END card and the first
statement at that entry point is 'STM
14,12,12(13) '.

This subroutine can be used for a
COBOL program which contains an ENTRY
statement immediately following the
Procedure Division header.
It will
not work with a COBOL subprogram
compiled with a Procedure Division
USING statement or for entry points in
a COBOL subprogram which appear
anywhere other than as the first
instruction of the Procedure Division.
A suggested technique for diverse
entry points is a table look-up using
v-type constants.

The example is a suggested technique,
and is not the only technique.

r-------------------------------------·-------------------STMNT
SOURCE STATEMENT
0601 OVERLAY
START 0
0002'
ENTRY OVRLAY
0003
AT ENTRY TIME
*
0004
Rl=POINTER TO ADCON LIST OF USING ARGUMENTS
*
0005
FIRST ARGUMENT IS PHASE OR SUBROUTINE NAME
*
0006
MUST BE 8 BYTES
*
0007
R13=ADDRESS OF SAVE AREA
*
0008
R14=RETURN POINT OF CALLING PROGRAM
*
0009
R15=ENTRY POINT OF OVFRLAY PROGRAM
0010 * AT EXIT
0011 *
Rl=POINTER TO SECOND ARGUMENT OF ADCON LIST
*
0012
OF USING ARGUMENTS
*
0013
R14=RETURN POINT OF CALLING PROGRAM--NOT THIS PROG
*
0014
R15=ENTRY POINT OF PHASE OR SUBPROGRAM
*
0015
0016 *
USING *,15
0017 OVRLAY
STM O,l,SAVE
SAVE WORK REGS
0018
L
POINT Rl TO PHASE NAME
1,0(1)
0019
CLC CORSUB,O (1)
IN CORE?
0020
BE
SUBIN
YES,BR
0021
MVC CORSUB (8) ,0 (1)
SET CURRENT PHASE
0022
SR
0,0
0023
SVC 4
LOAD PHASE
0024 SEARCHl
LA
1,4(1)
STEP SEARCH POINT
0025
CLC 0(3,1) ,=C'COB'
END OF INIT1?
0026
BNE SEARCHl
NO, LOOP
0027
S
1 , =F' 8'
POINT TO "START" ADCON
0028
L
1,0(1)
LOAD "START"
0029
LA
1,8(1)
INCREMENT TO "ENTRY"
0030
ST
1,ASUo
SAVE ENTRY ADDRESS
0031 SUBIN
LM
0, 1, SAVE
RELOAD WORK REGS
0032
LA
1,4(1)
POINT TO PARAMETERS
0033
15,ASUB
L
0034
BR
15
BRANCH TO ENTRY POINT
,.., ......
0035 CORSUB
0 \..LO
0036
DC
8X'FF'
0037 ASUB
DS
F
DS
0038 SAVE
2F
END
0039
L _ _ _ _ _ __
Figure 20.
82

Example of an Assembler Language Subroutine for Accomplishing Overlay

Note: Care should be taken with the
techniques used in statements 0019 and
0020. Only when the COBOL program is
loaded are altered GO TO statements
reinitialized. A better technique would be
to load the called programs each time they
are required.
The examples given in Figures 20, 21, and
22 require that all overlay modules be linked
together. To permit linkage to and return
from modules, compiled and link edited
separately, the following changes to
Figure 20 are necessary:

Also, to achieve maximum overlay, the phase
names for the called programs should be
different from the names of the called
programs specified in the PROGRA~-ID
paragraphs.
Figure 21 is a flow diagram of the
overlay logic. The PHASE cards indicate
the beginning address of each phase. The
phases OVERLAYC and OVERLAID will have the
same beginning address as OVERLAYB. The
sequence of events is:
1.

The main program calls the overlay
routine.

The overlay routine fetches the
particular COBOL subprogram and places
it in the overlay area.

The overlay routine transfers control
to the first instruction of the called
program.

The called program returns to the
COBOL calling program (not to the
assembler language overlay routine).

Replace lines 25 through 28
CLC

BNE
LR
L
MVC
LR
L
NOP L
MVI
LR
L

COBCON,20(1)
SEARCHI
0,1
1,0(1)
NOP+3(1),139(1)
1,0
1,4(1)
1,0(1)
O(l),X'FF'
1,0
1,12(1)

END OF INIT?
NO, LOOP
SAVE ADDR ADCON INITI
GET INITI ADDR
GET DISP OF VIRT CELL
RESTORE ADDR OF ADCON INITI
GET ADDR OF PGT
LOAD ADDR OF ILBDMNSO
SET 'CALLED PROGR' FLAG
RESTORE ADDR OF ADCON INITI
LOAD 'START' ADDRESS

If OVERLAYB were ~nown to be in storage,
the CALL statement would be:

Insert after line 38
COBCON DC

CL3'COB'
I

CALL "OVERLAYB" USING PARAM-1, PARAM-2.1
LINK EDITING WITH OVERLAY
In a linkage editor job step, the
programmer specifies the overlay points in
a program by using PHASE statements. In
the Working-Storage Section, a level-01 or
level-77 constant must be created for each
phase to be called at execution time.
These constants have a PICTURE of X(8) and
a VALUE clause containing the same name as
that appearing on the PHASE card for that
segment in the link edit run.
In addition, each argument to be passed
to the called program must have an entry in
the Linkage Section. Remember, also, that
the ENTRY statement should not refer to the
program-name.
(Use of the program-name
will result in incorrect execution.)
When more than one subprogram in the
overlay structure requires the same COBOL
subroutine, the // EXEC LNKEDT statement
must be preceded by INCLUDE cards for each
of these subroutines. The names of these
subroutines can be determined by requesting
LISTX at compile time.
When preparing the control cards for the
Linkage Editor, the programmer should be
certain to include the assembler language
subroutine with the main (root) p~ase.

But when using the assembler language
overlay routine (OVRLAY), it becomes:

CALL "OVRLAY" USING PROCESS-LABEL,
PARM-1, PARM-2.

where PROCESS-LABEL contains the
external-name OVERLAYB of the called
program.

However, the ENTRY statement of the
called program is the same for both cases,
i.e., ENTRY "OVEPLAYB" USING PARAM-l,
PARAM-2, whether it is called indirectly by
the main program through the overlay
program or called directly by the main
program.

Note: An ENTRY which is to be called by
OVRLAY must precede the first executable
statement in the called proqram.
Calling and Called Programs

JOB CONTROL FOF ACCOMPLISHING OVERLAY
COBOL
Moin or Root
Overlay Routine
Overlay Area

The job control statements required to
accomplish the overlay illustrated in
Figure 21 are shown in Figure 22. The
PHASE statements specify to the Linkage
Editor that the overlay structure to be
established is one in which the called
proarams OVERLAYF, OVERLAYC, and OVERLAYD
overlay each other when called during
execution.
Note: The phase name specified in the
PHASE card must be the same as the value
contained in the first argument for CALL
"OVRLAY", i.e., PROCESS-LABEL, COMPUTE-TAX,
etc., contain OVERLAYE, OVERLAYC,
respectively, which are the names given in
the PHASE card.

Figure 21.

Flow Diagram of Overlay Logic

It is the programmer's responsibility to
write the entire overlay, i.e., the COBOL
main (or callin~) proaram and an assembler
language subroutine {for which a sample
program is given in this chapte~ that
fetches and overlays the called programs.
A calling sequence to obtain an overlay
structure between three COBOL subproarams
is illustrated in Figure 23.

I I JOB OVERLAYS
I I OPTION LINK
PEASE OVERLAY,ROOT
I I ~XEC ~COBOL
(COEOL Source for Main Proaram MAINLINE}

/1 EXEC ASSEMBLY
[Source deck for Assembler Lanauaae Routine OVERLAY]

PHASE OVERLAY5,*

1/ EX=:C FCOEOL
{COBOL Source for Called Program OVERLAYB}

PEASE OVERLAYC,OVERLAYB

1/ EX f:C FCOBOL
(COBOL Source for Called Program OVEFLAYC}

PSASE OVERLAYD,OVERLAYC
/ / EXEC FeOBOL
{COBOL Source for Called Program OVERLAYD}

/ / EXE= LNKEDT
/ / EXEC

/*
/~
L----_____________________________________________________________________________
__

Figure 22.

Job Control for Accomplishing Overlay

COBOL Program Main (Root or Main Program)
IDENTIFICATION DIVISION.
PROGRAM-ID. MAINLINE.

ENVIRONMENT DIVISION.

WORKING-STORAGE SECTION.
77 PROCESS-LABEL PICTURE IS X(8) VALUE IS "OVERLAYB".
77 PARAM-1 PICTURE IS X.
77 PARAM-2 PICTURE IS XX.
77 COMPUTE-TAX PICTURE IS X(8) VALUE IS "OVERLAYC".
01

01
01

NAMET.
02 EMPLY-NUMB PICTURE IS 9(5).
02 SALARY PICTURE IS 9(4)V99.
02 RATE PICTURE IS 9(3)V99.
02 HOURS-REG PICTURE IS 9(3)V99.
02 HOURS-OT PICTURE IS 9(2)V99.
COMPUTE-SALARY PICTURE IS X(8) VALUE IS "OVERLAYD".
NAMES.
02 RATES PICTURE IS 9(6).
02 HOURS PICTURE IS 9(3)V99.
02 SALARYX PICTURE IS 9(2)V99.

PROCEDURE DIVISION.

CALL "OVRLAY" USING PROCESS-LABEL, PARAM-l, PARAM-2.

CALL "OVRLAY" USING COMPUTE-TAX, NAMET.

CALL "OVRLAY" USING COMPUTE-SALARY, NAMES.

I •

I •
------.--------~

Figure 23.

Calling Sequence to Obtain Overlay Between Three COBOL Subprograms (Part 1 of

Calling and Called Programs

COBOL

subpro~£am

IDENTIFICATION DIVISION.
PROGRAM-ID. OVERLAY1.

ENVIRONMENT DIVISION.

DATA DIVISION.
LINKAGE SECTION.
01
01

PARAM-l0 PICTURE X.
PARAM-20 PICTURE XX.

PROCEDURE DIVISION.
PARA-NAME. ENTRY "OVERLAYB" USING PARAM-l0, PARAM-20.

GOBACK.

IDENTIFICATION DIVISION.
PROGRAM-ID. OVERLAY2.

ENVIRONMENT DIVISION.

DATA DIVISION.
LINKAGE SECTION.
01

I
I
I
I
I

NAMEX.
02 EMPLY-NUMBX PICTURE IS 9{5}.
02 SALARYX PICTURE IS 9(4) V99.
02 RATEX PICTURE IS 9(3)V99.
02 HOURS-REGX
PICTURE IS 9(3)V99.
02 HOURS-OTX PICTURE IS 9(2}V99.

PROCEDURE DIVISION.
PARA-NAME. ENTRY "OVERLAYC" USING NAMEX.
•
•
•
GOBACK.

Figure 23.

Calling Sequence to Obtain overlay Between Three COBOL Subprograms
(Part 2 of 3)

COBOL Subprogram D
IDENTIFICATION DIVISION.
PROGRAM-ID. OVERLAY3.

ENVIRONMENT DIVISION.

DATA DIVISION.
LINKAGE SECTION
01 NAMES.
02 RATES PICTURE IS 9(6).
02 HOURS PICTURE IS 9(3)V99.
02 SALARYX PICTURE IS 9(2)V99.
PROCEDURE DIVISION.
PARA-NAME. ENTRY "OVERLAYD" USING NAMES.

GOBACK.
Figure 23.

Calling Sequence to Obtain Overlay Between Three COBOL Subprograms
(Part 3 of 3)

Callinq and Called Programs

USING THE SEGMENTATION FEATURE

COBOL segmentation permits the user to
subdivide logically and physically the
Procedure Division of a COBOL object
program. All source sections which contain
the same segment-number in their section
headers will be considered at object time
to be one segment. Since segment-numbers
can range from 00 through 99, it is
possible to subdivide any object program
into a maximum of 100 segments.

in the root segment. Thus no fields in
other than the root segment are modified.
The program SAVECORE could be segmented
as illustrated in Figure 24.
IDENTIFICATION DIVISION.
PROGRAM-IDa SAVECOREs

Program segments may be of three types:
fixed permanent, fixed overlayable, and
independent as determined by the
programmer's assignment of segment numbers.
Segmentation of a program would be used
when virtual storage is limited. In a real
storage system, the following would apply:

ENVIRONKENT DIVISION.
OBJECT-COMPUTER. IBM-370.
SEGMENT-LIMIT IS 15.
DATA DIVISION.

Fixed segments are always in real
storage during the execution of the
entire program, that is, they cannot
be overlayed except when the system
itself is executing another program,
in which case fixed segments may be
"rolled out."
Fixed overlayable segments may be
overlayed during program execution,
but any such overlaying is transparent
to the user, that is, they are
logically identical to fixed segments,
but physically different from them.
Independent segments may be overlayed,
but such overlaying will result in the
initialization of that segment.
Therefore, independent segments are
logically different from fixed
permanent/fixed overlayable segments,
and physically different from fixed
segments.

In a virtual storage system, all
logically "fixed" segments, that is, fixed
permanent and fixed overlayable, are
treated the same. They are both "paged in
and out" as required for execution.
In the same manner, independent segments
are paged in and out; when they are paged
in, however, they are brought back in the
initial state.
In DOS/VS COBOL, segments that are
overlayed are not actually "paged out".
All the variable data items associated with
the segment are contained in one segment,
which is considered the root segment. When
a segment is "paged in", all the fields
which must be reinitialized are contained

PROCEDURE DIVISION.
SECTION-1 SECTION 8.
SECTION-2

SECTION 8.

SECTION-3

SECTION 16.

SECTION-4

SECTION 8.

I•
ISECTION-5
I.
I•
ISECTION-6
I•
I•
ISECTION-7
I.
I•

Figure 24.

SECTION 50.
SECTION 16.
SECTION 50.

Segmenting the Program SAVECORE

Assuming that 12K of virtual storage is
available for the program SAVECORE, Figure
25 shows the manner in which storage would
be utilized. It is apparent from the
illustration that SECTION-3, SECTION-6, and
SECTION-7 cannot be in storage at the same
time, nor can SECTION-3, SECTION-5 and
SECTION-7 be in storage simultaneously.
Sections in the permanent segment
(SECTION-1; SECTION-2: and SECTION-4) are
those which must be available for reference
at all times, or which are referenced'
frequently. They are distinguished here by
the fact that they have been assigned
Using the Segmentation Feature

priority numbers less than the segment
limit.
Sections in the overlayable fixed
segment are sections which are less
frequently used. They are always made
available in the state they were in when
last used. They are distinguishable here
by the fact that they have been assigned
priority numbers greater than the segment
limit but less than 49.
Sections in the independent segment can
overlay, and be overlaid by, either an
overlayable fixed segment or another
independent segment. Independent segments
are those assigned priority numbers greater
than 49 and less than 100, and they are
always given control in their initial
state.

Segmented programs must not be called by
another program (segmented or not
segmented). If a segmented program calls a
subprogram, the CALL statement may appear
in any segment. However, the object module
associated with the subprogram must be
included in the root segment prior to the
execution of the main program. This can be
accomplished in either of two ways as
follows:
1.

Produce object decks for both programs
and place the one for the subprogram
in the root segment:
PHASE,ROOT
ESD card for the root segment
{object deck for the main program}
{object deck for the subprogram}

OPERATION
followed by aH EXEC LNKEDT and aV
EXEC.
Execution of the object program begins
in the root segment. The first segment in
the permanent segment is considered the
root segment. If the program does not
contain a permanent segment, the co.piler
generates a dummy segment which viII
initiate the execution of the first
overlayable or independent segment. All
global tables, literals, and data areas are
part of the root segment. Called object
time subroutines are also part of the root
segment. When CALL statements appear in a
segmented program, subprograms are loaded
with the fixed portion of the main program
as if they had a priority of zero.

Catalog the object module for the
subprogram in the relocatable library
prior to link editing the main
program. Insert an INCLUDE card for
the subprogram and an ENTRY card for
the root phase into the linkage editor
control cards for the root phase of
the main program. The ENTRY card will
cause the linkage editor to pass
control to the main program at
execution time. The Linkage Editor
will search the relocatable library
for the subprogram and include it with
the root phase.

data-buffers, global
table, etc., ( 1K)

I
I
I
I
I
I
I
I

I
I

SECTION-l (2K)

:1III

SECTION-2 (2K)
SECTION-4 (2K)

SECTION-3 (3K)

fixed portion
(12K)

permanent segment
(segment limit < 1S)
SECTION-S (2K)

(,
SK

~i
(1

SECTION-6 (2K)

----

SECTION-7 (lK)

----

-....".-

SECTION-3 and SECTION-6
are overlayablefixed segments
(14 < segment limit < SO)

Figure 2S.

If the program-name is 6, 7, or 8
characters in length, the
segment-name consists of the first
6 characters of program-name plus
the 2-character priority number.

If the program-name is less than 6
characters in length, the priority
number is appended after the
program-name.

Since the system expects the first
character of PROGRAM-ID to be
alphabetic, the first character,
if numeric, is converted as
follows:

COllPILER OUTPUT
The output produced by the compiler is
an overlay structure consisting of mUltiple
object modules preceded by linkage editor
control statements. Segments whose
priority is greater than the segment limit
(or 49, if no SEGMENT-LIllIT clause is
specified) consist of executable
instructions only.
The compiler generates each segment as a
separate object module preceded by a PHASE
card. The names appearing· on these PHASE
cards (segment-namesj conform to the
following naming conventions:

SECTION-5 and SECTION-7 are
independent segments
(49 < segment limit < 100)

Storage Layout for SAVECORE

OUTPUT FROM A SEGMENTED PROGRAM

---

The name of the root segment is the
same as the program-name specified in
the PROGRAM-ID clause.
The name of each overlayable and
independent segment is a combination
of the program-name and the priority
number of the segment. These names
are formed according to the following
rules:

1-9 -> A-I

The hyphen is converted to zero if
it appears as the second through
eighth character.
d.

When DECK is specified, the
punched object deck is sequenced
according to segments. Columns
73-74 contain the first two
characters of the program-id,
columns 7S-76 contain the priority
number of the segment, and columns
17-80 contain the sequence number
Using the Segmentation Feature

of the card. The priority of the
root segment is punched as 00.

AUI0LINK card for the Segmentation
subroutine.

When the compiler option CATALR is
in effect, the PHASE card for each
segment is preceded by a CATALR
card with the same name. This
will enable direct cataloging of
the compiler-produced object
module into the relocatable
library from which a load module
may be link edited into the
core-image library.

PHASE cards generated by the compiler
for segments of priority 10, 47-50, 60,
62, and 63.
Control card generated for the Sort
Feature. This card is eXplained in
"Sort in a Segmented Program."

Note: Single-digit priority numbers
are preceded by a zero.
warning: In order to avoid duplicate
names, the programmer must be aware of the
above naming conventions. If the last two
characters of an 8-character PROGRAM-ID are
numeric, these same two characters may not
appear in the source program as a segment
number.
Figure 26 is an illustration of the
compiler output for the skeleton program
shown in Figure 24.
PHASE SAVECORE,ROOT
{object module for the root segment
(sections with priority-numbers less
than the segment limit) including any
programs called by SAVECORE}

Load address of phase BIGJOBOO. Item 6
is explained in "Sort in a Segmented
Program."
Note: If the CATALR option of the CBL card
is specified, the compiler generates CATALR
cards in front of PHASE cards.

Cataloging a Segmented

PHASE SAVEC050,SAVEC016
{object module for segments with a
priority of 50 (two sections)}

Progra~

When the CATAL option is used to catalog
a segmented program, the following points
should be observed:
1.

To avoid duplicate names, the
programmer must be aware of the naming
conventions used by the compiler (see
"Compiler Output") because a
segment-name may be the same as a
phase-name already existing in the
core image library.

Since the PHASE card is generated by
the compiler, the programmer must not
specify a PHASE card for the program.

PHASE SAVEC016,*
{object module for segments with a
priority of 16 (two sections)}

Location of the entry point CURSEGM.
Item 5 is explained in "Determining the
Priority of the Last Segment Loaded
into the Transient Area."

To invoke a previously cataloged
segmented program, the programmer must use
the following control statement:
// EXEC name

Figure 26.

Compiler Output for SAVECORE
where ~mg is the program-name specified in
the PROGRAM-ID clause.

LINKAGE EDITOR OUTPUT
Determinin5Lihe Priori.1L.Q.i the Last
Segment Loaded into the Transient Area
Figure 27 is an illustration of the
input to the Linkage Editor and the phase
map produced by the Linkage Editor
resulting from the compilation and editing
of the segmented program BIGJOB. The
following text is an explanation of the
figure.

CI)
92

PHASE card generated by the compiler
for the root segment BIGJOB.

If a segmented program is abnormally
terminated during execution, and the SYMDMP
option has been specified, the CURRENT
PRIORITY cell in the Task Global Table
contains the priority of the last segment
loaded into the transient area. If SYMDMP
has not been specified, the priority of
this segment can be determined as follows:

In the map of virtual storage
ge~ed by the Linkage Editor, under
the column LABEL, look for the name
'CURSEGM' (see item 5 in Figure 27) •

Associated with this label, in the
column LOADED, is an address.

At this location is stored the
priority (one byte) of the segment
current in the transient area. If
this byte is X'OO', no segment has
been loaded into the transient area.
This indicates that the error causing
the dump occurred in the root segment.

SORT IN A SEGMENTED PROGRAM
If a segmented program contains a SORT
statement, the sort program will be loaded
above the largest overlayable or
independent segment as shown in Figure 28.
The compiler accomplishes this by
providing the following control statement
at the end of the overlay structure:
PHASE BIGJOBOO,transient area + L
This card is illustrated in Figure 27, item
4. The value of "L" in the figure is
X·002F2' which is the length of the longest
segment, BIGJOB47, rounded to the next
halfword boundary. Note that Linkage
Editor relocates the phase BIGJOBOO to the
next doubleword boundary (see Figure 27,
item 6).

Using the PERFORM Statement in a Segmented
Program
When the PERFORM statement is used in a
segmented program, the programmer should be
aware of the following:

• A PERFORM statement that appears in a
section whose priority-number is less
than the segment limit can have within
its range only (a) sections with
priority-numbers less than 50, and (b)
sections wholly contained in a single
segment whose priority-number is
greater 'than 49.
Note: As an extension to American
National Standard COBOL, DOS/VS COBOL
allows sections with any
priority-number to fall within the
range of a PERFORM statement.
• A PERFORM statement that appears in a
section whose priority-number is equal
to or greater than the segment limit
can have within its range only (a)
sections with the same priority-number
as the section containing the PERFORM
statement, and (b) sections with
priority-numbers that are less than the
segment limit.
Note: As an extension to American
National Standard COBOL, DOS/VS COBOL
allows sections with any
priority-number to fall within the
range of a PERFORM statement.
• When a procedure-name in a permanent
segment (priority-number less than
segment limit) is referred to by a
PERFORM statement in an independent
segment (priority-number greater than
49), the independent segment is
reinitialized upon exit from the
PERFORM. When a PERFORM statement
in the overlay able-fixed segment
(priority-number greater than segment
limit and less than 50) refers to a
procedure-name in a permanent segment,
the overlay able-fixed segment is not
reinitialized upon exit from the
PERFORM.

Using the Segmentation Feature

JOB

BIGJ

DISK LINKAGE EDITOR DIAGNOSTIC OF INPUT

ACTION TAKEN

MAP

BIGJOB'ROOT~

LIST

PHASE

LIST
LIST

AUTOLINK
AUTOLINK

LIST
LIST
ILIST
ILIST
ILIST
ILIST
ILIST
,LIST
ILIST

ROOT

PHASE
PHASE
PHASE
PHASE
PHASE
PHASE
PHASE
PHASE
PHASE

ILBDSEMO~
ILBDSRTO

BIGJOB10,*
BIGJOB41.BIGJOB10!
BIGJOB48,BIGJOB41
BIGJOB49,BIGJOB48 ~
BIGJOB50,BIGJOB49
3
BIGJOB60,BIGJOB50
BIGJOB62,BIGJOB60
BIGJOB63,BIGJOB62

BIGJOBOO'BIGJOB63+X'002F2'~

PHASE

XFR-AD

LOCORE

HICORE

DSK-AD

ESD TYPE

LABEL

LOADED

REL-FR

BIGJOB

003000

0015A3

64 04 1

CSECT

BIGJOB

003000

CSECT
* ENTRY
CSECT

ILBDSEMO
CURSEGM
ILBDSRTO

006268

006B38

CSECT
CSECT
CSECT
CSECT
CSECT
CSECT
CSECT
CSECT
CSECT

BIGJOB10
BIGJOB41
BIGJOB48
BIGJOB49
BIGJOB50
BIGJOB60
BIGJOB62
BIGJOB63
ILBDDUMO

0015A8 0015A8
0015A8 0015A8
0015A8 0015A8
0015A8 0015A8
0015A8 0015A8
0015A8 0015A8
0075A8 0015A8
0075A8 0015A8
0018AO ......0018AO

BIGJOB10
BIGJOB41
BIGJOB48
BIGJOB49
BIGJOB50
BIGJOB60
BIGJOB62
BIGJOB63
BIGJOBOO
Figure 21.

0015A8
0015A8
0075A8
0015A8
0015A8
0075A8
0015A8
0015A8
0018AO

Link

0015A8
0015A8
0015A8
0015A8
0015A8
0015A8
0075A8
0075A8
0018AO

0015E9
001899
0015DB
0015D3
0015F1
0016ED
0015D1
001621
0018A1

64
65
65
65
65
65
65
65
65

09
00
00
01
01
02
02
03
03

2
1
2
1
2
1

2
1

,
,,
I

TRANSIENT
AREA

Including COBOL subroutines and called programs

Overlayable and independent segments

I
I
ISORT PROGRAM,
I

= length

Figure 28.

of the largest segment in bytes.

Location of Sort Program in a Segmentation structure

I
I
I

: l;.

00631D~.------~(!)

Editing a Segmented Program

ROOT

PART II

PROCESSING COBOL FILES ON

PROCESSING 3540 DISKETTE

~ASS

STORAGE

DEVICES----~~

FILES=-==-----------------~~

VSA!----------------------------------------------.~

DETAILED FILE PROCESSING

PROCESSING ASCII TAPE

RECORD

CAPABILITIES--------------~. ~

FILES------------------------.~

FORftATS------------------------------------~. ~

PROCESSING COBOL PILES ON MASS STORAGE DEVICES
A mass storage device is one on which
records can be stored in such a way that
the location of anyone record can be
determined without extensive searching.
Records can be accessed directly rather
than serially.

sequential, direct, indexed, and VSAM. VSAM
is discussed in the chapter entitled "Virtual
Storage Access Method (VSAM)."

The recording surface of a mass storage
device is divided into many tracks. A ~
track is defined as a circumference of the
recording surface. The number of tracks
per recording surface and the capacity of a
track for each device are shown in Table 9.

In a sequential file, records are
organized solely on the basis of their
successive physical location in the file.
The records are read or updated in the same
order in which they appear.

Table

Recording Capacities of Mass
storage Devices

1Device
I
12311
1

1
12314,
12319
I
12321
1

Capacity

1200 tracks per surface; 3625
1 bytes per track.
1
1200 tracks per surface; 7294
1 bytes per track.
I
1100 tracks per strip; 2000
I bytes per track.

DIRECT ORGANIZATION
A file with direct organization is
characterized by some predictable
relationship between the key of a record
and the address of that record on a mass
storage device. This relationship is
established by the programmer.

1404 tracks per surface; 13030
I bytes per track.
I
I

3330-11* 1808 tracks per surface; 13030
I bytes per track.
I
3340
348 tracks per surface; 8368
Model 35
bytes per track.
3340
696 tracks per surface; 8368
Model 70
bytes per track.
13350
I

Individual records cannot be located
quickly. Records usually cannot be deleted
or added unless the entire file is
rewritten. This organization is used when
most of the records in the file are
processed each time the file is used.

13330

SEQUENTIAL ORGANIZATION

555 tracks per surface; 19069
bytes per track.

*In the COBOL ASSIGN statement the 3330-11
is specified as 333B.
Each device has some type of access
mechanism through which data is transferred
to and from the device. The mechanisms are
different for each device, but each
mechanism contains a number of read/write
heads that transfer data as the recording
surfaces rotate past them. Only one head
can transfer data (either reading or
writing) at a time.
FILE ORGANIZATION
Records in a file mus~ De logically
organized so that they can be retrieved
efficiently for processing. Four methods
of organization for mass storage devices
are supported by the DOS/VS COBOL compiler:

Direct organization is generally used
for files where the time required to locate
individual records must be kept to an
absolute minimum, or for files whose
characteristics do not permit the use of
sequential or indexed organization.
This organization method has
considerable flexibility. The accompanying
disadvantage is that although the Disk
Operating System/Virtual Storage provides
the routines to read or write a file of
this type, the programmer is largely
responsible for the logic and programming
required to locate the key of a record and
its address on a mass storage device.
Note: Direct organization is not supported
on fixed block devices.
INDEXED ORGANIZATION
An indexed file is similar to a
sequential file in that rapid sequential
processing is possible. The indexes
associated with an indexed file also allow
quick retrieval of individual records
through random access. Moreover, a
separate area of the file is set aside for
additions; this eliminates the need to
rewrite the entire file when adding
records, a process that would usuaily be
necessary with a sequentially organized
file. Although the added records are not

Processing COBOL Piles on Mass Storage Devices

physically in key sequence, the indexes are
constructed in such a way that the added
records can be quickly retrieved in key
sequence, thus making rapid sequential
access possible.
In this method of organization, the
system has control over the location of the
individual records. Since the
characteristics of the file are known, most
of the mechanics of locating a particular
record are handled by the system.
Note: Indexed organization is not supported
on fixed block devices.
DATA MANAGEMENT CONCEPTS
The data management facilities of the
Disk Operating System Virtual storage are
provided by a group of routines that are
collectively referred to as the
Input/Output Control System (IOCS). A
distinction is made between two types of
routines:
1.

Physical IOCS (PIOCS) -- the physical
input/output routines included in the
Supervisor. PIOCS is used by all
programs run within the system. It
includes facilities for scheduling
input/output operations, checking for
and handling error conditions related
to input/output devices, and handling
input/output interruptions to maintain
maximum input/output speeds without
burdening the programmer's problem
program.
Logical rocs (LIOCS) -- the logical
input/output routines linked with the
programmer's problem program. These
routines provide an interface between
the programmer's file processing
routines and the PIOCS routines.
LIOCS performs those functions that a
programmer needs to locate and access
a logical record for processing. A
logical record is one unit of
information in a file of similar
units, for example, one employee's
record in a master payroll file, one
part-number record in an inventory
file, or one customer account record
in an account file. One or more
logical records may be included in one
physical record. LIOCS refers to the
routines that perform the following
functions:

Blocking and deblocking records

Switching between input/output
areas when two areas are specified
for a file

Handling

and
conditions

end-of~file

end-of~olume

Checking and writing labels

A brief description of functions
performed by LIOCS and their relationship
to a COBOL program follows.
Whenever COBOL imperative-statements
(READ, WRITE, REWRITE, etc.) are used in a
program to control the input/output of
records in a file, that file must be
defined by a DTF (~efine !he rile) or, for
VSAM, an ACB (Access Method Control Block) •
A DTF or ACB is created for each file
opened in a COBOL program from information
specified in the Environment Division, FD
entry, and input/output statements in the
source program. The DTF for each file is
part of the object module that is generated
by the compiler. The ACB is generated at
object time. They describe the
characteristics of the logical file,
indicate the type of processing to be used
for the file, and specify the storage areas
and routines used for the file. Further
and more detailed onformation in VSAM is to
be found in the chapter "VSAM."
One of the constants in the DTF table is
the address of a logic module that is to be
used at execution time to process that
file. A logic module contains the coding
necessary to perform data management
functions required by the file such as
blocking and deblocking, initiating label
checking, etc.
Generally, these logic modules are
assembled separately and cataloged in the
relocatable library under a standard name.
At link edit time, the Linkage Editor
searches the relocatable library using the
virtual reference to locate the logic
module. The logic module is then included
as part of the program phase. vote that
since the Autolink feature of the Linkage
Editor is responsible for including the
logic modules, the COBOL programmer need
not specify any INCLUDE statements.
The type of DTF table prepared by the
compiler depends on the organization of the
file and the device to which it is
assigned. The DTF's used for processing
files assigned to mass storage devices are
as follows:
Sequential organization,
~equential access
DTFDA -- Direct organization,
sequential or random access
DTFIS -- Indexed organization,

For a 3540 diskette unit, the DTF is
DTFDU. Kore detail on this is given in the
chapter "Processing 3540 Diskette unit
Files."

SELECT [OPTIONAL] file-name

The remainder of this chapter provides
information about preparing programs which
process files assigned to mass storage
devices. Included are general descriptions
of the organization, the COBOL statements
that must be specified in order to build
the correct DTF tables, and coding
examples.

ASSIGN TO SYSnnn- {::}

SEQUENTIAL ORGANIZATION (DTFSD)
In a sequential file on a mass storage
device, records are written one after
another -- track by track, cylinder by
cylinder -- at successively higher
addresses.
Records may be fixed-length, spanned, or
variable-length, blocked or unblocked, or
undefined. Since the file is always
accessed sequentially, it is not formatted
with keys.
Processing a sequentially organized file
for selected records is inefficient. If it
is done infrequently, the time spent in
locating the records is not significant.
The slowest way is to read the records
sequentially until the desired one is
located. On the average, half of the file
must be read to locate one record.
Additions and deletions require a
complete rewrite of a sequentially
organized file on a mass storage device.
Sequential organization is used on mass
storage devices primarily for tables and
intermediate storage rather than for master
files.
Sequentially organized files formatted
with keys cannot be created using DTFSD.
DTFDA may be used to create and access
(sequentially or randomly)' such files.

2311
2314
2"321
2319
3-330
333B
3340
3350
FBAI

Optional clauses:
RESERVE Clause
FILE-LIM!T Clause
ACCESS MODE IS SEQUENTIAL
PROCESSING MODE IS· SEQUENTIAL
RERUN Clause
SAME Clause
APPLY WRITE-ONLY Clause ,(create only)
APPLY WRITE-VERIFY Clause (create or
update only)
Invalid clauses:
ACCESS MODE IS RANDOM
ACTUAL KEY Clause
NOMINAL KEY Clause
RECORD KEY Clause
TRACK-AREA Clause
MULTIPLE FILE TAPE Clause
APPLY EXTENDED-SEARCH Clause
APPLY CYL-OVERFLOW Clause
APPLY

MASTER-INDEX}
{ CIL-INDEX

Clause

APPLY CORE-INDEX Clause
DTFSD files may be opened as INPUT,
OUTPUT, or 1-0. When creating such a file,
an INVALID KEY condition·occurs when the
file limit has been reached and an attempt
is made to place another record on the mass
storage device. The file limit is
determined from the EXTENT control
statements.
When a DTFSD file is opened as OUTPUT,
each WRITE. statement signifies the creation
of a new record. When opened as 1-0, each
WRITE statement signifies that the record
just read is to be rewritten.
DIRECT ORGANIZATION (DTFDA)

PROCESSING A SEQUENTIALLY ORGANIZED FILE
To create, retrieve, or update a DTFSD
file, the following specifications should
be made in the source program:
ENVIRONMENT DIVISION
Required clauses:

With direct organization, there is a
definite relationship beteween the key of a
record and its address. This relationship
permits rapid access to any record if the
file is carefully organized. The
programmer develops a record address that
ranges from zero to some maximum by
converting a particular field in each
record to a track address. Each byte in
the address is a binary number. To

Processing COBOL Files on Mass Storage Devices

reference a particular record, the
programmer must supply both the track
address and the identifier that makes each
record unique on its track. Both the track
address and the identifier are supplied by
the programmer in the ACTUAL KEY clause.
This will be discussed in detail later in
this chapter.
With direct organization, records may be
fixed length, spanned or undefined. The
records must be unblocked. RO (record
zero) of each track is used as a capacity
record. It contains the address of the
last record written on the track, and is
used by the system to determine whether a
new record will fit on the track. The
capacity records are updated by the system
as records are added to the file. The
capacity records do not account for
deletions: as far as the system is
concerned, once a track is full it remains
full (even if the programmer deletes
records) until the file is reorganized.
Often, more records are converted to a
given track address than will actually fit
on the track. These surplus records are
known as overflow records and are usually
written into a separate area known as an
overflow area.
As already noted, the programmer has an
unlimited choice in deciding where records
are to be located in a directly organized
file. The logic and programming are his
responsibility.
When creating or making additions to the
file, the programmer must specify the
location for a record (track address) and
the identifier that makes each recor~ on
the track unique. If there is space on the
track, the system writes the record and
updates the capacity rGcord. If the
specified track is full, a standard error
condition occurs, and the programmer may
specify another track address in his USE
APTER STANDARD ERROR declarative routine.
In the case of one maximum size record
per track (when spanned records are not
specified), the data length plus the length
of the symbolic key cannot exceed the
following values:
2311 -- 3605 bytes
2314, 2319 -- 7249 bytes
2321
1984 bytes
3330
12974 bytes
3340
8293 bytes
3350
18987 bytes
When reading or updating the file, the
programmer must supply the track address
and the unique identifier on the track for
the specific record being sought. The
system locates the track and searches that
track for the record with the specified
100

identifier. If the record is not found,
COBOL indicates this to the programmer by
raising an INVALID KEY condition. Only the
track specified by the programmer is
searched. If EXTENDED-SEARCH is applied,
the search for a specified record key begins
on the track specified and continues until
one of two conditions occurs:
1.

The record is found.

The end of the specified cylinder
is reached.

In the second case, the INVALID-KEY option
of the READ or REWRITE is executed. To
ensure file integrity, the upper limit of
each extent of a file using EXTENDED-SEARCH
must be the last track of a cylinder.

Error recovery from a DTPDA file is
described in detail in the chapter
"Advanced Processing Capabilities."

ACCESSING A DIRECTLY ORGANIZED PILE
A directly organized file (DTPDA) may be
accessed either sequentially or randomly.
ACCESSING A DIRECTLY ORGANIZED PILE
SEQUENTIALLY: When reading a direct file
sequentially, records are retrFeved in
logical sequence; this logical sequence
corresponds exactly to the physical
sequence of the records. To retrieve a
DTPDA file sequentially, the following
specifications are made in the source
program:
ENVIRONMENT DIVISION
Required clauses:
SELECT [OPTIONAL] file-name

ASSIGN TO SYSnnn-DA-

2311
2321
2314
2319
3330
333B
3340
3350

Optional clauses:
PILE-LIMIT Clause
ACCESS MODE IS SEOUENTIAL
PROCESSING MODE IS SEOUENTIAL
ACTUAL KEY Clause
RERUN Clause
SAME Clause

Invalid clauses:
R~SERVE

Clause
ACCESS MODE IS RANDOM
NOMINAL KEY Clause
RECORD KEY Clause
TRACK-AREA Clause
MULTIPLE FILE TAPE Clause
APPLY WRITE-ONLY Clause

Processing COBOL Files on Mass Storage Devices

100.1

APPLY CORE-INDEX Clause

APPLY CYL-OVERFLOW Clause
APPLY EXTENDED- SEARCH Clause
APPLY WRITE-VERIFY Clause

APPLY

MASTER-INDEX}
{ CYL-INDEX

Note that in the ASSIGN clause, an A
must be specified for files with actual
track addressing, and a ~ must be specified
for files with relative track addressing.

Clause
To retrieve or update a directly
organized file randomly, the following
specifications must be made in the source
program.

APPLY CORE-INDEX Clause
When DTFDA records are retrieved
sequentially, the file may be opened only
as INPUT. The AT END condition occurs when
the last record has been read and execution
of another READ is attempted.

ENVIRONMENT DIVISION
"Required clauses:
SELECT file-name

Note that in the ASSIGN clause, an A
must be specified for files with actual
track addressing, and a ~ must be specified
for files with relative track addressing.

ASSIGN TO SYSnnn-DA-

ACCESSING A DIRECTLY ORGANIZED FILE
RANDOMLY: To create a directly organized
file randomly, the following specifications
are made in the source program:

ACCESS MODE IS RANDOM
ACTUAL KEY Clause

ENVIRON8ENT DIVISION
Required clauses:
SELECT file-name

2311

1J-

~~~~ {A}

2319
330
.3333B
3340
3350

ASSIGN TO SYSnnn-DA-

ACCESS MODE IS RANDOM
ACTUAL KEY Clause

2311
2314
2321
2319
3330
333B
3340
3350

-m

Note that in the ASSIGN clause an A must
be specified for files with actual track
addressing, a Q must be specified for files
with relative track addressing, a [ must be
specified for files wlth actual track
addressing when the REWRITE statement is
used, and ! must be specified for files
with relative track addressing when the
REWRITE statement is used.
The optional and invalid clauses are the
same as those specified previously for
creating a directly organized file.
Exception: APPLY EXTENDED-SEARCH is
optional when retrieving or updating a
directly organized file randomly.

Optional clauses:
FILE-LIMIT Clause
PROCESSING MODE IS SEQUENTIAL
RERUN Clause
SAftE Clause
APPLY WRITE-VERIFY Clause
Invalid clauses:
RESERVE Clause
ACCESS KODE IS SEQUENTIAL
NOMINAL KEY Clause
RECORD KEY Clause
TRACK-AREA Clause
MULTIPLE FILE TAPE Clause
APPLY WRITE-ONLY Clause
APPLY EXTENDED-SEARCH Clause
APPLY WRITE-VERIFY Clause
APPLY CIL-OVERFLOW Clause
APPLY{

MASTER-INDEX}
CYL-INDEX

Clause

ACTUAL KEY CLAUSE
Note that the ACTUAL KEY clause is
required for DTFDA files when ACCESS IS
RANDOM, is optional for DTFDA files when
ACCESS IS SEQUENTIAL, and is not used for
DTFSD files.
The actual key consists of two
components. One component expresses the
track address at which the record is to be
placed for an output operation, or at which
the search is to begin for an input
operation. The track address can be
expressed either as an actual address or as
a relative address, depending upon the
addressing scheme chosen when the file was
created. The other component is associated
with the record itself and serves as its
unique identifier. The structures of both
actual keys are shown in Figure 29.
Processing COBOL Files on Mass Storage Devices

101

Actual Key

through 258 bytes in length. It must be
defined in the File Section, the WorkingStorage Section, or the Linkage section.
The first four byte~ of data-name are the
track identifier. The identifier is used
to specify the relative track address for
the record and must be defined as an
8-integer binary data item whose maximum
value does not exceed 16,777,215. The
remainder of data-name, which is 1 through
254 bytes in length, is the record
identifier. It represents the symbolic
portion of the key field used to identify a
particular record on a track.

I
'

IActual Track IRecord Identifier,
,Address
,

Byte

8 9

263

,
Actual Key
I
f
i
,
I Relative
IRecord Identifier,
,Track Address I
,
IByte

4 5

Figure 29.

For a complete discussion.of the ACTUAL
KEY clause, see the publication IBM DOS
Full American National Standard COBOL.

258

structures of the Actual Key

The format of the ACTUAL KEY clause is:

Randomizing Technigues

ACTUAL KEY IS data-name
One method of determining the value of
the track address portion of the field
defined in the ACTUAL KEY clause is
referred to as indirect addressing.
Indirect addressing generally is used when
the range of keys for a file includes a
high percentage of unused values. For
example, employee numbers may range from
000001 to 009999, but only 3000 of the
possible 9999 numbers are currently
assigned. Indirect addressing is also used
for nonnumeric keys. Key, in this
discussion, refers to that field of the
record being written that will be converted
to the track address portion.

When actual track addressing is used,
data-name may be any fixed item from 9
through 263 bytes in length. It must be
defined in the Working-Storage, File, or
Linkage Section. The first eight bytes are
used to specify the actual track address.
The structure of these bytes and
permissible specifications for the mass
storage devices are shown in Figure 30.
The programmer may select from 1 to 255
bytes for the record identifier portion of
the actual key field.
Note: If a SEEK statement is used when
retrieving a direct file randomly, actual
track addressing is required.

Indirect addressing signifies that the
key is converted to a value for the actual
track address by using some algorithm
intended to limit the range of addresses.

When relative track addressing is used,
data-name may be any fixed item from 5
Cell

Pack
B

I 2311
I
I 2314
I
I 2321
I
I 3330

I 3330-11

,
,,
I

I
I
I

0-221

,,
,,

I
I

0-221

,
!
,,
I

2
0
0
0-9
0
0

Record

Head

I
5 I

0-199

0 I 0-9

I 0

0-199

0 I 0-19

,,
,,,
I

0-19

I
I
1
I

,
r
I
I

,
,

0-4

0-9

0-403

0
0
0-221
1 3340 Model 351
I
0
3340 Model 701
0-221
0
I
f
I
I 3350
0-221
0
I 0
I
I
I
I
Figure 30. Permissible Specifications for
102
~

Cylinder

,
,,,
,,

0-19
0-18

0 I 0-18

0-347

0 I 0-11

0-695

0-554

r
0 I 0-29

,,,
I

0-807

0-11

I
I
I

0-255

I
I
I

0-255

,
I
!
I
I
I
1
I

I
I

0-255

0-255
n_~~~
v-~~~

0-255
0-255
0-255

the First Eight Bytes of the Actual Key

Such an algorithm is called a randomizing
techniqug. Randomizing techniques need not
produce a unique address for every record
and, in fact, such techniques usually
produce synonyms. Synonyms are records
whose keys randomize to the same address.
Two objectives must be considered in
selecting a randomizing technique:
1.

Every possible key in the file must
randomize to an address within the
designated range.

can be accomplished by moving the key
to a field described as COMPUTATIONAL.
4.

Divide the key by the prime number
selected.

Ignore the quotient; utilize the
remainder as the relative location
within the data file.

(For actual track addressing only)
Locate the beginning of the space
available and manipulate the relative
address, to the actual device address
if necessary.

The addresses should be distributed
evenly across the range so that there
are as few synonyms as possible.

Note that one way to minimize synonyms
is to allocate more space for the file than
is actually required to contain all the
records. For example, the percentage of
locations that are actually used might be
80% to 85% of the allocated space.
When actual track addressing is used,
the first eight bytes of the ACTUAL KEY
field can be thought of as a "discontinuous
binary addres~." This is significant to
the programmer because he must keep two
considerations in mind. First, the
cylinder and head number must be in binary
notation, so the results of the randomizing
formula must be in binary format. Second,
the address is "discontinuous" since a
mathematical overflow from one element
(e.g., head number) does not increment the
adjacent element (e.g., cylinder number).
DIVISION/REMAINDER METHOD: One of the
simplest ways to indirectly address a
directly organized file is by using the
division/remainder method.
(For a
discussion of other randomizing techniques,
see the publication Introduction to IBM
Direct Access Storage Devices and
Organization Methods, Order No.
GC20-16 49.)
1.

Determine the amount of locations
required to contain the data file.
Include a packing factor for
additional space to eliminate
synonyms. The packing factor should
be approximately 20% of the total
space allocated to contain the data
file.

Select, from the prime number table,
the nearest prime number that is less
than the total of step 1. A Erime
number is a number divisible only by
itself and the integer 1. Table 10 is
a partial list of prime numbers.

Clear any zones from the first eight
bytes of the actual key field. This

For example, assume that a company is
planning to create an inventory file on a
2311 disk storage device. There are 8000
different inventory parts, each identified
by an 8-character part number. Using a 20%
packing factor, 10,000 record positions are
allocated to store the data file.
Method A: The closest prime number to
10,000, but under 10,000, is 9973. Using
one inventory part number as an example, in
this case #25DF3514, and clearing the zones
we have 25463514.
Dividing by 9973 we get
a quotient of 2553 and a remainder of 2445.
2445 is the relative location of the record
within the data file corresponding to part
number 25DF3514. The record address can be
determined from the relative location as
follows:
1.

(For actual track addressing only)
Determine the beginning point for the
data file (e.g., cylinder 100, track
0) •

Determine the number of records that
can be stored on a track (e.g., twelve
per track on a 2314 disk pack,
assuming each inventory record is 200
bytes long).
Because each data record contains
non-data components, such as a count
area and interrecord gaps, track
capacity for data storage will vary
with record length. As the number of
separate records on a track increases,
interrecord gaps occupy additional
byte positions so that data capacity
is reduced. Track capacity formulas
provide the means to determine total
byte requirements for records of
various sizes on a track. These
formulas can be found in the
publications IBM Component
Descriptions, Order Nos. GA26-5988
and GA26-3599.

Divide the relative number (2445) by
the number of records to be stored on
each track.

Processing COBOL Files on

~ass

storage Devices

103

4B.

(For actual track addressing only)
The result, quotient = 203, is now
divided into cylinder and head
designation. Since the 2311 disk pack
has ten heads, the quotient of 203 is
divided by 10 to show:

The number of records that may be
contained on one track is twelve.
Therefore, if 10,000 record locations
are to be provided, 834 tracks must be
reserved.

Cylinder or CC = 20
Head or HH = 03 (high-order zero
added)

The prime number nearest, but less
than 834, is 829.

(For relative track addressing only)
The result, quotient = 203, now
becomes the track identifier of the
actual key.

Divide the zone-stripped key by the
prime value.
(In the example,
25463514 divided by 829 provides a
quotient of 30715 and a remainder of
779. The remainder is the relative
address.)

Method B: utilizing the same example,
another approach will also provide the
relative track address:

104

I
·1
I
I
I
I
I
I
I
I

Partial List of Prime Numbers
(Part 2 of 2)

Table 10.

Partial List of·Prime Numbers
(Part 1 of 2)

Table 10.
A

(Number)
500
600
700
800
900
1000
1100
1200
1300
1400
1500
1600
1100
1800
1900
2000
2100
2200
2300
2400
2500
2600
2700
2800
2900
3000
3100
3200
3300
3400
3500
3600
3700
3800
3900
4000
4100
4200
4300
44'00
4500
4600
4700
4800
4900
5000
5100
5200
5300
5400
5500

(Nearest Prime Numberl
Less Than A)
I
499
599
691
797
887
991
1097
1193
1291
1399
1499
1591
1699
1789
1889
1999
2099
2179
2297
2399
2477
2593
2699
2797
2897
2999
3089
3191
3299
3391
3499
3593
3697
3797
3889
3989
4099
4177
4297
4397
4493
4597
4691
4799
4889
4999
5099
4197
5297
4399
5483

(Number)
5600
5700
5800
5900
6000
6100
6200
6300
6400
6500
6600
6700
6800
6900
7000
7100
7200
7300
7400
7500
7600
7700
1800
7900
8000
8100
8200
8300
8400
8500
8600
8700
8800
8900
9000
9100
9200
9300
9400
9500
9600
9100
9800
9900
10,000
10,100
10,200
10,300
10,400
10,500
10,600

1
(Nearest Prime Number 1
Less Than A)
1
I
5591
5693
5791
5897
5987
6091
6199
6299
6391
6491
6599
6691
6793
6899
6997
7079
7193
7297
7393
7499
7591
7699
7793
7883
7993
8093
8191
8297
8389
8467
8599
8699
8793
8899
8899
9091
9199
9293
9397
9497
9587
9697
9791
9887
9973
10,099
10,193
10,289
10,399
10,499
10,597

Processing COBOL Files on Mass Storage Devices

105

(For actual track addressing only) To
convert the relative address to an
actual device address, divide the
relative address by the number of
tracks in a cylinder. The quotient
will provide the cylinder number and
the remainder will be the track
number. For example, the 2311 disk
pack would utilize 779 as:
Cylinder or CC = 77
Track or HH = 9

Figure 31 is a sample COBOL program
which creates a direct file with actual
track addressing using Method Band
provides for the possibility of synonym
overflow. Synonym overflow will occur if a
record randomizes to a track that is
already full. The following description
highlights the features of the example.
Circled numbers on the program listing
correspond to the numbers in the text.
The value 10 is added to TRACK-1 to
ensure that the problem program does
not write on cylinder o. Cylinder 0
must be reserved for the Volume Table
of Contents.
• Since the prime number used as a
divisor is 829, the largest possible
remainder will be 828. Adding 10 to
TRACK-1 adjusts the largest possible
remainder to 838.
If synonym overflow occurs, control is
given to the error procedure
declarative specified in the first
section of the Procedure Division.
The declarative provides that:
• Any record which cannot fit on a
track (i.e., tracks 0 through 8 of
any cylinder) will be written in the
first available position on the
following track(s).
• Any record which cannot fit within a
single cylinder will be written on
cylinder 84 (i.e., the cylinder
overflow area) •

106

• If a record cannot fit on either
cylinders 1 through 83, or on
cylinder 84, the job is terminated.

The standard error condition "no room
found" is tested before control is
given to the synonym routine. Other
standard error conditions as well as
invalid key conditions result in job
termination.

ERROR-COND is the identifier which
specifies the error condition that
caused control to be given to the
error declarative. ERROR-COND is
printed on SYSLST whenever the error
declarative section is entered.
TRACK-ID and C-REC are also printed on
SYSLST. They are printed before the
execution of each WRITE statement.
This output has been provided in order
to facilitate an understanding of the
logic involved in the creation of
D-FILE.

The first twelve records which
randomize to cylinder 002 track 8 are
actually written on track 8.
The next twelve records which
randomize to cylinder 002 track 8 are
adjusted by the SYNONYM-ROUTINE and
written on cylinder 002 track 9.
The next twelve records which
randomize to cylinder 002 track 8 are
adjusted by the SYNONYM-ROUTINE and
written on cylinder 84 track 0 (i.e.,
the overflow cylinder) •
The last two records which randomize
to cylinder 002 track 8 are adjusted
by the SYNONYt-ROUTINE and written on
cylinder 84 track 1 (i.e., the
overflow cylinder).

// JOB METHODBA
// OPTION NODECK,LINK,LIST,LIS'I'X,SYM,E£l.RS
// EXEC FCOBOL

IBM DOS VS COBOL

REL 1. 0

PP NO. 5746-CB1

OS.47.44

10/04/73

IDENTIFICATION DIVISION.
PROGRM-1-ID. METhOD-B.
ENVIRON¥£NT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. IBM-370.
OBJECT-COMPUTER. IBM-370.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT D-FILE ASSIGN SYS015-DA-2314-A-MASTER
ACCESS IS RANDOM
ACTUAL KEY IS ACT-KEY.
SELECT C-FILE ASSIGN TO SYS007-UR-2540K-S.
DATA DIVISION.
FILE SECTION.
FD D-FILE
LABEL RECORDS ARE STANDARD.
01 D-REC.
02 PART-NUM PIC X(8).
02 NUM-ON-HAND PIC 9(4).
02 PRICE PIC 9(5)V99.
02 FILLER PIC X(lS1).
FD C-FILE
LABEL RECORDS ARE OMI'I'TED.
01 C-REC.
02 PART-NUM PIC XeS).
02 NUM-ON-HAND PIC 9(4)9.
02 PRICE PIC 9(5)V99.
WORKING-STORAGE SECTION.
71 HD
PIC 9 VALUE ZERO.
77 SAVE PIC S~(S) COMP SYNC.
77 QUOTIENT PIC S9(5) COMP SYNC.
01 ERROR-COND.
02 FILLER PIC 99 VALUE ZERO.
02 ERR
PIC 9 VALUE ZERO.
02 FILLER PIC 9(5) VALUE ZERO.
01 TRACK-l
PIC 9999.
01 TRACK-ID REDEFINES TRACK-l.
02 CYL PIC 999.
02 HEAD PIC 9.
01 KEY-1.
02 M
PIC S999 COMP SYNC VA~UE ZEROES.
02 BB PIC S9 COMP SYNC VALUE ZERO.
02 CC PIC S999 COMP SYNC.
02 HH PIC 8999
COMP SYNC.
02 R
PIC X
VALUE LOW-VALUE.
02 REC-ID
PIC xes).
01 KEY-2 REDEFINES KEY-l.
02 FILLER PIC x.
02 ACT-KEY PIC X(16).

Figure 31.

Creating a Direct File Using Method B (Part 1 of 4)

Processing COBOL Files on Mass Storage Devices

107

IBM DOS VS COBOL

REL 1. 0

PP NO. 5746-CBl

08.47.44

10/04/73

I
PROCEDURE DIVISION.
DECLARATIVES.
ERROR-PROCEDURE SECTION. USE AFTER STANDARD ERROR PROCEDURE
ON D-FILE GIVING ERROR-COND.

ERROR-ROUTINE.
EXHIBI'I' NAt! DOS VS COBOL

TRACK-ID =
ERROR-COND
TKACK-ID =
TRACK-ID =
ERROR-COND
TRACK-ID
TRACK-ID
TRACK-ID
TRACK-ID
TRACK-ID
BHROR-COND
TRACK-Ill =
TRACK-ID =
ERROR-COND
TRACK-ID =
TRACK-ID =
ERROR-COND
TRACK-ID =
TRACK-ID =
ERRoR-corm
TRACK-ID =
TRACK-ID =
ERKOR-COND
TRACK-ID =
TRACK-ID =
ERROR-COi'm
TRACK-ID =
TRACK-ID =
EJ:{ROR-COND
TRACK-ID =
TRACK-ID =
ER,WR-COND
TRACK-ID =
TRACK-ID =
ERROR-COND
TRACK-ID =

0028 C-RBC

5746-CE.:i.

pp NO.

8290001825

002 rid

008

8290001825
8290001826

CC
CC

002 Bti
002 hti

009
008

8290001826
8290001827
8290001828
8290001829
8290001830

cc
CC
CC
CC
CC

002
001
001
001
002

HH
hH
HH
HH
HH

009
001
001
001
008

8290001830
8290001831

CC
CC

002 HH
002 hH

009
008

8290001831
8290001832

CC
CC

002 nil
002 Hd

009
008

8290001832
8290001833

CC
CC

002 HH
002 hH

009
008

8290001833
8290001834

CC
CC

002 Hd
002 HH

009
008

8290001834
8290001835

CC
CC

002 tiH
002 HH

009
008

8290001835
8290001836

CC
CC

002 HH
002 HH

009
008

8290001836
8290001837

CC
CC

002 HH
002 HH

009
008

8290001837
8290001838

CC
CC

002 HH
002 Hd

009
008

8290001838

002 tiH

009

= 00100000

0028 C-REC
0028 C-REC
= 00100000
0028 C-REC
0011 C-REC
0011 C-REC
0011 C-REC
0028 C-REC
= 00100000
0028 C-REC
0028 C-REC
= 00100000
0028 C-REC
0028 C-REC
= 00100000
0028 C-REC
0028 C-REC
= 00100000
0028 C-REC
0028 C-REC
= 00100000
0028 C-REC
0028 C-REC
= 00100000
0028 C-REC
0028 C-REC
= 00100000
0028 C-REC
0028 C-REC
= 00100000
0028 C-REC
0028 C-REC
= 00100000
0028 C-REC

Figure 31.

110

REi.. 1.0

Creating a Direct File Using Method B (Part 4 of 4)

08.47.44

10/04/73

Figure 32 is a sample COBOL program
which creates a direct file with relative
track addressing using Method B. The
sample program provides for the possibility
of synonym overflow. Synonym overflow will
occur if a record randomizes to a track
wh1ch is already full. The following
discussion highlights some basic features.
Circled numbers on the program listing
correspond to numbers in the text.

caused control to be given to the
error declarative. ERROR-COND is
printed on SYSLST whenever the error
declarative section is entered.
TRACK-ID and C-REC are also printed on
SYSLST before execution of each WRITE
statement. This output has been
provided in order to facilitate an
understanding of the logic involved in
the creation of D-FILE.

since the prime number used as a
A~~~~~~
~~.~~~~

Q?O

~_J'

~ho
~--

'~rnOQ+

---~---

remainder will be 828.

o
o

nnQQ;hlo
r-------

If synonym overflow occurs, control is
given to the USE AFTER STANDARD ERROR
declarative specified in the first
section of the Procedure Division.
The declarative provides that any
record that cannot fit on the track to
which it randomizes will be written on
the first subsequent track available.
The standard error condition "no room
found" is tested before control is
given to the SYNONYM-ROUTINE. Other
standard error conditions as well as
invalid key conditions result in job
termination (EOJ).'
ERROR-COND is the identifier which
specifies the error condition that

The first twelve records which
randomize to relative track 18 are
actually written on relative track 18.

The next twelve records which
randomize to relative track 18 are
adjusted by the SYNONYM-ROUTINE and
are actually written on relative track
19.

The next twelve records which
randomize to relative track 18 are
adjusted by the SYNONYM-ROUTINE and
are actually written on relative track
20.

(j)

The last two records which randomize
to relative track 18 are adjusted by
the SYNONYM-ROUTINE and are actually
written on relative track 21.

processing COBOL Files on Mass Storage Devices

111

// JOB METHODBR
// OP1ION NODECK,LINK,LIST,LISTX,SYM,~RRS
// EXEC FCOBOL

IBM DOS VS COBOL

REL 1. 0

PP NO. 5746-CB1

OS.40.53

10/04/73

eEL (jUOTL
IDENTIFICA~ION DIVISION.
PROGRAM-ID. METHODB.
ENVIRONtt..EN1' DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. IBM-370.
OBJEC'I-CONPUTER. IBM-370.
INPUT-OUTPUT SECTION.
FILE-COt."'TROL.
SELECT D-FILE ASSIGN TO SYS015-DA-2314-D-~ffiSTER
ACCESS IS RANDOM
ACTUAL KEY IS ACT-KEY.
SELECT C-FILE ASSIGN TO SYS007-UR-2540R-S.
DATA DIVISION.
FILE SECTION.
PD D-FILE
LABEL RECORDS ARE STANDARD.
01 D-REC.
05 PART-NUM PIC xes).
05 NUM-ON-HAND PIC 9(4).
05 PRICE PIC 9(S)V99.
05 FILLER PIC X(lSl).
FD C-FILE
LABEL RECORDS ARE OMITTED.
01 C-kEC.
05 PART-NU'·j PIC X(S).
05 NUM-ON-HAND PIC 9(4).
05 PRICE PIC 9(S)V99.
OS HLLER PIC X(61l.
WORKING-STORAGE SECTION.
77 SAVE PIC S9(S) COMP SYNC.
77 QUOTIENT PIC S9(8) COMP SYNC.
01 ACT-KEY.
02 ~RACK-ID PIC S9(S) COMP SYNC.
02 REC-ID PIC xes).
01 ERROR-COND.
02 FILLER PIC 99 VALUE ZERO.
02 ERR PIC 9 VALUE ZERO.
02 FILLER PIC 9(5) VALUE ZE~O.

Figure 32.

Creating a Direct File with Relative Track Addressing Using Method B (Part i
of 4)

112

IBM DOS VS COBOL

REL 1.0

PP NO. 5746-CB1

08.40.53

10/04/73

PROCEDURE DIVISION.
DECLA.RATIV.c:;S.
ERROk-PROCEDURE SECTION. USE AFTER STANDARD ERROR ~ROCEDURE
ON D-FILE GIVING EaROR-COl'lD.
ERROR-ROUTINE.
EXHIBIT ~lED ERROR-COND.
IF ERR = 1 GO TO SYd"ONYH-ROUTI~E ELSE
DISPLAY ·OTHER STANDARD ERROR W REC-ID
GO TO EOJ.
SYNONYM-ROUTINE.
IF 'I'RACK-Ii; IS LESS THAN 834. ADD 1 'I'O TRACK-Hi. GO 'I'O
WRITES.
END DECLARA'I'IVES.
OPE~~ INPUT C-FILE

J (;\
\.!.I

OUTPUT D-FILE.
READS.
READ C-FILE AT END GO TO EOJ.
MOVE CORRESPOl~DING C-IlliC TO D-REC.
l'jOVE PART-NUM OF C-REC 'I'O REC-ID. SAVE.
DIVIDE SAVE BY 829 GIVING QUOTIENT RLI."..AINDER TRACl\-ID.
WRITES.
EXHIBIT NAMED TKACK-ID C-REC.
WRITE D-REC INVALID KEY GO TO INVALID-KEY.
GO TO READS.
INVALID-KEY.
DISPLAY "INVALID KEY • REC-ID.
EOJ.
CLOSE C-FILE D-FILE.
STOP RUN.

'T'
}~

/ / LBVI'YP NSD (01)
/1 E.XEC LNKEDT

Figure 32.

Creating a Direct File with Relative Track Addressing Using Method B
(Part 2 of 4)

Processing COBOL Files on Mass Storage Devices

113

IBM DOS VS COBOL

REL 1.0

PP NO. 5746-CBl

08.40.53

/ / ASSG~ SYS007,X'OOC'

//
//
//
//

ASSGN SYS015,X'231'
DLbL ~ASTER,,99/365,DA
EXT6Nr SYS015,111111,r,0,20,840
EXEC

TiALLOCATION
specifies that a portion
an
already defined VSAM da~a space is
suballocated to the object.
Objects
with the SUBALLOCATION attribute dO
not appear in the VTOC.
Only the
name of the data space that
contains the object appears thErE.
If the object has the SUBALLOCATION
attribute, there must be a VSAM
data space defined on the volume on
which the object is being defined.

Virtual Storage Access Method

(VSAM)

133

• INDEXEDjNONINDEXFD
This parameter
specifies the type of cluster being
defined.
INDEXED
specifies that the cluster being
defined is for a key-sequenced
file.
This is the default.

Entry-Sequenced File Processing~ An
entry-sequenced file can only be processed
sequentially; therefore, since the default
is sequential, the ACCESS clause need not
be specified.

~seqUenCed

File Processing: A
key-sequenced file can be processed
; sequentially, randomly, or both
NONINDEXED
sequentially and randomly. To process
specifies that the cluster being
sequentially, ACCESS IS SEQUENTIAL is
defined is for an entry-seguenced
specified. To process randomly, ACCESS IS
file.
RANDOM is specified. To process both
sequentially and randomly, ACCESS IS
• KEYS (length position) -- This
DYNAMIC is specified.
parameter specifies the length and the ,.,~-.-.--.----__.__~____ ~~___ .."~ ___.",.~,.~~._.~~___~_____-------starting position of the key field
ACCESS IS DYNAMIC provides the greatest
within each logical record.
(Position
flexibility since all the capabilities of
o is the first byte in the logical
both sequential and random processing are
record.)
The key field with this
supported.
Processing can be switched
specified length, and starting in the
from sequential to random and vice-versa,
specified position, is in all logical
as many times as desiree.
records in a key-sequenced file. The
sum of length and position must be
equal to or less than the length of the
logical record.
Current Record Pointer
• UPDATEPW (password) -- This parameter
specifies the update level password
for the file being defined.
The
update level password permits input
and output operations (READ, START,
DELETE, WRITE, REWRITE) against the
logical records of the file.

Note that this file has no read-level
protection and that its master level
password is WRITEFL.
ATTEMPTS (count)
specifies the maximum number of
times the operator can try to enter
the password in response to a
prompting message. Count can be
any number from 0 through 7. The
value 0 prevents any password
prompting.
CATALOG (catalog name/password)
specifies the catalog and its update
level password that is to contain the
entries for the cluster.

File Processinq Technigues
The COBOL user has three different file
processinq technigues available to him;
~eguentiai, random, and a combination of
sequential and random.
The technique to be
used is specified through the ACCESS clause
of the SELECT statement.
134

The current record pointer (CRP), a
conceptual pointer, is applicable only to
key-sequenced files.
The current record
pointer indicates the next record to be
accessed by a sequential reguest; the CRP
has no meaning for random processing. The
CRP is affected only by the OPEN, START and
READ statements, it is not used or affected
by the WRITE, REWRITE, or DELETE
statements. The following are examples of
how the CRP is affected by various COEOL
statements.
Example 1:
Assuming a file has records with keys
from 1 to 10, if the sequence of I/O
operations on the file with ACCESS IS
DYNAMIC and opened 1-0 i~:
MOVE 7 TO RECORD-KEY
READ filename
H0VE 114 TO RECORD-KEY
fV-RITE record -name
READ filename NEXT RECORD
the READ NEXT reads record 8 if the
prev~ous READ was successful.
If the
prev~ous READ was not successful, the
STATUS KEY will be set to 94 (No Current
Record Pointer) when the READ NEXT is
attempted. This occurs independently of
the successful intervening WRITE.

Generally, the last request on a file
which establishes a CRP (OPEN, READ, or
START) must have been successful in order
for a sequential read to be successful.

OPEN INPUT

(CRP is set to first
record on file)

MOVE 5 TO RECORD-KEY
READ filename

(record 5 is read, CRP
is set to record 6)

READ filename
NEXT RECORD
(or indent a couple
of spac~s)

(record 6 is read, CRP
is set to record 7)

Example 2:
In this example, ACCESS IS SEQUENTIAL is
specified; therefore, records are retrieved
in ascending key sequence starting at the
position indicated by the CRP~
(Assume
this file has records with keys from 1 to
10. }

OPEN INPUT filename

(CRP is at first
record on the
file)

MOVE 10 TO RECORD-KEY
START filename

(CRP is now at
record 10)

READ filename

(record 10 is
read)

Move 41 TO PECORD-KEY
READ filename
NEXT RECORD
(or indent a couple
of spaces)

(record 7 is read, CRP
is set to record 8)

The last READ---NEXT RECORD does not read
record 41 even though the record key field
contained 41.
This is true because a
sequential read does not use the contents
of the record key to determine which record
to read, it uses the position of CRP as
established by a previous request.
If the
last READ had been a random read (no NEXT)
then record 41 would have been read~
Example 4:

MOVE 5 TO RECORD-KEY
START filename

(CRP is now at
record 5)

In this updating example, ACCESS IS
DYNAMIC is specified; the REWRITE statement
does not affect the CRP.
(Assume this file
has records with keys from 1 to 44.)

READ filename

(record 5 is read
CRP is set to
record 6)

OPEH I-O

READ filename

(record 6 is read
CRP is set to
record 7)

Note that the CRP can be changed randomly
through the use of the START statement.
All reading is then done sequentially from
that point.
In this example, if the START
request for record key 5 had failed with
no record found (File Status=23), the
three READ statements following would have
failed with no current record pointer
(File Status=94).

MOVE 10 TO RECORD-KEY
READ filename

(record 10 is read,
CRP is set at record
11 )

MOVE 44 TO RECORD-KEY
REWRI,=",E record-name

(record 44 is updated,
CRP is set at record 11)

READ filename
NEXT RECORD

(record 11 is read, CRP
is set at record 12)

MOVE 74 TO RECORD-KEY
REWRI'I'E

(fails, record not
found in this file)

READ NEXT

(record 12 is read,
CRP is set at record 13)

Example 3:
In this example ACCESS IS DYNA~IC is
specified. Therefore, records are accessed
randomly if READ is specified and
sequentially if READ NEXT is specified.
(Assume this file has records with keys
from 1 to 44.)

(CRP is at first
record on file)

Note that although the last REWRITE failed,
the following READ NEXT was successful.

Virtual Storage Access Method

(VSA M)

135

Table 11.

File Status Values and Error Handling

I
No USE Declarative
l-,
I
I No AT END or
IFirst CharacterlAT END or INVALIDIINVALID KEY
lof FILE STATUS IKEY clause
I clause
I
I
,
I
0
IReturn to next
IReturn to next
I
I sentence
I sentence
I
I
I
I
1
I Return to AT END IReturn to next
I
I address
I sentence
I
I
I
I
I
I
tI
I
I
2
IReturn to INVALIDIReturn to next
I
IKEY address
I sentence
I
I
I
I
I
I
I
I
I
(
3
IWrite message and write message
I
Ireturn to next
and return to
next sentence
I
I sentence
I
I
I
I
I
9
(Return to next
Return to next
I
I sentence
sentence
I
I
I
I

USE Declarative
I
I
i
INo AT END or
I
IAT END or INVALID IINVALID KEY
,clause
(KEY clause

IReturn to next
IReturn to next
I sentence
I sentence
I
I
IReturn to AT END IReturn to next
Isentence after
I address
Ideclarative is
I
(executed
I
I
I
IReturn to INVALID IReturn to next
Isentence after
IKEY address
Idecla:rative is
I
I executed
I
I
I
IReturn to next
IReturn to next
Isentence after USElsentence after
Ideclarative is
Ideclarative is
lexecuted
I executed
I
I
IReturn to next
I Return to next
Isentence after USElsentence after
Ideclarative is
Ideclarative is
texecuted
lexecuted

I
USEI
I
I
I
I
USEI
I
I
f
I
USEI
I
I

I
I
USEI
I

ERROR HANDLING

Record Formats for VSAM Files

All errors on a VSAK file, whether logic
errors caused by the COBOL programmer (for
example, reading an unopened file), or 1-0
errors on the external storage media,
return control to the COBOL program. The
contents of FILE STATUS indicate the status
of the last request on the file. It is
strongly recommended that all files have a
file status associated with them, and that
the COBOL programmer check the contents of
FILE STATUS after each request.

For VSAM files, processing is
independent of whether or not the records
on a file are fixed-length (that is, all
records in the file are the same length)
or of variable-length format.

Table 11 describes the actions taken for
all the combinations of AT END, INVALID
KEY, and error declaratives for each value
of FILE STATUS.
Note: Return is always to NEXT STATEMENT
unless the request that caused the error
contained an AT END or INVALID KEY clause.
By omitting both the AT END and INVALID KEY
clauses and the USE ERROR/EXCEPTION for the
file, any type of error for the file can be
intercepted by checking the FILE STATUS
data name following each I/O request
(including OPEN and CLOSE) for the file.
This will simplify the exception-condition
handling in the COBOL program.

136

(

Thus for example, the considerations
which are discussed in "Record Formats For
Non-VSAM Files" generally do not apply.
However, the following points should
be considered:
• For record handling purposes, the
records are considered to be
fixed-length when
1.

All the records in the file are the
same size (or there is only one
record description) •

No record contains an OCCURS clause
with the DEPENDING ON option.
Otherwise, the records are
considered to be variable length.

• For variable length records, without
OCCURS DEPENDING ON clauses, the
following applies:

When a READ INTO statement is used, the
size of the longest record for the file
is moved to the input area. Coding
considerations for records with the
OCCURS DEPENDING ON option are
discussed in "Table Handling
Considerations. n
Initial Loading of Records into a File
A non-loaded file is one which has
been defined but has never contained
any records. An unloaded file is one
which has contained records but from
which all records have been deleted.
A loaded file is one which contains
records.

File Status Initialization
The value of uz, in Status Key 1 is
reserved for the programmer's use.
This
permits his determining whether a request
was made against his file.
For example, if
he initializes Status Key 1 to the value Z
before attempting to OPEN his file he can
then determine if his program actually
attempted the OPEN by checking the contents
of Status Key 1. If it is Z, the OPEN
statement was not executed; if it is a
value other than ZH the statement was
executed. This same technique can be used
for any request against the file GEN12 would
position the CRP to the first record in
the file whose key has the first two
characters greater than 01~

DELETE Statement
The DELETE is valid only for a
key-sequenced File. The same
considerations discussed under
"Key-Sequenced File Considerations for the'.
REWRITE Statement" apply to the DELETE
statement.

A COBO~ PFograromer can use VS~l~ in three
basic ways: to create a file, to retrieve
a file, and to update a file. However,
prior to. processing a VSAM file, it is an
absolute necessity that the previously
discussed Access Method Services functions
be performed. Most significant to the
COBOL programmer is whether the file is
defined as an entry-sequenced file or as a
key-sequenced file.
Creating a VSAM File
The minimum COBOL language statements
required to create a VSAM file are
summarized in Table 14.
Table 14.

COBOL Statements for Creating a
VSAM File

r-----------.---------------~----------~

I
I
I
I Entry-Seguenced I Key-Seguenced I
I
File
I
File
I
I
I
I
,
I Environment I SELECT
ISELEC~
I
I Division IASSIGN
IASSIGN
I
I
I
IORGANIZATION I
i
IS INDEXED
IRECORD KEY
I
IData
IFD entry
IFD entry
I
I Division ILABEL RECORDS
ILABEL RECORDS I
I
,
I
I
I Procedure IOPEN OUTPUT
IOPEN OUTPUT I
I Division I
or
I
or
I
IOPEN EXTEND
IOPEN EXTEND ,
,WRITE
,WRITE
,
I
,CLOSE
I CLOSE
I
I

Tne following discussion illustrates the
steps wnich must be taken to create an
entry-sequenced file. Assume the VSAM
catalog and vs~~~ data space have been
created as previously illustrated. The
next thing a user must do is define the
entry in the catalog for the VSAM file.
//

LTOB

DEFINE FILE

/ /

EXEC

IDCAMS t SIZE=1 OOK

DEFINE CLUSTER (NAME (TRANFILE)
VOI,UME ( 3 21 942) RECORDS ( 50 5)
RECORDSIZE(80 80) READPW(R0104) UPDATEPW(W0104) ATTEMPTS (0)
NONINDEXED SUBALLOCATION)
CATALOG (VSM1.CAT/SECRET)

/*
Virtual Storage Access Method (VSAM)

141

The meaning of the parameters is:
NAJ.\1E
(TRANFILE)

This is the data set name.

VOLUME
(321942)

This is the volume on which
the space for the data set
resides.

RECORDS
(50 5)

Primary allocation is for
50 records, secondary
allocation is for 5 records.

RECORDSIZE
(80 80)

The average and maximum
record size is 80 characters.

READPW
(RO 104)

The password R0104 must be
supplied to open the file
with the INPUT optio~

UPDATEPW
(W0104)

The password W0104 must be
supplied to open the file
with the OUTPUT, EXTEND or
1-0 option.

ATTEMPTS (0)

The operator is not to be
prompted for the password
when the file is opened.

NONINDEXED

The file is an entrysequenced file.

SUBALLOCATION

Space for this file is to
be suballocated from existing VSAM data space on the
volume.

CATALOG
(VSAMCAT/
SECRET)

The name of the catalog into
this file is cataloged
~s VSAMCAT and its update
password is SECRET.

~hich

The COBOL program to access such a I~Le
would include the following statements.
FILE-CONTROL.
SELECT VSAMSEQ
ASSIGN TO SYS010-AS-TESTFL
ORGANIZATION IS SEQUENTIAL
ACCESS IS SEQUENTIAL
PASSWORD IS VSAMPW
FILE
STATUS IS STATKEY•
I
DATA
FILE
FD
01

DIVISION.
SECTION.
VSAMSEQ
LABEL RECORDS ARE OMITTED.
VSAMREC.
05
FIELD1
PICTURE X(8).
05
FIELD2
PICTURE X(72).

WORKING-STORAGE SECTION.
77
STATKEY
PICTURE 99.
77
VSAMPW
PICTURE X(5).

PROCEDURE DIVISION.
BUILD-PASSWORD.
PERFORM PASSWORD-BUILDER.
PERFORM PASSWORD-SCRAMBLER.

OPEN OUTPUT VSAMSEQ.
IF STATKEY NOT = 0
GO TO ERROR-HANDLER.
BUILD-A-RECORD.

WRITE VSAMREC.
IF STATKEY NOT = 0
GO TO ERROR-HANDLER.

Note: When the user gains update access
to the file (by supplying the update level
of the password) he has also gained read
access.
In general, when a user gains
access to a file at a given level of
protection, he has gained access to that
file for all lower levels. This means that
the above file could be opened INPUT by
supplying the update level of the password.
However, it could not be opened OUTPUT,
EXTEND or 1-0 by supplying the read level
password.

142

GO TO BUILD-A-RECORD.

In this sample program the routines
PASSWORD-BUILDER and PASSWORD-SCRAMBLER
construct the update level password so
that the file can be opened OUTPUT. These
routines can be written in such a way
that they are difficult to follow, thus
improving security.

Note that the FILE-STATUS is checked
after each request on the fi~e: Thi~
ensures that unexpected condltlons wlll
be detected.
The JCL needed to execute the program is

II
II
II
II
II

JOB
ASSGN
DLBL
EXTENT
EXEC

SYS010 X'130'
TESTFL,'TRANFILE'"VSAM
SYS01 0,321942
program-name,SIzE=nnnk

Example 2:
This example shows the creation of a
COBOL key-sequenced VSA~ file. This
prQ~iam performs the same function as
~x·ample 1 except that now a key-sequ nced
7
file is being created. The records J.n the
file "INREC" are in ascending key order.
IDEN%IFICATION DIVISION.

ENVIRONMENT DIVISION.

PROCEDURE DIVISION.
PARA1.
OPEN INPUT INREe OUTPUT OUTREC.
IF CHK IS NOT ~ ~OO" GO TO CHKRTN.
PARA2.
READ INREC INTO OUTMASTER
AT END GO TO PARA4.
PARA3.
WRITE OUTMASTER.
IF CHK IS NOT = "00" GO TO CHKRTN.
GO TO PARA2.
PARA4.
CLOSE INREC OUTREC.
IF CHK IS NOT = "00" GO TO CHKRTN.
FINIT.
CLOSE INREC OUTREC.
STOP RUN.
CHKRTN.
DISPLAY "ERROR. STATUS KEY VALUE
IS" CHK
GO TO FINIT.
Note that in this example any Status Key
return other than 00 causes transfer of
control to paragraph CHKRTN. This routine
can determine the exact cause of the error
by checking the Status Key. Once the cause
is determined, instructions can be issued
according to the user's desired response to
each type of error.
Retrieving a VSAM File

INPUT~OUTPUT

SECTION.

FILE-CONTROL.
SELECT INREC
ASSIGN TO SYS005-UR-2540R-CARDIN.
SELECT OUTREC
ASSIGN TO SYS010-0UT~AST
ORGANIZATION IS INDEXED
RECORD KEY IS ARG-l
FILE STATUS IS CHK.

DATA DIVISION.
FILE SECTION.
FD INREC LABEL RECORDS ARE OMITTED
DATA RECORD IS INMASTER
01 INMASTER PIC X(80).
FD OUTREC LABEL RECORDS ARE STANDA.RD
DATA RECORD IS OUTMASTER.
01 OUTMASTER.
05 FILLER PIC X.
05 ARG-1 PIC XXX.
05 REM PIC X(76).
WORKING-STORAGE SECTION.
77 CHK PIC XX.

The mlnlmum COBOL language statements
required to retrieve a VSAM file are
summarized in Table 15.
Table 15.

COBOL Statements for Retrieving

a 'ISAM File
I
I
I
I Entry-Sequenced I Key-Sequenced I
File
,File
I
I
I
I
,
,
IEnvironmentlSELECT
I SELECT
I
I Division (ASSIGN
IASSIGN
I
I
I
IORGANIZATION I
,
I
I IS INDEXED I
I
I
I
I RECORD KEY
I
I
I
,
IData
IFD entry
IFD entry
I
I Division ILABEL RECORDS
ILABEL RECORDS I
I
I
I
I
IOPEN INPUT
I
I Procedure ,OPEN INPUT
I Division IREAD •••
IREAD
I
I
I AT END
I
I
I
ICLOSE
I CLOSE
I
,

virtual Storage Access Method (VSAM)

143

The following examples show the
retrieval of records from VSAM files.
Example 3:
This example shows the retrieval of
records from the entry-sequenced file
created in example 1. The records are then
printed.

Example 4:
This example shows the retrieval of
records from the key-sequenced file created
in example 2. Note that in the Procedure
Division there is a switch from sequential
processing to random processing; this is
permitted since ACCESS IS DYNA~IC is
specified in the ENVIRONMENT Division.
IDENTIFICATION DIVISION.

IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
ENVIRONMENT DIVISION

INPUT-OUTPUT SECTION.
FILE-CONTROL
SELECT INREC
ASSIGN TO SYS010-AS-INMAST
FILE STATUS IS CHK.
SELECT PREe
ASSIGN TO SYS005-UR-1403-S-PRNTR

DATA DIVISION.
FILE SECTION.
FD INREC LABEL RECORDS ARE STANDARD
DATA RECORD IS INMASTER.
01 INMASTER PIC X (80) •
FD PREC LABEL RECORDS ARE OMITTED
DATA RECORD IS POUT.
01 POUT PIC X(80).
WORKING-STORAGE SECTION.
77 CHK PIC xx.
PROCEDURE DIVISION.
PARA1.
OPEN INPUT INREC OUTPUT PREC.
IF CHK IS NOT = "00" GO TO CHKRTN.
PARA2.
READ INREC INTO POUT AT END GO TO
PARA4.
IF CHK IS NOT
"00" GO TO CHKRTN
PARA3.
WRITE POUT.
GO TO PARA2.
PARA4.
CLOSE OUTREC PREC.
IF CHK IS NOT = "00" GO TO CHKRTN.
FINIT.
STOP RON.
CHKRTN.
DISPLAY 'ERROR. STATUS KEY VALOE
IS' CHK.
GO TO FINIT.
Note that in this example any Status Key
return other than 00 causes transfer of
control to paragraph CHKRTN. This routine
can determine the exact cause of the error
by checking the Status Key.
Once the cause
is determined, instructions can be issued
according to the user's desired response to
each type of error.
144

INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT INREC
ASSIGN TO SYS010-INMAST
ORGANIZATION IS INDEXED
ACCESS IS DYNAMIC
RECORD KEY IS ARG-l
FILE STATUS IS CH~.
SELECT PREC
ASSIGN TO SYS005-UR-1403-S-PRINTR
DATA DIVISION.
FILE SECTION.
FD INREC LABEL RECORDS ARE STANDARD
DATA RECORD IS INMASTER.
01 INMASTER.
05 FILLER PIC X.
05

......
III
~

p..

ri-

00 00000

'"Jj
.....

......

(()

r.n
(I)

......
~

n
III

1--"
::;,

rw>

op0 0000000000000

11111 1111111 11111 11111 111111

222222222222222~

22 '22222 2222222 22222 2 ~ 2 2 2 2222 2 22 2 2222222222222

~44444

4444444 44444 4~ 444 444444 44444444444444

5 5 ~ 5 5 5 5 5555S55~ 5 5 ~555555555555555~ 55

~55555

5555555 55555 5 ~ 5 5 5 55 5 5 5 5 ~ 5 5555555555555

4444444~

~444444444444444~

71 ~777711771771717

P ~17177 1111717 17171 1 ~ 17 1 11711 7 ~ 1 7717171711717

8 B ~ S 8 8 8 368Se8SS & 8 ~38e838888888888e 88 ~88888 8888888 888 8 e 8.88 8 888 S 8 08 9SC88SSBRaeS8

9999 ~ ~ 9 ~ ~ 9 qs 995 ~ ~ ''3 S q 9999999999 S ~ ~ 9999999 9 9~ qg 9 9 9 9 S 9 9 9999999999999 g 9 9 9 9 9 S 9 9 ~ 9 9 9 9

til

'0
rl)

....
()

til

Notes:
I

11111111111111

11 11171 7111777

III

-lo

00 ~OOOOO 0000000 00000 O~OOO 00000

III

rt......

File
Seq.
No. o No.

1--"
Cl

tJ'

0
E
..:
o II

«I

66 6666 6 6666666E 66 ~666666666666666E 66 ~66666 6666666 666 6 6 6.666 66666 6 ~ 6 6666666666666

E!!
File Name Eo

Operatlon

1-3
t-'
tJ:i
t-'

«I

....

Ii 12

'4 I 1£ 11 hi

l'i 2l~

2121 2j 24 25

26~,

Jl 3~

3~ 3~ 3fo];

18 39

4'l.~

42 ':1 44

46 4)

4!1!11,)!a1 5.2

~1;i.4 ~

5151 SlS9 &0 5' &263 ... 6S f4 &7 '"

IBM_50...!1

Ilt J
L6L

Blank

OTF
Nome

L - 8 -5 punch---.J

Dote - yy/d or yy/dd or yy/ddd (on Input or Output)
Retention Period - d-dddd (on Output only)

6~ UI 1

;;,.

1J 14

1\ 7;'

1p '9

tv\aximum size TLBL fields
are shown.
• Any field (except Ident,
Operation, and Date)
may be from 1 position to
the maximum shown. IOCS
fi lis in the remaining
positions of the label field.
II Ident and Operation must
be as shown.
II Date may be 4- 6 positions;
Retention period, 1- 4.
2 If a field is omitted, shift the
following comma and fields
to the left.
IOCS supplies a default value
for the label field on output.
3 No comma fo Ilows the last
field used.

>lj

.....

Standard Tape File Label

H
(1)

Version Number

Ul
rt
Pl

System Code

File Identifier

!::1

0..
P.I
~1

0 R: I!

0..

:E 0 F: :

P.J

'"tJ
(1)
~

,..,-

.-..
ro

0 V'
I

OTF Name

bbbbbbbbbb

Volume
Serial
Number

!O 0 0
I

I
I
I

'-v-'

Supplied
by 10CS
On input, no values
are suppl ied and no
checking is performed.

t""4
Pl

f-'

Job Control TLBL Card

P.J
!::1

0..
~-'1

t""4
to
~

P.J
t1
AI
Ul

:::r
0

f-J.
!::1
'.0

:_:c
~,J.

!::1
f-JS

Oper-

File Name

ation

80 ~BOOO ~~OOOOOO OOOOOOOOOOOlOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO60000000000
I 2 3 4 5 • 7 1 ~ 10" 121314 I' I! I.' 11 II 20 21 :2 23 24 2Ii 2i

~I 21

2t 31131 3l ,oJ J, J5 • 31 II 3ll .,

~1 42 43 44 45 41 47 43

CJ 50

~1 52 53 .. ~

r.& 51 51

~. 50 ,. all 54 15 &I 17 SI .,

7t 71 72 73 14 15 71 77 71 79 10

I I 1 1 I 1 1 111111 1 1 1 1 1 1 1 1 1 1 1 1 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 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 lit tit lit 1 1 I 1

22 2 ~ 222 ~~222222 22222222222222222222222222222222222222222222222222222222222222222
33 3~333 3~333333 33333333333333333333333333333333333333333333333333333333333333333

44 4~444 ~'444444 44444444444444444444444444444444444444444444444444444444444444444

55 5~555 55555555 55555555555555555555555555555555555555555555 55555555 5555555555 55 5

6~666

66666666 6 6 6 6 666 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 66 6 6 666 6 & 6 6 6 &

S
~

11 11111 1 "1111 7 1 17177777717777777777777777777717711171111111117717717777171771771

(l)
I-Q

88 88888 8.888888 888888888868888888888888888888888881181888888881818888888 ••••••••

~ 99999999~99999999999999999999999999999999999999999999999999999999999999999999999

f-J.

ro
S

(l)

!::1

....-...

_ I2~.5 _~I ~" '2131"5"

IltLBLJ
Blank

OTF
Name

r:.,

1120 tI Z2 2324 25 2~ 2721~lI_3~l2 33 ~35 • 3711 U."4I43 4445 .47.4151515253 . . . 51SJ 51 • • '1 a a M • • •7 • • 111172 73 M 15 7171 7171.

LABEL PROCESSING CONSIDERATIONS

containing all the previously mentioned
labels as well as with unlabeled files.

Label considerations for VSAM are
discribed in the chapter "Virtual storage
Access Method (VSAK)".

If user standard labels are to be
created or checked in the COBOL program,
the USE AFTER BEGINNING/ENDING LABELS
declarative sentence and the LABEL RECORDS
clause with the data-name option must be
specified.

The labels which may appear on tape are
shown in Figures 40 and 41. The compiler
allows the programmer to work with files

Load Point Marker

1
I
V

R N
1

t---J
1

N R N

iii

N P

iii

'II'!

.....

P F R N

:r::

~..

iii

N P

iii

P R

Iii

IVIVI-IVIHIEI-IHIUI-IUI 1
I IEIEI-IEIUI-IUI IRIHI-IHIUI-IUI I
IOIOI-IOIDIDI-IDIHI-IHITI
ITIOIOI-IOITI-ITITIDIDI-IDIHI-IHITI
ILILI-ILIRIRI-IRILI-ILIMI FILE #lIMIFIFI-IFILI-ILIMIRIRI-IRILI-ILIMI FILE #2
11121-1811121-18111-181

R R N

P F
Iii

1 11121-18111-181

_ _ _ _~'~I~'~I~'~I~I~I~I~~I~I~I~'_________ 1

I· I

11121-18111-181
I

End of Tape Marker
I
I
V R R N
iii

N P

Iii

P R R

iii

Iii

IEIEI-IEIUI-IUI I 1
FILE #2 ITIOIOI-IOITI-ITITITI
IMIVIVI-IVILI-ILIMIMI
L-f

11121-18111-181

Required, processed by IOCS.
Permitted, but not written or checked, by IOCS and not available to
programmer.
Processed by IOCS and available to user.

R
N

P
igure 41.

Standard, User Standard, and Volume Labels

Load Point Marker
I
I
V
I

0
1

I AI I Al

R
1

C
i

I IL I ILl I
I i AI i AI i

IBI-IBITI
ITIBI-IEITI
lEI IEIMI FILE #lIMIEI lEI MI
ILl-ILl I
I ILl-ILl I
,IS II ,IS II I
,I IIS I IS II ,I

1
I
I
1

R
o
C

Figure 42.

ILl ILl I

f--J

Notes:

Required, processed by IOCS.
Optional.
Written by COBOL compiler.
Nonstandard Labels
Detailed File Processing Capabilities

165

Header labels are written or read when
the file is opened or when a volume switch
occurs. Trailer labels are written when
the physical end of the reel is reached, or
when a CLOSE REEL or CLOSE file-name is
issued. Trailer labels are read on each
reel except the last when a tapemark is
reached. For the last reel (i.e., EOF
labels), trailer labels are not read until
the file is closed.
For multivolume input files with
nonstandard labels, the programmer must
specify the inteqer-l option of the source
language ASSIGN clause, where integer-l is
the number of reels in the file. This
number can be overridden at execution time
by storing a nonzero integer in the special
register NSTD-REELS before opening the
file. The number of reels is then
available to the programmer while the file
is opened both in the special register
NSTD-RFELS and in the field reserved for
this purpose which precedes the DTF table
for DTFMT (see "DTF Tables" in this
chapter). In addition, the number of reels
remaining after each volume switch can also
be found in the field reserved for this
purpose which precedes the DTF table for
DTFMT.
When processing a multivolume file with
nonstandard labels (i.e., when the
data-name option of the LABEL RECORDS
clause is specified), if the proqrammer
wishes to stop reading or writing before
the physical end of a reel is reached, he
must set a switch in the appropriate
declarative section. In the Procedure
Division, he can either CLOSE REEL or CLOSE
FILE depending on the switch setting.
Volume switching is done by LIOCS when
CLOSE REEL is executed.

The second file on the input reel is
not used in this program and is
bypassed through use of the POSITION
option of the MULTIPLE FILE TAPE
clause.
The first and second input files are
closed by the execution of the CLOSE
statement with the NO REWIND option,
leaving the tape positioned in
mid-reel for the next OPEN.
All volumes with the exception of the
last volume of the multivolume output
file are closed by a close statement
with the REEL option. Volume
switching is performed as noted in
step@. The second and third input files
processed by the program are opened by
an OPEN statement with the NO REWIND
option.
At job completion, a standard CLOSE is
issued to reposition the tapes of the
closed files at their physical
beginnings.

(j)

An LBLTYP control statement is
included because a tape file requiring
label information is to be processed.

Alternate assignments have been made
for SYSOll. Eecause these alternate
assignments are in the sequence in
which the ASSGN statements are
submitted, the first volume of the
output file will be on tape drive 282,
the second on 283, and the third on
181.
When the first CLOSE OUT-PUT
REEL statement is executed, a standard
EOV label is written on the volume
assigned to drive 282 and the reel is
rewound and positioned at its physical
beginning. The next WRITE RECO
statement executed will then be
written on the volume mounted on drive
283.

Although the file OUT-PUT consists of
mUltiple volumes, only one TLBL
control statement need be submitted.

Note: An unlabeled multivolume tape file
should not be CLOSE WITH LOCK between two
reels.

Sample Programs
Figure 43 illustrates the manner in
which unlabeled input files on a multifile
volume are processed by a COBOL program.
The input volume contains four files, only
three of which are being used by the
program. This unused file, which resides
between the first and third file on the
volume. must be bypassed during file
processing. The program creates a single
multivolume file with standard labels.
All input files residing on the same
volume are assigned to the same
symbolic unit.
166

Figure 44 is a sample program that
illustrates the manner in which the
multivolume file created in Figure 43 is
read as an input file. The sample program
also creates a multifile volume with
standard labels.
fi~~ output files res~a~ng on the same
volume are assigned to the same
symbolic unit.

The name field of the system-name in
the ASSIGN clause is specified. This
is the external-name by which the file

~
~

is known to the system. When
specified, it is the name that appears
in the filename field of the DLBL or
TLBL job control statements.

The name field of the system-name of
the ASSIGN clause is specified. These
names will appear on the TLBL control
statements that refer to these files.

For the multivolume input file IN-PUT,
the AT END option of the READ
statement applies only to the last
volume containing the EOF label. For
prior volumes containing EOV labels,
automatic volume switching will take
place as indicated in the ASSGN
control statements pertaining to the
file IN-PUT.

The MULTIPLE FILE TAPE clause is not
required for the multifile volume
because each file is being processed
in the sequence in which it appears on
the reel.
A rewind will not be
executed for any file on the reel
except for that processed last.

The first and second file written on
the volume are closed using the NO
REWIND option of the CLOSE statement.
This option leaves the tape positioned
in mid-reel following the EOF label of
the file just closed.
At job's completion, a standard CLOSE
is issued to reposition the tapes of
the closed files at their physical
beginning.
A LELTYP control statement is included
because tape files requiring label
information are being processed.
There are three TLBL control
statements for the volume assigned to
SYS013, one for each file referenced
on the volume. The filename field of
the TLBL control statements for these
files contains the names used in the
ASSIGN clauses of the COBOL source
program, not the programmer logical
unit name.
Alternate assignments have been made
for SYS012 to handle the multiple
volumes of the file IN-PUT.
Figure 45 illustrates the creation of an
unlabeled multivolume file. The number of
output volumes is determined dynamically
during program execution. The program's
input consists of the labeled multifile
volume created in Figure 44.
All input files residing on the same
volume are assigned to the same
symbolic unit.

o
o

The CLOSE statement for files IN-PUT-1
and IN-PUT-2, and the OPEN statement
for files IN-PUT-2 and IN-PUT-3, use
the NO REWIND option. This leaves the
tape positioned in mid-reel for the
multifile volumets next OPEN
statement.
When it has been determined from the
input data that a new output reel is
required for the multivolume output
file, a CLOSE OUT-PUT REEL statement
is executed, processing is halted, and
a message is issued to the operator
which requests a new volume to be
mounted.
At job's compl~tion, a standard CLOSE
is issued to reposition the tapes of
the closed file at their physical
beginning.
An LBLTYP control statement is
included because tape files requiring
label information are being processed.
There are three TLBL control
statements for the volume assiqned to
SYS014, one for each file referenced
on the volume.
The filename field of
the TLBL control statements for these
files contains the names used in the
ASSIGN clauses of the source program
and not the programmer logical unit
names.
Only one tape drive is assigned to the
multivolume file OUT-PUT. Therefore,
each time a volume is closed,
processing must be halted and the
operator informed to mount a new tape.
This is illustrated in step~.

Detailed File Processing Capabilities

167

/1 JOB SAMPLE

UNLABELED MULTIFILE VOLUME TO MULTIVOLUME FILE WITH STANDARD LABELS

II OPTION LOG,DUMP,LINK,LIST,LISTX,XREF,SYM,ERRS,NODECK
/ / EXEC FCOBOL

000010
000020
000030
000040
000050
000060
000070
000080
000090
000100
000110
000120
000130
000140
000150
000160
000170
000180
000190
000200
000210
000220
000230
000240
000250
000260
000270
000280
000290
000300
000310
000320
000330
000340
000350
000360
000370
000380
000390
000400
000410
000420
000430
000440
000450
000460
000470
000480
000490
000500
000510
000520
000530

IDENTIFICATION DIVISION.
SAMPLE-l.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. IBM-370.
OBJECT-COMPUTER. IBM-370.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT iNPUT1 ASSIGN TO SYS010-UT-3410.-S-FILE1.}
SELECT INPUT2 ASSIGN TO SYS010-UT-3410-S-FILE2.
SELECT INPUT3 ASSIGN TO SYS010-UT-3410-S-FILE3.
SELECT OUT-POT ASSIGN TO SYS011-UT-3410-S.
I-O-CONTROL.
MULTIPLE FILE TAPE CONTAINS INPUTl POSITION 1 }
INPUT2 POSITION 3 •
INPUT3 POSITION 4
DATA DIVISION.
FILE SECTION.
FD INPUTl
RECORD CONTAINS 80 CP.ARACTERS
LABEL RECORD IS OMITTED.
01 RECl PIC X(80).
FD INPUT2
RECORD CONTAINS 80 CHARACTERS
LABEL RECORD IS OMITTED.
01 R~C2 PIC X(80).
FD INPUT3
RECORD CONTAINS 80 CHARACTERS
LABEL RECORD IS OMITTED.
01 BEC3 PIC X(80).
FD OUT-PUT
RECORD CONTAINS 80 CHARACTERS
BLOCK CONTAINS 3 RECORDS
LABEL RECORD IS STANDARD.
01 RECO PIC X(80).
PROCEDURE DIVISION.
OPEN INPUT INPUT1 OUTPUT OUT-PUT.
READ1.
PEAD INPUT1 INTO RECO AT END GO TO CLOSE1.
A. WRITE RECO.
B. GO TO READ1.
CLOSE1.
CLOSE INPUTl WITH NmEWIND.®
C. CLOSE OUT-PUT REEL. 4
D. OPEN INPUT INPUT2 WI H NO REWIND.f5\
READ2.
\V
READ INPUT2 INTO RECO AT END GO TO CLOSE2.
PERFORM A.
GO TO BEAD2.
CLOSF2.
(;\
CLOSE INPUT2 WITH NO REWIND. ~
PERFORM C.
OPEN INPUT INPUT3 WITH NO REwIND.
PROGRA~-ID.

Figure 43.

168

(!)

Processing an Unlabeled Multifile Volume

(Part 1 of 2)

000540 READ3.
READ INPUT3 INTO RECO AT END GO TO CLOSE3.
000550
PERFORM A.
000560
GO TO READ3.
000570
000580 CLOSE3.
000590
CLOSE INPUT 3 OUT-PUT.
STOP RUN.
000600

/ / LBLTYP TAPE
/ / EXEC LNKEDT

(J)

// ASSGN SYS010,X'281'
// ASSGN SYS011,X'282'
// ASSGN SYS011,X'283"ALT}
8
// ASSGN SYS011,X'181',ALT
// TLBL SYS011,'MULTI-VOL FILE',99/214
// EXEC

Figure 43.

Processing an Unlabeled Multifile Volume (Part 2 of 2)

Detailed Pile Processing Capabilities

169

/ / JOB SAMPLE
* LABELED MULTIVOLUME FILE TO LABELED MULTIFILE VOLUME
/ / OPTION LOG,DUMP,LINK,LIST,LISTX,XREF,SYM,ERRS,NODECK
/ / EXEC PCOBOL

IDENTIPICATION DIVISION.
PROGRAM-ID. SAMPLE-2.
ENVIRONMENT DIVISION.
CONPIGURATION SECTION.
SOURCE-COMPUTER. IBM-370.
OBJECT-COMPUTER. IBM-370.
INPUT-OUTPUT SECTION.
PILE-CONTROL.
SELECT IN-PUT ASSIGN TO SYS012-UT-3410-S.
SELECT OUT-PUTl ASSIGN TO SYS013-UT-3410-S-PILE1.}
SELECT OUT-PUT2 ASSIGN TO SYS013-UT-3410-S-FILE2.
SELECT OUT-PUT3 ASSIGN TO SYS013-UT-3410-S-FILE3.
DATA DIVISION.
.
PILE SECTION.
PD IN-PUT
RECORD CONTAINS 80 CHARACTERS
BLOCK CONTAINS 3 RECORDS
LABEL RECORD IS STANDARD.
01 IN-REC.
05 PILLER PIC X (4) .
05 CODA PIC X.
05 FILLER PIC X(6}.
05 CODB PIC X.
88 SW-PILl VALUE "9".
88 SW-FIL2 VALUE "8".
05 FILLER PIC X(68).
FD OUT-PUTl
RECORD CONTAINS 80 CHARACTERS
BLOCK CONTAINS 3 RECORDS
LABEL RECORD IS STANDARD.
01 OUT-RECl PIC X(80).
FD OUT-PUT2
RECORD CONTAINS 80 CHARACTERS
BLOCK CONTAINS 3 RECORDS
LABEL RECORD IS STANDARD.
01 OUT-REC2 PIC X (80) •
FD OUT-PUT3
RECORD CONTAINS 80 CHARACTERS
BLOCK CONTAINS 3 RECORDS
LABEL RECORD IS STANDARD.
01 OUT-REC3 PIC X(80).
WORKING-STORAGE SECTION.
17 TAPE-NUMBER PIC 9 VALUE O.
PROCEDURE DIVISION.
OPEN INPUT IN-PUT OUTPUT OUT-PUT1.

Pigure 44.

170

CI)

Reading a Multivolume File with Standard Labels; Creating a Multifile Volume
with Standard Labels (Part 1 of 2)

000460 READ-IN.
READ IN-PUT AT END GO TO END-OF-JOB.
000470
000480 A. MOVE IN-REC TO OUT-REC1.
WRITE OUT-REC1.
000490
IF SW-FILl NEXT SENTENCE ELSE G~O READ-IN.
000500
CLOSE OUT-PUTl WITH NO REWIND.
000510
OPEN OUTPUT OUT-POT2.
000520
ADD 1 TO TAPE-NUMBER.
000530
000540 B. PERFORM READ-IN.
MOVE IN-REC TO OUT-REC2.
000550
WRITE OUT-REC2.
000560
000570
IF SW-FIL2 NEXT SENTENCE ELSE GQ)0TO B.
CLOSE OUT-PUT2 WITH NO REWIND. 3
000580

C!)

\!J

,....n,nrnl\

VVV:J::1V

I"\...,,,.,,T

vr~D

"nmnTTm
vu~ru~

('\n"'_T'lTTm'4

vu.

rU.j.

ADD 1 TO TAPE-NUMBER.
000600
000610 C. PERFORM READ-IN.
MOVE IN-REC TO OUT-REC3.
000620
WRITE OOT-REC3.
000630
GO TO C.
000640
000650 END-OF-JOB.
CLOSE IN-PUT.
000660
IF TAPE-NUMBER
000670
o CLOSE OUT-PUTl GO TO D.
}
1 CLOSE OUT-PUT2 ELSE CLOSE OUT-PUT3. ~
IF TAPE-NUMBER
000680
000690 D. STOP RON ..

f4'

/ / LBLTYP TAPE
/ / EXEC LNKEDT

//
//
//
//
//
//
//

ASSGN SYS018,X'283'
TLBL FILE1,'MULTI-FILE1 VOL'} (;\
TLBL FILE2,'MULTI-FILE2 VOL'
TLBL FILE3,'MULTI-FILE3 VOL'
ASSGN SYS012,X'281'
ASSGN SYS012,X'282' ,ALT}
ASSGN SYS012,X'181',ALT ~
II TLBL SYS012,'MULTI-VOL FILE'
/ / EXEC
Figure 44.

\!;

f1\

Reading a Multivolume File with Standard Labels; Creating a Multifile Volume
with Standard Labels (Part 2 of 2)

Detailed File Processing Capabilities

171

// JoB SAMPLE

* LABELED MULTIFILE VOLUME TO UNLABELED MULTIVOLUME FILE
/ / OPTION LOG,DUMP,LINK,LIST,LISTX,XREF,SYM,ERRS,NODECK
/ / EXEC FCOBOL
000010
000020
000030
000040
000050
000060
000070
000080
000090
000100
000110
000120
000130
000140
000150
000160
000170
000180
000190
000200
000210
000220
000230
000240
000250
000260
000270
000280
000290
000300
000310
000320
000330
000340
000350
000360
000370
000380
000390
000400
000410
000420
000430
000440
000450
000460
000470
000480
000490
000500
000510
000520
000530
000540
000550

IDENTIFICATION DIVISION.
PROGRAM-ID. SAMPLE-3.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. IB[1-370.
OBJECT-COMPUTER. IBM-370.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT IN-PUT-l ASSIGN TO SYS014-UT-3410-S-FILE1.}
SELECT IN-PUT-2 ASSIGN TO SYS014-UT-3410-S-FILE2.
SELECT IN-PUT-3 ASSIGN TO SYS014-UT-3410-S-FILE3.
SELECT OUT-PUT ASSIGN TO SYS015-UT-3410-S.
DATA DIVISION.
FILE SECTION.
FD IN-PUT-1
RECORD CONTAINS 80 CHARACTERS
BLOCK CONTAINS 3 RECORDS
LABEL RECORD IS STANDARD.
01 IN-RECl PIC X(80).
FD IN-PUT-2
RECORD CONTAINS 80 CHARACTERS
BLOCK CONTAINS 3 RECORDS
LABEL RECORD IS STANDARD.
01 IN-REC2 PIC X(80).
FD IN-PUT-3
RECORD CONTAINS 80 CHARACTERS
BLOCK CONTAINS 3 RECORDS
LABEL RECORD IS STANDARD.
01IN-REC3PICX(80).
FD OUT-PUT
RECORD CONTAINS 80 CHARACTERS
BLOCK CONTAINS 3 RECORDS
LABEL RECORD IS OMITTED.
01 OUT-REC.
05 FILLER PIC X(4}.
05 CODA PIC X.
88 HI VALUE "9".
05 FILLER PIC X(6).
05 CO DB PIC Xe
88 LO VALUE "8".
05 FILLER PIC X(68).
PROCEDURE DIVISION.
OPEN INPUT IN-PUT-l OUTPUT OUT-PUT.
IN-1.
READ IN-PUT-l INTO OUT-REC AT END GO TO CLOSE1.
TESTER.
IF HI AND LO PERFORM CLOSE-OUT ELSE WRITE OUT-REC.CD
A. GO TO IN-l.
CLOSE1.
CLOSE IN-PUT-1 WITH NO REWIND.
} f,;\
OPEN INPUT IN-PUT-2 WITH NO REWIND.
IN-2.
READ IN-PUT-2 INTO OUT-REC AT END GO TO CLOSE2.
PERFORM TESTER.
GO TO IN-2.

Pigure 45.

172

(!)

\!J

Creating an Unlabeled Multivolume File (Part 1 of 2)

000560
000570
000580
000590
000600
000610
000620
000630
000640
000650
000660
000670
000680

CLOSE2.
CLOSE IN-PUT-2 WITH NO REWIND.
}
OPEN INPUT IN-PUT-3 WITE NO REWIND. \:J
IN-3.
READ IN-PUT-3 INTO OUT-REC AT END GO TO CLOSE3.
PERFORM TESTER.
GO TO IN-3.
CLOSE-OUT.
}
CLOSF OUT-PUT REEL.
STOP "REMOVE TAPE ON SYS015 AND MOUNT NEW TAPE".
CLOSE3.
CLOSE IN-PUT-3 OUT-PUT.
STOP RUN.

12'

(~\

II LBLTYP TAPE

C!)

/ / EXEC LNKEDT

//
//
//
//

ASSGN SYS014,X'283'
TLBL FILE1,'MULTI-FILEl VOT
TLBL FILE2,'MULTI-FILE2 vail
TLBL FILE3"MULTI-FI~3 VOL'
1/ ASSGN SYS015,X'282'(!j
/ / EXEC
Figure 45.

t} CD

Creating an Unlabeled Multivolume File (Part 2 of 2)

Detailed File Processing Capabilities

173

MASS STORAGE FILE LABELS

User Labels

The IBM Disk Operating System/Virtual
Storage provides postive identification and
protection of all files on mass storage
devices by recording labels on each volume.
These labels ensure that the correct volume
is used for input, and that no current
information is destroyed on output.

The programmer can include additional
labels to further define his file.
The
labels are referred to as user standard
labels. They cannot be specified for
indexed files.
A user label is an
SO-character label containing UHL (user
header label) or UTL (user trailer label)
in the first three character positions.
The fourth position contains a number 1
through a which represents the relative
position of the user label with a group of
user labels. The contents of the remaining
76 positions is entirely up to the
programmer. User header and trailer labels
are written on the first track of the first
extent of each volume allocated by the
proqrammer for the file.
User header
labels are resequenced starting with one
(URL1) at the beginning of each new volume.

The mass storage labels always include
one volume label for each volume and one or
more file labels for each logical file on
the volume. There may also be user header
labels and user trailer labels.

Volume Labels
The volume label is an aO-byte data
field preceded by a 4-byte key field.
Both
the key field and the first four bytes of
the data field contain the label identifier
VOL1.
IOCS creates a standard volume label
for every volume processed by the Disk
Operating System/Virtual Storage. It is
always the third record on cylinder 0,
track O. The format and contents of a
standard volume label can be found in the
publication DOS/VS Disk Labels.

LABEL PROCESSING CONSIDERATIONS
Files on Mass Storage Device Opened as
Input
1.

Standard labels checked
a.

The volume serial numbers in the
volume labels are compared to the
file serial numbers in the EXTENT
card.

Fields 1 through 3 in Format 1
label are compared to the
corresponding fields in the DLBL
card.

Each of the extent definitions in
the Format 1 and Format 3 labels
is checked against the limit
fields supplied in the EXTENT
card.

Standard File Labels
A standard file label identifies a
particular logical file, gives its
location(s) on the mass storage device, and
contains information to prevent premature
destruction of current files.
A standard
file label for a file located on a mass
storage device is a 140-character label
created (OPEN/CLOSE OUTPUT) in part by IOCS
using the DLBL control statement. The
fields contained within the label follow
three standard formats.
1.

Format 1 is used for all logical
files. The contents of the fields of
a Format 1 label is discussed in
"Appendix C: Standard Mass Storage
Device Labels. 1I
Format 2 is required for indexed
files.
The contents of the fields of
a Format 2 label can be found in the
publication DOS/VS Disk Labels~

174

Format 3 is required if a logical file
uses more than three extents of any
volume.
The contents of the fields of
a Format 3 label can be found in the
publication DOS/VS Disk Labels.

User labels checked
a.

If user header labels are
indicated for directly or
sequentially organized files, they
are read as each volume of the
file is opened. After reading
each label, the OPEN routine
branches to the programmer's label
routine if the appropriate USE
APTER STANDARD LABEL PROCEDURE
declarative is specified in the
source program.
The LABEL RECORDS'
clause with the data-name option
must be specified in the Data
Division. The programmer's label
routine then performs any
processing required.

If user trailer labels are
indicated on a sequential file,
they are read after reaching the
end of the last extent on each
volume when the file is closed,
provided end-of-file has been
reached. Trailer labels are
processed by the programmer's
label routine if the appropriate
USE AFTER STANDARD LABEL PROCEDURE
declarative is specified in the
source program. The LABEL RECORDS
clause with the data-name option
must be specified in the Data
Division.

Files on Mass Storage Devices Opened as
Output
1.

Standard labels created
a.

The volume serial numbers in the
volume labels are compared to the
file serial numbers in the EXTENT
card.

The extent definitions in all
current labels on the volume are
checked to determine whether any
extend into those defined in the
EXTENT card. If any overlap, the
expiration date is checked against
the current date in the
Communication Region of the
supervisor. If the expiration
date has passed, the old labels
are deleted. If not, the operator
is notified of the condition.

The new Format 1 label is written
with information supplied in the
DLBL card. If an indexed file is
being processed, the DTFIS routine
supplies information for the
Format 2 label.
The information in the EXTENT card
is placed in the Format 1 labels
and, if necessary, in the
additional Format 3 labels.

User header labels created
a.

If user header labels are
indicated by the presence of the
appropriate USE AFTER STANDARD
LABEL PROCEDURE declarative and
the LABEL RECORDS clause with the
data-name option, the programmer's
label routine is entered to
furnish the labels as each volume
of the file is opened. This can
be done for as many as eight user
header labels per volume. As each
label ~s presented, IOCS writes it
out on the first track of the
first extent of the volume.

If user trailer labels are
indicated by the presence of the
appropriate USE AFTER STANDARD
LABEL PROCEDURE declarative and
the LABEL RECORDS clause with the
data-name option, the programmer's
label routine is entered to
furnish the labels when the end of
the last extent on each volume is
reached. This can be done for as
many as eight user trailer labels.
The CLOSE statement must be issued
to create trailer labels for the
last volume of a sequential file
or for a direct file.

UNLABELED FILES
When a mUit1volume tape I1ie is opened
as INPUT and integer as specified in the
ASSIGN clause is greater than 1, the
compiler will generate the following
message to the operator:
C126D IS IT EOF?

The operator must respond either with N if
it is not the last reel, or with y if it is
the last reel. If it is end-ot-file,
control passes to the imperative-statement
specified in the AT END phrase of the READ
statement; if it is not end-of-file,
processing of the next volume is initiated.
If the integer specified in the ASSIGN
clause is not greater than 1, control
always passes at end-of-volume to the
imperative-statement specified in the AT
END phrase of the READ statement.

Detailed File Processing Capabilities

175

PROCESSING ASCII TAPE FILES

The IBM DOS/VS COBOL Compiler and
Library support the American National
Standard Code for Information" Interchange
(ASCII) as well as EBCDIC. This support
allows the user at object time to accept
and create magnetic tapes in accordance
with all of the following standards:
• American National Standard Code for
Information Interchange~ X3.4-1968.
• American National Standard Magnetic
Tape Labels for Information
Interchange, X3.27-1969.
• American National Standard Recorded
Magnetic Tape for Information
Interchange (800 CPI, NRZI),
X3.22-1967.

FILE HANDLING
:n processing ASCII files, thE supported
record formats are fixed, undefined, and
variable.
A variable-length record on an
ASCII file is known as a D-iormat record.
ASCII support does not extend to spanned
records. Record formats are discussed in
detail in the chapter "Record Formats."
For an ASCII file that contains a buffer
offset field, the following consjderations
apply:
• If the BLOCK CONTAINS clause with the
RECORDS option is specified, or if the
BLOCK CONTAINS clause is omitted, the
compiler compensates for the buffer
offset field.
• If the BLOCK CONTAINS clause with the
CHARACTERS option is specified, the
programmer must include the buffer
offset as part of the physical record.

COBOL LANGUAGE CONSIDERATIONS
The ASCII feature is supported by the
following addition to IBM's implementation
of American National Standard COBOL:
The system-name specified in the ASSIGN
clause is now coded as
SYSnnn-UT-device-C[-buffer offset][-name]
where
Organization code C indicates that an
ASCII-encoded tape file is to be
processed.
Buffer offset is a two-character field
that serves to indicate the size of the
block prefix. A block prefix, if
present, precedes each physical record
and is not accessible to the COBOL
programmer. This entry may only be
present for ASCII tape files and is only
reguired if a non-zero block prefix
exists. For output files, buffer offset
may be specified as 00 for P, U, or
D-mode records, or as 04 for D-mode
records only.
A buffer offset of 04 on
output means that the block prefix will
contain the length of each physical
record. For input files, buffer offset
may be in the range 00 through 99.

Labels on ASCII files are processed as
are the existing DOS/VS standard and user
standard labels.
Nonstandard label procedures, however, are
not supported. Therefore, USE BEFORE
STANDARD LABEL PROCEDUFEs are not permitted
for ASCII files.
ASCII files on unlabeled
tapes are supported. These unlabeled tapes
may contain data in any of the supported
record formats.
A complete discussion of
tape file labels can be found in the
ch~pter "Advanced Processing Capabilities."
The ASCII option (organization code C in
the ASSIGN clause) must not be speci=ied
for a file on which checkpoints are to be
written.
Diagnostic messages associated with
ASCII file handling are provided.
At
compile time, E-level messages are issued
for files whose record descriptions contain
data formats that are inconsistent with
ASCII conversion.
At object time, a
message is issued if an invalid sign
configuration is present during
translation, and the job will be
terminated.
Processing ASCII Tape Files

177

OPERATIONAL CONSIDERATIONS
It should be noted that ASCII support
causes translation from ASCII to EBCDIC on
input and from EBCDIC to ASCII on output.
Translation occurs automatically and is
transparent to the COBOL programmer. Since
an ASCII file is assumed to contain only
ASCII characters, standard character
sUbstitution occurs when untranslatable
configurations are present. The character
X'lA' is substituted for invalid EBCDIC
configurations during translation. An
invalid ASCII configuration (high-order bit
on) translates to the character X'3P'.

form of a leading overpunch or separate
character, a Program Product IBM DOS/VS
Sort/Merge program must be used. If sort
files reside on a 3330 or 3340 device, the
Sort program that supports thesE devices is
required. The Program Product IBM DOSjVS
Tape and Disk Sort/Merge, Program Number
5746-SMl is designed specifically for use
with a DOSjVS system.
To obtain an ASCII collated sort, the
system-name in the ASSIGN clause for the
sort work files should contain a C in the
organization field. The class field may be
specified as either UT or DA.
(Since ASCII
support causes translation from ASCII to
EBCDIC on input, sort work files are not
restricted to tapes.)

OBTAINING AN ASCII COLLATING SEQUENCE ON A
SOR!

Note that for an ASCII collated sort,
the buffer offset field is not permitted.

If an ASCII collated sort is desired or
numeric sort keys contain a sign in the

The ASCII collating sequence is listed
in the publication IBM DOS Full American
National Standard COBOL.

178

RECORD FORMATS FOR NON-VSAM FILES

Logical records for files which are not
VSAM files may be in one of four formats:
fixed-length (format F), variable-length
(format V) , undefined (format U), or
spanned (format S). All of these formats
are not supported for all access methods.
F-mode files must contain records of equal
lengths~
Files containing records of
unequal lengths must be V-mode, S-mode, or
U-mode. Files containing logical records
that are longer than physical records must
be S-mode.

DEPENDING ON option, or if mUltiple record
descriptions are all the same length.

The record format is specified in the
RECORDING MODE clause in the Data Division.
If this clause is omitted, the compiler
determines the record format from the
record descriptions associated with the
file. If the file is to be blocked, the
BLOCK CONTAINS clause must be specified in
the Data Division.

In unblocked format P, the logical
record constitutes the block. The BLOCK
CONTAINS clause is unnecessary for
unblocked records.

The prime consideration in the selection
of a record format is the nature of the
file itself. The programmer knows the type
of input his program will receive and the
type of output it will produce. The
selection of a record format is based on
this knowledge as well as an understanding
of the type of input/output devices on
which the file is written and of the access
method used to read or write the file.
Coding considerations for non-fixed
length records are discussed in the chapter
"Table Handling Considerations."

The number of logical records within a
block (blocking factor) is normally
constant for every block in the file. When
fixed-length records are blocked~ the
programmer specifies the BLOCK CONTAINS
clause in the file description entry in the
Data Division.

F0rmat F records are shown in Figure 46.
The optional control character, represented
by C, is used for stacker selection and
carriage control. When carriage control or
stacker selection is desired, the WRITE
&tatement with the ADVANCING or POSITIONING
option is used to write records on the
output file. In this case one character
position must be included as the first
character of the record. This position
will be automatically filled in with the
carriage control or stacker select
character. The carriage control character
never appears when the file is written on
the printer or punched on the card punch.

!.ogical Record
FIXED-LENGTH (FORMAT F) RECORDS

r--~-------------------------'

I C

Format F records are fixed-length
records. The programmer specifies format F
records by including RECORDING MODE IS F in
the file description entry in the Data
Division. If the clause is omitted and
both of the following are true:
• All records in the file are the same
size
• BLOCK CONTAINS [integer-l TO]
integer-2 ••• does not specify
integer-2 less than the length of the
maximum level-Ol record
the compiler determines the recording mode
to be F. All records in the file are the
same size if there is only one record
description associated with the file and it
contains no OCCURS clause with the

Data

Blocked Records
Logical
Record

Logical
Record

Logical
'f,:ecord

--------Fixed Length
Unblocked Record

Logical Record
L----________________________________
--J

--------Fixed Length----------->

igure 46.

Fixed-Length (Format F) Records

Record Formats for

Non-VSA~

Files

179

UNDEFINED

ASCII tape file.
D-format records are
processed in the same manner as V-format
records on tape files.

(FORMA~RECORDS

Format U is provided to permit the
processing of any blocks that do not
conform to F or V formats.
Format U
records are shown in Figure 47. The
optional control character C, as discussed
under "Fixed-Length (Format F) Records,"
may be used in each logical record.
The programmer specifies format U
records by including RECORDING MODE IS U in
the file description entry in the Data
Division. U-mode records may be specified
only for directly organized or standard
sequential files.
If the RECORDING MODE clause is omitted,
and BLOCK CONTAINS [integer-l TO]
integer-2 ••• does not specify integer-2
less than the maximum level-Ol record, the
compiler determines the recording mode to
be U if the file is directly organized and
one of the following conditions exist:
• The FD entry contains two or more
level-Ol descriptions of different
lengths.
• A record description contains an OCCURS
clause with the DEPENDING ON option.

The programmer specifies format V
records by including RECORDING MODE IS V in
the file description entry in the Data
Division. V-mode records may only be
specified for standard sequential files.
If the RECORDING MODE clause is omitted and
BLOCK CONTAINS [integer-l TO] integer-2 •••
does not specify integer-2 less than the
maximum level-01 record, the compiler
determines the recording mode to be V if
the file is standard sequential and one of
the following conditions exists:
• The FD entry contains two or more level
01 descriptions of different lengths.
• A record description contains an OCCUPS
clause with the DEPENDING ON option.
• A RECOPD CONTAINS clause
range of record lengths.

specifi~s

V-mode records, unlike U-mode or P-mode
records, are preceded by fields containing
control information. These control fields
are illustrated in Figures 48 and 49.
The first four bytes of each block
contain control information (CC):

• A RECORD CONTAINS clause specifies a
range of record lengths.
Each block on the external storage media
is treated as a logical record. There are
no record-length or block-length fields.

LL -- represents two bytes designating
the length of the block (including
the 'CC' field).
BB --

Note:
When a READ INTO statement is used
for a U-mode file, the size of the longest
record for that file is used in the MOVE
statement.
All other rules of the MOVE
statement apply.

repre~ents

two bytes reserved for

system use.
The first four bytes of each logical
record contain control information (cc):
11 -- represents two bytes designating

the logical record length
(including the 'cc' field).

Logical Record
C

Data

bb -- represents two bytes reserved for
system use.

Format U Record

For unblocked V mode records (see Figure
the data portion + CC + cc constitute
the block.
4~)

Logical f(ecord
----.J

Figure 47.

Undefined

(Format U) Records

4
4
variable
<--bytes-><--bytes--><------bytes------->
I

LL
VARIABLE-LENGTH RECORDS

18 a

,~I

'CC'
There are two types of variable-length
record:
D-format and V-format.
AD-format
record is a variable-length record on an

BB I 11 I bb I
'cc'

L-__________________________________

Figure 48.

Unblocked V-Mode Records

1st
Logical Record

------...

2nd
Logical Record

--~/'....

~1~==~I~~~I

DATA-1

I 11

ICC'
(block con trol
bytes)

--,

DATA-3

Blocked

fCC'

(record control
bytes)
V-~ode

Records

The control bytes are automatically
provided when the file is written and are
not communicated to the programmer when the
file is read. Although they do not appear
in the description of the logical record
provided by the programmer, the compiler
will allocate input and output buffers
which are large enough to accomodate them.
When variable-length records are written on
unit record devices, control bytes are
neither printed nor punched. They appear,
however, on other external storage devices
as well as in buffer areas of storage.
V-mode records moved from an input buffer
to a working-storage area will be moved
without the control bytes.
Note: When a READ INTO statement is used
for a V-mode file, the size of the longest
record for that file is used in the MOVE
statement. All other rules of the MOVE
statement apply.
Example 1:
Consider the following standard
sequential file consisting of unblocked
V-mode records:

I 11

For blocked V-mode records (see Figure
49) the data portion of each record + the
cc of each record + CC constitute the
block.

__==~==~~__________~I~__~I____-LI__________~__~-L~_ _~_ _ _ _ _ _ ~

~'--------.,./~---

igure 49.

DATA-2

3rd
Logical Record

VARIABLE-FILE-l
RECORDING MODE IS V
BLOCK CONTAINS 35 TO 80 CHARACTERS
RECORD CONTAINS 27 TO 72 CHARACTERS
DATA RECORD IS VARIABLE-RECORD-l
LABEL RECORDS ARE STANDARD.
VARIABLE-RECORD-l.
05 FIELD-A
PIC
05 FIELD-B
PIC
05 FIELD-C OCCURS
DEPENDING r'\l\l
VI.'
PIC
FIELD-B

X(20).
99.
1 TO 10 TIMES
9( 5),

The LABEL RECORDS clause is always
required.
The DATA RECORD(S) clause is
never required.
If the RECORDIdG MODE
clause is omitted, the compiler determines
the mode as V since the record associated
with VARIABLE-FILE-l varies in length
depending on the contents of FIELD-B. The
RECORD CONTAINS clause is never required.
The compiler determines record sizes frow
the record description entries. Record
length calculations are affected by the
following:

• When the BLOCK CONTAINS clause with the
RECORDS option is used, the compiler
adds four nytes to the logical record
length and four more bytes to the block
length.

• When the BLOCK CONTAINS clause with the
CHARACTERS option is used" the
programwer must include each cc + CC in
the length calculation (see Figure 49).
In the definition of VARIABLE-FILE-l,
the BLOCK CONTAINS clause specifies 8
more bytes than does the record
contains clause.
Four of these bytes
are the logical record control bytes
and the other four are the block
control bytes.
Assumming that FIELD-B contains the
value 02 for the first record of a file and
FIELD-B contains the value 03 for the
second record of the file, the first two
records will appear on an external storage
device and in buffer areas of storage as
shown in Figure 50.
If the file described in Example 1 had a
blocking factor of 2, the first two records
would appear on an external storage medium
as shown in Figure 51.

Record Formats for Non-VSAM Files

181

•.

I
1st Block
2nd Block
I ,.--..
____________- - - - _
Ii i '
i i i '
I i i
i i '
i'
i i i
II0040IBBI0036IbbIFIELD-AI02IFIELD-CIFIELD-CI0045IBBIO041IbbIFIELD-AI03IFIELD-CIFIELD-CIFIELD-CI
I'
I '
"
"
I
' "
"
I
I
,
I
I
I
I Note: Lengths appear in decimal notation for illustrative purposes.
I
~

Figure 50.

Fields in Unblocked V-Mode Records

1st Record

------------~------------

2nd Record

------------~-------------

I r-----~~~----r i i i
i
I
I
i i i
i
I
I
110081IBBI0036IbbIFIELD-AI02IFIELD-CIFIELD-C10041IbbIFIELD-AI03IFIELD-CIFIELD-CIFIELD-CI
I L.
- - L -_ _---'
I
I Note: Lengths appear in decimal notation for illustrative purposes.
I
Figure 51.

Fields in Blocked V-Mode Records

Example 2:
If VARIABLE-FILE-2 is blocked, with
space allocated for three records of
maximum size per block, the following FD
entry could be used when the file is
created:
FD

VARIABLE-FILE-2
RECORDINb MODE IS V
BLOCK CONTAINS 3 RECORDS
RECORD CONTAINS 20 TO 100 CHARACTERS
DATA RECORDS ARE VARIABLE-RECORD-1,
VARIABLE-RECORD-2
LABEL RECORDS ARE STANDARD.
VARIABLE-RECORD-l.
05 FIElD-A PIC X (20) •
05 FIELD-B PIC X(80).
VARIABLE-RECORD-2.
05 FIELD-X PIC X (20) •

As mentioned previously, the RECORDING
MODE, RECORD CONTAINS, and DATA RECORDS
clauses are unnecessary.
By specifying

182

that each block contains three records, the
programmer allows the compiler to provide
space for three records of maximum size
plus additional space for the required
control bytes. Hence, 316 character
positions are reserve~ by the compiler for
each output buffer. If this size is other
than the maximum, the BLOCK CONTAINS clause
with the CHARACTERS option should be
specified.
Assuming that the first six records
written are five 100-character records
followed by one 20-character record, the
first two blocks of VARIABLE-FILE-2 will
appear on the external storage device as
shown in Figure 52.
The buffer for the second block is
truncated after the sixth WRITE statement
is executed since there is not enough space
left for a maximum size record. Hence,
even if the seventh WRITE to
VARIABLE-FILE-2 is a 20-character record,
it will appear as the first record in the
third block. This situation can be avoided
by using the APPLY WRITE-ONLY clause when
creating files of variable-length blocked
records.

1st Block
1316IBBI10~lbbIDataI104IbbIDataI10~lbbIDatal

~
i i i
I

Note:

i i i

, I

I i i

Suppose VARIABLE-FILE-2 is being created
with the following FD entry:
VARIABLE-FILE-2
RECORDING MODE IS V
BLOCK CONTAINS 316 CHARACTERS
RECORD CONTAINS 20 TO 100 CHARACTERS
DATA RECORDS ARE VARIABLE-RECORD-l,
VARIABLE-RECORD-2
LABEL RECORDS ARE STANDARD.

VARIABLE-RECORD-l.
05 FIELD-A PIC X(20).
05 FIELD-B PIC X(80).

VARIABLE-RECORD-2.
05 FIELD-X PIC X (20) •

;

If an APPLY WRITE-ONLY clause is specified
for a file and an OCCURS DEPENDING ON clause
is specified within a record description of
the file, the object of the OCCURS DEPENDING
ON clause should not be defined within the
record description for the file.

When retrieving a file with S-mode
records, only complete records are made
available to the programmer.

i308ibbi24ibbiDatall04ibbID~104ibb;Data ~
I

---

When creating files with S-mode records,
if a record is larger than the remaining
space in a block, a segment of the record
is written to fill the block.
The
remainder of the record is stored in the
next block or blocks, as required.

Using the APPLY WRITE-ONLY clause will
cause a buffer to be truncated only when
the next record does not fit in the buffer.
That is, if the next three WRITE statements
to the file specify VARIABLE-RECORD-2, the
block will be created containing six
logical records, as shown below:

A spanned record is a logical record
that may be contained in one or more
physical blocks. Format S records may be
specified for direct files and for standard
sequential files assigned to magnetic tape
or to mass storage devices.

123 6 1bbl241bbiDatal1041bbiDatall041bbiDatai
I

SPANNED (FORMAT S1 RECORDS

The first three WRITE statements to the
file create one 20-character record
followed by two 100-character records.
Without the APPLY WRITE-ONLY clause, the
buffer is truncated after the third WRITE
statement is executed, since the maximum
size record no longer fits.
The block is
written as shown below:
j

Note: When using the APPLY WRITE-ONLY
clause, records must not be constructed in
buffer areas. An intermediate work area
must be used with a WRITE FROM statement.

The APPLY WRITE-ONLY clause is used to
make optimum use of buffer and external
storage space when creating a standard
sequential file with blocked V-mode
records.

First Two Blocks of VARIABLE-FILE-2

APPLY WRITE-ONLY Clause

1236lBBl104lbblDatai104lbblDatal2~lbblDatai

Lengths appear in decimal notation for illustrative purposes.

Figure 52.

2nd Block

Spanned records are preceded by fields
containing control information. Figure 53
illustrates the control fields.
BDF (Block Descriptor Field) :
LL -- represents 2 bytes designating the
length of the physical block
(including the block descriptor
field itself).
BB -- represents 2 bytes reserved for
system use.

Record Formats for Non-VSAM Files

183

SDP (Segment Descriptor Pield) :

11 -- represents 2 bytes designating the
length of the record segment
(including the segment descriptor
field itself).

Figure 54 is an illustration of blocked
spanned records of SFILE. SFILE is
described in the Data Division with the
following file description entry:
FD SFILE
RECORD CONTAINS 250 CHARACTERS
BLOCK CONTAINS 100 CHARACTERS

bb -- represents 2 bytes reserved for
system use.

Note: There is only one block descriptor
field at the beginning of each physical
block. There is, however, one segment
descriptor field for each record segment
within the block.
Each segment of a record in a block,
even if it is the entire record, is
preceded by a segment descriptor field.
The segment descriptor field also indicates
whether the segment is the first, the last,
or an intermediate segment. Each block
includes a block descriptor field. These
fields are not described in the Data
Division; provision is automatically made
for them. These fields are not available
to the programmer.
A spanned blocked file may be described
as a file composed of physical blocks of
fixed length established by the programmer.
The logical records may be either fixed or
variable in length and that size may be
smaller, equal to, or larger than the
physical block size. There are no required
relationships between logical records and
physical block sizes.
A spanned unblocked file may be
described as a file composed of physical
blocks each containing one logical record
or one segment of a logical record. The
logical records may be either fixed or
variable in length. When the physical
block contains one logical record, the
length of the block is determined by the
logical record size. When a logical record
has to be segmented, the system always
writes the largest physical block possible.
The system segments the logical record when
the entire logical record cannot fit on the
track.

Figure 54 also illustrates the concept
of record segments. Note that the third
block contains the last 50 bytes of REC-l
and the first 50 bytes of REC-2. Such
portions of logical records are called
record segments. It is therefore correct
to say that the third block contains the
last segment of REC-l and the first segm~nt
of REC-2. The first block contains the
first segment of REC-1 and the second block
contains an intermediate segment of REC-l.

S-MODE CAPABILITIES
Formatting a file in the S-mode allows
the programmer to make the most efficient
use of external storage while organizing
data files with logical record lengths most
suited to his needs.
1.

Physical record lengths can be
designated in such a manner as to make
the most efficient use of track
capacities on mass storage devices.

The programmer is not required to
adjust logical record lengths to
maximum physical record lengths and
their device-dependent variants when
designing his data files.

The programmer has greater flexibility
in transferring logical records across
DASD types.

Spanned record processing will support
the 2400, 3410, 3420 tape series, the 2311,
2314, 2319, 3330, and 3340 disk storage
devices, and the 2321 data cell drive.

<--4 bytes---> <--4 bytes--> <----------------Variable bytes------------------->
BB

LL
I

BDF
igure 53.

184

Data Record or Segment

11
I

SDF

Control Fields of an S-Mode Record

<--------100 bytes------->

<--------100 bytes------->
REC-l

1st Block
Figure 54.

REC-l

<-50 bytes-> <-50 bytes->
G

REC-l

REC-2

3rd Block

2nd Block

One Logical Record Spanning Physical Blocks

SEQUENTIALLY ORGANIZED S-MODE FILES ON TAPE
OR HASS STORAGE DEVICES
When the spanned format is used for
DTFMT or DTFSD files, the logical records
may be either fixed or variable in length
and are completely independent of physical
record length. A logical record may span
physical records. A physical record may
contain one or more logical records and/or
segments of logical records.

When the spanned recording mode is being
used, each logical record is processed in a
work area, not in the buffer. Logical
records are always aligned on a double-word
boundary. Therefore, the programmer is not
required to add inter-record slack bytes
for alignment purposes.
Except for the APPLY WRITE-ONLY clause,
all the options for a variable file apply
to a spanned file.

Source Language Considerations
Processing Seguentially Organized S-Mode
Files
The programmer specifies S-mode by
describing the file with the following
clauses in the file description (FD) entry
of his COBOL program:

Suppose a file has the following file
description entry:

• BLOCK CONTAINS integer-2 CHARACTERS

SPAN-FILE
BLOCK CONTAINS 100 CHARACTERS
LABEL RECORDS ARE STANDARD
DATA RECORD IS DATAREC.

DATAREC.
05 FIELD-A PIC X(100).
05 FIELD-B PIC X (50) •

• RECORD CONTAINS [integer-l TO]
integer-2 CHARACTERS
• RECORDING MODE IS S
The size of the physical record must be
specified using the BLOCK CONTAINS clause
with the CHARACTERS option. Any block size
may be specified. Block size is
independent of logical record size.
The size of the logical record may be
specified by the RECORD CONTAINS clause.
If this clause is omitted, the compiler
will determine the maximum record size from
the record descriptions under the FD.
Format S may be specified by the
RECORDING MODE IS S clause. If this clause
is omitted, the compiler will set the
recording mode to S if the BLOCK CONTAINS
integer-2 CHARACTERS clause was specified
and either:
1.

integer-2 is less than the largest
fixed-length level-Ol FD entry

integer-2 is less than the maximum
length of a variable level-Ol FD entry
(i.e., an entry containing one or more
OCCURS clauses with the DEPENDING ON
option).

Figure 55 illustrates the first four
blocks of SPAN-FILE as they would appear on
external storage devices (i.e., tape or
mass storage) or in buffer areas of virtual
storage.
Note:
1.

The RECORDING MODE clause is not
specified. The compiler determines
the recording mode to be S since the
block size is less than the record
size.

The length of each physical block is
100 bytes, as specified in the BLOCK
CONTAINS clause. All required control
fields, as well as data, must be
contained within these 100 bytes.

No provision is made for the control
fields within the level-Ol ent~y
DATAREC.
Record Formats for Non-VSAM Files

185

bytes ------------>

<-bytes-><-bytes-><
i

DATAREC ( 1)

ILL ,IBB III

DATAREC (1)

bytes ------------>

DATAREC (2)

i i i

ILL IBB III

bb IDATAREC (2) 111

DATAREC (3)

4th Block

3rd Block

Figure 55.

•

bb IDATAREC (2) I

<-bytes-><-bytes-><--bytes---><-bytes-><---bytes---->
,

ILL IBB III

III

2nd Block

1st Block

<-bytes-><-bytes-><

I i i

III
IBB
ILL
,
,

<-bytes-><-bytes-><---bytes---><-bytes-><--bytes--->

First Four Blocks of SPAN-FILE

r----------------------------------------------~----------------------------------------------~
RECORDING MODE IS S
RECORDING ~ODE IS V

I
I
I
I
I
I

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

150
150
"-'v-'~
Rl

G ,

150

100

r------,
G , 150

150

1
....'-_~---"'-~_---L-::---~'

100

150

____
'-I--_-.l..-~--,. .'-'-v-"--~'
.
R3

I
I
INot~:
The enclosed diagrams are for illustrative purposes only. Neither takes into
,account the space required for control fields.

Figure 56.

Advantage of S-Mode Records Over V-Mode Records

The preceding discussion dealt with
S-mode records which were larger than the
physical blocks that contained them.
It is
also possible to have S-mode records which
are equal to or smaller than the physical
blocks that contain them. In such cases,
the RECORDING ~ODE clause must specify S
(if so desired) since the compiler cannot
determine this by comparing block size and
record size.
One advantage of S-mode records over
V-mode r~cords is illustrated by a file
with the following characteristics:
1.

RECORD CONTAINS 50 TO 150 CHARACTERS

BLOCK CONTAINS 350 CHARACTERS

The first fivE records written are
150, 150, 150, 100, and 150 characters
in length.

186

For V-mode records, buffers are
truncated if the next logical record is too
large to be completely contained in the
block (see Figure j6) • This re~ults in
more physical blocks and more inter-record
gaps on the external storage device.
Note: For V-mode records, buffer
trUncation occurs:
1.

When the maximu. level-Ol record is
too large.

If APPLY WRITE-ONLY or SAME RECORD
AREA is specified and the actual
logical record is too large.

For S-mode records, all blocks are 350
bytes long and records that are too large
to fit entirely into a block will be
segmented. This results in more efficient
use of external storage devices since the

number of inter-record gaps are minimized
(Figure 56) •

DIRECTLY ORGANIZED S-MODE FILES

With the exception of the last block,
the actual physical block size will always
fall between the limits of specified block
size and four bytes less than the specified
block size, depending on whether or not the
residual space of an incomplete block in
the buffer is sufficient to add a segment
length field and at least one byte of data.
That is, specified block size - 4 5 actual

When S-mode is used for a directly
organized file, only unblocked records are
permitted. Logical records may be either
fixed or variable in length. A logical
record will span physical records if, and
only if, it spans tracks. A physical
record will contain only one logical record
or a segment of a logical record, or
segments of two logical records and/or
whole logical records. Records may span
tracks r cylinders: and extents, but not
volumes.

block size S specified block size.

The last block may be short when an
incomplete block remains in the buffer at
CLOSE time.
A second advantage of S-mode processing
over that of V-mode is that the programmer
is no longer limited to a record length
that does not exceed the track capacity of
the mass storage device selected. Records
may span track, cylinders, and extents, but
not volumes.
DTFMT and DTFSD spanned records differ
from other formats because of an allocation
of an area of storage known as the "logical
record area." If logical records span
physical blocks, COBOL will use this
logical record area to assemble complete
logical records. If logical records do not
span blocks (i.e., they are contained
within a single physical block) the logical
record area is not used. Regardless, it is
complete logical records that are made
available to the programmer. Both READ and
WRITE statements should be thought of as
manipulating complete logical records and
not record segments.

Source Language Considerations
The programmer specifies S-mode by
describing the file with the following
clauses in the file description (FD) entry
of his COBOL program:
• BLOCK CONTAINS integer-2 CHARACTERS
• RECORD CONTAINS [integer-1 TO] integer-2
CHARACTERS
• RECORDING MODE IS S
The size of a logical record may be
specified by the RECORD CONTAINS clause.
If this clause is omitted, the compiler
will determine the maximum record size from
the record descriptions under the YD.
The spanned format may be specified by
the RECORDING MODE IS S clause. If this
clause is omitted, the compiler will set
the recording mode to S if the BLOCK
CONTAINS integer-2 CHARACTERS clause was

Sequential File
R1

Direct File
R3

••• 1st track •••

• __ 2nd track.=.

R3
r---------~

••• 3rd track •••

•. 4th track...

G L-________
I
R4

L______

Figure 57.

Direct and Sequential Spanned Files on a Mass Storage Device
Record Formats for Non-VSAM Files

187

specified and integer-2 is less than the
greatest logical record size. This is the
only use of the BLOCK CONTAINS clause@ It
is otherwise treated as comments.
The physical block size is determined by
either:
1.

The logical record length, or

The track capacity of the device being
used.

If, for example, the track capacity of a
mass storage device is 3625 characters, any
record smaller than 3625 characters may be
written as a single physical block. If a
logical record is greater than 3625
characters, the record is segmented. The
first segment may be contained in a
physical block of up to 3625 bytes, and the
remaining segments must be contained in
succeeding blocks. In other words, a
logical record will span physical blocks
if, any only if, it spans tracks.

one logical record or one record segment.
Logical record R3 spans physical blocks
only because it spans tracks. The file
consists of seven physical blocks, occupies
more than three tracks, and contains three
inter-record gaps.

Processing Directly organized S-Mode Files
When processing directly organized
files, there are two advantages spanned
format has over the other record formats:
1.

Figure 57 illustrates four
variable-length records (R1, R2, R3, and
R4) as they would appear in direct and
sequential files on a mass storage device.
In both cases, control fields have been
omitted for illustrative purposes. For
both files, assume:
1.

BLOCK CONTAINS 3625 CHARACTERS (track
capacity = 3625)

RECORD CONTAINS 500 TO 5000 CHARACTERS

In the sequential file, each physical
block is 3625 bytes in length and is
completely filled with logical records.
The file consists of three physical blocks,
occupies three tracks, and contains no
inter-record gaps.
In the direct file, the physical blocks
vary in length. Each block contains only

188

Logical record lengths may exceed the
length restriction of the track
capacity of the mass storage device.
If, for example, the track capacity of
a mass storage device is 2000 bytes,
the length of each logical record for
formats other than spanned is, by
necessity, restricted to the track
capacity.
Note: Even when the spanned format is
used, the COBOL restriction on the
length of logical records (i.e., a
maximum length of 32,767 characters)
must be adhered to.

For formats other than spanned, only
complete logical records can be
written on any single track. This
means that if a track has only 1000
unoccupied bytes and the programmer
attempts to add a record of 1100 bytes
to this track, an INVALID KEY
condition will occur. When the
spanned format is used, a 1000 byte
segment will be written on the
specified track, and the remainder
will be written on the next track.
The segmenting is transparent to the
programmer.

PART III

PROGRAMMING

·~I

TECHNIQUES----------------------------------------------~.

USING THE SORT

FEATURE----------------------------------------------~. ~

USING THE REPORT WRITER FEATURE---------------------------------------..

TABLE HANDLING CONSIDERATIONS-----------------------------------------..

189

~
~

PROGRA~~ING

Note:
When OPT is in effect, the
generated code is more suitable for
running under VS, as the addressing
scheme is designed to reduce possible
page faults.

This chapter describes techniques and
hints for better COBOL programming.

CODING

'C',.....n

.l:vn

TECHNIQUES

Further~

the procedure is divided into
4K blocks, each of which is assigned a
PBL.
Since these blocks corres~ond to
two pages each, the user may get some
idea of the inter-page relationships in
his program (although the first is not
page aligned). The statement range for
each PBL is given on the compiler
output listing. This should help the
user rearrange his program if he so
desires.

T"\I"'\C' rr.TC'

uv...."

v....,

These suggestions will aid DOS/VS
efficiency:
• If a short subprogram is referenced
only once or twice (and is not an
exception condition routine), then its
code should be incorporated in the
calling program, if convenient.
• Subprograms and frequently used
subroutines should be loaded near the
programs which use them. This can be
done via linkage editor control cards.

• The REDEFINES clause should be used for
its alternate grouping and alternate
description capabilities rather than
for merely saving space. Although it
will save virtual space, it can lead to
coding errors if not used carefully.

• Segmentation in many cases is no longer
necessary or desirable.
GENERAL CONSIDERATIONS

• Data items of constant value should be
grouped together. Data items whose
values vary during execution should
also be grouped together and should be
separate from those of constant value,
if feasible.

COpy

• FDs for files that will be opened at
the same time should be grouped
together.

The COpy function should be used by an
installation so that if a record format,
for example, changes, each program does not
need to be modified itself. Rather, the
COpy library is updated and each program
then recompiled.

• The most frequently referenced data
items should be placed in the beginning
of the working Storage section.
• The COBOL Procedure Division should be
organized generally as follows:
- All frequently used paragraphs or
sections should be located near the
routines that use them.
- All infrequently used paragraphs or
sections should be grouped together
and apart from frequently used
routines. The COUNT option can be
used as an aid in this process.

Use of this function can lead to
standardization of naming conventions and
ease of maintenance.

SYNTAX CHECKING
The first several compilations of a
program should use the CSYNTAX or SYH'I'AX
feature to save compilation time.

• Avoid initializing data areas until
just before they are needed.

Formattinq the Source Program Listing

• Reference data in the order in which it
is stored.

The lister feature increases
significantly the usability of the source
program listing, not only by producing
cross-reference information, but by

• Use the OPTIMIZE feature if possible.

PrograRrring Techniques

191

formatting the listing to aid logic
tracing. There are four statements that
can be coded in any or all of the four
divisions of a source program: SKIP1,
These statements
SKIP2, SKIP3, and EJECT.
provide the programmer with the ability to
control the spacing of a source listing and
thereby improve its readability. These
statements should not be used when the
lister feature is used.

ENVIRONMENT DIVISION
RESERVE Clause
When using an additional buffer to
process standard sequential or indexed

192

files, care must be taken to ensure that
the buffer is filled before the execution
of each WRITE or REWRITE statement.

APPLY WRITE-ONLY Clause
To make optimum use of buffer and
external storage space allocated when
creating a standard sequential file with
blocked V-mode records, the programmer
should use the APPLY WRITE-ONLY clause for
the file.
Using this clause causes a
buffer to be truncated only when the next
record does not fit in the buffer.
(If
APPLY WRITE-ONLY is not specified, the
buffer is truncated when the maximum size
record will not fit in the space remaining
in the buffer.)

DATA DIVISION
STORAGE CONSIDERATIONS
The amount of storage used for all FD
entries, the WORKING STORAGE SECTION, and
REPORT SECTION must not exceed I Mb, since
the compiler can only handle a maximum of
255 for BL-CELLS. One BL-CELL is assigned
for each file or for 4096, whichever
comes first.

"corresponding" names with the prefixed
unique names. This technique eliminates
excessive qualifying.
For example:
01

OVERALL CONSIDERATIONS

FD Entries
File Description (FD) entries for the
most active files should appear first,
since the COBOL compiler assigns registers
to files until it runs out of registers,
and then reuses the last registers for all
subsequent files. This does not apply when
OPT is in effect, since in that case the
compiler will determine the frequency of
usage and assign registers accordingly.
Prefixes
Assign a prefix to each level-01 item in
a program, and use this prefix on every
subordinate item (except FILLER) to
associate a file with its records and work
areas.
For example, MASTER is the prefix
used here:
FILE SECTION.
FD MASTER-INPUT-FILE

MASTER-INPUT-RECORD.

MST-WORK-AREA.
05 SAME-NAMES.
<***)
10 LAST-NAME PIC •••
10 FIRST-NAME PIC •••
10 PAYROLL PIC •••

DIFF-NAMES REDEFINES SAME-NAMES.
10 MST~LAST-NAME PIC=::
10 MS~-FIRST-NAME PIC •••
10 MST-PAYROLL PIC •••
RPT-WORK-AREA.
05 SAME-NAMES.
<***)
10 PAYROL~ PIC •••
10 FILLER PIC •••
10 FIRST-NAME PIC •••
10 FILLER PIC •••
10 LAST-NAME PIC •••

PROCEDURE DIVISION.
IF MST-PAYROLL IS EQUAL TO HDQ-PAYROLL
AND MS~'- LAST- NAME
IS NOT EQUAL TO PRRV-LAST-NAME
MOVE CORRESPONDING
MST-WORK-AREA
TO RPT-WORK-AREA.
Note: Fields marked *** above must have
exactly the same names for their
subordinate fields to be considered
"corresponding." The same names must not
be the redefininq ones or they will not be
considered to correspond.
Level Numbers

WORKING-STORAGE SECTION.
01 MASTER-WORK-AREA.
05 MASTER-PAYROLL PICTURE 9(3).
05 MASTER-SSNO PICTURE 9(9).
If files or work areas have the same
fields, use the prefix to distinguish
between them. For example, if three files
all have a date field, instead of DATE,
OAT, and DA-TE, use MASTER-DATE,
DETAIL-DATE, and REPORT-DATE. Usi~g a
unique prefix for each level-01 item and
all subordinate fields makes it easier for
a programmer unfamiliar with the program to
find fields in the program listing, and to
know which fields are logically part of the
same record or area.
When using the MOVE statement with the
CORRESPONDING option and referring to
individual fields, redefine or rename

The programmer should use widely
incremented level numbers such as 01, 05,
10, 15, etc., instead of 01, 02, 03, 04~
etc., In order to allow space for future
insertions of group levels. For
readability, indent level numbers.
(The
lister feature does this automatically,
even if the original source program does
not follow such indenting practices.)
Note that when using the SYMDMP option,
level numbers appear "normalized" in the
symbolic dump produced. For example, a
group of data items described as:
01 RECORDA.
05 FIELD-A.
10 FIELD-A1 PIC X.
10 FIELD-A2 PIC X.

programming Techniques

193

will appear as follows in SYMDMP output:
01
02
03
03

Areas which do not contain VALUE
clauses should be separated from areas
that do contain VALUE clauses. VALUE
clauses (except for level-S8 items)
are invalid in the Linkage section.

When the Working-Storage Section
consists of one level-Ol item without
any VALUE clauses, the COPY statement
can easily be used to include the item
as the description of a Linkage
Section in a separately compiled
module.

See the chapter "Using the
Segmentation Feature" for information
on how to modularize the Procedure
Division of a COBOL program; VS coding
considerations should also be taken
into account.

RECORDA •••
FIELD-A •••
FIELD-Al •••
FIELD-A2 ....

Use level number 88 for codes. Thus, if
the codes must be changed, the Procedure
Division coding for tests need not be
changed.

FILE SECTION
RECORD CONTAINS Clause
The programmer should use the RECORD
CONTAINS clause with the integer CHARACTERS
option in order to save himself, as well as
any future programmer, the task of counting
the data record description positions.
In
addition, the compiler can then diagnose
errors if the data record description
conflicts with the RECORD CONTAINS clause.

BLOCK CONTAINS Clause
If a block prefix exists on an ASCII
file and the BLOCK CONTAINS clause is used
in the COBOL program, the length of the
block prefix must be included in the BLOCK
CONTAINS clause ..

WORKING-STORAGE SECTION
Separate Modules
In a large program, the programmer may
wish to plan ahead for breaking the
programs into separately compiled modules,
as follows:
1.

194

When using separate modules, an
attempt should be made to combine
entries 'of each Working-Storage
Section into a single level-Ol record
(or a single level-Ol record for each
32K bytes). Logical record areas can
be indicated by using level-02, -03,
etc., entries. A CALL statement with
the USING option is more efficient
when a single item is passed than when
many level-Ol and/or -77 items are
passed. when this method is employed,
mistakes are more easily avoided.

Locating the Working-Storage section in
Dumps
If the SYMDMP option is not used for
program debugging, a method of locating the
Working-Storage Section of a program in
object-time dumps is to include the two
following statements as the first and last
Working-Storage statements, respectively,
in the program.
77

FILLER PICTURE X(44), VALUE "PROGRAM
XXXXXXXX WORKING-S~ORAGE BEGINS HERE".

FILLER PICTURE X(42), VALUE "PROGRAM
XXXXXXXX WORKING-STORAGE ENDS HERE".

These two nonnumeric literals will
appear in all dumps of the program,
delimiting the Working-Storage Section.
The program-name specified in the
PROGRAM-ID clause should replace the
XXXXXXXX in the literal.
The location and length of
Working-Storage is given in the compiler
output when SYM, LISTX, or CLIST is in
effect.
REDEFINES Clause
REUSING DATA AREAS: Virtual storage can be
used more efficiently by writing different
data descriptions for the same data area.
For example, the coding that follows shows
how the same area can be used as a work
area for the records of several input files
that are not processed concurrently.
Caution should be exercised when using this
procedure, as it can lead to programming
errors.

WORKING-STORAGE SECTION.
01 WORK-AREA-FILE1.
(largest record description for FILE1)

WORK-AREA-FILE2 REDEFINES
WORK-AREA-FILE1.
(largest record description for FILE2)

ALTERNATE GROUPINGS AND DESCRIPTIONS:
Program data can often be described more
efficiently by providing alternate
groupings or data descriptions for the same
data. For example, a program references
both a field and its subfields, each of
which is more efficiently described with a
different usage. This can be done by using
the REDEFINES clause as follows:
01
05
05

PAYROLL-RECORD.
EKPLOYEE-RECORD PICTURE X(28}.
EKPLOYEE-FIELD REDEFINES
EKPLOYEE-RECORD.
10 NAKE PICTURE X(24).
10 NUMBERX PICTURE S9(5} COMP.
DATE-RECORD PICTURE X (10) •

The following illustrates how a table
(TABLEA) can be initialized by having
different data descriptions for the same
data:

VALUE-A.
10 Al PICTURE S9(9) COMPUTATIONAL
VALUE IS ZEROES.
10 A2 PICTURE S9(9) COMPUTATIONAL
VALUE IS 1.

Al0a PICTURE S9(9} COMPUTATIONAL
VALUE IS 99.
TABLEA REDEFINES VALUE-A
PICTURE S9(9) COMPUTATIONAL
OCCURS 100 TIMES.

Note: caution should be exercised when
redefining a subscript. If the value of
the redefining data item is changed in the
Procedure Division, a new calculation for
the subscript is performed only if a new
paragraph is entered.

Programming Techniques

195

PICTURE Clause

DECIMAL-POINT ALIGNMENT: Procedure
Division operations are most efficient when
the decimal positions of the data items
involved are aligned. If they are not, the
compiler generates instructions to align
the decimal positions before any operations
involving the data items can be executed.
I This is referred to as scaling.

A plus or minus sign. If S is
specified in the PICTURE clause, a
plus or minus sign is inserted when
either of the following conditions
prevail:
a.

The item is in the Working-Storage
Section and a VALUE clause has
been specified.

A value for the item is assigned
as a result of an arithmetic
operation during execution of the
program.

Assume, for example, that a program
contains the following instructions:
WORKING-STORAGE SECTION.
A PICTURE S999V99.
B PICTURE S99V9.

77
71

If an external decimal item is
punched, printed, or displayed, an
overpunch will appear in the low-order
digit. In EBCDIC, the configuration
for low-order zeros normally is a
nonprintable character. Low-order
digits of positive values will be
represented by one of the letters A
through I (digits 1 through 9) ;
low-order digits of negative values
will be represented by one of the
letters J through R (digits 1 through

PROCEDURE DIVISION.

ADD A TO B.
Time and internal storage space are
saved by defining Bas:

77 B PICTURE S99V99.

9) •

If it is inefficient to define B
differently, a one-time conversion can be
done, as explained in "Data Format
Conversion" in this chapter~
FIELDS OF UNEQUAL LENGTH: When a data item
is moved to another data item of a
different length, the following should be
considered:
• If the items are external decimal
items, the compiler generates
instructions to insert zeros in the
high-order positions of the receiving
field, when it is the larger.
• If the items are nonnumeric, the
compiler may generate instructions to
insert spaces in the low-order
positions of the receiving field (or
the high-order positions if the
JUSTIFIED RIGHT clause is specified).
This generation of extra instructions
can be avoided if the sending field is
described with a length egual to or
greater than the receiving field.
SIGN USAGE: The presence or absence of a
plus or minus sign in the description of an
arithmetic field often can affect the
efficiency of a program. The following
paragraphs discuss some of the
considerations.
Decimal Items: The sign position in an
internal or external decimal item can
contain:

196

A hexadecimal F. If S is not
specified in the PICTURE clause, an F
is inserted in the sign position when
either of the following conditions
prevail:
a.

The item is in the Working-Storage
Section and a VALUE clause has
been specified

A value for the item is developed
during the execution of the
program.

An F is treated as positive, but is
not an overpunch.
3.

An invalid configuration. If an
internal or external decimal item
contains an invalid configuration in
the sign position, and if the item is
involved in a Procedure Division
operation, the program will be
abnormally terminated.

Note: If the SIGN clause is used and it
specifies that the sign is LEADING, more
object code will be generated when that
data item is used with a verb. The
additional code is needed to move the sign
character to the TRAILING position before
performing the operation~
Unsigned items (items for which no S has
been specified) are treated as absolute
values. Whenever a value (signed or
unsigned) is stored in or moved in an

~
~

elementary move to an unsigned item, a
hexadecimal F is stored in the sign
position of the unsigned item. For
example, if an arithmetic operation
involves signed operands and an unsigned
result field, compiler-generated code will
insert an F in the sign position of the
result field when the result is stored.

For internal and external decimal items
used as input, it is the programmer's
responsibility to ensure that the input
data is valid. The compiler does not
generate a test to ensure that the
configuration in the sign position is
valid.

When a group item is being moved, the
data is moved without regard to the level
structure of the group items involved. The
possibility exists that the configuration
in the sign position of a subordinate
numeric item may be destroyed. Therefore,
caution should be exercised in moving group
items with subordinate numeric fields or
with other group operations such as READ or
ACCEPT.

USAGE Clause
DATA FORMAT CONVERSION: Operations
involving mixed, elementary numeric data
formats require conversion to a common
format. This usually means that additional
storage is used and execution time is
increased. The code generated must often
move data to an internal work area, perform
any necessary conversion, and then execute
the indicated operation. Often, too, the
result may have to be converted in the same
way. Table 31 indicates when data
conversion is necessary.
If it is impractical to use the same
data formats throughout a program, and if
two data items of different formats are
frequently used together, a one-time
conversion can be effected. For example,
if A is defined as a COMPUTATIONAL item and
B as a COMPUTATIONAL-3 item, A can be moved
to a work area that has been defined as
COMPUTATIONAL-3. This move cau~es the data
in A to be converted to COMPUTATIONAL-3.
Whenever A and B are used in a Procedure
Division operation, reference can be made
to the work area rather than to A.
When
this technique is used, the conversion is
performed only once, instead of each time
an operation is performed.

Programming Techniques

197

Table 31.

,
IUsage

Data Format Conversion (Part 1 of 2)

,Bytes
,Required
I

,DISPLAY 11 per digit
I (external I (except for
I decimal) I V)

converted
IBoundary 1
I
for
Typical
,Alignmentl
,Arithmetic
Usage
Operations
'Required I
I
1
Yes
I
No
IInput from
,
Icards, output
I
Ito cards,
I
I listings
I

I
I
I
I
I
I

I
,
,
,
I
I

I
,
,
I
I

IDISPLAY 11 per
I (external I character
I floating I (except for
I point)
f V)

I
I
I
I

ICOMP-3
,1 per 2
I (internal digits plus
I decimal) 1 byte for
,
lOW-order
I
digit and
I
sign

IWork areas

,
f
I

,
COMP
(binary)

12 if 1$N$4

Halfword

I
f 4 if 5$NS9

Fullword

18 if 10SNS18

Fullword

,where N is
Ithe number of
19's in the
Ipicture

I
I
1
I
I
I
I

Subscripting

Arithmetic
fields

I
I
I
1
I

Yes

1Sometimes
Iwhen a
small
COllP-3 item
is used
with a
small COftP
item

Converted to COftP-2
format via COBOL library
subroutine.
Requires less space than
DISPLAY.
convenient form for
decimal alignment.
Can be used in arithmetic
computations without
conversion.
Fields over 15 digits
require a subroutine when
used in computations.

Sometimes
for both
mixed and
unmixed
usages

Rounding and testing for
the ON SIZE ERROR
condition are cumbersome
if calculated result is
greater than 9(9).

Extra instructions are
generated for computations if the SYNCHRONIZED
clause is not specified.

Fields of over nine
digits require additional
handling.

,
1
I

198

IInput to a
Ireport item
(fields

1
I

IInput from
Icards, output
Ito cards,
Ilistings

I
I Arithmetic

lIay be used for numeric
fields up to 18 digits
long.
Fields over 15 digits
require extra instructions if used in
computations.

I
I
I
I
I

Special
Characteristics

Table 31.

Data Format Conversion (Part 2 of 2)

I
Converted
IBountary I
I
for
Bytes
IAlignmentl
Typical
IArithmetic
Required
IRequired I
Usage
I Operations
I
I
I
No
Fullword Fractional
I
4 (shortICOMP-1
precision)
exponentiation I
I (internal
I floating
I
I point)
I
I
I
I
I
I
I
I
I
I
I
No
IDouble- I Fractional
I
ICOMP-2
18 (longI exponentiation I
precision) Iword
I (internal I
Iwhen addition-I
I floating I
I
lal precision
I
I point)
I
I
lis required
I
I
I
I

I
I
I
IUsage

The following seven cases show how data
conversions are handled on mixed elementary
items for names, data comparisions, and
arithmetic operations. Moves without the
CORRESPONDING option to and from group
items, as well as comparisons involving
group items, are done without conversion.

Special
Characteristics
Tends to produce less
accurate results if more
than 17 significant
digits are required and
if the exponent is
large.
Extra instructions are
generated for computations if the SYNCHRONIZED
clause is not specified.
Requires floating-point
feature.
Same as COMP-1.

COMPUTATIONAL-3 to COMPUTATIONAL:
To Move Data: Moves COMPUTATIONAL-3 data
to a work area and then converts
COMPUTATIONAL-3 data to COMPUTATIONAL data.
To Compare Data: Converts COMPUTATIONAL
data to COMPUTATIONAL-3 or vice versa,
depending on the size of the field.

Numeric DISPLAY to COMPUTATIONAL-3:
To Move Data: Converts DISPLAY data to
COMPUTATIONAL-3 data.
To Compare Data: Converts DISPLAY data to
COMPUTATIONAL-3 data.

To Perform Arithmetic Operations: Converts
COMPUTATIONAL data to COMPUTATIONAL-3 or
vice versa, depending on the size of the
field.

To Perform Arithmetic Operations: Converts
DISPLAY data to COMPUTATIONAL-3 data.
COMPUTATIONAL to COMPUTATIONAL-3:
Numeric DISPLAY to COMPUTATIONAL:
To Move Data: Converts DISPLAY data to
COMPUTATIONAL-3 data and then to
COMPUTATIONAL data.
To Compare Data: Converts DISPLAY to
COMPUTATIONAL or converts both DISPLAY and
COMPUTATIONAL data to COMPUTATIONAL-3 data.
To Perform Arithmetic Operations: Converts
DISPLAY data to COMPUTATIONAL-3 or
COMPUTATIONAL data.

To Move Data: Converts COMPUTATIONAL data
to COMPUTATIONAL-3 data in a work area, and
then moves the work area.
To Compare Data: Converts COMPUTATIONAL to
COMPUTATIONAL-3 data or vice versa,
depending on the size of the field.
To Perform Arithmetic Operations: Converts
COMPUTATIONAL to COMPUTATIONAL-3 data or
vice versa, depending on the size of the
field.

Programming Techniques

199

COMPUTATIONAL to Numeric DISPLAY:
To Move Data: Converts CO~PUTATIONAL data
to COMPUTATIONAL-3 data antl then to DISPLAY
data.
To Compare Data: Converts DISPLAY to
COMPUTATIONAL or both COMPUTATIONAL and
DISPLAY data to COMPUTATIONAL-3 data,
depending on the size of the field.
To Perform Arithmetic Operations:
Depending on the size of the field,
converts DISPLAY data to COMPUTATIONAL
data, or both DISPLAY and COMPUTATIONAL
data to COMPUTATIONAL-3 data in which case
the result is generated in a
COMPUTATIONAL-3 work area and then
converted and moved to the DISPLAY result
field.
COMPUTATIONAL-3 to Numeric DISPLAY:
To Move Data: Converts COMPUTATIONAL-3
data to DISPLAY data.
To Compare Data: Converts DISPLAY data to
COMPUTATIONAL-3 data. The result is
generated in a COMPUTATIONAL-3 work area
and is then converted and moved to the
DISPLAY result field.
Numeric DISPLAY to Numeric DISPLAY:
To Perform Arithmetic Operations: Converts
all DISPLAY data to COMPUTATIONAL-3 data.
The result is generated in a
COMPUTATIONAL-3 work area and is then
converted to DISPLAY and moved to the
DISPLAY result field.
Internal Floating-point to Any Other: When
an item described as COMPUTATIONAL-lor
COMPUTATIONAL-2 (internal floating-point)
is used in an operation with another data
format, the item in the other data format
is always converted to internal floatingpoint. If necessary, the internal
floating-point result is then converted to
.the format of the other data item.

SYNCHRONIZED Clause
As illustrated in Table 31,
COMPUTATIONAL, COMPUTATIONAL-1 and
COMPUTATIONAL-2 items have specific
boundary alignment requirements. To ensure
correct alignment, either the programmer or
the compiler may have to insert slack bytes
or the compiler must generate extra
instructions to move the item to a
correctly aligned work area when reference
is made to the item.
200

The SYNCHRONIZED clause may be used at
the elementary level to specify the
automatic alignment of elementary items on
their proper boundaries, or at the 01 level
to synchronize all elementary items within
the group. For COMPUTATIONAL items, if the
PICTURE is in the range of S9 through
S9(4j, the item is aligned on a halfword
boundary. If the PICTURE is in the range
of S9(5) through S9(18), the item is
aligned on a fullword boundary. For
COMPUTATIONAL-1 items, the item is aligned
on a fullword boundary. For
COMPUTATIONAL-2 items, the item is aligned
on a doubleword boundary. The SYNCHRONIZED
clause and slack bytes are fully discussed
in the publication IBM System/360 Disk
Operating System: Full American National
Standard COBOL.
Special Considerations for DISPLAY and
COMPUTATIONAL Fields
NUMERIC DISPLAY FIELDS: Zeros are not
inserted into numeric DISPLAY fields by the
instruction set. When numeric DISPLAY data
is moved, the compiler generates
instructions that insert any necessary
zeros into the DISPLAY fields. When
numeric DISPLAY data is compared, and one
field is smaller than the other, the
compiler generates instructions to move the
smaller item to a work area where zeros are
inserted.
COMPUTATIONAL FIELDS: COMPUTATIONAL fields
can be aligned on either a half word or
fullword boundary. If an operation
involves COMPUTATIONAL fields of different
lengths, the halfword field is
automatically expanded to a fullword field.
Therefore, mixed halfword and fullword
fields require no additional operations.
COMPUTATIONAL-1 AND COMPUTATIONAL-2 FIELDS:
If an arithmetic operation involves a
mixture of short-precision and
long-precision fields, the compiler
generates instructions to expand the
short-precision field to a long-precision
field before the operation is executed.
COMPUTATIONAL-3 FIELDS: The compiler does
not have to generate instructions to insert
high-order zeros for ADD and SUBTRACT
statements that involve COMPUTATIONAL-3
data. The zeros are inserted by the
instruction set.
Data Formats in the Computer
The following examples illustrate how
the various COBOL data formats appear in
the computer in EBCDIC (Extended

Binary-Coded-Decimal Interchange Code)
format. More detailed information about
these data formats appear in the
publication IBM System/370 Principles of
operation.

Note that a leading zero is inserted in the
above example.

COMPUTATrO~Bin~:

Numeric DISPLAY (External Decimal):
Suppose the value of an item is -1234, and
its PICTURE and USAGE clauses are:

Suppose the value
of an item is 1234, and its PICTURE and
USAGE clauses are:
PICTURE S9999 COMPUTATIONAL.

PICTURE 9999 DISPLAY.
The item appears internally in the
following form:

0000

PICTURE S9999 DISPLAY.

F3 I F4
,

F3 I D4 I
I

0010

Sign
Position

Byte

1101

The item appears in the computer in the
following forms, respectively:

0100

A a in the sign position indicates that
the number is positive. Negative numbers
are represented in two's complement form;
thus, the sign position of a negative
number will always contain a 1.

Byte
Hexadecimal F is treated arithmetically as
positive; hexadecimal D represents a minus
sign.

For example -1234 would appear as
follows:
1111

COMPUTATIONAL-3 (Internal Decimal) :
Suppose the value of an item is +1234, and
its PICTURE and USAGE clauses are:

1011

0010

1110

S~gn

Position
PICTURE 9999 COMPUTATIONAL-3.
or
PICTURE S9999 COftPUTATIONAL-3.
The item appears internally in the
following forms, respectively:
01

23 I 4F I
I

Binary Item Manipulation: A binary item is
allocated storage ranging from one halfword
to two fullwords, depending on the number
of 9 1 s in its PICTURE. Table 32 is an
illustration of how the compiler allocates
this storage. Note that it is possible for
a value larger than that implied by the
PICTURE clause to be stored in the item.
For example, PICTURE S9(4} implies a
maximum value of 9,999, although it could
actually hold the number 32,767.

Byte
01

23 I 4C I
I

Byte
Hexadecimal F is treated arithmetically as
positive; hexadecimal C represents a plus
sign.
Note: Since the low-order byte of an
internal decimal number always contains a
sign field, an item with an odd number of
digits can be stored more efficiently than
an item with an even number of digits.

Because most binary items are
manipulated according to their allotted
storage capacity, the programmer can ignore
this situation. For the following reasons,
however, he must be careful of his data:
1.

When the ON SIZE ERROR option is used,
the size test is made on the basis of
the maximum value allowed by the
picture of the result field.
If a

size error condition exists, the value
of the result field is not altered and
control is given to the imperativestatements specified by the error
option.
Programming Techniques

201

Table 32.

Relationship of PICTURE to Storage Allocation

I
PICTURE
i
159 through S9(4)
I
159(5) through S9(9)
I
IS9(10) through S9(18)

Maximum Working Value

Assigned Storage

32,767

One halfword

2,147,483,647

One fullword

9,223,372,036,854,775,807

Two fullwords

Note:
If TRUNC option is used and data is moved to decimal receiving field, then
maximum working value for S9(10) through S9(18) PICTURE is 2,147,483,647,999,999,999.
2.

Bits 1 through 7 are the exponent
(characteristic) of the number.

When a binary item is displayed or
exhibited, the value used is a
function of the number of 9 1 s
specified in the PICTURE clause.

Bits 8 through 31 are the fraction
(mantissa) of the number.

When the actual value of a positive
number is significantly larger than
its picture value, a value of 1 could
appear in the sign position of the
item, causing the item to be treated
as a negative number in subsequent
operations.

Figure 58 illustrates three binary
manipulations. In each case, the result
field is an item described as PICTURE S9
COMPUTATIONAL. One halfword of storage has
been allocated, and no ON SIZE ERROR option
is involved. Note that if the ON SIZE
ERROR option had been specified, it would
have been executed for cases Band C.
COMPUTATIONAL-lor COMPUTATIONAL-2
(Floating-point): Suppose the value of an
item is +1234 and that its USAGE is
COMPUTATIONAL-1, the item appears
internally in the following form:
101100
I

001110100 1101 0010 0000 0000 00001

S 1

7 8

S is the sign position of the number.

o in the sign position indicates that
the sign is plus.
1 in the sign position indicates that
the sign is minus.

Case

Hexadecimal Result of
Binary Calculation

PROCEDURE DIVISION
The Procedure Division of a program can
often be made more efficient or easier to
debug by using some of the techniques
described below.

MODULARIZING THE PROCEDURE DIVISION
Modularization involves organizing the
Procedure Division into at least three
functional levels: a main-line routine,
processing subroutines, and input/output
subroutines. When the Procedure Division
is modularized, programs are easier to
maintain and document. In addition,
modularization makes it simple to break
down a program using the segmentation
feature, resulting in a more efficient
segmented program. Virtual storage
implications should be taken into

Actual Decimal Value
in Halfword of Storage

DISPLAY or
EXHIBIT Value

0008

OOOA

+10

C350

50000

-15536

Figure 58.
202

Decimal
Equivalent

This form of data is referred to as
floating point. The example illustrates
short-precision floating-point data
(COMPUTATIONAL-1). In long-precision
(COMPUTATIONAL-2), the fraction length is
56 bits.
(For a detailed explanation of
floating-point representation, see the
publication IBM System/370 Principles of
Operation.)

Treatment of Varying Values in a Data Item of PICTURE S9

consideration when rearranging the
Procedure Division. The COUNT option is
useful in determining a rearrangement
scheme.

OVERALL CONSIDERATIONS

OPTIMIZE Option
Main-Line Routine
The main-line routine should be short
and simple, and should contain all the
major logical decisions of the program.
This routine controls the order in which
second-level subroutines are executed. All
second-level subroutines should be invoked
from the main-line routine by PERFORM
statements.

If the OPTIMIZE option is in effect, the
number of procedure blocks in a program
cannot exceed 255. A procedure block is
equivalent to approximately 4096 bytes of
Procedure Division code.
If the COUNT option is in effect, the
number of verb blocks in a program cannot
exceed 32,767. A verb block consists of a
set of verbs in which any verb (excluding
ABEND) in the block is executed if and only
if all verbs in the block are executed.
The average program Procedure Division
contains approximately three verbs per verb
block.

Processing Subroutines
Processing subroutines should be broken
down into as many functional levels as
necessary, depending on the complexity of
the program. These must be completely
closed subroutines, with one entry point
and one exit point. The entry point should
be the first statement of the subroutine.
The exit point should be the EXIT
statement. Processing subroutines can
PERFORM only lower level subroutines;
return to the higher level subroutine
J
-> A-I

The hyphen is converted to zero if it
appears as the second through eighth
character.

The RERUN' clause is fully described in
the publication IBM DOS Full American
National Standard COBOL.

USING SORT IN A MULTIPHASE ENVIRONMENT
When the Sort program is invoked in a
multiphase environment, the following
should be noted:
1.

It is the programmer's responsibility
to ensure that the COBOL program
containing the SORT statement is the
highest phase in storage.

If two programs are compiled, link
edited, and executed together, only
one program may use the Sort feature.
If both programs require Sort, the
programs can be compiled separately
and then the decks must be organized
so that the dummy phase cards for Sort
are both together at the end of the
deck before they are link edited and
executed.

If Debug and Sort are used together,
the Debug modules must be included
in the root phase.

CHECKPOINT/RESTART DURING A SORT
The Checkpoint/Restart Feature is
available to the programmer using the COBOL
SORT statement. The programmer uses the
RERUN clause to specify that checkpoints
should be taken during program execution.
The control statement requirements for
taking a checkpoint are discussed in the
section entitled "Program Checkout."
Checkpoint/Restart is not available during
a merge operation.
The system-name specified in the RERUN
clause as the sort checkpoint device must
not be the same as any system-name used in
the source language ASSIGN clause, but
follows the same rules of formation.

210

USING THE REPORT WRITER FEATURE

REPORT Clause in a File Description (FD)
Entry
A given report-name may appear in a
maximum of two file description entries.
The file description entries need not have
the same characteristics, but both must be
standard sequential.
If the same
report-name is specified in two file
description entries, the report will be
written on both files.
For example:
ENVIRONMENT DIVISION.
SELECT FILE-1 ASSIGN SYS005-UR-1403-S.
SELECT FILE-2 ASSIGN SYS001-UT-2400-S.
DATA DIVISION.
FD FILE-l RECORDING MODE F
RECORD CONTAINS 121 CHARACTERS
REPORT IS REPORT-A.
FD FILE-2 RECORDING MODE V
RECORD CONTAINS 101 CHARACTERS
REPORT IS REPORT-A.
For each GENERATE statement, the records
for REPORT-A will be written on FILE-l and
FILE-2, respectively. The records on
FILE-2 will not contain columns 102 through
121 of the corresponding records on FILE-l.

Method 1:
01 TYPE CONTROL FOOTING YEAR.
02 SUM COST.
01 TYPE CONTROL FOOTING MONTH.
02 SUM COST.
01 TYPE CONTROL FOOTING WEEK.
02 SUpi COST.

01 TYPE CONTROL FOOTING ADAY.
02 SUM COST.
Method 2:
01 TYPE CONTROL FOOTING
02 SUM A.
01 TYPE CONTROL FOOTING
02 A SUM B.
01 TYPE CONTROL FOOTING
02 B SUM C.
01 TYPE CONTROL FOOTING
02 C SUM COST.

YEAR.
MONTH.
WEEK.
ADAY.

Method 2 will execute faster. One
addition will be performed for each day,
one more for each week, and one for each
month.
In Method 1, four additions will be
performed for each day.

Use of SUM

Summing Techniques
Execution time of an object program can
be decreased by keeping in mind that Report
Writer source coding is treated as though
the programmer had written the program in
COBOL without the Report Writer feature.
Therefore, a complex source statement or
series of statements will generally be
executed faster than simple statements that
perform the same function. The following
example shows two coding teChniques for the
Report section of the Data Division.
Method 2 uses the more complex statements.
RD ••• CONTROLS ARE YEAR MONTH WEEK DAY.

Unless each identifier is the name of a
SUM counter in a TYPE CONTROL FOOTING
report group at an equal or lower position
in the control hierarchy. the identifier
must be defined in the File, WorkingStorage, or Linkage sections as well as in
a TYPE DETAIL report group as a source item
or no summing will occur. A SUM counter is
algebraically incremented just before
presentation of the TYPE DETAIL report
group in which the item being summed
appears as a source item or the item being
summed appeared in a SUM clause that
contained an UPON option for this DETAIL
report group. This is known as SOURCE-SUM
correlation. In the following example,
SUBTOTAL is incremented only when DETAIL-l
is generated.

Using the Report Writer Feature

211

sequence in which the DETAIL report groups
are specified.

FILE SECTION.

02 NO-PURCHASES

PICTU~E

99.

REPORT SECTION.
01 DETAIL-l TYPE DETAIL.
02 COLUMN 30 PICTURE 99 SOURCE
NO-PURCHASES.

The following two examples show the SUM
routines that are generated by the Report
Writer.
Example 1 illustrates how operands
are selected for inclusion in the routine
on the basis of simple SOURCE-SUM
correlation. Example 2 illustrates how
operands are selected when the UPON
detail-name option is specified.
Example 1: The following statements are
coded in the Report Section:

01 DETAIL-2 TYPE DETAIL.

01 ADAY TYPE CONTROL FOOTING
LINE PLUS 2.

01 DETAIL-l TYPE DE
02 ••• SOURCE A.

01 DETAIL-2 TYPE DE
02 ••• SOURCE B.
02 ••• SOURCE C.

02 SUBTOTAL COLUMN 30 PICTURE 999
SUM NO-PURCHASES.
01 DETAIL-3 TYPE DE
02 ••• SOURCE B.
01 MONTH TYPE CONTROL FOOTING
LINE PLUS 2 NEXT GROUP
NEXT PAGE.

01 TYPE CF •••
02 SUM-CTR-l ••• SUM A, B, C.

SUM Routines
A SUM routine is generated by the Report
Writer for each DETAIL report group of the
report. The operands included for summing
are determined as follows:
1.

The SUM operand(s} also appears in a
SOURCE clause(s} for the DETAIL report
group.
The UPON detail-name option was
specified in the SUM clause.
In this
case, all the operands are included in
the SUM routine for only that DETAIL
report group, even if the operand
appears in a SOURCE clause in other
DETAIL report groups.

When a GENERATE detail-name statement is
executed, the SUM routine for that DETAIL
report group is executed in its logical
sequence. When GENERATE report-name
statement is executed and the report
contains more than one DETAIL report group,
the SUM routine is executed for each one.
The SUM routines are executed in the

212

01 TYPE CF •••
02 SUM-CTrt-2 ••• SUM B.
A SUM routine is generated for each
DETAIL report group, as follows:
SUM-ROUTINE FOR DETAIL-l
REPORT-SAVE
ADD A TO SUM-CTR-l.
REPORT-RETURN
SUM-ROUTINE FOR DETAIL-2
REPORT-SAVE
ADD B TO SUM-CTR-l.
ADD C TO SUM-CTR-l.
ADD B TO SUM-CTR-2.
REPORT-RETURN
SUM-ROUTINE FOR DETAIL-3
REPORT-SAVE
ADD B TO SUM-CTR-l.
ADD B TO SUM-CTR-2.
REPORT~RETURN

Heading at the top of each page, he
must include the information and data
to be printed as part of the Page
Heading. Since only one Page Reading
may be specified for each report, he
should be selective in considering his
Control Heading because it will be the
same for each page, and may be printed
at inappropriate times (see "Control
Footings and Page Format" in this
chapter) ~

Example 2: This example uses the same
coding as Example 1, with one exception:
the UPON detail-name option is used for
SUM-CTR-1, as follows:
01 TYPE CF
02 SUM-CTR-1 ••• SUM A, B, C
UPON DETAIL-2.
The following SUM routines would then be
generated instead of those shown in the
previous example:
2e

SUM Routine for DETAIL-l
REPORT-SAVE
REPORT-RETURN
SUM Routine for DETAIL-2
REPORT-SAVE
ADD A TO SUM-CTR-l.
ADD B TO SUM-CTR-1.
ADD C TO SUM-CTR-l.
ADD B TO SUM-CTR-2.
REPORT-RETURN

GROUP INDICATE items are printed after
page and control breaks. -Figure 56
contains a GROUP INDICATE clause and
illustrates the execution output.

REPORT SECTION.

DETAIL-LINE TYPE IS DETAIL LINE
NUMBER IS PLUS 1.
02 COLUMN IS 2 GROUP INDICATE
PICTURE IS A(9) SOURCE IS
MONTHNAME OF RECORD-AREA (MONTH).

SUM Routine for DETAIL-3
REPORT-SAVE
ADD B TO SUM-CTR-2.
REPORT-RETURN

(Execution Output)
IJANUARY

output Line Overlay
The Report writer output line is created
using an internal REDEFINES specification,
indexed by inteqer-1. No check is made to
prevent overlay on any line. For example:
02
02

COLUMN 10 PICTURE X(23)
VALUE "MONTHLY SUPPLIES REPORT".
COLUMN 12 PICTURE X(9)
SOURCE CURRENT-MONTH.

A length of 27 in column 10, followed by a
specification for column 12, will cause
field overlay when this line is printed.
Page Breaks
The Report Writer page break routine
operates independently of the routines that
are executed after any control breaks
(except that a page break will occur as the
result of a LINE NEXT PAGE clause). Thus,
the programmer should be aware of the
following facts:
1.

A Control Heading is not printed after
a Page Heading except for first
generation. If the programmer wishes
to have the equivalent of a Control

AOO •••

A02 •••
I
I
I PURCHASES AND COST •••
I
IJANUARY
I

Figure 59.

A03 •••
A03 •••

Sample of GROUP INDICATE Clause
and Resultant Execution output

WITH CODE Clause
When more than one report is being
written on a file and the reports are to be
selectively written, a unique l-character
code must be given for each report. A
mnemonic-name is specified in the RD-Ievel
entry for each report and is associated
with the code in the Special-Names
paragraph of the Environment Division.
Note: If a report is written with the CODE
option, the report should not be written
directly on a printer device.
This code will be written as the first
character of each record that is written on
the file. When the programmer wishes to
write a report from this file, he needs
Using the Report Writer Feature

213

only to read a record, check the first
character for the desired code, and have it
printed if the desired code is found.
The
record should be printed starting from the
third character, as illustrated in Figure
60.

I
ICode
1

Figure 60.

PRINT-REC.
05 FILLER

PICTURE 1(121).

PROCEDURE DIVISION.
LOOP.

Format of a Report Record When
the CODE Clause is Specified

The following example shows how to
create and print a report with a code of A.
A Report Writer program contains the
following statements:

READ RPT-IN-FILE AT END
GO TO CONTINUE.
IF CODE-CBR = "A"
WRITE PRINT-REC FROM PRINT-PART
AFTER POSITIONING CTL-CBR LINES.
GO TO LOOP.
CONTINUE.

Control Footings and Page Format

ENVIRONMENT DIVISION.
SPECIAL-NAMES.

"A" IS CODE-CHR-A
"B" IS CODE-CBR-B.

DATA DIVISION.
REPORT SECTION.
RD REP-FILE-A

CODE CODE-CHR-A •••

CODE CODE-CHR-B •••

REP-FILE-B

A second program could then be used to
print only the report with the code of A,
as follows:
DATA DIVISION.
FD RPT-IN-FILE
RECORD CONTAINS 122 CHARACTERS
LABEL RECORDS ARE STANDARD
DATA RECORD IS RPT-RCD.
01 RPT-RCD.
05 CODE-CBR
PICTURE X.
05 PRINT-PART.
10 CTL-CHR
PICTURE I.
10 RECORD-PART PICTURE X(120).
FD PRINT-FILE
RECORD CONTAINS 121 CHARACTERS
LABEL RECORDS ARE STANDARD
DATA RECORD IS PRINT-REC.

214

Depending on the number and size of
Control Footings (as well as the page depth
of the report), all of the specified
Control Footings may not be printed on the
same page if a control break occurs for a
high-level control. When a page condition
is detected before all required Control
Footings are printed, the Report Writer
will print the Page Footing (if specified),
skip to the next page, print the Page
Beading (if specified) and then continue to
print Control Footings.
If the programmer wishes all of his
Control Footings to be printed on the same
page, he must format his page in the
RD-level entry for the report (by setting
the LAST DETAIL integer to a sufficiently
low line number) to allow for the necessary
space.

NEXT GROUP Clause
Each time a CONTROL FOOTING report group
with a NEXT GROUP clause is printed, the
clause is activated only if the report
group is associated with the control that
causes the break. This is i1lustrated in
Figure 61.

EXPENSE-REPORT CONTROLS ARE FINAL,
MONTH, ADAY

TYPE CONTROL FOOTING DAY
LINE PLUS 1 NEXT GROUP
NEXT PAGE.

relative line as its first line will have
its relative line~pacing suppressed; the
first line will be printed on either the
value of FIRST DETAIL or INTEGER PLUS 1 of
a NEXT GROUP clause from the preceding
page. For example:

If the following body group was the
last to be printed on a page
01

TYPE CONTROL FOOTING "ONTE
LINE PLUS 1 NEXT GROUP
NEXT PAGE.

TYPE CF NEXT GROUP NEXT PAGE

then this next body group
01

TYPE DE LINE PLUS 5

would be printed on value of FIRST
DETAIL (in PAGE clause) •
(Execution Output)

If the following body group was the
last to be printed on a page

EXPENSE REPORT
01
January 31 ••••••••• 29.30
(Output for CF ADAY)
January total ••••• 131.40
(Output for CF MONTH)
igure 61.

Activating the NEXT GROUP
Clause

Note: The NEXT GROUP NEXT PAGE clause for
the Control Footing DAY is not activated.

Floating First Detail
The first presentation of a body group
(PH, PF, CH, CF, DE) that contains a

TYPE CF NEXT GROUP LINE 12

and after printing, line-counter
then this next body group
01

40,

TYPE DETAIL LINE PLUS 5

would be printed on line 12 + 1 (i.e.,
line 13).

Report Writer Routines
At the end of the analysis of a report
description (RD) entry, the Report Writer
routines are generated, based on the
contents of the RD. Each routine
references the compiler-generated card
number of its respective RD.

Using the Report Writer Feature

215

TABLE HANDLING

Subscripts
If a subscript is represented by a
constant and if the subscripted item is of
fixed length, the location of the
subscripted data item within the table or
list is resolved during compilation.
If a subscript is represented by a
data-name, the location is resolved at
execution time. The most efficient format
in this case is COMPUTATIONAL, with a
PICTURE size less than five integers.
The value contained in a subscript is an
integer which represents an occurrence
number within a table.
Every time a
subscripted data-name is referenced in a
program, the compiler generates up to 16
instructions to calculate the correct
displacement. Therefore, if a subscripted
data-name is to be processed extensively,
move the subscripted item to an
unsubscripted work area, do all necessary
processing, and then move the item back
into the table. Even when subscripts are
described as COMPUTATIONAL, subscripting
takes time and storage.

Index-names
Index-names are compiler-generated
items, one fullword in length, assigned
storage in the TGT (Task Global Table). An
index-name is defined by the INDEXED BY
clause. The value in an index-name
represents an actual displacement from the
beginning of the table that corresponds to
an occurrence number in the table. Address
calculation for a direct index requires a
maximum of four instructions; address
calculation for a relative index requires a
few more. Therefore, the use of
index-names in referencing tables is more
efficient than the use of subscripts. The
use of direct indexes is faster than the
use of relative indexes.

CONSIDERATI~S

that are assigned storage within the COBOL
program area. An index data item is
defined by the USAGE IS INDEX clause. The
programmer can use index data items to save
values of index-nawes for later reference.
Great care must be taken when setting
values of index data items. Since an index
data item is not part of any table, the
compiler is unable to change any
displacement value contained in an
index-name when an index data item is set
to the value of an index-name or another
index data item. See the SET statement
examples later in this chapter.
Index data items can only be referenced
in SEARCH and SET statements.

OCCURS Clause
If indexing is to be used to reference a
table element and the Format 2 (SEARCH ALL)
statement is also used, the KEY option must
be specified in the OCCURS clause. A table
element is represented by the subject of an
OCCURS clause. and is equivalent to one
level of a table. The table element must
then be ordered upon the keyes) and
data-name(s) specified.

DEPENDING ON Option
If a data item described by an OCCURS
clause with the DEPENDING ON data-name
option is followed by nonsubordinate data
items, a change in the value of data-name
during the course of program execution will
have the following effects:
1.

The size of any group described by or
containing the related OCCURS clause
will reflect the new value of
data-name.

Whenever a MOVE to a field containing
an OCCURS clause with the DEPENDING ON
option is executed, the MOVE is done
on the basis of the current contents
of the object of the DEPENDING ON
option.

The location of
items following
with the OCCURS
affected by the

Index-names can only be referenced in
the PERFORM, SEARCH, and SET statements.

Index Data Items
Index data items are compiler-generated
storage positions, one fullword in length,

any nonsubordinate
the item described
clause will be
new value of

Table Handling Considerations

217

data-name.
If the programmer wlsnes
to preserve the contents of these
items, the following procedure can be
used:
prior to the change in
data-name, move all nonsubordinate
items following the variable item to a
work area; after the change in
data-name, move all the items back.
Note: The value of data-name may change
because a move is made to i t or to the
group in which it is contained; or the
value of data-name may change because the
group in which it is contained is a record
area that has been changed by execution of
a READ statement.
For example, assume that the Data
Division of a program contains the
following coding:
01

ANYRECORD.
05 A PICTURE S999 COMPUTATIONAL-3.
05 TABLEA PICTURE S999 OCCURS 100
TIMES DEPENDING ON A.
05 GROUPB.

as VSAM files, may contain one or more
OCCURS clauses with the DEPENDING ON
option.
This section discusses some factors that
affect the manipulation of records
containing OCCURS clauses with the
DEPENDING ON option.
The text indicates
whether the factors apply to the File or
Working-Storage sections, or both.
The compiler calculates the length of
V-mode records containing the OCCURS clausE
with the DEPENDING ON option at three
different times, as follows (the first and
third applies to FD entries only; the
second to both FD and Working-Storage
entries):
1.

When a file is read and the object of
the DEPENDING ON option is within the
record.

When the object of the DEPENDING ON
option is changed as a result of a
move to it or any item within its
group.
(The length is not calculated
when a move is made to an item which
redefines or renames it.)

Subordinate data items.
End of record.
GROUPB items are not subordinate to TABLEA,
which is described by the OCCURS clause.
Assuming that WORKB is a work area with the
same data structure as GROUPB, the
following procedural coding could be used:

For instance before a group item
with an OCCURS DEPENDING ON clause
in it can be moved from an I/O
area to working storage, the
object of the DEPENDING ON clause
must be moved separately from the
I/O area to the corresponding
area in working storage to force
initial calculation of the
receiving field's length.

MOVE GROUPB TO WORKB
Calculate a new value of A
MOVE WORKB TO GROUPB

If the object of the DEPENDING ON
option is changed outside of the
COBOL program, to insure correct
length, a dummy move of the
DEPENDING ON object must be made
upon return to the COBOL program.

The preceding statements can be avoided
by placing the OCCURS clause with the
DEPENDING ON option at the end of the
record.
Note: data-name can also change because of
a change in the value of an item that
redefines or renames it.
In this case, th~
group size and the location of
nonsubordinate items as described in the
two preceding paragraphs cannot be
determined.

For an output file, after the record
is written, the length is set to
maximum to enable a full move of the
next record to the buffer.
Immediately after the move, the
correct length is recalculated as in
item 2.
Consider the following example:

OCCURS CLAUSE WITH THE DEPENDING ON OPTION
If a record description contains an
OCCURS clause with the DEPENDING ON option,
the record length is variable. This is
true for records described in an FD as well
as in the working-Storage section. A
previous chapter discussed four different
record formats of non-VSAM files.
Three of
them, V-mode, U-mode, and S-mode, as well
218

WORKING-STORAGE SECTION.
77
77

CONTROL-1
WORKAREA-1

SALAHY-HISTORYe
05 SALARY OCCURS 0 TO 10 TIMES
DEPENDING ON
CONTROL-1 PIC 9(6)V99.

PIC 99.
PIC 9(6)V99.

The Procedure Division statement MOVE
5 TO CONTROL-1 will cause a recalculation
of the length of SALARY-HISTORY. MOVE
SALARY (5) TO WORKAREA-1 will not cause
the length to be recalcula~~d.
The compiler permits ,the occurrence of
more than one level-01 record, containing
the OCCURS clause with the DEPENDING ON
option, in the same FD entry (see Figure
62). For non-VSAM files, if the BLOCK
CONTAINS clause is omitted, the buffer size
is calculated from the longest level-a'
record description entry. In Figure 62,
the buffer size is determined by the
description of RECORD-1 (RECORD-1 need not
be the first record description under the
FD).
During the execution of a READ
statement, the length of each level-01
record description entry in the FD will be
calculated (see Figure 62). The length of
the variable portion of each record will be
the product of the numeric value contained
in the object of the DEPENDING ON option
and the length of the subject of the OCCURS
clause. In Figure 62, the length of
FIELD-1 is calculated by multiplying the
contents of CONTROL-1 by the length of
FIELD-1; the length of FIELD-2, by the
product of the contents of CONTROL-2 and
the length of FIELD-2i the length of
FIELD-3 by the contents of CONTROL-3 and
the length of FIELD-3.
Since the execution of a READ statement
makes available only one record type (i.e.,
RECORD-1 type, RECORD-2 type, or RECORD-3
type), two of the three record descriptions
in Figure 62 will be inappropriate. In
such cases, if the contents of the object
of the DEPENDING ON option does not conform
to its picture, th~ length of the
corresponding record will be unpredictable.
For the contents of an item to conform to
its picture:
item described as USAGE DISPLAY must
contain external decimal data.

The following example illustrates the
length calculations made by the system when
a READ statement is executed:
FD

RECORD-1.
05 A PIC 99.
05 B PIC 99.
05 C PIC 99 OCCURS 5 TIMES
DEPENDING ON A.

RECORD-2.
05 D PIC XX.
05 EPIC 99.
05 F PIC 99.
05 G PIC 99 OCCURS 5 TIMES
DEPENDING ON F.

WORKING-STORAGE SECTION.

~ABLE-3.

05
01

H PIC99 OCCURS 10 TIMES DEPENDING
ON B.

TABLE-4.
05 I PIC99 OCCURS 10 TIMES DEPENDING
ON E.

When a record is read, lengths are
determined as follows:
1.

The length of C is calculated using
the contents of field A. The length
of RECORD-1=A+B+C.

The length of G is calculated using
the contents of field F. The length
of RECORD-2=D+E+F+G.

The length of TABLE-3 is calculated
using the contents of field B.

The length of TABLE-4 is calculated
using the contents of field E.

• An

• An item described as USAGE
COMPUTATIONAL-3 must contain internal
decimal data.

The programmer should be aware of
several characteristics of the previously
cited length calculations. The following
example illustrates a group item (i.e.,
REC-1) whose subordinate items contain an
OCCURS clause with the DEPENDING ON option
and the object of that DEPENDING ON option.

• An item described as USAGE
COMPUTATIONAL must contain binary data.
• An item described as signed must

contain signed data.
item described as unsigned must
contain unsigned data.

• An

WORKING-STORAGE SECTION.
01 REC-l.
05 FIELD-l PIC 9.
05 FIELD-2 OCCURS 5 TIMES DEPENDING ON
FIELD-l PIC XeS).

Table Handling Considerations

219

r---------------------------------------------------------------------------------------,
INPUT-FILE

I FD
I
I
01

DATA RECORDS ARE RECORD-l RECORD-2 RECORD-3.
RECORD-l.
05 CONTROL-l
PIC 99.
05 FIELD-l OCCURS 0 TO 10 TIMES DEPENDING ON CONTROL-l
RECORD-2.
05 CONTROL-2
PIC 99.
05 FIELD-2 OCCURS 1 TO 5 TIMES DEPENDING ON CONTROL-2
RECORD-3.
05 FILLER
PIC XX.
05 CONTROL-3
PIC 99.
05 FIELD-3 OCCURS 0 TO 10 TIMES DEPENDING ON CONTROL-3

Figure 62.

PIC 9(4).

PIC X(4) .•

Calculating Record Lengths When Using the OCCURS Clause with the DEPENDING ON
Option

REC-2.
05 REC-2-DATA

PIC X(50).

The results of executing a MOVE to the
group item REC-1 will be affected by the
following:
• The length of REC-1 may have been
calculated at some time prior to the
execution of this MOVE statement.
The user should make sure that REC-I
reflects the correct length.

• The length of REC-I may never have been
calculated at all, and the result of the
MOVE will be unpredictable.

• After the move, since the contents of
FIELD-1 have been changed, an attempt
will be made to recalculate the length
of REC-l. Correct recalculation,
however, will only be made if the new
contents of FIELD-1 conform to its
picture (i.e., USAGE DISPLAY must
contain an external decimal item, USAGE
COMPUTATIONAL-3 must contain an
internal decimal item and USAGE
COMPU'IATIONAL must contain a binary
item. An item described as signed must
contain signed data, and an item
described as unsigned must contain
unsigned data).
In the preceding
example, if FIELD-l does not contain an
external decimal item, the length of
REC-l will be unpredictable.
Note: According to the COBOL description,
FIELD-2 can occur a maximum of five times.
If, however, FIELD-l contains an external
decimal item whose value exceeds five, the

220

PIC 9(5).

length of REC-l will still be calculated.
One possible consequence of this invalid
calculation will be encountered if the
programmer attempts to initialize REC-l by
moving zeros or spaces to it. This
initialization would inadvertently delete
part of the adjacent data stored in REC-2.
The following discussion applies to
updating a record containing an OCCURS
clause with the DEPENDING ON option and at
least one other subsequent entry. In this
case, the subsequent entry is another item
containing an OCCURS clause with the
DEPENDING ON option.
WORKING-STORAGE SECTION.
01 VARIABLE-REC.
05 FIELD-A
PIC X(10).
05 CONTROL-l
PIC 99.
05 CONTROL-2
PIC 99.
05 VARY-FIELD-1 OCCURS 10 TIMES
DEPENDING ON CONTROL-l PIC X(5).
05 TEMP.
06 VARY-FIELD-2 OCCURS
10 TIHES DEPENDING ON
CONTROL-2 PIC X(9).
01 STORE-VARY-FIELD-2.
05 VARY-FLD-2 OCCURS 10 TIMES
DEPENDING ON CONTROL-2 PIC X(9).
Assume that CONTROL-l contains the value
5 and VARY-FIELD-1 contains 5 entries.
In order to add a sixth field to
VARY-FIELD-l the following steps are
required:
MOVE TEHP TO STORE-VARY-FIELD-2.
ADD 1 TO CONTROL-l.
MOVE 'additional field' TO VARY-FIELD-l
(CONTROL-l).
MOVE STORE-VARY-FIELD-2 TO TEMP.

SET statement
The SET statement is used to assign
values to index-names and to index data
items.
When an index-name is set to the value
of a literal, identifier, or an index-name
from another table element, it is set to an
actual displacement from the beginning of
the table that corresponds to the
occurrence number indicated by the second
operand in the statement.
The compiler
performs the necessary calculations.
If an
index-name is set to another index-name for
the same table, the compiler need make no
conversion of the actual displacement value
contained in the second operand.
However, when an index data item is set
to another index data item or to an
index-name, or when an index-name is set to
an index data item, the compiler is unable
to change any displacement value i t finds,
since an index data item is not part of any
table.
Thus, no conversion of values can
take place. Remember this to avoid making
programming errors.
For example, suppose that a table has
been defined as:

01 A.
05 B OCCURS 2 INDEXED BY 11, IS.
10 C OCCURS 2 INDEXED BY 12, 16.
15 D OCCURS 3 INDEXED BY 13, 14.
20 EPIC X(20).
20 F PIC 9 (5),
The table appears in storage as shown in
Figure 63.
Suppose that a reference to D (2, 2, 3)
is necessary.
The following wethod is
incorrect:
SET 13 TO 2.
SET INDX-DATA-I~M TO 13.
SET 13 UP BY 1.
SET 12, 11 TO INDX-DATA-ITM.
MOVE D (11, I2, 13) TO WORKAREA.
The value contained in 13 after the first
SET statement is 25, which represents the
beginning point of the second occurrence of
D. When the second SET statement is
executed, the value 25 is placed in
INDX-DATA-ITM, and the fourth SET statement
moves the value 25 into 12 and 11. The
third SET statement increases the value in
13 to 50. The calculation for the address
D (11, 12, 13) would then be as follows:
(address of D (1, 1, 1») + 25 + 25 + 50
= (address of D (1. 1, 1» + 100
This is not the address of D (2, 2, 3).

Byte

(1,1,1)

~cc
B (1)

(1, 1)

\ D (1,1,3)

(1. 2)

~cc

(2,1)

(1, 2, 2)

r------------------+---f 125
(1, 2, 3)
(2, 1, 1)

\ D (2,1,3)

(2. 2)

---+---f 100

(2, 2, 1)
(

r------------------+-~

(1, 2, 1)

(2, 1, 2)

B (2)

(1, 1, 2)

E
F
I
~------------------+-~
E
F
I
r-------------------r---~,
E
F
I

(2, 2, 2)
(2, 2, 3)

~------------------~--f

150

E
F
I
r-------------------~--~i
E
F
I

175

r------------------r----;I 200
E

r-----------------r---~t

225

E
F I
r-------------------r---~I
E
F
I

250

r---------------------~----__1f

275

I
300

Figure 63.

Table Structure in Virtual storage
Table Handling Considerations

221

The following method will find the
correct address:
SET 13 TO 2.
SET 12, 11 TO 13.
SET 13 UP BY 1.
In this case, the first SET statement
places the value 25 in 13. Since the
compiler is able to calculate the lengths
of Band C, the second SET statement places
the value 75 in 12, and the value 150 in
11. The third SET statement places the
value 50 in 13. The correct address
calculation will be:

222

;
ICC
On:; 97 8

REL 1.0

AT CARD 000071
CARD
LV NAME
000040

PP NO. 5746-CB1

TYPE

VALUE

NB-S

+13
OOOD

02 NAME-FIELG

02 KOUNT
(HEX)

07D9EO

000047

07C9EE

000053

02 NO-OF-DEPENDENTS

07G9E2

000049

02 RECCRD-NO

0013

TYPE

VALUE

NB-S

+17
0011

02 NAME-FIELG

TESTRU!'
LCC
07D978

J"T CAFD 000071
LV NAME
CARD
000040

02 KOUNT
(HEX)

07G9BO

000047

07G9EE

000053

02 NO-OF-DEPENDENTS

07D9B2

000049

02 RECORD-NO

0017

TYPE

VALUE

NB-S

+21
0015

TESTRUN
LCC
07G978

AT CARD 000071
CARD
LV NAME
000040

02 KOUNT
(HEX)

07G9BO

000047

02 NAME-FIELD

07D9EE

000053

02 NO-OF-DEPENDENTS

07D9B2

000049

02 RECCRD-NO

0021

TYPE

VALUE

NB-S

+25
0019
Y

TESTRUN
LCC
07G978

AT CARD 000071
LV NAME
CARD
000040

02 KOUNT
(HEX)

07G9EO

000047

02 NAME-FIELD

07G9BE

000053

02 NO-OF-DEPENDENTS

07I:9E2

000049

02 RECORD-NO

0025

TYPE

VALUE

TESTRUN
LCC

07.52.05

10/02/73

AT CARD 000080
CARD
LV NAME.
000046

01 WORK-RECORD

07D9BO
07I:9EO
07D9B1
07r;9B2
07G9B6
07C9E7
07G9BA
07r;9EE
07G9BD

000047
000048
000049
000050
000051
000052
000053
000054

02
02
02
02
02
02
02
02

07C9C8

000057

02 B

(HEX)
NAME-FIELD
FILLER
RECORD-NO
FILLER
LOCATION
FILLER
NO-OF-DEPENDENTS
FII.LER

AN
AN
ND
AN
A
AN
AN
AN
NP-S
(HEX)

Figure 64.

C107FOFO FOF140D5 E8C340FO
A
*
0001

40404040 40404040

NYC

*1*2*3*
FlF2F3C4

Using the Symbolic Debugging Features to Debug the Program TESTRUN
(Part 9 of 12)

Symbolic Debugging Features

243

IBM DOS VS COBOL

REL 1. 0

PP NO. 5746-CBl

07.52.05

COBOL AEEND DIAGNOS1IC AIDS

IN1ERRUP~
PRCGRA~
LAS~

LAST PSW AD DR BEFORE ABEND D007E1AE

CODE 7

TESTRUN

CARD NUMBER/VERB NUMBER EXECUTED -- CARD

TES~RUN

NU~EER

000080/VERB NUMBER

01.} CD

FLOW TRACE
000066 000070 000066 000070 000066 000070 000066 000070 000076 000079

(;\

\!J

DATA DIVISION DUMP m' TES1RUN

1ASJ( GLOBAL TABLE
SAVE AREA

LOC

07CC78
07DC98
07DCB8
SwITCH
07DCCO
~ALLY
07DCC4
SCR~-SAVE
07DCC8
EN1RY-SAVE
07DCCC
SCR~-CORE-SIZE
07DC[;0
NSTD-REELS
07DCD4
SORT-RETURN
07DCD6
wORRING CELLS
07DCD8
07DCF8
07DD18
07DD38
07DD58
07DD78
07DD98
07DDB8
07DDD8
07DDF8
SORT-FILE-SIZE
07DE08
SCRT-MODE-SIZE
07DEOC
FG~-VN TBL
07DE10
TGT-VN TBL
07DE14
SOR~AB AD DR
07DE18
'.iN TBL LENGTH
07DE1C
SORTAB LENGTH
07DE1E
FRCGRAM-ID
07DE20
A (IN IT!)
07DE28
UPSI-SWITCHES
07DE2C
~GT-DBG TABLE
07DE34
CURRENT PRIORITY
07DE38
~RANSIENT AREA LENGTH
07DE39
FROCEDURE-BLCCK
07DE3C
UNUSED
07DE40
RESERVED
07DE44
VSAM SAVE AREA
07DE48
UNUSED
07DE4C
RESEJ:{VED
07DE511
CVERFLOW CELLS
(NONE>
EL CELLS
07DE6C
LTFADR CELLS
07DE78
(NONE)
FIB CELLS
TE~P STORAGE
07DE80
ELL CELLS
07DE88
'.iLC CELLS
(NONE)
(NONE)
SBL CELLS
(NONE)
INDEX CELLS
OTHER (SEE MEMORY MAP) 07DE8C
07DEAC

Figure 64.

244

VALUE
0000F233
0000001A
4007E1AE
3C10004B
00000000
00000000
0007DF38
00000000
0000
0000
0007DA60
FOF2F640
11011040110
--SAME-40404040
0000001A
0007D9AF
0007DEBO
0007FAII8
00000000
00000000
00000000
E2C1D4D7
D3C54040
0007D878
0000
0000
TESTRUN
0007D878
C9D3C2C4
00000228
00
689120
EOOOll780
F0325810
F0789101
100011710
F0329601
00000000

1B009101 00080168 8007E18E
0007[;1160 5007E29A 0007D978
0007DEBO

0007E1A8 4007EiAA 0007DA60 0007DBA8
0007DAEC 0007DBA8 0007E264 0007D878

0007DB40 0000001A 0007D1\60
D5E8C340 F0404040 40404040
110110110110 11011040110 40404040

5007E29A F16E9025 F21290BC 40E907FO
40404040 40404040 40404040 404011040
110110110110 40404040 404011040 40404040

1104011040
01000000
5007E29A
55EOF088
0007E0811
00000000

404040110 40404040
0007~070 0007F518
0007D978 0007DAD8
4780F030 18FE05EF
0007F518 4A50F060
07070607 07070707

40404040
0007D9AF
0007DBA8
18F498E4
4A20F060

40400000
0007E0811
0007E264
F0684BOO
183047FO

00000000
0000001A
0007D878
00024620
F036D200

0007E082
0000001A
1I007E08A
0007E082
50002000

[;6E2E8FO

00000000
F0549110 000002EO 00000100

000002A8 DIIC5E3C8

0007DAEC 0007DBA8 0007iJ978
0007D9E8 0007DA60
00000000 0000026C
00000000

0007D993 0007D9AF 0007EOAC 0007EOAC
000006F8

D7C5D540 OAOOOA68 000009D2 5C29FOC8

Using the Symbolic Debugging Features to Debug the Program TESTRUN
(Part 10 of 12)

10/02/73

IBM DOS VS COBOL

pp NO.

REL 1.0

07.52.05

5746-CB1

10/02/73

DA'IA DIVISION DUMP OF 'IESTRUN
Lec

CARD
000017

FD FILE-1

S'IANDARD SEQUEN'IIAL
PRE-DTF
DTFMT

07~9DO

07r9Ea
07DA08
07I:A28
07~A48

07DAEC
07I:AEC

000028

01 RECORD-1

000029

02 FIELD-A

000018

FD FILE-2

000036

01 RECORD-2

000037

02 FIELD-A

000039

01 FILLER

07D97A
07r::97B
071:;97C
07r;97D
07D97E
07r;97F
07D980
07r:981
071:;982
07D983
07~984

07D985
07D986
07~987

07D988
071::989
07D98A

Figure 64.

®
®

(HEX)

(HEX)
NB-S
AN
*AN

(SUBl)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

16
17

SEQU~NTIAL

00000000
OCOO0108
2407E1A2
0007DBA8
00000000

02 KCUNT
02 ALPHABE'I
02 ALPHA

01010014
00008200
10000000
0007DBA8
00000000

00000000
00070A20
00000000
00000014
00000000

ASSIGNED TO SYS008, CLOS:t.D
00000000
0007DA28
86BCF018
0007DBA3
00000000

6COOOOOO
0007E368
41EOE001
00640063
6COOOOOO

D807FOFO F1F740D5 E.8C340F1
Q*0017 NYC 1

STANDARD
PRE-D'IF
DTFMT

000040
000041
000042

00000000
OCOO0108
00000000
0007DB40
00000000

(HEX)

07CA60
07DA80
07r::AAO
07DACO

07r:978
07D990
07r:9A8
07D978
07r::97A

01010014
00009200
00000000
0007DB40
01010014

07~A48

071:;BA8
07:CBA8

VALUE

TYPE

LV NAME

00000000
0007DA98
00000001
00000014
00000000

00000000
1160E.2E8
58201044
00000000
00000000

E2FOFOFS
0107DADS
00000000
00008200

40400162
20000064
400802bS
OCOO0108

40404040 40404040

ASSIGNED 'IO SYS008, OPE.N INPUT
00000000
0007DAAO
86BCF018
00070COB
00000000

6COOOOOO
0007E368
41EOE001
00640063
00000000

00000000
llE8E2E8
58201044
00000000
00000000

E2FOFOF8
0207DC10
000802BO
E907FOFO

40400272
00000064
00080268
F2F640D5

C107FOFO FOF140D5 E8C340FO
A*OOOl NYC 0

40404040 40404040

001AC1C2 C3C4C5C6 C7C8C9D1
E6E7E8E9 001AFOF1 F2F3F4FO
F3F4FOF1 F2F3F4FO
+26
ABCDEFGHIJKLMNOPQRSTUVWXYZ

D2D3D4D5 D6D7D8D9 ~2E.3E4E5
F1F2F3F4 FOF1F2F3 F4FOF1F2

A
B
C
D
E
F
G
H

I
J
K
L
M
N

o
p
Q

Using the Symbolic Debugging Features to Debug the Program TESTRUN
(Part 11 of 12)

Symbolic Debugging Features

245

IBM DOS V$ COBOL

REL 1. 0

PP NO. 5746-CBl

07.52.05

DA'1A CIVISION DUMP OF 'IES'IRUN
LCC
07[;98B
07[;98C
07D98D
07[;98£
07[;98F
07[;990
07[;991
07[;992
07D993
07[;994
07[;996

CARD

LV NAME
18
19
20
21
22
23
24
25
26

000043
000044
000045

X
Y
Z

NB-S
liN
*lIN

® (SU~1)

01 WORK-RECORD

000047
000048
000049
000050
000051
000052
000053

02
02
02
02
02
02
02

+26
01234012340123401234012340

0
1
2
3
4
0
1
2
3
4
0
1
2
3
4
0
1
2
3
4
0
1
2
3
4
0

2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
000046

VALUE
S
'1
U
V

02 NUMER
02 DEPENDENTS
02 DEPEND

07C996
07D997
07[;998
07D999
07C99A
07[;99B
07[;99C
07[;99D
07[;99£
07[; 9 9F
07r:;9AO
07D9111
07[;9A2
07D9A3
07[;9A4
07[;9A5
07[;9A6
07r:.9A7
07[;9A8
07D9A9
07[;9AA
07D9AE
0n:9AC
07D911D
07C9AE
07[;9AF
07D9BO
07[;9BO
07D9B1
07C9B2
07r:.9B6
07[;9E7
07[;9BA
07r:;9EE

TYPE

(HEX)
AN
AN
ND
AN
A
AN
AN

NAME-FIELD
FILLER
RECORD-NO
FII.LER
LOCA'IION
FII.LER
NO-OF-DEPENDENTS

C107FOFO FOF140D5 EBC340FO
A
*
0001

40404040 40404040

NYC
0

DATA DIVISION DUMP OF TESTRUN
LCC
07r:;9BD
07[;9C8
07r:9C8
07D9C8

CARD

LV NAME

TYPE

000054

02 FILLER

000055

01 RECORDA

000056
000057

02 A
02 B

(HEX)
ND-O'I

~NP-S

VALUE

F1F2F3C4
+1234
*1*2*3*

END OF COBOL DIAGNOSTIC AIDS

Figure 64.

246

Using the Symbolic Debugging Features to Debug the Program TESTRUN
(Part 12 of 12)

10/02/73

PROGRru~

A programmer using the DOS/vS COBOL
Compiler and Library has several methods
available to him for testing and debugging
his programs. Use of the symbolic
debugging features is the easiest and most
efficient method for testing and debugging
and is described in detail in the chapter
·Symbolic Debugging Features." Using the
execution statistics feature is another
method for testing, debugging and
optimizing a program, and is described in
the chapter "Execution Statistics".
This chapter contains information useful
for testing and debugging programs run
without the symbolic debugging features.
It also contains information on linkage
editor and execution-time diagnostics as
well as a description of taking checkpoints
and restarting programs.

CHECKOUT

The date and time of compilation are
given in the header line of the
compilation listing.

The date and time of compilation are
punched into the object deck and will
be found beginning at relative
location XiEC· in the dump of the
object module.

By moving the special register
WHEN-COMPILED to an output record, the
user may flag his output to identify
it with a particular compilation.
WHEN-COMPILED is described more fully
in IBM DOS Full American National
Standard COBOL.

DEBUG LANGUAGE
SYNTAX-CHECKING COMPILATION
The compiler checks the source text for
syntax errors and then generates the
appropriate error messages. With the
syntax-checking feature, the programmer can
request a compilation either conditionally,
wit~ object code produced only if no
messages or just W- or C-Ievel messages are
generated, or unconditionally, with no
object code produced regardless of message
level.
Selected test cases run with the
syntax-checking feature have resulted in a
compilation-time saving of as much as 70%,
For a discussion of the syntax-checking
options, SYNTAX and CSYNTAX, see the
section "CBL Statement -- COBOL Option
Control Card."

The COBOL debugging language is designed
to assist the COBOL programmer in producing
an error-free program in the shortest
possible time. The following sections
discuss the use of the debug language and
other methods of program checkout.
The three debug language statements are
TRACE, EXHIBIT, and ON. Anyone of these
statements can be used as often as
necessary. They can be interspersed
throughout a CCBOL source program, or they
can be contained in a packet in the input
stream to the compiler.
Program checkout may not be desired
after testing is completed. A debug packet
can be removed after testing to eliminate
the extra object program coding generated
for the debug statements.
The output produced by the TRACE and
EXHIBIT statements is listed on the system
logical output device (SYSLST).

IDENTIFICATION OF PROGRAM VERSIONS
The following discussions describe
methods of using the debug language.
One problem a programmer may have during
checkout is associating a particular
compilation listing with the object deck
from that compilation and the output and/or
dump from a particular run. To aid in
this, the following facilities can be used:
1.

Specify a DATE-COMPILED paragraph as
part of the Environment Division.
This is replaced by the actual date of
compilation on the source listing
(OPTION LIST).

FLOW OF CONTROL
The READY TRACE statement causes the
compiler=generated card numbers for each
section-name and paragraph-name to be
displayed. These card numbers are listed
on SYSLST at execution time when control
passes to these sections and paragraphs.
Program Checkout

247

Hence, the output of the READY TRACE
statement appears as a list of card
numbers.
If VERB is specified, the actual
paragraph-names and names of the verbs will
be listed.
To reduce the length of the list and the
time taken to generate it, a trace can be
stopped with a RESET TRACE statement. The
READY TRACE/RESET TRACE combination is
helpful in examining a particular area of
the program where the flow of control is
difficult to determine, e.g., code consists
of a series of PERFORM statements or nested
conditional statements. The READY TRACE
statement can be coded so that the trace
begins before control passes to that area.
The RESET TRACE statement can be coded so
that the trace stops when the program has
passed beyond the area.
Use of the ON statement with the TRACE
statement allows conditional control of the
tracing. When the COBOL compiler
encounters an ON statement, it creates a
counter which is incremented during
execution, whenever control passes through
that ON statement. For example, if an
error occurs when a specific record is
processed, the ON statement can be used to
isolate the problem record. The statement
should be placed where control passes
through it only once for each record that
is read. When the contents of the counter
equal the number of the record (as
specified in the ON statement), a trace can
be taken on that record. The following
example shows a method in which the 200th
record could be selected for a TRACE
statement.
Col.
1

Note:
If an error occurs during
compilation of an ON statement, the
diagnostic message may refer to the
previous statement number.

DISPLAYING DATA VALUES DURING EXECUTION
A programmer can display the value of a
data item during program execution by using
the EXHIBIT statement. The EXHIBIT
statement has three options:
1.

EXHIBIT NAMED -- Displays the names
and values of the data-nawes listed in
the statement.

EXHIBIT CHANGED -- Displays the value
of the data-names listed in the
statement only if the value has
changed since the last execution of
the statement.

EXHIBIT CHANGED NAMED -- Displays the
names and the values of the data-na~es
only if the values have changed since
the last execution of the statement.

Data values can be used to check the
accuracy of the program. For example,
using EXHIBIT NAMED, the prograrrmer can
display specified fields from records,
compute the calculations himself, and
compare his calculations with the output
from his program. The coding for a payroll
problem might be:
Col.
1

Area A

GROSS-PAY-CALC.
COMPUTE GROSS-PAY
RATE-PER-HOUR * (HRSWKD
+ 1.5 * OVERTIMEHRS).
NET-PAY-CALC.

RD-REC.

DEBUG

RD-REC
PARA-NM-l.

ON 200 READY TRACE.
ON 201 RESET TRACE.

If the TRACE statement were used without
the ON statement, every record would be
traced.
An example of a common program error is
failing to break a loop or unintentionally
creating a loop in the program. If many
iterations of the loop are required before
it can be determined that a program error
exists, the ON statement can be used to
initiate a trace after the expected number
of iterations has been completed.
248

Area A

DEBUG

NE?-PAY-CALC
SAMPLE-l. ON 10 AND
EVERY 10 EXHIBIT NAMED
RATE-PER-HOUR, HRSWKD,
OVERTIMEHRS, GROSS-PAY.

This coding will cause the values of the
four fields to be listed for every tenth
data record before net pay calculations are
made. The output could appear as:
RATE-PER-HOUR = 4.00 HRSWKD = 40.0
OVERTIMEHRS = 0.0 GROSS-PAY = 160.00
RATE-PER-HOUR = 4.10 HRSWKD = 40.0
OVERTIMEHRS = 1.5 GROSS-PAY = 173.23

RATE-PER-HOUR = 3.35 HRSWKD = 40.0
OVERTIMEHRS = 0.0 GROSS-PAY = 134.00

Note: Decimal points are included in this
example for clarity, but actual printouts
depend on the data description in the
program.

Program Checkout

248.1

The preceding was an example of checking
at regular. intervals (every tenth record) •
A check of any unusual conditfons can be
made by using various combinations of COBOL
statements in the debug packet. For
example:

IREAD INPUT I
I DATA FOR 1 < - - B
CITY
I
I
r

IF OVERTIMEHRS GREATER THAN 2.0
EXHIBIT HAftED PAYRCDHRS •••

I
I
V

In connection with the previous example,
this statement could cause the entire pay
record to be displayed whenever an unusual
condition (overtime exceeding two hours) is
encountered.

CALCULATE
RATE FOR
CITY

1
i
V

The EXHIBIT statement with the CHANGED
option also can be used to monitor
conditions that do not occur at regular
intervals. The values of data-names are
listed only if the value has changed since
the last execution of the statement. For
example, suppose the program calculates
postage rates to various cities. The flow
of the program might be:

EXHIBIT
CHANGED
I
I
V

<§?

CITY

:?B

YES

I
I
I
V

STATE

= 01

CITY

03 BUS

CITY

01 RAIL

10 BUS

= 06 AIR = 15
RAIL = 30 BUS = 25

STATE = 02 CITY

01 TRUCK

CITY

20 AIR

Figure 65.

02 TRUCK

TRUCK

14 TRUCK

28 AIR

12 AIR

= 30

Sample output of EXHIBIT Statement With the CHANGED NAMED Option

Program Checkout

249

The EXHIBIT statement with the CHANGED
option in the program might be:

r--------~

START
EXHIBIT CHANGED STATE CITY RATE
L ____~--~

The output from the EXHIBIT statement
with the CHANGED option could appear as:
01

02
03

15
10

04
01

20
15

02
03
04
01

,
I
V
r--------~

I
I
I

DEBUG
PACKET
FOR A

The first column contains the code for a
state, the second column contains the code
for a city, and the third column contains
the code for the postage rate. The value
of a data-name is listed only if it has
changed since the previous execution. For
example, since the postage rate to city 02
and city 03 in state 01 are the same, the
rate is not printed for city 03.
The EXHIBIT statement with the CHANGED
NAftED option lists the data-name if the
value has changed. For example, the
program might calculate the cost of various
methods of shipping to different cities.
After the calculations are made, the
following statement could appear in the
program:

I
V
STOP
RUN

EXHIBIT CHANGED NAMED STATE CITY RAIL
BUS TRUCK AIR
The output from this statement could appear
as shown in Figure 65. Note that a
data-name and its value are listed only if
the value has changed since the previous
execution.

In this program, A creates data, B
processes it, and C prints it. The debug
packet for A simulates test data. It is
first in the program to be executed. In
the packet, the last statement is GO TO B,
which permits A to be bypassed. After B is
executed with the test data, control passes
to the debug packet for C, which contains a
GO TO statement that transfers control to
the end of the program, bypassing C.

TESTING A PROGRAM SELECTIVELY
TESTING CHANGES AND ADDITIONS TO PROGRAMS
A debug packet allows the programmer to
select a portion of the program for
testing. The packet can include test data
and can specify operations the programmer
wants to be performed. When the testing is
completed, the packet can be removed. The
flow of control can be selectively altered
by the inclusion of debug packets, as
illustrated in the following example of
selective testing of B:
250

If a program runs correctly, and changes
or additions might improve its efficiency,
a debug packet can be used to test changes
without modifying the original source
program.
If the changes to be incorporated are in ~
the middle of a paragraph, the entire

paragraph with the changes included must be
written in the debug packet. The last
statement in the packet should be a GO TO
statement that transfers control to the
next procedure to be executed.
There are usually several ways to
perform an operation. Alternative methods
can be tested by putting them in debug
packets.
The source program library facility can
be used for program checkout by placing a
source program in a library (see the
chapter "Librarian Functions"). Changes or
additions to the program can be tested by
using the BASIS card and any number of
INSERT and DELETE cards. Such changes or
additions remain in effect only for the
duration of the run.
A debug packet can also be used in
conjunction with the BASIS card to debug a
program or to test deletions or additions
to it. The debug packet is inserted in the
input stream immediately following the
BASIS card and any INSERT or DELETE cards.

If a serious error occurs during
execution of the problem program, the job
is abnormally terminated; any remaining
steps are bypassed; and a program phase
dump is generated. The programmer can use
the dump for program checkout.
(However,
any pending transfers to an external device
may not be-completed. For example, if a
READY TRACE statement is in effect when the
job is abnormally terminated, the last card
number may not appear on the external
device.)
In cases where a serious error
occurs in other than the problem program
(for example, Supervisor), a dump is not
produced. Note that program phase dumps
can be suppressed if the NODUMP option
of the OPTION control statement has been
specified for the job, or if NO DUMP was
specified at system generation time and
is not overridden by the DUMP option for
the current job.

HOW TO USE A DUMP
When a job is abnormally terminated due
to a serious error in the problem program,
a message is written on SYSLST which
indicates the:
1.

Type of interrupt (for example,
program check)

Hexadecimal address of the instruction
that caused the interrupt

Condition code

Reason for the interrupt (for example,
data exception)

The instruction address can be compared
to the Procedure Division map. The
contents of LIST! provide a relative
address for each statement. The load
address of the module (which can be
obtained from the map of virtual storage
generated by the Linkage Editor) must be
subtracted from the instruction address to
obtain the relative instruction address as
shown in the Procedure Division map. The
PMAP=nnnnnn CBL option can be used to
relocate LISTX addresses so that this
calculation need not be done. If the
interrupt occurred within the COBOL
program, the programmer can use the error
address and LISTX to locate the specific
statement in the program which caused a
dump to be taken. Examination of the
statement and the fields associated with it
may produce information as to the specific
nature of the error.
Figure 66 is a sample dump which was
caused by a data exception. Invalid data
(i.e., data which did not correspond to its
usage) was placed in the numeric field B as
a result of redefinition. The following
discussion illustrates the method of
finding the specific statement in the
program which caused the dump. Letters
identifying the text correspond to letters
in the program listing.
The program interrupt occurred at HEX
LOCATION 07DFDC. This is indicated in
the SYSLST message printed just before
the dump.
The linkage editor map indicates that
the program was loaded into address
7D878. This is determined .by
examining the load point of the
control section TESTRUN. TESTRUN is
the name assigned to the program
module by the source coding:
PROGRAM-ID.

TESTRUN.

The specific instruction which caused
the dump is located by subtracting the
load address from the interrupt
address (that is, subtracting 7D878
from 7DFDC). The result, 764, is the
relative interrupt address and can be
found in the object code listing. In
this case the instruction in question
is an AP (add decimal).
Program Checkout

251

The left-hand column of the object
code listing gives the compilergenerated card number associated with
the instruction. It is card 66. As
seen in the source listing, card 66
contains the COMPOTE statement.

COBOL subprogram can acquire invalid
information from the main program,
e.g., a CALL statement using a
procedure-name and an ENTRY statement
using a data-name.
10.

Additional details about reading a dump
are found in the chapter "Interpreting
Output."

The compiler does not generate a test
to check the sign position for a val~d
configuration before the item is used
as an operand. The programmer can
test for valid data by means of the
numeric class test and, by using the
TRANSFORM statement, convert it to
valid data under certain conditions.

ERRORS THAT CAN CAUSE A DUMP
A dump can be caused by pne of many
errors. Several of these errors may occur
at the COBOL language level while others
can occur at the job control level.

For example, if the units position of
a numeric data item described as OSAGE
IS DISPLAY contained a blank, the
blank could be transformed to a zero,
thus forcing a valid sign.

The following are examples of COBOL
language errors that can cause a dump:
1.

A GO TO statement with no
procedure-name following it may have
been improperly initialized with an
ALTER statement. The execution of
this statement will cause an invalid
branch to be taken and results will be
unpredictable.
ftoves of or arithmetic calculations
using numeric fields that have not
been properly initialized.
For example, neglecting to initialize
the object of an OCCURS clause with
the DEPENDING ON option, or
referencing data fields prior to the
first READ statement may cause a
program interrupt and a dump.

3.
4.
5.

Invalid data placed in a numeric field
as a result of redefinition.
Input/output errors that are
nonrecoverable.

An input file contains invalid data
such as a blank numeric field or data
incorrectly specified by its data
description.

11.

Division by zero without an ON SIZE
ERROR clause will cause a data
exception.

LOCATING A DTF
One or more DTF's are generated by the
compiler for each file opened in the COBOL
program.
All information about that file
is found within the DTF or in the fields
preceding the DTF. See the chapter
"Detailed Processing Capabilities" for the
type of information available and its
location.
A particular DTF may be located in an
execution-time dump as follows:
1.

Items with subscripts whose values
exceed the defined maximum value can
destroy machine instructions when
moved.

Determine the order of the DTF address
cells in the TGT from the DTF numbers
shown for each file-name in the
glossary.
Note: Since the order is the same as
the FD's in the Data Division, the
order can be determined from the
source program if the SYM option was
not used (i.e., no glossary was
printed) •

Attempting to execute an invalid
operation code through a system or
program error.

Generating an invalid address for an
area that has address protection.

Subprogram linkage declarations that
are not defined exactly as they are
stated in the calling program.

Find the relative starting address of
the block of DTF cells from the TGT
listing in the Memory Map.

Calculate the absolute starting
address of the block by adding the
hexadecimal relocation factor for the
beginning of the object module as
given in the linkage editor MAP.

252

Data or instructions can be modified
by entering a sUbprogram and
manipulating data incorrectly. A

Allowing one fullword per DTF cell,
count off the cells from the starting
address found in step 3, using the
order determined in step 1 to locate
the desired DTF cell.

Locate data-name B in the glossary.
It appears under the column headed
SOURCE-NAME. Source-name B has been
assigned to base locator 3 (i.e.,
BL =3> with a displacement of 050,.
The sum of the value of base locator 3
and the displacement value 50 is the
address of data-name B.

If more than one DTF is generated for
a file, the above procedure should be
followed using the PGT and the SUBDTP
cells rather than the TGT and the
DTPADR cells. The order of multiple
DTF's in storage is dependent on the
OPEN option as follows:
a.

INPUT

OUTPUT

I-O or INPUT REVERSED

The following discussion illustrates the
method of finding the DTP's in the sample
program in Figure 66. Letters identifying
the text refer to letters in the program
listing.

the programmer should locate the contents
of field B at the time of the interrupt.
This can be done as follows:

The DTF for PILE-1 precedes the DTF
for PILE-2.
DTFADR CELLS begin at relative
location 600.
Since the relocation factor is 7D878,
the DTFADR CELLS begin at location
7DE78 in the dump.
The DTF for FILE-1 begins at location
7D9E8, and the DTF for FILE-2 begins
at location 7DA60.

LOCATING DATA
The location assigned to a given
data-name may similarly be found by using
the BL number and displacement given for
that entry in the glossary, and then
locating the appropriate one fullword BL
cell in the TGT. The hexadecimal sum of
the glossary displacement and the contents
of the cell should give the relative
address of the desired area. This can then
be converted to an absolute address as
described above.
Since the problem program in Figure 66
interrupted because of a data exception,

The Register Assignment table lists
the registers assigned to each base
locator. Register 6 has been assigned
to BL =3.
The contents of the 16 general
registers at the time of the interrupt
are displayed at the beginning of the
dump. Register 6 contains the address
0007D978.

The location of data-name B can now be
determined by adding the contents of
register 6 and the displacement value
50. The result, 7D9C8, is the address
of the leftmost byte of the 4-byte
field B.

Note: Field B contains P1F2F3C4.
This is external decimal
representation and does not correspond
to the USAGE COMPUTATIONAL-3 defined
in the source listing.
The location assigned to a given
data-name may also be found by using
the BL CELLS pointer in the TGT Memory
Map. Figure 64 indicates that the BL
cells begin at location 7DE6C (add 5F4
to the load point address, 7D878, of
the object module>. The first four
bytes are the first BL cell, the
second four bytes are the second BL
cell, etc. Note that the third BL
cell contains the value 7D978. This
is the same value as that contained in
register 6.

Note: Some program errors may destroy
the contents of the general registers
or the BL cells.
In such cases,
alternate methods of locating the
DTF's are useful.

Program Checkout

253

// JOB DATACHlt
OPTION NODECt;LINK,LIST,LISTX,SYM,ERRS
// EXEC FCOEeL

IBM DOS VS COBOL

CEL QUOTE, SEQ
C0001
(0002
00003
00004
C0005
(0006
C0010
e0011
C0012
C0013
C0014
00015
C0016
00017
C0018
00019
00020
00021
00022
e0023
C0024
00025
e0026
00027
(J0028
C0029
00030
0003l
00032
e0033
0003"
00035

Figure 66.

254

REL 1. 0

PP NO. 5746-CE1

07.35.08

IDENTIFICATION DIVISION.
PROGRAM-ID. TESTRUN.
AUTHOR.
PROGRAMMER NAME.
INSTALLATION.
NEW YORK PROGRAMMING CENTER.
DATE-WRITTEN. SEPTEMBER 25,1973
DATE-COMPILED. 10/02/73
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
IBM-370.
SOURCE-COMPUTER.
OBJECT-COMPUTER. IBM-310.
INPUT-CUTPUT SECTION.
FILE-CONTROL.
SELECT FILE-l ASSIGN TO SYS008-UT-2400-S.
SELECT FILE-2 ASSIGN TO SYS008-UT-2400-S.
DATA DIVISION.
FILE SECTION.
FD FILE-1
LABEL RECORDS ARE OMITTED
BLOCK CONTAINS 5 RECORDS
RECCRDING MODE IS F
RECORD CONTAINS 20 CHARACTERS
DATA RECORD IS RECORD-l.
01 RECORD-l.
05 FIELD-A PIC X(20).
FD FILE-2
\V
LABEL RECORDS ARE OMITTED
BLOCK CONTAINS 5 RECORDS
RECORD CONTAINS 20 CHARACTERS
RECORDING MODE IS F
DATA RECORD IS RECORD-2.
01 RECCRD-2.
05 -FIELD-A PIC·X(ZOr.

f£\

Sample Dump Resulting from Abnormal Termination (Part 1 of 6)

10/02/73

IBM DOS VS COBOL
C0036
00037
00038
C0039
C0040
C0041
C0042
C0043
00044
00045
C0046
00047
00048
00049
C0050
C0051
00052
00053

COO 54
COC55
C0056
C0057
C0058
C0059
C0060
C0061
00062
00C63
00C64
C0065
00066
00067
00068
C0069
C0070
C0071
C0072
00073
C0074
C0075
00076
00077
00078
00079
C0080
00081

Figure 66.

REL 1.0

PP NO. 5746...cB1

07.35.08

10/02/73

WORKING-STORAGE SECTION.
01 FILLER.
02 KOUNT PIC S99 COMP SYNC.
02 ALPHABET PIC X(26) VALUE IS "ABCDEFGHIJKLMNOPQRSTUVWXYZ".
02 ALPHA REDEFINES ALPHABET PIC X OCCURS 26 TIMES.
02 NUMBR PIC S99 COMP SYNC.
02 DEPENDENTS PIC X(26) VALUE "01234012340123401234012340·.
02 DEPEND REDEFINES DEPENDENTS PIC X OCCURS 26 TIMES.
01 WORK-RECORD.
05 r;AME-FIELD PIC X.
05 FILLER PIC X.
05 RECORD-NO PIC 9999.
05 FILLER PIC X VALUE IS SPACE.
05 LOCATION PIC AAA VALUE IS nNYC".
05 FILLER PIC X VALUE IS SPACE.
05 NO-OF-DEPENDENTS PIC XX.
05 FILLER PIC X(7) VALUE IS SPACES.
01 RECCRDA.
02 A PICTURE S9(4) VALUE 1234.
02 B REDEFINES A PICTURE S9(7) COMPUTATIONAL-3.
PROCEDURE DIVISION.
BEGIN. READY 'IP~CE.
NOTE THAT THE FOLLOWING OPENS THE OUTPUT FILE TO BE CREATED
AND INITIALIZES THE COUNTERS.
STEP-l. OPEN OUTPUT FILE-l. MOVE ZERO TO KOUNT, NUMBR.
NOTE THAT THE FOLLOWING CREATES INTERNALLY 'IHE RECORDS TO Bl:.
CONTAINED IN THE FILE, WRITES THEM ON TAPE, AND DISPLAYS
THEM ON THE CONSOLE.
STEP-2. ADD 1 TO KOUNT, NUMBR. MOVE ALPhA (KOUNT) TO
NAME-FIELD.
(;\
COMPUTE B = B + 1. ~
MOVE DEPEND (KOUNT) TO NO-OF-DEPENDENTS.
MOVE NUMBR TO RECORD-NO.
STEP-3. DISPLAY WORK-RECORD UPON CONSOLE. wRITE RECORD-l FROM
WORK-RECORD.
STEP-4. PERFORM STEP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 26.
NOTE THAT THE FOLLOWING CLOSES THE OUTPUT FILE AND REOPENS
IT AS INPUT.
STEP-5. CLOSE FILE-l. OPEN INPUT FILE-2.
NOTE THAT THE FOLLOWING READS BACK THE FILE AND SINGLES
OUT EMPLOYEES WITH NO DEPENDENTS.
STEP-6. READ FILE-2 RECORD INTO WORK-RECORD AT END GO TO STEP-8.
STEP-7. IF NO-OF-DEPENDENTS IS EQUAL TO "0" MOVE ·Z" TO
NO-OF-DEPENDENTS. EXHIBIT NAMED WORK-RECORD. GO TO ST'EP-6.
STEP-8. CLOSE FILE-2.
STOP RUN.

sample Dump Resulting from Abnormal Termination (Part 2 of 6)

Program Checkout

255

INTRNL NAME

LVL SOURCE NAME

DNM=1-148
DNM=1-179
DNM=1-200
DNM=1-217
DNM=1-248
DNM=1-269
DNM=1-289
DNM=1-308
DNM=1-323
DNM=1-341
DNM=1-359
DNM=1-374
DNM=1-394
DNM=1-410
DNM=1-434
DNM=1-454
DNM=1-473
DNM=1-492
DNM=2-000
DNM=2-018
DNM=2-037
DNM=2-063
DNM=2-082
DNM=2-102
DNI-J=2-113

FD
01
02
FD
01
02
01
02
02
02
02
02
02
01
02
02
02
02
02
02
02
02
01
02
02

BASE

FILE-l
RECORD-l
FIELD-A
FILE-2
RECORD-2
FIELD-A
FILLER
KOUNT
ALPHABET
ALPHA
NUMBR
DEPENDENTS
DEPEND
WORK-RECORD
NAME-FIELD
FILLER
RECORD-NO
FILLhR
LOCATION
FILLER
NO-OF-DEPENDENTS
FILLER
RECORDA
A
B

DTF=Ol
BL=l
BL=l
DTF=02
BL=2
BL=2
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3

-0

07.35.08

PP NO. 5746-CB1

REL 1.0

IBM DOS VS COBOL

DISPL

000
000
000
000
000
000
002
002
01C
OlE
OlE
038
038
039
03A
03E
03F
042
043
045
050
050
050

INTRNL NAME
DNM=1-l48
DNM=1-179
DNM=1-200
DNM=1-2l7
DNM=1-248
DNM=1-269
DNM=1-289
DNM=1-308
DNM=1-323
DNM=l-34l
DNM=l-359
DNM=1-374
DNM=l-394
DNM=1-4l0
DNM=l-434
DNM=1-454
DNM=1-473
DNM=l-492
DNM=2-000
DNM=2-0l8
DNM=2-037
DNM=2-063
DNloti=2-082
DNM=2-l02
DNM=2-113

DEFINI'IION

DS OCL20
DS 20C
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS
DS

OCL20
20C
OCL56
lH
26c
lC
1H
26C
lC
OCL20
lC
1c
4C
1C
3C
lc
2c
7C
OCL4
4C
4P

USAGE
D'IFMT
GROUP
DISP
DT'FI-iT
GROUP
DISP
GROUP
COi'iP
DISP
DISP
CONP
DISP
DISF
GROUP
DISP
DISP
DISP-NM
DISP
DISI'
DISP
DISI'
DISP
GROUP
DISP-Ni1
cOMP-3

10/02/73
R

XSA-CELLS

PARAM CELLS
RPTSAV AREA
CHECKPT CTR
IOPTR CELLS

Figure 66.

256

00400

SAVE AREA
SWITCH
TALLY
SORT SAVE
ENTRY-SAVE
SORT ceRE SIZE
NSTD-REELS
SORT RET
WORKING CELLS
SORT FILE SIZE
SORT MODE SIZE
PGT-VN TBL
TGT-VN TEL
SORTAB ADDRESS
LENGTH OF VN TBL
LNGTH OF SORTAB
PGM ID
ACINITl}
UPSI SWITCHES
DEBUG TABLE PTR
CURRENT PRIORITY
TA LENGTH
PROCEDURE BLOCKl PTR
UNUSED
RESERVED
VSAM SAVE AREA ADDRESS
UNUSED
RESERVED
OVERFLOW CELLS ( ; \
BL CELLS ~
DTFADR CELLS
FIB CELLS
TEMP STORAGE
TEMP STORAGE-2
TEMP STORAGE-3
TEMP STORAGE-4
BLL CELLS
VLC CELLS
SBL CELLS
INDEX CELLS
SUBADR CELLS
ONCTL CELLS
PFMC'IL CELLS
PFMSAV CELLS
VN CELLS
SAVE AREA =2
XSASw CELLS

MEMORY MAP
TGT

00400
00448
0044C
00450
00454
00458
0045C
0045E
00460
00590
00594
00598
0059C
005AO
005A4
005A6
005A8
005130
005B4
005BC
005CO
005Cl
005C4
005C8
005ec
005DO
005D4
005DC
005F4
005F4.
f7\F
00600 ~
00608
00608
00610
00610
00610
00610
00614
00614
00614
00614
0061C
0061C
0061c
00620
00624
00624
00624
00624
00628
00628
00628

Sample Dump Resulting from Abnormal Termination (Part 3 of 6)

IBM DOS VS COBOL

PP NO. 5746-CBl

P.EL LO

07.35.08

10/02/73

BL =3
BL =1
BL =2

--®

64
00070S
00070C
000710
000714
00071A
00071E
0007n
000126
00072A
00072E
000732
00073S
00073C
000740

4S
4A
4E
D7
94
4F
40
4S
4A
4E
D7
94
4F
40

30
30
30
05
OF
30
30
30
30
30
05
OF
30
30

C 03A

000744
000748
00074C
000750
000752
000756
00075A
00075E

41
4S
4C
1A
5B
50
58
D2

40
20
20
42
40
40
EO
00

000764

FA 30 6 050 C 03C

6
D
D
D
D
6
C
6
D
D
D
D
6

000
20S
20S D 20S
20E
20S
000
03A
01C
20S
20S D 20S
20E
20S
01C

LH
AH
CVD
XC
NI
CVB
STH
LH
AH
CVD
XC
NI
CVB
STH

3,03A(O,12)
3,000(0,6)
3,20S(O,13)
20S(6,13),20S(13)
20E(13),X'OF'
3,20S(O,13)
3,000(0,6)
3,03A(O,12)
3,OlC(O,6)
3,20S(O,13)
20S(6,13),20S(13)
20E(13),X'OF'
3,20S(O,13)
3,OlC(O,6)

LIT+2
DNM=1-308
TS=Ol
TS=Ol
TS=01+6
TS=Ol
DNM=1-30S
LIT+2
DM'l=1-359
TS=Ol
TS=Ol
TS=01+6
TS=Ol
DNM=1-359

oLi,002(O,6)
2,000(0,6)
2,03A(O,12)
4,2
4,03S(O,12)
4,214(0,13)
14,214(0,13)
038 (1,6) ,000 (14)

DNM=1-341
DNM=1-308
LIT+2
LIT+O
SSS=l
SBS=l
DNM=1-434

DNM=1-341

050(4,6),03C(l,12)

DNM=2-113

LIT+4

TS=Ol

64
6 002
6 000
C 03A
C
D
D
6

Lri
MH
AR
S
ST
L
MVC

038
214
214
038 E 000

66
67

®--AP

// EXEC LNKEDT

LOADED

REL-FR

TESTRUN

07D878

IJFFBZZN
IJFFZZZN
IJFFBZZZ
IJFFZZZZ

07E278
07E278
07E278
07E278

07E278

CSECT
ENTRY

ILBDSAEO
ILBDSAE1

07F128
07F170

07F128

CSECT

ILBDMNSO

07F120

CSECT
ENTRY

ILBDDSPO
ILBDDSP1

07E628
07EA28

07E628

CSECT

ILBDIMLO

07FOCS

07FOC8

CSECT
ENTRY
ENTRY
ENTRY
ENTRY
ENTRY
ENTRY
ENTRY
ENTRY

ILBDDSSO
ILBDDSS1
ILBDDSS2
ILBDDSS3
ILBDDSS4
ILBDDSS5
ILBDDSS6
ILBDDSS7
ILBDDSSS

07EDAO
07FOOO
07EFF8
07FOB8
07EDC6
07£E72
07EED2
07EE9C
07EDF6

01EDAO

CSECT
ENTRY
ENTRY

IJJCPDV
IJJCPDVl
IJJCPDV2

07EB58
07EB58
07EB58

07EB58

WXTRN
WXTRN

STXITPSW
I LBDDBG 2

PHASE

XFR-AD

LOCORE

HICORE

DSK-AD

ESD TYPE

LABEL

PdASE***

07D878

07F2AF

05F OF 4

CSECT
CSECT
* ENTRY
ENTRY
ENTRY

•

• UNREFERENCED SYMBOLS

RELOCATAELE

-®

002 UNRESOLVED ADDRESS CONStANTS

I I ASSGN SYS009,X'492'

// EXEC

Figure 66.

Sample Dump Resulting from Abnormal Termination (Part 4 of 6)

Program Checkout

257

OS03I PROGRAN CHECK INTERRUPTION - HEX LOCATION 07DFDc - cONDITION ceDE 2 - DATA £XC£FTION
CSCOI JOB DATACHK CMlCELEr:;

DATACHK
GR O-F
FP REG
CR O-F
COMREG

ceoooo
000020
000040
COO060
COO080
OOOOAO
COOOCO
000360
C00380
C003AO
C003CO
C003EO
000400
000420
000440
000460
000480
0004AO
C004CO
0004EO
000500
000520
000540
000560
000580
0005AO
C005eO
0005EO
000600
C00620
000640
000660

00000001
0007D878
00000000
FFFFFFFF
00000000

00000001
00070878
00000000
FFFFFFFF
00000000

0007D97A
0007DEAO
00000000
00000000
00000000

5007E22C
0007DC78
00000000
00000000
00000000

0007D978
0007D97A
00000000
00000000
C4000000

0007DB40
0007E628
00000000
00000000
00000200

00000000
07000000
00000E68
040COOOO
00000400
00000000
00000000
F1F061F0
0011D7FF
38983D4A
3EFOOOOO
00000000
0000528C
OOOOFOOO
40800000
00000000
00009812
00081018
00000000
00005388
OOOOCOAO
010DOOOO
00080700
0000318C
00000000
00830083
00830083
06B006BO
00B006BO
06604590
06B041BB
42BOA001

00000000
04000000
00000E58
OOOCOOOO
00020007
00000000

00000000
000074DA
00000000
0000980C
00020001
000002CO

00000000
00000000
EFFCC798
04080000
1207F003
00000000

00000360
00000000
012A88EA
0000C09E.
00000000
00000000

00000000
070C2000
040COOOO
040COOOO
00000000
OOOOOOOE

00000000
000OO71E
00OOO9BE
000008F8
00000000
00000000

FOOOFOOO
0007F2AF
374C3750
372CC010
00000448
063E05FA
0014002C
00008350
00000000
00000544
00000000
00000005
00000000
0000A1E8'
00000360
00000000
00000008
00830083

00000000
00000010
375438F1
00000010
COC00340
00003A40
00030000
00005100
000030DO
00000000
00000000
03C10401
0001D1FF
00000000
00000000
00000000
00020406
00830083

00000000
0017D7FF
FOFOF2F7
000070EC
4040404("
00001F42
000{)5F78
000051B4
000004FO
0000BC88
00000000
OOOODDOO
FF010114
OOOAOOOO
8000150E
04FC0552
080AOCOl::
00830083

00000000
F97F5CD3
F3F2F7F5
00000000
40404000
00004058
00000000
0000520C
000070F5
00007F50
000031A6
OOOOCOFO
015502A0
00001000
900015CO
00000000
00183048
00830083

C4C1E3C1
A8A07CDO
00003544
000030DC
40404040
00004F5E
000072F5
00100010
0OO03C5A
000032FC
00000000
0000D5FO
FFOOO045
00002000
400053C8
00000000
607890A8
00830083

C3C8D240
00A63891
00000000
34440000
40404000
00007308
00005204
00000000
00000000
00003314
00000000
00005378
0000C6EO
00003000
00004F5E
00000000
00000000
00830083

00000083
06E006BO
06B006BO
066006BO
06A85890
960CAOOF

83838300
4EE0056A
06B006BO
06B006BO
041441FO
07FF960C

80020000
068006BO
41EBOOlF
06B006BO
92161211
AOOF4400

00007888
06B006BO
41B80010
06B006BO
41100660

00000000
068006BO
18F69503
'06B041BB
41F09314
920003CF

0000BBA5
06B00680
04454110
001F06BO
94633006
928305C9

Figure 66.

258

0007DE78 0007DF80
0007DBA8 0007E1FC
00000000 00000000
004000FF 0100DOOO
00000000 00000000
BG AODR IS 000360
00000000
000076CE
08000000
0000097A
00000000
00000000
--SAME-F261F7F3
0007F2AF
3D4BOOOO
363C36BC
036010EO
00002742
0300505E
0000070E
000065F8
000088C8
00200000
00000000
00000000
00003868
000016e4
00000000
00000EE8
00830083

\~)

--SA~E--

00830083
06B006BO
06B006BO
06D447FO
001B4570
58B00514

B52~011F

Sample Dump Resulting from Abnormal Termination (Part 5 of 6)

DATACHK
07C800
07D820
07C840
07[;860
07C880
07C8AO
On8CO

07I:8EO
07[;900
07I:920
07r::940
07I:960
07[;980
07I:9A0

07DA40.
07tA60'
07DA80
07I:AAO
07CACO
07DBOO
07CB20
07DB40
07CE60
07tB80
07DEAO
07CBCO
07CEEO
07DCOO
07CC20
OnC40
07CC60
07tC80
07CCAO
oncco
07DCEO
07tDOO
07CD60
07W80
07CtAO
07r:DCO
07CDEO
07DEOO
07I:E20
07r::E40
o tE60
07DE80
-o7I:EAO
OnECO
07CEEO
onFOO
07CF20
07DF40
07CF60
07DF80
07CFAO
07DFCO
onFEO
07EOOO
07E020
07E040
07E060
07E080
07EOAO
07EOCO
onOEO

07E100
07E120
07E140

D7C8C1E2
0007CC78
5007E22C
00000000
47FOF082
0011D7FF
00000000
0007DBA8
58EOCOOO
90ECDOOC
0007DEAO
00000000
C7C8C9D1
FOF1F2F3
4 4 4 4
6COOOOOO
E2FOFOF8
0107[;AD8

C55C5C5C
0007D97A
0007D978
00000000
0007D878
0007F8c8
00000000
0007E1FC
58DOFOCA
185D989F
0007DC78
FlF061FO
D2D3D4D5
F4FOF1F2
0 0000
0000000
40400162
20000064

0007DFE2
0007DE78
0007DBA8
00000000
0011D7FF
00000000
00000000
0007D878
4770FOA2
D0480719
0007E1E2
FOF74BF3
0000000
000001
04000000
0007DB40

00000000
~Q008200
00000000
0007DC10
00000000
00000000
0007DCF8
FFFFFFFF
00008000
0207DD38
00198800
F14C9108
1130EOO01
001447FO
58140038
4BEOF250
FlA85820
F23211780
117FOF16E
701000llB
0000D8E6
4011011040
11011011040
4007DF511
0007D978
0007E628
50002000
07070607
E3C5E2E3
F0325810
0 00100
00000000
0OO7F120
0007E07E
5B5BC2D6
60D9C5C3
051F0001
4500FOOC
5870D1F4
4830C03A
C03A4A30
48206000
C03C4140
E00092110
1I00llF6F9
60385810
C004051F
60004930
00014004
4500FOOC
5000F008
58FOC004
41FOC028
58FOC018

4007F128 01010014
QooQOlQ81.0007DA98
20000000 00000000
00000000 00000014
--SAME-00000000 00008000
00000000 0207DD10
FFFFFFFF FFFF[;BE1
00000107 0007DBE8
20000050 4120EOOO
00190600 120011780
401511710 F09119180
89000019 88000019
FOC411100 000c1BIIO
S010F20A 4110F20A
D20lF210 EOO05810
F20A1I122 000058EO
Fl111111800 F22E91100
41EOF14C 9101F233
00000000 00000000
0007D9E8 5007E22C
--SAME-110404040 40110110110
0007E628 00 0 7I:E78
0007DBIIO 0007DBA8
0007DE78 0007FOOO
4A50F060 4A20F060
07070707 00000000
D9E4D540 0007D878
F0789101 10004710
o 00lA8 D4C E3C
0000001C 00000000
0OO7E628 0OO7FOC8
0007E092 0007E146
D7C5D540 5B5BC2C3
D6D9C4BE 58FOC004
4004F6FO 40404076
0007D9E8 OA024100
D2016000 C038D201
4A306000 4E30D208
601C4E30 D208D705
IIC20C03A 1AII25BIIO
601E4820 60004C20
6011114830 601C4E30
1I01l040FO 58FOC004
D20018111 58F01010
00014004 F7F14040
C03E58FO C024078F
F7F440110 40585810
00000000 OA025800
11500FOOC 00000000
051FOOOl 4004F7F7
D2021025 F00158FO
07FF5810 C01C07Fl

Figure 66.

0007E1FC
0007DF80
0000844B
00000000
00COC8E6
182F07F1
00000000
0007DEAO
9610D048
07FF0700
C3D6C2C6
F54BFOF8
107DB78
01010014
0007DA20
00000000
00000014

0007D878
00000001
E56753BE
00000000
0000DB64
0007D878
00000000
0007DC78
92FFEOOO
0007E1FC
F3FOFOFO
10604780
0001FOF1
000040D5
00000000
00000000
86BCF018
0007DBA3

0007D878
00000001
00000000
05F00700
80000015
D7C8C1E2
0007D978
00000000
47FOFOAC
0007[;878
E3C5E2E3
0001C1C2
F2F3F4FO
E8C34000
00000000
0007E278
41EOE001
00640063

F1F2F3F4
00404040
00000000
1160E2E8
58201044
00000000

00000000
00000000
86BCF018
00000000

00000000
0007E278
41E0E001
00640063

00000000
1168E2E8
58201044
00000000

00000000
E2FOFOF8
0207DBA8
0007F170

00000000
40400272
00000064
0007F128

00000107
2COOOO14
20000082
00000000
47000000
F0741120E
110154710
113EEOOOO
·58EIIOOOO
5010F202
F21120AOO
F23E58FO
F2325820
4780F16E
0007r::F08
F16E9025

0007I:B90
4120EOOO
4710F132
0007E3B8
0000FOC4
00009601
FOE84100
89EOOO19
1A401l1EE
D20lF200
91801002
FlF207FF
F23A58EO
001000llB
00000000
F21290BC

00000000
47000000
47FOF15E
02050202
18E44BEO
F232117FO
0008117FO
88EOOO19
000012EE
40069108
11710Fl111
117FOF1011
F23E58FII
00000000
00000000
40110110110

0007E450
OOOOFFFF
91084015
0007DCEO
F24C430E
F01l611800
FOC418EII
19EOll780
11780F132
40154780
OA079108
0000F233
00100A09
00000000
0007D9E8
40110110110

02050202
FFFFFFFF
00000000
00000000
00008900
F23047FO
IIBEOF24E
F08Cll100
50EOF1F2
FllC18E4
1102011710
lB009101
1I1EOF11C
00000000
0007DBIIO
11040110110

1101100000
0007DF80
0007E1FC
0007DE40
1830117FO
00000000
C9D3C2C4
F0329601

00000000
0007DE40
0007D878
00014720
F036D200
E2C1D4D7
D6E2E8FO
00000000

0007DF78
·0000D8E6
0007D878
0007DF78
50002000
D3C54040
F3F09002
OOOOOOQO

000 D97A
0OO7DF70
0007E174
D3D6E2C5
051F0001
5820D1F4
D20058FO
601CC038
D705D208
D208D208
C0385040
C03A1AII2
D208F331
05lFOO02
45EOFOOC
400F5800
5810COOC
D200911EF
D2004110
OA024100
40404040
101045EO
58FOC004

9802D068
0007E05E
0007E05E
5B5BC2C6
4004F5F7
4110C040
C00805EF
58FOC004
D208940F
940FD20E
D21458EO
5BIIOC038
603At20E
000000111
5020D1F4
D2205000
07F15800
10201801
C0500A02
D201158FO
5810D204
F0085020
051F0001

47FEOO
0007E100
400B1F88
C3D4E4D3
1I04040D2
S800D200
5810D200
051F0001
D20E4F30
4F30D208
D214D200
501l0D218
96F0603D
ODOO01FC
5870D1F4
D21C5800
D21C5000
1811011110
4110COIIO
C00805EF
58FOC028
D1F85880
4004F7F8

0007DB40
0007D9E8
0007DEAO
0007EDAO
00000000
C007D878
D0689120
F0549110
00 D E8
007E05E
0OO7E14C
00000001
COOOOOOO
9640D048

01000000
5007E22C
0007DF80
1I007E88E
00000000
00000000
EOO04780
000002EO
0007DA6
D7C5D 40
0007E1A4
lcaOO01A
E6D6D9D2
58FOC004
5000F008
5020D1F4
40404004
60004830
1111106002
FA306050
D20060113
051FOO01
D21370·00
07F158FO
D22011830
COOII051F
5000F008
184005FO
96101020
071F1841
60388000
5820C02C

E2E3E4E~6E7E8E9

~2F3F4F

~M~DB4~

0007DBA8I0007D9~~

~84005FO

96101020
4004F6F4
D2084030
4030601c
6038EOOO
58EOD218
58FOCOOII
0038FFFF
5810D220
C0205000
D22058FO
COll805FO
5800D2011
5810D2011
91201010
DlF8D213
40404080

0007CEAO
0007D97A
00000000
900EFOOA
80000015
C55C5C5C
0007DAD8
58COFOC6
98CEF03A
0007D878
D9E4D540
C3C4C5C6

Sample Dump Resulting from Abnormal Termination (Part 6 of 6)

Program Checkout

259

EXECUTION STATISTICS

The DOS/VS COBOL ~ompiler provides
several methods for testing, debugging, and
optimizing programs.
Use of the symbolic
debugging features is an efficient method
for testing and debugging a program, and is
described in the chapter "Symbolic
Debugging Features".
The chapter entitled
"Program Checkout" contains information
useful for testing and debugging programs
without the symbolic debugging featuresQ
The OPT option, described in the chapter
"Preparing COBOL Programs for Processing",
is an efficient method for automatically
optimizing a program.

To obtain execution statistics if
COUNT is requested for one of many
program units, either all programs
must be compiled by at least DOS/VS
Release 2 compiler, or the program
must terminate in a program unit
compiled on at least a DOS/VS COBOL
Release 2 compiler, or the program
must terminate in at least a DOS/VS
COBOL library Release 2 subroutine.

If COUNT is requested, the user must
specify the SIZE parameter on his load
module EXEC card. The dynamic space
required for COUNT is approximately
512 bytes plus 80 bytes per program
unit being monitored, and four bytes
per count block (see the compiler
output statistics). The requirements
for each program unit are rounded to
the next 128-byte boundary.

The OTHERWISE verb is treated as if
the user coded the ELSE verb.

This chapter describes execution
statistics -- how they may be obtained,
some sample output, and some uses of the
output.
OBTAINING EXECUTION STATISTICS
Execution statistics are invoked via the
CBL card at compile time.
No source
language coding changes are required.
The
execution frequency statistics option,
COUNT, facilitates testing, debugging, and
optimizing by providing the programmer with
verb counts at the following times.
• STOP RUN
• GOBACK in the main program

Debugging and Testing
• Abnormal termination of a job
When COUNT is specified, the following
items should be taken into account:
1.

If COUNT and STXIT are desired, either
STIXIT must be requested in the
program unit requesting COUNT, or, the
program unit requesting COUNT must be
entered before the program unit
requesting STIXIT.

The execution statistics clearly
identify the following areas of the
program:
• Untested and weakly tested areas of the
program
• The last blocks entered and executed
• Possible sources of unnecessary code

260

When COUNT is specified, the compiler
divides the program into blocks of
verbs. When the statistics are
printed, the last block of verbs
executed in each program unit is
indicated.
If the program abnormally
terminates, the statement causing the
abnormal termination can be determined
(by using the symbolic debugging
features, for example). The
programmer should then subtract one
from the verb count for each verb
flagged which follows the abending
verb.

• The most heavily used parts of the
program; that is, those parts most
susceptible to changes.

OPTIMIZATION METHODS
Based on execution frequency and timer
statistics, the following types of
optimization can be implemented by the
user:

• Resequencing the program

Common Expression Elimination

• Insight into SYMDMP

This technique is designed to eliminate
unnecessary arithmetic calculations. An
arithmetic expression calculation is
considered unnecessary if it represents a
value calculated elsewhere that will always
be used without modification. One such
example would be an arithmetic expression
whose operands are not redefined or
reevaluated, but the expression is
recalculated.

• Common expression elimination
• Backward movement
• Unrolling
• Jamming
• Unswitching

Backward Movement

• Incorporating procedures inline

Resequencing the Program

This technique facilitates moving
calculations and other operations from an
area of code frequently executed to an area
less frequently executed. For example, an
expression calculated within a PERFORMed
procedure (using a Format 2~ 3, or 4
PERFORM statement) which always yields the
same value for that PERFORM statement could
be calculated in-line or in another
procedure which would be PERFORMed just
prior to the regularly PERFORMed procedure.
Another example might be an expression
which is calculated in many procedures
which are often PERFORMed in succession.
This expression could be removed from all
the procedures and calculated just once
prior to the procedures.

The COBOL Procedure Division should be
organized as follows:

Unrollinq

• Tabling
• Efficiency guidelines
Note, however, that each optimization
technique can result in more inefficient
code if the statistics used in optimizing
the program are not representative of the
normal program flow. In addition, it is
recommended that any optimization methods
implemented be documented in the program.

All frequently-used paragraphs or
sections should be located near the
routines that use them.
All infrequently-used paragraphs or
sections should be grouped together
and apart from frequently-used
routines.
The most frequently-referenced data
items should be placed in the
beginning of the Working-Storage
Sections.

Procedures which are frequently executed
may be expanded so that the statements
within the procedure are repeated, with
slight modification, to reduce the
procedure overhead. For example,
PERFORM YEARLY-GROSS-CALC VARYING
WEEK-NO
FROM 1 BY 1 UNTIL WEEK-NO
GREATER THAN 52.
YEARLY-GROSS-CALC.
ADD GROSS-SALARY (WEEK-NO) TO
YEARLY-GROSS
could be replaced by

Insight into SYMDMP Output
The area where dynamic symbolic dumps
are to be used can be pOinted to by the
execution statistics. Knowledge of what
area of code is executed and how often it
is executed should give the user
information on what sections should be
further investigated.

PERFORM YEARLY-GRaSS-CALC VARYING
WEEK-NC
FROM 1 BY 4 UNTIL WEEK-NO
GREATER THAN 52.
YEARLY-GRaSS-CALC.
ADD

GROSS-SALARY (WEEK-NO),
GROSS-SALARY (WEEK-NO+1),
Execution statistics

260.1

ADD JOB-COST (COUNT) TO
TOTAL-JOB-COST.
IF SWITCH = 0 ADD JOB-EXPENSE
(COUNT) TO ~OTAL-EXPENSES ELSE
ADD JOB-EXPENSE (COUNT) OVERHEAD TO
TOTAL-EXPENSES.
ADD JOB-INCOME (COUNT) TO
TOTAL-INCOME.
IF SWITCH = 0 ADD JOB-PROFIT (COUNT)
TO TOTAL-PROFITS ELSE
COMPUTE TOTAL-PROFITS =
TOTAL-PROFITS + JOB-INCOME (COUNT)
- JOB-COST (COUNT) - JOB-EXPENSE
(COUNT) - OVERHEAD.

GROSS-SALARY (WEEK-NO+2) , GROSS
SALARY (WEEK-NO+3)
YEARLY-GROSS.
In addition, indexing might be useful in
this example.

Jamming
In some instances, two procedures can be
merged into one procedure, thereby saving
some procedure overhead. An example of
this might be replacing

by
COUNT = 0
IF SWITCH = 0
PERFORM JOB-TOTAL-CAL-O JOB-NUM
TIMES ELSE
PERFORM JOB-TOTAL-CAL-l JOB-NUM
TIMES.

MOVE 0 TO WEEK-NUM •.
PERFORM YEARLY-GROSS-CAL 52 TIMES.
MOVE 0 TO WEEK-NUM.
PERFORM YEARLY-NET-CAL 52 TIMES.

YEARLY-GROSS-CAL.
ADD 1 TO WEEK - NUM,.
ADD GROSS-SALARY (WEEK-NUM) to
YEARLY-GROSS.
YEARLY-NET-CAL.
ADD 1 TO WEEK-NUM.
ADD NET-SALARY (WEEK-NUM) TO
YEARLY-NET.
by
MOVE 0 TO WEEK-NUM.
PERFORM YEARLY-CAL 52 TIMES.

YEARLY-CAL.
ADD 1 TO WEEK-NUM.
ADD GROSS-SALARY (WEEK-NUM) to
YEARLY-GROSS.
ADD NET-SALARY (WEEK-NUM) TO
YEARLY-NET.

JOB-TOTAL-CAL-O.
ADD 1 TO COUNT.
ADD JOB-COST (COUNT) TO
TOTAL-JOB-COST.
ADD JOB-EXPENSE (COUNT) TO
TOTAL-EXPENSES.
ADD JOB-INCOME (COUNT) TO
TOTAL-INCOME.
ADD JOB-PROFIT (COUNT) TO
TOTAL-PROFITS.
JOB-TOTAL-CAL-l.
ADD 1 TO COUNT
ADD JOB-COST (COUNT) TO
TOTAL-JOB-COST
ADD JOB-EXPENSE (COUNT), OVERHEAD TO
TOTAL-EXPENSE
ADD JOB-INCOME (COUNT) TO
TOTAL-INCOME
COMPUTE TOTAL-PROFITS =
TOTAL-PROFITS + JOB-INCOME (COUNT)
- JOB-COST (COUNT) - JOB-EXPENSE
(COUNT) - OVERHEAD.

Unswitching
Incorporating procedures Inline
Procedures may contain tests that result
in the same action for any set of
executions of that procedure. In such a
case, the test can be removed from the
procedure and the procedure duplicated.
For example, if "SWITCH" is not changed
within the loop, replace
COUNT=O
PERFORM
TIMES.

Based on module size, number of
repetitions, modification activities,
future expansion considerations, and
frequency statistics, small procedures can
be moved in-line to minimize overhead
requirements.

JOBS-TOTAL-CAL JOB-NUM
Tabling

JOB-TO'I'AL-CAL.
ADD 1 TO C()UNT.
260.2

This technique is designed to replace
many IF statements by one table look-up

stat@ment, or by one computed GO TO
statement. For example, if'- the same
data-item is tested in many successive IF
statements to set the value of another
data-item to some constant, and the" range
of tested values of the original data-item
is limited, then a predetermined table of
values could be used to assign the value of
the second data-item. Similarly, many
consecutive statements of the form

WORKING WITH DIAGNOSTIC MESSAGES
1.

IF data-item-1=some-constant GO TO
some-procedure
could be replaced by one computed GO TO
statement.

Efficiency Guidelines
Based on execution frequency statistics,
the following types of coding
inefficiencies may be removede

Approach the diagnostic messages in
the order in which they appear on the
source listing. It is possible to get
compound diagnostic messages.
Frequently~ an earlier diagnostic
message indicates the reason for a
later diagnostic message. For
example, a missing quotation mark for
an alphabetic or alphanumeric literal
could involve the inclusion of some
clauses not intended for that
particular literal. This could cause
an apparently valid clause to be
diagnosed as invalid because it is not
complete, or because it is in conflict
with something that preceded it.

2 •. Check for missing or superfluous
punctuation, or other errors of this
type.
3.

Frequently., a seemingly meaningless
message is clarified when the valid
syntax or format of the clause or
statement in question is referenced.

Statement numbers are generated when a
verb or procedure-name is encountered.

Unaligned decimal places in arithmetic
or numeric comparison operands.

Different size operands in moves,
comparisons, or arithmetic operations.

Mixed usage in arithmetic or numeric
comparison operands.

GENERATION OF DIAGNOSTIC MESSAGES

Display usage in arithmetic operands
or one numeric operand and one display
operand in a comparison.

SYNC missing for COMP or COMP-1, -2,
or -4 items.-

The compiler scans the statement,
element by element" to determine whether
the words are combined in a meaningful
manner.
Based upon the elements that have
already been scanned, there are only
certain words or elements that can be
correctly encountered •.

Inefficient COMP type picture; that
is, no sign or more than 9 digits in a
COMP item and no sign, even number of
digits, or more than 16 digits in
COMP-3 items.

Noncomputational subscripts.

If the anticipated elements are not
encountered, a diagnostic message is
produced. Some errors may not be uncovered
until information from various sections of
the program is combined and the
inconsistency is noted. Errors uncovered
in this manner can produce a slightly
different message format than those
uncovered when the actual source text is
still available. The message that is made
unique through that particular error may
not contain, for example, the actual source
statement that produced the error.

DIAGNOSTIC MESSAGES
Diagnostic messages are generated by the
compiler and listed on SYSLST when errors
are found in the source program.
Note: Diagnostic messages (except FIPS
diagnostic messages) are suppressed when
the NOERRS option is in effect.

Errors that appear to be identical are
diagnosed in a slightly different manner,
depending on where they were encountered by
the compiler and how they fit within the
context of valid syntax.
For example i a
period missing from the end of the
Working-Storage section header is diagnosed
specifically as a period required. There
is no other information that can appear at
Execution Statistics

260.3

that point.
However, if at the end of a
data item description entry, an element is
encountered that is not valid at that
point, such as the digits 02, it is
diagnosed as invalid. Any clauses
associated with the 02 entry which conflict
with the clauses in the previous entry (the
one that contained the missing period), are
diagnosed. Thus, a missing period produces
a different type of diagnostic message in
one situation than in the other.
If an error occurs during compilation of
an ON statement, the diagnostic message may
refer to the previous statement number.

lSln D STATEMENT OUT OF SEQUENCE.
I

• If a D-level diagnostic is generated
and the error is a compiler error, the
job will terminate via the CANCEL macro
and produce a dump.
• The following messages will not be
issued during a SYNTAX-only compilation
or during a CSYNTAX compilation if a
C-level error in the diagnostic number
ILAOxxx to ILA4xxx range was
encountered:
ILA5001I

COMPILER ERROR.
ABANDONED.

COMPILATION

ILA5002I

COMPILER ERROR.
ABANDONED ..

COMPILATION

ILA5003I

DIVISOR IS ZERO.
ALL 9'S.

ILA5004I

ALPHANUMERIC SENDING FIELD TOO
BIG. 18 LOW ORDER BYTES USED.

Notes:
• If an E-level diagnostic is generated,
the LINK option is cancelled, and any
linkage editor control statements in
the job stream are invalid. For this
reason, the following message is issued
by the Job Control Processor following
the first linkage editor control
statement encountered:

260.4

RESULT WILL BE

ILA5005I

C0l1P1LER ERROR.
ABANDONED.

COl1PILATION

ILA5025I

ADVANCING OR POSITIONING OPTION
ILLEGAL FOR NON-SEQUENTIAL
FILE. IGNORED.

ILA5006I

COMPILER ERROR.
ABANDONED.

COl1P1LATION

ILA5026I

EXHIBIT OPERAND GREATER THAN 256
BYTES. LENGTH OF 256 ASSUMED.

ILA5027I
ILA50071

COMPILER ERROR.
ABANDONED.

COl1PILATION

NEGATIVE OR ZERO SUBSCRIPT
INVALID. CHANGED TO POSITIVE
1.

ILA5028I
ILA5008I

COMPILER ERROR.
ABANDONED.

C0l1P1LATION

RESULT FIELD WILL HAVE POSITIVE
SIGN.

ILA5029I
1LA50091

C0l1P1LER ERROR.
ABANDONED.

COl1PILATION

STOP RUN GENERATED AFTER LAST
STATEMENT.

ILA5030I
ILA50101

HIGH ORDER TRUNCATION OF THE
CONSTANT DID OCCUR.

ILA5011I

HIGH ORDER TRUNCATION l1IGHT
OCCUR.

INSTEAD OF AN MVCL INSTRUCTION,
AN MVC OR A CALL TO AN
OBJECT-TIME SUBROUTINE HAS BEEN
GENERATED BECAUSE THE FIELDS
OVERLAP DESCRUCTIVELY.

ILA5031I
ILA5012I

LOST INTERl1EDIATE RESULT
ATTRIBUTES IN 'XINTR' TABLE.
COMPILATION ABANDONED.

ILA5013I

ILLEGAL COMPARISON OF TWO NUl1ERIC
LITERALS. STATEl1ENT DISCARDED.

AN MVCL INSTRUCTION HAS BEEN
GENERATED FOR A MOVE INVOLVING
AT LEAST ONE LINKAGE SECTION
DATA-NAME. IF THE FIELDS
OVERLAP DESTRUCTIVELY THE MOVE
WILL NOT BE PERFORMED.

ILA5014I

KEY IN SEARCH ALL AT INVALID
OFFSET. STATEMENT DISCARDED.

ILA50151

INVALID USE OF SPECIAL REGISTER.
SUBSTITUTING-TALLY.

ILA5016I

l10RE THAN 255 SUBSCRIPT ADDRESS
CELLS USED. PROGRAl1 CANNOT
EXECUTE CORRECTLY.

ILA5017I

INVALID ADVANCING OPTION FOR A
DTFCD FILE. USING STACKER1.

ILA5018I

INTEGER IN POSITIONING OPTION NOT
BETWEEN 0 AND 3. 1 ASSUl1ED.

ILA5019I

PUNCH STACKER SELECT SPECIFIED
FOR A DTFPR FILE. USING 'SKIP
TO CHANNEL 11.

ILA5020I

IDENTIFIER NAl1E{S) IN EXHIBIT
EXCEEDS l1AXIMUM. TRUNCATED TO
120 CHARACTERS.

ILA5021I

ILA5022I

INTEGER IN ADVANCING OR
POSITIONING OPTION NOT
POSITIVE. POSITIVE ASSUftED.
MORE THAN 2-DIGIT INTEGER IN
ADVANCING OPTION. USING
INTEGER 1.

ILA5023I

EOP INVALID FOR DOUBLE-BUFFERED
FILE. IGNORED.

ILA5024I

END-OF-PAGE OPTION REQUESTED FOR
NON-DTFPR FILE. IGNORED.

In addition, no message of the form
ILA6xxx will be issued.

LINKAGE EDITOR OUTPUT
The Linkage Editor produces diagnostic
messages, console messages, and a storage
map. For a complete description of output
and error messages from the Linkage Editor,
see the publication DOSIVS System Control
Statements. Output resulting from the link
editing of a COBOL program is discussed in
the chapter "Interpreting Output."

EXECUTION TIME MESSAGES
When an error condition that is
recognized by compiler-generated code
occurs during execution, an error message
is written on SYSLST and often SYSLOG.
Messages that normally appear on SYSLOG
are provided with a code indicating from
which partition the message originated~
A complete list of execution-time
messages can be found in "Appendix I:
Diagnostic Messages."
Program Checkout

261

RECORDING PROGRAM STATUS
When a program is expected to run for an
extended period of time, provision should
be made for taking checkpoint information
periodically during the run. A checkpoint
is the recording of the status of a problem
program and storage (including input/output
status and the contents of the general
registers). Thus, it provides a means of
restarting the job at an intermediate
checkpoint position rather than at the
beginning, if for any reason processing is
terminated before the normal end of the
program. For example, a job of higher
priority may require immediate processing,
or some malfunction (such as a,power
failure) may occur and cause an
interruption. Checkpoints are taken using
the COBOL RERUN clause.
Restart is a means of resuming the
execution of the program from one of the
checkpoints rather than from the beginning
of the job. The ability to restart is
provided through the RSTRT job control
statement. Full details on using this
statement are in- -DOSIVS System Control
Statements.

TAKING A CHECKPOINT
In order to take a checkpoint, the
programmer must specify the source language
RERUN clause and must define the file upon
which checkpoint records are to be written
(for example, ASSGN, EXTEND, etc.). Checkpoin~
information must be written on a 2311, 2314,
2319,3330,3340, 3350, or fixed block mass
1 storage device or on a magnetic tape--either
7- or 9-track. Checkpoint records cannot be
embedded in one of the problem program's
output files, that is, the program must
establish a separate file exclusively for
checkpoint records. Checkpoints cannot be
written on VSAM files.
In designing a program for which
checkpoints are to be taken, the programmer
should consider the fact that, upon
restarting, the program must be able to
continue as though it had just reached that
point in the program at which termination
occurred. Hence, the programmer should
ensure that:
1.

File handling is such as to permit
easy reconstruction of the status of
the system as it existed at the time
of checkpoint was taken. For example,
when multifile reels are used, the
operator should be informed (by
message) as to which file is in use at
the time a checkpoint is to be taken.
He requires this information at
restart time.

The contents of files are not altered
between the time of the checkpoint and
the time of the restart. For
seguential files, all records written
on the file at the time the checkpoint
is taken should be unaltered at
restart time. For nonseguential
files, care must be taken to design
the program so that a restart will not
duplicate work that has been completed
between checkpoint time and restart
time. For example, suppose that
checkpoint 5 is taken. By adding an
amount representing the interest due,
account XYZ is updated on a
direct-access file that was opened
with the 1-0 option. If the program
is restarted from checkpoint 5 and if
the interest is recalculated and again
added to account XYZ, incorrect
results will be produced.

RERUN CLAUSE
The presence of the RERUN clause in the
source program causes the CHKPT macro
instruction to be issued at the specified
interval. When the CHKPT .acro instruction
is issued, the following information is
saved:
1.

Information for the Restart and other
supervisor or job control routines.

The general registers.

Bytes 8 through 10, and 12 through 45
of the Communication Region.

The problem progra. area.

All file protection extents for files
assigned to mass storage devices if
the extents are attached to logical
units contained in the program for
which checkpoints are taken.

Since the COBOL RERUN clause provides a
linkage to the system CHKPT macro
instruction, any warnings and restrictions
on the use of this macro instruction also
apply to the use of the RERUN clause. See
the publication DOS/VS Supervisor and I/O
Macros for a complete description of the
CHKPT macro instruction.
262

If the program is modular in design,
RERUN statements must be included in all
modules that handle files for which
checkpoints are to be taken.
(When an
entry point of a module containing a RERUN
statement is encountered, a COBOL
subroutine, ILBDCKPO, is called. ILBDCKPO
enters the files of the module into the

chapter "Preparing COBOL Programs For
Processing." All other job control
statements applicable to the job step
should be the same as when the job was
originally run. If necessary, the
channel and unit addresses for the II
ASSGN control statements may be
changed.

list of files to be repositioned.)
Repositioning to the proper record will not
occur for any files that were defined in
modules other than those containing RERUN
statements. !oreover, a restart from any
given checkpoint may not reposition other
tapes on which checkpoints are stored.
Note, too, that only one disk checkpoint
file can be used.
2.

Rewind all tapes used by the program
being restarted, and mount them on
devices assigned to the symbolic units
required by the program. If
multivolume files are used~ mount (on
the primary unit) the reel being used
at the time that the checkpoint was
taken, and rewind it. If multifile
volumes are used, position the reel to
the start of the file referenced at
the time the checkpoint is being
taken.

Reposition any card file so that only
cards not yet read when the checkpoint
was taken are in the card reader.

Execute the job.

A checkpointed program can be
restarted only in the same partition.
The virtual partition must start at
the same location as when the program
was checkpointed and its end address
must not be lower than at that time.
This is because checkpoint dumps
the entire virtual partition.

RESTARTING A PROGRA!
If the programmer requests checkpoints
in his job by means of the COBOL RERUN
clause, the following message is given each
time a checkpoint is taken:
OC001 CHKPT nnnn HAS BEEN TAKEN ON
SYSxxx
nnnn
is the 4-character identification of
the checkpoint record.
To restart a job from a checkpoint, the
following steps are required:
1.

Replace the // EXEC statement with a
// RSTRT statement. The format of the
RSTRT statement is discussed in the

Program Checkout

263

APPENDIX A:

The following is a sample COBOL program
and the output listing resulting from its
compilation, link editing, and execution.
The program creates a blocked, unlabeled,
standard sequential file, writes it out on
tape, and then reads it back in. It also
does a check on the field called
NO-OF-DEPENDENTS. All data records in the
file are displayed. Those with a zero in
the NO-OF-DEPENDENTS field are displayed
with the special character Z. The records

SAMPLE PROGRAM OUTPUT

of the file are not altered from the time
of creation, despite the fact that the
NO-OF-DEPENDENTS field is changed for
display purposes. The individual records
of the file are created using the
subscripting technique.
The output formats illustrated in the
listing are described in the chapter
"Interpreting output."

// JOB SAMPLE
// OPTION NODECK,LINK,LIST,LISTX,SYM,ERRS
// EXEC FCOBOL

IBM DOS VS COBOL

REL 1.0

PP NO. 5746-CBl

08.17.32

10/02/73

CBL QUOTE,OPT,SXREF,LVL=A
00001
000010 IDENTIFICATION DIVISION.
00002
000020 PROGRAM-ID. TESTRUN.
00003
AUTHOR. PROGRAMMER NAME.
00004
INSTALLATION. NEW YORK DEVELOPNENT CENTER
00005
DATE-WRITTEN. APRIL 18,1973
00006
DATE-COMPILED. 10/02/73
00007
REMARKS. THIS PROGRAM HAS BEEN WRITTEN AS A SAMPLE PROGRAM FOR
OOOOS
COBOL USERS. IT CREATES AN OUTPUT FILE AND READS IT BACK
00009
AS INPUT.
00010
000100
00011
000110 ENVIRONMENT DIVISION.
00012
000120 CONFIGURATION SECTION.
00013
000130 SOURCE-COMPUTER. IBM-360-H50.
00014
000140 OBJECT-COMPUTER. IBM-370.
00015
000150 INPUT-OUTPUT SECTION.
00016
000160 FILE-CONTROL.
00017
000170
SELECT FILE-1 ASSIGN TO SYSOOS-UT-2400-S.
00018
000180
SELECT FILE-2 ASSIGN TO SYSOOS-UT-2400-S.
00019
000190
00020
000200 DATA DIVISION.
00021
000210 FILE SECTION.
00022
000220 FD FILE-l
00023
000230
LABEL RECORDS ARE OMITTED
00024
000240
BLOCK CONTAINS 5 RECORDS
00025
000250
RECORDING MODE IS F
00026
000255
RECORD CONTAINS 20 CHARACTERS
00027
000260
DATA RECORD IS RECORD-1.
00028
000270 01 RECORD-l.
00029
05 FIELD-A PIC X(20).
00030
000290 FD FILE-2
00031
000300
LABEL RECORDS ARE OMITTED
00032
000310
BLOCK CONTAINS 5 RECORDS
00033
000320
RECORD CONTAINS 20 CHARACTERS
00034
000330
RECORDING MODE IS F
00035
000340
DATA RECORD IS RECORD-2.
00036
000350 01 RECORD-2.
00037
05 FIELD-A PIC X(20).

Appendix A:

Sample Program Output

265

IB.r.~

00038
00039
00040
00041
00042
00043
00044
00045
00046
00047
00048
00049
00050
00051
00052
00053
00054
00055
00056
00057
00058
00059
00060
00061
C0062
00063
00064
00065
00066
00067
00068
00069
00070
00071
00072
00073
00074
00075
00076
00077
00078
00079
00080

266

DOS VS COBOL

REL l.0

PP NO. 574f5-CBl

000370 WORRING-STORAGE SECTION.
000380 01 FILLER.
02 ROUNT PIC S99 COMP SYNC.
000400
02 ALPHABET PIC X(26) VALUE IS "ABCDEFGHIJKLMNOPQRSTUVWXYZ".
000410
02 ALPHA REDEFINES ALPHABET PIC X OCCURS 26 TIMES.
000420
02 NUMBR PIC S99 COMP SYNC.
000430
02 DEPENDENTS PIC X(26) ~ALUE ·01234012340123401234012340·.
000440
02 DEPEND REDEFINES DEPENDiN~S PIC X OCCURS 26 TIMES.
000450 01 WORR-RECORD.
000460
05 NAME-FIELD PIC X.
000470
05 FILLER PIC X VALUE IS SPACE.
05 RECORD-NO PIC 9999.
000480
000490
05 FILLER PIC X VALUE IS SPACE.
000500
05 LOCATION PIC AAA VALUE IS "NYC".
000510
05 FILLER PIC X VALUE IS SPACE.
000520
05 NO-OF-DEPENDENTS PIC XX.
000530
05 FILLER PIC X(7) VALUE IS SPACES.
000540
000550 PROCEDURE DIVISION.
BEGIN.
NOTE THAT ~HE FOLLOWING OPENS THE OUTPUT FIL~ TO BE CREATED
000570
AND INITIALIZES COUNTERS.
000580
000590 STEP-l. OPEN OUTPUT FILE-l. MOVE ZERO TO KOUNT, NUMBR.
NOTE THAT THE FOLLOWING CREATES INTERNALLY THE RECORDS TO BE
000600
CONTAINED IN THE FILE, WRITES THEM ON TAPE, AND DISPLAYS
000610
000620
THEM ON THE CONSOLE.
000630 STEP-2. ADD 1 TO KOUNT, NUMBR. MOVE ALPHA (KOUNT) TO
000640
NAME-FIELD.
000650
MOVE DEPEND (KOUNT) TO NO-OF-DEPENDENTS
000660
MOVE NUMBR TO RECORD-NO.
000670 STEP-3. DISPLAY WORK-RECORD UPON CONSOLE. WRITE RECORD-l FROM
WORK-RECORD.
000680
000690 STEP-4. PERFORM STEP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 26.
000700
NOTE THAT THE FOLLOWING CLOSES THE OUTPUT FILE AND REOPENS
IT AS INPUT.
000710
STEP-5.
CLOSE FILE-l. OPEN INPUT FILE-2.
000720
000730
NOTE THAT THE FOLLOWING READS BACK THE FILE AND SINGLES
000740
OUT EMPLOYEES WITH NO DEPENDENTS.
000750 STEP-6. READ FILE-2 RECORD INTO WORK-RECORD AT END GO TO STEP-8.
000760 STEP-7. IF NO-OF-DEPENDENTS IS EQUAL TO "0· MOVE "Z" TO
000710
NO-OF-DEPENDENTS. EXHIBIT NAMED WORK-RECORD. GO TO STEP-6.
000780 STEP-So CLOSE FILE-2.
000790
STOP RUN.

OB.17.32

10/02/73

REL 1.0

IBM DOS VS COBOL
INTRNL NAME

LVL SOURCE NAME

DNN=1-148
DNM=1-179
DNl-J=1-200
DNM=1-217
DNM=1-248
DNM=1-269
DNl-l=1-289
Di'lM=1-308
DNM=1-323
DNM=1-341
DNM=1-359
DNM=1-374
DNM=1-394
DNM=1-410
DNl'l=1-434
DNM=1-454
DNM=1-473
DNM=1-492
DNr-;=2-000
DNM=2-018
DNM=2-037
DNM=2-063

FD
01
02
PD
01
02
01
02
02
02
02
02
02
01
02
02
02
02
02
02
02
02

FILE-l
RECORD-1
FIELD-A
FILE-2
RECORD-2
FIELD-A
FILLER
KOUNT
ALPHABET
ALPHA
NUMBR
DEPENDENTS
DEPEND
WORK-RECORD
NAME-FIELD
FILLER
RECORD-NO
FILLER
LOCATION
FILLER
NO-OF-DEPENDENTS
FILLER

pp NO. 5746-CBl

BASE
DTF=Ol
BL=l
BL=l
DTF=02
BL=2
BL=2
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3
BL=3

DISPL

IN'IRNL NAME

08.17.32
DEFINITION

DNl~=1-148

000
000
000
000
000
000
002
002
01C
OlE

DNM=1-119
DNM=1-200
DNM=1-211
DNM=1-248
DNM=1-269
DNM=1-289
DNM=1-308
DNM=1-323
DNM=1-341
DNM=1-359
DNM=1-374

DS OCL20
DS 20C
DS
DS
DS
DS
DS
DS
DS
DS

OCL20
20C
OCL56
lH
26C
lC
1H
26C

V.l.L

DNr.~=1=394

n",

038
038
039
03A
03E
03F
042
043
045

DNM=1-410
DNM=1-434
DNM=1-454
DNM=1-473
DNM=1-492
DNM=2-000
DNM=2-018
DNM=2-037
DNM=2-063

DS
DS
DS
)S
DS
DS
DS
DS
DS

OCL20
1C
1C
4C
1C
3C
1C
2C
7C

Appendix A:

USAGE
DTFf.:T
GROUP
DISP
D'I'FNT
GROUP
DISP
GROUP
CQlV1P
DISP
DISP
COMP
DISP
DIS?
GROUP
DISP
DISP
DISP-NM
DISP
DISP
DISP
DISP
DISP

10/02/73
rt

M
F
F

Sample Program Output

267

IBM DOS VS COBOL

PP NO. 5746-CBl

MEMORY MAP
TGT
SAVE AREA
SWITCH
TALLY
SORT SAVE
ENTRY-SAVE
SORT CORE SIZE
NSTD-REELS
SORT RET
WORKING CELLS
SORT FILE SIZE
SORT MODE SIZE
PGT-VN TBL
TGT-VN TBL
SORTAB ADDRESS
LENGTH OF VN TBL
LNGTH OF SORTAB
PGM ID
A(INIT1)
UPSI SWITCHES
DEBUG TABLE PTR
CURRENT PRIORITY
TA LENGTH
PRaLl CELL PTR
UNUSED
RESERVED
VSAM SAVE AREA ADDRESS
UNUSED
RESERVED
OVERFLOW CELLS
BL CELLS
DTFADR CELLS
FIB CELLS
TEMP STORAGE
TEMP STORAGE-2
TEMP STORAGE-3
TEMP STORAGE-4
BLL CELLS
VLC CELLS
SBL CELLS
INDEX CELLS
SUBADR CELLS
ONCTL CELLS
PFHCTL CELLS
PFMSAV CELLS
VN CELLS
SAVE AREA =2
XSASW CELLS
XSA CELLS
PARAM CELLS
RPTSAV AREA
CHECKPT CTR
IOPTR CELLS
DEBUG TABLE

268

003F8
003F8
00440
00444
00448
0044C
00450
00454
00456
00458
00588
005SC
00590
00594
00598
0059C
0059E
005AO
005A8
005AC
005B4
005B8
005B9
005BC
005CO
005C4
005C8
005CC
005D4
005EC
005EC
005F8
00600
00608
00610
00610
00610
00610
00614
00614
00614
00614
0061C
0061C
0061C
00620
00624
00624
00624
00624
00628
00628
00628
00628

08.17.32

10/02/73

IBM DOS VS COBOL

REL 1. 0

PP NO. 5746-CB1

08.17.32

10/02/73

LITERAL POOL (HEX)
00640 (LIT+O)
00658 (LIT+24)

00000001
C2C6C3D4

001A5B5B
E4D35B5B

C2D6D7C5
COOOOOOO

D5405B5B

C2C3D3D6

E2C55BSB

DISPLAY LITERALS (BCD)
00664 (LTL+36)

'WORK-RECORD'
PGT
DEBUG LINKAGE AREA
OVERFLOW CELLS
VIRTUAL CELLS
PROCEDURE NAME CELLS
GENERATED NAME CELLS
SUBDTF ADDRESS CELLS
VNI CELLS
LITERALS
DISPLAY LITERALS
PROCEDURE BLOCK CELLS

00628
00628
00628
0062C
00638
00638
0063C
0063C
00640
00664
00670

BL =3
BL =1
BL =2

WORKING-STORAGE STARTS AT LOCATION 00100 FOR A LENGTH OF 00050.
PROCEDURE BLOCK ASSIGNMENT
PBL

= REG

PBL =1

11
STARTS AT LOCATION 000674

STATEMENT 60

Appendix A:

Sample Program Output

269

uvw VS COBOL
IBM ,.,.,...'"

REL 1.0

pp NO.

5746-CBl

08.17.32

0
57
000674

PN=02

EQU

000674

PN=03

EQU

S'IART

EQU
L
L

60
60

*
*
*
11,048(0,12)

000674
000674
000678
00067e
000680
000684
000686
000688
00068C
000690
000694
000696
00069A
00069E
0006AO
0006A4
0006A8
0006AC

58 BO C 048
58 20 D IF4
41 10 C OlE
58 00 D 200
18 40
05 FO
50 00 F 008
45 00 F ooe
00000000
OA 02
41 00 D 200
58 FO C 008
05 EF
58 10 D 200
96 10 1 020
50 20 D IF4
58 70 D IF4

L
BALR
L
01
ST
L

2,H'4(0,13)
1,01E(0,12)
0,200(0,13)
4,0
15,0
0,008(0,15)
0,00e(0,15)
X'OOOOOOOO'
2
0,200(0,13)
15,008(0,12)
14,15
1,200(0,13)
020(1) ,X'10'
2,lF4(0,13)
7,lF4(0,13)

0006BO
0006B6

D2 01 6 000 C 018
D2 01 6 Ole C 018

MVC
MVC

000(2,6),018(12)
01C(2,6) ,018 (12)

EQU

LH
AH
CVD
XC
N1
CVB
STH
LH
AH
CVD
XC
NI
eVB
STH

3,01A(0,12)
3,000(0,6)
3,210(0,13)
210(6,13),210(13)
216(13),X'OF'
3,210(0,13)
3,000(0,6)
3,OlA(0,12)
3,01C(0,6)
3,210(0,13)
210(6,13),210(13)
216(13),X'OF'
3,210(0,13)
3,01C(0,6)

4,002(0,6)
2,000(0,6)
2,01A(0,12)
4,2
4,018(0,12)
4,21C(0,13)
14,21C(0,13)
038<1,6),000(14)
4, OlE (0·, 6)
2,000(0,6)
2,01A(0,12)
4,2
4,01S(0,12)
4,220(0,13)
15,220(0,13)
043 (1,6) ,000 (15)
044(6),X'40'

L1T+O
SES=2
SBS=2
DNM=2-37
DNM=2-37+1

3,01C(0,6)
3,210(0,13)
03A(4,6),216(2,13)
03D(6),X'FO'

DNM=1-359
'1S=Ol
DNM=1-473
DNM=1-473+3

L
LR
BALR
ST
BAL
DC
sve
LA

PEL=l
BL =1
L1T+6
D'IF=l

D'1F=l
V (ILBDHlLO)
DTF=l
BL =1
BL =1

60
DNM=I-308
DNM=1-359

L1'1+0
LI'I+0

64
PN=04

0006BC
64
0006Be
0006CO
0006C4
0006C8
0006CE
0006D2
0006D6
0006DA
0006DE
0006E2
0006E6
0006EC
0006FO
0006F4

48
4A
4E
D7
91.1
4F
40
48
4A
4E
D7
94
4F
40

30
30
30
05
OF
30
30
30
30
30
05
OF
30
30

C
6
D
D
D
D
6
C
6
D
D
D
D
6

0006F8
0006FC
000700
000704
000706
00070A
00070E
000712
000718
00071C
000720
000124
000726
00072A
00072E
000732
000738

41
48
4C
lA
5B
50
58
D2
41
48
4e
111
5B
50
58
1J2
92

40
20
20
42
40
40
EO
00
40
20
20
42
40
40
FO
00
40

6 002
6 000
C 01A

00073C
000740
000744
00074A

48
4E
F3
96

30
30
31
FO

01A
000
210
210 D 210
216
210
000
01A
01C
210
210 D 210
216
210
01C

lI'I+2
Di~M=1-308

'IS=Ol
TS=Ol
'1S=01+6
TS=Ol
DNM=1-308
.i.IT+2
DNM=1-359
'IS=Ol
TS=Ol
'IS=01+6
TS=Ol
Dt-IM=1-359

TS=ul

TS=Ol

64
LH
MH
AR
S
ST
L
MVC

C
D
D
6
6
6
C

018
21C
21C
038 E 000
OlE
000
01A

C
D
D
6
6

018
220
220
043 F 000
044

LH
Mti
AR
S
ST
L
MVC
MVI

6
D
6
6

01C
210
03A D 216
03D

LH
CVD
UNPK
01

DNM=1-341
DNM=1-308
L1T+2
L1T+O
SBS=1
SES=l
DNM=1-434
DNM=1-394
DNM=1-30S
L1T+2

DNM=1-341

DNM=1-394

270

TS=07

10/02/73

PN=05

0OO74E
68

00074E
000752
000754
000756
000757
0OO75A
00075E
000760

58 FO C OOC
05 1F
0002
00
000014
ODOOO1FC
0038
FFFF

000762
000768
00076C
00076E
000772
000776
00077A
00077E
000782

D2
58
18
58

45
50
58
58
07

13
10
41
FO
EO
20
70
10
Fi

7 000 6 038
D 200
1 010
F

ooe

D 1F4
D 1F4
D 228

18.17.32

PP NO. 5746-CBl

REL 1.0

IBM DOS VS COBOL

EQU

L
BALR
DC
DC
DC
DC
DC
DC

15, OOC (0, 12)
1,15
X'0002'
X'OO'
X'00OO14'
X'ODOOO1FC'
X'OO38'
X'FFFF'

V (ILEI:DSPO)

MVC
L
LR
L
BAL
ST
L
L
BCR

000(20,7),038(6)
1,200(0,13)
4,1
15,010(0,1)
14,OOC{O,lS)
2,lF4(0,13)
7,lF4(0,13)
1,228(0,13)
15,1

DNM=1-179
D'IF=l

EQU

INC
LA
ST
EQU
LH
CH
BC
Be
EQU
MVC

224(4,13),228(13)
o ,11E (0,11>
0,228(0,13)

10/02/73

BL =3

DNK=1-410

BL =1
BL =1
VN=Ol

70
PN=06

000784
70
000784
00078A
00078E
000792
000792
000796
00079A
00079E
0007A2
0007A2

D2 03 D 224 D 228
41 00 B llE
50 00 D 228
GN=Ol
48
49
47
47

30
30
80
FO

6
C
B
B

000
01C
12E
048
GN=02

D2 03 D 228 D 224

*3,000(0,6)

PSV=l
GN=Ol
VN=Ol

3,01C(0,12)
8,12E(0,11>
15,048(0,11>

DNM=1-308
L1'I+4
GN=02
PN=04

*228(4,13),224(13)

VN=Ol

PSV=l

EQU

0007A8
0007AC
0007BO
0007B2
0007B4
0007B8
0007BA
0007BC
0007CO
0007C4
0007C8
0007CA
0007CE
0007D2

58 10 D 200
94 EF 1 020
18 01
18 40
41 10 C 026
07 00
05 FO
50 00 F 008
45 00 F OOC
00000000
OA 02
58 00 D 200
41 10 C 02E
OA 02

PN=07

L
N1
LR
LR
LA
BCR
BALR
ST
BAL
DC
SVC
L
LA
SVC

1,200(0,13)
020 (1) ,x 'EF'
0,1
4,0
1,026(0,12)
0,0
15,0
0,008(0,15)
0,OOC(0,15)
X'OOCOOOOO'
2
0,200(0,13)
1,02E(0,12)
2

0007D4
0007D8
0007DC
0007DE
0007EO
0007E4
0007E8
0007EC
0007EE
0007F2
0007F6
0007F8
0007FC

41 10 C OlE
58 00 D 204
18 40
05 FO
50 00 F 008
45 00 F OOC
00000000
OA 02
41 00 D 204
58 FO C 008
05 EF
58 10 D 204
96 10 1 020

LA
L
LR
BALR
ST
BAL
DC
SVC

1,01E(0,12)
0,204(0,13)
4,0
15,0
0,008(0,15)
0,00C(0,15)
X'OOOOOOOO'
2
0,204(0,13)
15,008(0,12)
14,15
1,204(0,13)
020 (1) ,X'10'

0007A8
73

D'IF=l

L1'I+14

D'IF=l
L1T+22

L
BALR
L
01

Appendix A:

L1T+6
D'IF=2

D'IF=2
V ,001(15)
15,010(0,1)
14,008(0,15)
2,li8 (0,13)
8,lF8(0,13)
038(20,6),000(8)
15,lC2(0,11)

76
000800
000804
000808
00080C
00080E
000812
000818
00081C
000820
000824
000828
00082E
000832

58
91
47
18
41
D2
58
45
50
58
D2
47

10
20
10
41
FO
02
FO
EO
20
80

000832
000836

47 FO B 208

D
13 6
FO B

010
025 FOOl
010
008
IFe
IF8
038 8 000
lC2
GN=03

MVC
L
BAL
ST
L
MVC
BC
EQU

GN=04

BC
EQU

PN=09

EQU

043(6),X'FO'
7,lDA(0,11)
044(6),X'40'
7, IDA (0,11)
043(6),X'E9'
044(6),X'40'

GN=05

CLI
BC
CLI
BC
MVI
MVI
EQU
L
ST

76
77

000836
77

6
B
6
B
6
6

043
IDA
044
IDA
043
044

GN=03

BL =2
BL =2
DNM=1-410
GN=04
PN=010

*
*

95
47
95
47
92
92

00084E
000852
000856
00085A
00085E
000860
000862
000863
000866
00086A
00086C
00086D
000870
000874
000876

58 10 c 038
50 10 D 22C
41 20 D 22C
58 FO C OOC
05 IF
8001
10
OOOOOB
OCOOO03C
0000
00
000014
ODOOOIFC
0038
FFFF

BALR
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC

1,038(0,12)
1,22C(0,13)
2,22C(0,13)
15,00C(O,12)
1,15
X'8001'
X'10'
X'OOOOOB'
X'OCOOO03C'
X'OOOO'
X'OO'
X'OOO014'
X'ODOOOIFC'
X'0038'
X'FFFF'

000878

47 FO B 18C

15,18C(O,ll)

LA
L

GN=03

*
15,208(0,11)

000836
00083A
00083E
000842
000846
00084A
00084E

FO
70
40
70
E9
40

D'IF=2

DNM=2-37
GN=05
DNM=2-37+1
GN=05
DNM=2-37
DNM=2-37+1

*
LI'I+32
PR~=1

PRM=l
V (ILBDDSPO)

LI'I+36

BL =3

78
FN=08

79
PN=010

00087C

EQU

L
NI
LR
LR

1,204(0,13)
020(1) ,X'EF'
0,1
4,0
1,026(0,12)
0,0
15,0
0,008(0,15)
0,00C(0,15)
X'OOOOOOOO'
2
0,204(0,13)
1,02E(0,12)

79
00087C
000880
000884
000886
000888
00088C
00088E
000890
000894
000898
00089C
00089E
0008A2
0OO8A6

58 10 D 204
94 EF 1 020
18 01
18 40
41 10 C 026
07 00
05 FO
50 00 F 008
45 00 F OOC
00000000
OA 02
58 00 D 204
41 10 C 02E
OA 02

BCR
BALR
ST
BAL
DC
SVC
L
LA
SVC

0008A8

OA OE

SVC

272

DTF=2

LIT+14

DTF=2
LIT+22

DNM=1-248

10/02/73

OOOSAA
OOOSAE
0008B2
0008B6
0008BA
OOOSBC
OOOSCO
000SC4
OOOSCS
OOOSCA
0008CE
0008D2
0008D6
OOOSDA
0008DE
OOOSEO
0008E4
OOOSES
OOOSEC
OOOSFO
000SF2
000SF6
0008F8
0008FC
000900
000904
00090S
00090A
00090E
000910
000914
000918
00091C
000920
000922
000926
000928
00092C
000930
000934
000938
00093C
000942
000946
00094A
00094E
000000
000002
000004
000008

aooooc

000084
000088
OOOOSC
000090
000094
000098
00009C
OOOOAO

PP N('. 5746-CB1

REL 1.0

IBM Do"S VS COBOL

50 DO 5 008
50 50 D 004
58 20 C 004
95 00 2 000
07 79
92 FF 2 000
96 10 D 048
50 EO D 054
05 FO
91 20 D 048
47 EO F 016
58 00 B 04S
98 2D B 050
58 EO D 054
07 FE
96 20 D 048
41 60 0 004
41 10 C 000
41 70 C 003
05 50
58 40 1 000
lE 4£
50 40 1 000
S7 16 5 000
41 10 C 010
41 70 C 017
05 50
5S 40 1 000
1E 4B
50 40 1 000
S7 16 5 000
41 SO D IF4
41 70 0 20F
05 10
5S 00 8 000
lE OB
50 00 S 000
87 S6 1 000
58 60 D 1FC
58 70 D IF4
58 80 0 1F8
D2 03 0 228 C 014
58 EO D 1BO
90 60 E 060
58 EO D 054
07 FE
05 FO
07 00
90 OE F OOA
47 FO F 082
00000000
58 CO F OC6
58 EO C 004
5S DO F OCA
95 00 E 000
47 70 F OA2
96 10 D 04S
92 FF E 000
47 FO F OAC

INI'I2

ST
ST
L
CLI
BCR
MVI
01

INI'!3

ST
BALR
TM
BC
L
LM
L
BCR
01
LA
LA

LA
BALR
L
ALR
ST
BXLE
LA
LA

BALR
L
ALR
ST
BXLE
LA
LA

BALR
L
ALR
ST
BXLE
L
L
L
MVC
L
S'J:M
L

INIT1

BCR
BALR
BCR
STl
2,13,050(11)
14,054(0,13)
15,14
04S(13),X'20'
6,004<0,0)
1,000
4,11
4,000(0,1>
1,6,000(5)
1,010(0,12)
7,017(0,12)
5,0
4,000(0,1)
4,11
4,000<0,1)
1,6,000(5)
8,lF4(0,13)
7,20F(0,13)
1,0
O,OOO(O,S)
0,11
O,OOO(O,S)
8,6,000(1)
6,1FC(0,13)
7,lF4(0,13}
S,lF8(0,13)
228(4,13),014(12)
14,180(0,13)
6,13,060(14)
14,054(0,13)
15,14
15,0
0,0
0,14,00A(15)
15,082<0,15)
30F'0'
12,OC6(0,15}
14,004(0,12)
13,OCA(0,15)
OOO(14),X'00'
7, OA 2 (G, 15)
048 (13) ,X'10'
000 (14) ,X' FF'
15,OAC(0,15}

OS.17.32

10/02/73

VIR=l

SWT+O
SW'I+O

SWT+O
VIR=1-1

Pl'l=Ol
LIT+0-1

OVF=1
TS=01-1

BL =3
BL =1
BL =2
VN=Ol

VNI=l

VIR=1

SWT+O

Appendix A:

Sample Program Output

273

IBM DOS VS COBOL

0000A4
OOOOA8
OOOOAC
OOOOAE
OOOOB2
0000B6
0000B8
OOOOBA
OOOOBC
OOOOCO
0000C4
0000C8
OOOOCC
000000
000004
000008
OOOOEO
0000E8
OOOOEC
0000F4

*S'IATISTICS*
*S'IATISTICS*
*OPTIONS IN EFFECT*
*OPTIONS IN EFFECT*
*OPTIONS IN EFFECT*
*OPTIONS IN EFFECT*

274

PP NO. 5746-CBl

REL 1. 0

98 CE F 03A
90 EC 0 OOC
18 5D
98 9F F OBA
91 10 D 048
07 19
07 FF
07 00
000008C4
00000000
00000000
00000628
000003F8
00000674
000008AA
C3D6C2D6F3FOFOFO
E3C5E2E3D9E4D540
00000000
F1F061FOF261F7F3
FOF84BF1F74BF3F2

SOURCE RECORDS
80
PARTITION SIZE
655176
PMAP RELOC ADR
NCNE
LIS'IX
QUOTE
NOCLIST
FLAGW
NOS'IA'IE
TRUNC

LM
STM
LR
LM
TIvi
BCR
BCR
BCR
ADCON
AOCON
ADCON
ADCON
ADCON
ADCON
AOCON
DC
DC
DC
DC
DC

12,14,03A(15)
14,12,00C(13)
5,13
9,1:J,OEA<1S)
048(13),X'10'
1,9
15,15
0,0
L4(INI'I3)
L4(INI'Il)
L4 UNI'Il)
L4(PGT)
L4('IGT)
L4(S'IART)
L4 UNIT2)
X'C3D6C2D6F3FOFOFO'
X'E3C5E2E3D9E4D540'
X'OOOOOOOO'
X'F1F061FOF261F7F3'
X'FOF84BF1F74BF3F2'

DATA ITEMS =
LINE COUNT =
SI'ACING
SYM
NOCATALR
ZWB
NOSUPMAP
SEQ
NOSYMDMP

22
56
1

09.17.32

10/02/73

SWT+O

NO OF VERBS
BUFFER SIZE
FLOW
LI';~K
LIST
XREF
ERRS
NODECK
HOVERB

28
512
NONE
NOS'IXIT
SXRl.F
NOSYNTAX

,WLIB
OPT
LVL=A

PP NO. 5746-CBl

REL 1.0

IBM DOS VS COBOL

08.17.32

10/02/73

CROSS-REFERENCE DICTIONARY
DATA NA..'1ES

DEFN

AI.PHA
AI.PHABET
DEPEND

000042
000041
000045
000044

DEPENDEL~TS

REFERENCE
000064
000066

00002~

FIELD-A
FIELD-A
FILE-1
FILE-2

RECORD-NO
RECORD-1
RECORD-2
WORK-RECORD

000037
000017
000018
QQQQ4Q
000051
000047
000053
000043
000049
000028
000036
000046

000064
000066
000060
000067
000068
000076
000068

PROCLDURE NAMES

DEFN

REFERENCE

BEGIN
S'IEP-1
S'IEP-2
STEP-3
STEP-4
S'IEP-5
STEP-6
S'IEP-7
STEP-8

000057
000060
000064
000068
000070
000073
000076
000077
000079

KCUNT
LCCA'IION
NAME-FIELD
NC-OF-DEPENDENTS

NUMBrt

CARD

ERROR MESSAGE

00064
00064

lLA5011I-W
ILA5011I-W

000060
000073
000060

000068
000076
000064

000073
000079
000066

000077
000064

000067

000076

000078

000070

000070
000070
000078
000076

HIGH ORDER TRUNCATION MIGHT OCCUR.
HIGH ORDER TRUNCATION MIGHT OCCUR.
FEDERAL INFORMATION PROCESSING STANDARDS (FIPS> DIAGNOSTIC MESSAGES

LINE

NUMBER

MESSAGE

00006
00025
00034
00054
00060
00062
00062
C0064
00064
00068
00068
00068
00070
00076
00078

ILA8003I-W
ILA8002I-W
ILA8002I-W
ILA8003I-W
ILA8003I-W
ILA8003I-W
ILA8003I-W
ILA8003I-W
ILA8003I-W
lLA8003I-W
lLA8002I-W
lLA8003I-W
lLA8003I-W
ILA8003I-W
ILA8002I-W

DATE-COMPILED PARAGRAPH IS AN EXTENSION TO FIPS LEVEL A.
RECORDING MODE IS CLAUSE IS AN EXTENSION TO ALL FIPS LEVELS.
RECORDING MODE IS CLAUSE IS AN EXTENSION TO ALL FIPS LEVELS.
SPACES IS AN EXTENSION TO FIPS LEVEL A.
COMMA OR SEMICOLON AS PUNCTUATION IS AN EXTENSION TO FIPS LEVEL A.
COMMA OR SEMICOLON AS PUNCTUATION IS AN EXTENSION TO FIPS LEVEL A.
COMMA OR SEMICOLON AS PUNCTUATION IS AN EXTENSION TO FIPS LEVEL A.
COMMA OR SEMICOLON AS PUNCTUATION IS AN EXTENSION TO FIPS LLVEL A.
MULTIPLE RESULTS IN ADD STATEMENT IS AN EXTENSION TO FIPS LEVEL A.
UPON OPTION OF DISPLAY STATEMENT IS AN EXTENSION TO FIPS LEVEL A.
UPON CONSOLE OPTION OF DISPLAY STATEMENT IS AN EXTENSION TO ALL L1WELS.
FROM OPTION OF WRITE S~TEMENT IS AN EXTENSION TO FIPS LEVEL A.
UNTIL OPTION OF PERFORM STATEMENT IS AN EXTLNSION TO FIPS LEVEL A.
INTO OPTION OF READ S'IATEMENT IS AN EXTENSION TO FIPS LEVEL A.
EXHIBIT STATEMENT IS AN EXTENSION TO ALL FIPS LEVELS.

PAGE

END OF COMPILATION

Appendix A:

Sample Program output

275

!a~

PP NO. 5746-CB1

REL 1. 0

DOS VS COBOL

08.17.32

// EXEC LNKED'I

JOE

DOS LINKAGE EDITOR DIAGNOSTIC OF

SAMPLE

AC'!ION
LIS'!
LIS'!
LIS'!
LIST
LIST
LIST
LIST
LIS'!
LIS'I

TAKEN MAP REt
IJFFBZZN
AUTOLINK
AUTOLINK
ILBDDSPO
AUTOLINK
IJJCPDV
AUTOLINK
ILBDDSSO
INCLUDE IJJCPDV
AUTOLINK
ILBDIMLO
ILBDMNSO
AUTOLINK
ILBDSAEO
AUTOLINK
ENTRY

10/02/73

PHASE

XFR-AD

LOCORE

HICORE

DSK-AD

ESD TYPE

LABEL

LOADED

REL-FR

PHASE···

07D878

07F1FF

05F OF 4

CSECT

TESTRUN

07D878

CSEC'I
ENTRY
* :::NTRY
* ENTRY

IJFFBZZN
IJFFZZZN
IJFFBZZZ
IJFFZZZZ

07E1C8
07E1C8
07E1C8
07E1C8

07:t:.1C8

CSECT
ENTRY

ILBDSAEO
ILBDSAEl

07F078
07FOCO

07F018

CSECT

ILBDMNSO

07F010

01F010

CSECT

ILBDIMLO

07F018

CSECT
ENTRY

ILBDDSPO
ILBDDSPl

07E578
01E978

07E578

CSEC'!
ENTRY
ENTRY
ENTRY
ENTRY
ENTRY
ENTRY
ENTRY
ENTRY

II.BDDSSO
ILBDDSSl
ILBDDSS2
ILBDDSS3
ILBDDSS4
ILBDDSSS
ILBDDSS6
ILBDDSS7
ILBDDSS8

07ECFO
07EFSO
07EF48
07FOO8
07ED16
07EDC2
07EE22
07EDEC
07ED46

07ECFO

CSECT
ENTRY
ENTRY

IJJCPDV
IJJCrCn
IJJCPDV2

07EAA8
07EAAS
07EAA8

o 71:.AA8

WXTRN
WXTRN

STXITPSW
ILBDDBG2

• UNREFERENCED SYMBOLS
002

276

Il~PUT

UNR~SOLVED

ADDRESS CONSTANTS

RELOCATAEL£

10/02/73

IBM DOS VS COBOL

// ASSGN
// hX£.C
WCRK-R~COKD

WORK-RECORD
WORK-RECORD
WCRK-RECORD
WORK-HECORD
WCRK-RECORD
WORK-RECORD
WCRK-RECCRD
WORK-RECORD
WCRK-RECORD
WORK-RECORD
WORK-RECORD
WCRK-RECORD
WORK-RECORD
WORK-RECORD
WORK-RECORD
WORK-RECORD
WORK-RECORD
WORK-RECORD
WCRK-RECORD
WORK-RECORD
WORK-RECORD
WORK-RECORD
WCRK-RECORD
WORK-RECORD
WORK-RECORD

REL 1.0

PP NO. 5746-CBl

08.17.32

10/02/73

SYS008,X'483'

A 0001
B 0002
C 0003
D 0004
E 0005
F 0006
G 0007
H 0008
I 0009
J 0010
K 0011
L 0012
M 0013
N 0014
0 0015
P 0016
Q 0017
R 0018
S 0019
T 0020
U 0021
V 0022
W 0023
X 0024
Y 0025
Z 0026

NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC
NYC

1
2
3
4
Z

1
2
3

4
Z

1
2
3

4
Z

ECJ SAMPLE

BG
BG
BG
BG
BG
BG
BG
BG
BG
BG
BG

A 0001 NYC 0
B 0002 NYC 1
C 0003 NYC 2
D 0004 NYC 3
E 0005 NYC 4
F 0006 NYC 0
G 0007 NYC 1
H 0008 NYC 2
I 0009 NYC 3
J 0010 NYC 4
0011 NYC
K
BG
BG L 0012 NYC 1
BG M 0013 NYC 2
BG N 0014 NYC 3
BG 0 0015 NYC 4
BG P 0016 NYC 0
BG Q 0017 NYC 1
BG R 0018 NYC 2
BG S 0019 NYC 3
BG T 0020 NYC 4
BG U 0021 NYC 0
6G V 0022 NYC 1
BG W 0023 NYC 2
BG X 0024 NYC 3
BG Y 0025 NYC 4
BG Z 0026 NYC 0
BG EOJ SAMPLE
00.56.19,DURATION 00.03.42

Appendix A:

sample Program Output

277

APPENDIX B:

STANDARD TAPE FILE LABELS

File
'lelel

&.aIIe1
NulnMr

Label
Wentifler

V."ion

Fil.

Nuntber'"

See."i"

Getwation

The standard tape file label format and contents are as follows:

Field

Name and Length

Description

LABEL IDENTIFIER
3 bytes, EBCDIC

Identifies the type of label.
HDR
Header
(beginning of a data file)
EOF
End-of-file (end of a set of data)
EOV
End-of-volume {end of the physical reel}

FILE LABEL NU!BER
1 byte, EBCDIC

Always a 1.

FILE IDENTIFIER
17 bytes, EBCDIC

Uniquely identifies the entire file, may contain
only printable characters. Some other systems
will not accept embedded blanks in the file
identifier. -

FILE SERIAL NUMBER
6 bytes, EBCDIC

Uniquely identifies a file/volume relationship.
This field is identical to the volume serial
number in the volume label of the first or only
volume of a multivolume file or a multifile set.
This field will normally be numeric (000001 to
999999), but may contain any six alphanumeric
characters.

VOLU!E SEQUENCE
NU!BER
4 bytes

Indicates the order of a volume in a given file or
multifile set. The first must be numbered 0001,
and subsequent numbers must be in proper numeric
sequence.

FIL~

SEQUENCE
4 bytes

Assigns numeric sequence to a file within a multifile set. The first must be numbered 0001.

GENERATION TI!E
4 bytes

Uniquely identifies the various editions of the
file.
Kay be from 0001 to 9999 in proper numeric
sequence.

VERSION NUKBER OF
GENERATION
2 bytes

Indicates the version of a generation of a file.

Appendix B: Standard Tape File Labels

279

Field
9.

Description

Name and Length
CREATION DATE
6 bytes

Indicates the year and the day of the year that the
file was created.
position
1
2-3
4-6

Code
blank
00-99
001-366

Meaning
none
year
day of year

(e.g., January 31, 1973 would be entered as
13031) •

10.

EXPIRATION DATE
6 bytes

Indicates the year and the day of the year when the
file may become a scratch tape. The format of
this field is identical to field 9. On a
multifile reel processed sequentially, all files
are considered to expire on the same day.

11.

FILE SECURITY
1 byte

Indicates security status of the file.

No security protection.

Security protection. Additional
identification of the file is required before
i t can be processed.

12.

BLOCK COUNT
6 bytes

Indicates the number of data blocks written in the
file from the last header label to the first
trailer label, exclusive of tapemarks. Count
does not include checkpoint records. This field
is used in trailer labels.

13.

SYSTEM CODE
13 bytes

Uniquely identifies the operating system.

14.

RESERVED
7 bytes

Reserved.

280

Should be recorded as blanks.

APPENDIX C:

STANDARD MASS STORAGE DEVICE LABELS

Format

Format 1:

Field
1.

This format is cOlltllon't-oal1data files on disk.

Name and Length
FILE NAME
44 bytes, alphanumeric EBCDIC

Description
This field serves as the key portion of the file
label. It can consist of three sections:
1.

Pil~ ID is ari alphanumeric field assigned by
the programmer arid identifies the file. It
can be 1 through 35 bytes in length if
generation and version numbers are used, or
through 44 bttes in length if they are not
used.

Generation Number. If used, this field is
separated from File ID by a period. It has
the format Gnnnn, where G identifies the
field as the generation number and nnnn (in
decimal) identifies the generation of the
file.

Version Number of Generation. If used, this
sectio-n imllediately follows the generation
number and has the format Vnn, where V
identifies the field as the version of
generation number and nn (in decimal)
identifies the version of generation of the
file.

IBM DOS/VS System compares the entire field
against the filename given in the DLBL card. The
generation and version numbers are treated
differently by the IBM OSjVS System.

Appendix C: Standard Mass Storage Device Labels

281

Fields 2 through 33 constitute the DATA portion of the file label.
Fiel~

Name and Length

Descrinion

FORMAT IDENTIFIER
1 byte, EBCDIC numeric

FILE SERIAL NUMBER
6 bytes, alphanumeric EBCDIC

Uniquely identifies a file/volume relationship. It
is identical to the volume serial number of the
first or only volume of a multivolume file.

VOLUME SEQUENCE NUMBER
2 bytes, binary

Indicates the order of a volume relative to the
first volume on which the data file resides.

CREATION DATE
3 bytes, discontinuous binary

Indicates the year and the day of the year the file
was created. It is of the form YDD, where Y
signifies the year (0-99) and DD the day of the
year (1-366).

EXPIRATION DATE
3 bytes, discontinuous binary

Indicates the year and the day of the year the file
may be deleted. The form of this field is
identical to that of field 5.

7a.

EXTENT COUNT
1 byte, binary

Contains a count of the number of extents for this
file on this volume. If user labels are used,
the count includes the user label track as a
separate extent. This field is maintained by the
Disk Operating system.

7b.

BYTES USED IN LAST BLOCK
OF DIRECTORY
1 byte, binary

Used by IBM Operating System Virtual Storage only
for partitioned (library structure) data sets.
Not used by the Disk Operating System Virtual
Storage.

7c.

SPARE
1 byte

Reserved for future use.

SYSTEM CODE
13 bytes

Uniquely identifies the operating system.

RESERVED
7 bytes

Reserved for future use.

FILE TYPE
2 bytes

The contents of this field uniquely identify the
type of data file.

10.

format 1

Hex
Code
4000

Meaning
Sequential organization

2000

Direct organization

8000

Indexed organization

0200

Library organization

(,\1'\,,/,\

Organization not defined in the file
label

VVVV

282

Field

Name and Length

11.

RECORD FORMAT
1 byte

Description
The contents of this field indicate the type of
records contained in the file.
Bit
Position
o and 1

5 and 6

12.

OPTION CODES
1 byte

Content
01

Meaning
Variable-length records

Fixed-length records

Undefined format

No track overflow

File is organized using track
overflow (IBM OSjVS only)

Unblocked records

Blocked records

No truncated records

Truncated records in file

Control character ASA code

Control character machine code

Control character not stated

Records are written without
keys

Records are written with keys

Bits within this field are used to indicate various
options used in building.the file.
~~
B ..L.\..

Position

~ning

If on, indicates data file was created
using write validity check.

1-7

Unused.

13.

BLOCK LENGTH
2 bytes, binary

Indicates the block length for fixed-length
records, or maximum block size for variablelength blocks.

14.

RECORD LENGTH
2 bytes, binary

Indicates the record length for fixed-length
records, or the maximum record length for
variable-length records.

15.

KEY LENGTH
1 byte, binary

Indicates the length of the key portion of the data
records in the file.

16.

KEY LOCATION
2 bytes, binary

Indicates the high-order position of the data
record.

Appendix C: Standard Mass storage Device Labels

283

!iel~

Name and Length

17.

DATA SET INDICATORS
1 byte

Description
Bits within this field are used to indicate the
following:
Bit
position
--0--

Meaning
If on, indicates that this is the last
volume on which this file normally
resides. This bit is used by the
DOS/VS DTFSR routine only. None of
the other bits in this byte are used
by the DOS/VS.

If on, indicates that the data set
described by this file must remain
in the same absolute location on the
direct-access device.

If on, indicates that block length
must always be a multiple of eight
bytes.

If on, indicates that this data file
is security protected; a password
must be provided in order to ac~ess
it.

4-7

Space.

Reserved for future use.

18.

SECONDARY ALLOCATION
4 bytes, binary

Indicates the amount of storage to be requested for
this data file at end-ot-extent. This field is
used by IBM OS/VS only. It is not used by DOS/VS
routines.

19.

LAST USED TRACK AND
RECORD ON THAT TRACK
5 bytes, discontinuous binary

Indicates the last occupied track in a consecutive
file organization data file. This field has the
format CCHHR. It is all binary zeros if the last
track in a consecutive data file is not on this
volume, or if it is not consecutive organization.

20.

AMOUNT OF SPACE REMAINING ON
LAST TRACK USED
2 bytes, binary

A count of the number of bytes of available space
remaining on the last track used by this data
file on this volume.

21.

EXTENT TYPE INDICATOR
1 byte

Indicates the type of extent with which the
following fields are associated:
Hex
Code

284

Meaning
Next three fields do not indicate any
extent.

Prime area (indexed) or consecutive
area, etc., (i.e., the extent
containing the user's data records).

Overflow area of an indexed file.

Cylinder index or master index area of
an indexed file.

User label track area.

Shared cylinder indicator.

Description

Fiel~

Name and Length

22.

EXTENT SEQUENCE NUMBEh
1 byte, binary

Indicates the extent sequence in a multi-extent
file.

23.

LOWER LIMIT
4 bytes, discontinuous binary

The cylinder and the track address specifying the
starting point (lower limit) of this extent
component. This field has the format CCHH.

24.

UPPER LIMIT
4 bytes

The cylinder and the track address specifying the
end point (upper limit) of this extent component.
This field has the format CCHH.

25-28. ADDITIONAL EXTENT
10 bytes

These fields have the same format as the fields
21 through 24, above.

29-32. ADDITIONAL EXTENT
10 bytes

These fields have the same format as fields 21
through 24, above.

33.

POINTER TO NEXT FILE LABEL
WITHIN THIS LABEL SET
5 bytes, discontinuous binary

The disk address (format CCHHR) of a continuation
label is needed to further describe the file. If
field 9 indicates indexed organization, this
field will point to a Format 2 file label within
this label set. Otherwise, it points to a Format
3 file label, and then only if the file contains
more than three extent segments. If no
additional file label is pointed to, this field
contains all binary zeros.

Appendix C: Standard Mass Storage Device Labels

285

APPENDIX D:

TRACK FORMATS FOR DIRECT-ACCESS STORAGE DEVICES

The track format for the 2311, 2314,
2319, 2321, 3330, 3340, and 3350 directaccess storage devices is illustrated in
Figure 67. The names of the fields are
given in the following discussion.

portion for direct and indexed
organizations.

Index Marker: All tracks start with an
index marker. It is a signal to the
hardware that indicates beginning of the
track.

Count Portion. The count portion
contains the identification of each
record, the key length, and the data
length.
a.

Identification. Each record is
identified with its cylinder
number, head number, or record
number. The cylinder and head
numbers will be the same as those
of the home address.
The record
number will indicate a particular
record on the track. That is, the
first record after record 0 will
be record 1, followed by record 2,
etc. This 5-byte binary field in
the form of CCHHR is often
referred to as the record ID.

Key Length. The key length is
specified in an 8-bit byte; its
length can range from 0 to 255.
This field will contain a zero if
there is no key.

Data Length. The data length is
specified in the 16 bits of the
next two bytes.

Home Address: The home address, preceded
by a gap, follows the index marker. The
home address uniquely identifies each track
by specifying the cylinder and head number.
Track Descriptor Record (Reco~: Record
o consists of two parts: a count portion
and a data portion. The ~1-EQrtion is
the same as it is for any other record (see
the following description of count for
record 1. The 8-byte data portion is used
to record information used by LIOCS. The
information in the data portion depends on
the data organization (direct or indexed)
that is being used.
For direct organization, this portion in
the form of CCHHR contains the address of
the last record on the track and the number
of bytes remaining on the track. This
information is used to determine whether
there is space for another record on the
track. For indexed organization, the data
portion contains the address of the last
record in the cylinder overflow area and
the number of tracks remaining in the
cylinder overflow area. Record 0 is then
used as the cylinder overflow control
record.
Address Marker: All records after record 0
will be preceded by a 2-byte address
marker. The address marker is a signal to
the hardware that a record is starting.
Data Records: Data records can consist of
a count and data portion for sequential
organization, or a count, key, and data

Appendix D:

Note: It is the count portion
that identifies the presence or
absence of a key, in addition to
indicating the data length. In
this way, each record is unique
and self formatting.
2.

Key Portion. The key portion of the
record is normally used to store the
control field of the data record such
as a man number. Direct and indexed
files must have a key portion.

Data Portion. The data portion of the
record contains the data record.

Track Formats for Direct-Access storage Devices

287

Note that all records, including tne
data record, terminate with a 2-byte cyclic
check. The hardware uses this cyclic check
to ensure that is correctly reread what it
had written. The cyclic check is
cumulative and is appended to each record
when it is written. Upon reading the
record, the cyclic check is again
accumulated and then compared with the
appended cyclic check. If they do not
agree, a data check is initiated.

becomes defective, a utility program may be
used to transfer the data to an alternate
track.
(Cylinders 200 through 202 are
reserved for alternate tracks on the 2321.
Strips 6 through 9 of subcell 19 of each
cell are reserved for alternate tracks on
the 2321.)
In this case, a flag bit within
the byte is set Qrr to indicate that this is
a defective track and the address of an
alternate track will be placed in the
record ID of record O. Subsequent
references to this defective track will
result in the Supervisor accessing record 0
for the address of the alternate track.

The first byte of the count portion of
each record and the home address is
reserved for a flag byte. If a track

First Data
Record

I
G
A

P
Record
Number

Cylinder
Number

Dato
length

~
Key

o
o

o Original}
1 Alternate

G
I

I~III

Fie, C I H ! H I R ,Kl,DL, Dl! c! c

Flag

Figure 67.

288

Record
10

Key
Dolo
Cyclic
Length Length Check

Track Format

~~!c!c,

By;e. Remaining
Alter "Initialize Di.k"

Optional
Variable
Length

Data

Variable
Length

APPENDIX E:

The IBM DOS/VS COBOL Object-Time
Subroutine Library, Program Number
5746-LM4, is packaged with the DOS/vS COBOL
Compiler and also available as a separate
product.
It provides subroutines to be
link edited with object modules produced by
DOS/VS COBOL Compiler.
It also provides
subroutines that can be dynamically fetched
during problem program execution.

There are several major categories of
COBOL library subroutines:
• Input/output verb routines
• ASCII support routines
~

COBOL LIBRARY SUBROUTINES

Printer Spacing
The ILBDSPAO subroutine is used to
control printer spacing when the WRITE
statement with the BEFORE/AFTER ADVANCING
or POSITIONING option is specified in the
source program.

Tape and Sequential Disk Labels
The ILBDUSLO and ILBDNSLO subroutines
are used when user or nonstandard labels,
respectively, are to be processed (LABEL
RECORDS ARE data-name).

Conversion routines

• Arithmetic verb routines
CLOSE WITH LOCK Subroutine
• Sort/Merge Feature interface routines
• Checkpoint (RERUN) routines
• Segmentation Feature routines
• Other verb routines
• Object-time debugging routines

The ILBDCLKO subroutine is given control
on an OPEN if the file is ever closed with
lock in the program. It checks whether the
OPEN statement is used to open a file
previously closed with lock.
If the file
was previously closed with lock, it issues
an object-time message and terminates the
current job.

• Object-time execution statistics
routines
• Optimizer routines

WRITE Statement Subroutines

• Transient routines
The ILBDVBLO subroutine is used to write
variable-length blocked records.
The following sections describe some of
the more commonly used subroutines.

The ILBDDIOO stibroutine is used for
writing files with direct organization
(DTFDA).
The ILBDISMO subroutine is used for
writing files with indexed organizatio~.

INPUT/OUTPUT SUBROUTINES
READ Statement Subroutines
The input/output subroutines are used
for the COBOL verbs DISPLAY (TRACE and
EXHIBIT), ACCEPT, STOP (literal), READ,
WRITE, REWRITE, OPEN, CLOSE, DELETE, and
START printer spacing, printer overflow,
input/output errors, disk formatting and
extent handling, and tape and sequential
disk labels.

The ILBDDSRO subroutine is used to read
sequentially the records of a directly
organized file.
The ILBDDIOO subroutine is used to read
randomly the records of a directly
organized file.
Appendix E: COBOL Library Subroutines

289

The ILBDISMO subroutine is used to read
an indexed file.

Input/Output Error Subroutines

REWRITE Statement Subroutines

The ILBDSAEO subroutine is used for
processing input/output errors that occur
on tape and sequential disk.

The ILBDDIOO subroutine is used to
update records on a directly organized
file.

The ILBDDAEO subroutine is used for
processing input/output errors that occur
on directly organized files.

The ILBDISMO subroutine is used to
update an indexed file.

The ILBDISEO subroutine is called
whenever an input/output error occurs
during the processing an indexed file.

DISPLAY (EXHIBIT and TRACE) Subroutines

The ILBDABXO subroutine is used to issue
a STXIT macro instruction causing control
to be passed to i t if there is an error on
a unit-record device.

The ILBDDSPO subroutine formats one or
more operands into printed lines,
performing conversions as needed.
The ILBDOSYO and ILBDASYO subroutines
open SYSLST and/or SYSPCH and/or SYSIPT if
there are DISPLAY or ACCEPT statements in a
label declarative.
ACCEPT and STOP (literal) Statement
Subroutines
The ILBDACPO subroutine is used to
handle ACCEPT statements for both SYSIPT
and the console, as well as the STOP
(literal) statement.
The ILBDACPO
subroutine does not format or convert
operands.
For operands greater than 80
characters in length, any remainder in
excess of the nearest multiple of 80 is
ignored when accepting data from SYSIPT.

Disk Extent Subroutines
The ILBDFMTO subroutine writes record 0
(RO) on each track of each extent of a
directly organized file opened as output,
and writes an end-of-file (EOF) record as
the last record in the file.
This
subroutine is called after the file has
been opened.
The ILBDXTNO subroutine stores for
subsequent use the extent information for
directly organized files.

3886 OCR Subroutine

CLOSE Subroutine
The ILBDCRDO subroutine is given control
when a CLOSE UNIT statement is issued for a
sequential input file with direct
organization.

The ILBDOCRO subroutine is used to
perform I/O operations for the 3886 Optical
Character Reader.

VSAM Subroutines
Multiple File Tape Subroutine
The ILBDMFTO subroutine is given control
when a reel contains more than one file and
there are no standard labels.
Tape Pointer Subroutine
The ILBDIMLO subroutine locates the
pointer to the physical tape drive
associated with the logical unit for a
particular tape file.

290

The ILBDINTO subroutine does
initialization for VSAM processing.
The ILBDVOCO performs VSAM open ahd
close functions.
The ILBDVIOO performs all action
requests for VSAM files (for example, READ,
WRITE, REWRITE, S~ARTr DELETE).
These routines may call the Checkpoint
subroutine and $$BCOBRl discussed later in
this chapter.

Auxiliary Subroutines

output) and three internal (for internal
processing) •

Certain input/output subroutines use
auxiliary subroutines as follows:
The five external formats are:
Auxiliary
Routine
ILBDMOVO
ILBDIDAO
ILBDTABO

Used By
ILBDSPAO, ILBDNSLO,
ILBDVBLO
ILBDFMTO, ILBDDSRO
ILBDDIOO, ILBDIDAO,
ILBDCKPO

• External or zoned decimal
• External floating-point
• Sterling display

ASCII SUPPORT SUBROUTINES
• Numeric edited
The subroutine described below handles
functions necessary for files written in
ASCII. Other functions are handled by code
gene~ated by the compiler or by the
subroutine ILBDSPAO.

• Sterling report

The three internal formats are:
Separately Signed Numeric Subroutine
• Internal or packed decimal
The ILBDSSNO subroutine is called to
check the validity of signs described as
TRAILING SEPARATE CHARACTER or LEADING
SEPARATE CHARACTER.

CONVERSION SUBROUTINES
Eight numeric data formats are permitted
in COBOL: five external (for input and

• Binary
• Internal floating-point
The conversions from internal decimal to
external decimal, from external decimal to
internal decimal, and from internal decimal
to numeric edited are performed in-line.
The other conversions are performed by the
COBOL library subroutines shown in Table
35.

Appendix E: COBOL Library Subroutines

291

Table 35.

Functions of COBOL Library Conversion Subroutines
Conversion

Subroutine Name
and Entry Points

From

ILBDEFL2

External floating-point

Internal decimal

ILBDEFL1

External floating-point

Binary

ILBDEFLO

External floating-point

Internal floating-point

ILBDBIDOI

Binary

Internal decimal

Binary

External decimal

Binary

Internal floating-point

Binary

External floating-point

ILBDTEF2

Internal decimal

External floating-point

IFBDTEF3

Internal floating-point

External floating-point

ILBDIDBO

Internal decimal

Binary.

ILBDIDB1

External decimal

Binary

ILBDDCI1

Internal decimal

Internal floating-point

ILBDDCIO

External decimal

Internal floating-point

ILBDIFDO

Internal floating-point

Internal decimal

ILBDIPD1

Internal floating-point

External decimal

ILBDIFBl

Internal floating-point

Binary integer and a power
of 10 exponent

ILBDIFB03

Internal floating-point

Binary

ILBDIDRO

Internal decimal

Sterling report

ILBDIDTO

Internal decimal

Sterling non-report

ILBDSTIO

Sterling non-report

Internal decimal

ILBDBID11
ILBDBID21
ILBDBIEOI
ILBDBIEll
ILBDBIE21
ILBDBIIOZ
ILBDBII12
ILBDTEF02
ILBDTEF12

ILBDIFB2 3

liThe entry points used depend on whether the double-precision number is in registers 0
I and 1, 2 and 3, or 4 and 5, respectively.
12The entry points are for single-precision binary and double-precision binary,
I respectively.
3
1
, This entry point is used for calls from other COBOL library subroutines.
292

ARITHMETIC VERB SUBROUTINES

SEGMENTATION FEATURE SUBROUTINE

Most arithmetic operations are performed
in-line. However, involved calculations
with very large numbers, such as decimal
multiplication of two 30-digit numbers, are
performed by COBOL library arithmetic
subroutines. These subroutine names and
their functions are shown in Table 36.

The Segmentation Feature requires an
object time subroutine, ILBDSEMO. The
ILBDSEMO subroutine performs the following
functions when segments are needed:
1.

Loads and initializes independent
segments not in storage.

Loads overlayable segments not in
storage.

Initializes independent segments if
the segment is in storage.

Branches to desired entry points.

SORT/MERGE FEATURE INTERFACE ROUTINE
Communication between the Sort/Merge
program and the COBOL program is maintained
by ILBDSRTO and ILBDMRGO.

CHECKPOINT (RERUN) SUBROUTINE

OTHER VERB ROUTINES

The ILBDCKPO subroutine issues the
checkpoint macro instruction, which will
write checkpoint records on a programmerspecified tape or disk checkpoint device.
There are two calling sequences to this
subroutine. The first, ILBDCKP1, is
activated during initialization when the
addresses of all files in the program are
entered in a table. The second, ILBDCKP2,
is required to take checkpoints during a
sorting operation.

There are also COBOL library subroutines
for comparisons, the verbs MOVE and
TRANSFORM, and other features of the COBOL
language.

If RERUN is requested during a sorting
operation, ILBDSRTO must gather a list of
physical IOCS files in use by the Sort
program every time Sort exits at Ell, E21,
and E31. ILBDSRTO then calls the
checkpoint subroutine which will take a
checkpoint of all active files.

Table 36.

Compare Subroutines
The ILBDVCOO subroutine compares two
operands, one or both of which is variable
in lengtha Each may exceed 256 bytes.
The ILBDIVLO subroutine is used in
comparisons involving the figurative
constant ALL 'literal', where literal is
greater than one character.

Functions of COBOL Library Arithmetic Subroutines

r---------------T-----------------------------------------------------------------------,
I Subroutine Name 1
Function
I
~---------------+-----------------------------------------------------------------------~

IILBDXMUO
I Internal decimal multiplication (30 digits * 30 digits = 60 digits)
I
~---------------+-----------------------------------------------------------------------~
JILBDXDIO
I Internal decimal division (60 digits/30 digits = 30 digits)
I
~-~-------------+-----------------------------------------------------------------------1
IILBDXPRO
I Decimal fixed-point exponentiation
I
~---------------+-----------------------------------------------------------------------~
IILBDF"PWO
J Floating-point exponentiation
I
~---------------+-----------------------------------------------------------------------1
iILBDGPW01
i Floating-point exponentiation
!
~---------------~-----------------------------------------------------------------------~
J1The ILBDGPWO entry point is used if the exponent has a PICTURE clause specifying an
J
Il _______________________________________________________________________________________
integer. The ILBDFPWO entry point is used in all other cases.
JI

Appendix E: COBOL Library Subroutines

293

MOVE Subroutines

Main Program or Subprogram Subroutine

The ILBDVMOO subroutine is used when one
or both operands is variable in length and
in-line instructions cannot be generated
(for example, fields overlap, etc). Each
may exceed 256 bytes. The subroutine has
two entry points, depending on the type of
MOVE: ILBDVMOO (left-justified) and
ILBDVM01 (right-justified).

The ILBDMNSO subroutine is a 1-byte
switch tested in the code generated for
EXIT PROGRAM, GOBACK, INIT1, and INIT2e

The ILBDANFO subroutine is used to move
the figurative constant ALL 'literal',
where literal is greater than one
character.
The ILBDANEO subroutine is used to
perform a right-or left-justified
alphanumeric edited move.
The ILBDSMVO subroutine handles moves to
right-justified receiving fields either
greater than 512 bytes in length or
variable in length.

TRANSFORM Subroutine
The ILBDVTRO subroutine transforms
variable-length items using the ILBDTRNO
transform table.

Class Test Subroutine
The ILBDCLSO subroutine is used to
perform class tests for variable-length
items and those fixed-length items longer
than 256 bytes.

The ILBDSETO subroutine must be called
by a non-American National Standard COBOL
program prior to any call to an American
National Standard COBOL program. When
calling ILBDSETO, standard linkage
conventions must be observed; there are no
parameters to be passed. The ILBDSETO
subroutine sets the 1-byte switch
(ILBDMNSO) to X'FF'. This switch is tested
in the American National Standard COBOL
program to determine whether it is a main
or a called program. The name of this
subroutine can be changed to any name
desired by the COBOL user.
OBJECT-TIME DEBUGGING SUBROUTINES
Three options are available for
object-time debugging. These are the
statement number option (STATE), the flow
trace option (FLOW), and the symbolic debug
option (SYMDMP). The subroutines for the
first two options provide debugging
information when a program terminates
abnormally; the subroutines for the third
option provide debugging inforrration either
at abnormal termination or dynamically
during execution of a program. All of the
subroutines are under the control of and
are serviced by the Debug Control
Subroutine (ILBDDBGO). This section
discusses (1) the Debug Control Subroutine,
and (2) the subroutines that are called in
response to each of the three debugging
options.
Debug Control Subroutine

Note: The following tables are placed in
the library for use by the in-line coding
generated by the compiler and the
subroutines called for by both the class
test and TRANSFORM:
ILBDATBO
ILBDETBO
ILBDITBO
ILBDUTBO
ILBDWTBO

Alphabetic class test
External decimal class test
Internal decimal class test
Unsigned internal decimal
Unsigned external decimal

SEARCH Subroutine
The ILBDSCHO subroutine processes each
search argument key according to type.
294

The ILBDDBGO subroutine is included in
the load module whenever the CBL control
card for a program contains at least one of
the debugging options, or when the CBL
control card for a program requests
execution statistics.
Statement Number Subroutine
The ILBDSTNO subroutine provides the
number of the statement and the number of
the verb being executed when abnormal
termination occurs.· If abnormal
termination occurs during execution of an
instruction outside of the COBOL program,
the statement number that is provided is
that of the last COBOL instruction
executed.

Flow Trace Subroutine
Space is allocated at compile time for a
flow trace table using the programmerspecified number in the FLOW option of the
CBL card.
(If FLOW=O was specified for a
subprogram, no space is allocated; rather
the subprogram shares the table space
reserved by that program preceding it in
the calling sequence for which a FLOW
specification was made.)
Each time the flow trace subroutine
ILBDFLWO receives control from the COBOL
program, it inserts the executing program's
identification as well as the card number
of the current procedure into the next
available position in the table. When the
end of the table is reached. subsequent
entries overlay the first set of entries.
The procedure is repeated until the end of
the program or until abnormal termination.
If abnormal termination occurs, the
subroutine produces a list of each entry of
the table, beginning with the earliest
entry.

OBJEC'I'-TIME EXECUTION STATISTICS
SUBROUTINES
The object-time execution statistics
subroutines enable the printing of
execution statistics when a program
terminates normally (via STOP RUN or GOBACK
in the main program) and when a program
terminates abnormally.
In addition, when
COUNT is requested, the debug control
subroutine (described above) is also
included in the load module.

COUNT Initialization Subroutine
The ILBDTCOO subroutine is called from
the debug control subroutine to get space
for an initialize the table and chains
which service the COUNT options.

COUNT Frequency Subroutine
The ILBDCT10 subroutine maintains the
execution frequency statistics.
Symbolic Debug Subroutines
The symbolic debug subroutines provide a
formatted symbolic dump, either dynamically
at execution time, or at abnormal
termination.
The following subroutines perform
initialization and precess debug control
cards:
ILBDMP1C, ILBDMPll, ILBDMP12, ILBDMP13,
ILBDMP14, and either ILBDMPOl or
ILBDMP02.
To provide a dump at abnormal
termination, the following subroutines are
used:
ILBDMP20, ILBDMP21, ILBDMP22, ILBDMP23,
ILBDMP24, ILBDMP25 an,j ILBDMPOl or
ILBDMP02. These subroutines are not
included in the load module at link edit
time; they are loaded dynamically during
program execution.
The ILBDADRO subroutine tests the
validity of an address calculated for a
subscripted identifier or the validity of
the starting and ending addresses of a
variable-length identifier used as the
receiving field in a MOVE statement.

COUNT Termination Subroutine
The ILBDTC20 subroutine is included in
all COBOL load modules.
It determines if
execution frequency statistics were
requested.

COUNT Print Subroutine
The ILBDTC30 subroutine formats and
prints the execution frequency statistics.

OPTIMIZER SUBROUTINES
GO TO •••

DEPENDING ON Subroutine

The ILBDGDOO subroutine is called only
when the optimization option (OPT) has been
specified.
It is used to more efficiently
process GO TO statements with the DEPENDING
ON option in both segmented and
nonsegmented programs.
Appendix E: COBOL Library Subroutines

295

Optimizer DISPLAY Subroutine

Error Message Subroutine

The ILBDDSSO subroutine is used to print
or type certain data types on SYSLST or the
console, respectively.

The $$BCOBER subroutine prepares
input/output error messages.

ErrOr Message·Print Subroutine
TRANSIENT SUBROUTINES
The IBM DOS/vS COBOL Object-Time
Subroutine Library includes routines that
are dynamically fetched during program
execution. These routines are as follows:

The $$BCOBRl subroutine prints the error
messages prepared by $$BCOBER and provides
a dump if the DUMP option is in effect.

Reposition Tape Subroutine
Symbolic Debug Subroutines
with the exception of ILBDDBGO, the
symbolic debug subroutines described
previously are transient routines.

SYMDMP Error Message Subroutine
The $$BCOBEM subroutine prepares SYMDMP
error messages.

296

The $$BFCMUL subroutine resets the PUB
pointer for a particular (SYSnnn) device to
the same as that saved earlier by the
gubroutil'leILBDIMLO.
If dynamically fetched subroutines
are required during problem program
execution. the Subroutine Library must be
installej on the object machine. If
dynamically fetched subroutines are not
required during problem program execution,
the object-time subroutines can be link
edit~d on the source machine; the
Subroutine Library must in this case be
installed on the source machine.

APPENDIX F:

This appendix contains information
concerning system and size requirements for
the DOS/VS COBOL compiler, execution time
considerations, and the Sort/Merge Feature.
Additional information used in estimating
the virtual and auxiliary storage
requirements is contained in the
publication IBM DOS/VS COBOL Compiler and
Library, Installation Reference Material.

MINIMUM MACHINE REQUIREMENTS FOR THE
COMPILER
1.

A System/370 supported by DOS/VS.
A minimum of 60K bytes of virtual
storage is required.
Five work files. The system logical
unit SYSLNK must be assigned to a
single area (extent) on a 2314, 2319,
3330, 3340, 3350, or fixed block mass
storage device. Four programmer logical
units (SYS001 through SYS004) must
reside on 2400, 3410, 3420 tape units,
or on 2314, 2319, 3330, 3340, 3350, or
fixed block mass storage devices. At
least one programmer logical unit as
well as the operating system must
reside on a mass storage device (that
is, a 2311, 2314, 2319, 3330, 3340,
3350, or fixed block mass storage
device). If the three remaininq
logical units reside on tape, there
must be a separate tape unit for each
file. If they reside on mass storage
devices, there must be enough space
on those devices. An additional logical
unit, SYS005, must be assigned if the
symbolic debug option (SYMDMP) is
being used. Logical unit SYS006 must
be assigned for the FIPS flagger.
Work file assignments must be made as
follows:
SYSLNK
SYS001
SYSOO2

SYSOO3

SYSOO4

SYSOO5

SYSOO6

mass
mass
mass
unit
mass
unit
mass
unit
mass
unit
mass

storage device
storage device
storage device or tape
storage device or tape

SYSTEM AND SIZE CONSIDERATIONS

The filenames for SYSLNK and SYS001
through SYS006 on the TLBL or DLBL
statements are IJSYSLN, IJSYS01~
IJSYS02, IJSYS03, IJSYS04, IJSYS05,
and IJSYS06, respectively.
If the
"filename" parameter of the SYlI.DMP
option is specified, this filename is
used instead of IJSYS05 on DLBL
statements.
3.

A device, such as a printer keyboard,
for direct operator communication.

A device, such as a card reader, for
the job input stream.

A device, such as a printer or tape
unit, for system output files.

The floating-point arithmetic feature,
if floating-point literals or
calculations are used.

SOURCE PROGRAM SIZE CONSIDERATIONS
Compiler Capacity
This section contains information which
must be considered in determining the
limitations on the size of a COBOL source
program in a specific virtual storage size.
It also contains information to aid the
programmer in determining how his source
program affects usage of space at
compilation time.
The capacity of the COBOL compiler is
limited by two general conditions:
(1) the
total table requirement may be greater than
the space available and (2) the fact that
an individual table (with the exception of
the ADCON and cross-reference tables) nlay
need to be longer than 32,767 bytes.
If
either of these conditions are met during
compilation, one of the following error
messages will be issued:
ILA0001I-D NO MORE TABLE SPACE
AVAILABLE.
COMPILATION
ABANDONED.

storage device or tape
storage device or tape

ILA0003I-D A TABLE HAS EXCEEDED THE
~illXIMUM SIZE.
COMPILATION
ABANDONED.

storage devi-::e unit

Note that SYSLNK need only be assigned
at compile time if the CATAL or LINK
option is in effect.

ILA6007I-D TABLE HAS EXCEEDED MAXIMUM
SIZE. LISTX, OBJECT MODULE,
AND DECK WILL BE INCOMPLETE.
INCREASE PARTITION.

Appendix F:

System and Size considerations

297

In each case, compilation is terminated.
However, in the first and third cases, or
in the case of overflow of the ADCON or
cross-reference table, the program may be
recompiled with a larger size parameter.

10 files, assuming an average of 3
subordinate record entries

Effective Storage Considerations
The compiler will accept and compile a 1500
card program in the minimum storage of 64K.
In this configuration, the minimum size
compiler input/output areas must be
allocated.
If both LINK and DECK are
specified, more storage is required for
buffer space, which reduces the space
available to a given program. Within this
configuration, the compiler will accept
programs much larger than 1500 cards; the
specific size limitation for any storage
size depends entirely on the statement mix
in that program, but the limiting factors
are described in the next section.
The overall critical limit using the
minimum buffer specification may be
expressed as follows:
2 (number of pn's + gn's + literals +
virtuals) + 8A + S (L + 5D + 8V + 3P)
14336 + C

where the number of virtuals is the number
of calls to COBOL object-time subroutine
entry points and subprograms specified in a
CALL statement, and V is the number of
unique such names; also
A

= number

of entries in
as defined below .

~he

ADCON table

1 if the segmentation Feature is
required and NOOPT is in effect;
otherwise 0

length of optimized literals

number of segment discontiguities in
the Procedure Division

number of PERFORM exits and altered
GO TO statements

any storage over 64K assigned to the

The performance of the compiler is
affected by the amount of storage it is
allocated. The compiler will take
advantage of any extra storage it is
assigned.
Furthermore, the use of a BUF
parameter tailored to the work file device
type in use is recommended.
The following
CBL parameters positively affect
compile-time performance:
OPT
SYNTAX (CSYNTAX)
NOLIB
BUF
The amount of virtual storage within the
compiler's partition and the liroitation on
the size of an individual internal table
are two factors that limit the capacity of
the compiler.
The limitation on the size
of internal tables can, in some instances,
be overcome by the spilling over of some
tables onto external devices.
However,
spilling over may cause a severe
degradation of performance. The storage
limitation should not be reached by any
reasonable use of the language. However,
within a limited storage capacity, excessive
use of certain features and cowbination of
features in the language could make
cOIT.pilation impossible.
Some of the
features that significantly affect storage
usage are:
1.

ADCON Table
Each entry occupies 8 bytes. This
table is not limited to the maximum
size of 32,767 bytes. Entries are
based on:
• Number of 4096-byte segroents in the
Working-Storage section

progr~m

It should be noted that the number of gn's
is reduced when using OPT.

• Number of 4096-byte segments in a
file buffer area
• Number of referenced procedure-names

Within this configuration, assuming no
Report Section, the compiler will accept
for example:
300 procedure references assuming an
average procedure-name length of 12
characters
25 OCCURS clauses with the DEPENDING ON
option

• Number of implicit procedure-name
references such as those generated
by IF, SEARCH, and GENERATE
statements, ON SIZE ERROR, I~~ALID
KEY, and AT END options, the OCCURS
clause with the DEPENDING ON option,
USE sentences, and the Segmentation
Feature
•

298

Number of files

The size of this table is
significantly reduced when using OPT.
2.

data item. Some of the features that
contribute to the value Q are:
• One byte for each character in a
numeric edited or alphanumeric
edited item PICTURE clause.

Procedure-Name Table
This table contains the number of
definitions written in a section and
unresolved procedure references.
Procedure references are resolved at
the end of a section if the definition
of the procedure-name is in that
section or a preceding section.
Therefore, forward references beyond a
section impact space.

• Three bytes for an item
subordinate to an OCCURS clause.
In the statistics output, an
indication is given if spill of
this table occurred.
If spill
occurred, increasing the partition
size assigned to the compiler
should increase performance.

OCCURS DEPENDING ON Table
This table contains an entry for each
unique object of an OCCURS clause with
the DEPENDING ON option. The size of
an entry is (2 + length of name +
length of each qualifier) bytes.

• Five bytes for an elementary item
with a sterling report PICTURE
clause.

The total length of all literals
(after optimization) may not exceed
32511 bytes. No more than 16255
literals may be specified.

Index Table
An entry is made for each INDEXED BY
clause consisting of 11 bytes for each
index.

If the segmentation feature is used,
an area corresponding to the total
length of all optimized literals must
be kept free during the time the ADCON
table is being built. Therefore, a
segmented pro~ram with literals may
need more storage.

File Table
An entry is made for each file
specified in the program. Each entry
occupies 60 bytes of storage.

10.

Report Writer Tables
A considerable amount of information
is maintained concerning each RD such
as controls, sums, headings, footings,
routines to be generated, etc. The
contents of the table is increased by
the existence of qualification and
subscripting in the Report Section.
Approximately 30 reports can be
processed, without exceeding the limit
of a table.

Literal Tables

Miscellaneous Tables
The existence of the following items
causes entries to be made into tables
and impacts the total space required
for compilationo
•
•
•
•
•
•
•
•
•
•
•
•

Operand Table
Entries are made depending on the
number of operands in a statement.
This table could reach its limits by
the use of compound nested IF
statements or GO TO DEPENDING ON
statements with an excessive number of
branch points.

SAME (RECORD) AREA clause
Subscripting
Intermediate Arithmetic Results
Complex Arithmetic Expressions
Complex Logical Expressions
APPLY clauses
Special-Names
RERUN clauses
Error messages
XREF
Segmentation feature
VERBSUYvVERBREF

EXECUTION TItJJE CONSIDERATIONS
8.

Dictionary Table
An entry is made for each
procedure-name and each data-name in
the program. A procedure entry
consists of (7 or 9 + length of name)
bytes. A data entry consists of
(length of name + n) bytes, where Q is
determined by the attributes of the

The amount of virtual storage must be
sufficient to accomodate at least:
• The selected control prograITI
• Support for the file processing
techniques used

Appendix F:

System and Size considerations

299

• Load module to be executed
• Dynamic storage for VSAM, 3886
processing, and COUNT.
When the OPTIMIZE option is specified,
the number of procedure blocks in the
program cannot exceed 255. A procedure
block is approximately 4096 bytes of
Procedure Division code.
COBOL programs compiled with any of the
symbolic debugging options (STATE, FLOW,
SYMDMP) have different requirements at
execution time than similar programs
compiled without these options. The"
following differences should be noted:
• If the SYMDMP option is in effect, the
work file required at compile time
(SYS005) must be present at execution
time.
• The size of the load module will
increase by about 3200 bytes if the
SYMDMP option is in effect.
In
addition, since the object-time
subroutine that provides SYMDMP output
is invoked dynamically, the programmer
must provide space in the partition
amounting to S + V. When only an
abnormal termination dump is required,
S = 4000 and V = 0; that is, 4000 extra
bytes must be available. When dynamic
dumps are required, S = 11,000 and V is
approximately 25 * number of linecontrol cards + 10 * the number of
identifiers specified on these linecontrol cards.
• The size of the load module will
increase by 4500 + V bytes if the FLOW
option is in effect. V is a variable
factor that depends upon the number
specified by the programmer on the CBL
card. V is calculated using the
formula:
V

92 + 4

nn + 8

where "nn" is any number from 0 through
99, and "pH is the number of
procedure-names in the program.

• A SIZE parameter must be specified on
the EXEC card for VSAM and 3886
processing and if COUNT is requested on
the CBL card.
COBOL programs with the execution
frequency option COUNT have the following
additional requirements:
• The size of the load module will
increase by about 6000+V bytes (if any
of the symbolic debugging options are
in effect) to 8900+V bytes (if the
symbolic debugging options are not in
effect).
V is calculated using the
formula:
V=(54 * pgm)+(8*nvb)+C7*npr)+«4+sym) *
vbl)+pnl
where
pgm is the number of COPOL program
units being monitored by COUNT
nvb is the number of verbs in the
program units
npr is the number of procedure-names
plus inserted pror,edure-names in the
program
sym is zero unless SYMDMP is in
effect, then it becomes two
vbl is the number of verb blocks in
the program (which can be estimated
as 1/3 the number of verbs in the
program)
pnl is the sum of the lengths of the
procedure-names.
• The increase in dynamic storage in
estimated using the formula
D = 512+(72*pgm)+(4 * vbl)
where
pgm is the number of COBOL programs
being monitored by COUNT
vbl is the number of verb blocks in
the program (which can be estimated
as 1/3 the number of verbs in the
program).

• The size of the load module will
increase by 4600 + V bytes when the
STATE option is in effect. V is
approximately 5 * the number of COBOL
statements in the program.

MULTIPROGRAMMING CONSIDERATIONS

• When both SYMDMP and FLOW are in
effect, the size of the load module
will increase by the amount it would
for FLOW alone, and the size of the
partition increases by the amount it
would for SYMDMP alone.

In a system which supports the batch-job
foreground (NPARTS = 2 or more) and private
core-image library options, the Linkage
Editor can execute in any foreground
partition (as well as the background

300

partition) provided a mlnlmum of 14K or 64K
of storage is assigned to the partition.
When executing in a foreground partition. a
private core image library must be
assigned.
In the multiprogramming environment
described above. the COBOL compiler can be
executed in any partition having a minimum
of 64 bytes in the following manner:
At system generation time. link edit
the compiler in the background
partition and place it in the system
core image library.

SORT FEATURE CONSIDERATIONS
The DOS/VS SORT/MERGE Program Product.
Program Number 5746-SM1. must be executed
under control of DOS/VS. It requires the
following minimum machine configuration:
1.

Standard instruction set.

At least one 2314, 2319, 3330, 3333,
3340, or 3350 work file.
(System
residence requirements may necessitate
having an additional disk storage unit
for sorting.)

One IBM 1403, 1443, or 3211 Printer,
or one IBM operator communication
device (for example, 3215).

One IBM 1442, 2501, 2520, 2540, 3505,
3525, or 2560 Card Reader, or one IBM
2400 or 3400 Series Magnetic Tape Unit
(7- or 9-track) assigned to SYSIPT and
SYSRDR.

Three IBM 2400 or 3400 Series Magnetic
Tape Units for work files when tape
units are to be used for intermediate
storage.

For specific size. device~ apd work file
requirements of the other Sort/Merge
products, see the respective Programmer's
Guides as noted in the preface.

The DOS/VS SORT/MERGE Program Product
uses 16K bytes; additional storage is
needed for DOS/VS and for user-written
r0utines (that is, the COBOL program,
etc. ) •

Note: If a size parameter is used in the
77EXEC statement, it should be used as
follows:

Note: Performance often increases
significantly if 50K is available for
operation of the Sort/Merge program.
At the lOOK level. the performance
could be even higher.

//EXEC,SIZE= (AUTO ,nK)
where NK has to meet specific Sort
storage requirements.
'

Appendix F:

System and Size Considerations

300.1

APPENDIX G:

PROGRAM COMMUNICATION

Byte(s)

Information

UPSI (user program switch
indicators). Set to binary zero
when the JOB statement for the
job is encountered. Initialized
by UPSI job control statement.

For each partition, the supervisor contains
a storage area called the communication region.
The supervisor uses the communication region,
and your program also can use it. Your
program can check the communication region of
the partition in which your program runs; your
program can also modify the user area of this
communication region.

The condition-name associated
with the status of the UPSI
switches can be specified in the
COBOL program via the
Special-Names paragraph of the
Environment Division. The
condition-name associated with
each may be tested in the
Procedure Division of the COBOL
program.

Figure 68 shows the portion of the corr~unication
region containing information of interest. This
information is also described below.
Byte(s)

Information

0-7

Calendar date. Supplied from system
date whenever the JOB statement is
encountered. The field can be two
forms: mm/dd/yy or dd/mm/yy where
mm is month, dd is day, yy is year.
It can be temporarily overridden by
a DATE statement.

8,9

Address of the problem program area.

10,11

Address of the beginning of the
problem program area.

12-22

User area for communication within
a job step or between job steps.
All 11 bytes are set to z~r.9 wheI1
the '//JOB' JOB control-statement
is encountered.

COMMUNICATION REGION

24-31

Job name as found in the JOB
statement for the job.

32-35

Address of the uppermost byte
of the program area. If the
program was initiated with the
SIZE parameter in the EXEC job
control statement, this address
gives the highest duty of the
area determined by the SIZE
parameter.
If the SIZE parameter was not
specified, the address is the
highest address in the partition
(either real or virtual).
Address of the uppermost byte
of the current phase placed in
the program area by the last
FETCH or LOAD macro in the job.

36-39

Note: The COBOL compiler uses bytes
12 and 13.

}
~

a..

i
0

a':
~

:0
0

a':

§
Q)

a.
a.

:::)

-0"0

-0

-g

c:'"
'0
c:
Q)

....,
In

:c'"

.!«
.0_
".0

Cl. ..

... .J

o E

~~
c: 0
Q)

.Ja..

43 4445
3940
Byt~~r-________~~~~~~____________~~~________~31~32~~3~5~3~6__~~~-=~~LJ

Address of first
byte supplied
in register 1
by COMRG

Figure 68.

Communication Region in the Supervisor
Appendix G:

Communication Region

301

~yte

fs)

Information

40-43

Highest ending virtual storage
address of the phase among all
the phases having the same first
four characters as the operand
on the EXEC statement. For the
background partition only, job
control builds a phase directory
of these phases. The address
may be incorrect if the program
loads any of these phases above
its link-edited origin address
and the relocating loader is not
used. If the EXEC statement has
no operand, job control places
in this location the ending
address of the phase just
link-edited.

44,45

Length of program label area.

The COM-REG special register may be used
to access bytes 12-22 of the communication
region.

302

APPEND1X H:

This appendix illustrates the necessary
job control statements and their sequence
for five typical programs:
i.

Creating a Direct File

Retrieving and Updating a Direct File

Creating an Indexed File

Retrieving and Updating an Indexed
File

Sorting an Unlabeled Tape File

In all five programs the programmer has
requested the following compiler options
through the OPTION control statement:
NODECK -- No punched card output for the
object program is needed.
LINK

specified must be associated with the
device whose number is given in the device
field of system-name.
The DLBL control statememt fora labeled
file on a mass storage device must. contain
the same name as system-name. This is the
name by which the file is known to the
control program.
(The ~ field of
system-name is optional.
If ~ is
omitted, the DLBL statement must. specify
the logical unit (SYSnnn) as the
file-name.)
The code field of the D~BL
statement must co~tespOnd .tothe class and
orqanization fields of ·system.... ~narne as
follows:
DLBL
"code"

I ASSIGN
I
ASSIGN
1 "class"! .. "organization"

--------+-----.;;..;.;..~~+;,..:.;.,.;;.;~~..;;.;;...~-~-'.;..

I DA'or uf

.The object module is to be
linkage edited.

LIST

The COBOL source statements
are to be printed on SYSLST.

LISTX

A Procedure Division map with
global tables, literal pool,
and register assignments is to
be printed on SYSLST.

SYM

A Data Division map is to be
pr~nted on SYSLST.

ERRS

The diagnostic messages of the
COBOL compiler are to be
printed on SYSLST.

The EXEC FCOBOL statement calls for
execution of the FCOBOL compiler.
By using the CBL card, the programmer
indicates that in this source program the
quotation mark (") is used for nonnumeric
literals.
The ASSIGN clause in the COBOL source
program specifies a system-name with the
following fields:
(Non-VSAM)
SYSnnn-class-device-organization[-name]
(VSAM)
SYSnnn[-class] [-device] [-organization]
[-name]
The ASSGN control statement for a file
must specify the same logical unit as the
SYSnnn field of system-name. The ASSGN
statement assigns the logical unit to a
specific hexadecimal address.
The address

SAMPLE JOB DECKS

ISC

ISE

t
r

. . .-

AS (entrysequenced file)
omitted (keysequenced file)

I
I
I
I
I

A or UI' D or

i
I
I
I

Vi]

I
I

If SYSnnn is omitted from the first
EXTENT control statement:· for a' file on a"
mass storage device, then the logical'
unit is determinedfroro the SYSilhnfield
of the COBOL system-name; if SYSnnn is
included in the first EXTENT statement
and differs from SYSnnn of the system....
name, the EXTENT card specification
overrides the COBOL source specification.
(Subsequent EXTENT statements for the
same file, if they immediately follow
the first, may omit this field.)
The
type of the ~xtent must be compatible
with the organization field of systemname as follows:
EXTENT
"type"

I
ASSIGN
I "orgartization"

--T------------------t--------------1 I (data area, no
I S, A, U, I,D,
I split cylinder) I
I
I
I
I
2 I (overflow area fori
I indexed file)
I
I
I
4 I (index area for
I
I indexed file)
I
!
I
8 I (data area, split t
I cylinder)
I
Appendix H:

Vi]

AS
I
I

S, A, U, I,D, W

Sample Job Decks

303

DIRECT FILES
The following two examples illustrate
the job control statements necessary for
programs that create and update a direct
file.
In the COBOL source programs, the
programmer has written:
SELECT DA-FILE ASSIGN TO
SYS015-DA-2311-A-MASTER •••

(Note
relative
required
updating
the file

that in the EXTENT statement, the
track number (1020) is not
for the input DA file of the
program, since the system will use
labels for this information.)

The EXEC statement begins execution of
the problem program, and is followed by
input data.
The /* statements indicate end-of-data,
the /& statement indicates end-of-job.

SELECT CARD-FILE ASSIGN TO
SYS007-UR-2540R-S •••
In the READFILE source program, the
programmer has written:
PRINT-FILE ASSIGN TO
SYS008-UR-2403-S •••

Creating a Direct File

SELEC~

(Note the relationship between the
system-names in the source programs and the
control statements.)

// JOB CREATEDA
// OPTION NODECK,LINK,LIST,LISTX,SYM,ERRS
// EXEC FCOBOL
CBL QUOTE
{COBOL source deck}

The LBLTYP statement defines the amount
of storage to be reserved to process labels
for the DA file.
The file has one extent.
The EXEC LNKEDT statement causes the
object program to be link edited.
An ASSGN control statement assigns
logical unit SYS007 to the hexadecimal
address OOC -- a 2540R Card Reader.

In the updating program, another ASSGN
statement assigns logical unit SYS008 to
the hexadecimal address OOE -- a 1403
Printer.

//
//
//
//
//
//
//

LBLTYP NSD(Ol)
EXEC LNKEDT
ASSGN SYS007,X'00C'
ASSGN SYS015,X'192'
DLBL MASTER,,74/365,DA
EXTENT SYS015,111111,1,0,1020,100
EXEC
{input data cards}

/*
/&

The next series of statements identify
the direct file completely.

Retrieving and Updating a Direct File

The ASSGN statement identifies the file
as residing on logical unit SYS015, which
has the hexadecimal address of 192 -- a
2311 Disk Drive.

// JOB READFILE
// OPTION NODECK,LINK,LIST,LISTX,SYM,ERRS
// EXEC FCOBOL
CBL QUOTE

The DLBL statement specifies the
filename as MASTER, with an expiration date
of the 365th day of 1973, and that the file
has direct organization (DA).

The EXTENT statement specifies that the
file residing on logical unit SYS015 has a
serial number 111111, that the extent is a
data area with no split cylinder and that
this is the first (and only) extent for the
file (type and sequence number 1,0), that
the file begins on relative track 1020
(track 0 of cylinder 102), and that the
file occupies 100 tracks.

304

{COBOL source deck}
//
//
//
//
//
//
//
//

LBLTYP NSD{Ol)
EXEC LNKEDT
ASSGN SYS007,X'OOC'
ASSGN SYS008,X'OOE'
ASSGN SYS015,X'192'
DLBL MASTER,,74/365,DA
EXTENT SYS015,111111,l,O,1020,100
EXEC
{input data cards}

/*
/&

INDEXED FILES
The following two examples illustrate
the job control statements necessary for
programs that create and update an indexed
file.
In the CREATEIS source program, the
programmer has written:
SELECT IS-FILE ASSIGN TO
SYS015-DA-2314-I-MASTER
ACCESS IS SEQUENTIAL
RECORD KEY IS R~C-ID.
In the RANDIS source program, the
programmer has written:
SELECT IS-FILE ASSIGN TO
SYS015-DA-2314-I-MASTER
ACCESS IS RANDOM
NOMINAL KEY IS KEY-ID
RECORD KEY IS REC-ID.
SELECT PRINT-FILE ASSIGN TO
SYS008-UR-1403-S
RESERVE NO ALTERNATE AREAS.

the retrieval program, the file label is
indexed sequential using Load Extension,
Add or Retrieve (code ISE).
The first EXTENT statement is identified
as a master index (type and sequence
numbers are 4,0), and the relative track is
i 900 (the extent begins on cylinder 90
track 0), and the extent is 20 tracks long.
The second EXTENT statement is
identified as a cylinder index (type and
sequence number are 4,1), the relative
track is 1820 (the extent begins on
cylinder 91, track 0), and the extent is 20
tracks long.
(Note that the extents assigned to
master and cylinder indexes must be
contiguous, and that the master index must
precede the cylinder index on the disk
pack. Also note, that if a master index is
not requested, the first extent is that for
the cylinder index, which would be type 4,
sequence number 1.)

In both source programs, he has written:
SELECT CARD-FILE ASSIGN TO
SYS001-UR-2540R-S.
I-O-CONTROL.
APPLY MASTER-INDEX TO 2311 ON IS-FILE.
(Note the relationship between the
source program statements and the job
control statements.)
The LBLTYP statement defines the amount
of storage reserved to process labels for
the indexed file. The file has three
extents: a master index extent, a cylinder
index extent, and a data extent.
The EXEC LNKEDT statement causes the
object module to be link edited.
An ASSGN control statement assigns
logical unit SYS001 to the hexadecimal
address OOC -- a 2540R Card Reader.

The third EXTENT statement is identified
as a data area (type 1) and is the third
extent named for this file.
The relative
track is 0020 (the extent begins on
cylinder 1, track 0), and the extent is
1160 tracks long.
End-of-data is indicated with the /*
statement; end-of-job is indicated with the
/& statement.

Creating an Indexed File
// JOB CREATEIS
// OPTION NODECK,LINK,LIST,LISTX,SYM,ERRS
// EXEC FCOBOL
CBL QUOTE
{COBOL source deck}

In the retrieval program, another ASSGN
statement assigns logical unit SYS008 to
the hexadecimal address OOE -- a 1403
Printer.
The next ASSGN statement assigns logical
unit SYS015 to the hexadecimal address 193
a 2314 Disk Drive.
The DLBL statement names the file as
MASTER, and indicates the expiration date
as the 365th day of 1974.
In the file
creation program, the file label is indexed
sequential using Load Create (code ISC); in

//
//
//
//
//
//
//
//
//

LBLTYP NSD(03)
EXEC LNKEDT
ASSGN SYS001,X·00C·
ASSGN SYS015,X'193·
DLBL MASTER,,74/365,ISC
EXTENT SYS015,111111,4,O,1800,20
EXTENT SYS015,111111,4,1,1820,20
EXTENT SYS015,111111,1,2,0020,1760
EXEC
{input data card}

/*
/&

Appendix H:

Sample Job Decks

305

Retrieving and Updating an Indexed File

(Note the relationship between the
system-names in the COBOL source program
and the control statements.)

II JOB RANDIS
/1 OPTION NODECK,LINK,LIST,LISTX,SYM,ERRS
/1 EXEC FCOBOL

The EXEC LNKEDT statement causes the job
to be link edited.

{COBOL source deck}
/1 LBLTYP NSD(03)
1/ EXEC LNKEDT

II ASSGN SYS007,X'OOC'
II ASSGN SYS008,X'OOE'
/1 ASSGN SYS015,X'193'
II DLBL MASTER,,73/365,ISE
II EXTENT SYS015,111111,4,0,1800,20
II EXTENT SYS015,111111,4,l,1820,20
II EXTENT SYS015,111111,1,2,0020,1760
1/ EXEC
{input data cards}
1*

1&
FILES USED IN A SORT OPERATION

The first two ASSGN control statements
assign the logical unit SYSO·07 to
hexadecimal address 181, and logical unit
SYS008 to hexadecimal address 182. SYS007
is the sort input file, and SYS008 is the
sort output file.
The last three ASSGN statements assign
logical unit SYSOOl to hexadecimal address
183, logical unit SYS002 to hexadecimal
address 281, and logical unit SYS003 to
hexadecimal address 282. SYS001, SYS002~
and SYS003 are the logical units that must
be used for sort work files.
The sort work
files must be assigned to 9-track tape
units. At this installation, 9-track tape
drives are associated with hexadecimal
addresses 183, 281, and 282.

The following example illustrates the
job control statements necessary for a
program that sorts an unlabeled tape file.
Sorting an Unlabeled Tape File
In the COBOL source program, the
programmer has written:
/1 JOB SORTCOB·

SELECT NET-FILE-IN ASSIGN TO
SYS007-UT-2400-S.

II OPTION NODECK,LINK,LIST,LISTX,SYM,ERRS
1/ EXEC FCOBOL

CBL QUOTE
SELECT NET-FiLE-OUT ASSIGN TO
SYS008-UT-2400-S.
SELECT NET-FILE ASSIGN TO 3
SYSOOI-UT-2400-S.
NET-FILE-IN is the input file;
NET-FILE-OUT is the output file; NET-FILE
is the sort work file, which utilizes three
tape units.

306

1/
1/
//
1/
/1
1/
//

{COBOL source deck}
EXEC LNKEDT
ASSGN SYS007,X'181'
ASSGN SYS008,X·182·
ASSGN SYS001,X'183'
ASSGN SYS002,X'281'
ASSGN SYS003,X'282'
EXEC

APPENDIX I:

DIAGNOSTIC MESSAGES

This appendix contains information on how to generate a listing of
compile-time diagnostic messages.

COMPILE-TIME MESSAGES
The user can request a complete listing of the diagnostics generated
by this compiler simply by compiling a program with a PROGRAM-ID of
ERRMSG. For a description of the formats of compiler diagnostics and
information about generating this listing, see the chapter entitled
"output" in this publication.

OPERATOR MESSAGES
This section lists the messages issued to SYSLOG by the IBM DOS/VS
COBOL Compiler and Library.
All of the messages listed are also issued
on SYSLST.
The following messages are issued during compilation on SYSLOG.
are also printed on SYSLST with the prefix ILA.

I C1001

They

PARTITION IS LESS THAN 64K
Explanation:
At least 64K is required to compile using DOS/VS
COBOL. Probable user error.
System Action:

The compilation is terminated.

Programmer Response:

Not applicable.

Operator Response: Use the ALLOC command to allocate at least
64K to the partition (refer to BUF option).
If the problem
recurs, do the following to complete your problem determination
action before calling IBM for programming support.

C101I

Execute the MAP command and save the output.

Have the source deck, control cards, output listing, and
console sheet available.

DEVICE NOT ASSIGNED - SYSnnn.
Explanation:
(nnn is either 001,002,003, or 004.). The
specified logical unit is unassigned and must be assigned.
Probable user error.
System Action:

The compilation is terminated.

Programmer Response:

Not applicable.

operator Response:
Use the ASSGN command to assign a physical
unit (magnetic tape or disk) to the file indicated. If the
problem recurs, do the following to complete your problem
determination action before calling IEM for programming
support:
Appendix I: Diagnostic Messages

307

C102I

Execute the LISTIO command and save the output.

Have the source deck, control cards, output listing, and
console sheet available.

UNSUPPORTED DEVICE TYPE - SYSnnn.
ExplanatiQ!!:
(nnn is either 001, 002, 003, or 004.)
The
specified file must be a tape or disk file for SYS002 through
SYS004. SYS001 should be assigned to disk; however, in small,
simple programs that do not require dictionary spill, it is
sometimes possible to compile with the spill file (SYS001)
assigned to tape. If any spill does occur, an input/output
error may occur. Compile-time statistics will say "DICTIONARY
SPILL HAS OCCURRED". No mention is made of dictionary spill in
the compile-time statistics if spill does not occur. Probable
user error ..
System Action:

The compilation is terminated.

Programmer Response:

Not applicable.

Operator ReSDonse: Use the ASSGN command to assign the
appropriate physical unit to the file indicated -- SYS001
should be assigned to a magnetic tape or disk unit. If the
problem recurs, do the following to complete your problem
determination action before calling IBM for programming
support:

C103I

Execute the LISTIO command and save the output.

Have the source deck, control cards, output listing, and
console sheet available.

END OF FILE ON SYSIPT.
Explanation: End-of-file was encountered in the initialization
phase; no source statements were found. Probable user error.
System Action:

The compilation is terminated.

Programmer Response:

Not applicable.

Operator Response: Ensure that a /* card does not precede the
source deck, or add the source deck to the job stream. If the
problem recurs, do the following to complete your problem
determination action before calling IBK for programming
support:

C104I

Execute the

Have the source deck, control cards, output listing, and
console sheet available.

LIST~O

command and save the output.

SYSOOl FILE NOT ASSIGNED TO DISK
Explanation: In small, simple programs that do not require
dictionary spill, it is sometimes possible to compile with the
spill file (SYS001) assigned to tape. However, if any spill
does occur, an input/output error may occur. Any compilation
which spills the dictionary will contain a message in
compile-time statistics. User error.
System Action:

The compilation continues.

Programmer Action:
308

Not applicable.

Operator Response:
Use the ASSGN command to assign SYSOOl to a
disk unit.
If the problem recurs, do the following to complete
your problem determination action before calling IBM for
programming support:

Cl05I

Execute the LISTIO command and save the output.

Have the source deck, control cards, output listing, and
console sheet available.

W-CANNOT OPEN SYS005 --

S~lDMP

IGNORED.

Explanation: The SYMDMP option has been specified, but the
file needed for symbolic debug cannot be opened since SYS005 is
unassigned. Probable user error.
System Action: The SYMDMP option is canceled, and the
compilation continues.
Programmer Response:

Not applicable.

operator Response: Use the ASSGN command to assign SYS005 to a
physical unit.
If the problem recurs, do the following to
complete your problem determination before calling IBM for
programming support:

Cl06I

Execute the LISTIO command and save the output.

Have the source deck, control cards, output listing, and
console sheet available.

SYS006 IS NOT A DISK.
Explanation:
disk.
System Action:

NOLVL ASSUMED.

The specified logical unit is not assigned to a
Compilation continues with NOLVL.

Programmer Response:
Operator Response:
disk unit.

Not applicable.
Use the ASSGN command to assign SYS006 to a

OBJECT-TIME MESSAGES
The following messages are normally issued on SYSLOG.
Cll0A

STOP literal
Explanation: The programmer has issued a STOP literal
statement in the COBOL source program.
System Action:

Awaits operator response.

Programmer Response:

Not applicable.

Operator Response: Operator should respond with end-of-block,
or with any character in order to proceed with the program.
ClllA

AWAITING REPLY
Explanation: This message is issued in connection with the
Full American National Standard COBOL ACCEPT statement.
System Action:

Awaits operator response.

Programmer Response:

Provide the operator with instructions.
Appendix I: Diagnostic Messages

309

Operator Response:
the programmer.

The operator should reply as specified by

The following messages are issued on SYSLOG and SYSLST prior to
cancellation of the job. If the DUMP option is specified, a partial
dump is taken from the problem program origin to the highest storage
location of the last phase loaded. When this occurs, the eight bytes
immediately preceding the DTF are destroyed. The messages have the
form:
CmmmI SYSnnn filename DTFaddress text
where:
nnn is equal to 001 through 255
IIIename is seven or fewer characters and is generated from the
file-name specified in the SELECT sentence.
address is the hexadecimal address of the file's DTF table.
mmm and text correspond as follows:
mmm
112
113
114
115
116
117
118
119
120
121
122

123
124
125
127
128
129
130
131
132
140

text
DATA CHECK
wRONG LENGTH RECORD
PRIME DATA AREA FULL
CYLINDER INDEX TOO SMALL
MASTER INDEX TOO SMALL
OVERFLOW AREA FULL
DATA CHECK IN COUNT
DATA CHECK IN KEY OR DATA
NO ROOM FOUND
DASD ERROR
DASD ERROR WHILE ATTEMPTING TO WRITE
RECORD ZERO
FILE CANNOT BE OPENED AFTER CLOSE WITH LOCK
CYLINDER AND MASTER INDEX TOO SMALL
NO EXTENTS
NO EOF RECORD WRITTEN IN PRIME
DATA AREA
UNRECOVERABLE I/O ERROR
3540 EQUIPMENT CHECK
INPUT/OUTPUT ERROR. FILE STATUS SET TO XX
NEAR REL LOC. XXXXXX.
USABLE TO OPEN FILE 'SYSnnn'. CANCELING.
SIZE NOT SPECIFIED OR INSUFFICIENT GETVIS AREA.
INVALID SEPARATE SIGN CONFIGURATION.

Explanation:

Condition indicated occurred on SYSnnn.

system Action:

The job is cancelled.

Programmer Response: Rerun the job or add a user Declaractive
Section to the Procedure Division of the source program to
handle errors within the program.
If the problem recurs, do the following before calling IBM
for programming support: have source deck, control cards,
compiler output, and console sheet available.
operator Response:

C1251

Not applicable.

NO EXTENTS
Explanation: During CLOSE UNIT processing,
for the next volume.
System Response:

The job is cancelled.

Programmer Response:
statements.
310

extent is found

Rerun job with proper EXTENT (XTENT)

Operator Response:

Not applicable.

If the problem recurs, do the following before calling IBM
for programming support: have source deck, control cards,
compiler output, and console sheet available.
The following message is issued on SYSLOG:
C126D

SYSnnn IS IT EOF?
Where nnn is equal to 001 through 255
Explanation:
A tapemark was just read on an unlabeled tape
file described at compilation time as having more than one
reel.
System Action:

Awaits response from operator.

Programmer Response:

Not applicable.

Operator Response: The operator must respond either with N if
is end of volume, or with Y if it is end of file.
The following messages are issued on SYSLOG and SYSLST:
C127D

NO EOF RECORD WRITTEN IN PRIME DATA AREA
Explanation: During CLOSE processing of an ISAM file opened
OUTPUT, no room was found to write EOF record.
Programmer Response:

Rerun the job with the proper EXTENT.

If the problem recurs, do the following to complete your
problem deter~ination action before calling IBM for programming
support. Have source deck, control cards, compiler output, and
console sheet available.
Operator Response:
C128D

Not applicable.

UNRECOVERABLE I/O ERROR
Explanation:

This is probably a hardware error on tape.

Programmer Response:
Operator Response:

Not applicable.
Rerun the job.

If the problem recurs, do the following to complete your
problem determination action before calling IBM for programming
support.
Have source deck, control cards, compiler output, and
console sheet available.
C1291

VSAM SUBROUTINE ERROR.

CANCELING JOB.

Expl~ation:
The subroutine has encountered an unrecoverable
error.
This can occur when a VSAM OPEN, CLOSE, or ACTION request
(GET, PUT, etc.) returns an error code from which the subroutine
has no means of recovering, or when one of the VSAM macros (SHOWCB,
GENCB, etc.) returns a non-zero return code. All such conditions
indicate an error found in the subroutines and/or in VSAM.

Action:

The program is canceled with a dump.

Programmer Response:

Submit an APAR with the dump.

If the problem recurs, do the following before calling IBM
for programming support: have source deck, control cards, and
compiler output available.
Appendix I: DiagnostiC Messages

311

C1301

INPUT/OUTPUT ERROR. FILE STATUS SET TO xx NEAR REL LOC.
xxxxxx.
Explanation: An I/O error has occurred on the file being
accessed by the COBOL statement at or near the relative
location given in the message, and the user has no USE
declarative for that file.
Action: Control returns to COBOL at the statement following
the COBOL request that caused the error.
Programmer Response: If the error occurred on a READ
operation, processing can continue. If the error occurred on a
WRITE operation, there may be a loss of data.
If the problem recurs, do the following before calling IBM
for programming support: have source deck, control cards, and
compiler output available.

C1311

UNABLE TO OPEN FILE 'SYSnnn'.

CANCELING.

Explanation: The VSAM OPEN or CLOSE request gave a return code
of X'68' or X'6C' because of invalid time stamps in the VSAM
catalog or VSAM file. The VSAM catalog or file should be
recreated. See DOS/VS Supervisor and 1/0 Macros for more
detail on the OPEN/CLOSE return codes.
ActiQQ:

The job is canceled.

Programmer Response:

Recreate the VSAM catalog and/or file.

If the problem recurs, do the following before calling IBM
for programming support: have source deck, control cards, and
compiler output available.

I C1321

SIZE NOT SPECIFIED OR INSUFFICIENT GETVIS AREA.
Explanation: A GETVIS SVC to obtain GETVIS space
for VSAM control blocks was unsuccessful.
Action:

The job is canceled.

Programmer Response:
Increase the partition size
and resubmit the job with a SIZE parameter in the
EXEC statement.

C1401

INVALID SEPARATE SIGN CONFIGURATION
Explanation: During execution of a COBOL program, an invalid
sign was detected for a separately signed item.
ActiQQ:

The job is terminated.

Programmer Response: Probable user error.
input data before reexecuting.

Correct program's

If the problem recurs, do the following before calling IBM
for programming support: have source deck, control cards,
compiler output, and data available.

312

The follo~ing messages (C150I-C170I) are listed on SYSLST.
messages have the form:
CmmmI

prOgram-id

}

{ card/verb number

The

text

Messages C1S0I through C162I may appear interspersed among the SYMDMP
control cards at the point at which the error is encountered.
Program-id is provided for all messages except C1S0I through C1S2I. For
these, the card/verb number of the corresponding line-control card is
given instead. The program-id associated with C1S0I through C1S2I can
be determined from the nearest preceding program-control card.
Messages C153I through C1S5I may also appear in the midst of the dump
output if the error condition is not recognized until dumping has
started.
elS0I

IDENTIFIER NOT FOUND.
Explanation: An identifier specified on the 1ine-contro1 card
cannot be found in the program or is invalid. Level-66 and

Appendix I: Diagnostic Messages

312.1

level-88 items and items defined under an RD are invalid
requests.
Action:

The dump request for this identifier is ignored.

Programmer Response: Probable user error. Before reexecuting,
ensure that no requests have been made on the line-control card
for the dumping of identifiers that have not been defined or
that are invalid.
If the problem recurs, do the following before calling IBM
for prograrrming support: have source deck. control cards, and
compiler output available.
C151I

CARD NUMBER NOT FOUND
Explanation: The card number specified on the line-control
card is not within range of the Procedure Division.
Action: The line-control card which specifies the nonexistent
card number is skipped.
Programmer Response: Probable user error. Ensure that any
card LImber specified on a line-control card is within range of
numbers specified for source program before reexecuting.
If the problem recurs.
do the following before calling IBM
for programming support: have source deck, control cards, and
compiler output abailable.

C152I

VERB NUMBER NOT FOUND
Explanation: The verb number specified on a line-control card
does not exist on the card specified.
Action:

The nearest verb number on the card specified is used.

Programmer Response: Probable user error.
specification before reexecutingo

Correct verb number

If the problem recurs, do the following before calling IBM
for programming support:
have source deck, control cards, and
compiler output available.
C153I

NO ROOM TO DUMP.
Explanation: If this message immediately follows a
program-control card, sufficient storage is not available for
the debug subroutine or for the 12 bytes of data required for
each program in the run unit. If this message follows an
abnormal termination message, one or more of the following is
not available in free storage or in the COBOL Procedure
Division: a contiguous block of 4000 bytes, a contiguous block
of 1800 bytes, or a contiguous block of 512 bytes.
Action:
No Data Division dump for the indicated program and,
in SOffie instances, no statement number information, is
provided.
Programmer Response: Probable user error.
Increase the size
of the partition before reexecuting. See "System
Configuration" for information about storage requirements for
symbolic debugging.
If the problem recurs, do the following before calling IBM
for programming support: have source deck. control cards, and
compiler output available.
Appendix I: Diagnostic Messages

313

C154I

I/O ERROR ON DEBUG FILE.
Explanation: An input/output error has occurred on the debug
file.
Note that such an error may be the result of a file
other than the debug file being mounted on the logical unit
specified.
Action:

SYMDMP output is cancelled for the indicated program.

Response: Hardware, operator, or user JCL error. Before
reexecuting, check logical unit number specified on
program-control card against current mounting, as well as the
ASSGN, DLBL, and EXTENT cards of compilation.
If the problem recurs, do the following before calling IBM
for programming support: have source deck. control cards, and
compiler output available.
C155I

WRONG DEBUG FILE FOR PROGRAM.
Explanation: The file corresponding to the filename and/or
logical unit number provided on the program-control card is not
the debug file created for this program at compile time.
Action:

SYMDMP output is cancelled for the indicated program.

Programmer Response: Probable user error. Before reexecuting,
ensure that the filename and/or logical unit specified on the
program-control card corresponds to that of the debug file
created at compile time.
If the problem recurs, do the following before calling IB~
for prograrr.ming support: have source deck. control cards, and
compiler output available.
C156I

NO ROOM FOR DYNAMIC DUMP.
Explanation: Sufficient storage is not available to store the
line-control card information during execution.
Action: Dynamic dumping is cancelled for the indicated
program.
Programmer Response: Probable user error.
Increase size of
partition or decrease number of line-control cards before
reexecuting.
If the problem recurs, do the following before calling IBM
for programming support: have source deck. control cards, and
compiler output available.

C157I

INVALID FILENAME.
Explanation: If the "filename" parameter is specified for a
disk file on the CBL card at compile time, the same "filename"
must also be specified on the program-control card.
"Filename"
may be from one to seven characters in length; the first
character must be a letter.
Action: All SYMDMP output is cancelled for the indicated
program.
Programmer Response: Probable user error. Correct "filename"
specification on the program-control card before reexecuting.
If the problem recurs, do the following before calling IBM
for programming support: have source deck, control cards, and
compiler output available.

314

C1S81

INVALID LOGICAL UNIT.
Explanation: The logical unit parameter on the program-control
card must be specified, must be an integer between 0 and 244,
and must match the one specified in the ASSGN control state~ent
for the debug at compile time.
Action: All SYMDMP output is cancelled for the indicated
program.
Programmer Response: Probable user error. Correct loaical
unit specification on program-control card before reexecuting.
If the problem recurs, do the following before calling IBM
for prograrr.ming support: have source deck, control cards, and
compiler output available.

C1591

MISSING PARAMETERS.
Explanation: A non-continued line-control card ends with
(HEX>, OF, IN, or THRU.
possibly a continuation punch is
missing in column 72.
Action: A HEX or THRU option ending a card is ignored. When a
card ends with OF or IN, the word is ignored and the identifier
that is dumped is the first one encountered whose qualifiers
match those preceding the word OF or IN.
Proqrammer Response:
Probable user error. Check line-control
card for keypunch errors before reexecuting.
If the problem recurs, do the following before calling IBM
for prograrr.ming support:
have source deck, control cards, and
compiler output av~ilable.

C1601

INVALID OPTION.
Explanation: An element used as an optional parameter on a
program-control card is not one of the legal program-control
card options.
Action:

The element is ignored.

Programmer Response: Probable user error.
program-control card before reexecuting.

Correct syntax of

If the problem recurs, do the following before calling IBM
for programming support: have source deck, control cards, and
compiler output available.
C1611

SUBSCRIPTING ILLEGAL.
Explanation: The "name" parameter of the line-control card may
not be subscripted.
Action: The subscripts are ignored.
identifier is dumped.

Every occurrence of the

Programmer Response:
Probable user error~
Specify the name of
the item without the subscript before reexecuting. This will
result in a dump of every occurrence of the item.
If the problem recurs, do the following before calling IBM
for programming support:
have source deck, control cards, and
compiler output available.
Appendix I: Diagnostic Messages

315

C162I

ON PARAMETER TOO

BIG~

Explanation: Neither the n , m, nor k parameter of the ON
option may exceed 32767.
Action:

The number is reduced to 32767.

Proqrammer Response: Probable user error.
parameter before reexecuting.

Correct invalid

If the problem recurs, do the following before calling IBM
for programming support: have source deck, control cards, and
compiler output available.
C1631

FLOW TRACE NON-CONTIGUOUS.

MORE THAN 10 PROGRAMS ENCOUNTERED

Explanation: A non-contiguous flow trace will result if FLOW
option is effective in a subprogram structure of more than 10
programs compiled with the FLOW option.
Action: The FLOW trace is terminated upon encountering the
eleventh PROGRAM-ID. Tracing resumes only upon returning to
one of the original ten programs.
Programmer Response:
Probable user error.
If trace is absent
for a program where it is critical, recompile one or more of
the programs where the flow is non-critical without the FLOW
option and reexecute.
If the problem recurs, do the followin~ before calling IBM
for programming support: have source deck. control cards, and
compiler output available.
C164I

FLOW TRACE IN EFFECT BUT NO PROCEDURES TRACED.
Explanation: Abnormal termination has taken place before any
COBOL statement with a procedure-name has been traced.
Action:

No tracing is done.

Proqrammer Response: Probable user error.
If trace is
desired, recompile the program after inserting additional
procedure-names.
If the problem recurs, do the following before calling IBM
for progromming support: have source deck. control cards, and
compiler output available.
C1651

SYMDMP/STATE/FLOW/COUNT INTERNAL ERROR.

EXECUTION CANCELLED.

Explanation: Abnormal termination occurred during execution of
one of the debugging subroutines.
Action:

The job is cancelled.

Programmer Response:

Internal logic error.

If the problem recurs, do the following before calling IB~
for programming support: have source deck, control cards, and
compiler output available.

316

C1691

STATE OPTION CANCELLED.
Explanation: compiler or logic error has occurred during STATE
option processing.
Under certain conditions, this error may
result from other user errors. For example, a loop might
destroy some of the information required by the STATE
subroutines; an invalid branch might cause a non-existent
priority~number to be stored in the TGT, etc.
Action:

STATE output is cancelled.

Programmer Response: Probable user error.
possible compiler
error or user error. Correct other known errors (if any)
before attempting reexecution.
If the problem recurs, do the following before calling IBM
for programming support: have source deck, control cards, and
compiler output available.
C1101

INVALID ADDRESS.
Explanation: The address calculated for a subscripted
identifier u or a starting or ending address of a
variable-length identifier used as the receiving field in a
MOVE statement is invalid.
Action:

A symbolic dump is produced.

Programmer Response: Probable user error.
Possible compiler
error or user error. Correct other known errors (if any)
before attempting reexecution.
If the problem recurs, do the following before calling IBM
for programming support: have source deck, control cards, and
compiler output available.
C1711

SPACE NOT FOUND FOR THE COUNT CHAIN.
Explanation:
space.

CONTINUING.

A GETVIS macro was unsuccessful due to lack of

Action: Execution continues. Execution statistics are not
provided for the last indicated program unit.
Programmer Response: Probable user error. Allocate more space
on EXEC card before attempting reexecution.
If the problem recurs, do the following before calling IBM
for programming support: have source deck" control cards, and
compiler output available.
C112I

SPACE NOT FOUND FOR THE VERBSUM TABLE.
Explanation:
space.

CONTINUING.

A GETVIS macro was unsuccessful due to lack of

Action: Execution continues.
provided for the program.

Verb summary statistics are not

Programmer Response: Probable user erroru Allocate more space
on EXEC card before attempting reexecution.
C1731

FREEVIS FAILED.

Explanation:
Action:

EXECUTION CANCELLED.

A FREEVIS macro was unsuccessful.

Execution is terminated.
Appendix I: Diagnostic Messages

317

Programmer Response: Probable user error. Allocate more space
on EXEC card before attempting reexecution.
If the problem recurs, do the following before calling IBM
for prograrrming support: have source deck, control cards, and
compiler output available.
C175I

INVALID COUNT TABLE ENTRY.

EXECUTION CANCELLED.

Explanation: A count table entry in the object module is not
one of the following:
end-of-table indicator, procedure-id, or
verb-ide
Action:

Execution is terminated.

Proarammer Response: Probable user error.
possible compiler
or user error. Check your program for routines that may have
moved data into the count table area. Correct other known
errors "IOOO
OCCURS
130.
15 OCR-STANDARD-FIELD-CHAR PIC X
90667000
10 OCR-IMAGE-MODE-RECORD
90677000
REDEFINES OCR-STANDARD-MODE-RECORD.
90687COO
15 OCR-IMAGE-FIELD-LENGTH PIC 99 OCCURS 14.
90697000
15 OCR-IMAGE-FIELD-CHAR
PIC X
OCCURS 102.
90699000
********** END OF 3886 DATA DIVISION COPY MEMBER *************
91561400
05 NOTICE-OF-PAYMENT-DUE REDEFINES OCR-DATA-RECORD.
91561600
10 LINE-l.
PIC X (20)'
91561800
15 LI-POLICYHOIDER-NA~E
15 FILLER PIC X(15).
91561900
10 LINE-2 REDEFI "ES lINE-1.
91562200
PIC X(20).
15 L2-CITY-AND-STATE
91562400
PIC X(8).
15 L2-POLICY-NU~EE~
91562600
PIC 9(4)V99.
15 L2-AMOUNT-DUE
91562700
15 L2-PAYMEN7-VERIFY-CODE PIC 9.
91562800
10 LINE-3 REDEFINES LINE-1.
91563100
15 L3-AMOUNT-PAID
PIC 9(5)V99.

Sample OCR Program (Part 2 of 5)

00123
00124
00125
00126
00127
00128
00129
00130
00131
00132
00133
00134
00135
00136
00137
00138
00139
00140
00141
00142
00143
00144
00145
00146
00147
00148
00149
00150
00151
00152
00153
00154
00155
00156
00157
00158
00159
00160
00161
00162
00163
00164
00165
00166
00167
00168
00169
00170
00171
00172
00173
00174
00175
00176
00177
00178
00179
00180
00181
00182
00183
00184
00185
00186
00187
00188
00189
00190
00191
00192

Figure 69.

PROCEDURE DIVISION.
STOP RUN.
Pl0-START.
MOVE 'SYS010' TO OCR-FILE-ID.
MOVE 'FOR~AT' TO OCR-FOR~AT-RECORD-ID.
PERFORM OCR-OPEN.
OPEN OUTPU'l PRINTER.
P10-HEAD.
MOVE ALL '*' TO PRINT-LINE.
PERFORM PRINT-ROUTINE.
MOVE 1 TO OCR-STACKER.
Pl0-READ.
PERFORM OCR-READ.
IF OCRS-NONRECOVERY-ERROR, GO TO P10-EOP-ERR.
IF OCRH-LINE-GOOD,
GO TO P10-GOOD.
IF OCRH-LINE-BLANK,
GO TO Pl0-GOOD.
IF OCRH-LINE-NON-CRITICAL-ERR, GO TO Pl0-GOOD.
IF OCRH-END-OF-PAGE.
GO 'IO P10-FOll_
***** IF OCRH HAS ANY OTHER CODE, CONSIDER THE DATJI. AS BAD ****
Pl0-BAD.
MOVE MSG-EAD-DATA TO PRINT-LINE.
PERFORM PRINT-ROUTINE.
~OVE 2 TO OCR-STACKER.
Pl0-GOOD.
~OVE OCR-DATA-RECORD TO PRINT-LINE.
PERFORM PRINT-ROUTINE.
MOVE 1 TO PRINT-CONTROL.
ADD 1 TO OCR-LINE-NUMBER, OCR-LINE-FORFAT.
IF OCRH-LINE-NUMBER IS LESS THAN 3, GO TO Pl0-READ.
P10-EOP.
MOVE 3 TO OCR-LINE-NUMBER.
PERFORl·1 OCR- EJECT.
Pl0-EOP-ERR.
I-IOVE 1 TO CCR-LINE-NUIvlBER, OCR-LINE-FOrtlY1AT.
MOVE 3 TO PRINT-CONTROL.
GO TO Pl0-BEAD.
********* EXCEPTION PROCESSING ROUTINE ***************
OCR-EXCEPTION-ROUTINE.
IF OCRS-END-OF-FILE,
GO TO F20-EOF.
IF OCRS-MARK-CHECK,
MOVE MSG-~ARK-CHECK '10 PRINT-LINE,
GO TO P20-RETURN.
IF OCRS-NONRECOVERY-ERROR,
~OVE MSG-NONRECOVERY-bRROR TO PRINT-LINE,
GO TO P20-RETURN.
IF OCRS-INCOMPLETE-SCAN,
MOVE MSG-INCOMPLETE-SCAN TO PRINT-LINE,
GO TO P20-RETURN.
IF OCRS-MARK-AND-EQUIP-CHECK,
MOVE MSG-MARK-AND-EQUIP-CHECK TO OCR-LINE,
GO TO P20-PRINT-EOF.
IF OCRS-PER~ANENT-ERROR,
MOVE MSG-PERMANENT-ERROR TO PRINT-LINE,
GO TO P20-PRINT-EOF.
***** IF NONE OF THE ABOVE ERRORS, GIVE; TERMINATION MESSAGE *****
MOVE OCR-STATUS-KEY TO MSG-TERI":-STATUS-KEY.
MOVE MSG-TERMINATION TO PRnn-LINE.
GO TO P20-PRINT-EOF.
P20-RETURN.
PERFORM PRINT-ROUTINE.
GO TO OCR-CALL-EXIT.
P20-PRINT-EOF.
PERFORM PRINT-ROUTINE.
P20-EOL
PERFORM OCR-CLOSE.
CLOSE PRINTER.
STOP RUN.
PRINT-ROUTINE.
WRITE PRINT-RECORe AFTER ADVANCING PRINT-CONTROL.
OCR-COPIED-PROCEDURES~
COPY ILBr:;OCRP.

91563400
91563700
91564000
91S65000
91566000
91567000
91568000
91569000
91570000
91571000
91572000
91573000
91574000
91574200
91575000
91576000
91579000
<)1580000
91581000
91582000
91583000
91584000
91584200
91585000
91585200
91585400
91585600
91585800
91585900
91586200
91586300
91586400
91586600
91586700
91586800
91587100
91587300
91587400
91587600
91587700
91587800
91587900
91588100
91588500
91588700
91~88900

91589100
91S89300
91589500
91589700
91590000
91591000
91592000
91593000
91594000
91595000
91596000
91597000
91598COO
91598200
91598400
91600000
91001000
91602000
91603000
91604000
91605000
91607000
91609000
91610000

Sample OCR Program (Part 3 of 5)

Appendix J:

COBOL 3886 Optical Character Reader Support

329

00193 C

00194
00195
00196
00197
00198
00199
00200
00201
00202
00203
00204
00205
00206
00207
00208
00209
00210
00211
00212
00213
00214
00215
00216
00217
00218
00219
00220
00221
00222
00223
00224
00225
00226
00227
00228
00229
00230
00231
00232
00233
00234
00235
00236
00237
00238
00239
00240
00241
00242
00243
00244
00245
00246

C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C

Figure 69.

330

******* ILBDOCRP ~ OCR 3886 PROCEDURES
******************************************************************90757000
********
0 C R
3 8 8 6
PRO C E D U R F S
*********90767000
******************************************************************90777000
* THE 3886 OCR SUBROUTINE USES OCR-FILE FIELDS AS FOLLOwS
90778000
*
90779000
* ALL OPERATIONS REQUIRE
90780000
*
OCR-FILE-ID = THE UNIQUE NA~E USED TO IDENTIFY THE FILE
90781000
*
'IO THE SUBROU'IINE AND TO THE SYSTE~ 90782000
*
OCR-OPERATION = THE CODE FCR THE REQUESTED OPERATION
90783000
* ALL OPERATICNS RETURN
90784000
*
OCR-STATUS-KEY = RETURN CODE FCR VARIOUS OCCURRENCES
90785000
*
90786000
* OCR-OPEN ("OPEN ") ALSO REQUIRES
90786200
*
OCR-FORMAT-RECORD-ID = LIBRARY NAME OF DFR TO LOAD
90786400
* OCR-CLOSE ("CLOSE") REQUIRES NC ADDITIONAL PARAMETERS
90786600
* OCR-READ ("READ ") ALSO REQUIRES
90786800
*
OCR-LINE-NUMEER (1-33) = LINE. TO READ (ON DOCUMENT)
90786900
*
OCR-LINE-F-ORMAT (1-63) = DLINT NUMBER (IN CUHRENT DFR)
90787900
*
AND RETURNS (IF OCRS-SUCCESSFUL)
90788100
*
OCR-HEADER-RECORD = HEADER RECORD, AS RETURNED BY THE 3886 90788300
*
OCR-DA'IA-RECORD = DATA FROM DOCUMENT, FROM 3886
90788500
* OCR-READ-OVERLAPPED ("READO") BAS SAME REQUIREMEN'I'S AS OCR-READ90788800
* OCR-WAIT ("WAIT ") RETURNS SAME PARAMETFRS AS OCR-READ
90789800
* OCR-MARK-LINE ("MARKL") ALSO REQUIRES
90790000
*
OCR-LINE-NUMBER (1-33) = LINE TO ¥ARK (CN DOCUMENT)
90790200
*
OCR-MARK (1-15) = SUM OF DESIRED MARK CODES (8421)
90790400
* OCR-MARK-DOCUMENT ("MARKD") ALSO REQUIRES
90790600
*
OCR-~ARK (1-15) = SUM OF DESIRED MARK CODES (8421)
90790700
* OCR-EJECT ("EJECT") ALSO REQUIRES
90791700
*
OCR-S'IACKER (1-2) = STACKER 'IO SELECT (A OR B)
90791900
*
OCR-LINE-NUMEER (0-33) = NUMBER OF LINES CN DOCUMENT
90792100
*
FOR VALIDATICN (IF 0, NO VALICATION wILL OCCUR) 90792500
* OCR-SET-DEVICE ("SETDV") ALSO REQUIRES
90792600
*
OCR-FORMAT-RECORD-ID = LIBRARY NAME OF DFR TO LOAD
90793600
*
90793800
*NOTES90794000
* 1. 'IHE TERMS DFR AND DLINT ARE USED TO REFER TO THE EXPANDED 90794200
* CODE, IN LOADABLE FORM, OF THE RESPECTIVE SYSTEM MACROS.
90794400
* 2. OCR-WAIT MAY BE REQUES'IED AF'IER, AND ONLY AFTER, A
90795300
* SUCCESSFUL OCR-READ-OVERLAPPED REQUEST. NO INTERVENING
90795500
* I/O COMMANDS WILL BE ALLOWEC ON 'IHAT SAME FILE.
90795700
* 3. THE PROCEDURES PROVIDED BELCW AUTOMATICALLY FILL IN
90795900
* THE OCR-OPERATION FIELD, CALL THl. SUBROUTINE, AND TEST
90796100
* THE OCR-STATUS-KEY AFTER RETURN. IF ANY EXCEP'IICNAL
90796400
* CONDITIONS OCCUR, THEY PASS CON'IROL TO THE ROUTINF
90796bOO
* OCR-EXCEPTION-ROUTINE, WHICH THE PRCGRAMMER MUST PROVIDE.
90796700
* THE PROGRAMMER MAY AVOID EXCEPTION ROUTINE INVOCATION BY
90797900
* ADDING THE FOLLOWING PHRASE TO 'IHE COpy S'IATEMENT:
90798100
*
REPLACING OCR-EXCEPTION-ROUTINE BY OCR-CALL-EXI'I
90798300
* 4. ALTHOUGH OCR-STATUS-KEY MAY INDICATE THAT THE DESIRZD
* OPERATION WAS SUCCESSFUL, THE VALIDITY OF THE DA'IA OBTAINED
* SHOULD BE DE'IERMINED BY TESTING CCRH-LINE-STATUS.
******************************************************************90798700

Sample OCR Program (Part 4 of 5)

00247
00248
00249
00250
00251
00252
00253
00254
00255
00256
00257
00258
00259
00260
00261
00262
00263
00264
00265
00266
00267
00268
00269
00270
00271
00272
00273
00274
00275
00276
00277
00278
00279
00280

C
C
C
C
C
C
C

C
C
C

C
C
C
C

C
C
C
C
C

C
C
C

C
C
C
C
C
C
C

C
C

OCR-3886-PROCEDURES.
OCR-OPEN.
MOVE 'OPEN ' TO OCR-OFERATION OF OCR-FILE.
PERFORt.., OCR-CALL THRU OCR-CALL-EXI'J...
OCR-CLOSE.
1",0VE 'CLOSl:!.' TO OCR-OPERATION OF OCR-FILE.
PERFORIv: OCR-CALL THRU OCR-CALL-EXIT.
OCR-READ.
MOVE 'READ ' TO OCR-OPERATION OF OCR-FILE.
PERFOPJ.~ OCR-CALL THRU OCR-CALL - EXIT.
OCR-READ-OVERLAPPED.
~OVE 'READO' TO OCR-OPERATION OF OCR-FILE.
PERFORM OCR-CALL THRU OCR-CALL-EXIT.
OCR-wAIT.
MOVE 'WAIT ' TO OCR-OPERATION OF OCR-FILE.
PERFORM OCR-CALL THRU OCR-CAI.I.-EXI'I.
OCR-NARK-LINE.
MOVE 'MARKL' TO OCR-OPERATION OF OCR-FILE.
PERFORM OCR-CALL THRU OCR-CALL-EXIT.
OCR-fll.ARK-DOCUMEtn.
MOVE 'MARKD' TO OCR-OPERATION OF OCR-FILE.
PERFORM OCR-CALL THRU OCR-CAI.I.-EXIT.
OCR-EJECT.
MOVE 'EJECT' TO OCR-OPERATION OF OCR-FILE.
PERFORM OCR-CALL THRU OCR-CALL-EXIT.
OCR-SET-DEVICE.
MOVE 'SETDV' TO OCR-OPERATION OF OCR-FILE.
PERFOR:t-~ OCR-CALL THRU OCR-CALL- EXIT.
OCR-CALL.
CALL 'ILEDOCRO' USING OCR-FILE.
IF NOT OCRS-SUCCESSFUL OF OCR-FILE,
GO TO OCR-EXCEPTION-ROUTINE.
OCR-CALL-EXIT. EXIT.
********** END OF 3886 PROCEDURE DIVISION COPY MEMBER

Figure 69.

*********

90799700
90800700
90807000
90817000
90827000
90837000
90847000
90857000
90867000
90877000
90887000
90897000
90907000
90917000
90927000
90937000
90947COO
90957000
90967000
90977CCO
90987COO
90997000
91007COO
91017000
91027000
91037000
91047000
91057000
91067000
91077000
91087000
91097000
91107000
91109000

Sample OCR Program (Part 5 of 5)

Appendix J:

COBOL 3886 Optical Character Reader Support

331

This index is supplemented with entries from the index of IBM DOS Full American National
Standard COBOL. These entries are identified by an asterisk (*).
(Where more than one page reference is given, the major reference appears £irst.)
* 22,205,42
* in arithmetic expressions*
(see also asterisks, used in PICTURE
clause) *
** in arithmetic expressions*
/*
15
/&
15
{ (see braces)*
[ (see brackets)*
(see pound sign)*
• (see period)*
••• (see ellipsis)*
< in relation conditions*
and ) in*
arithmet~c expressions*
compound conditions*
PICTURE clause*
subscripting and indexing*
+ (see plus symbol)*
$ (see currency symbol, dollar sign)*
in Data Division and Procedure Division
entries*
(see also semicolon)*
(see either hyphen, or minus symbol)*
/ in
arithmetic expressions*
sterling report items*
, (see comma)*
> in relation conditions*
in
COMPUTE statement*
relation conditions*
• or " in nonnumeric literals*
(see also quotation· mark) *

A, in PICTURE clause*
alphabetic items*
alphabetic symbol*
alphanumeric edited items*
alphanumeric items*
abbreviations*
abnorm~l termination
251-253
absolute*
column number*
line spacing in a report*
values in MOVE statement*
ACCEPT statement 13,*
subroutines 290
Access Method Services 130
ACCESS MODE and VSAM capabilities*
ACCESS MODE clause*
ACCESS MODE clausen VSAM*

accessing a direct file 99~117,*
randomly 101
sequentially 100
accessing an indexed file 118-122,*
randomly 121-122
sequentially 121
accessing a sequential file 99,*
acknowledgement*
action request time file status values
(VSAM)
138
.
ACTION statement 42
actual decimal point*
actual key 101-111
actual track addressing 101-110,
116-117
considerations for specific
devices 116-118
sample program 106-110
relative track addressing 101-106
sample program 111-115
structures 102
ACTUAL KEY clause 101-102
description and format 102,*
READ statement*
REWRITE statement*
SEEK statement*
WRITE stateroent*
actual track addressing 101-110,116-117
considerations for specific
devices 116-118
sample program 106-110
ADCON table 298
ADD statement (Librarian)
51,52
description and formats 51,*
adding a record to a prime track 120
adding records to an indexed file 119-120,
121-122
adding source statements to a be ok 51
addition operator*
addressing direct files
actual track addressing 101-110.
116-117
sample progra~ 106-110
relative track addressing 101-106
sample program 111-115
addressing schemes 99-122,*
direct 99-117.*
indexed 118-122,*
sequential 99,*
advantage of S-mode records over V-mode
records 186
algebraic value in a sign condition*
algorithm*
alignment of data items*
comparisons*
Index

333

decimal point*
editing*
File Section Items*
JUSTIFIED clause*
Linkage Section Items*
PICTURE clause 196.*
SYNCHRONIZED clause 200.*
USING option*
VALUE clause*
Working-Storage Items 194.*
ALL literal figurative constant*
description*
MOVE statement*
relation condition*
STOP statement*
alphabetic character*
alphabetic class test*
alphabetic collating sequence*
alphabetic data items*
alphabetized cross-reference listing
'68
generation of 260
linkage editor 71,261
object time 309-317,260-261
operator 307-309,73,72
sort 209
direct data organization 97.*
direct files 99-118,97
accessing techniques 100 n l0l,*
ACTUAL KEY clause 101~*
actual track addressing 101-110,
116-117
APPLY EXTENDED-SEARCH clause 101,*
ASSIGN clause 100,101n *
BLOCK CONTAINS clause*
error processing 106,1116*
initiating access 100.*
invalid key condition*
random access 101,*
READ statement*
recording mode*
relative track addressing 101-106,
111-115

REWRITE statement*
sample job decks 304,303
sequential access 100,*
user labels*
WRITE statement*
direct indexing*
direct linkage 82
direct organization (DTFDA)
99-118,97
disk extent subroutines 290
Diskette input/output unit (3540)
processing 123-125
DISPLAY items
conversions involving 197-200
internal format of 201
special considerations for 200
DISPLAY statement*
DISPLAY usage*
alignment*
alphabetic items*
alphanumeric items*
ASCII considerations*
description*
edited items*
numeric items*
SYNCHRONIZED clause*
DISPLAY-ST usage*
DISPLAY statement subroutines 290
displaying data values during
execution 248
DIVIDE statement*
division, arithmetic operation*
division by zero*
division header*
division operator*
division of a program, definition*
division/remainder method of
randomizing 103-106
used to create a direct file
actual track addressing 107-110
relative track addressing 112-114
DLAB control statement 30
DLBL control statement 28
identifying private libraries 55
document description (OCR)
320
document design (OCR)
319
dollar sign*
DOS/VS COBOL Unresolved External
References 71
double slash 22
double spacing*
doubleword*
DTF
creation of 98,150
locating in a dump 252-253
DTF tables 150-155
dummy files*
dummy segment 89
DUMP option 32
dumps
errors that can cause 252
how to use 251
symbolic 229-245
system 251-259
duplication of names*

in
external floating-point items*
floating-point numeric literals*
EBCDIC collating sequence (Extended Binary
Coded Decimal Interchange Code)*
edit and execute job 14
editing 17-18,40-42~*
editing character*
edit-only job 14
editor, linkage 11
effective storage considerations 298
EJECT 59,191.325,*
ellipsis 23
ellipsis ( ••• ) in formats 23,*
ELSE option*
IF statement*
nested IF statements*
ON statement*
END DECLARATIVES.*
END statement 51~52
end-of-data control statement 15
end of file*
end-of-job control statement 15
end of page condition*
end of volume positioning*
ENTER statement*
ENTRY control statement 42
entry point in a called program 76.77
entry-sequenced files 127
considerations for READ statement 140
considerations for REWRITE
statement 139
considerations for WRITE statement 139
ENTRY statement 76
in an overlay structure 83
Environment Division*
ASCII considerations*
Configuration Section*
Input-Output Section*
international considerations*
organization*
segmentation considerations*
sort considerations*
Systern/370 card devices*
Systern/370 instructions*
3540 Diskette unit file
considerations 123
equal sign (=)*
in COMPUTE statement*
in relation condition*
equal size operands in a relation
condition*
equivalents*
reserved words and abbreviations*
THROUGH and THRU*
error bytes*
error conditions, arithmetic operations*
error handling (VSAM)
36
file status values
at OPEN 138
at action request time 138
status key 136,130
error messages, diagnostic (see messages)
error message subroutine 295
ERROR procedures. VSAM*
error processing declaratives*
E.

Index

339

error recovery for non-VSAM files 155
on unit-record devices 35
using an assembler language
routine 159-161
using error declarative section 155-158
using INVALID KEY 155,156
errors that can cause a dump 252
ERRS option, 33
evaluation rules*
EXAMINE statement*
EXCEPTION/ERROR procedure, VSAM*
CLOSE statement*
DELETE statement*
description and format*
OPEN statement*
READ statement*
REWRITE statement*
START statement*
WRITE statement*
EXEC control statement 15
EXEC FCOBOL statement 17,15
EXEC LNKEDT statement 17,15
execute-only job 14
execution, order of*
execution output 72-73
execution time
considerations 299-300
machine requirements 297-298
messages 261
EXHIBIT statement 248-249,247
subroutine 290
exit point for procedures*
EXIT PROGRAM statement 76
symbolic debugging*
EXIT statement*
description and format*
PERFORM statement*
PROGRAM option*
with sort procedures*
explanatory comments*
exponent*
floating-point items*
floating-point numeric literals*
exponentiation 204
Extended Binary Coded Decimal Interchange
Code (EBCDIC)*
collating sequence*
nonnumeric literals*
extended search 100
EXTENDED-SEARCH option of the APPLY
clause 100,*
extended source program library
facility 57
EXTENT control statement 28-30
external data*
external decimal items*
external floating-point items*
external-name 76
in ASSIGN clause*
external reference 71
unresolved 71
weak 71

F-mode records
FCOBOL 17
340

179,*

Features of the DOS/VS compiler 7
FD*
Federal Information processing Standard
(FIPS)
39,*
figurative constants*
file*
and volume portability (VSAM) 130
definition*
disposition of*
CLOSE statement*
OPEN statement*
entry-sequenced 127
FILE-CONTROL paragraph*
file description entry*
inter-record slack bytes*
I-O-CONTROL paragraph~
key-sequenced 127
file control block (FCB) 148
FILE-CONTROL paragraph*
ACCESS MODE clause*
ACTUAL KEY clause*
ASSIGN clause*
copying*
FILE-LIMIT clause*
format*
NOMINAL KEY clause*
PROCESSING MODE clause*
RECORD KEY clause*
RESERVE clause*
SELECT clause*
.
sort considerations*
TRACK-AREA clause*
file description (OCR)
320
file description entry*
BLOCK CONTAINS clause*
description and format*
DATA RECORDS clause*
LABEL RECORDS clause*
RECORD CONTAINS clause*
RECORDING MODE clause*
REPORT clause*
report writer*
sort*
VALUE OF clause*
file description entry, VSAM*
file information area for OCR*
file information block (FIB) 146
file integrity 116
FILE-LIMIT clause*
file-name
arguments 79
definition*
file organization 97-98
direct 99-118.97
indexed 118-122,97-98
sequential 99,97
VSAM 127
file processing for 3540 Diskette unit
files 123
file processing technique*
file retention
on direct-access storage devices 28
on tape devices 27
File Section 194 n *
ASCII considerations*
boundary alignment*
content*
copying*

file description entry*
format*
naming data*
record description entry*
report writer considerations*
sort considerations*
file size for sort*
files sharing same storage area*
FILE STATUS clauser VSAM 136,*
file status values (VSAM)
at OPEN 138
at action request time 138
file table 299
FILLER*
CORRESPONDING option*
inter-record slack bytes*
record description entry*
FINAL control*
CONTROL clause*
TYPE clause*
final phase of sort*
FIPS diagnostic messages 68
FIPS flagger description 39,*
fixed insertion editing*
fixed-length records 179
fixed partitioned mUltiprogramming 12
fixed point numeric item*
fixed point numeric literal*
fixed portion of a segmented program 89 r *
FLAGE option 36
FLAGW option 36
floating first detail 215
floating insertion editing*
floating-point data items and intermediate
results 204
floating-point numeric literal*
flowchart*
flow diagram of overlay logic 84
FLOW option
description 37,229
restriction with OPT 229,37
restriction with STXIT 38,229
flow trace option (see FLOW option)
flow trace subroutine 295
footing report groups*
foreground compilation 300 r 12
foreground programs 12
form overflow*
format*
DISPLAY statement output*
EXHIBIT statement output*
logical records*
report page*
statement 22
format control of the source program
listing*
format F records 179
format notation
job control statements 22-23
symbolic debug control statements 230
format S records 183-188
format U records 180
format V records 180-183
formats of blocked and unblocked
records 118
formulas for converting actual to relative
track addresses 29

formulas tor converting relative to actual
track addresses 29
fractions g internal floating-point items*
FROM identifier option, VSAM
full FIPS flagging 39,*
fullword*
function-name*
functional commands (VSAM) 130
functions of COBOL library arithmetic
subroutines 293
GENERATE statement*
generation of diagnostic messages 260
gen~ric terms
22
GIVING option of error declarative 156-158
global table 65
glossary 64
GOBACK statement 76
GO TO ••• DEPENDING ON subroutine 295
GO TO MORE-LABLES*
GO TO statement*
GOBACK statement*
group*
collating sequence for sort*
contents*
report*
GROUP INDICATE clause*
group item*
halfword*
halting execution*
header labels*
heading print groups*
hierarchy*
high-intermediate FIPS flagging 39.*
HIGH-VALUE (HIGH-VALUES) figurative
constant*
how to use a dump 251
hyphen in statement formats 22

1-0 files*

I-O-CONTROL entry, VSAM*
I-O-CONTROL paragraph*
IBM sterling representation*
IBM-supplied processing programs 12
ID Division header*
Identification Division*
identification field of COBOL source
statements 50
identification of program versions 247
identifier, definition*
identifying records*
IF statement 205
IGN parameter of ASSGN job control
statement 25,*
ILBDCKPO subroutine 263,293
ILBDDUMO 93
ILBDMNSO 75,294
ILBDSEMO subroutine 94,293
ILBDSETO 75.294
ILBDSRTO subroutine 209,293
imperative statements*
implementing an OCR operation 319
improving efficiency 122
Index

341

improving performance
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.3
Linearized : No
XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37
Create Date : 2012:05:25 12:57:48-08:00
Modify Date : 2012:05:25 13:26:23-07:00
Metadata Date : 2012:05:25 13:26:23-07:00
Producer : Adobe Acrobat 9.51 Paper Capture Plug-in
Format : application/pdf
Document ID : uuid:a412813d-30ff-4175-ae63-4113b52470b4
Instance ID : uuid:2622483f-6793-47bd-84a7-61e135838de4
Page Layout : SinglePage
Page Mode : UseNone
Page Count : 404

EXIF Metadata provided by EXIF.tools

SC28 6478 3_DOS_VS_COBOL_Compiler_and_Library_Programmers_Guide_Feb79 3 DOS VS COBOL Compiler And Library Programmers Guide Feb79

SC28-6478-3_DOS_VS_COBOL_Compiler_and_Library_Programmers_Guide_Feb79 SC28-6478-3_DOS_VS_COBOL_Compiler_and_Library_Programmers_Guide_Feb79

Navigation menu

Versions of this User Manual:

Views

Navigation