SC28 6483 2_OS_VS_COBOL_Compiler_and_Library_Programmers_Guide_Jun84 2 OS VS COBOL Compiler And Library Programmers Guide Jun84
SC28-6483-2_OS_VS_COBOL_Compiler_and_Library_Programmers_Guide_Jun84 SC28-6483-2_OS_VS_COBOL_Compiler_and_Library_Programmers_Guide_Jun84
User Manual: SC28-6483-2_OS_VS_COBOL_Compiler_and_Library_Programmers_Guide_Jun84
Open the PDF directly: View PDF 
.
Page Count: 630
| Download | |
| Open PDF In Browser | View PDF |
SC28-6483-2
File No. S370-24
Program Product
IBM OS/VS COBOL
Compiler and Library
Programmer's Guide
Program Number 5740-CB1
5740-LM1
-- ----~-
- - - --------,,--_
... ~-~ -~-
First Edition (June 1984)
Changes are made periodically to the information herein; these changes will be
incorporated in new editions of this publication.
Products are not stocked at the address given below. Requests for copies of this
product and for technical information about this product should be directed to
your IBM marketing representative.
A Program Comment Form (for your comments about the PROFS/PO product) and a
Reader's Comment Form (for your comments about this book) are provided at the back of
this publication. If the Program Comment Form has been removed, address comments to:
IPS Product Support Center, IBM Corporation, P.O. Box 152560, Irving, Texas 75015-2560.
If the Reader's Comment Form has been removed, address comments to: IBM Corporation,
Department 6DD, 220 Las Colinas Boulevard, Irving, Texas 75062.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 1984
Who Should Read this Book?
If you are a business professional who has a need for the
decision-making tools available on the IBM Personal
Computer as well as the principal support functions
available on the IBM Professional Office System (PROFS),
or if you want to know how to use the PROFS Personal
Computer Connection (PROFS/PC2), you should read this
book.
What this Book Will Tell You
This book, Using the PROFS Personal Computer
Connection, tells you how to install PROFS/PC2, what you
need to know and do before you use the product, how to
use PROFS/PC2, how to tailor the main menu to suit your
needs, and how to respond to the messages you may get
from time to time while you are using PROFS/PC2.
You should read the "Introduction" to get an orientation
to the whole system and to perform the tasks, especially
the one-time tasks, necessary for you to use PROFS/PC2.
The "Introduction" tells you how to:
• Install PROFS/PC2.
• Log on to the VM host where you're running PROFS.
(A host system is the data processing system to which
To the Reader
Vll
The COBOL communications user must write
a message control program (MCP) to handle
messages transmitted between remote
stations and the central computer before
they can be processed by a COBOL program.
General te lecommunica tions access method
(TCAM) information, as veIl as specific
guidelines for creating an HCP, can be
found in the publications:
Q~LVS1_Q~1~_~a!l~g~mgnt_fQI_~Y2ig!
f.£Qg!:ammg~§, Order No.
GC26-3837
Q§LY§~_§Y2t§ill_~~Q9~~IDID!ng_~!Q~~~Yl __ Q~t~
~~n~g§ill§n~, Order No.
GC26-3830
Q§LY§1_822§§2_~§tbQg_§§~Y!2§2' Order
No.
GC26-3840
QSLYS2_A~~e~~_MetbQ~_Ser~i~e~,
!~_Q~!~~1g£Qm~n!£atiQft2-!~2
~ethQg_1I£!~1~Qn~Ei~_aUg-la~liti~,
No.
onent: Access
No. GT26-38 3
Order No. GC30-2042
!BM_Q~/VS
TCAM_£~Qg£a~~~2_~uig~,
Order
Order
GC26-3841
QSL~~_1~a~g!2'
Order No.
GC26-3795
No. GC30- 2041
The list of publications that follows
contains the title and IBM form number of
each IBM publication referred to in this
publication:
OSL.!.L!irtua 1 ll2~!!~H~_A££22_~ihQ1.
Order
No.
GC26-3838
~AM1-Programmer~2~gigg,
OS/VS Data Management Services Guide,
Order No. GTOO-0303
OS/VS Data Management Macro
Instructions, Order No. GTOO-030S
!l1Q1.Q_CML!l§g£..!.2_Guide_f~_£Q~Q1.
No.
Order
.Q.SL.!~_1I~g3~_1!~!:~!:.I.i. __ 1i!!~ag~_!g!lQ!:,:
gnd_~QadeLl1~2§ag:g2' Order
SC28-6469
No.
Q.§L!~_1i!!kage_~di
No.
!]I1_Q~_£O BO ~_!!!lg~~£ t i!.~Lllg~.!rn_I§!:.!!in~!.
tOL£u,HLLoagfi, Order
GC26-3813
QS/V~l_£!~i!!g_~nd_Y~_~Y!Q~,
No.
Order
GC24-S0 90
Order
OS/VS JCL Reference publications:
No.
Order
Order No.
GC24-
5100
Order No.
GC28-0692
OS/VS Checkpoint/Restart, Order
No. GTOO-0304
QSLV~l_~tQ£~~_~§li~glg~,
No.
Order
GC24-50 94
.QUVSL~lQ!:~~Esti~!&§.,
No.
Order
GC28-0604
Q~_11~Ql_~Q~Ql_f£Q!Et~_Iermi~1
l!§~C2_Q!iig~-A!lL.Refe~!l£g, Order
IBM
No..
Q§LY§~_§Y2t§ill_~~Q9~~IDID!ng_~!Q~~~Y:
SC28-6433
as/vs Data Management publications:
Order Nos.
GC28-0708
OS/VS1 Utilities, Order No.
GC26-3901
OS/VS2 Utilities, Order No.
GC26-3902
Q~!S_~Q£!L~g£g:g_£~Q~~~'s Ggig~,
Order No.
Q~VSl~£~,
Order
OS ~Q£lL~£g~_~~2g~a~§!:':~§_~~~, Order
No.
SC33-4001
GC24-5099
Q~VSl-4£l~£!i£~,
De~ygging:-i~i~,
GC 24-5093
and GC28-0709
GC28-0671
Q~!~1-~£~Refe£gn£~,
~!~1
Q§Qygg!ng_tl~nggQQ~,
GC28-0667
OS/VS~_~~leas~_~_~Yiq~,
No.
User' 2_Guide and_IH~I~£g!!.£§, O.rder
No.
SC28-6465
No.
Q~vs~~~nniag_Quide_IQ£_gg!ga§g_2,
Order No.
GC38-1007
SC33-4035
Q~~Q!:lL~~~~Install~tiQn_R~f§~!!£~
Material, order No.
SC33-4004
Q~!~_~Q..tiL~!ti:gg_IY.2ta!lation Ref~£'~B.£g
~~i.!!l, Order No.
SC33-4034
The OS/VS COBOL Compiler and Library,
Release 2, is designed according to the
specifications of the followinq industry
standards (as understood and inte.r preted by
IBM as of April, 1976):
• The highest level of American National
Standard COBOL, X3.23-1974 (excepting
the Report Writer Module).
ANS COBOL
X3.23-1974 is compatible with and
identica 1 to In terna tional Organization
for Standardization/Draft International
Standard (ISO/DIS) 1989-COBOL.·
• The highest level of American National
standard COBOL, X3.23-1968 (including
the Report Writer module).
ANS COBOL
X3.23-1968 is compatible with and
identical to ISO/R 1989-1972
Programming Language-COBOL.
Quick Reference to PROFS is a handy reference card to
PROFS tasks. Use it as a quick memory jogger. (Order
no. GX20-2408)
IBM Personal Computer Publications
For more information about the PC, you may want to
refer to the following books:
Disk Operating System, Version 2.0 or 2.1 tells you how
to use DOS on the PC. (Order no. 6024001)
IBM Personal Computer 3278/79 Emulation Control
Program User's Guide explains how to use your IBM
PC or IBM PC XT with the IBM PC 3278/79 Emulation
Control Program, that is, the program that lets you
emulate, or imitate, the functions of an IBM 3278
typewriter keyboard and either the IBM 3278 Model 2
Display Station or the IBM 3279 Model 2A Color
Display Station. (Order no. 1502422)
IBM 3270 Personal Computer Control Program User's
Guide and Reference explains keys, functions, and
procedures that are used to perform tasks on the IBM
3270 Personal Computer. The IBM 3270 Personal
Computer Control Program is designed to operate on
the IBM 3270 Personal Computer machine
configuration 5271 standard models 2, 4, and 6, when
installed with IBM Personal Computer Disk Operating
System, Version 2.0 or 2.1. (Order no. 1837434)
X
PROFS/PC2
The PROFS Personal Computer Connection (PROFS/PC2) lets
you work with selected PROFS tasks on the IBM Personal
Computer. By using the 3278/79 adapter, the PC 3270, or the
IBM Asynchronous Communications Adapter, you can transfer
DOS files from the PC to the host system and you can transfer
files from the host system to the PC. (Throughout this book,
the PC 3270, both hardware and software, and a PC with the
3278/79 adapter card and the 3278/79 Control Program are
referred to as the "PC 327x.") Then you can work with these
files either on the PC in a stand-alone mode or on the host
system. You can move your incoming mail from PROFS to
PROFS/PC2 to open and respond to at a more convenient time
or place. PROFS/PC2 lets you look at, reply to, forward, erase,
file, and resend notes. You can also create new notes.
Actions you take during note processing can be transferred to
the PROFS host system for processing or distribution to other
PROFS users. If you have an optional printer attached to
your Personal Computer, PROFS/PC2 lets you print PROFS
documents that you've transferred from the host system.
What You Need to Use PROFS/PC 2
Hardware
You can perform both host-attached and stand-alone tasks by
means of anyone of the following products:
• IBM Personal Computer or IBM Personal Computer XT
with the following:
Introduction
1-1
18
INTRODUCTION • • • • • • • •
18
Executing a COBOL Program • • • •
18
Compilation
Linkage Editing • • • • •
• • 19
19
Loading
19
Execution
• • • • • • • • •
Operating System Environments
19
19
OS/VS 1 • • • • • • • • • • • •
OS/VS2 • • • • • • • • • • • • • . • . 19
Conversational Monitor system
19
JOB CONTROL PROCEDURES •
Control Statements. • •
Job Management • • • • • •
Preparing Control statements •
Name Field • • •
opera tion Field
••••••
Operand Field • • • • . •
Co mmen ts Fie 1 d • • • • • • •
Conventions for Character Delimiters •
Rules for Continuing Control
statements • • • • • • • • • • • • • •
Notation for Describing Job Control
statements • • • • • ~ • • • • • • • •
JOB statement • • • • • • . • • • •
Identifying the Job (jobname)
•••
Job Parameters • • • • • • .
Supplying Job Accounting
Information • • • • • • •
Identifying the Programmer .
Displaying All Control statements,
Allocation, and Termination
Messages (MSGLEVEL)
•••••
specifying Conditions for Job
Termination (CONm
• • • • . • •
Requesting Restart for a Job (FD)
•
Resubmitting a Job for Restart
(RESTART)
•••••••••••••
priority Scheduling Job Parameters • •
Setting Job Time Limits (TIME) • • •
Assigning a Job Class (CLASS)
•
Assigning Job Priority (PRTY)
•••
Requesting a Message Class
(MSGCLASS) • • • • • • • • • • •
Specifying Main Storage
Requirements for a Job (REGION)
Holding a Job for Later Execution •
Specifying Address Space (ADDRSPC) •
EXEC Statement • • • • • • • • • • • . •
Identifying the step (stepname)
Positional Parameters • • • • • •
Identifying the Program (PGM) or
Procedure (PROC) • • • • • • • • • •
Keyword Pa rameters • • • • • • • •
Specifying Job step Accounting
Information (ACCT) • • • •
• •
Specifying Conditions for
Bypassing or Executing the Job
Step (CO ND)
•••.••••
•
20
22
22
22
23
23
23
24
24
24
25
25
25
26
26
27
27
27
28
29
30
30
30
30
30
31
31
31
32
32
32
32
34
34
35
Passing Information to the
processing Program (PARM)
•
options for the Compiler •
• •
options for the Lister Feature • • •
Options for Use Under TSO Only • . •
options for the Linkage Fditor • • .
opt ions for the Loa der .
. .
options for Execution
.•.••
Requesting Restart for a Job Step
(RD) • • • • • . . . •
.
Priority Scheduling EXEC Parameters
Establishing a Dispatching
Priori ty (DPRTY) • • • • . • • • . .
Setting Job step Time Limits (TIME)
specifying Main storage
Requirements for a Job step
(REGION) • . • • • . . • • .
•
Specifying Address Space (ADDRSPC) •
DD Statement • • . . • • • . . . .
·
Additional DD statement Facilities • • •
JOBLIB and STEPLIB DD Statements • • ·
SYSABEND and SYSUDUMP DD Statements ·
SYSCHK DD statement • . • • . .
·
JOBCAT AND STEPCAT DD statements .
PROC Statement • • • •
·
PEND Statement . • •
·
Command Statement . • . . • . • • • . ·
Delimiter statement
•
. •
Null S ta tement • • . •
Co mmen t St a tement
• . • .
·
BATCH compilation
. . ••
·
Data Set Requirements
·
compiler • • • • • •
SYSUT1, SYSUT2, SYSUT3, SYSUT4,
SYSUT5, SYSUT6 •
•
SY SIN
•
SYSPRI NT .
SYSTERM
•
SYSPUNCH • . . • •
..• .•
SYSLIN • •
.
SYSLIB and/or Other COpy Libraries •
Linkage Editor
. • • .
SYSLIN • •
•
SYSPRINT •
•
SYSTERM
. • •
SYSLMOD
.•
SYSUT1 . •
•
SYSLIB • •
. .••..•
User-Specified Data Sets .
.
loader •
. . •
SY SLIN • •
••• . • . • .
•
SYSLIB . • • . •
. . •.
•
SYSLOUT •
• • • .
.
Execution Time Data Sets . • • . . . .
DISPLAY Statement
. • • •
•
ACCEPT statement . • .
. .•..
EXHIB!T or TRACE Statement
.
COBOL Debugging Aid s . . •
.
Abnormal TerminationDu~r
COUNT option . • • . • • •
.
COBOL Subr outineLibra ry • • • • . .
37
38
44
45
47
47
48
49
50
50
50
51
51
51
69
69
69
69
70
70
70
70
70
70
71
71
73
73
73
74
74
74
74
75
76
76
76
76
77
77
78
78
78
78
78
78
79
79
79
80
80
80
81
81
81
USER NON-VSAM FILE PROCESSING
82
User-Defined Files • • • • • • •
82
File Names and Data Set Names
• • 82
Specifying Information about A File • 83
File Processing Techniques • • •
• 83
Data Set organization • • • •
• 83
Accessing a Physical Sequential File • 85
Specifying ASCII File Processing.
90
processing ASCII Files • • • • • • • • 91
Block Prefix. . • • • • • • • •
91
Handling Numeric Data Items from
ASCII Files • • • • • • • • • • • • 92
Direct File processing • • • • • • • • 92
Dummy and capacity Records • • • • • 94
Sequential Creation of Direct Data
Se t
•. • • • . • • • . . • • • . • 9 5
Random Creation of a Direct Data
Set
• • • • • • • • •
97
sequential Reading of Direct Data
Sets • • • • • • • • • • • • • •
98
Ra ndom Reading, TJpda ting, an d
Adding to Direct Data Sets
98
Multi v'ol ume Da ta Sets
99
File Organization Field of the
System-Name • • • • • •
• .100
Randomizing Techniques.
• • • • 101
Relative File processing.
• • • . 110
Sequential Creation
• • 111
sequential Reading • • • •
• • 112
Random Access • • • • • • • • • • • 112
Indexed Sequential File Processing • • 119
Indexes • • • • . • • . • • • • • • 120
Indexed Sequential File Areas • • • 122
Creating Indexed Sequential Files .123
Reading or Updating Indexed
Sequential Files Sequentially • • • 127
Accessing an Indexed Sequential
File Randomly • • • •
• .129
Using the DD Statement • • • . • • • . • 131
creating a Non-VSAM Data Set • • . • • 131
Creating Unit Record Data Sets • • • 133
Creating Data Sets on Magnetic Tape 133
Creating sequential (BSAM or QSAM)
Data Sets on Mass storage Devices .133
Creating Direct (BDAM) Data Sets •• 134
Creating Indexed (BISAM and QISAM)
Data Sets • • • • • • • • • • • • • 134
Creating Data Sets in the output
Stream • • • • • • • • • • • • • • • 134
Examples of DD Statements Used To
Create Data Sets. . • • • •
• .135
Retrieving Previously Created
Non-VSAM Data sets. • • • • •
• .138
Retrieving cataloged Data Sets • • • 138
Retrieving Noncataloged (KEEP)
Da ta Set s
•• • • • • • • • • • • • 139
Retrieving Passed Data sets
.139'
Retrieving Data through an Input
Stream • • • • • • • • • • • • • • • 139
Examples of DD statements Used to
Retrieve Data Sets • • • • • • • • • 140
DD Statements that Specify Unit
Record Dev ices • • • •
• • 141
Cataloging a Data Set
• • 141
Generation Data Groups
• • 141
Naming Data Sets •
• • 142
Extending Non-VSAM Data Sets •
• • 142
Additional File Processing Information .142
Da ta Con trol Block • • • • • • •
• 143
Overriding DCB Fields • • • • • • .143
Identifying DCB Information
.143
Error processing for Non-VSAM COBOL
Files • • • • • • • • •
• • • 143
Volume Label in g • • • •
• • • 154
Standard Label Format
• • • 155
Standard User Labels • •
.155
User Label Totaling
• • • 156
Nonstandard Label Format
.156
Nonstandard Lapel processing
.157
User Label Procedure.
.157
ASCII File Labels • • • • • • • • • 158
ASCII Standard Label Processing • • 159
ASCII User Label Processing
.159
User Label Exits. • •
• .159
NON-VSAM RECORD FORMATS
• • • 160
.160
Fixed-Length (Format F) Records
Unspecified (Format U) Records • •
• 161
Variable Length ~ormat ~ Records • • • 161
.164
APPLY WRITE-ONLY Clause
Spanned (Format S) Records • . •
• • 164
S-Mode Capabilities
•• • • • •
.165
Sequential S-Mode Files (QSAM) for
Tape or Mass Storage Devices.
.165
Source Language Considerations • • • 166
processing Sequential S-Mode Files
(Q SAM) • • • • • • • • • • • •
.166
Directly Organized S-Mode Files
(BDAM and BSAM)
••.•••••
.168
Source Language Considerations • • • 168
Processing Directly Organized
S-Mode Files (BDAM and BSAM)
.169
OCCURS Clause with the DEPENDING ON
option • • • • • • • •
• 170
VSAM FILE PROCESSING.
.173
Types of VSAM Data Sets • • • • •
.173
Entry-Sequenced Data Sets
• • • 173
Key-Sequenced Data,Sets
.173
Relative Record Data Sets
. • • 174
Access Method Services . • • • • • • • • 174
The DEFINE Command. • • • •
.174
Functions of the DEFINE Command • • 174
Specification of the DEFINE Command 175
Defining a Master Catalog: DEFINE
MASTERCATALOG • . • • • . • • . • • 175
Defining a User Catalog: DEFINE
USERCATALOG • • • • . • • • • . • • 176
Defining a VSAM 'Data Space: DEFINE
.176
SP ACE • • . • •
• • • 177
Defining a KSDS
Defining an RRDS •
.179
Defining an ESDS •
• • • • • • • 179
Reusable Data Sets ••
.179
Miscellaneous DEFINE Cluster
Considerations. • • • • • • •
.180
COBOL File Processing Considerations • • 180
File Processing Techniques.
. • • 180
ESDS P rocessinq • • • •
. 180
KSDS and RRDS Processing.
.181
Password Usage. • • • • •
.181
Current Record Pointer.
.181
Use of the START Verb
.183
Error Processing Opti ons • •
• 183
The Importance of Status Key.
.183
Invalid Key • • • • • • • • • • • • 183
EXCEPTION/ERROR Procedure
• • 183
Error Handling Considerations
.184
Opening a VSAM File
• • • • • .185
Opening an Unloaded File • • • • • • 185
Opening an Empty File • • • •
• 185
opening a File Containing Records • 186
OPEN status Key Values • • • • • • • 186
Dynamic Invocation of Access Method
Services for KSDS and RRDS Data
Sets • • • • • • • • • • • • • • • • 186
Initial Loading of Records into a
File • • • • • • • • • • • • • • • • • 188
Writing Records into a VSAM File • • • 188
ESDS Considerations • . • • • • • • 189
KSDS Considerations - (ACCESS IS
SEQUENTIAL)
• . . • • . • • • • • • 189
KSDS Considerations - (ACCESS IS
RANDOM/DYNAMIC)
• . • • • • • • 189
RRDS Considerations • . • • • • • • 189
Rewriting Records On a VSAM File • • • 189
ESDS Considerations • . • •
• .189
KSDS considerations • . • •
• • 189
Reading Records on a VSAM File
• • 189
ESDS Considerations • . • •
• • 189
KSDS Considerations - (ACCESS IS
SEQUENTIAL)
• • • • • • • • • • • • 190
KSDS Considerations - (ACCESS IS
RANDOM)
• • • • • • • • • • • • • • 190
KSDS Considerations - (ACCESS IS
DYNAMIC) • • • • • • • • • • • • • • 190
RRDS Considerations • • • • • • • • 190
Deleting Records on a File. •
• .190
status Key settings for Action
Requests • • • • • • • • • • •
• .190
C1 os in g a F i 1 e • • • • • • • •
• • 191
COBOL Language Usage with VSAM • • • • • 193
Writing a VSAM Data Set
• • 193
Retrieving Records From A VSAM Data
Set • • • • • • • • • • • • • • • • • 195
Updating A VSAM Data Set. • •
• .198
Job Control Language For VSAM File
Processing • • • • • • • • • • • • • • • 201
DD Statement for a User Catalog
.201
DD Parameters Used with VSAM • • • • .201
VSAM-Only JCL Parameters • • • • • • .201
Converting Non-VSAM Files to VSAM Files 201
using COBOL ISAM Programs With VSAM
Files • • • • • • • • • • • • • • • • . 202
VSAM Features Not Available Through
COBOL • • • •
• • • 202
LISTER FEATURE •
• .203
Operation of the Lister Feature • • • .203
Programming considerations • •
• .203
The Listing • • • • • • • • •
• .203
The Output Deck • • • • • • •
• .204
Reformatting of Identification and
Environment Divisions • • • •
• • 204
Data Division Reformatting • •
• .204
Procedure Division Reformatting • • • 207
Summary Listing
• • 209
The Source Listing •
• .210
Format Conventions
• .210
Type Indicators
• • 211
The Summary Listing
• • • • • .211
General Appearance •
• • 211
The output Deck • • • • • • • • • • .211
Specifying the Lister
.212
SYMBOLIC DEBUGGING FEATURES
.213
Use of the Symbolic Debugging
FeaturE::S • • •
.213
ST ATE Option • • • • • • •
.213
.214
FLOW option • • • • • . •
SYMDMP Option • • • • • •
• • .214
Object-Time Control Cards
.215
.216
DEFAULT SYSDBG DATA SET
Symbolic Debugging under Information
Management System (PP5734-XX6,
.217
5740-XX2)
•••••••.
Sample Program -- TESTRUN
.217
Debugging TESTRUN
.218
.231
OUTPUT • • • • • • • •
.231
Compiler output
Displaying a List of Diagnostic
Messages • • • • . • •
• • 238
Object Module
· • • 239
Linkage Editor Output
· .240
Comments on the Module Map and
Cross Reference List •
.242
'.242
Linkage Editor Messages
.243
Loader output • . • . . . • .
.243
COBOL Load Module Execution Output
.246
Requests for output
.246
Operator Messages
.246
System output
PROGRAM CHECKOUT
· .247
.247
•
.247
SYNTAX-Checking Only compilation .
Debugging Language • • • . • • • . • • • 247
Debugging Lines • • • • • • . .
.248
Declarative Procedures--use for
.248
Debugging • • • • • • • • • • •
.251
TRACE, EXHIBIT, and ON • . • • •
.251
Following the Flow of Control
Displaying Data Values during
.251
Execution • • • • . . • . • •
.253
Testing a Program Selectively
Testing Changes and Additions to
Programs . • • • • • •
• . • . .254
• 254
Abend Dumps . • • • • • • • •
User-Ini tiated Dumps . . • •
· .254
.255
Errors That Can Cause a Dump
Input/Output Errors
· .255
Errors Caused by Invalid Data
.255
.256
Other Errors • • • . • •
.257
Completion Codes • • . • •
Finding Location of Program
Interruption'in COBOL Source
Program Using the Condensed Listing 259
Using the Abnormal Termination Dump .260
Finding Data Records in an Abnormal
Termination Dump • • • • • • • . . . 268
Locating Data Areas for Spanned
Records • • . • • . • • • • . . • • 274
Locating TCAM Data Areas. • •
.275
Incomplete Abnormal Termina tion
.277
Scratching Non-VSAM Data Sets
.278
.278
Obtaining Execution statistics
.279
Debugging and Testing • • • •
.279
Optimization Methods • . • • •
Resequencing the Program.
.279
.279
Insight into SYMDMP output • .
1 i s t er f ea t u r e
Common Expression Elimination . • • 279
Backward Movement
. • • • • • • 279
Unrolling
. • ••
.280
Jamming . • • • • •
. • • 280
Unswitching
• . 280
Incorporating Procedures Inline • . 281
Tabling • • • • • • • .
• .281
Efficiency Guidelines
. • 281
PR OG RAMM IN G TECHNIQU ES • .
• .282
Gene ra 1 Considerations • . •
• • • 282
Spacing the Source Program Listing .282
Coding considerations
• • 282
Environment Division • • • • • • • • . • 282
APPLY WRITE-ONLY Clause
•• 282
QSAM Spanned Records • . . • • • • • 282
APPLY RECORD-OVERFLOW Clause
• • 283
APPLY CORE-INDEX Clause • • • . . . 283
BDAI1-W File Organization •
• .283
Data Division • . • . • • • • •
• .283
Overall Considerations • • • . • • • • 283
Maximum Data Division Size • • . . • 283
Prefixes. . • .
• .283
Level Numbers • • • •
• .284
File Section. • • • • • •
• .284
RECORD CONTAINS Clause
• • 284
Communication Section • • • • • • • • 284
CD Entries. • • • • • •
• • • 284
Working-Storage Section
• • 285
Separate Modules • • •
• .285
Locating the Working-Storage
Section in Dumps • •
• .285
Data Description •
· .285
REDEFINES Clause
• .285
RENAMES Clause.
• • 286
PICTURE Clause •
• .286
SIGN CIa use
• .287
USAGE Clause • •
• .288
special considerations for DISPLAY
and COMPUTATIONAL Fields.
• .290
Data Formats in the Computer • • • • 290
.Proced ure Di vision • • . • . • • • • • • 292
Modularizing the Procedure Division .292
Main-Line Routine
• • • 292
Processing Subroutines.
• .292
Input/Output Subroutines.
• .293
Collating Sequences
• • 293
Use of the UPSI Switches
• • 293
Intercepting I/O Errors • • • • • • • 293
Errors That May Escape Detection • • 294
Intermediate Results.
• • • • • • 294
Intermediate Results and Binary
Data Items. • • • •
• • • 294
Intermediate Results and COBOL
Library Subroutines
• • 294
Intermediate Results Greater than
30 Digits •• • • •
· .294
Intermediate Results and
Floating-Point Data Items
• .294
Intermediate Results and the ON
SIZE ERROR Option
• • 295
Verbs • • • • • • •
• .295
.295
CALL Statement •
CANCEL Statement
· .295
CLOSE Statement
• .295
COMPUTE statement
• .295
IF Statement • •
• .295
MOVE Statement • •
• .296
NOTE statement. . • • • •
.296
OPEN Statement • • • • • • • • • • . 296
PERFORM Verb • • • • • • • . • • • . 2~6
READ INTO and WRITE FROM Options • . 296
WRITE ADVANCING with LINAGE,
FOOTING, and END-OF-PAGE .
.297
RECEIVE Statement
• • • • • • • • • 297
SEND Statement. • • . • .
. .297
ENABLE/DISABLE Statements
.297
START Statement
.298
STRING Statement. • .
• • • 298
TRANSFORM Statement
.298
UNSTRING Statement • •
. .299
Using the Report writer Feature
. • 299
REPORT Clause in FD
.299
summing Technique
. • 300
Use of SUM. • . • • .
• .300
SUM Routines. . . . •
• .300
output Line Overlay
• • • • .301
Page Breaks
. • 302
WITH CODE Clause . • •
. • • 302
Control Footings and Page Format • • 303
Floating First Detail Rule
.304
Report writer Poutines • • •
• .304
Table Handling Considerations
.304
Subscri pts • • • •
• .304
Index-Names
.305
Index Data Items.
• .305
OCCURS Clause
• • 305
DEPENDING ON Option
• • • 305
SET Statement
. • • •
.306
SEARCH Statement. • .
. .307
Building Tables
• • • • • • • 309
Queue Structure Considerations. •
.309
Accessing Queue Structures through
COBOL
• • • • • • • • • • • • . 312
Specifying ddnames with Elementary
Sub-Queues. • • . • • • •
• .313
Rules for Queue Structure
Description • • • • • • •
.315
CALLING AND CALLED PROGRAMS
.316
Specif ying Linkage • • • • • •
• .316
Linkage in a Calling COBOL Program • • 317
Linkage in a Called COBOL Program • • 317
Dynamic Subprogram Linkage • • . • • 318
Correspondence of Identifiers in
Calling and Called Programs
• • 322
File-Name Arguments • • • • • •
.322
Linkage in a Calling or Called
Assembler-Language Program • •
• • 322
Conventions Used in a Calling
Assembler-Language Program • • • • • 323
Conventions Used in a Called
Assembler- Language Program • • • • 325
Communication with Other Languages • • 326
Sample CALLING and CALLED Programs • . • 327
Link-Editing Programs •• • •
.331
Specifying Primary Input. •
.332
Specifying Additional Input
.332
INCLUDE Statement
.333
LIBRARY Statement
.333
ALIAS Statement
.333
NAME Statement. •
.333
ENTRY Statement
.334
ORDER Statement
.334
PAGE Statement. •
.334
p·rograms Compiled with the DYNAM
and/or Resident options • • • • • • .334
Specifying DYNAM/RESIDENT
• .335
Specifying NODYNAM/RESIDENT
• .335
specifying NODYNAM/NORESIDENT
.336
Linkage Editor Processing
• .338
Example of Linkage Editor
Processing. • • • • • • • •
• .339
Overlay Structures • • • • • • e • • • • 340
Considerations for overlay.
• .340
Linkage Editing with Preplanned
Overlay • • • • • • • • •
• .340
Dynamic Overlay Technique
• • 341
Loading Programs • • • • • • •
• .346
Specifying Primary Input • •
• .346
Specifying Additional Input
• .346
LIBRARIES • • • • • • • •
• .347
Kinds of Libraries • • • •
• .347
System Libraries Used in COBOL
Applications • • • • • •
• .347
Link Library.
• • • • • • 347
Procedure Library
• • 348
Sort Library • • •
• .348
COBOL Subroutine Library
• • • 348
Libraries Created by the user
• • 349
Automatic Call Library.
• .349
COBOL Copy Library.
• .349
COpy Statement •
• • • • • • • 351
BASIS Card. • • • • • • • •
• .351
JOB Libr ary
• • 353
Sharing COBOL Library Subroutines • • • 353
Concatenating the Subroutine Library .353
Creating and Changing Libraries
• • 354
USING THE CATALOGED PROCEDURES • • • • • 356
Calling Cataloged Procedures..
• .356
Data Sets Produced by Cataloged
Procedures. • • • • • . • •
• .356
Types of Cataloged Procedures
•• 357
programmer-Written Cataloged
Procedures. • • • • • • . • •
• .357
Testing Programmer-Written
Procedures. • • • •
• • • • • • 357
Adding Procedures to the Procedure
Library • •.• • • • • • • • • • • • 357
IBM-Supplied cataloged Procedures • • 358
Procedure Naming Conventions.
.359
Step' Names in Procedures • • • • • • 359
unit Names in Procedures..
• .359
Da ta Set Names in Procedures • • • • 359
COBUC Procedure
• • 359
'COBUCL Procedure • • • . • • • • • . 359
COBULG Procedure. •
• .359
COBUCLG Procedure
• . 361
COBUCG Procedure.
• .361
Modifying Existing Cataloged Procedures 362
overriding and Adding to cataloged
Procedures.
• • • • • • • • • • • • 362
Overriding and Adding to EXEC
Statements. • • • • • •
• .362
Examples of Overriding and Adding
to EXEC Statements • • . • • • • • • 362
Testing a Procedure as an In-Stream
Pr ocedur e
• • • • •
• .363
Overriding and Adding to DD
Statements
•••••
• .364
Examples of Overriding and Adding
to DD statements • • • • •
.364
using the DDNAME Parameter. •
.366
Examples of Using the DDNAME
Parameter • • • • • • • •
.' • • 366
USING THE SORT/MERGE FEATURE.
.368
Sort/Merge DD Sta temen ts • • •
...368
Sort Input DD Statements • •
.368
sort output DD statements
.368
Sort Work DD Statements • • • • • • • 368
SORTWKnn Data Set considerations • • 368
Input DD Statement. •
.369
OU t put DDS tat men t • • •
• . • 36 9
SORTWKnn DD statements. •
• • • 369
Additional DD Statements. •
.370
Sharing Devices between Tape Data Sets .370
Using More Than One Sort/Merge
Statement in a Job • • • • • • • • • • . 370
SORT Program Example • • . • • • • • . • 370
cataloging SORT/MERGE DD Statements • • 371
Linkage with the SORT/MERGE Program • • 371
Completion Codes • • • • • • • • • • 371
Terminating the Sort Program from
the COBOL PROGRAM • • • • • • •
.372
Locating Sort/Merge Record Fields • . • 372
Locating Last Record Released to
Sort/Merge by an Input procedure •
.372
.372
Sort/Merge Checkpoint/Restart
Efficient program Use
•• • •
.372
Data Set Size • • • • • • •
. .373
Main storage Requirements • • • • • • 373
.373
Sort/Merge Diagnostic Messages
Defining Variable-Length Records •
.374
.374
Sorting Variable-Length Records
Sort/Merge for ASCII Files • •
.375
Other Collating Sequences
. . . 375
OS/VS Sort/Merge Debug Feature
.377
USING THE SEGMENTATION FEATURE
.378
Using the Perform Statement in a
Segmented Program • • • . • • •
.378
Operation . • • . • • • • • • • • • • 379
LANGLVL Option and Re-Initialization .379
Compiler Output • • • • • • • • • • • 379
USING THE CHECKPOINT/RESTART FEATURE • • 394
.394
Taking a Checkpoint
Checkpoint Methods • • • •
.394
DD statement Forma ts • • • •
. . • 394
Designing a Checkpoint • • • . •
.396
Messages Generated during Checkpoint .396
Restarting a Program •
.396
RD Parameter • • •
.396
.397
Automatic Restart
.397
Deferred Restart •
CHECKPOINT/RESTART DATA SETS
.398
USING THE COMMUNICATION FEATURE
.401
Writing a Message Control Program
.404
Functions of the Message Control
Progra m
• • . • •
.404
User Tasks . • . • • • • • . . • • • • 404
Defining the Buffers. • • . •
.426
Activating and Deactivating the
Message Control Program
• . • . • • 426
Defining the MCP Data sets and
Process Control Blocks. •
.427
Defining Terminal and Line Control
Areas • • • • • : • • • •
• .427
Designing the Message Handler • • • 429
ANS Standard MCP Requirements
•• 432
ENABLE/DISABLE: Operator Command
Interface • • • • • • • • • • • • • 432
ENABLE/DISABLE--KEY Phrase • • • • • 433
ENABLE/DISABLE INPUT TERMINAL • • • 433
ENABLE/DISABLE INPUT (without
TERMINAL)
••••.•••
.434
ENABLE/DISABLE OUTPUT
•• 434
Specifying Characteristics for
Symbolic Destinations • • • • • • • 435
communications Job Scheduling (CJS) 436
Summary of ANS Standard MCP
Requirements • • • • • • • • • . • • 441
JCL for the MCP • • • • . . • •
• .444
Assembling, Link-Editing, and
Executing an MCP • • •
• .444
Assemblinq an MCP
• • 445
Link-Edi ti ng an MCP • • • • • • • • 445
Executing an MCP • •
• • • 445
Writing a TCAM-Compatible COBOL Program 446
~esting a COROL TP Program..
• .446
Communicating between a COBOL
Program and the MCP
• • • • 449
Defining the Interface. • •
• .449
Activating the Interface • • • • • • 455
Transferring Messages between the
COBOL Program and the MCP
• • • •• 455
Deacti va ting the Interface • • • • • 455
Additional Interface Considerations 455
Using TCAM Service Facilities
•• 456
MACHINE CONSIDERATIONS • . • •
•
Minimum Machine Requirements
Compiler Size Requirements •
OS/VS2 and the Region Parameter
Intermediate Data Sets Under
OS/VS2, Release 1 • • • • • • •
Execution Time Considerations
Sort/Merge Feature Considerations
APPENDIX A: SAMPLE PROGRAM OUTPUT
•
•
•
•
.457
• 457
.457
.457
• .458
• .458
• .460
.461
APPENDIX B: COBOL LIBRARY SUBROUTINES .472
Subroutines for Subprogram Linkage • • • 472
ENTER Subroutine (ILBONTRO)
•• 472
NORES Initialization Subroutine
(ILBOBEGO) • • • • • • • • • • • • • 472
Object-Time Options Subroutine
(I LBO P RM0 ) • • • • • • • • • • • • • 4 7 2
STOP RUN Subroutine (ILBOSRVO) • • • 472
STOP RUN Messages Subroutine
(ILBOMSGO) . • • • • . • • • • • • • 472
STOP RUN Termination Subroutine
~LBOSTTO}
. • • • • • • • • • • • • 472
Object-Time Program Operations • • • • • 473
COBOL Library Conversion Subroutines .473
Separate Sign Subroutine (ILBOSSNO) 473
COBOL Library Arithmetic subroutines .476
COBOL Library Subroutines for Testing
Conditions at Object Time • • • • • • 476
Class Test Subroutine (ILBOCLSO) •• 476
COMPARE Subroutine (ILBOVCOO)
.476
Compare with Figurative constant
Subroutine (ILBOIVLO)
••••
.476
COBOL Library Data Manipulation
.476
Subroutines •• • • • • • • • •
MOVE Subroutine (ILBOVMOO and
ILBOVM01)
• • • • • • . • • • • • • 476
MOVE Subroutine for System/370
(ILBOSMVO) • • • • • • • • • •
.476
MOVE to Alphanumeric-Edited Field
Subroutine (ILBOANEO)
• • • . • • • 476
MOVE to Numeric-Edited Field
Subroutine (ILBONEDO)
• • • 476
MOVE Figurative Constant
(ILBLOANFO)
•••••••
.477
TRANSFORM Subroutine (ILBOVTRO)
• • 477
STRI NG Subroutine (ILBOSTGO) • • • .477
UNSTRING Subroutine (ILBOUSTO) • • . 477
IN SPECT Subroutine (ILBOl NSO)
.477
COBOL Library Data ~anagement
.477
Subroutines • . • • • • • • • .
DISPLAY, TRACE, and EXHIBIT
.477
Subrou tine (IL BODSPO)
••••
DISPLAY Subroutine (ILBODSSO)
.477
.477
ACCEPT subroutine (ILBOACPO) •
Generic Key START Subroutine
(ILBOSTR 0) • • • . . • . • • • • • .478
Checkpoint Subroutine (lLBOCKPO) • • 478
Wait Subroutine (ILBOWAT)
.478
Error Intercept Subroutine
.478
(I LBOE RR0) . . • • • • . •
Error Intercept Subroutine
.478
(ILBOSYNO)
•• • • • •
Label Handling SUbroutine
(1LBOLBLO)
• • . • .
.478
Printer overflow Subroutine
(ILBOPTVO) • • • • • • • •
· • • 478
Printer spacing Subroutine
(ILBOSPAO) • • • • • • • •
· . . 478
B5AM WRITE/CLOSE and BDAM OPEN
.478
Subroutine (ILBOS AMO)
.•••
• • 478
B5AM READ Subroutine (ILBOSPNO)
.479
Q5AM I/O Subroutine (ILBOQIO)
DCB Exit Subroutine (ILBOEXTO) · . • 479
VSAM Initialization Subroutine
(1LBOINTO) • • . . • • • • • • • • • 479
VSAM open and Close Subroutine
(1LBOVOCO) • • • • • • • • • • • • • 479
VSAM Action Request Subroutine
.479
(1LBOVIO 0) • • • • • • • • • •
.479
RECEIVE Subroutine (ILBORECO)
RECEIVE Initialization Subroutine
(1LBORNTO) • • • • • • • •
• • • 479
Queue Analyzer Object-Time
.479
Subroutine (ILBOSQAO)
Queue Structure Description
Subroutine (ILBOQSUO)
••••
.479
Messag e Count Subroutine (ILBOMSC) .479
Queue Structure Scan
(Communications) subroutine
(1LBOQSS)
• • • • • • • • • • • • • 479
Job Scheduler Subroutine (ILBOSCD) .479
ENABLE/DISABLE Subroutine (ILBONBL) 480
Communications Job scheduler
Utility (ILBOCJS)
• • . • • • • • • 480
Declarative Save Area Chaining
Subroutine (ILBOCHNO)
• • • • • • • 480
GETCORE Subroutine (ILBOCMMO)
.480
SEND Subroutine (ILBOSNDO) • • • • • 480
SEND Initialization SUbroutine
(ILBOSNTO) • • • • • • • • • • • • • 480
COBOL Library Subroutines for Special
Features • • • • • • • • • • • • • • • 480
Sort/Merge Feature Subroutine
(I L BO S RT 0) • • • • • • • • • • • • .480
Merge Subroutine (ILBOMRGO)
• .480
Sort Subroutine (ILBOSMGO) • • • • .480
sort Deb ug S ubro utin e (I LBOSDBO) • .480
Alternate Collating Sequence
Compare Subrou ti ne (ILBOAC S) • • . .481
SEARCH Subroutine (ILBOSCHO) • • • • 481
Segmentation Subroutine (II.BOSGMO) .481
GO TO DEPENDING ON Subroutine
(ILBOGDOO) • • • • • • . • • • • • • 481
Date-and-Time Subroutine (ILBODTEO) 481
3886 optical Character Reader
Interface Subroutine (ILBOOCRO)
• . 481
ABEND Request Subroutine (ILBOABNO) 481
Ob ject -Time Debuggin g
• • • • • • • • .481
Debug Control Subroutine (ILBODBGO) 481
Use-for-Debugging Subroutine
(I LB OB UG )
• • • • • • • • • • • • • 482
Flow Trace S ubrou tin e (ILBOFLWO) • . 482
Statement Number Subroutine
(ILBOSTNO) • • . • • • • • • • • • • 482
Symbolic Dump Subroutine (ILBOD10
and ILBOD20) • • • • • • • • • • • • 482
SYMDMP Error Message Subroutine
(IL BODBEO) • • • • • • . • • . • • .482
COUNT Initialization Subroutine
(ILBOTCOO) • • • • • • . • • ~ • • • 482
COUNT Frequency Subroutine
(ILBOCT10) • • • • • • . • • • • • • 482
COUNT Termination Subroutine
(ILBOTC20) • • • • • • . • •
• • 482
COUNT Print Subroutine (ILBOTC30)
.482
Object-Time Debugging under Information
Management System (PP5734-XX6) • •
.483
SPIE Subroutine (ILBOSPIO) • • . • • 483
Calling And Storage Information
.483
APPENDIX C: FIELDS OF THE DATA CONTROL
BLOCK • • • • • • • • • • • •
• • • 490
APPENDIX D: COMPILER OPTIMIZATION
.496
Performance Considerations • • • • . • .496
Block Size for compiler Data Sets
.496
How Buffer Space Is Allocated to
Buffers • • • • • • . • • • • • • • • • 497
APPENDIX E: INVOCATION OF THE COBOL
COMPILER AND COBOL COMPILED PROGRAMS • • 499
Invoking the COBOL compiler
• • 499
Invoking COBOL compiled Programs • • • 500
APPENDIX F: SOURCE PROGRAM SIZE
CONSIDERATIONS • • • • • •
• .501
Compiler Capacity
• .501
Minimum Configuration SOURCE
PROGRAM Size • • • • • • • •
• .501
Effective storage Considerations • • • • 501
Linkage Editor capacity
• .502
APPENDIX G: INPUT/OUTPUT ERROR
CONDITIONS. • • • • • •
• • • • • 504
APPENDIX H: CREATING AND RETPIEVING
INDEXED SEQUENTIAL DATA SF.TS • • •
.510
Creating an Indexed Data Set • • . . 510
Retrieving an Indexed Data Set • • . 512
APPENDIX I: CHECKLIST FOR JOB CONTROL
PROCEDURES • • • • • • • • • • • • • . • 514
compilation
• • • • • • • • . • . . . . 514
Case 1: Compilation Only -- No
Object Module Is to Be Produced
• . 514
Case 2:
Source Module from Input
Stream. • • • • • • •
.514
Case 3:
Object Module Is to Be
Punched
. • • • • • • • • . • • . • 514
Case 4: Object Module Is to Be
Passed to Linkage Editor. • •
.514
Case 5:
Object Module Is to Be
Saved • • • • • • • • . . • • • • • 515
Case 6:
COpy Statement in COBOL
Source Module or a BASIS Card in
the Input Stream. • . • . • •
.515
Linkage Editor . • . . • . . • . • • . • 515
Case 1: Input from Previous
Compilation in Same Job
. • • • . . 515
Case 2:
Input from System Input
St re am • • • • . • . . . . • • • • • 515
Case 3: Input Not from Compilation
in Same Job
• • • • •
.515
Case 4:
Output to Be Placed in
Link Library. . • . • • • •
.516
Case 5:
output to Be Placed in
Private Library
• • • • • . • • • . 516
Case 6:
output to Be Used Only in
this Job. • • • • • • • •
.516
Execution Time. • • . • • • •
.516
Case 1:
Load Module to
Executed Is in Link Li brary
• . • .516
Case 2:
Load Module to Be
Executed Is a Member of Private
Library
•••
516
Case 3:
Load Module to Be
Executed Is Created in Previous
Linkage Editor Step in Same Job • . 517
Case 4:
Abnormal Termination Dump .517
Case 5: DISPLAY Is Included in
Source Module • • • • . • . . • • • 517
Case 6: DISPLAY UPON SYSPUNCH Is
Included in Source Module • • • • • 517
Case 7: ACCEPT Is Included in
Source Module (Except for Format 2
or ACCEPT MESSAGE) • . . • • . . • . 517
Case 8: Debug Statements EXHIBIT
or TRACE Are Included in Source
Module • • • • • . • • • . • . . • • 517
Case 9: Object Time Symbolic
Debugging a pt ions
.517
Case 10: COUNT Option
..•.
.517
Fe
y
• • • • • • • • • •
APPENDIX J: FIELDS OF THE GLOBAL TABLE .519
Task Global Table
. • 519
Program Global Tab Ie • • . • . •
• 527
APPENDIX K: DIAGNOSTIC MESSAGES
Compile-Time Messages
Object-Time Messages •
completion Codes •
Informative Messages •
. . .,
.529
. • 529
.529
.529
.529
Diagnostic Messages -- MCS
Consid erations • • .
COBOL Object Program Unnumbered
Messages • • . • • •
Queue Analyzer Messages • • • • • •
• .537
· .538
• .539
APPENDIX L: RESOLVING COBOL COMPILER
PROBL~MS
• .543
AFPENDIX M: 3886 OPTICAL CHARACT~R
READER PROCESSING
••••
OCR COBOL Capabilities • . • . • • •
· .544
• .544
OCR I/O Requests • • • . • • • • • .
544
OCR STATUS KEY. • • • . • • . •
:545
Implementing an OCR Application
.549
Document Design
. . . . . • ..
.549
Do cu men t Des c rip t ion • . . . . •
. 550
COBOL File and Record Descriptions • . 552
Procedural Code
. . • • • . . • . 552
Exception Handling with ILBOOCRP . . 552
Sample Program • . . • . • . • • . • • 553
Format Pecord Assembly Example . • • 553
Processing Tapes from the 3886 OCR,
Model 2
. • • 560
INDEX
.561
Figure 1. Job Control Procedure
21
Figure 2.
Using a Cataloged Procedure 21
Figure 3.
Control Statements
• 22
Figure 4.
General Format of Control
23
Statements • • • • • • • •
26
Figure 5. JOB Statement • • • •
• 33
Figure 6.
EXEC Statement • • • •
Figure 7.
Significant Characters for
Compiler 0 ptions
.......... .
• 38
Figure 8.
Compiler, Linkage Editor,
46
and Loader PARM options
••••
Figure 9.
The DD Statement (Part 1
53
of 3)
• .. • • • • • • • • • • ..
Figure 9.
The DD Statement (Part 2
of 3)
• • • • • • • • • .. • • • • • 54
Figure 10.
Device Class Names
Required for IBM-Supplied Cataloged
Procedures
• • • • . .. .. • • • • • 59
Figure 11.
Mass Storage Volume states
64
Figure 12.
Data Set References
66
Figure 13.
Example of a Batch
Compilation • • • • • • • • • .. • • • • 72
Figure 14.
Creation of Four Toad
Modules with Programs PROG1 and PROG2
and BASIS Library Members PAYROLL and
PAYROLL2
• • • • •
• • 73
Figure 15.
Data Sets Used for
Compilation
• • • • •
• • • • 75
Figure 16.
Data Sets Used for linkage
77
Editing • • • • • • • • •
Figure 17.
Determining the File
• • 84
Processing Technique • .. • •
Figure 18. COBOL Clause for Physical
sequential File Processing
• • • • • • 86
Figure 19.
DEN Values
.......
86
Figure 20.
DD statement Parameters
Applicable to Physical sequential
OUTPUT Files • • .. • • • • . • . • . • • 89
Figure 21.
DD statement Parameters
Applicable to Physical sequential
INPUT and 1-0 Files •• • • • • • • • • 90
Figure 22.
Directly organized Data as
93
it Appears on a Mass storage Device
Figure 23.
Sample Format of the First
Two Tracks of a Direct File • . • • • • 94
Figure 24.
Sample Space Allocation
for sequentially Created Direct Files . 96
Figure 25.
Sample Space Allocat~on
for Randomly Created Direct Files • • • 97
Figure 26.
Mass Storage Device
• 103
Overhead Formulas
• • • •
Figure 27.
Mass Storage Device
.103
Capacities
•••••••••
Figure 28.
Mass storage Device Track
.104
capacity
•••••••••
Figure 29.
Partial List of Prime
Numbers (Part 1 of 2)
• • • • • • • • • 105
Figure 30.
Sample Program for a
Randomly Created Direct File (Part
of 2)
.•••••.••.••••
.106
Figure 31.
Direct File Processing on
Mass Storage Devices • . • • • • •
.108
Figuri~32.
JCL Applicabie to Directly
Organizeq Files
.......
109
&
• • • •
Figure 33.
Relatively Organized Data
as it Appears on a Mass Storage nevice .111
Figure 34.
Sample Format of Two
Tracks of a Relative File
• • • . • 111
Figure 35.
Sample program for
Rela ti ve File Processing (Part
of 4) • 114
Figure 36.
Relative File Processing
on Mass Storage Devices
• 118
Figure 37.
JCL Applicable to
Relatively organized Files
· • 120
Figure 38.
Track Index
• • 120
Figure 39. cylinder Index
• 121
Figure 40.
Blocked Records on an
Indexed File • • • . • • • • •
• 121
Figure 41.
Unblocked Records on an
Indexed File
• • . • • • • • • • • • . 122
Figure 42.
Cylinder Overflow Area • • • 123
Fi~ure 43.
Independent Overflow Area .123
Figure 44.
DD statement Parameters
Applicable to Indexed Files opened as
Output
. • • • • • . • • . • • • • • • 126
Figure 45.
Example of DD Statements
for New Indexed Files • • • . • • . • • 127
Figure 46.
DD statement Parameters
Applicable Indexed sequential Piles
Opened as INPUT or 1-0 • . . . • . • • . 129
Figure 47.
Indexed sequential Pile
Processing on Mass Storage Devices
• • 131
Figure 48.
DD Statement Parameters
Frequently Used in Creating Data sets
.132
Figure 49.
Parameters Frequently Used
in Retrieving PreviouslY Created Data
Sets
. • • • • . • • • . . . . • • . . 138
Figure 50.
Parameters Used To Specifv
unit Record Devices . • . • • • • • • . 141
Figure 51. Links between the SELECT
Statement, the DD statement, the Data
Set Label, and the Input/Output
Statements • . • . • • • . • •
· . 143
Figure 52. Flow of Control in COBOL
After Error Detected on .
BSAM/QISAM/BDAM/BISAM I/O.· . • • • • • 145
Figure 53. Flow of Control in COBOL
147
~fter Error Detected on QS,AM I/O
jig~~e 54. ·Ex~mpl~ of Use of GIVING
Option in Error Declarative (Part 1 of
3)
••••••••••••••••
•
Figure 55.
Recovery from an Invalid
Key Condition or from an Input/Output
Error
• • • • . • .
• • • .
Figure 56.
Input/Output Error
Processing Pacilities • • • •
F i q u r e 5 7 • Ex it Lis t C od e s
• • • • ·
Figure 58.
Parameter List Formats
Figure 59.
Label Routine Return Codes
Figure 60.
Fixed-length (Format F)
Records . • • • . • • • • , • • •
Figure 61.
Unspecified (Format U)
Records • • • • • • • • • . • • .
Figure 62.
Unblocked V-Mpde Records
Figure 63.
Blocked V-~ode Records
·
. 150
.154
.155
• 158
.158
158
.160
• 161
.162
. 162
Figure 64.
Fields in Unblocked V-Mode
Records • • • • • • • • • • • • • • • • 163
Figure 65.
Fields in Blocked V-Mode
Records •• • • • • • • • •
.163
Figure 66.
First Two Blocks of
VARIABLE-FILE-2 • • • • •
• .164
Figure 67.
Control Fields of an
S-Mode Record • • • • • • • •
• .166
Figure 68.
One Logical Record
Spanning Physical Blocks • • • • • • • • 166
Figure 69.
First Four Blocks of
SP AN- F I L E • • • • • • • • • • •
• • 167
Figure 70.
Advantage of S-Mode
Records Over V-Mode Records
• • 167
Figure 71.
Direct and Sequential
Spanned Files on a Mass Storage Device 168
Figure 72.
Calculating Record Lengths
When Using the OCCURS Clause with the
DEPENDING ON option • • • • • • . • • • 171
Figure 73. Defining a VSAM Indexed
Data Set (KSDS) with Both Primary and
Alternate Keys • • • • • • • • • • • • • 178
Figure 74.
status Key Values And
Their Meanings. • • • • • • • • •
.184
Figure 75.
Error Handling Actions
Based on COBOL Program Coding..
• .185
Figure 76.
(Part 1 of 2) Status Key
Values for OPEN Requests. • • •
• .187
Figure 77.
(Part 1 of 2) Status Key
Values for Action Requests. • •
• .192
Figure 78.
COBOL Statements
Frequently Used for Writing into a
VSAM Data Set • • • • • • • • • . • . • 194
Figure 79.
COBOL Statements
Frequently Used for Retrieving Records
From a VSAM Data Set • • • • • • • • • • 196
Figure 80.
COBOL statements
Frequently Used for Updating a VSAM
Data Set • • • • • • • • • • • . • • • • 199
Figure 81.
Sample Identification and
Environment Division Output Listing •• 204
Figure 82.
Sample Data Division
output Listing • • • • • • • • • • • • • 206
Figure 83.
Sample Procedure Division
Qutput Listing • • • • • • • • • • • • • 208
Figure 84.
Sample Summary Listing • • • 209
Figure 85.
Individual Type Codes Used
in SYMDMP output
• • • • • • • • • • • 219
Figure 86.
Using the SYMDMP Option to
Debug the Program TESTRUN (Part 1 of
11)
••••••••••••••
• .220
Figure 87.
Examples of Compiler
Output (Part 1 of 4) • • • • • •
• .232
Figure 88.
A Program that Produces
compiler Diagnostics and Explanations .239
Figure 89.
Glossary Definition and
Usage • • • • • • • • • • • • •
.239
Figure 90.
Symbols Used in the
Listing and Glossary to Define
Compiler-Generated Information
.240
Figure 91.
Linkage Editor output
Showing Module Map and Cross-Reference
List.
• • . . • • • • • • . • • • . 241
Figure 92.
Module Map Format Example .244
Figure 93.
Execution Job Step output .245
Figure 94.
system Message
Identification Codes
. • . • • • . • . 246
Figure 95. Program with USE FOR
DEBUGGING • • • • • • . • • • • • • • . . 250
Figure 96.
Example of Program Flow
• . • . . . • • . • • • . • • 252
Figure 97.
Selective Testing of B • . . 253
Figure 98.
COBOL Program That will
Abnormally Termina te (Part 1 of 3) • • .264
Figure 99.
Load List of program That
will Abnormally Terminate
.267
Figure 100. Program with Data
Interrupt (Part 1 of 5)
.269
Figure 101. Locating the QSAM Logical
Record Area • • . • • . . • . • • . • . 274
Figure 102. Logical Record Area and
Segment Work Area for BDAM and BSAM
Spanned Records • • • • • • . • • . • • 275
Figure 103. Fields of the RECEIVE Queue
Block
• • . •.
• . • • • • • 276
Figure 104. Fields of the SEND Queue
Block
. • • • • . • • • • •
.276
Figure 105. Structure of a TCAM
Record
.277
Figure 106. Codes Used in the TCAM
Control Byte
• • . • • • . • • • . • . 278
Figure 107. Data Format Conversion • . 289
Figure 108.
Relationship of PICTURE
to storage Allocation
• ~ • • • • • . • 292
Figure 109. Treatment of Varying
Values in a Data Item of PICTURE S9 • • 292
Figure 110. Using the STRING
Statement • • • •
• . • . • •
.298
Figure 111. Using the UNSTRING
Statement • • • •
• • . • • •
.299
Figure 112. Sample Showing GROUP
INDICATE Clause and Resultant Execution
Output
• • . • • . • • . • . • • • • . 302
Figure 113. Format of a Report Record
When the CODE Clause is Specified
.302
Figure 114. storage Layout for Table
Reference Example
• • • • .306
Figure 115.
Rules for the SET
Statement • • • • . • • • _ •
.307
Figure 116.
A Queue Structure with
Three Levels of Sub-Queues
• • • • • • 310
Figure 117.
A Sample Queue structure
Descripion
• • . • • . . • . • • • • . 311
Figure 118. Sample Message Retrieval
options
• • • • • • • • • • • 313
Figure 119. Using ddnames with Queue
Structures
••••...•••
.314
Figure 120. Format for Input to Queue
structure Description Routine
.315
Figure 121. Calling and Called
Programs. • • • • . • . . • • • •
.316
Figure 122. Sample Calling and Called
Programs Using Dynamic CALL and CANCEL
Stat e men t s ( Pa r t 1 0 f 3)
••••
• 3 19
Figure 123. Linkage Registers
.322
Figure 124. Effect of STOP RUN
Statement • • • • • • • • . • • •
.325
Figure 125. Sample Linkage Coding
Used in a Calling Assembler-Language
Program . • . . • • • . • • . • • • • • 326
Figure 126.
Sa_pIe calling and Called
Programs (Part 1 of 7) • • • • . .
.327
Figure 127. Save Area Layout and
contents
••••••.•••••
.332
Figure 128.
CALL with DYNAM and
RESIDENT
••••••••.••
• .335
Figure 129. CALL With NODYNAM and
RESIDENT. • • • . • • • • • •
• .335
Fioure 130. CALL with NODYNAM and
RESIDENT With CALL Literal Option • • • 336
Figure 131. CALL With NODYNAM and
NONRESIDENT • • • . • • • . • •
• .336
Figure 132.
Sample JCL for
Called/Calling Programs Compiled with
the DYNAM and RESIDENT options
.337
Figure 133. Sample JCL Used for a
Calling Assembler-Language Program and
a Called COBOL Program • • . • • •
.338
Figure 134. Specifying primary and
Additional Input to the Linkage Editor 339
Figure 135. overlay Tree Structure • . 341
Figure 136. Sample Deck for
Linkage-Editor Overlay Structure • • • • 342
Figure 137.
Sample COBOL Main Program
and Assembler-Language Subprogram
using Dynamic overlay Technique (Part
1 of 3)
• • • • • • • • ••
• .343
Figure 138. Format of a Library
• • . 348
Figure 139. Entering Source
statements into the COpy Library • • • • 350
Figure 140.
Updating Source
statements in a COpy Library. •
. .350
Figure 141. COBOL Statements to
Deduct Old Age Tax
• • • • • • • . • . 352
Figure 142. Programmer Changes to
Source Program • • • • • • . • • • • • • 352
Figure 143. Changed COBOL Statements
to Source COpy Library Statements
.352
Figure 144. Concatenating the
Subroutine Library
• • • • • • • • • • 354
Figure 145.
Example of Adding
Procedures to the Procedure Library
•• 358
Figure 146.
Statements in the COBUC
Procedure • • • . • • • •
• .360
Figure 147.
Statements in the COBUCL
Procedure • • • • • • • •
• • • • • 360
Figure 148. Statements in the COBULG
Procedure • • • • • • . •
• • • . • 360
Figure 149.
Statements in the COBUCLG
Procedure • • • • • • • •
• • • • • 361
Figure 150. Statements in the COBUCG
Procedure • • • • • • • •
• •• 361
Figure 151. Sort Feature Control
Cards
• • . • • • • • • • • • • • 370
Figure 152.
Sorting Variable-Length
Records Whose File-name Description and
sort-File-name Description Correspond .376
Figure 153. Segmentation of Program
SAVECORE • • • • • • • • • • • • • • • • 378
Figure 154. Sample segmentation
Program (Part 1 of 14)
••••
• .380
Figure 155. Restarting a Job at a
Specific Checkpoint Step
•• 398
Figure 156. Using the RD Parameter •• 399
Figure 157.
Modifying Control
Statements Before Resubmitting for
Step Restart. • • • • • • • •
• • • 399
Figure 158.
Modifying Control
Statements Before Resubmitting for
Checkpoint Restart • • • • • ,.
• .400
Figure 159.
Message Flow between
Remote stations and a COBOL Program •• 402
Figure 160.
A Message Control Program
for Communication Application (Part 1
of 20)
• • • • ••
• • • • • • 406
Figure 161. Macros that can be coded
in a Message Handler
• • . • . 430
Figure 162.
Replacing the Mer Jobname
CSECT
• • • • . • • • . •
.433
Figure 163. Exam?le of Message
Formation for a Fixed Line Size
Destination Supporting Vertical
positioninq . • • • • • • • • • .
.437
Figure 164: Communications Job
Scheduling • • • . • . . . • • • • • • . 439
Figure 165.
Sample CJS Application
(Part 1 of 2)
••••••••
.440
Figure 166.
ANS Standard MCP
Requirements (part 1 of 2) • • . • • . . 442
Figur& 167. Sample JCL for Testing a
Communication Job without TCAM.
.4u7
Figure 168.
Sample JCL for Running a
Communication Job in a Quasi-Terminal
Environment . • • . • . . . . . . . . . . 448
Figure 169.
Sample JCL for Running a
Communication Job with a Remote
Terminal • • . • • • . • . . . . • • • .448
Figure 170.
Creating a TCAM Data Set
for Testing without Terminals (Part 1
of 2)
•••••••••• • • • •
.451
Figure 171.
A COBOL Program That
Processes TCAM Messages (Part 1 of 2)
.453
Figure 172. Functions of corOL
Library Conversion Subroutines (Part 1
of 2)
•••••••••
• • • • • 474
Figure 173. Function of COBOL Library
Arithmetic Subroutines
• • • • . 475
Figure 174. Calling and storage
Information for COBOL Library
Subrou tines (Part 1 of 6)
.484
Figure 175. Data control Block Fields
for Physical Sequential Files (QSAM) . . 491
Figure 176. Data Control Block Fields
for Direct and Relative Files Accessed
Sequentially (BSAM)
• . . • . . . • • • 492
Figure 177. Data Control Block Fields
for Direct and Relative Files Accessed
Randomly (BDAM)
• • . • . . • • • . . • 493
Figure 178. Data Control Block Fields
for Indexed Sequential Files Accessed
Sequentially (QISAM) • • . • . • • . • • 494
Figure 179. Data Control Block Fields
for Indexed sequential Files Accessed
Randomly (BISAM) • • • • • • . • • • . . 495
Figure 180. sample Constant Area Used
in SYNADAF Processing (Part 1 of 3)
• • 505
Figure 181. A Sample Job to get a
.507
Dump of a Constant Area • • • •
Figure 182. Creating an Indexed Data
set • • • • • • • • • • • • . • •
.511
Figure 183.
Area Arrangement for
Indexed Data Sets • • • • • • • •
.512
Figure 184. Retrieving an Indexed
Data Set. • • • • • • • • • • • •
.513
Figure 185. General Job Control
Procedure for Compilation
• • • • • • • 514
Figure 186. General Job Control
Procedure for a Linkage Editor Job step 516
Figure 187. General Job Control
Procedure for an Execution-Time Job
St e p • • • . • • • • •
• • • • • • • 51 7
Fiqure 188. Fields of th~ Task Global
Table (Part 1 of 3)
• • • • • • • .520
Figure 189. Fields of the Program
Global Table
••••
• • • • • • 527
Figure 190. Format of COBOL Parameter
Data Area . • • • • • • • • • • • • • • 545
Figure 191. IBM-supplied Data
Division COpy Member (Part 1 oi 2)
.546
Figure 192. IBM-supplied Procedure
Di vision COP Y Member (Part 1 of 2) • • .548
Figure 193. OCR STATUS KEY Values
(Part 1 of 2)
• • • • • • • • • • • • • 550
Figure 194. Requesting OCR Functions
and Information Returned • • • • • • • • 553
Figure 195.
Sample Document • . • • • • 555
Figure 196 ... Format Record Assembly
Coding Example. • • • • . • • . •
.556
Figure 197. Sample Data . . . • . • • • 557
Figure 198. Sample COBOL OCR
Processing Program (Part 1 of 3)
.558
An OS/VS COBOL program can be processed
by the IBM Operating System.
The operating
system consists of a number of E!Q£gssing
££Qg~§ and a £2~!£~~g~~.
The processing programs include the
COBOL compiler# service programs, and any
user-written programs.
The control program supervises the
execution or loadi ng of the processing
programs; controls the location# storage,
and retrieval of data; and schedules jobs
for continuous processing.
A request to the operating system for
facilities and scheduling of program
execution is called a .iQ.l!..
For example# a
job could consist of compiling a program by
utilizing the COBOL compiler. A job
consists of one or more jQQ stg£2# each of
which specifies execution of a program.
The programmer can make requests to the
operating system by using job control
sta temen ts.
Each job is headed by a JOB statement
that identifies the job.
Each job step is
headed by an EXEC statement that describes
the job step and calls for execution.
Included in each job step are data
definit.ion (DD) statements, which describe
data sets and request allocation of
input/output devices.
£!1!!Qgl or in both (if they are not the
same).
The catalog itself is a data set
residing on one or more mass storage
devices. It is organi2ed into indexes that
relate each data set name to its location-the volume in which it resides and its
position within the volume. Only the data
set name and DISP parameter need be
specified to identify a cataloged data set
to the sys tern.
The catalog is originally created by a
utility program.
Once the catalog exists,
any non-VSAM data set residing on either a
mass storage device or a magnetic tape
volume can be cataloged automatically by
use of a catalog subparameter in a DD
statement that refers to the data set.
VSAM data sets are cataloged through Access
Method Services.
Several input/output devices grouped
together and given a single name when the
system is generated constitute a g,gyic~
class.
Each device class can be referred
a collective name.
For example# one
device class called SYSDA could consist of
all the mass storage devices in the
installation; another called SYSSQ c6uld
consist of all the mass storage devices and
tape devices.
to-by
The data processed by execution of any
processing program must be in the form of a
g~1~-2g1A data set is a named, organized
collection of one or more records that. are
logically related.
Information in a data
set mayor may not be restricted to a
specific type# purpose# or storage medium.
A data set may be# for example, a source
program, a library of SUbroutines, or a
group of data records that is to be
processed by a COBOL program.
Four basic operations are performed to
execute a COBOL program:
A data set resides in one or more
A volume is a unit of external
storage that is accessible to an
input/output device.
For example, a volume
may be a reel of tape or it may be a mass
storage device.
COMPILATION
• compilation
- Linkage editing
-Loading
• Execution
!.Qlumg§_
To facilitate retrieval of a data set,
the serial nrimber of the volume upon which
it resides can be entered, along with the
data set name l in either the system £S.glog
of data sets (SYSCTLG) or in the VSAM
18
Com pila tion is the process of
translating a COBOL source program into a
series of instructions comprehensible to
the computer, i.e., machine language. In
operating system terminology, the input
(source program) to the compiler is called
the 2QQ££~~Qgule_ The output (compiled
source program) from the compiler is called
the obj~£~_mod~le.
LINKAGE EDITING
OS/VS1
The linkage editor is a service program
that prepares object modules for execution.
It can also be used to combine tvo or more
separately compiled object modules into a
format suitable for execution as a single
program.
The executable output of the
linkage editor is called a !Q~g_~dule,
which must always be stored as a member of
a partitioned data set.
The OS/VS1 control program divides
storage into a numbe~ of discrete areas
called partitions. Job steps are directed
to these partitions using a priority
scheduling system; that is, jobs are not
executed as encountered in the job stream·
but according to a priority code. The
OS/VS1 control program provides for:
• priority scbeduling of jobs using the
class code
In addition to processing object
modules, the linkage editor can combine
previously edited load modules, with or
without multiple object modules, to form
one load module.
During the process of linkage editing,
external references between different
modules are usually resolved.
• Concurrent scheduling and execution of
up to 15 separately protected jobs
• Reading one or more input streams
Por furtber information about the
various optional features of the OS/Vs1
control program. see tbe publication Q~!li1
fl~nning_ang_U2~_~g1~g·
LOADING
OS/VS2
The Loader is a service program that
processes object and load modules, resolves
any references to subprograms, and executes
the loaded module.
All these functions are
performed in one step.
The Loader cannot
produce load modules for a program library.
For detailed information on the Loader,
see the publication Q~LY~_1ift~~g~£~itQ~
~n~_Lo~Q~~, where a discussion of invoking
the Loader can be found in "Using the
Loader."
The OS/VS2 control program divides
storage into areas called regions.
Like
OS/VS1, the OS/V52 control program uses a
priority scheduling system and provides for
concurrent execution of up to 255 tasks.
In addition, the OS/VS2 control program
provides for assignment of storage regions
on a variable basis according to a region
code. For further information about the
various optional features of the 05/'52
control program, see the publication !2~!~~
glgnni~_gng_a§g_~g1~~·
EXECUTION
Actual execution is under supervision of
the control proqram,which obtains a load
module from a library, loads it into main
storage, and initiates execution of the
machine language instructions contained in
the load mod ule.
The IBM as/vs COBOL Compiler and Library
operates under control of OS/VS1 or OS/VS2
(with or without TSO), and under the CMS
component of VM/370. OS/VS1 and OS/VS2 can
operate as independent systems or under
control of VM/370.
CONVERSATIONAL MONITOR SYSTEM
The Conversational Monitor System (CMS)
is a time-sharing system that depends upon
the control program component of Virtual
Machine Facility/310 (VM/370) for real
computer management. eMS provides an
extensive range of conversational
programming capabilities a t. a remote
terminal. The CMS command language
simplifies file and data handling through
the use of simple terminal commands.
For a
detailed description on the use of the
OS/VS COBOL Compiler and Library under CMS,
see the publication 1~H-Y~Ll1Q_£~~ Use£~~
~~igg_!Q£_£Q~Q1.
This guide contains a
list of restrictions and limitations· for
using the OS/VS COBOL Compiler under CMS.
Introduction
19
communication between the COBOL
programmer and the job scheduler is
effected through nine job control
statements (hereinafter called control
statements):
1.
Job sta tement
2.
Execute statement
3.
Data Definition statement
4.
PROe statement
5.
PEND statement
6.
Command Statement
7.
Delimiter statement
8.
Null Statement
9.
Comment Statement.
Parameters coded in these control
statements aid the job scheduler in
regulating the execution of jobs and job
steps, retrieving and disposing of data,
allocating input/output resources, and
communicating with the operator.
The job_§ll!ill!gnt (hereinafter called
the JOB statemen~ marks the beginning of a
job an4, when jobs are stacked in the input
stream, marks the end of the control
statements for the preceding job. It may
contain accounting information for use by
an installation's accounting routines, give
conditions for early termination of the
job, regulate the display of job scheduler
messages, assign job priority, request a
specific class for job scheduler messages,
specify the amount of main storage to be
allocated to the job, and hold a job for
later execution.
The ~~~tatem~nt (or EXEC
statement) marks the beginning of a job
step and identifies the program to be
executed or the cataloged procedure to be
used. It may also provide job step
accounting information, give conditions for
bypassing the job step, pass control
information to a processing program, assign
a time limit for the execution of the job
step and specify the amount of main storage
to be allocated.
The datLde.fiJl.itiQ1L§.tate~!l! (or DD
statement) describes a data set and
20
requests the allocation of input/output
resources.
The DD statement parameters
identify the data set, give volume and unit.
information and disposition, and describe
the labels and physical attributes of the
data set.
The £.RQ~§ls.lgm~:nl appears as the first
control statement in a cataloged procedure
or an in-stream procedure and is used to
assign default values to symbolic
parameters defined in the procedure.
The g~lilLsts.lgmg!ll appears as the last
control statement in an in-stream procedure
and marks the end of the in-stream
procedure.
For further information about
in-stream procedures, refer to the topic
"Testing a Procedure as an In-Stream
Procedure" in the chapter "Using t.he
Cataloged Procedures."
The £.Q!!.nnd_§!ate!!~n! is used by the
operator to enter commands through the
input stream. Commands can activate or
daactivate system input and output units,
request printouts and displays, and perform
a number of other operator functions.
The delimiter statement and the null
2i~~i are markers-in-an input stream.
The delimiter statement is used, when data
is included in the input stream, to
separate the data from subsequent control
statements. The null statement can be used
to mark the end of the control statements
for the entire job {preventing subsequent
statements from being associated with this
job) •
The comment statement can be inserted
before or-after-;Uy-control statement and
can contain any information deemed helpful
by the person who codes the control
statements. Comments can be coded in
columns 4 through 80. The comment cannot
be continued onto another statement.
If
the comment statement a ppears on a system
output listing, it can be identified by the
appearance of asterisks in colUmns 1
through 3.
The sequence of cont.rol statements
required to specify a jo,b is called a jQQ
control procedure.
For example, the job control procedure
shown in Figure 1 CQuld be placed in the
input stream to compile a COBOL source
module.
,
r-
IIIJOB1
IIISTEP1
JOB
EXEC
PGM=IKFCBLOO,PARM=DeCK
1/ISYSUT1
DD
OSNAME=&&UT1,UNIT=SYSDA,SPACE=(TRK,
OSNAME=&&UT2, UNIT=SYSSQ,SPACE= (TRK,
DSNAME=&&UT3, UNIT=SYSSQ,SPACE= (TRK,
OSNAME=&&UT4,UNIT=SYSSQ,SPACE=(TRK,
SYSOUT=A
S YSOUT= B
IIISYSUT2
DO
IIISYSUT3
IIISYSUT4
IIISYSPRINT
JIISYSPUNCH
DD
DD
00
DD
DD
IIISYSIN
I
(source deck)
f/*
J
J
(40»
(40»
(40»
(40»
I
J
f
I
I
I
I
I
*
1
L--
Figure
.J
1.
Job Control Procedure
In the illustration, JOB1 is the name of
the job.
The JOB statement indicates the
beginning of a job.
STEPl is the name of the single job step
in the job. The EXEC statement specifies
that the IBM OS/VS COBOL Compiler
(IKPCBLOO) is to execute the job. The
statement also specifies that a card deck
of the object module is to be produced
(PARM=DECK) •
The SYSUT1, SYSUT2, SYSUT3, SYSUT4,
SYSUT5 (if the SYMDMP or TEST option is
spec if ied in the PARM parameter of the EXEC
card), and SYSUT6 (if the LVL option is
specified in the PARM parameter of the EXEC
card) DD statements define utility data
sets, used by the compiler to process the
source module. The names of the data sets
defined by SYSUT1, SYSUT2, SISUT3, SYSUT4,
SYSUTS and SYSUT6 are &&UT1, S&UT2, &&UT3,
&&UT4, &&UTS and &&UT6, respectively.
SYSUT1 must be on a mass storage device
(UNIT=SYSDA). The system will allocate 40
tracks of space to SYSUT1
[SPACE=(TRK, (40»]. The other four utility
data sets are assigned either to any
available tape, in which case the SPACE
parameter is ignored, or to a mass storage
unit (UNIT=SYSSQ).
The SYSPRINT DO statement defines the
da ta set tha t is to be printed. SYSOUT= A
is the standard designation for data sets
whose destination is the system output
device, usually indicating that the data
set is to be listed on a printer.
The SYSPUNCH DD statement defines the
data set that is to be punched.
By
convention, SYSOUT=B designates a card
punch.
The SYSIN DD state.ent defines the data
set (in this case, the source module) that
is to be used as input to the job step.
The asterisk (*) indicates that the input
data set follows in the input stream.
The delimiter (/*) statement separates
data from subsequent control statements in
the input stream.
output from this job step includes any
diagnostic messages associated with the
compilation. They are printed in the data
set specified by SYSPRINT.
Note:
S ISO A, SYSSQ,
IBM-specified device
are to be used, they
at system generation
A, and Bare
class names.
If they
must be incorporated
time.
To avoid rewriting these statements, and
the possibility of error, the programmer
may place frequently used procedures on a
system library called the procedure
library.
A procedure contained in the
procedure library is called a cataloged
2~~~~~.
A cataloged procedure can be
called for execution by placing in the
input stream a simple procedure that may
require only the JOB and EXEC statements.
If slightly mOdified, the procedure in
the previous example can be cataloged,
i.e., placed in the procedure library.
For
example, if it vere cataloged and given the
name CATPROC, it could be called for
execution by placing the statements shown
in Figure 2 in the input stream.
,
t"
IIIJOB2
JOB
IIISTEPA
EXEC
IIISTEP1.SYSIN DO
J
(source deck)
11*
PROC=CATPROC
*
I
t
I
I
,
_____________- - J
I
Figure
2.
Using a Cataloged Procedure
In Figure 2, JOB2 is the name of the job.
STEPA is the name of the single job step.
The EXEC statement calls the cataloged
proced ure containing STEP1 to execute the
job step (PROC=CATPROC).
Job Control Procedures
21
A procedure can be tested before it is
placed in the procedure library by
converting i t into an in::§.tr!!S.!Lprocedut:~.
An in-stream procedure can be executed any
number of times during a job. For further
information about in-stream procedures,
refer to the topic "Testing a Procedure as
an In-stream Procedure" in "Using the
Cataloged Procedures. l1
•
i
The section "Control Statements," below,
shows the format and use of the parameters
and subparameters that can be specified for
each job control statement. Some
parameters of the statements are described
only briefly.
Por further information, see
the publication QSLIL!l~.L~~~!!£~. The
syntactic format descriptions in this
chapter can be used as a reference for the
exact format and for the use of each
parameter.
Func tion
I-----_t__
,JOB
I Indicates the beginning of a
I
I nev job and describes that
I
t job.
~
I
IIndicates a job step and
I describes that job step;
I indicates the load module or
I cataloged procedure to be
I executed.
I
lDescribes data sets, and
J controls device and volume
, assignment.
,EXEC
I
J
"User Pile Processing" and "Appendix I:
Checklist for Job Control Procedures"
explain, with numerous examples, the
preparation of job control procedures.
UDa ta Set Requirelllen ts" describes required
and optional data sets for compilation,
linkage editing, and execution time job
steps. The chapter "Using Cataloged
Procedures" provides informa tion about
using and modifying cataloged procedures.
,
IS ta temen t I
,
,
I
tDD
I
I
•
-+--
,
-t
1
1
I
f
1
I
I
I
I
~
I
1
1
-f
J
IdelimiterlSeparates data sets in the
I
I
input stream from control
I
,
, statements; it ma y folloll
,
J each data set that appears inl
I
I
I
the input stream, e.g., afterl
I
I a COBOL source module punchedl
I
) deck.
,
I
I
~
Icomment lcontains miscellaneous remarks 1
I
t a nd notes wri t ten by the
f
J
I programmer; it may appear
1
J
J anywhere in the job stream
1
I
J after the JOB statement
,
,
I
(except wi thi n data or
I
J
I -______________
source) •
t
LL
_
J
Figure
The COBOL programmer uses the control
statements shown in Figure 3 to compile,
linkage edit, and execute programs.
JOB MANAGEMENT
Control statements are processed by a
group of operating system routines known
collectively as job management. These job
management routines interpret control
statements and commands, control the flow
of jobs, and issue messages to both the
operator and the programmer. Job
management comprises tvo major components:
a job scheduler and a master scheduler.
The job_§chegul~ is a set of routines
that reads input streams, analyzes control
statements, allocates input/output
resources, issues diagnostic messages to
the programmer, and schedules job flow
through the system.
22
J.
control Statements
The master scheduler is a set of
routines-that accepts operator commands and
acts as the operator's agent within the
system. It relays system messages to the
operator, performs system functions at his
request, and resp_onds to his inquiries
regarding the status of a job or of the
system. The master scheduler also relays
all communication between a processing
program and the opera tor.
PREPARING CONTROL STATEMENTS
Except for the comment statement,
control statements are identified by the
initial characters // or 1* in card columns
1 and 2. The comment statement is
identified by the initial characters 1/* in
columns 1 through 3. Control statements
may contain four fields:
name, operation,
operand, and comment, as shown in Figure 4.
,
i-
t
J
J
I
J
I
J
I
I
I
t
f
r-
I
,
i
tL-______________
'optional.
__
•
t
•J
-f
•
•
..
Fields
4
I 11213
I
I
JOB
comments'
Job
operand'
I Il/Iname
operand
EXEC
comlllents'
Execute
J 1I/Iname l
operand
comments 1
Data Definitionl It/lname' DD
operand
co.ments l
Procedure
Il/tname' PROC
operation (command)
operand
Command
I 1111
Delilli ter
comments'
I 11*1
Null
J 1I1I
comments
Comment
1 11/1*
Pend
I 1I/Iname 1 PEND
r---
,
statement
t
Columns
,
,
,,
t
t
I
I
I
comments'
I
.,I
I
I
J
Figure
4.
General Format of Control statements
The name contains from one through eight
alphanumeric characters, the first of which
must be alphabetic. The name begins in
card column 3. It is followed by one or
more blanks. The name is used, as follows:
• To identify the control statement to
the operating system
• To enable other control statements in
the job to refer to information
contained in the named statement
The operand field is preceded and
followed by one or more blanks and may
continue through column 71 and onto one or
more continuation cards. It contains the
parameters or subparameters that give
required and optional information to the
operating system. Parameters and
sub parameters are separated by commas. A
blank in tbe operand field causes the
system to treat the remaining data on the
card as a comment. There are two types of
parameters: positional and keyword
(Figures 5, 6, and 9).
f2~tiQn~1~~met~:
• To relate DD statements to files named
in a COBOL source program
The operation field is preceded and
followed by one or more blanks. It may
contain one of the following operation
codes:
JOB
EXEC
DD
PROe
PEND
If the statement is a delimiter statement,
there is no operation field and comments
may start after one blank.
Positional
parameters are the first parameters in tbe
operand field, and they must appear in the
specified sequence. If a positional
parameter is omitted and other positional
parameters follow, the omission must be
indicated by a comma. If other positional
parameters do not follow, no comma is
needed.
Keyword Parameters: A keyword parameter
may be placed anywhere in the operand field
following the positional parameters. A
keyword parameter consists of a keyword,
followed by an equal sign, followed by a
single value or a list of subparameters.
If there is a subparameter list, it must be
enclosed in parentheses or single quotation
marks; the subparameters in the list mllst
be separated by commas. Keyword parameters
may appear in any sequence.
Sub parameters are either positional or
keyword.
positional and keyword
subparameters for job control statements
are shown in Figures 5, 6, and 9.
positional subparameters appear first in
the parameter and must be in the specified
sequence. If a positional sub para meter is
Job Control Procedures
23
omitted and other positional sub parameters
follow, a comma must indicate the omission.
optional comments must be separated from
the last parameter (or the 1* in a
delimiter statement) by one or more blanks
and may appear in the remaining columns up
to and including column 71. An optional
cOllment may be continued onto one or more
continuation cards. Comments can contain
blanks.
1 through 71 of cards or card images. If
the total length of a statement exceeds 11
columns, or if a parameter is to be placed
on separate cards, theoperatinq system
continuation conventions must be used •. To
continue an operand field:
1.
Interrupt the field at the end of a
complete parameter or subparameter,
including the comma that follows it,
at or before column 11.
2.
Include any commments desired by
following the interrupted field with
at least one blank.
Note: comments in the optional comments
fIeld follow different procedures from
those on the comment statement.
3.
Optionally, code any nonblank
character in column 12.
CONVENTIONS FOR CHARACTER DELIMITERS
4.
Code the identifying characters II in
columns 1 and 2 of the following card
or card image.
5.
continue the interrupted operand
beginning in any colUmn from 4 through
Commas, parentheses, and blanks are
interpreted as character delimiters. If
they are not intended by the programmer to
be used as delimiters, the fields in which
they appea r must be enclosed in single
quotation marks, indicating that the
enclosed information is to be treated as a
single field. When an apostrophe (or a
single quotation mark, since the same
character is used for either) is to be
contained within such a field, it must be
shown as two consecutive sinili-!l!!Qtatio!!'
marks (5-8 punch), ~Qi as a double
quotation mark (1-8 punch). For eXample,
Wm.
16.
comments other than those on a comment
statement can be continued onto additional
cards after the operand has been completed.
To continue a comments field:
1.
Interrupt the Gomment at a convenient
place.
2.
Code a nonblank character in column
O'Connor
should be shown as
'Wm.
O· 'Connor'
This convention applies to three fields:
programmer's name in the JOB statement,
information in the PARM parameter of the
EXEC statement, and accounting information
in the JOB and EXEC statements.
RULES POR CONTINUING CONTROL STATEMENTS
Except for the comment statement,
control statements are contained in columns
24
72.
3.
Code the identifying characters II in
columns 1 and 2 of the following card
or card image.
4.
Continue the comments field beginning
in any column after column 3.
Any control statements in the input
stream that the job scheduler considers to
contain only continued comments will print
on a system output listing with a 11* in
columns 1 through 3. Comments written on a
comment statement cannot be continued.
NOTATION FOR DESCRIBING JOB CONTROL
STATEMENTS
4.
The notation used in this publication to
define the syntax of job control statements
is as follow s:
1.
The set of symbols below define
control statements, but they are never
written in an actual statement.
Name
Joins lower-case
letters, words, and
symbols to form a
single variable
Itor" symbol
{ }
Indicate that the
enclosed is a group of
related items, only
one of which is
required
brackets
[
Indicate that the
enclosed are optional
items.
Brackets are
also used with
alterna ti yes to
indicate that a
default is assumed if
no alternative is
listed
ellipsis
2.
3.
5.
Lower-case letters, words, and symbols
appearing in a control statement
definition represent variables for
which specific information is
substituted in the actual statement.
6.
Blanks are used in Figures 5, 6, 8,
and 9 to improve the readability of
control statement definitions. In
actual statements, blanks would be
interpreted as delimiters.
Indicates alternatives
braces
superscript
Hot~:
Many of these defaults can be
changed at system generation time.
£Y£.QQ§~
hyphen
Indicates that the
preceding item or
group of items can be
repeated
1
2
3
The JOB statement is the first statement
in the sequence of control statements that
describe a job. The JOB statement can
contain the following information:
1.
Name of the job.
2.
Accounting information relative to the
job.
3.
programmer's name.
4.
Indication of whether or not the job
control statements are to be printed
on the system output listing.
5.
Conditions for terminating the
execution of the job.
6.
Job priority assignment, job scheduler
message class, and real or virtual
region size.
Indicates a footnote
reference
Stacked items, enclosed in either
brackets or braces, represent
alternative items.
No more than one
of the stacked items can be written by
the programmer.
Upper-case letters and words, numbers,
and the set of symbols listed below
are written in an actual control
sta teme nt exactly as shown in the
statement definition.
(Any exceptions
to this rule are noted in the
definition of a control statement.)
An underscore indicates a default
option.
If an underscored alternative
is selected, it need not be written in
the actual statement.
pigure 5 is a general format of the JOB
statement.
.Identifying the Job
Name
single quotation mark
asterisk
comma
equal sign
parentheses
period
slash
•
=
( )
/
{jobn~.!!n
The jobname identi.fies the job to the
job scheduler.
It must satisfy the
positional, length. and content
requirements for a name field.
No two jobs
being handled by a priority scheduler
should hav~ the same jobname.
Job Control Procedures
25
•
i
i
1
,Name
IOperation,
Operand
i
&-tI
~
I
I
I
I
t
gQsi!iQ.!!al..f.Yamet~
J
I
I
I
Illjobname JOB
H ([account-number] [*accounting-information) 1 2 3]
I
I
I
I
I
1[,programmer-name]· 5
1
I
I
J
I.
'.Kglwo£~n~1~:&2
1
H MSGLE VEL= (x, y) ]6
I [TIME= (minutes, seconds) ]
I [ CLASS=jobclass)
I
I(COND= «code,operator) [, {code, operator) ] .... 7) 8
I(PRTY=job priority]
I
I I [ MSGCt ASS=classname]
I
H REGION=valueK]
I
J(RD=reguestJ
J
I
*
I
J[RESTART=<{ stepname
} [,checkid])
f
I
stepname.procstepname
I
I[NOTIFY=user id]9
,
I r
{ HO LD }
] 10
•
I L TYPRUN=
SCAN
J
I
I
1
,
I
I
I
~
:
[ADDRSPC=
1
1
1
]
I
I
t
]
J
f
,
1
,
{~i!i} ]
:
1-_
-L-.::
~
J t If the information specified (account-number and/or accounting- informa tion) conta ins I
I
blanks, parentheses, or equal signs, the information must be delimited by single
I
, quotation marks instead of parentheses.
I 21f only account-number is specified, the delimiting parentheses may be omitted.
I 3The maximum number of characters allowed between the delimiting quotation marks is
J 142.
I 4If programmer-name contains any special characters other than the period, it must be
J enclosed within single quotation marks.
J 5The maximum number of characters allowed for programmer-name is 20.
I 6X = 0, 1, or 2 is the JCL message.
1 Y = 0 or 1 is the allocation message level.
I
Note that the value 1 may be used in place of (1~1).
I 7The maximum number of repetitions allowed is 7.
I 8If only one test is specified, the o~ter pair of parentheses may be omitted.
, 9For TSO only.
110SCAN is for OS/VS1 only.
l.-
Figure
1
I
I
J
,
1
I
1
1
J
,
I
I
I
.J
5.
JOB Sta tement
r-,
J (acctt,additional accounting infocmation) J
1.-
For job accounting purposes,tbe JOB
statement can be used to supply information
to an installa tion' s accounting procedures.
To supply job accounting information, code
the positional parameter first in the
operand field.
26
---'
Replace the term "acctl" with the account
number to which the job is charged; replace
the term "additional accounting
informationttwith other items required by
an installationts accounting routines. The
requirement can be established with a
cataloged procedure for the input reader.
otherwise, the account number ,is considered
optional.
• subparameters of additional accounting
information must be separated by
commas.
• The number of characters in the account
number and additional accounting
information must not exceed a total of
142.
• If the list contains only an account
number, the programmer need not code
the parentheses.
• If the list does not contain an account
number, the programmer must indicate
its absence by coding a comma preceding
the additional accounting information.
• If the account number or any
subparameter of additional accounting
information contains any special
character {except hyphens), the
programmer must enclose the number or
subparameter in apostrophes (5-8
punch). The apostrophes are not passed
as part of the information.
The person responsible for a job codes
his name or identification in the JOB
statement, following the job accounting
information. This positional parameter is
also passed to an installation'S routines.
As a system generation option, the
programmer's name can be established as a
required parameter. The requirement can
also be established with a cataloged
proced ure for the in pu treader. otherwise,
this parameter is considered optional.
Di~J215lzing All Control_st~1~~n12L
AllocaliQll~~d Te£~instiQn_~g~g~§
111~GLEn!J..
The MSGLEVEL parameter indicates whether
or not the programmer wants control
statements and/or allocation and
termination messages to appear .in his
output listing. TO receive this output,
code the keyword parameter in the operand
field of the JOB statement.
,
r-
I
I
1.
~
The letter "x" represents a job control
language message code and can be assigned
the value 0, 1, or 2.
When x = 0 is
specified, only the JOB statement,
incorrect control statements, and
associated diagnostic messages are
displayed.
When x = 1 is specified, input
statements, cataloged procedure statements,
and symbolic SUbstitution of parameters are
displayed. When x = 2 is specified, only
input statements are displayed.
The letter "y" represents an allocation
message code and can be assigned the value
o or 1. When y = 0 is specified, no
allocation, termination, or recovery
messages are displayed, unless an ABEND
occurs during problem program execution.
If an ABEN D occurs, termina tion messages
are di spla yed. When y = 1 is specified,
all allocation, termination, and recovery
messages are displayed.
• If the value 1 is selected for both
codes, the value may be specified once
without the parentheses; i.e.,
MSGLEVEL=l is the same as
MSGLEVEL= (1, 1).
• The number of characters in the name
cannot exceed 20.
• The default values are taken from the
reader procedure.
• If the name contains special characters
other than periods, it must be enclosed
in apostrophes. If the special
characters include apostrophes, each
must be shown as two consecutive
apostrophes, e.g., 'T.O·'NEILL'.
• If an error occurs on a control
statement that is continued onto one or
more cards, only one of the
continuation cards is printed with the
diagnostic messages.
• If the job accounting information is
not coded, the programmer must indicate
its absence by coding a comma preceding
the programmer-name.
• If neither job accounting information
nor prog rammer-name is prese nt# the
programmer need not code commas to
indicate their absence.
~~cifYing_conditiQn§_tor_~Q~_Iermi~ati~
EQlifrL
To eliminate unnecessary use of
computing time, the programmer might want
to base ·the continuation of a job on the
successful completion of one or more of
Job Control Procedures
27
Replace the word flrequest" with:
its job steps. At the completion of each
job step, the processing program passes a
number to the job scheduler as a return
code. The CONDparameter provides the
means to test each return code as many as
eight times.
If anyone of the tests is
satisfied, subsequent steps are bypassed
and the job is termina ted.
To specify conditions for job
termination, code the keyword parameter in
the operand field of the JOB statement.
,
~
ICOND=«code,operator), •• , (code,operator»)
L---
J
See the COND parameter on the EXEC
statement for a discussion of the operator
values and the codes issued by the compiler
and linkage editor at the end of a job
step.
to permit automatic step
restart
HC
to suppress the action of the
CHKPT macro instruction and not
to permit automatic restart or
deferred restart
NR
to request that the CHKPT macro
instruction be allowed to
establish a cheCKpoint, but not
to permit automatic restart.
Deferred restart is permitted
through specification of
RESTART on the resubmitted job.
RNC -- to permit step restart and to
suppress the action of the
CHKPT macro instr uction
Each of these requests is described in
greater detail in the following paragraphs.
RD=R: If the processing programs used by
the job do not include any CRKPT macro
instructions, RD=R allows execution to be
resumed at the beginning of the step that
causes abnormal termination.
If any of the
programs do include one or mo.re CHKPT macro
instructions, step restart can occur if a
step abnormally terminates before execution
of a CHKPT macro instruction; thereafter,
checkpoint restart can occur.
!2!~:
• The subparameters EVEN and ONLY cannot
be specified as part of the COND
parameter on the JOB statement.
The restart facilities are used in order
to minimize the time lost in reprocessing a
job that abnormally terminates.
These
facilities permit execution of jobs that
abnormally terminate to be automatically
restarted.
Execution of a job can be automatically
restarted at the beginning of the job step
that abnormally terminated (step restart)
or within the step (checkpoint restart).
In order for checkpoint restart to occur,
the CBKPT macro instruction must have been
executed in the processing program prior to
abnormal termination. The CHRP!' mac.ro
instruction is activated by the COBOL
source language RERUN clause. The RD
parameter specifies that step restart can
occur or that the action of the CHKPT macro
instruction is to be suppressed.
To request that step restart be
permitted or to request that the action of
the RERUN clause be suppressed, code the
keyword parameter in the operand field of
. the JOB statement.
•
L--,___________________________________________
~
RD=request
I
28
R
RD=NC or RD=RNC:
RD=NC or RD=RNC should be
specified to suppress the action of all
CHKPT macro instructions included in the
programs.
When RD=HC is specified, neither
step restart nor checkpoint restart can
occur.
When RD=RNC is specified, step
restart can occur.
RD=!!!.:
BD=NR permits a CHKPT macro
instruction to establish a checkpoint, but
does not permit automatic restart.
Instead, at a later time, the job can be
resubmitted and execution can begin at a
specific checkpoint.
(Resubmitting a job
for restart is discussed later.)
Before automatic step restart occurs,
all data sets in the restart step with a
status of OLD or MOD, and all data sets
being passed to steps following the restart
step, are kept.
All data sets in the
restart step with a status of NEW are
deleted.
Before a utoma tic checkpoint
restart oc~urs, all data sets currently in
use by the job are kept.
If the RD parameter is omitted and no
checkpoints are taken, automatic restart
cannot occur. I.f the RD parame~er is
omitted but one or more checkpoints are
taken, automatic checkpoint restart can
occur.
Replace the word stepname with the name of
the step in which execution is to be
restarted.
Replace the term "checkid" with
the 1- to 16-character name that identifies
the checkpoint within the step.
• For as/VS1 restart can occur only if
MSGLEVEL=1 is coded on the JOB
statemen t.
• If step restart is requested, each step
must be assigned a unique step name.
• If no RERUN clause is specified in the
user's program, no checkpoints are
written regardless of the disposition
of the RD parameter.
If the RESTART parameter is not
specified on the JOB statement of the
resubmitted job, execution is repeated.
• For detailed information on the
checkpoint/restart facilities, see the
publication OSLYS Ch~.!££oint/Restart.
• If execution is to be restarted at or
within a cataloged procedure step, give
both the name of the step that invokes
the procedure and the procedure step
name, as helow.
The restart facilities can be used if
the job is abnormally terminated and the
programmer wants to reSUbmit the job for
execution.
These facilities reduce the
time required to execute the job since
execution of the job is resumed, not
repeated.
"1
J
If execution is to be restarted at a
particular job step, code the keyword
parameter in the operand field of the JOB
statement before resubmitting the job.
r------------·------------------------------REST ART=s tepname
"1
I
L-
Replace the word "stepname" with the name
of the step at which execution is to be
restarted.
Replace step name with an
asterisk (*) if execution is to be
restarted at the first job step.
If execution is to be restarted at a
particular checkpoint within a particular
job step, code the keyword parameter in th~
operand field of the JOB statement before
resubmitting the job.
r--------I
L-
t
RESTART=stepname.procstepname
Execution of a resubmitted job can be
restarted at the beginning of a step (step
restart) or within a step (checkpoint
restart) •
In order for checkpoint restart
to occur, a program must previously have
had a checkpoint record written.
The
RESTART parameter specifies where execution
is to be restarted.
1
If execution is to be restarted at a
checkpoint r the resubmitted job must
inclUde an additional DD statement. This
DD statement defines the checkpoint data
set and has the ddname SYSCHK.
Do not
include a SYSCHK DD statement if step
restart is to be performed.
• If step restart is performed,
generation data sets that were created
and cataloged in steps preceding the
restarted step must not be referred to
in the restart step or in steps
following the restart step by means of
the same relative generation numbers
that were used to create them.
For
example, a generation data set assigned
a generation number of +1, would be
referred to as 0 in the restart step or
steps following the restart step.
• Backward references cannot be made to
steps that precede the restart step
using the following keyword parameters:
PGM, COND, SUBALLOC, and VOLUME=REF,
unless in the last case the referenced
statement includes ~OLUME=SER=(sert).
• For detailed information on the
checkpoint/restart facilities, see the
publication OS/VS_Che£~.Qoint/rtest~.£!.
-----------------,
BESTART=(stepname,checkid)
J
___________ J
Job Control Procedures
29
PRIORITY SCHEDULING JOB PARAMETERS
~tting
to make the job part of the group of
jobs to be time-sliced.
Time-slicing
permits the processing of tasks of
equal priority so that each is executed
for its specified period of time.
At
system generation* a group of
contiguous partitions are selected to
be used for time-slicing, and each
partition is assigned at least one job
class.
If the job is to be
time-sliced, specify a class that was
assigned only to the partitions
selected for time-slicing.
Job Time Limits It.!l1ID..
To assign a limit to the computing time
used by a job, code the keyword parameter
in the operand field.
-----,
T 1l'lE= (min utes, seconds)
'--
•
J
Such an assignment is useful in a
multiprogramming environment where more
than one job has access to the computing
system.
The time is coded in minutes and
seconds to represent the maximum time for
execution of a job.
Assigning Job PrioritLlfR!!l
• The number of minutes cannot exceed
1439 and the number of seconds cannot
exceed 59. If the job is not completed
in this time it is terminated.
• If the job requires use of the system
for more than 24 hours (1q39 minutes)
specify TIME=1440.
This number
suppresses job timing.
To assign a priority other than the
default job priority (as established in the
input reader procedure), code the keyword
parameter in the operand field of the JOB
statement.
I
1
PRTY-=nn
Replace the letters "nn" with a decimal
number from 0 through 13 {the highest
priority number is 1~.
• If the time limit is given in minutes
only, the parentheses need not be
coded; e.g., TIME=5.
• If the time limit is given in seconds,
the comma must be coded to indicate the
absence of minutes; e.g., TIME=(,45).
• If the TIl'lE parameter is omitted, the
default job time is assumed.
If an installation provides time-slicing
facilities in a system with OS/VS2. the
PRTY parameter can be used to make the job
part of a group of jobs to be time-sliced.
At system generation, the priority of the
time-sliced group is selected.
If the job
priority number specified corresponds with
the priority number selected for
time-slicing, then the job will be
time-sliced.
If the PHTY parameter is omitted, the
default job priority is assigned to the
job.
To assign a job class to a job. code the
keyword parameter in the operand field of
the JOB statement.
r---------------------------------------------,
I
CLASS=jobclass
J
~
~
MQ!~:
Whenever possible, avoid using
priority 13. This is used by the system to
expedite processing of jobs in which
certain errors were diaqnosed.
It is also
intended for other special uses by future
feat ares of systems with priority
schedulers.
The meaning and use of the term "jobclass"
is pre-defined by each installation.
If
the CLASS pa rameter is omitted, the default
job class of A is assigned to the job.
• If an installation provides
time-slicing facilities in an OS/'S1
system, the CLASS parameter can be used
30
With the quantity and diversity of data
in the output stream, an installation may
want to separate different types of output
data into different classes.
Each class is
directed to an output writer associated
with a specific output unit. The MSGCLASS
parame"ter allolls routing of all messages
issued by the job scheduler to an output
class other than the normal message
class, A.
If the REGION parameter is omitted or if
a region size smaller than the default
region size is requested. it is assumed
that the default value is that established
by the input reader procedure.
To choose such a class, code the keyword
parameter in the operand field of the JOB
statement.
r------------------MSGCLASS=x
The REGION parameter can be used lIith
either the VIRT or REAL options of the
ADDRSPC parameter.
I
L
------------------~
Replace the letter "x" with an alphabetic
{A-Z) or numeric (0-9) character. An
output writer, which is assigned to process
this class, will transfer this data to a
specific device.
• Region sizes for each job step can be
coded by specifying the REGION
pa rameter in the EXEC sta temen t for
each job step. However. if a REGION
parameter is present in the JOB
statement, it overrides REGION
parameters in EXEC statements.
If the MSGCLASS parameter is omitted,
job scheduler messages are routed to the
standard output class, A.
• For information on storage requirements
to be considered when specifying a
region size, see the appropriate
~.tQ£g9.~_~1!!!~1~2 publication.
• For a more detailed discussion of
output classes, see the appropriate
pI a!l!!.iruI_~.!l d Ug.Ji!!i de.
~~g£ifying~aiD-~orage
~Q!LjREGIONl
Reguirement2
TO temporarily prevent a job from being
selected for processing. code the keyword
parameter in the operand field of the JOB
sta temen t.
for_~
For jobs that require an unusual amount
of main storage, the JOB statement provides
the REGION parameter. The REGION parameter
specifies the maximum amount of main
storage to be allocated to the job. This
amount must include the size of those
components required by the user's program
that are not resident in main st?rage.
The REGION parameter is used in
conjunction with the ADDRSPC parameter to
determine the total amount of main storage
available to a program and to either allow
or disallow paging.
JiQig: The REGION parameter has different
meanings for OS/VS1 and OS/VS2. see the
publication Q§'L~_J.£L~~£!i£,g2 for detailed
information.
r--------------------------1--------------'
IL ______________________
TYFRUN={HOLD _______________ JI
§f~
The job is then held until a RELEASE
command is issued by the operator. This
specification is particularly useful when
one job must be run after another job has
terminated.
HOLD specifies that the job is to be
held until the operator issues a RELEASE
command. SCAN (for OS/YS1 only) specifies
that the JCL for a job is to be scanned for
syntax errors but that the job is not to be
executed. If SCAN is specified for OS/YS2,
a JCL error viII occur.
To specify a region size, code the
keyword parameter in the operand field of
the JOB statement.
,
REGION=(nnnnnxK(,nnnnnyK)
I
To request the maximum amount of main
storage required by the job, the term
"nnnnnx" should be replaced with the number
of 1024-byte areas allocated to the job,
e. g., REGION-=52K. This number can range
from 1 to 5 digits but cannot exceed 16383.
To take advantage of the storage
facilities offered by OS/VS1 and OS/VS2,
always specify ADDRSPC = '1FT or omit the
parameter.
,
VIRT}
ADDRSPC= { REAL
I
I
..J
L-
Job Control Procedures
31
Note that the compiler and its object code,
including library subroutines, can run
VIRTUAL, and should be run that way unless
a non-COBOL program in the partition
requires the REAL option.
positional, length, and content
requirements for a name field.
The
programmer must specify a stepname if later
control statements refer to the step.
POSITIONAL
The EXEC statement defines a job step
and calls for its execution. It contains
the following information:
1.
2.
The name of a load module or the name
of a cataloged procedure that contains
the name of a load module that is to
be executed. The load module can be
the COBOL compiler, the linkage
editor, the loader, or any COBOL
proqram in load module form.
Accounting information for this job
step.
PA~AMETERS
Id.!m,tifiing the
JERQ£l.
Progra!!~f~l1L.Q.Lel:Q£!ltg!!!:~
The EXEC statement identifies the
program to be executed in the job step with
the PGM parameter. To specify the COBOL
compiler, code the positional parameter in
the fifst position of the operand field of
the EXEC statement.
.J
-----------------,I
PGM=IKFCBLOO
3.
Conditions for bypassing the execution
of this job step.
4.
Computing time for a job step or
cataloged procedure step, and main
storage region size.
It indicates that the COBOL compiler is the
processing program to be executed in the
job step.
5.
Compiler, linkage editor, or loader
options chosen for the job step.
To specify the linkage editor* code the
positional parameter in the first position
of the operand field of the EXEC statement.
Figure 6 is the general format of the
EXEC sta teme nt.
H~i~:
If the information specified is
normally delimited by pa rentheses but
contains blanks, parentheses, or equal
signs, it must be delimited by single
quotation marks instead of parentheses.
The stepname identifies a job step
within a job. It must satisfy the
32
.J
L
.-----J
----------------------,I
PGM=IEWL
L--
J
This indicates that the linkage editor is
the processing program to be executed in
the job step.
The PGM parameter depends upon the type
of library in which the program resides.
If the job step uses a cataloged procedure,
the EXEC statement identifies it with the
PROC parameter, in place of the PGM
parameter.
--,
I
I
rr------------·---r----~
JOper-1
lationl Operand
J
lName
I--
I
J-+
II
t
~
I
I
I
I
J
PGM =progname
III( stepna me)1 I EX EC
1
J
I PGM=*.stepname.ddname
4
J
I PRoC=procname
•
' J procname
J
I
1 PGM=*.stepname.procstep.ddnalie
,
I
1
I
I
I
I
J
I
I
.qACCTz
}
J
'l~ACCT.procstep
,J
"1
I~COND2
}
J I ~COND. procstep
J
J
t
t
J
J
J~PARM.procstep
I
J
I
J~TIME
l
J
:
:
t
J
:I
:
J
J
I
I
I
(code, operator[ ,stepname(. procstep]]) ••• )
6 7J '.
3 a 9J
= (option[.option] ••• )
t
10
,
=
f
J
I
= valueK]
t
I
,
t
request]
J
lff~;~~i. procstep}
J
t
(value 1, _alae 2)]
I
J
=
1
{VIRT}]
REAL
1 lstepname is required when information from this control statement is referred to in
1 later job step.
1
I
1
I
I
I
J
ZIf this format is selected, it may be repeated in the EXEC statement once for each
step in the cataloged procedure.
3If the information specified contains any special characters except hyphens, it must
be delimited by single quotation ~arks instead of parentheses.
.If accounting-information contains any special charactecs except hyphens, it must be
delimited by single quotation marks.
5The maximum number of characters allowed between the delimiting quotation marks or
parentheses is 142.
6The maximum number of repetitions allowed is 7.
7If only one test is specified, the outer pair of parentheses may be omitted.
alf the only special character contained in the value is a comma, the value may be
enclosed in quotation marks.
9The maximum number of characters allowed between the delimiting quotation marks or
parentheses is 100.
t
f
J
1
I
t
,
f
..
al
,
,,t
J
I
I
I
t
J
1
J
J
I
I
.J
L-
Figure
I
J
t
= {IIi nutes, secondS.]
}
I OREGION. procstep
I
:~:~. procstep}
J
I
}
T1f1E .procstep
J
J
I
t
II~ADDRSPC}
IOADDRSPc.procstep
r----------L----'--J
,
3 - SJ
1
I
J
t I l ~R EG 10 N
t
t
,
(accounting-information)
'IU{PARM2}
I
I
t
I
I
J
~ywor4 Pa~!~£!
1
•
J
I
6.
EXEC statement
Job Control Proceduces
33
1 •.
Tem~xary libra£i~
are temporary
partitioned data sets created to store
a prograa until it is ~sed in a later
job step of the same job. This type
of library is particularly useful for
storing the program output of a
linkage editor run until it is
executed in a later job step. To
execute a program from a temporary
library, code the positional parameter
in the first position of the operand
field of the EXEC statement.
statements for several steps, each of
which executes a particular program.
Cataloged p.rocedures are members of a
library named SYS1.PROCLIB. To
request a cataloged procedure, code
the posi tiona 1 parame ter in the first
position of the operand field of the
EXEC statement.
,
-,
r-
JL - -_ ___
PROC= procna me
__-J
,
PGM=*.stepname.ddname
Replace the term p.rocname with t.he
unqualified name of the cataloged
procedure (see "Using the DD
statement" for a discussion of
qualified names).
J
-----------------~
The asterisk (*) indicates the cur~ent
job step.
Replace the terms stepname
and ddname with the names of the job
step and the DO statement within the
procedure step, respectively, in which
the temporary library is created.
If the temporary library is created in
a catalogued procedure step, in order
to call it in a later job step outside
the procedure, give both the name of
the job step that calls the procedure
and the procedure stepname by coding
the positional parameter in the first
position of the operand field of the
EXEC statement.
---------------------------,
2.
34
~~£iIYiQg_~QQ_S1~E_!££Q~nliQg_InfQt~~liQn
1A£CTl
The §I2tem librg£Y is a partitioned
data set named SYS1.LINKLIB that
contains nonresident control pt'ogram
routines, and proce.ssor programs. To
execute a program that resides in the
system library, code the positional
parameter in the first position of the
operand field.
When executing a multistep job, or a job
that uses cataloged procedures, the
programmer can use this parameter so that
jobsteps are charged to separate accounting
areas.
To specify items of accounting
information to the installation accounting
routines for this job step, code the
keyword parameter in the operand field of
the EXEC statement.
PGM=progname
3.
KEYWORD PARAMETERS
PGM=*.stepname.procstepname.ddname
_________ •_____________________________J,
r-
I
A procedure may be tested before it
is placed in the procedure library by
converting it into an in-stream procedure
and placing it within the job step itself.
In-stream procedures are discussed in the
section, "Testing a Procedure as an
In- streamProced ure" in the chapter "Using
the Cataloged Procedures."
liQ1~:
---------,
Replace the term progname with the
member name or alias associated with
this program.
This same keyword
parameter can be used to execute a
program that resides in a 1?ri v~!.g
lib~£~.
Private libraries are made
available to a job wi th a special DD
statement (see ·'Additional DD
statement Facilities").
Instead of executing a particular
program. a job step may use a
£~taloged-E£Q£~g~£~.
A cataloged
procedure can cont.ain control
I
,
ACCT=(accounting information)
____________________Jt
Replace the term "accounting information"
~ith one or more sub parameters separated by
commas. If both the JOR and EXEC
statements contain accounting information,
the installation accounting routines decide
how the accounting infot'mation shall be
used for the job step.
To pass acc6unting information to a step
within a cataloged procedure, code the
keyword parameter in the operand field of
the EXEC statement.
,
,
,
ACCT. procstep= (accounting information)
'--------
I
The compiler issues a return code of 1&
when any of the following are detected:
---------------,~
• BASIS member-name is specified and no
member of that name is found
procstep is the name of the step in the
cataloged procedure. This specification
overrides the ACCT parameter in the named
procedure step, if one is pcesent.
• Required device not available
• Not enough main storage is available
for the tables required for compilation
~Qg£if Yi J!9.~Q!!d i liQ!UL.iQL.!U!Ea§.§.i n 9._Q£.
~!g£utiD.9.-th~~Q!LSt~CONDl.
• A table exceeded its maximum size
The execution of certain job steps is
based on the success or failure of
preceding steps. The COND parameter
provides the means to:
• A permanent input/output error has been
encoun tered on an external device
• Make as many as eight tests on return
codes issued by preceding job steps or
cataloged procedure steps, which were
completed normally. If anyone of the
tests is satisfied, the job step is
bypassed.
The return codes have a correlation with
the severity level of the error messages.
With linkage editor messages, for example,
the rightmost digit of the message number
states the severity level; this number is
multiplied by 4 to get the appropriate
return code. With the COBOL compiler. 04,
08, 12, and 16 are equal to the severity
flags:
W, C, E, and D, respectively.
• Specify that the job step is to be
executed even if one or more of the
preceding job steps abnormally
terminated or only if one or more of
the preceding job steps abnormally
terminated.
TO specify conditions for bypassing a
job step, code the keyword parameter in the
operand field of the EXEC statement.
I
,
1 COND={(code,operator,[stepname), ••• ,
1L- ________________
(code
,opera tor, [s tepname ])
_
Normal conclusion
04
Warning messages have been listed,
but program is executable.
08
Ercor messages have been listed;
execution may fail.
12
Severe errors have occurred;
execution is imp~ssible.
16
Terminal errors have occurred;
execution of the processor has been
terminated.
GT
GE
EQ
I
LT
,
LE
J
NE
The term "code" may be ceplaced by a
decimal numeral to be compaced with the job
step return code. The return codes for
both the compiler and the linkage editor
are:
00
The term "operator" specifies the test
to be made of the relation between the
programmer-specified code and the job step
return code.
Replace the term operator
with one of the following:
(greater than)
(greater than or equal to)
(equal to)
(less than)
(less t.han or equal to)
(not equal t.o)
The term "stepname" identifies the
previously executed job step that issued
the return code to be tested and is
replaced by the name of that preceding job
step. If stepname is not specified, code
is compared to the return codes issued by
all preceding steps in the job.
Replace the term stepname with the name
of the preceding job step that issues the
return code to be tested.
If the programmer codes
COND={(4,GT,STEP1) , (8,EQ,STEP2»)
the statement is interpreted as: "If 4 is
greater than the return code issued by
STEP1, or if STEP2 issues a return code of
8, this job step bypassed."
Job Control Procedures
35
only when one or more of the preceding job
steps have abnormally terminated. However,
if any return code tests specified in this
job step are satisfied, the step is
bypassed.
• If only one test is made, the
programmer need not code the outer
parentheses, e.g., COND=(12,EQ,STEPX).
• If each return code test is made on all
preceding steps, the programmer need
not code the terms stepname, e.g.,
COND= { (4 ,GT) , (8 ,EQ) ) •
• When the return code is issued by a
cataloged procedure step, the
programmer may want to test it in a
later job step outside of the
procedure. In order to test it, give
both the name of the job step that
calls the procedure and the procedure
stepname, e.g., COHD=«code,operator.
stepname.procstep), ••• ).
When a job step abnormally terminates.
the COND parameter on the EXEC statement of
the next step is scanned for the EVEN or
ONLY subparameter.
If neither is specified, the job step is bypassed and the EXEC
statement of the next step is scanned for
the EVEN or ONLY subparameter. If EVEN or
ONLY is specified, return code tests, if
any, are made on all previous steps
specified that executed and did not
abnormally terminate. If anyone of these
tests is satisfied, the step is bypassed.
otherwise, the job step is executed.
If the programmer codes
Abnormal termination of a job step
normally causes subsequent steps to be
bypassed and the job to be terminated. By
means of the COND parameter, however, the
programmer can speci.fy execution of a job
step after one or more preceding job steps
have abnormally terminated. For the COND
parameter, a job step is considered to
terminate abnormally if a failure occu.rs
within the user's program once it has
received control.
(If a job step is
abnormally terminated during scheduling
because of failures such as job control
language errors or inability to allocate
space, the remainder of the job steps are
bypassed, whether or not a condition for
executing a later job step was specified.)
COND=EVEN
the statement is interpreted as: "Execute
this step even if one or more of the
preceding steps abnormally terminated
during execution." If COND=ONLY is coded,
it is interpreted as: "Execute this step
only if one or more of the preceding steps
abnormally terminated during execution."
If the COND parameter is omitted, no
return code tests are made and the step
will be bypassed when any of the preceding
job steps abnormally terminate.
To specify the condition for executing a
job step, co de the keyword parameter in the
operand field of the EXEC statement.
r-
I
EVEN}
__
COHD= { ONLY
IL---______________________
.J
The EVEN or
excl usi ve.
be coded in
return code
between, or
ONLY subparameters are mutually
The subparameter selected can
combination with up to seven
tests, and can appear before,
after return code tests, e.g.,
COND= (EVEN, (4.GT,STEP3))
CORD= ((8,GE,STEP1), (16,GEt ,ONLY)
The EVEN subparameter causes the step to
be executed eYen when one or more of the
preceding job steps have abnormally
terminated. However, if any return code
tests specified in this job step are
satisfied, the step is bypassed. The ONLY
subparameter causes the step to be executed
36
• When a job step that contains the EVEN
or ONLI subparameter refers to a data
set that vas to be created or ca taloged
in a preceding step, the data set will
not exist if the step creating it was
bypassed.
• When a jobstep that contains the EVEN
or ONLY subparameter refers to a data
set that vas to be created or cataloged
in a preceding step, the data set may
be incomplete if the step creating it
abnormally terminated.
• When the job step uses a cataloged
procedure, the programmer can establish
return code tests and the EVEN or ONLY
subparameter for a procedure step by
including, as part of the keyword COND,
the procedure stepname, e.g.,
COND.procstepname. This specification
overrides the COND parameter in the
named procedure step if one is present.
The programmer can code as many
parameters of this form as there are
steps in the cataloged procedure.
• TO establish one set of return code
tests and the EVEN or ONLY subparameter
for all steps in a procedure, code the
parameter without a procedure
stepname. This specification replaces
all COND parameters in the procedure if
any are present.
COND
Job steps following a step that
abnormally terminates are normally
bypassed.
If a job step is to be executed
even if a preceding step abnormally
terminates, specify this condition, along
with up to seven return code tests:
To pass options to a compiler, the
linkage editor, loader~ or the execution
step within the named cataloged procedure
step~ code the k.eyword parameter in the
operand field.
,
~
This will pass options to the compiler~
linkage editor, loader, or object program
when anyone of them is called by the PGM
parameter in the EXRC statement or to the
first step in a cataloged procedu.re.
PARM.procstep=(option[,option] ••• )
IIISTEP3 EXEC PGM=CONVERT,
Xl
tIl
COND=(EVEN, (4,EQ,STEP1»_ _
, ._
. ._ _ _ _- "I
L-
Here, the step is executed if the return
code test is not satisfied, even if one or
more of the preceding job steps abnormally
terminated.
If a job step is to execute
only when one or more of the preceding
steps abnornally terminate, replace EVEN in
the above example with ONLY.
If the EXEC statement calls a cataloged
procedure, the programmer can establish
return code tests and the EVEN or ONLY
subparameter for a procedure step by.coding
the CON.D parameter followed by the name of
the procedure step to which it applies:
,
,--IliSTEP4 EXEC ANALYSIS,COND.
XI
tIl REDUCE=(16,EQ.STEP4.LOOKUP),ONLY) •••••
-------------------------------------------~
Here, the cataloged procedure step named
REDUCE will be executed only if a preceding
job step has abnormally terminated and the
procedure step named LOOKUP does not issue
a return code of 16. The programmer can
code as many COND parameters of this type
as there are steps in the procedure.
~§sing Inform£!tiQD._12-t.~
J
Any PARM parameter already appearing in the
procedure step is deleted. and the PARM
parameter that is passed to the procedure
step is inserted.
A maximum of 100 characters may be
written between the parentheses or single
quotation marks that enclose the list of
options. The COBOL compiler selects the
valid options of the PARK field for
processing by looking for significant
characters (usually three) of each key
option word. When the keyword is
identified. it is checked for the presence
or absence of the prefix NO, as
appropriate. The programmer can make the
most efficient use of the option field by
using the significant characters instead of
the entire option.
Figure 1 lists the
significant characters for each option (see
"Options for the Compiler" for an
explanat ion of each).
Processing
Pr rullll!Llf AR 1ft.
For processing programs that require
control information at the time they are
executed. the EXEC statement provides the
PARK parameter. To pass information to the
program, code thekeyvord parameter in the
operand field.
1
PARM=(Option[,option] ••• )
Job Cont.rol Procedures
37
,
...-----
J
I
,Option
J-
I
,
I
I
I
I
I
I
,
ADV
APOST
BATCH
B crF
CDECK
CLIST
Siqnificant
Characters
ADV
I
APO
I
I
,
•
I
BAT
BUF
CDE
Cl.I
CSY
J
I
CSYNTAX
COUNT
1
COU
I
DECK
J
I
J
DAAP
DUMP
DTN AM
I
I
I
DMA
I
.,1
I
1
J
I
•I
•J
ENDJOB
f
END
J
PDE
FLO
I
I
1
LCOLl/LCOL2
LIB
I
t
J
I
LAG, LAGW
J
,
FDECK
FLAGE tV)
FLOW
LANGLVL
,
,,
LIB
I
I
LINECNT
LOAD
J
J
I
J
LSTONLY/LSTCO~P
J
,
J
I
LVL
L132/L120
I
I
,
~
NUM
OPTIMIZE
J
I
I
PMAP
J
I
I
J
I
J
NAME
1
DEC
DUM
DYN
LANGLVL
OL1/0L2
CNT
LOA
LSTO/LSTC
LVL
L13/L12
NAM
NUM
I
J
J
J
• When an option and its default (such as
IREF and NOXREP) are both specified~
J
the last encountered option is
generally the one assumed.
(Exceptions
to this rule are cited in the option
descriptions.)
Accordingly, the
programmer may change one of the many
options without repunching the entire
EXEC card.
t
I
,
J
I
J
I
J
PRINT
I
PRI
•
QUOTE
RESIDENT
1
1
!
I
QUO
RES
SEQ
SIZ
J
J
SEQ
SIZE
I
I
I
SOURCE
J
SPACE
I
STATE
SUPMAP
S XREF
SYMDMP
SYNTAX
,
I
1
,
J
J
1
t
1
I
J
J
,
j
t
S Ysx
t
I
f
SYN
J
SIS
TEE
TERM
J
1
I
I
I
I
t
I
VERB
TES
TRU
VBS
VBR
VER
XRE
ZWB
.L--
1-.
Figure
STA
SUP
SIR
SYH
I
TEST
TRUNC
VBSUM
VBa E1"
XREF
ZWB
SOU
ACE
7.
I
I
I
I
J
I•
I
J
J
J
,
,
J
I
I
I
1
J
SIZE=yyyyyyy
indicates the amount of main storage~
in bytes, available for compilation
(see "Machine Considerations").
The
COBOL default value is 131,072 bytes,
or 128K.
BUF=yyyyyy
indica t~..s the a mount. of main storage
to be allocated to buffers. If both
SIZE and BUF are specified, the amount
allocated to buffers is included in
the amount of main storage available
for compilation (see "Appendix D:
Compiler optimization" for information
about how buffer size is determined).
HQ~:
The SIZE and BUF compile-time
parameters can be given in multiples
of K, where K=1024 decimal bytes.
Por
example, 131,072 decimal bytes can be
specified as 128K.
.J
Significant Characters for
Compiler options
Note:
The compiler recognizes the
significant characters to set the proper
options.
If an option is incorrectly
spelled, the compiler default option is
used.
The IBM-supplied default options
indicated by an underscore in the following
38
PARM=fSIZE=160000,PMAP'.
This is the
recommended (that is~ most efficient)
technique.
other ways of specifying
special characters in the PARM
parameter are described in OS/VS_Jf~
IHi~fg.£g!l£g •
J
J
t
• When a subparameter contains an equal
sign, the entire information field of
the PARM parameter must be enclosed by
single quotation marks instead of
parentheses~ e.g.,
1
OPT
PMA
J
discussion can be changed when the compiler
is installed. The forma"t of the PARM
parameter is illustrated in Figure 8.
LANGLVL Pll)
specifies whether the 1968 or the 1974
American National Standard COBOL
definition (as understood and
interpreted by IBM) is to be used when
compiling those source elements whose
meaning has changed.
LANGLVL(1) tells
the compiler to use the 1968 ANS
standard (X3.23-1968) if the compiler
encounters any of those source
elements whose definition has changed;
this interpretation would be the one
that was used by Release 1 of the
compiler.
LANGLVL(2) tells the
compiler to use the 1974 ANS
standard (X3.23-1974) when
encounteringany--offhose-rede-:fl.ned
elements. LANGLVL(2) is the default.
Generally speaking, the language
level supported by the Release 2
compiler includes all of that
supported by Release 1. The Release 2
compiler will accept not only source
programs written in the new (1974)
language, but also source programs
that were or are written in the older
(1968) language. However, the
superset relationship between the new
and the older languages is not
absolute; there are a few exceptions-elements whose meaning has changed
because of ANS redefinition. It is
only these few elements that are
controlled by the LANGLVL option.
(These elements are identified in
Section III of Appendix A of IBM
VS COBOL for OS/VS.)
Language-elements whose meanings did not
change from 1968 ANS to 1974 ANS
(the vast majority of the language)
are unaffected by the LANGLVL option,
as are all IBM extensions and those
language elements new in the 1974
ANS definition. The compiler accepts
all such elements regardless of the
LANGLVL specification. LANGLVL
affects only that small percentage of
elements whose definition changed from
1968 to 1974.
Job Control Procedures
3~.1
The LANGLVL specification does affect
the operation of the PIPS flagger.
When the FIPS .L Vt option has been
specified, selecting the 1968 ANS
standard will cause FIPS flagging to
be done to those corresponding
specifications; selecting the 1974 ANS
standard causes FIPS flagging to be
done according to the newer
specifications.
SO!!~CE
NOSOURCE
indiGates whether or not the source
module is to be listed.
CLIST
NOCLIST
----Indicates whether or not a condensed
listing is to be produced. If
specified, the procedure portion of
the listing will contain generated
card numbers (unless the NUM option is
in effect), verb references, and the
location of the first instruction
generated for each verb. Global
tables, literal pools, register
assignments, and information about the
Working-storage section ar~ also
provided. CLIST and PMAP are mutually
exclusive options.
(If both are
specified, COBOL rejects the one
specified first.)
illustration of the use of these options,
see the "Output" section.
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
PMAP or CLIST is in effect. VERB is
automatically in effect if SYMDMP,
STATE, or TEST is in effect. NOVERB
yields more efficient compilation.
Note:
If READY TRACE debugging
statements are used in the program,
VERB will cause paragraph-names rather
than card numbers to be displayed at
execu tion time.
LO'1D
NOLOAD
indicates whether or not the object
module is to be placed on a mass
storage device or a tape volume so
that the module can be used as input
to the linkage editor.
If the LOAD
option is used. a SIS LIN DD statement
must be specified.
DECK
!fQDE~!
indicates
module is
option is
statement
IQt~:
In nonsegmented programs, verbs are
listed in source order. In segmented
programs, the root segment is first,
followed by the indiVidual segments in
order of ascending priority.
aQ.
DMAP
NODM1P
-----rndicatesw hether or not a glossary is
to be listed.
Global tables, literal
pools, reqister assignments, and
information about the Working-Storage
section are also provided.
PMAP
NOPMAP
----indicates whether or not register
assignments, global tables, literal
pools, information about the
Working-storage section, and an
assembler-language expansion of the
source modules are to be listed.
CLIST and PKAP are mutually exclusive
options.
(If both are specified,
COBOL rejects the one specified
first. )
!21~:
If anyone of the options CLIS~,
DMAP, and PKAP is specified, the comp1ler
will produce a message giving the
hexadecimal length and starting address of
the Working Storage Section.
Fo.r an
NOSEQ
whether or not the object
to be punched.
If the DECK
used. a SYSPUNCH DD
must be specified.
.
indicates whether or not the comp1ler
is to check the sequence of the source
module statements. If the statements
are not in sequence, a message is
printed.
l!.21~:
For examples ofwha t the SO UReE.
DMAP, PMAP. and SEQ options produce, see
"Output. "
LINECNT=nn
indicates the number of lines to be
printed on each page of the
compilation source card listing. The
number specified by nn must be a
2-digit integer from 01 to 99. If the
LINECNT option is omitted, 60 lines
are printed on each page of the output
1 isting.
Job Control Procedures
39
The compiler regu~res three
lines of what the user has specified
for its headings.
(For example, if
~ll=55 is specified, then 52 lines are
printed on each page of the output
listing.)
12tg:
6.
The LANGLVL option controls the
version of FIPS that will he used.
Requesting LANGLVL{l)--the 1968
ANS standard--causes flagging to
be done according to the 1972 FIPS
specifiea tions.
Requestinq
LANGLVL{2)--the 1974 ANS
standard--causes flagging to be
done according to the 1975 FIPS
speci fications.
7.
Generally,FIPS flagging will not
be done if the compiler has
detected any source errors (that
is, if the return code is not
zero). The only exceptions
concern a few W-level messages
(such as IKF1100-W) that are
purely informational; detecting
these will not prevent FIPS
flagging. The FLAGE option should
not be used, since W-Ievel messages
will not be listed and results are
unpredictable.
8.
If the compiler detects a
D-Ievel error, PIPS will not
execute, nor will any of the
compiler's usual messages or
listings be produced. A
return code of 16 will be the
only indication that this has
occurred. To overcome this
difficulty, recompile with a
specification of NOLVL, then
remove the source errors as
ipdicated by the compiler, and
finally recompile -again with LVL.
~li~
NOZWB
indicates whether or not the compiler
generates code to strip the sign from
signed external decimal field when
comparing this field to an
alphanumeric field.
If ZWB is
specified, the signed external decimal
field is moved to an intermediate
field, in which its sign is removed,
before it is compared to the
alphanumeric field.
ZWB complies with
the ANS standard; NOZWB should be used
when, for example, input numeric
fields are to be compared with SPACES.
a
LVL=A/B/C/D
NOLVL
-----specifies what level of FIPS (Federal
Information Processing standard)
flagging is to be used.- -- A-~- B, -C, and
D correspond to the levels Low,
Low-Intermediate, High-Intermediate,
and Full, respectively.
If flaggin9
is specified, source clauses and
statements that do not conform to the
specified level of lIPS are
identified. See the publication IBll
Y~.-£QBOL fQLQ~L!§ for a complete list
of the statements flagged at each
level.
Not,g§:
1.
If LVL is the SYSGEN default6 its
assigned val~e can be overridden
at compile time with any level
except NOLVL.
If NOLVL is the
SYSGEN default, it can be
overridden at compile time with
any level.
2.
If the LVL option is in effect,
the SYSUT6 data set must be
specified.
3.
If both LVL=A/B/C/D and TERM are
specified, the compiler listing
output to SYSPRINT for options
such as SOURCE, PMAP, and XRE? are
not produced.
40
4.
The option SOURCE is automatically
turned on if LVL is specified. If
TERM is off, a listing is produced.
If TERM is on, there is no listing.
(See note 3.)
5.
If both LVL and BATCH are
specified, LVL is rejected.
~!~!
FLAGE
indicates the type of messages that
are to be listed for the compilation.
FLAGW indicates that all warning and
diaqnostic messages are to be listed.
FLAGE indicates that all error
messages are to be listed, but that
the warning messages are not to be
liste-d. Note. With the use of
FLAGE, and only W-Ievel errors, the
return code will be zero.
SUPMAP
NOSUPMAP
--indicates whether or not the object
code listing, and object module and
link edit -decks are to be suppressed
if an E-Ievel or D-level message is
generated by the compiler.
1lR.!£l!1
SPACE2
SPACE.3
indicates the type of spacing that is
'':0 be used on the source card listing
generated when SOURCE is speCified.
SPACE1 specifies single spacing,
SPACE2 specifies double spacing, and
SPACE3 specifies triple spacing.
TRUNC
!!QnYl!~
applies to movement of COMPUTATIONAL
arithmetic, fields.
If TRUNC (standard
truncation) is specified and the
number of digits in the sending field
is greater than the number of digits
in the receiving field, the arithaetic
item is truncated t.o the number of
iigits specified in the PICTURE clause
of the receiving field when moved. If
NOT,RUNC is specified, movement of th~
1 tem -rs dependent on -the size of the
field (halfword, full word).
SYMDMP
NOll!tlH1f
requests a formatted dump of the data
area of the object program at abnormal
termination.
with this option, the
programmer may also request dynamic
dumps of specified data-names at
strategic points during program
execution.
See "Symbolic Debugging
Features" for more information.
1.
If the SYMDMP option is in effect,
the SYSUTS data set must be
specified, and the NULLFILE or
DUMMY parameter should not be
specified on its DD statement.
2.
If the BATCH option is requested,
SYMDHP is rejected.
3.
If WITH DEBUGGING MODE is
specified and one or more USE FOR
DEBUGGING statements are in the
program, the SYMD~P option is
rejected.
4.
Specification of the SYMDMP option
automatically yields the OPTIMIZE
feature, discussed below, and
rejects the STATE option because
SYMDMP output includes STATE
output at abnormal termination.
WlQ1~
APOST
indicates to the compiler that either
the double quote (It) or the apostrophe!
(') is acceptable as the character to
delineate literals and ~o U~A that
character in the generation ot
figurative constants.
STATE
NOST AT E
----indicates whether or not the number o'f
the COBOL statement being executed at
the time of an abnormal termination is
desired. STATE identifies the number
of the statement and the number of the
verb being executed. If the STATE
option is used, a SYSDBOUT DO
statement must be specified at
execution time for the output data set
on which the statement number message
can be written.
For more information,
see "Debugging Facilities" in the
cha pter "Program Checkout. 11
FLOWr =nn]
NOFLOW
---indicates whether or nO,t a formatted
trace is desired for a va,riable number
of procedures execu ted before an
abnor ma 1 termination.
The number of
procedures traced is specified by nn,
where DD may be any integer value from
one to 99. FLOW[=nn] must be
specified at compile time to generate
the necessary trace linkage; however,
specifying .nn may be deferred until
execution time.
If an is omitted, the
default value is employed. This value
is either 99 or that specified at
program product installation.
specifying NOFLOW at compile time
precludes specification of the Flow
Trace option at execution time.
A
S'{SDBOUT DO statement must be includad
for the output data set on lfhich the
trace can be written.
See "Options
for Execution" for more Information.
For a disc ussion of the FLOW, 5T AT E, and
SYMDMP options, and their value to the
COBOL programmer, see the chapter entitled
"Symbolic Debugging Features." A SYSDBOUT,
SYSDBG, and debug file DD codes are
required at execution time.
OPTIMIZE
NOOPTIMIZE
causes optimized object code to be
generated by the compiler,
considerably reducinq t.he use of
object program main storage.
In
general, the greater the number of
COBOL Procedure Division source
statements, the greater the percentage
of reduction in the amount of main
storage required.
Igt~:
The optimizer feature is
automatically in effect when the
SYMDMP or TEST feature is specified.
Job Control Procedures
41
a DMAP) , depending on hu~ much work
the compiler had completed before
the error was discovered.
SYNTAX
CSYNTAX
NOSYNIAX
NOCSYNTAX
indicates whether object code
generation is to be suppressed--that
is, vhetbe~ the compiler will only
scan the source text for syntax' errors
(with appropriate error messages being
produced) •
5.
SJNTAX causes syntax checking only,
with absolute suppression of object
code generation.
CSYNTAX causes syntax checking ~ith
conditional object code generation:
a
full compilation is produced ~slong
as no errors exceed the W or C level;
if one or m6re E-level. or higher.
sever ity errors are discovered, the
compiler· does not generate the object
code.
NOSYNTAX causes normal compilation,
with both syntax checking and object
code generation.
1.
DECK
SYMDMP
TRUNe
NOSUPMAP
FLOW
STATE
PMAP
2.
3.
4.
42
NUM
NONUM
-----indicates whether or not line numbers
have been recorded in the input and,
rather than compiler-generated source
numbers, should be used in error
messages, as well as in PMAP, CLIST,
STATE, XREF, SIREF, and FLOW.
NOHUM
indicates that the compiler-generated
numbers should be used in error
messages as well as in PMAP, CLIST,
STATE, XREF, SIREF, and FLOW.
When the SYNTAX option is in
effect, all of the following
compile-time options are
suppressed:
LOAD
XREF
SXREF
CLIST
OPTIMIZE
Note:
If when the NUM option is in
effect the compiler discovers a
non-numeric character in a line number
or if ascending numeric sequence is
broken, the compiler invalidates the
number.
The compiler then takes the
last valid card number in sequence,
adds a 1 to that number and begins
genera~ing card numbers from that
point.
The increment is 1.
Six
digits is the maximum sequence number.
The card that follows 999999 will he
flagged and NUM, SY~DMP, and TEST
canceled.
STATE and FLOW will not be
canceled.
NAM.E
COUNT
VBSUti
VBREF
DMAP
Unconditional syntax checking is
assumed if all of the following
co~pile-time options are
specified:
NOLOAD
NOCLIST
SUPMAP
NOXREF
NOSXREF
NOPMAP
NODECK
CSYNTAX and SYNTAX are mutually
exclusive.
CSYNTAX will override
SYNTAX.
When .CSYNTAX has been specified
and an E-Ievel or higher error is
detected, the final pa.rts of . the
compilation procedure execution of
phases 60, 62, 63, or 64 (which deal
with code generation) are not
executed.
Beca use of this, any
existing syntax errors that could
only he detected by these latter
phases of compilation will l!2i be
discovered and made known to the
user during the CSYNTAX run; they
will only come to light during a
later full compilation-
If LSTCOMP is in effect, the statement
number generated· by the lister feature
is used regardless of NUM or NONUM
specification.
IREF
@!RM
If CSYNTAX is specified and an E
or D-Ievel diagnostic message is
encountered before or during the
operation of phase 21 or during
the operation of phases 30, 40,
45, 50, or 51, the SYNTAX option
replaces CSYNTAX, and the options
listed in Note 1 above are suppressed. However, certain types of
output may be produced (for example,
indica teswhe ther or not a
cross-reference listing is produced.
If IREF is s,pecified, an unsorted
listing is produced with data-names
and procedure-names appearing in two
parts in source order.
SIBEP
t!QU1U~!
indicates whether Or not a sorted
cross-reference listing is produced.
If SIREr is specified, a sorted
listing is produced with data-names
and procedure-names in alphanumeric
order.
LIB
.l2ll!!
indicates whether or not a COpy and/or
a BASIS request will be part of the
COBOL source input stream. If no
library facilities are to be used, the
specification of NOLIB will save
compilation time.
BATCH
NOB.A~l!
• XREF and SIBEF are mutually
exclusive. If both are specified,
COBOL rejects the one specified
first.
• Some data names used in STRING,
UNSTRING, SEARCH, and USE FOR
DEBUGGING statements are not part of
the compiler-generated code, and
therefore will not appear in an IREF
or SIREF listing.
• Group names in a MOVE CORRESPONDING
statement will not be listed in an
XREF or SXREF listing; however, the
elementary names within those groups
will be listed.
• Because most of the Report writer
code is generated before the compiler creates the dictionary, most
of the Report Writer data names do
not appear in an XREF or SXREF
listing.
indicates whether or not multiple
programs and/or subprograms are to be
compiled with a single invocation of
the compiler. In the BATCH
environment all compiler options
specified on the EXEC card, plus all
default options, will apply to every
program in the batch unless specific
options are overridden on the CBL
card, which must be included for each
proqram. See "Batch compilation" for
more information on batch compilations
and the CBL card.
When BATCH is specified, the LVL and
SyftDKP options will be rejected. In
addition, the BUP, L120/L132, and SIZE
options are precluded froa use on a
Job Control Procedures
42.1
CBL card and will be rejected if
speci fied.
NAME
NONAME
-----rndicates whether or not programs in a
batch compilation environment will be
link-edited into one or more load
modules.
If NAME is specified~ each
succeeding program in the batch will
be link-edited into a separate load
module.
This option will remain in
effect for the entire compilation
unless NONAME is specified on the CBL
card for an individual program.
If
NONAME is specified on the eBL card,
no name will be generated for this
compilation.
Names for the load
modules vill be formed according to
the rules for forming module names
from the PROGRAM-ID. See "Batch
Compi.lation" for more details on batch
compilation and the CBL card.
!Q.!.~:
If the BATCH option is not
specified, NONAME will be in effect.
RESIDENT
!Q.!liSIQEN!
requests the COBOL Library Management
feature.
When one program in a given
region/partition requests the RESIDENT
option, the main program and all
subprograms in that region/partition
should also request it.
Note:
The RESIDENT option is
automatically in effect when the DYNAM
option is invoked.
DYNAM
NOQIlll1
causes subprograms invoked through the
CALL literal statement to be
dynamically loaded and through the
CANCEL statement to be dynamically
deleted at object time (instead of
link-edited with the calling program
into a single load module).
Note:
When both NORESIDENT and
i~~iNAM are either specified or
implied by default, and a CALL
identifier statement occurs in the
source statement being compiled, the
COBOL Library Management Facility
option (RESIDENT) is automatically in
effect.
A printed statement of this
is given in the compiler output.
(For
a discussion of the COBOL Library
Management FacilitJ~ see the section
"Sharing COBOL Library Subrou"tines" in
the "Libraries" chapter.)
2!.§!
SYSx
indicates whether SYSOUT or SYSOUx,
where x must be alphanumeric (that is~
0-9 or A-Z except for T), is the
ddname of the file to be used for
debug output (READY TRACE, EXHIBI~ or
DISPLAY statement.
The specification
in the program that is first to ~ccess
the file is chosen.
ENDJOB
NOEND.JOB
---indicates whether or not, at the end
of each run-unit (which is assumed to
begin with the highest-level COBOL
program called), the COBOL library
subroutine I1BOSTTO is to be called to
delete modules and free main storage
acquired through GETMAINs issued by
COBOL library subroutines.
ENDJOB
takes effect either at a STOP RUN in
any program, or at a GO BACK statement
in a main program only.
Violation of
the restriction against mixing RES and
NORES modules within a run-unit may
cause an unpredictable execution-time
abend when ENDJOB is in effect, even
in programs which ran successfully
without ENDJOB.
~Q!~:
When a non-COBOL program, such
as IMS or an installation-defined
assembler program, links to COBOL load
modules many times within a job step,
the resulting accumulation of
GETMAIN-acquired areas and loaded
modules may result in execution-time
abends.
In order to prevent
fragmentation and overload of storage
in such an environment~ the ENDJOB
compiler option must be specified.
This will cause ILBOSTTO to be loaded
at the normal termination of the
run-unit to free all GETMAIN areas
and~ in a RES environment, to delete
any loaded subroutines and
dynamically-invoked subprograms.
The
only GETMAIN areas not freed by
ILBOSTTO are those obtained when
opening a random indexed BISAM file
for which the options APPLY CORE-INDEX
and/or TRACK-AREA IS integer
CHARACTERS have been specified; before
terminating, the user should close
such files within the COBOL program.
since ILBOSTTO is always loaded, it
must be made available at execution
time (by placing it in the link pack
area or by specifying the COBOL
library on a STEPLIB DO statement for
the GO step). If ILBOSTTO is not
placed in the link pack area, it
should be explicitly deleted by the
invoker of the COBOL run-unit;
otherwise, one copy of this subroutine
will remain in the user region after
the run-unit has completed.
Job control Procedures
43
1)21
NOlDV
indicates whether or not records for
files with WRITE ••• lDVANCING need
reserve the first byte for the control
character.
ADV specifies that the
first byte need not be reserved, but
that the compiler will add one byte
to the LRECL for the control
character.
COUNT
!!Q.£QON~
indicates whether or not code is to be
generated to produce verb execution
summaries at the end of problem
program exeqution.
Each verb is
identified by procedure-name and by
statement number# and the number of
times i t was used is indicated.
In
addition, the percentage of verb
execution for each verbvith 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.
COUNT
requires both SYSDBOUT and SYSCOUNT
DD statements at execution time. For
a more detailed discussion on the use
of the COUNT option, see the chapter
"Program Checkout. II
Q2~~
NODUMP'
specifies whether the compiler should
produce a dump or an informative
message in the event it encounters a
D-level ("disaster") error condition
during its processing. The compiler
will abnormally terminate after producing the dump/message.
DUMP specifies that a dump (but no
message) is to be produced.
This dump
will contain a four-digit user
completion code.
See Appendix K for
more information on these codes.
(Note:
The most frequent cause of
comprler abend is insufficient SIZE
value--a user completion code of 0003.
In this case, rerun the program specifying a larger value.)
NODUMP specifies that the compiler is
to produce an informative message
(but no dump) •
If analysis of
does not solve
Appendix L for
in calling IBM
the
the
the
for
message or dump
problem, see
procedure to follow
assistance.
VBSUM
~QY~§2~
provides a brief summary of verbs
used in the source program and a
44
count of how often each verb appeared.
This option provides the user with a
quick search for specific types of
statements. VBSUM implies VERB.
VBREF
~QY~B£![
provides a cross-reference of all
verbs used in the program.
This
option provides the programmer with
a quick index to any verb used.in
the program. VBREF implies VERB
and VBSUM.
There are five compiler options for using
the lister feature of the compiler.
Note
that either LSTONLY or LSTCOMP must be
selected for the other four options to have
meaning unless the BATCH option is
specified.
In a batch compilation, if some
or all of the programs are to be compiled
using the lister feature, L120 or L132 must
be specified in the FARM field of the EXEC
card, even if LSTCOMP or LSTONLY are to be
specified on the CBL card.
For detaile~ information on the use of the
lister, see the chapter "The Lister
Feature." The options are listed in Figure
6, 'where:
LSTONLY
LSTCOMP
NOLST
----indicates whether the lister feature
is to be used.
LSTONLY specifies that
a reformatted listing is to be
produced bat that no compilation is to
occur. LSTCOMP specifies that both a
ref ormat ted list ing is t.o be prod uced
and compilation is to occur in the
same job step.
PO.ECK
NOPDECK
---indicates whether a copy of the
reformatted source program is to be
written on the SYSPUNCH data set.
Since FDECK has meaning only with
either LSTONLY or LSTCOMP, the lister
oatput will be both a reformatted
listing and a reformatted deck.
CDECK
NOCOECK
----riidicateswhether or not COpy
statements are to be expanded into
COpy members in the SYSPONCH output.
The COpy members are to be expanded in
the reformatted deck requested through
FDECK. If CDECK is specified with
NOFDECK, only the expanded COpy
sta tements are produced.
LeOL1
1&OL2
indicatesvhether the Procedure
Division part of the listing is to be
in single or double column format.
Job Control Procedures
44.1
L120
L1ll
indicates whether the length of each
line of the reformatted listing is to
be 120 or 132 characters long.
Time sharing provides the COBOL programmer
with facilities for entering, compiling,
and testing programs at his terminal.
(For
further information on the Time Sharing
Option, see the Program Product publication
!~~~~_COBOL_fIQm~!~~min~!
~!r's-2uide andR~feIj!l!£g.)
These options
are listed in Figure 8, where:
In addition to the preceding compiler
options, the following options are designed
for ~se with the Time Sharing option (T50).
Job Control Procedures
45
r
•
,
,
J Compiler:
I
,
{PARM
PARM.
,
procstep
}
=([ SIZE=yyyyyyy][ • BUF=yyyyyy][ , LANGLVL (1/~J)
I
1
1
J
I
r,PMAP
]
J
l
r,SUPMAP
L,liOP!t!f
r,LOAD
lrNOLOAD
L,NOSUPl1Afj
r, TRUNC]
I
I
I
[,2. £lil]
PA
J
r,STATE
I
,
I
J
J
L,!iOSII1Ql1f
[.BATCH
J
J
t
I
r,RESIDENT
J
I
r,ADV
,
r,TERM
J
J
.
J
r,SYNTAX
J
1
[,NAM.E
,!ONAUj
J
I
J[,LIB
l
, !!QLI Jij
J
[, VERB]
,NOVERB
[,DYNAM]
, NODll.!!1
r,ZWB
l!NOZWB
~'LSTONLY
l
l!r,DUMP
NODUlt~
,~OUNT
..]
,
I
I
I
I
I
I
J
I
I
[,LVL=A/B/C/D]
l! l!Q CS lB.!!!
[.COUNT]
L,NOADV
,
r,PRINT
{(*)S
}
L,l'!2fR!!I (dsname)
..]
r,CSYNTAX
]
, ~1!QJO 11
]
]
L-l!Q~!REF_
J lr NOTEll.r!
[,ENDJOB
L,!!QB]SI1!EN!
J
f,SXBEF
I
I
•
I
t
r,OPTIM1ZE
..
L, !!.QI~~! j
]
L,lioOPTIH1Zr; L. NO~Il!IAI
1
r,TEsT
1
lrFtAGE
, LSTCOMP
l
lr !21H!!1j
r,NUM
[,§YSI]
,SYS·x
1
6J[,LCOL1 6J
.1£QL2
1NO~
t
~
[,FDECK
6l
,!fop Q~~.K j
1
r
[.CDECK
6l
f,L 11~
, Noc~g j
~ L 120
r.L, VBSUMBS!!!!jl r.lr
6l
j
NO V
]>
VBREF
NOVBllI::
1~3
1Lin kage Editor:
1
I
I
{PARM
PARM.
procst.ep
}.
=
[fl{MAP}l
X REP' J
[ , LIST]
[.OVLY])
~
:I {!!::. procstep}
t
=
[:~:Al~] [::~:ES]
[, EP=name ]
r
~;~~LL]
[,PRINT
[:~~rt;!]
]
, !!QPR1!~.
[: ;i;::!~~~J
1~
J Execution:
I
I {PARM}
[FLowr:nn
DEBUG
]
I
PARM. procstep :: {[ user parameters]/
!!Ql1&!
• NODE BUG [, UPSI (nnnnnnnn) ]
J
t
[, A1XBLD
]
r ,QUEUE{value-list) ]) lZ3
I
, NOA.IIJaI!
.----------------------------------------------------------11 If the information specified conta ins any special characte.rs, it must be delimited by
I single quotation marks instead of parentheses.
,ZIf the only special character contained in the value is a cOlima. the value may be
I enclosed in parentheses or quotation marks.
13 Themaximum number of characters allowed between the deli1liting quotation marks or
1 parentheses is.100.
,-These options should be used in the Time Sharing environment only.
J STso-only forma t.
16 These options are used to request the lister fea ture.
1]·
'-
[,
I
I
f
I
I
:
I
t
,
f
I
,
I
,
I
I
I
f
,
I
I
I
I
,
I
I
I
------------------------------------------------------------.------------------------~
Figure
46
I
I
I
I
I
I
I
I
I
I
ILoader:
f
I
,
I
I
J
r, Q!loT~l
~APOSTj
r,l1£AGW]
l!l!Q!!LE!
,l!OFLOW
r,SYMDMP
I
r.XREF
[,FLOW[:nnJl
,!211!I£H
t
t
]
[,SEQ l
, NOSEQj
lr!QJl!~!ij
L-NOCLISIj
L, NOS!!!~
,SPACE2
"SPACE3
l
r,DECK
l
r, CLIST
[,LINECNT=nn]lrl!QtRU!£
l
[,SOUBCE
[,DMAP ]
, NOSOURCEJ ' NODMAP
8.
compiler, Linkage Editor, and Loader PARM Options
PRINT
(*)
specify FLOW, STATE, COUNT, SYMDMP, or
BATCH.
}
{
(dsname)
l!Q.PRll!
indicates whether or not the program
listing is to be suppressed, placed on
the out pu t data set specified by
dsname, or displayed at the terminal.
If PRINT is specified, the listing
will include page headings, line
numbers of the statements in error,
message identificati~n numbers,
severity levels, and message texts (as
well as any other output requested by
SOURCE, CLIST, DMAF, P~AP, XREF, or
SIBEF). If (*) is specified instead
of data-set name, the printed output
is sent to the term inal. If PRINT
alone is specified, a listing data set
is created on secondary storage and
named according to standard da ta set
naming conventions. NOPRINT specifies
that no listing is to be printed. If
nei ther PRINT nor NOPRINT is
specifiedand anyone or more of the
options SOURCE, CLIST, DMAP, XREF, or
PMAP are specified, PRINT is the
default. Otherwise, NOPRINT is the
default. If PRINT is specified in a
non-TSO environment, it is ignored.
TERM
NOTERlI
---indicates whether or not progress and
diagnostic messages are to be printed
on the SISTERM terminal data set. The
severity level of the messages may be
controlled by the FLAG option. If
PRINT (*) is specified, then NOTERM is
the default, to ensure that messages
appear only once. If TERM is
specified in a non-TSO environment,
the output that normally goes to the
SISTERM DO data set is written on the
SYSTERM file if a SYSTERM DD card bas
been included. If there is no SISTERM
DD card, a warning message is issued.
TEST
NOTEST
--indicates whether or not the program
can be debugged at the terminal using
the program product IBM OS COBOL
Interactive Debug (Program Number
5734-CB4). A program that is compiled
without the TEST option is
unacceptable to the Interactive Debug
command processor. Complete
information on COBOL Interactive Debug
is contained in IBM as COBOL
l!!1tla£ti.!LQgQuq Ierir1!9.1:Q~~
If the TE,T option is in effect, the
SISUT5 data set must be specified.
The TEST option is rejected if both
WITH DEBUGGING MODE is specified and
one or more USE FOR DEBUGGING
statements are in the program.
QEtions for the
Links!SULj~gilQ!:
MAP
indicates that a map of the load
module is to be listed.
If MAP is
specified, XREF cannot be specified,
but both can be omitted.
XREF
indicates that a cross-reference list
and a module map are to be listed. If
XREF is specified, MAP cannot be
specified.
LIST
indicates that any linkage editor
control statements associated with the
job step ~re to be listed.
OVLY
indicates that the load module is to
be in the format of an overlay
structure. This option is required
when the COBOL Segmentation feature is
used.
The format of the PARM parameter is
illustrated in Figure 8. For examples of
what the MAP, XREY, and LIST options
produce, see "Output. tI Linkage edito.r
control statements and overlay stru~tures
are explained in "Calling and Called
Programs." There are other PARM options
for linkage editor processing that describe
additional processing options and special
attributes of the load module (seethe
publication QS.L!S._1!n.!.a~~{!itor an.S!
Load,g,!;l..
MAP
NO MAP
----indicates whether or not a map of the
loaded module is to be produced that
lists external names and their
absolute addresses on the SYSLOUT data
Guide~nd Ref~£ID!£~.
set. If the SYSLOUT DD statement is
not used in the input deck, this
When TEST is in effect, the COBOL
option is ignored. An example of a
compiler produces optimized object code.
module map is shown in "output."
When you specify TEST, you cannot also
Job Control Procedures
47
R.~~
NOBES
indicates whether or not an automatic
search of the link padt area queue is
to be made. This search is always
made after processing the primary
input (SYSLIN), and before searching
the SYLIB data set.
When the RES
option is specified, the CALL option
is automatically set.
CA~!:.
NOCALL (NCAL)
indicates whether or not an automatic
sea rch of the S ISLl B da ta set .1s to be
made.
If the SYSLIB DD statement is
not used in the input deck, this
option is ignored. The NOCALL option
causes an automatic NORES.
LET
NOLET
-----indicates whether or not the loader
will try to execute the object program
when a severity level 2 error
condition is found.
S.I~~=1QQI1
SIZE=size
specifies the size, in bytes, of
dynamic main storage that can be used
by the loader. This storage must he
larqe enouqh to accommodate the object
program.
EP=name
specifies the external name to be
assigned as the entry point of the
loaded program.
ERINT
NOPRINT
indicates whether or not diagnostic
messages are to be produced on the
SYSLOUT data set.
The format of the PARM parameter is
illustrated in Figure 8.
The default
options, indicated by an underscore, can he
changed a t system genera tion with the
LOADER macro instruction.
These options are specified through the
PARM parameter, as illustrated in Figure 8.
Note that a slash must immediately precede
the first COBOL-defined option coded.
(If
user parameters themselves are to include
a slash or slashes, then an additional,
trailing slash must be added to demark the
user parameters' end. All data following
the last slash is considered to be COBOL
system parameter information, and will
not be passed to the program.)
48
If an execution-time parameter field
is passed to a program, a load of the
library subroutine ILBOPRM will be issued.
If this subroutine is not available to the
loader, an 806 abend may occur. One way
to circumvent this problem is to place
an INCLUDE SYSLIB(ILBOPRM) statement in
the link edit SYSLIN data stream, which
would link this subroutine into the load
data set.
User Parameters
The programmer can code any parameters
he wishes to pass to a main COBOL
program. For information on how to
access such parameters, see the "USING
option" as described in I~~-I~_£Q]Q~
foL-QUVS.
FLOV[ =nn]
NOFLOW
- - - I f the FLOW option is specified at
compile time for a trace of procedure
names, at execution time a value for
un may be specified that overrides any
value set at compile time.
If FLOW is
requested at compile time with no
value for !U!., a value should be
specified at execution time.
A
default of 99 is assumed for lHl if it
is not specified at either step and
PLOW is in effect; otherwise, nn is as
previously specified.
The PLOW trace may be suppressed at
execution time by specifying NOFLOW.
FLOW cannot be specified as an option
for exedution if it is not specified
at compilet~me or if NOFLOW is in
effect by default. See the sections
"Debugging Facilities" and "Options
for the Compiler" for additional
information.
DEBUG
NODEBUG
DEBUG indicates that USE FOR DEBUGGING
declarative procedures are in the
program and should in fact be
activated during th~s execution.
NODEBUG indicates that even though
such declarative procedu.resvere
included in the program, they are not
desired and their execution is to be
suppressed.
(Note that this DEBUG
switch has meaning only if the source
program was compiled with the WITH
DEBUGGING MODE clause.)
UP 51 (n nnnnnnn)
assigns values (either ~ero or one) to
the eight switches UPSI-O, UPSI-1,
UPSI-2, •••
UPSI-7.
(The default
values are zeros.)
These values are
then available in the COBOL program
through the condition names associated
with them in the SPECIAL-NAMES
paragraph.
AIXBLD
NOAIXBItA2
for VSAM KSDS and RRDS data sets,
AIXBLD indicates that COBOL should
invoke Access Method Services to
complete the file and index definition
procedures. NOAIXBLD indicates that
the user has already performed such
definitions himself ahead of time, and
has no need for this service.
In general, better performance is
obtained if the user provides such
definitions himself (NOAIXBLD). If
AIXBLD is specified, substantial
amounts of additional storage are
required for COBOL execution (the
exact amount depending on specific
Job Control Procedures
48.1
system configuration).
Also, a
SYSPRINT DO card is necessary for any
Access Method Services messages that
may be produced.
For more detail, see "Dynamic
Invocation of Access Method services
for KSDS and RRDS output Data sets" in
the section "VSAM File Processing."
QUEUE{value-list)
specifies a queue-name structure (in
value-list) which is the strQcture
that viII cause this program to be
scheduled for execution. For more
detail, see "Communications Job
Schedulinq" in the section "Using the
Communications Feature."
The restart facilities can be used in
order to minimize the time lost in
reprocessing a job that abnormally
terminates. These facilities permit the
automatic restart of jobs that were
abnormally terminated during execution.
The programmer uses this parameter to
tell the operating system:
(1) whether or
not to take checkpoints during execution of
a progra m, and (2) whether or not to
restart a proqram that has been
interrupted.
A checkpoint is taken by periodically
recording the contents of storage and
registers during execution of a program.
The RERUN clause in the COBOL language
facilitates taking checkpoint readings.
Checkpoints are recorded onto a checkpoint
data set.
Execution of a job can be automatically
restarted at the beginning of a job step
that abnormally terminated (step restart)
or within the step (checkpoint restart).
In order for checkpoint restart to occur, a
chec kpoint must have been taken in the
processing program prior to abnormal
termination.
The RD parameter specifies
that step restart can occur or that the
action of the CHKPT macro instruction is to
be suppressed.
To request that step restart be
permitted or to request that the action of
the CHKPT macro instruction be suppressed
in a particular step, code the keyword
parameter in the operand field of the EXEC
statement.
rRD=request
J
JL-____________________________________________
Replace the word "request" with:
a
to permit automatic step restart.
The programmer must specify at
least one RERUN clause in order
to take checkpoints.
Ne
to suppress the action of tbe
CHKPT macro instruction and to
prevent automatic restart.
No
checkpoints are taken; no RERUN
clause in the COBOL program is
necessary.
NR
to request that the CHKPT macro
instruction be allowed to
establish a checkpoint, but to
prevent automatic rest~rt. Tbe
programmer must sp..eeify at least
one RERUN clause in order to take
checkpoints.
RNC -- to permit step restart and to
suppress the action of the CHKPT
macro instruction.
No
checkpoints are taken; no RERUN
clause in the COBOL program is
necessary.
Each request is described in greater detail
in the following paragraphs.
RD=!: If the processing programs used by
this step do not include a RERUN statement,
RD=R allows execution to be resumed at the
beginning of this step if i t abnormally
terminates.
If any of these programs do
include one or more CHKPT macro
instructions (through the use of the RERUN
clause), step restart can occur if this
step abnormally terminates before execution
of a CHKPT macro instruction; thereafter,
checkpoint restart can occur.
RD=NC or RD=RNC:
RD=NC or RD=RNC should be
specified to suppress the action of all
CHKPT macro instructions included in the
programs used by this step.
When RD=NC is
specified, neither step restart nor
checkpoint restart can occur. When RD=RNC
is specified, step restart can occur.
!Q=NR:
RD=NR permits a CHKPT macro
instruction to establish a checkpoint, but
does not permit automatic restarts.
However, a resubmitted job could have
execution start at a specific checkpoint.
Before automatic step restart occurs,
all data sets in theresta rt step vi th a
status of OLD or MOD, and all data sets
being passed to steps following the restart
step, are kept. All data sets in the
restart step with a status of NEW are
Job Control Procedures
49
deleted. Before automatic checkpoint
restart occurs, all data sets currently in
use by the job are kept.
If the RD parameter is omit ted and no
CHKPT macro instructions are e.%ecuted,
automatic restart cannot occur. If the RD
parameter is omitted but one or more CHKPT
macro i.nst.ructions are executed, automatic
check.point restart can occur.
• If the RD parameter is specified on the
JOB statement, RD parameters on the
job's EX EC statements are iqno.red.
• Restart can occur only if MSGLEVEL=1 is
coded on the JOB statement.
step, code the keyword parameter in the
operand field of the EXEC statement.
,
DPRTY:(value 1.value 2)
Both "value 1" and "value 2" should be
replaced with a number from 0 through 15.
"Value 1" represents an internal priority
value. "Value 2" added to "value 1"
represents the dispatching priority. The
higher numbers represent higher priorities.
A default value of 0 is assumed if no
number is assigned to "value 1." A default
value of 11 is assumed if no number is
assigned to "value 2."
• If step restart is requested for this
step, assign the step a unique step
name.
• Whenever possible, avoid assigning a
number of 15 to "value 1." This number
is used for certain system tasks.
• When this job step uses a cataloged
procedure, make restart request for a
single procedure step by including, as
part of the RD parameter, the procedure
stepname, i.e., RD.procstepname. This
specification overrides the RD
parameter in the named procedure step
if one is present. Code as many
parameters of this form as there are
steps in the cataloged procedure.
• If "value 1" is omitted, the comma must
be coded before "value 2" to indicate
the absence of "value 1," e.g.,
DPRTY= (. 14) •
• If "value 2" is omitted, the
parentheses need not be coded, e.g.,
DPRTY:12.
• When the step uses a catalogea
procedure, a dispatching priority can
be assigned to a single procedure step
by including the procedure step nalle in
the DPRTY parameter, i.e.,
DPRTY.procstepname={value 1, value 2).
This parameter may be used for each
step in the cataloged procedure.
• To specify a restart request for an
entire cataloged procedure, code the RD
parameter without a procedure stepname.
This specification overrides all RD
parameters in the procedure if any are
present.
• .If no RERUN clause is specified in the
user's program, no checkpoints are
written, regardless of the disposition
of the RD parameter.
• To assign a single dispatching priority
to an entire cataloged procedure, code
the DPRTY parameter without a procedure
step name. This specification
overrides all DPRTY parameters in the
procedure if there are any.
• For detailed information on the
checkpoint/restart facilities, see the
publication Q~!~_Check2ointLR~1art.
.E§!:~blishing-LDis2fttcli.l!.9.-f.riQ1::itL'DPR.n1..
To assi gn a limit to the computing time
used by a single job step, a cataloged
procedure, or a cataloged procedure step,
code the keyword parameter in the operand
field of the EXEC statement •
(OS/VS2 only)
The DPRTY parameter allows the
programmer to assign to a job step, a
dispatching priority different from the
priority of the job. The dispatching
priority determines in what sequence tasks
use main storage and computing time. To
assign a dispatching prior ity to a job
50
I
r-
J
TIME=(minutes,seconds)
L-___________________________________
such an assignment is useful in a
multiprogramming environment where more
than one job has access to the computing
system. ftinutes and seconds represent the
maX1mum number of minutes and seconds
allotted for execution of the job step.
To specify a region size, code the
keyword parameter in the operand field of
the EXEC statement.
,
REGION= (nnnnnK)
• If the job step requires use of the
system for 24 hours (1440 minutes) or
longer. the programmer should specify.
TIME=1440.
Using this number
suppresses timing.
The number of
seconds cannot exceed 59.
• If the time limit is given in minutes
only, the parentheses need not be
coded; e.g., TIME=5.
• If the time limit is given in seconds.
the comma must be coded to indicate the
abse.nce of minutes; e.g., TIME=(,45).
e When the job step uses a cataloged
procedure, a time limit for a single
procedure step can be set by qualifying
the keyword TIME with the procedure
step name; i.e •• TIME. procstep=
(minutes.seconds). This specification
overrides the TIME parameter in the
named procedure step if one is present.
As many parameters of this form can be
coded as there are steps in the
cataloged procedure.
I
To request the maxillu. amount of main
storage required by t.he job, replace the
term "nnnnn" with the maximum number of
contiguous 1024-byte areas allocated to the
job step. e.g., REGION=52K. This number
can range from 1 to 5 digits but must not
exceed 16383.
If the REGION parameter i~ omitted or if
a region size smaller than the default
region size is requested, it is assumed
that the default value is that establiShed
by the input reader procedure.
eRegion sizes for each job step can be
coded by specifying the BEGION
pa rameter in the EXEC sta temen t for
each job step. However, if a REGION
parameter is present in t.he JOB
statement, it overrides REGION
parameters in EXEC statements.
• To set a time limit for an entire
procedure, the TIME keyword is left
unqualified. This specification
overrides all TIME parameters in the
procedure if any are present.
• For information on storage requirements
to be considered when specifying a
region size, see the appropriate
st~gg~E§!im~!~§ publication.
e If this parameter is omitted, the
standard job step time limit is
assigned.
~~g£ if y,!.ng.J1 a i.!L..~.!Q~~ Reg!!irem,,gn t
~Qb S!~-'REGION)_
s f or ~
TO take advantage of the storage
facili ties offered by OS/VS 1 and OS/VS2,
always specify AOORSPC=VIRT.
r-
The REGION parameter permits the
programmer to specify the size of the main
storage region to be allocated to the
associated job step. The REGION parameter
specifies the maximum amount of main
storage to be allocated to the job. This
amount must include the size of those
components required by the userts program
that are not resident in main storage.
1
I
ADDRSPC=
VI.!!!}
{ REAL
Note that the compiler and its object code,
including library subroutines, can run
VIRTUAL, and should be run that way unless
a non-COBOL program in the partition
requires the REAL option.
The REGION parameter is used in
conjunction with the ADDRSPC parameter to
determine the total amount of main storage
available to a program and to either allow
or disallow paging.
!21~:
The REGION parameter has different
meanings for OS/VS1 and OS/V52. See the
publicationOSLVS_~£1_~!..!ic~§ for detailed
information.
The data de£inition (DO) statement
identifies each data set that is to be used
in a job step, and it furnishes info.rmation
about the data set. The DD statement
specifies input/output facilities requir~d
Job Control Procedures
51
for using the data set; it also establishes
a logical relationship between the data set
and input/output references in the program
named in the EXEC statement for the job
step.
Figure 9 is a general format of the DD
statement.
52
Parameters ,used most frequently for
COBOL ptograms are discussed in detail.
The other parameters (e.g •• SEP and AFr)
are mentioned briefly. For further
information, see the publication Q~LY~_J~b
~~~.
,
,
.--
---_ ..,.
...
Operand
1 operation
I
~.
rI
i
----~----~-------~
1
I DD
t
}
• {ddname
(see below and next page)
~
III
I
I
procste p. ddna me
1
I
IName
L-
,•
----------------------.------~------------------------~
a
r
I Operand 2
.
I
I
•I
[ DUKMY]
I
I
t
I
I [DDNAME=ddname]
12
I
I
,
,
j
DSNAMEl
f
{ DSN
J
J
I
I
I
=
dsname
dsname (element)
*. ddname
*.stepname.ddnalle
*.stepname.procstep.ddname
&&nalle
&&name(element)
NUtLF.ILE
, (QNAME=processname)l4
!
[nCB=
I
(liS[:s::.:ttributeSl
DCB=(
,
I
I
*.ddname
*.stepname.ddname
·*.stepname.procstep.ddnaae
J
[SEP= (SU bparalleter list)
,AFF=ddname
•
[COPIEs=nnn]
t
:I
]
-l
J
7
[ .SIlbParaaeter-list 1,]
11
[ OUTLIM=nuliber]
[TEBM~;1
:I
t
f2§i tioM.~bpa!:~iG
:
,
[UNIT= (name[ ,[n/P][,DEl'ERllt: ,SEP=(list
~NIT=(AFF=ddnaae)
I
[!les= (character set code
,FOLD
I
,
·l!ll2IUyREnu.nU§.
up to 8 ddna.es) ])
. .
[ , VilIFY])]
o.
f
I
9] 11 13
....
f See
:I
L-__________
.~_____,
notes a.____________________________________________________________________
t end of fig ure.
Figure
9.
.
I
I
I
~
The DD Statement (Part 1 o.f 3)
Job Control Procedures
S3
,
.--
I Operand 2
lI
I
: SPACE= (
•
J
----i
I
{~~~
, (primary-quantity[,secondary-quantity],
}
averaqe-record-length
,
I
I
1
[directory- or index-quantity]) [ , RLSE]
J
J
, riXLG
,ALX .
[ ,CONTIG
,
I
[ , ROUND])
I• SPACE= (ABSTR, (quantity ,beginning-address[ , directory- or index-quantity]»)
•
: SPLIT= (n,
I
,
~
SUBALLOC=(
J
{CYL
}
average-record-length
{~!~
, {primary-quant.ity[ ,secondary-quantity]))
},
(primary-quantity[ ,secondary-quantity]
I
1
1
1
I
J
[.directory-qnantity». {::::::me.ddname
. }
stepname.procstep.ddname
sequence number 1.[ volume count][.J
: SER= (volume-serial-n umber( Yolume-serial-nu mber ]I 0 • • •
{~~~~:=me
}
*.stepname.ddname
*.stepname.procstep.ddname
1----------------------I See notes at end of figure
)ll
)
f
I
t
J
J
1
I
I
I
I
.,I
I
J
L-
54
,
t
!~~g~UKE} =~ PRIVATE l.[ RETAIN l.[ volulle
Figure
J
I
J
I
: REF::
I
,
J
I
I
,average-record-length
i
,,
,
9.
The DD statement (Part 2 of 3)
r0-
t operand 2
..-
,
I
I
NL
I
I
NSL
SUL
I LABEL= ([ data-set-sequence-number] .. ~1
t
~M
J
BU
,
AUL
At
t
i[Drsp: ( [
l!.RR~
OLD
,DELETE
,KEEP
,PASS
SHR
MOD
1
1
1
r. PASSWORDl [f',OUT
IN J
~NOPWREA~
, EXPDT=yydddl
[ • RETPD=xxxx
J
[ ,CATLG
.UNCATLG
[s YSOUT= (classname[
.. program-name]( , form-no. ])]
t
rFeB= (image-id
L
[,ALIGN])
, V ERIPY
"J
I [AMP=(subparameters) 15]
lI tThe name field must be blank vhen concatenating data sets.
I
1 ZA 11 parameters are optional to allow a programmer flexibility in the use of the DD
J
I
statement; however, a DO statement with a blank operand field is meaningless.
I
I 3It the positional parameter is specified, keyword parameters other than DeB cannot be I
I specified.
J
I ·For OS/VS2 only.
1
t sIt sub parameter-list consists of only .2{!g subparameter and no leading comma
J
I
(indicating the omission of a positional subparameter) is required, the delimiting
I
t
parentheses may be omitted.
I
1 61f subparameter-list is omitted, the entire parameter must be omitted.
I
1 7See "UseI:'-Defined Files" fo.r the applicab le subpa rameters.
1
I eSee the publication Q~!~~£1-Ref~~£g.
.
I
f 9If only name is specified, the delimiting parentheses may be omitted.
I
1 10 rf only one volume-serial-number is specified, the delimiting parentheses may be
t
,
omitted.
I
11 t The SEP and AFF parameters should not be confused with the SEP and AFF subparameters 1
J of the UNIT parameter.
J
J
1 1z The value specified may contain special characters if the value is enclosed in
1 a postrophes. If the only special character used is the hyphen. the value need not bel
I
J
enclosed in apostrophes.
If DSNAME is a qualified name, it may contain periods
t without being enclosed in apostrophes.
I
,13The unit address may contain a slash, and the unit type number may contain a hyphen, I
1 without being enclosed in apostrophes, e. g., UNIT=293/5,UNIT=2400-2.
I
J14The QNAME= parameter is used in COBOL teleprocessing and must be the name of a TeAM I
1 destination queue.
1
J lSThis parameter is for use with VSAM only.
The subparameters are described in the
J
! chapter "VSAM File Processing."
f
.I
L-
Fiqure
9.
The DD Statement (Part 3 of 3)
Job Control Procedures
55
DL~f~~~~Chan~illg_Qatg_Qg!i~itgr_fQ£
1i~.!!.Lf.!~!g
ddname (Identifying the DD statement)
is used:
InID!:L~!!!.)
specifies the delimiter to be used
instead of /* or II to terminate data
defined in the input st~eam.
Assigning a different delimiter allows
the standard delimiter f/* or II) to
be used as data in the input stream.
The DLM pa~ameter has meaning only on
DD* and DO DATA statements. The data
must be terminated with the characters
assigned in the DLM parameter.
• To identify data sets defined by
this DD statement to the compiler or
linkage editor (see "Compiler Data
Set Requirements" and "Linkage
Editor Data Set Requirements").
• To relate the data sets defined in
this DD statement to a file
described in a COBOL source program
(see "User-Defined Files").
• TO identify this DD statement to
other control statements in the
in put stream.
procstep. ddname
is used to alter or add DD statements
in cataloged procedures.. The step in
the cataloged procedure is identified
by procstep. The ddname identifies
either one of the following:
• A DO statement in the cataloged
procedure that is to be modified by
the DD statement in the input
stream.
•
A DO statement that is to be added
to the OD statement in the procedure
step.
!_~!.tl~r
~!:~n)
(DefininLQg,ta_in an Inl!ut
indicates that data immediately
follows this DD statement in the input
stream. This parameter is used to
specify a source deck or data in the
input stream.
The data cannot contain
II or 1* in the first two character
positions of any record unless the DLM
parameter is used. If (while scanning
JCL) the system encounters a card that
does not begin with II, it logically
inserts a IISYSIN DD * card before it.
The SYSIN data set thus created is
delimited by the next 1* or II job
control card encountered.
DA TA ParSll!!tter (De!.ining.-Q~!a in an .Input,
Streaa)
also indicates a JCL deck or data in
the input stream. The end of the data
set must be indicated by a delimiter
statement. The data cannot contain /*
in the first two characters of any
recprd unless the DLK parameter 'is
used. The DD DATA statement must be
the last DD statement of the job step.
II may appear in the first and second
positions in the record, for example,
when the data consists o.f control
statements of a procedure that is to
be cataloqed.
56
DUMMY ParameterlBypassing_!!g.!l£g
Allocation and ~Yi-QEQ£a~iQll§-2n_~h~~2i~
§.gi)
allows a program to attempt I/O
operations on a data set during
execution without the operating
systemfs pe~forming actual operations
on the da ta set.
(Programs compiled
with the LANGLVL(2) option can specify
the COBOL source statement SELECT
OPTIONAL to obtain this ability and
thus avoid supplying a dummy DD
statement.)
The DUMMY parameter is
valid only for COBOL input sequential
data sets. No device allocation#
external storage allocation, or
cataloging takes place for dummy data
sets.
When the DUMMY parameter is
specified, a read request to an
"opened" file results in an end of
data set exit.
For a VSAM data set, if DUMMY is
specified, an attempt to read results
in an end-of-data condition.
AMP='AMORGt must be specified if DUMMY
is specified; see "VSAM-only JCL
Parameter" in the chapter "VSAM Pile
processing. "
NO!&..:.
Compiler work. files (including
SYSUT5 and SYSUT6) cannot be described
as DD DUMMY.
Data in the input stream is temporarily
transferred to a direct-access device for
later high-speed retrieval.
Normally, the
system stores it in a format that is not
under control of the programmer.
However,
in some situations the programmer may be
able to assign his own values through use
of the BLKSIZE subparameter of the DCB
parameter.
He may also indicate the number
of buffers to be assigned to transmitting
the data, through use of the BurNO
parameter. For example, he may assign the
following:
DCB=(BLKSIZE=800,BUFNO=2)
In YS1 and VS2 Release 2 ~nd later, maximum
performance is obtained for SYSIN and
SYSOUT data sets when BLKSIZE=80 and
BUrN0:1 are used.
If not supplied by the
problem program, i t can be supplied by the
DCB parameter on the DD statement.
If
omitted from both sources, the defaults are
BLKSIZE=80 and BUFNO=2.
• Sim~~2:
For data sets that
are not cataloged.
• Reference names:
For data sets
whos;-na;es-;r;-given in the DSNAME
parameter of another DD statement in
the same job.
Jll1i!1Lf£!:~U!~g!tl-1Rg~gr vi.llil2 pa cgJ!!9.tl
Q~L.!S2_w i
tIL TSQ)
specifies that space is to be reserved
in internal tables so that data set
requirements that arise during a TSO
terminal session can be satisfied.
This allows deferred definition of a
data set until it is required.
During
LOGON processing for T50, no devices
or external storage are allocated to a
data set defined by a DD DYNAM
statement.
When a data set is
required, the actual device and
external storage for the data set is
then allocated.
see the publication
.Q~LVS2 TSO Guide, Order No. GC28-0644,
for further information.
!Q!.g:
No other parameter can be
specified on a DD statement where
DYNAH is specified.
~Q~!~~-f£~~ete!:-1p02~~nin~he
Deiinitio!
QI._£ Dat£_SeU
defines a pseudo da ta set that. will
assume the characteristics of a real
data set if a subsequent DD statement
of the step is labeled with the
specified ddname.
When the DDNAME
parameter is specified, it must be the
first parameter in the operand.
All
other parameters, except the DeB
subparameters BLKSIZE, BUPNO, and
OIAGNS, are ignored and should be
omitted when the DDNAME parameter
appears (see "Using the cataloged
procedures").
The ddname specifies a DD statement
that, if present, supplies the
attributes of the data set. If it is
not present, the statement is ignored.
DS!!ME Pa~A!~~~Igenti!Yin~lh~~ata~~lt
allows the programmer to specify the
name of the data set to be created or
to refer to a previously created data
set.
Various types of names can be
specified (see "using the DO
statement" for a discussion of the
various names) as follows:
• :t:J!llI--!U!alifi.g9.-D.n~.:. For da ta
sets to be retrieved from or stored
in the system cat alog.
• Gen~ation 9A1.sL9.!:Q!:uL.!!n~i. For an
entire generation data group. or any
single generation thereof.
•
I~~pora~~_n£~~~
For temporary data
sets that are to be named for the
duration of one job only.
If the DSNAME parameter is omitted,
the operating system assigns a unique
name to the data set.
(This parameter
should be supplied for all except
temporary data sets to allow future
referencing of the data set.)
DSNAKE
may be coded DSN.
~SNAMI-SYQQa~a~~te!:~
dsname
specifies the fully qualified
name of a data set.
This is the
name under which the data set can
be cataloged or otherwise
identified on the volume.
dsname (element)
specifies a particular generation of a
generated data group, a member of a
partitioned data set. or an area of an
indexed data set.
To indicate a
generation of a generated data group,
the element is a zero or a signed
integer.
TO indicate a member of a
partitioned data set, the element is a
name.
To indicate an area of an
indexed data set. the element is
PRIME, OYFLOW, or INDEX (see "Using
the DD statement" for information
about generation data groups and
examples of partitioned data sets).
*. ddname
indicates that the DSNAKE parameter
(only) is to be copied from a
preceding DO statement in the current
job step.
*.stepname.ddname
indicates that the DSNAME parameter
(only) is to be copied from the DD
statement, ddname, that occurred in a
previous step. stepname, in the
current job.
If this form of the
subparameter appears in a DD statement
of a cataloged procedure, stepname
refers to a previous step of the
procedure, or. if no such step is
fOllnd , t o a previous step of the
current job.
*.stepname.procstep.ddname
indicates that the OSNA"E parameter
(only) is to be copied from a OD
statement in a cataloged procedure.
The EXEC statement that called for
Job Control Procedures
57
a cataloged data set or from a
preceding DD statement (see the
publication QS.LILJCL._R~fe~~ for
detailed information about the DCB
s ubpa ra meter) •
execution of the procedure, as well as
the step and DD statement of the
procedure, must be identified.
&&name
allows the programmer to supply a
temporary name for a data set that is
to
deleted at the end of the job.
The ope.rating system subs-t.i tutes a
unique symbol for this sub parameter.
The programmer can use the temporary
name in other steps to refer to the
data set. The same symbol is
substituted for each recurrence of
this name within the job. Upon
completion of the job, the name is
dissociated from the data set. The
same temporary name can be used in
other jobs without ambiguity.
be
&&name (element)
allows the programmer to supply a name
for a member of a temporary
partitioned data set that will be
deleted at the end of the step.
NtJLLFILE
serves the same function as the DUMMY
parameter (described above).
Q!!I~~~~~~_lnefinin]L!a~_Oata t2-~
A££es§ed-IlLTCA1U.
specifies the name of a TPROCESS macro
that def~nes a destination queue for
messages that are to be processed by
an application program and creates a
process entry ~or the queue in the
Terminal Table (see the section
"Defining Terminal and Line Control
Areas" in the chapter entitled "Using
the Teleprocessing Featu.-re tf ) .
Not!t: The DCB parameter is the only
parameter that can be coded on a DD
statement with the QNAME parameter.
The only operands that may be
specified as subparameters are
BLKSIZE, BtJ~L, LRECL, OPTCD, and
RECFM.
DCll_~~teLjDe§£Iibin£L1l!e
11H~_Da ta~etl
Altributes of
allows the programmer to specify at
execution time, rather than at
compilation time, information for
completing the data control block
associated with the data set (see
"Execution Time Data Set Requirements"
and "Additional File Processing
Information" for further information
about the data control block and DCB
subparameters).
The first subparameter of this
parameter may be used to copy DCB
attributes from the data set label of
58
and AFLf.Srame~jQ£!i.m.izi!!g.£.ha nn~!
Usage)
allow the programmer to optimize the
use of channels among groups of data
sets. SEP indicates channel
separation and APr indicates channel
affinity. SEP and APF are ignored for
any data sets that have been allocated
devices by the automatic volume
recognition (AVR) option.
,S,lP
If neither parameter is supplied, any
available channel, consistent with the
UNIT parameter requirement, is
assigned. The affinity parameter
groups two or more data sets so that
they can be separated from another
data set requesting channel
separation. For indexed sequential
data sets these parameters are written
in the same way as those for any data
set. For VSAM data sets, these
parameters should not be used if the
data and its index reside on unlike
devices. They can be used in
succeeding DO statements to refer to
the first DD statement. ~efining an
indexed sequential da ta set. However,
the second and third OD statements
cannot request separation from or
affinity to one aaother because they
are unnamed. Thus, to establish
channel separation and affinity for
all of the areas, the name
subparameter of the UNIT parameter
must be used to request specific
dey ices on specific chann~ls.
UNll-fArameter (Requesting_a UnitL
specifies the quantity and types of
input/output devices to be allocated
for use by t.he data set.
If the UNIT parameter is not specified
in the current DD statement~ there are
several ways in which the unit
information may be inferred by the
system:
• If the current data set has already
been created and it is either beinq
passed to the current step, or if it
has been cataloged~ any unit name
specified in this DO statement is
ignored.
• If the REP subparameter of the
VOLUME parameter is specified, the
current data set is given affinity
with the data set referred to; that
data set's defining DD statement
provides the unit information.
installation at system generation
time.
• If the current data set is to
operate in the split cylinder mode
with a previously defined data set,
it will reside on the unit specified
in the DD statement for the previous
da ta set.
The block size specified in the source
program (in the BLOCK CONTAINS clause
or in the record description) must not
exceed the maximum block size
permitted for the device.
For
example. the maximum block size for
the IBM 2314 is 1294 characters. and
the maximum block size for the IBM
2400 series is 32.760 characters.
• If the current data set is to use
space suballocated from that
assigned to a previously defined
data set, it will reside on the same
unit as the data set from which the
space is obtained.
liot~:
When device-independence is
specified by use of UT as the device
class in the ASSIGN statement in the
Environment Division, the device
chosen by the system will be dependent
on the OD statement. Therefore. if
the user's installation has both an
IBM 2314 and an IBM 3330 that may be
used as utility devices, the user
should write
• If the current data set is assigned
to the standard output class (sysOUT
is specified), it is written on the
unit specified by the operator for
class A.
If the current data set is in the input
stream (defined by a DD * or DD DATA
statement), the DD statement defining the
data set should not contain a UNIT
parameter.
If this parameter specifies a mass
storage device for a data set being
created, it is also necessary to reserve
the space the data set will occupy, using
another parameter of the DO statement. For
Vs~M data sets, the APF and sEP
subparameters should not be used if the
da ta and its index reside on unlike
devices.
Depending on the way in which the
space will be used, the SPACE, SPLIT, or
sUBALLOC parameter can be specified.
These
parameters are discussed under individual
headings.
BLOCK CONTAINS 7294 CHARACTERS
(or any number smaller than 7294) to
ensure that the block can be contained
on orie track.
n
specifies the number of devices to be
allocated to the data set.
If this
parameter is omitted. 1 is assumed.
p
specifies parallel mount.
DEFER
indicates deferred mounting.
Deferred
mounting cannot be specified for a new
output data set on a mass storage
device or for an I5AM data set.
For VSAM data sets, it indicates that
the volumes are not to be mounted
until access method services requires
them.
If the UNIT parameter specifies a tape
device, no SPACE, SPLIT, or SUBALLOC
parameters are required.
The UNIT parameter must be specified if
VOLUME=SER is specified in the DD
statement.
name
specifies the name of an input/output
device, a device class name, or any
meaningful combination of input/output
devices specified by an installation.
(Mass storage devices and magnetic
tape devices can be combined.
No
other device type combination is
allowed.)
Names and device classes
are defined at system generation time.
The device class names that are
required for IBM cataloged procedures
and are normally used by most
installations are shown in Figure 10.
These names can be specified by the
sEP=(list of up to eight ddnames)
specifies unit separation.
AFF=ddname
specifies unit affinity.
r-------.---
,
,
,
.
I
1Class NamelClass FunctionslDevice Type
I
----.f
Imass storage I
IsY55Q
I writing
Imagnetictape I
I
Jreading
•
I
+~
1mass storage I
ISysDA
I writing
,
I
f
treading
~
Figure 10.
J
Device Class Names Required for
IBM-Supplied Cataloged
ProcedUres
Job Control Procedures
59
a DD statement for a job that is a
system task. RT should not be
specified on DD*, DD DATA and SYSOUT
DD statements.
~QR~a~a!~!~I-1Re~Y~2ti~g_Additional
Q~!~ Set~ie§L
is specified when more than one copy
of the output data sets is desired.
It can be specified only with the
SISOUT parameter on the same DD
statement. The maximum number of
copies that can be requested is 255.
For further information on the use of
the COPIES parameter, see the
publication OSLVS JCL~g£Yi~g2.
TS
indicates to the system that the input
or output data being defined is coming
from or going to a time sharing
terminal. If TSO is not in use. the
DD statement containing the TERM
parameter is treated as a DO DUMMY
statement. Only the DeB parameter can
be specified with TERM=TS; any other
parameters specified on the same DD
statement are ignored.'
QQItIfi-fg~et~_lS~~f~n[_Qut~l_Re£Qrd
t.i.ID.i!)
is specified. for OS/VS1 only. to
limit the number of logical records to
be included- in the output data set
being routed through the output
stream. For OS/VS2, OUTLIM is
ignored. When the limit is reached,
an exit provided by the system
Management Facilities option is taken
to a user-supplied routine that
determines whether to cancel the job
or increase the limit. If the exit
routine is not supplied, the job is
canceled. The largest number that can
be specified is 16717215.
The OUT LIM parameter has meaning only
if the system Management Facilities
option is in use in the system and
job, and step data collection was
selected at system generation. OUTtIN
is iqnored unless SISOUT is coded in
the operand field of the same DD
statement. If OUTLIN is not
specified. the system default will be
used unless SYSODUMP or SYSABEND is
being processed; in this case no
output limiting is done.
H!H!1~I1!m.tlgLl!fQ.tiiL.~ll telLof ~pecia 1
Deyice)
speci fies different in.forma tion for
OS/VS1 and OS/VS2. For VS1. the TERM
parameter notifies the system to the
presence of an RTAM (Remote Terminal
Access Method) device used with RES
(Remote Entry Services). For VS2 with
TSO, the TERM parameter notifies the
system that a data set is coming from
or going to a time sharing terminal.
See the publication
~~~~~l~~l~pecifYin~~h~~ct~~_~~1-fQt
a 1403 or 3211 Printex:)
describes the character set to be used
for printing an output data set on a
1403 or 3211 printer.
In order to use
a particular special character set, an
image of the character set must be
contained in SYS1.IMAGELIB, and the
chain or train corresponding to the
character set must be available for
~se.
The UCS parameter. the DDNAME
parameter, and the DCB subparameters
RKP, CYLOPL. and INTVL# are mutually
exclusive. For further information on
the ues parameter, see the publication
Q~L!~~llt.~!!L£!:QllU!!!illL.L i h:>.!i._
j!atLManagem!Ult·
Q~~SuQ~a~~~!~£~:
character set code
identifies the special character set
to be used for printing the data set.
POLO
specifies that the chain or train
corresponding to the desired character
set is to be loaded in the fold mode.
The fold mode is described in the
publication il!L2811_~2ntroL!!nit,
Order No. GA24-3112.
QUllLRE~_~t!!!!
.f.tQg~m.ti~LQy.ide,
Order
No. GC28-6818, for detailed
information on Remote Entry Services.
/
l~R~~~~.ete~:
RT
indicates that a remote unit record
device is in use for iTA" and that the
usual allocation processing is to be
bypassed. RT can only be specified on
60
VERIFY
specifies that the operator is to
verify that the correct chain or train
is mounted be:fore the data set is
printed. If the VERIFY subparameter
is specified and the FOLD sub parameter
is not, a comma must precede VERIFY
since FOLD is a positional
subpa rameter and its absence IIUSt be
indicated.
to write a record. The directory
quantity is used when initially
creating a partitioned data set (PDS),
and it specifies the number of
256-byte records to be reserved for
the directory of the PDS. It can also
specify the number of cylinders to be
allocated for an index area embedded
within the prime area when a new 15AM
data set is being defined (see the
publication Q~L!~~k_E~f~~~).
~~A~E Pail.!!!.f~L1!!.!.Q.£lli!lg_~2§2iQraq~
~2~£~
specifies space to be allocated in a
mass storage volume. Although SPACE
has no meaning for tape volumes, if a
data set is assigned to a device class
that contains both mass storage
devices and tape devices, SPACE should
be specified. For VSAM data sets,
space i~ allocated through access
method services.
forms of the SPACE parameter may
be used, with or without absolute
track address (ABSTR). The ABSTR
parameter requests that allocation
begin at a specific address.
li~:
The directory contains the name
and the relative position, within the
data set, for each member of a
partitioned data set. The name
requires eight bytes, the location
four bytes. Up to 62 additional bytes
can be used for additional
information. For a directory of a
partitioned data set that contains
load modules, the minimum directory
requirement for each member is 34
bytes.
TWO
~{f~~:T~Ub£A£S~1~f§~
}
TRK
CYL
average-record-Iength
specifies the unit of measurement in
which storage is to be assigned. The
units may be tracks (ABSTR o·r TRK),
cylinders (CIL), or records
(average-record-length, expressed as a
decimal number). In addition, the
AB5TR sub parameter indicates that the
allocated space is to begin at a
specific track address. If the
specified tracks are already allocated
to a nothe r da ta set, the y will not be
reallocated to this data set.
For I5AM data sets, only t.he
elL or ABSTR subparameter is
permitted. When an I5AM data set is
defined by more than one DD statement,
all must specify either elL or AB5TRi
if some statements contain CYL and
others ABSTR, the job will be
abnormally terminated.
Noi~:
(p.r ima ry-qua nti ty[ , seconda ry-qua ntit y)
(,directory- or index-quantity])
specifies thea moun t of space to be
allocated jor the data set. The
primary quantity indicates the number
of records, tracks, or cylinders to be
allocated when the job step begins.
For 15Al"l data sets, this subparameter
specifies the number of cylinders for
the prime, overflow, or index area
(see ftExecutionTime Data Set
Requirements lt ) . The secondary
quantity indicates how much additional
space is to be allocated each time
previously allocated space is
exhausted. This sl1bparameter must !!Q.!
be specified when defining an I51K
data set. If a secondary quantity is
specified for a sequential data set,
the program may receive control when
additional space cannot be allocated
RLSE
indicates that all unused external
storage assigned to this data set is
to be released when processing of the
data set is completed.
~~iG }
{ CONTIG
qualifies the request for the space to
be allocated to the data set. MXIG
requests the largest single block of
storage that is greater than or equal
to the space requested in the primary
quantity. ALX requests the allocation
of additional tracks in the volume.
The operating system will allocate
tracks in up to five blocks of
storage, each block equal to or
greater than the primary quantity.
CONTIG requests that the space
indicated in the primary quantity be
contiguous.
If this subparameter is not
specified, or if any option cannot be
fulfilled, the operating system
attempts to assign contiguous space.
rf there is not enough contiguous
space, up to five noncontiguous areas
are allocated.
ROUND
indicates that allocation of space for
the specified number of records is to
begin and end on a cylinder boundary.
It can be used only when average
record length is specified as the
first subparaaeter.
quanti ty
specifies the number of tracks to be
allocated. For an IS1ft data set, this
Job Control Procedures
61
quantity must be equivalent to an
integral number of cylinders; it
specifies the space for the prime,
overflow, or index area (see
"Execution Time Data Set
Requirements") •
beginninq address
specifies the relative number of the
track desired, .here the first track
of a volume is defined as O.
(Track 0
cannot be requested.)
The number is
automatically converted to an address
based on the particular device
assigned. For an ISAM data set this
number must indicate the beginning of
a cylinder.
directory quantity
defines the number of 256-byte records
to be allocated for the directory of a
It also
new partitioned data set.
specifies the number of tracks to be
allocated for an index area embedded
within the prime area when a new
indexed data set is being defined. In
the latter case, the number of tracks
must be equivalent to an integral
number of cylinders (see the
publication Q.sLlS_~CL_l!eference).
~PL~£g~g~~_1!1!~1ing_~~§§-sto£aqe
~Ei!£&
is specified when other data sets in
the job step require space in the same
mass storage volume, and the user
wishes to minimize access-arm movement
by sharing cylinders with the other
data sets. The device is then said to
be operating in a split cylinder mode.
In this mode, two or more data sets
are stored so that portions of each
occupy tracks within every allocated
cylinder.
~ot~:
SPLIT should not be used a)
when one of the data sets is an ISAM
data set, or b) under VS2 Release 2 or
later.
!!
indicates the number of tracks per
cylinder to be used for this data set
if CYL is specified. If the average
record length is specified, ~ is the
percentage of the tracks per cylinder
to be used for this data set.
}
eYL
{ average-record-length
indicates the units in which the space
requirements are expressed in the next
subpa ca meter.
The units may be
cylinders (CIL) or physical records
(in which case the average record
62
length in bytes is specified as a
decimal number not exceeding 65,535).
If the average record length ~s given,
and the data set is defined to have a
key, the key length must be given in
the DeB parameter of this DD
sta tement.
primary-quantity
defines the number of cylinders or
space for records to be allocated to
the entire group of data sets.
secondary-quantity
defines the number of cylinders or
space for records to be allocated each
time the space allocated to any of the
data sets in the group has been
exhausted and more data is to be
written. This quantity will not be
split.
A group of data sets that share
cylinders in the same device is
defined by a sequence of DD
statements. The first statement in
the sequence must specify all
parameters except secondary quantity,
which is 6ptional.
Each of the
statements that follow the first
statement must specify only I, the
amount of space required.
SQBALLOC Parameter
lAllQ£giinq_Mas§_~lQrag~
~acel
permits space to be obtained from
another data set for which contiguous
space was previously allocated.
This
enables data sets to be stored in a
single volume. Space obtained through
suballocation is removed from the
original data set, and may not be
further suballocated.
The SUBALLOC
parameter should not be used to obtain
space for an 151M data set, nor should
it be used under VS2 Release 2 or
later.
Except for the subparameters
described below, the subparameters in
the SUBALLOC parameter ha ve t he salle
meaning as those described in the
SPACE parameter ..
SUBALLoe Subparameters:
ddname
indicates that space is to be
suballoca ted from the da ta set defined
by the DD statement. ddname, that
appears in the current step.
stepname.ddname
indicates that space is to be
suballocated from the data set defined
by the DD statement, ddname, occurring
in a previous step, stepname. If this
form of the sub parameter appears in a
DD statement in a cataloged procedure,
stepname refers to a previous step of
the procedure, or if no such step is
found, to a previous step of the
current job.
stepname.procstep.ddname
indicates that space is to be
suballocated from a data set defined
in a cataloged procedure.
The first
term identifies the step that called
for execution of the procedure, the
second identifies the procedure step,
and the third identifies the DD
statement that originally requested
space.
!Q1YME-1!Q1L~~~~~t~~-1~g£ifying_yolumg
In£ormatiQnl
specifies information about the
volume{s) on which an input data set
resides, or on which an output data
set will reside.
A volume can be a
tape reel, or a mass storage device.
Volumes can be used most efficiently
if the programmer is familiar with the
states a volume can assume.
Volume
states involve tvo criteria:
the type
of data set the progrdmmer is defining
and the manner in which the programmer
requests a volume.
Data sets can be classified as one
of two types, !~QQ£a£I or
!!Q~!gmQorary.
A temporary data set
exists only for the duration of the
step that creates it.
A nontemporary
data set can exist after the job is
completed. The programmer indicates
that a data set is temporary by
coding:
theUNIT parameter.
Such a data set is
deleted at the end of the job.
The manner in which the programmer
requests a volume can be considered
specific or nQR2~cif!£.
A s~ecific
reference is implied whenever a volume
with a specific serial number is
requested.
Anyone of the following
conditions denotes a specific volume
reference:
• The data set is cataloged or passed
from an earlier job step.
• VQLUPlE=SER is coded in the DD
sta tement.
• VOLUME=REF is coded in the DD
statement, referring to an earlier
specific volume reference.
All other types of volume references
are nonspecific.
(Nonspecific
references can be made only for new
data sets, in which case the system
assigns a suitable volume.)
The state of a volume determines
when the volume will be demounted and
what kinds of data sets can be
assigned to it.
~a§~stor~Vol~~g2:
Mass storage
volum es differ from ta pe volumes in
that they can be shared by two or more
data sets processed concurrently by
more than one job.
Because of this
difference, mass storage volumes can
assume different volume states than
tape volumes. The volume state is
determined by one characteristic from
each of the following groups:
Mount
Allocation
~haracter!sti£§.
~ha£a£t!ll:i§!i£§
Per manent ly
Resident
Reserved
Removable
Public
Private
storage
• DSN AM E=&&name
• No DSNAME parameter
• DISP=(NEW,DELETE). either explicitly
or implied, e.g •• DISP={,DELETE)
• DSNAME=reference, referring to a DD
statement that defines a temporary
data set.
All ot.her data sets are considered
nontemporary.
If the programmer
attempts to keep or catalog a passed
data set that was declared temporary.
the system changes the disposition to
PASS unless DEPER was specified in
~~!!g~1!1_£~id~Qi volumes are
always mounted.
The permanently
resident characteristic applies
automatically to:
• All physically permanent volumes,
such as 2305 Fixed Head storage.
• The volume from which the system is
loaded (the IPL volume).
• The volume containing the system
data sets SYS1.LINKLIB,
SYS1.PBOCLIB, and job scheduler
queue.
Job Control Procedures
63
• Other volumes can be designated as
perma nently resident in a special
member of SYS1.PROCLIB named
PRESRES.
Permanently resident volumes are
always public. The £~2~sl
characteristic applies to volumes that
remain mounted until the operator
issues an UNLOAD command. They are
reserved by a MOUNT command referring
to the unit on which they are mounted
or by a system parameter library
entry. The !:tlQvable characteristic
applies to all volumes that are
neither permanently resident nor
reserved.
Removable volumes do not
have an allocation characteristic when
they are not mounted.
A reserved
volume becomes removable after an
UNLOAD command is issued for the unit
on which it resides.
1
,
t
+----+-----1
r--------------~
I
J
Allocation
,
,Characteristic
I
I
Mo un t
1-------,j
~
ICharacteristic ,public tPrivate ,storagel
~
I
+
•
~
IPermanently
Jsystem lsystem 'system I
I Resident
Jparm.
lparm.
lparm.
I
Jlibrary ,library ,library1
I
J
J or
I
1
I
t
,Default I
I
I
..
Isystem t
I parm.
t
tlibrary JlibrarYI
1
or
1
or t
JMOUNT
IMOUNT
,MOUNT 1
,command lcommand Icommand)
'Reserved
1system
I parm.
Ilibrary
I
or
I
•
I
I
1
,
-t-
J
I-
L
= Not
I
+------~
fDefault ,VOLUME= I
I
IPRIVATE J
JRemovable
fna
Jsystem
1 parm.
--L
na
.J-_ _ _ _
J
I
~
t
applicable
.J
The allocation characteristics,
public, private, and storage, indicate
the availability status of a volume
for assignment by the system to
temporary data sets, and, if the
volume is removable, when it is to be
demounted. A Eubli£ volume is used
primarily for temporary data sets and,
if it is permanently resident, for
frequently used data sets. It must be
requested by a specific volume
reference if a data set is to be kept
or cataloged on it.
If a public
volume is removable, it is demounted
only when its unit is required by
another volume. The programmer can
change a public volume to private
status by specifying VOLUME:PRIVATE.
A priv~~ volume must be requested by
a specific volume reference. A new
data set can be assigned to a private
volume by specifying VOLUME=PRIVATE.
If the volume is reserved, it remains
mounted until the operator issues an
UNLOAD command for the unit on which
it resides. If it is removable, it
viII be demounted after it is used,
unless the programmer specifically
requested that it be retained
(VOLUftE=.RETAIN) or passed
(DISP:,PASS).
Once a removable volume
has been made private, it vill
ultimately be demounted. To use it as
a public volume, it must be remounted.
A 2~~ volume is used as an
extension of main storage, to keep or
catalog non temporary data sets having
nonspecific volume requests. Th~
programmer can assign the PRIVATE
option to storage volumes.
Figure 11 shows how mass storage
volumes are assigned their mount and
allocation characteristics.
64
Figure 11.
Mass Storage Volume States
~~g~lic raEe_!Ql~~2:
The volume
state of a reel of magnetic tape is
also determined by a combination of
mount and allocation characteristics:
Mount
~ha!:~£1~ti21i£2.
Reserved
Removable
Allocation
£hf!!:a£te!:i§li£§
Private
Scratch
The reserved-scratch combination is
not a valid volume state.
Reserved
tape volumes assume their state-when
the operator issues a MOUNT command
for the unit on which they reside.
Thev remain mounted until the operator
issues a corresponding UNLOAD command.
Reserved tapes must be requested by a
specific volume reference.
A remoyabl~ tape volume is assigned
the 2rivate characteristic when one of
the following occurs:
• It is requested with a specific
volume reference.
• It is requested for allocation to a
non temporary data set.
• The VOLUME parameter is coded with
the PRIVATE option.
A removable-private volume is
demoanted after its last use in the
job step, unless the programmer
. requests that it be retained.
the
All other tape volumes are assigned
£emovable~sc£~tch state.
The tape
volumes remain mounted until their
unit is required by another volume.
vol~~_PaI~~!Q!-fg£ili1i~§:
The
facilities of the VOLUME parameter
allow the programmer to:
• Bequest private volumes (PRIVATE)
• Request that private volumes remain
mounted until the end of the job
( RETAIN)
read or written. The yolume sequence
number is meaningful only if the data
set is cataloged and earlier volumes
are omi t ted.
volume-count
specifies the number of volumes
required by the data set. Unless the
SER or REP subparameter is used this
subparameter is required for every
multivolume output data set.
SER
specifies one or more serial numbers
for the volumes required by the data
sets.
A volume serial number consists
of one to six alphanumeric characters.
If it contains fewer than six
characters, the serial number is left
justified and padded with blanks. If
SER is not specified and DISP is not
specified as NEW, the data set is
assumed to be cataloged. and serial
numbers are retrieved from the
catalog. A volume serial number is
not required for new output data sets.
Two volumes should not have the same
serial number. When the SER parameter
is included, the volume is treated as
PRIVATE commencingllith allocation for
the current job step. If this
subparameter is specified, the UNIT
parameter must also be specified.
• Select volumes when the data set
resides on more than one volume
(volume-sequence-number)
• Request more than one nonspecific
volume (volume-count)
• Identify specific volumes (SER and
REF)
These facilities are all optional.
The programmer can omit the VOLUME
parameter when defining a new data
set, in which case the system assigns
a suitable public or scratch volume.
!QbQHE ~ub~~!g~§~
PRIVATE
indicates that the volume on which
space is being allocated to the data
set is to be made private. If the
PRIVATE, SER, and REF subparameters
are omitted for a new output data set,
the system assigns the data set to any
suitable public or scratch volume that
is available.
RETAIN
indicates that this volume is to
remain mounted after the job step is
completed. Volumes are retained so
that data may be transmitted to or
from the data set, or so that other
data sets may reside in the volume.
If the data set requires more than one
volume, only the last volume is
retained; the other volumes are
previously dismounted. Another job
step indicates when to dismount the
volume by omitting RETAIN. If each
job step issues a RETAIN for the
volume, the retained status lapses
when execution of the job is
completed.
volume-sequence-number
is a 1- to 4-digit number that
specifies the sequence number of the
first volume of the data set that is
REF
indicates that the data set is to
occupy the same volume(s) as the data
set identified by dsname *.ddname,
*.stepname.ddname, or *.stepname.
procstep.ddname.
Figure 12 shows the
data set references.
If SER or REP is not specified, the
control program will allocate any
nonprivate volume that is available.
1!lllt_£ll~!.~!tt!:_lQ~2.~!:ibin£LD.~iL~~t._1&llell
specifies information about the label
or labels associated with the data
set. If a data set is passed from a
previous job step, label information
is retained from the DD statement that
specified DISP=(,PASS).
A LABEL
parameter, if specified in the DD
statement receiving the passed data
set, is ignored. If the LABEL
parameter is omitted and the data set
is not being passed. standard labeling
is assumed. The operating system
verifies mounting when the label
parameter specifies standard labels
(SL) or standard and user labels
(SUL). Nonstandard labels can be
specified only when installation-
Job Control Procedures
65
rI
I
Option
I
IREP=dsname
Refers to
-,
I
I
SA data set named dsname
rIREF=*.ddname
f
I
,------+1------------------------------------------------------4
IA data set indicated by DD statement ddname in the
J
,current job step
I
I
-~
I REF=*.stepname. ddname
,A da ta set indicated by DD statement ddname in the job t
I
Jstep stepname
t
II
-f
fREP=*.stepnalle.p,rocstep.ddname, A data set indicated by DD statement ddname in the
•
t
I cataloqed procedure step procstep called in the job step.
ILII stepname (see "Using t he Cataloged Proced urestI)
f
____ J
f
r-
Figure 12.
Data set References
written routines to write and process
nonstandard labels have been
incorporated into the operating system
(see "User Label Processing" and the
publication Q~L~~~La~~ls for
information about writing these
routines).
1!~E~YRE~a!~'ter~:
data-set-sequence-number
is a 4-digit number that identifies
the relative location of the data set
with respect to the first data set in
a tape volume.
(Fo,r example, if t.bere
are three data sets in a magnetic tape
volume, the third data set is
identified by data set sequence number
0003.)
If the data set sequence
number is not specified, the operating
system assumes that it is 0001.
(This
option should not be confused with the
volume sequence number, which
represents a particular volume for a
data set.)
nonstandard label. SUL indicates IBft
standard and user labels.
EXPDT=yyddd
RETPD=xxxx
specifies how long the data set shall
exist. The expiration date,
EXPDT=yyddd, indicates the year tyy)
and the day (ddd) that the data set
can be deleted. The period of
retention, RETPD=xxXX, indicates the
period of time, in days, that the data
set is to be retained. If neither is
specified, the retention period is
assumed to be zero.
PASSWORD
indicates that the data set is to be
made accessible only when the correct
password is issued by the operator.
The operating system assigns security
protection to the data set. In order
to retrieve the data set, the operator
must issue the password on the
console.
NOPWREAD
indicates that the data set can be
read without the password, but the
correct password must be issued by the
opera tor be'fore the da ta set can be
changed, extended, or deleted.
IN
specifies the kind of label used for
the data set. AL indicates American
Nationa 1 standard labels. AUL
indicates American National Standard
user labels. BLP indicates tha t the
system is not to perform label
processing for the tape data set. LTK
indicates that the data set bas a
leadingtapellark. A, indicates that
the data set has standard labels and
another subparameter follows. NL
indicates no labels. SL indicates IBM
standard labels. NSL indicates
66
indicates that the data set is to be
processed for input on1 y.
OUT
indicates that the data set is to be
processed for output only.
nrsp Paramete£~~ifying_~gi~~~1-~l~!!§
s!lLDi§l!2§iti,on}
describes the status of a data set and
indicates what is to be done with it
after its last use, or at the end of
the job. The job,scheduler executes
the requested disposition functions at
the completion o.f the associated job
step. If the step is not executed
because of an error found by the
system before trying to initiate the
step (e.g., an error in a job control
language statement) , the remaining
statements are read and interpreted;
hovever, none of the succeeding steps
are executed, and the requested
dispositions are not performed. This
parameter can be omitted for data sets
created and deleted during a single
job step. Additional information
about the relationship between the
DISP parameter and the volume table of
contents is contained in "Additional
File Processing Information."
!H.~g~ubllara meters:
NEW
indicates that the data set is being
generated in this step. If the status
is omitted, the NEW subparameter is
assumed.
NEW is assumed. If the volume serial
number is given, it is assumed that
the data set is on the specified
volume.
DELETE
causes the space occupied by the data
set to be released for other purposes
at the end of the current step. If
the da ta set is ca taloged, an d the
catalog is used to locate it,
reference to the dataset is removed
from the catalog. If it is on a mass
storage device, all references are
removed from the volume table of
contents, and the device space is made
available for use by other data sets.
If the data set is on tape, the volume
in which the data set resides is then
a vail able for use by other da ta sets.
KEEP
ensures that the data set remains
intact until a DELETE parameter is
exercised in either th~ current job
orsome subsequent job. If the data
set is on a mass storage device, it
remains tabulated in the volume table
of contents after completion o.f the
job. When the volume containing the
data set is to be dismounted, the
operator is advised of the
disposi tion ..
OLD
indicates that the data set specified
in the DSNAME parameter already
exists.
SUR
has meaning only in a multiprogramming
environment for existing data sets
that reside on mass storage volumes.
This subparameter indicates that the
data set is part of a job in which
operations do not prevent simultaneous
use of the data set by another job.
FO.r a non-VSAM data set that is to be
shared, the DD statement DISP
para meter should be specified as
DISP=SHR for every re.ference to the
data set in a job. Unless this is
done, the data set cannot be used by a
concurrently operating job, and the
job viII have to vait until the
particular file is free.
PASS
indicates that the data set is to be
referred to in a later step of the
current j6b, at which time its
disposition may be determined. When a
subsequent reference to this data set
is encountered, its PASS status lapses
unless another PASS is issued. The
final disposition of the data set
should be specified in the last DD
statement referring to the data set
within the current job.
While a data set is in PASS status,
the volume(s) on which it resides are,
in effect, retained; that is, the
system will attempt to avoid
demounting them. If demounting is
necessary, the system will ensure
proper remounting, through operator
messages. The unit name specified on
the DD statement in the receiving step
must be consistent with the unit name
in the passing step ..
l!21g: For VSAM data sets, this
subparameter alone does not guarantee
that sharing will take place. For
mO.re information see the chapter "Data
Security and Integrity" in the
publication Q~~-yir1~al~~~~
!£~§2-~hod_J.VSAML.f!.:2g£gmmer.!.§
~uidg.
MOD
causes logical positioninq after the
last record in the data set. It
indicates that the data set already
exists and that it is to be added to,
rather than read. When MOD is
specified and neither the volume
serial number is given nor the data
set cataloged or passed from an
earlier job step, MOD is ignored and
CATLG
causes the creation, at the end of the
job step, of an index entry in the
system catalog pointing to the data
set. The data set ca n be referred to
by name in subsequent jobs, without
the need for volume serial number or
device type information from the
Job control Procedures
67
programmer.
Cataloging also implies
KEEP.
UNCATLG
causes the index entry that points to
this data set to be removed from the
index structure at the end of this
step. The data set is not deleted.
If it is on a mass storage volume,
reference to it remains in the volume
table of contents.
JiQig:
The absence of DELETE, KEEP#
PASS, CATLG, and UNCATLG indicates
that no special action is to be taken
to alter the permanent or temporary
status of this data set.
If the data
set was created in this job, it will
be deleted at the end of the current
step.
If the data set existed before
this job, it will be kept.
The third subparameter indicates the
disposition of the data set in the event
the job step terminates abnormally.
This
is the conditional disposition
subparameter. Explanations for DELETE,
KEEP, CATLG, and UNCATLG are the same as
those for normal termination. The
f~llowing points should be noted when using
the third sub parameter.
• If a conditional disposition is Dot
specified and the job step abnormally
terminates, the requested disposition
(the second subparameter) is performed.
• Data sets that were passed but not
received by subsequent steps because of
abnormal termination will assume the
conditional disposition specified the
last time they were passed.
If a
conditional disposition was not
specified at that tiae, all new data
sets are deleted and all other data
sets are kept.
related to a particular output unit.
Valid values for the SYSOUT parameter
are A through Z and 0 through 9.
A is
the standard output class.
H21~:
Classes 0 through 9 should not
be used except in cases where the
other classes are not sufficient.
These classes are intended for future
features of systems.
(classname[ , program-name][ ,form-no])
classname specifies the class
associated with the output device to
which the output data set is to be
written.
output writers route data
from the output classes to system
output devices.
The DD statement tor
this data set can also include a unit
specification describing the
intermediate mass storage device and
a.D estimate of the space required..
If
there is a special installation
program to handle output operations,
its program-name should be specified.
Program-name is the member name of the
program, which must reside in the
system library.
If the output data
set is to be printed or punched on a
specific type of output form, a
4-digit form number should be
specified. Porm-no. is used to
instr uct the opera tor of the form to
be used in a message issued at the
time the data set is to be printed.
• If both the program-name and form-no.
are omitted, the delimitinq parentheses
can be omitted.
• If the Direct SYSOUT Writer is used to
write a data set, both the form-no.
and program-name are ignored. All
parameters on the DD statement, i.e.,
UNIT or SPACE, are also ignored •
• A conditional disposition other than
DELETE for a temporary data set is
invalid and the system assumes that it
is DELETE.
~I~QU'l Paramtlg!:-1RQutinSLl!!!ta
ihg~~~reagl
set throu!!!!
schedules a printinq or punching
operation for the data set described
by the DD statement.
~I~QQI~ubearameters:
classname
speci fies the system output class on
which the data set is to be written.
A class name is an installation
specified 1-character name designating
the oat put class to which the data set
is to be written.
Each classname is
68
f£~~~~~mgte~~eg£ifYiRY-Qut~t
f£in!.g!:_~~_3525_£~~~_Pun£~)
fQ£-s-1l1!
is used to select the forms control
image to be used to print an output
data set on a 3211 printer, or a 3525
card punch with the read feature.
The
FCB parameter will be ignored if the
data set is not written to either one
of these devices.
The FCB parameter,
the DDNAME parameter and the DCB
subparameters RKP, CYLOFL, and INTVL,
are mutually exclusive.
l£!LSubparameters:
illage-id
identifies the image to be loaded into
the forms control buffer.
For further
information on the forms control
buffer. see the publication as/vs Dat~
fOL~ystem Proqrammer§.
!1~~~U!!!§U
ALIGN
VERIFY
requests the operator to check the
alignment of the printer forms before
the data set is printed or to verify
that the image displayed on the
printer is the desired one.
!tlf_pa~~L1SJ2.gcifyinq
'y~AM
Information fo£
Proce2§.i.n.g)
specifies information to be used for
processing by VSAM.
The AMP parameter
and its subparameters are described
under "VSAM-only JCL Parameter" in the
chapter "VSAM File Processing".
available to later job steps. Only one
JOBLIB statement may be specified for a job
but more than one library may be specified
on a JOBLIB statement. The JOBLIB
statement is meant to concatenate existing
private libraries with the system library.
It need not be specified for load mod Illes
created in the job or for permanent members
of the system library (see "Checklist for
Job Control statements" and "Libraries" for
examples) •
The STEPLIB DD statement may appear in
any position among the DD statements for
the job step. The library should be
defined as OLD.
If the library is to be
passed to other job steps, the second
subparameter of the DISP parameter should
be coded PASS.
A later job step may then
refer to the library by coding its STEPLIB
DO statement as follows:
//STEPLIB DD DSNAME=*.stepname.STEPLIB, X
II
DISP=(OLD,PASS)
By specifying certain ddnames, the
programmer can request the operating system
to perform additional functions.
The
operating system recognizes these
spec ia 1- purpose ddna mes:
The STEPLIB statement overrides the
JOBLIB statement if both are present in a
job step.
• JOBLIB and STEPLIB to identify private
user libraries
SYSABEND AND SYSUDUMP OD STATEMENTS
• SYSABEND and SYSUDUMP to identify data
sets on which a dump may be written
The ddnames SYSABENO or SYSUDUMP
identify a data set on which an abnormal
termination dump may be written.
The dump
is provided for job steps subject to
abnormal termination.
• SYSCHK to identify t he checkpoint da ta
set written during the original
execution of a processing program.
• JOBCAT and STEPCAT to identify VSAM
user catalogs.
The SYSABEND DO statement is used when
the programmer wishes to inclUde in his
dump the problem program storage area, the
system nucleus, and the trace table if the
trace table option had been requested at
system generation time.
JOBLIB AND STEPLIB DD STATEMENTS
The JOBLI Band STEPLI B DD statements are
used to concatenate a userts private
library with the system library
(SYS1.LINKLIB). Use of JOBLlB results in
the system library being combined with the
private library for the duration of a job;
use of STEPLIB, for the duration of a job
step.
During execution, the library
indicated in these statements is scanned
for a module before the system library is
searched.
The JOBtlB DD statement must appear
immediately after the JOB statement and its
operand field must contain at least the
DSNAME and OISP parameters. The DISP
parameter must contain PASS as the second
subparameter if the library is to be made
The SYSUOUMP DO statement is used when
the programmer wishes to include only the
problem program storage area.
The programmer may rout the dump
directly to an output writer by specifying
the SISOUT parameter on the DD statement.
In a mul ti programming environment, the
progra IDIDer may also define the intermedia te
direct-access device by specifying the UNIT
and SPACE parameters.
SYSCHK DO STATEMENT
The SYSCHK DO statement is required when
a job is being submitted for deferred
checkpoint/restart. It defines a
Job Control Procedures
69
checkpoint data set written during the
original execution of a processing program.
For detailed information about the
checkpoint/restart facilities. see the
publication ~L!~Ch~£~ointL~2taI1.
term PEND in the operation field.
The PEND
statement is not used for cataloged
procedures. For further information about
in-stream procedures, see .fTesting a
procedure as an In-Stream Procedure" in
"Osing the Cataloged Procedures."
The SYSCHK DD statement must immediately
precede the first EXEC statement of the
resubmitted job when restart is to begin at
a checkpoint. The RESTART parameter must
be included on the JOB statement; otherwise
the SYSCHK DD statement will be ignored.
Different SYSCHK DD statement parameter
spec if ication rules apply depending on
whether the checkpoint data set is
cataloged or not. These rules are
discussed in detail in the publication
Q~LY~J£1_Refer~n£g.
JOBCAT AND STEPCAT DD STATEMENTS
The JOBCAT DD statement specifies the
VSAM user catalog that is to be available
throuahout a VSAM processing job, while the
STEPCAT DD statement specifies the VSAM
user ca talog that is to be a vailable for a
single job step in a VSAM processing job.
For more detailed information on the
facilities provided by the JOBCAT and
STEPCAT DD statements, as well as the
specification rules, see the publication
~~L!~Vi~YA1-~iQ~~~ AC£g22_~ethog_J!~!~l
££Qg~~g£~_~~!de.
The PRGC statement may appear as the
first control statement in a cataloged
procedure and must appear as the first
control statement in an in-stream
procedure.
The PROe statement must contain
the term PRoe in its operation field.
For
a cataloged procedure, the PRce statement
assigns default values to symbolic
parameters defined in the procedure; its
operand field must contain symbolic
parameters and their default values.
The
PRGe statement marks the beginning of an
in-stream procedure; its operand may
contain symbolic parameters and their
defa ul t va lues.
The PEND statement must appear as the
last control statement in an in-stream
procedure and marks the end of the
in-stream procedure.
It must contain the
70
The opera tor issues commands to the
system via the console or a command
statement in the input stream. Commands
can also be issued to the system via a
command statement in the input stream.
However, this should be avoided since
commands are executed as they are read and
may not be synchronized with execution of
job steps.
Command statements must appear
immediately before a JOB statement r an EXEC
statement, a null statement, or another
command statement.
The command statement contains
identifying characters VI) in colUmns
and 2, a blank name field, a command, and,
in most cases, an operand field.
The
operand field specifies the job name, unit
name, or other information being
considered.
Note:
A command statement cannot be
continued, it must be coded on one card or
card image.
The delimiter statement marks the end of
a data set in the input stream. The
identifying characters 1* must be coded
into columns 1 and 2. the other fields are
left blank. Comments are coded as
necessary.
1iQ!.~:
The end of a data set need not be
marked in an input stream that is defined
by a DD * statement.
The null statement is used to mark the
end of a job in an input stream. It causes
the card reader file to be effectively
closed. The identifying characters II are
coded into columns 1 and 2, and all
remaining columns are left blank.
The comment statement is used to enter
any information considered helpful by the
programmer. It may be inserted anywhere in
the job control statement stream after the
JOB statement.
(The comment statement
contains a slash in columns 1 and 2, and an
asterisk in column 3. The remainder of the
card contains comments.)
Comments are
coded in columns 4 through 80, but a
com men t may not be con tinued 0 nto another
statement.
When the comment statement is printed on
an output listing, it is identified by the
appearance of asterisks in columns 1
through 3.
The batch compile feature is used to
compile multiple programs or subprograms
with one invocation of the compiler.
The
object programs produced from the batch
compilation may be link-edited into either
one load module or separate load modules.
This feature must be requested at
compile time by specification of BATCH in
the PARM field or, if a cataloged procedure
is used, in the PARM.COB field of the EXEC
card. In the BATCH mode, all options
specified on the EXEC card, as well as all
default options, apply to every program in
the batch unless specific options are
overridden, via the CBL card, for an
individual compilation.
The CBL card must be the first card in
each program within a batch mode. The CBL
card, in addition to separating logical
program units, may be used to change
existing options (as they were specified
or defaulted to on the EXEC card) for that
individual program, and has the following
format: .
r-I
JCBL [option 1X,option 2] ••• [,option'n]
,
L-
,
• A sequence number may appear in columns
1 through 6 of the CBL card.
• In most cases, an option specified on
the CBL card overrides the corresponding EXEC card option for compilation
of that one program only.
However,
this is not true in the case of options
that require use of a file that will
be used in a subsequent compilation
in the batch, or in a subsequent job
step. Generally speaking, it is unwise
to use the CBL card to specify any such
option, because use of that file in
compilation may cause an abend. Options
in this category are LOAD, LIB, DECK,
FDECK, and CDECK.
If some programs in a batch compilation
require the use of one of these options
and the other programs do not, specify
the option on the EXEC card, and then
specify the NO ••• form of the option
on those CBL cards where the option is
not wanted. For example, if programs
2, 3, and 5 in a batch compilation
require FDECK and programs 1 and 4
require NOFDECK, then FDECK should
be specified (or defaulted to) on the
EXEC card, and NOFDECK specified on
the CBL cards for programs 1 and 4.
(It would not be possible to specify
or default to NOFDECK on the EXEC
card and then override it with FDECK
on a CBL card.)
• If a CBL card is present and BATCH is
not specified on the EXEC card, the CBL
card is regarded as an invalid
statell ent.
• If the compiler NAME option is
specified on the CBL card, a linkage
editor NAME control card is generated
for this compilation, facilita ting the
link-editing of the program into a
separate load module.
• The output of a batch compilation may
be executed only if the member name
specified at compile time is the name
specified at execution time.
J
•
I
--J
The letters £]1 may appear in any three
consecutive columns 1 through 12, and the
option{s) specified may be any PARM
compiler option (s) gxc~H~!. SIZE, BUF, BATCH,.
L120, L132, SYMDMP. and LVL, which are
ignored if indicated.
• The batch option may be used in
conjunction with BASIS.
This facility
provides the COBOL programmer with th~
ability to combine a (multiple) BASIS
library member{s) and/or a (multiple)
COBOL source program(s) with one
invocation of the compiler.
• The BATCH option and the ~YMDMP option
are mutually exclusive.
Job Control Procedures
71
When the batch option is used in
combination with BASIS, the following rules
apply:
1.
All the BASIS library members to be
compiled must be members of the
partitioned data set(s) referred to by
the SYSLIB DD data set name(s).
2.
Each BASIS library member must contain
only one source program.
Figure 13 shows that with one invocation
of the COSUCL cataloged procedure (see the
chapter "Using the Cataloged Procedures"),
the programs COMPILE1, COMPILE2, and
COMPILE3 are compiled and two load modules
created as follows:
r-----------------Illjobname
IIICOMPILE
, IICOB. SYSIN
1.
COMPILE1 and COMPILE2 are link-edited
together to form one load module with
the member name of COMPILE2. a typical
calledlcalling situation.
(For
further discussion of articulation
between COBOL programs, see the
chapter "Called and calling
Programs".)
In this case~ the entry
point o.f the load module is still the
first program, COMPILE1.
2.
COMPILE3 is link-edited to create the
load module with the member name of
COMPILE3.
Figure 14 shows that with one invocation
of the COBUCL procedure the programs PROG1
and PROG2 and BASIS library members PAYROLL
and PAYROLL2 are compiled and four load
modules are created.
(An example of how to
execu.te load mod ules created wi th the BATCH
feature using the procedure COBUCL is qi ven
in Figure 1.3.)
,
JOB
EXECl
1, BATCH, MSGL EVEL= 1
COBUCL,PARM.COB:'BATCH,NAME'
DD
*
I CBL NONAME
ID DIVISION.
PROGRAM-ID. COMPILE1.
I
I
J
I
I
J
I
J
CBL NAME
ID DIV IS.ION.
PROGRAM-ID. COMPILE2.
I
,
J
I
I
CBL NAME
ID DIVISION.
PROGRAft-ID. COMPILE3.
1/*
IIILKED.SYSLMOD
DD
J
t
I
t
I
I
DSN=BATCHRON,SPACE=(TRK, (10,5,2)
1/*
•••••
J
J
IIICOMPILE2
EXEC
IIISTEPLIB2
DD
III (Cards needed to execute
PGM=COMPILE2
DSN=BATCHRUN2,DISP=SHR,....
CO~PILE1 and COftPILE2)
1/*
'1ICOftPILEJ
EXEC
PGM=COftPILE3
'IISTEPLIB
DD
DSN=BATCHRUN. DISP=SHR... ••
III (Cards needed to execute COMPILE3)
1/*
I
I
I
t
,
I
•
J
~
~
11In the compile step, no special JCt is needed for SISLIN because the cosueL cataloged I
I procedure is used (see the cba pter 1IUsing The cataloged Procedures").
I
12 In the link-edit step, a partitioned
data
I
.L-____________________________
.______________
___ set is created with the DSN of BATCHRUN.
Figure 13.
72
Example of a Batch Compilation
,
,Jlljobname
IIICOMP
~//COB.SYSLIB
I//COB.SYSIN
J CBL
I
JOB
1,BATBASIS,MSGLEVEL=1
EXEC
COBUCL,PARM.COB='BATCH,NAME,LIB'
DD
DSN=LIB1?OS, ••• l
DD
NAME, NOLI B
IDENTIFICATION DIVISION.
PROGRAM-ID. PROG1.
I
t
I
I
I
I
*
J
,
,,
J
•I
f
NAME
PAYROLL
NAME
PAYROLL2
NAME, NOLIB
IDENTIFICATION DIVISION
PROGRAM-ID. PROG2.
J CBL
JBASIS
1 CBL
fBASIS
, CBL
1
I
t
J
1/*
J I /LKED. SYSLl10DZ
DD
J
I
J
I
I
I
f
I
DSN=BATCHBAS,SPACE=(TRK,
(10,5,~
), •••
•I
1/*
I-
J1This partitioned data set contains as separate members PAYROLL and PAYROLL2.
!ZThe load mod~les of these four COBOL programs exist as separate members of a
I partitioned data set named BATCHBAS.
-f
,
J
J
~
Figure 14.
~
creation of Four Load Modules with Programs PROG1 and PROG2 and BASIS
Library Members PAYROLL and PAYROLL2
Default
Unblocked
~ta
COMPILER
A number of data sets may be defined for
a compilation job step; six of these
(SYSUT1, SYSUT2, SYSUT3, SYSUT4, SYSIN, and
SYSPRINT) are always required.
SYSUT5 is
required if the SYI1DMP or TEST option is
invoked.
SYSUT6 is required if FIPS
flagging is requested.
Additional data
sets (SYSLIN. SYSPUNCH, SYSTERI1, and SYSLIB
and/or other COpy libraries) are optional.
For compiler data sets other than
utility data sets, a logical record size
can be specified by using the LRECL and
BLKSIZE subparameters of the DCB parameter.
The values specified must be permissible
for the device on which the data set
resides.
LRBCL equals the logical record
size, and BLKS.IZE equals LRECL multipl.ied
by a, where n is equal to the blocking
factor.
If this information is not
specified in the DD statement, it is
assumed that the logical record sizes for
the unblocked data sets have the following
defa ul t values:
Val~_ll!Yl£.2l.
S~l
SYS.IN
SYSLIN
SYSPUNCH
SYSLIB or other
COpy libraries
SYSPRINT
SYSTERfIl
80
80
80
80
121 or 133
121
!Q~:
The default for SYSPRINT has a value
of 133 if 132 is selected with LSTCOMP or
LSTONLY.
The ddname that must be used in the DD
statement describing the data set appears
as the heading for each description that
follows.
Figure 15 lists the function,
device requirements, and allowable device
classes for each data set.
(See" Appendix
D:
Compiler Optimization" for further
information on blocked compiler data sets
other than utility data sets.)
The DD statements using these ddnames
define utility data sets that are used by
the compiler when processing the source
module. The data set defined by the SYSUT1
Dn statement must be on a mass storage
device.
Except for SYSUT5, which is needed
at execution time, these data sets are
Job Control Procedures
73
temporary and have no connection with any
other job step. For example, the DD
statement
include the results of the default or
specified options of the PARM paramete.r
(i.e •• diagnostic messages, the object code
listing) • For e.xample .. in the DD statement
//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK, (40,10»
/ /SYSPRI NT
specifies that the data set is to be
written on any available mass stor~ge
device, with a primary allocation of 40
tracks. Additional tracks, if required,
are to be allocated in groups of 10. The
data set is to be deleted at the end of the
job step (by default).
The NULLPILE or DUMMr parameter or
the RLSE subparameter of the SPACE
para meter should never be specified for any
of these data sets. In addition, the data
sets must be single volume, since the
compiler uses the TCLOSE facility
extensively and TeLOSE will not reposition
multivolume data sets.
DO
SYSOUT=A
SYSOUT is the disposition for printer data
sets. and A is the standard output class
.for printe.r da ta sets.
IQi~:
The data set defined by the SYSTERM DD
statement is used for certain compiler
output for a TSO terminal user when the
TERM option is specified. The compiler
output consists of diagnostic and progress
messages and compiler statistics. For
example:
//SYSTERt1 DD TERf'l=TS
The data set defined by the SYSIN DD
statement contains the input for the
compiler, i.e., the source module
statements that are to be processed. The
data set assigned to this DD statement is a
sequential data set, or a member of a
partitioned data set. It may be part of
the input stream. If so, it is commonly
referred to as a SYSIN data set. For
example,
IISYSIN
DD
*
specifies that the input data set follows
in the input stream.
TERM=TS indicates that the SYSTER~ data
set is to be directed to the TSO terminal.
The data set defined by the SYSPUNCH DD
statement is used to punch an object module
deck or. if FDECK or CDECK is specified, to
punch a source deck. This data set can be
directed to a card punch.. mass storage
device, or magnetic tape. For example. in
the DD statement
IISYSPUNCH
DD
SYSOUT=B
SYSOUT is the disposition for punch data
sets, and B is the standard output class
for punch data sets.
This data set is used by the compiler to
prod uce a listing. OutPllt may be directed
to a printer, a mass storage device, or a
magnetic-tape device. The listing will
74
Note: The SYSPUNCH DD statement is not
required if NODECK is in effect. SYSPUNCH
may be either a sequential da ta set or a
member of a PDS.
.
.--
J
I
ddnalle
'
Type
-
Function
1
1
J
Device
Requirements
-+-
Allowable
Device Classes
•
--of
1Card reader
1SYSSQ. SYSDA, or th~1
IIntermediate storagelinput stream device,
I
• (specified h y DO * ,
I
lor DD DATA)
I
.' I
-+,
---I
,SYSPRINT I
IWriting the storage 1Printer
ISYSSQ, SISDA, stand-I
J (required) I
,map, listings, and
IIntermediate storagelard output class A t
I
I
I and messages
I
I
I
f, .
I
-+,
fSYSTERM
J
,Writing diagnostic
loutput device
I
I
1 {optional) I
land progress messageslTSO t e r m i n a l ,
I
f,II
t
~
fSYSPUNCH ,
IPunching the object ,Card punch
ISYSCP, SYSSQ, SYSDA"
I (optional)J
Jmodule deck
IMass storage
Istandard output
I
I
I .
,Magnetic tape
Jclass B
I
f
~
I
I
I
I
JSYSLIN,
Icreating an object
,Mass storage
,SY55Q, SYSDA
t
I (optional),
Imodule data set as
,Magnetic tape
1
I
a
J
,output from the com- I
t
I
I
t
Ipiler and input to
I
J
J
I
I
Ithe linkage edi tor
J
1
1
f-I
I f f
--f
ISYSUT1
I Utility
IWork data set needed ,Mass storage
lSYSD1
J
I (required) I
I by the c o m p i l e r .
I
I
I
I
Idnring compilation
I
1
•
I-,''I
--+f
JSYSUT2
t
,Work data set needed ,Mass storage
lSYSSQ, SYSDA
f
, (required) 1
I by the compiler
J Magnetic tape
1
I
I
I
Jdurinq compilation
J
' I
t
f~
IJ
J
of
,SYSUT3
I
,Work data set needed lMass storage
ISYSSQ, SYSDA
J
I (required) •
I by the compiler
I Magnetic tape
1
1
I
•
Iduring compilation
I
I
I
II
lI
t
--t
fSYSUT4)
IWork data set needed ,Mass storage
JSYSSQ. SYSDA
J
I (required) t
f by the compiler
I Magne tic tape
J
t
,
1
Jduring compilation
,
I
,
•
, ' ' I
f
~
ISYSUT5
J
,Work data set needed (Mass storage
fSYSSQ, SYSDA
J
I
I
1when SYMDMP or TEST ll1aqne tic t a p e )
I
I
I
,option is in effect
t
t
J
I-I
I
-+I
--f
I SYSUT6
J Utility
I Work data set needed ,Mass storage
I SYSSQ, SYSDA
I
I
I
t \f hen LiL option is in, Magne tic ta pe
I
,
I
•
,effect
I
I
1
I-•
iJ
1
--f
,SYSLIB
I Library
Joptional user source IMass storage
ISY5DA
t
J and/or
I
tprogram libraries
,
I
I
lother COPYI
J
I
J
J
Ilibraries I .
I
,
J
I (optional) I .
I
I
t
I-I
-'--.Lof
IIQt.~:
Once created, a SYSUT5 data set can be moved only to a device of the same type. I
,That is, if the SYSUT5 data set is put on tape at compile time, that data set cannot bel
I moved .to a disk at execution time. The SYSHT5 da ta set must be unblocked.
I
ISYSIN
Jlnput/outputlReading the source
I (required)'
Iprogram
•
.,
I
I
I
J
~
Figure 15.
J
Data Sets Used for compilation
~YS~IN
an object module. It may be on a mass
storage or magnetic tape device. For
example:
The device defined by the SISLIN DD
statement is used by the compiler to store
Job Control Procedures
75
IISYSLIN DO
II
II
II
OSNAME=&&GOFILE,
DISP= (MOD,PASS) ,
UNIT= SISD A,
x
X
I
SPACE=(TR~,{30,10»)
The temporary name of the data set is
GOFILE, the parameter DISP=(MOD,PASS)
indicates that the data is to be created or
added to in this job step and is to be
passed to another job step, which may be
the linkage editor step. The device to be
assigned for storage is a mass storage
device on which 30 tracts are initially
allocated to the data set. If more space is
needed, tracks are allocated 10 at a time.
Note:
The SYSLIN DO statement is not
SYSLIN
may be either a data set or a member of a
POSe
~;~~ired if NOLOAD is in effect.
These DD statements define the libraries
(PDS's) that contain the data requested by
COpy state~nts (in the source module) or
by a BASIS card in the input stream. The
DD statement must be SYSLIB if a BASIS
library is to be included, or if the COpy
statement does not specify a library name
(by qualifying the text name).
Libraries
must always be on mass storage devices.
Note that more than one partitioned data
set may be used for the library function by
concatenating them with SYSLIB (see
"Libraries" for an example).
Although only
one SYSLIB statement may be used in a
compilation job step, multiple user-defined
COpy libraries may be used. For example,
in the DD statements
//SYSLIB
/IHOUSELIB
//PRIVLIB
The SYSLIB and other COpy library DD
statements are not required if NOLIB is in
effect.
DD DSNAME=USERLIB,DISP=OLO
DDOSNA ME='COPYX, DISP=OLD
DD DSNAME=COPY~,DISP=OLD
the names of the source libraries are
USERLIB* COPYX, and COPYZ. DISP=OLD
indicates that the libraries have been
created in a previous job and are
cataloged, or have been created in a
prev ious ste p in this job. No other
information need be given if the specified
libraries ha ve been ca taloged.
LINKAGE .EDITOR
pive data sets are required for linkage
editor processing. Others may be necessary
if secondary input is specified. In the
following discussions, the ddname that must
be used in the DD statement describing the
data set appears as the heading for each
description of the particular data set.
For any user-defined data set, the ddnaae
is defined by the programmer. Pigure 16
lists the function, device requirements*
and allowable device classes for each data
set.
The SYSLIN DD statement defines the data
set that is primary input to linkage editor
processing. Norma 11 y this data set
consists of the output from a previous
compilation job step. The primary input
may also be linkage editor control
statements, such as the INCLUDE, LIBRA.RY,
or OVERLAY statements (see "Calling and
Called Programs"). The input device
assigned to this data set is either the
device transmitting the input stream. if
the input is an object module deck, or a
device designated by the programmer.
However, the data set may simply be passed
from the previous compilation job step.
For example, in the DD statement
//5YSLI5
II
When concatenating SYSLIB, the library
with the largest blocksize must be
specified in the first DD statement.
76
DSNAME=*.STEPNAME.SYSLIN,
DISP=(OLD,DELETE)
X
the data set is defined in the SISLIN DD
statement contained in the compiler job
step, STEPNAME. DISP=(OLD.DELETE)
indicates that the data set was created in
a previous job step and is to be deleted at
the end of this job step.
SYSPRINT
The data set defined by the SYSPRINT DD
statement is used ,by the linkage editor to
produce a listing. For example:
I/SYSPRINT
Notes: Maximum b10cksize for any COpy
library is 16K (there is no such
restriction for BASIS).
DD
OD
SYSOUT=!
Output may be directed to a printer or to
an intermediate data set. The listing aa,
include any options specified by the PAIU!
parameter of the EXEC statement (a module
map or cross reference list, diagnostic or
informative messages, etc.).
,.--
-r------,
, I '
I
I
I
ddname
.-,SYSLIN
I
(required)
,
I-ISYSPRINT
I
(required)
,
I
I
ISYSLMOO
I
(required)
....- ISYSUT1
I
{required)
r--
Device,
Allowable
I
J Type J
Function
1 Requirements 1
Device Classes
,
I
I
-+I
~
IInputl I primary input data,
IMass storage ,SYSSQ, SYSDA, or the inputl
loutput I
normally the output IMagnetic tape J stream device (specifiedt
1
I of tbe compiler
,Card reader.
by DO * or DD DATA)
I
•
I
I
,
of
,
IDiagnostic messages
IPrinter
lSISSQ, standard output
I
I I Informative messages ,Intermediate I class A I
t
I Kodule map
J storage
J
I
J
t Cross-reference list I
J
I
' I
,
-+-i
I
loutput data set for
IMass storage ISYSDA
I
J
I
the load m o d u l e ,
I
J
1
t i t .,
lutilitylwork data set
IMass storage
ISISDA
t
I
I
1
I
I
+----t
I
I
of
I LibrarYI Automatic call librarY1Mass storage ISISDA
I
I
I
(SYS1.COBLIB is the,
f
I
1
I name of the COBOL
I
I
I
J
J
subrou tine library) ' I
I
ISYSLIB
I
(required)
I for COBOL
,Library
I subroutines 1
I1
I SYSTERM
I
I
(required,
J if TERM op- I
,
tion is
I
I specified)
I
II
IUser-specified,
J (optional) I
,
1
L-
I
J
I
I Numbered erro,r/warning) Printer
I
I messages
ITSO terminal
I
I
J
I
J
I
I
I
I
I Additional object
I modules and load
1 modules
--t
J
J
I
I
I
t
'
I-+..
IMass storage ISYSDA, SYSSQ
I
I Magnetic tape I
•
'
Figure 16.
I
I
J
I
---+
I '
I
•
.J
--L--
Data Sets Used for Linkage Editing
The SISTER! DD statement is optional: it
describes a data set that is used only for
numbered error/warning messages.
Although
intended to define the terminal data set
when the linkage editor is being used under
TSO, the SYSTERM DD statement can be used
in any environment to define a data set
consisting of numbered error/warning
messages that supplements the SISPRINT data
set.
SYSTER" output is defined by including a
SISTER" DD sta'tement and speci.fying TER" in
the PARM field of the EXEC statement. When
SYSTERM output is defined, numbered
messages are then vri tten to both the
SYSTERft and SISPRINT data sets.
The SYSTER! DD statement is specified as
follolls:
The SYSLMOD DD statement defines the
output data set, in this case the lo~d
module. The load module must be placed in
a library as a named member. The library
can be the Link Library (SYS1.LINKLIB) or a
private user-defined library. such
libraries must always reside on a mass
storage device, and space for the library
is allocated when the library is created.
For example, in the DO statement
IISISJ.MOD DD DSNAME=SYS 1. LINKLIB(MEMBER) , X
DISP=OLD
II
the load module, ME~BER, is stored as a
member of the link library. DISP=OLD
indicates that the library is already
created and additions are to be made to it.
IISISLliOD
IISYSTERM DO SYSOUT:!
1/
II
II
II
DD
DSNAME=LIBl (BALANCE),
DISP=(NEW,CATLG) ,
VOLUME=SER=111111,
SPACE={TRK, (40,10,1»,
UNIT=SYSDA
Job Control Procedures
x
X
X
X
11
The load module, BALANCE, is to be a member
of a library, LIB1, which is to be created
in this job step, with BALANCE as its
firstmember.
The mass storage volume to
which it is directed is identified by the
serial number, 111111.
A primary quantity
of 40 tracks is allocated to the library
with an additional allocation for one
256-byte record to be used for the
directory. If more space is needed for the
library, tracks are added, 10 at a time.
(However, no additional space can be
allocated for the directory.)
Additional data sets may be defined for
linkage editor processing. ~hese data sets
may be used as additional input sources of
object modules or load modules. They may
also be concatenated with the primary input
data set or the automatic call library (see
"Libraries").
IQt~:
LOADER
If the load module is placed in a
pri vate libr ary, the JOBLI B or STEPLID DD
statements must be specified in subsequent
jobs that execute load modules from the
library.
The SYSUT1 DD statement defines a
utility data set used by the linkage editor
when processing object modules and load
modules.
The data set must be on a mass
storage device. It is a temporary data set
and has no connection with any other job
step.
For example:
One data set (SISLIN) is required for
loader processing. Three are optional
(SYSLIB, SYSLOUT and SYSTERl'I).
(These
ddnames can be changed during system
generation with the LOADER macro
instruction.)
In addition, any DD
statements and data required by the loaded
program mus·t be included in the input deck.
In the following discussions, the
default ddnaae for the DO statement
describing the da ta set appears as the
heading for each description of the
particula.r data set.
IISYSUTl DD UNIT=SISDA,SPACE=(TRK,{40,10»
The data set is initially allocated 40
tracks on any available mass storage
device.
If more space is neededj tracks
are added, 10 at a time.
A temporary name
is assigned to the data set for the job
step.
The SYSLIN DD statement defines the data
set that is primary input to the loader.
This input can be either object modules
produced by the COBOL compiler or load
modules produced by the linkage editor, or
both. The loader allows both object module
and load module conca tenation on SISLIN.
The data sets defined by the SISLIN DD
statements can be either sequential data
sets or members of a partitioned data set,
or both.
The SYSLIB DD statement assigns the
named partitioned data set to the automatic
call library from which modules may be
automatically obtained by the linkage
editor to resolVe external references.
//SYSLIB
DD
DSNAME;SYS1.COBLIB,DISP=SHR
This statement assigns the COBOL subroutine
library to the automatic call library.
When there is a possibility that the
compiler ~dy have generated calls to any
COBOL library subroutines, the SISLIB
statement must be specified (see "Appendix
B:
COBOL Library subroutines" for a list
of library subroutines, their functions,
and entry points).
78
The SYSLIB DD statement defines the data
set containing IBM or user-vri tten library
routines to be included in the loaded
program. The SYSLIB data set is searched
when unresolved references remain after
processing SYSLIN and, optionally,
searching the link pack area of OS/VS2 or
the resident reenterable modules feature of
OS/VS1. The library may contain either
object modules or load mod Illes but not
both. The data set defined by the SISLIB
DD statement must be a partitioned data
set.
where:
n
The SYSLOUT DO statement defines the
data set used for error and warning
messages and for an optional map of
external references.
The data set must be
a sequential data set. The record format
of S YSLOU'!' is always ass umed to be F BSA.
is the blocking factor
SYSPUNCH must be on a device where blocking
is permitted. For example:
IISYSPUNCH
II
II
II
EXECUTION TIME DATA SETS
Any number of data sets may be used for
execution time processinq. These data
sets, or files, are identified in the
source program, and each must be described
by a DD statement.
The ddname is used to
link the DD statement to the COBOL ASSIGN
clause in the source program that specifies
the ddname.
DD statement requirements for
the DISPLAY, ACCEPT, EXHIBIT, and TRACE
statements are discussed in the following
text. DD statements that specify COBOL
debugging aids and an abnormal termination
dump are also discussed.
Use of either the
Sort or the RERUN feature requires
additional DD statements. For information
about these statements, see "Using the sort
Feature" and .fUsing the CheckpointlRestart
Feature."
DO
x
UNIT=SYSSQ,
DCB= (RECFM=FB,
BLKSIZE=160),
LABEL= (, NL)
X
X
When the UPON option is omitted, SYSOUT is
the default option.
identifier}
DISPLAY
{ literal
IISYSOUT DD applicable parameters
It is assumed that SYSOUT is an
unblocked data set that has a line width of
121 characters (1-byte for the control
character) •
Por example:
The DISPLAY statement requires an
associated DD statement unless the data is
to be displayed on the console. The DD
statements needed for each form of the
DISPLAY statement are as follows:
!n.!!l?!.~L.1 :
DISPLAY {
identifier}
I/SYSOUT DD SYSOUT=A
However. the prog.rammer can specify an
alternate line width, recording mode,
andlor a blocked data set by using the DCB
parameter. To specify an alternate line
width, the subparameters of the DCB
parameter are used as follows:
LRECL=line width+1,BLKSIZE=LRECL value
••• UPON SYSPUNCH
literal
To specify a blocked da ta set, the
subparameters are used as follows:
IISYSPUNCH DD applicable parameters
RECF!=FBA,LRECL=line width+1,
BLKSIZE=n* (LRECL value),
It is assumed that SI~UN£!! is an
unblocked data set that has a logical
record length of 80 characters. For
example:
where:
IISYSPUNCH DD SYSOUT=B
However, the programmer can specify a
blocked data set by using the subparameters
of the DCB parameter as follows:
n
is a blocking factor
SYSOUT must be on a device where blocking
is permitted. The extra character in LRECL
allows for the carriage control character.
For example, to specify an alternate line
width, the following SYSOUT statement can
he used.
IIS1S0UT
RECFM=FB,BLKSIZE=n*80
II
DD SYSOUT=A,DCB=(LRECL=133, X
BLKS'IZE= 133)
Job Control Procedures
79
For example:
To specify a blocked data set, the
following SYSOUT statement can be used.
DD
IISYSOUT
II
II
II
II
II
IISYSIN
DD *
(data)
DSNAM E=PRINTOUT,
U NIT= Sf SD A, ••• ,
DC B= (REeF M=.FB A,
x
X
X
1*
LRECL=121,
X
X
However, the programmer can specify a
blocked data set bI using the subparameters
of the DCB parameter as follows:
BLKSI ZE=605) ,
VOLUME=SER=111111
Note:
If the problem uses the Sort/Merge
feature, remember that SYSOUT is the
default error message data set, and a
conflict can arise.
See "Additional DD
Statements" in the chapter "Using the
Sort/Merge Feature" for suggested
solutions.
RECFM=FB,BLKSIZE=n*80
where:
~
is the blocking factor
~!.llli~_l :
SYSIN must be on a device where blocking is
permitted.
For example:
The DISPL}Y statement can use a
mnemonic-name rather than a system-name.
l/SYSIN
DISPLAY
identifier}
{ Ii teral
••• UP3N mnemonic-name
. SYSPUNCH}
.
{ SYSOUT
II
II
UNIT=2400, ••• ,
DCB= (RECFM=PB,
BLKSIZE=160) #
LABEL= (, Nt)
x
X
X
.
where mnemonic-name is associated with the
word SYSPUNCH or SYSOUT in the Environment
Di vision.
II
DD
II
If a logical record length of other than 80
cha.racters is desired, it must be specified
in the LRECL field of the DCB parameter.
DD applicable parameters
The EXHIBIT or TR.ACE statement requires
a SYSOUT DD statement as discussed fat:
O.ISPLA Y.
The ACCEPT statement requires an
associated DD statement unless the data is
being accepted from the console, format 2
of the ACCEPT statement is used, or ACCEPT
MESSAGE is used (making possible use of the
options DATE, DAY, and TIME). The OD
statements for each form of the ACCEPT
statement are as follows:
ACCEPT identifier
When the FROM option is omitted, SYSIN is
the default option.
DD
IISYSIN
~xam1?le
applicable parameters
liQte:
If the job step already includes a
SYSOUT DD statement for some other use,
another may not be inserted since all
SYSOUT output from any source in the job
step will be merged onto the one SYSOUT
data set defined for that job step.
.1£ one or more of the options FLOW,
STATE, and SYMDMP is in effect, the
following DD statement must be used:
IISYSDBOUT
DD
applicable parameters
If the output is routed through the output
stream and written on a syst~m output
device, the following may be used:
2:
IISYSOBOUT
DD
SYSOUT=A
ACCEPT identifier PROM mnemonic-name
where mnemonic-name is associated with the
word SYSIN in the Environment Division.
The recording mode is FBA. The user
can, however, specify a blocked data set
and alternate recording mode by using the
DCB subparameters.
IISYSIN DD applicable parameters
It is assumed that SYSIN is an unblocked
da ta set tha t has a logical record length
of 80 characters.
80
!Qte: It
unblocked
121 bytes
character)
is assumed that SYSDBOUT is an
data set that has a line width of
(one byte for a control
•
See the chapter "Symbolic Debugging
Features" in this manual.
The following DO statement must be used
to make the COBOL library module ILBODBEO
available at execution time:
IISTEPtIB DO DSN=SIS1.COBLIB.OISP=SHR
with the SYMDMP option which could include
the aonormally terminating program and its
callers, up to and including the main
program. The IISYSABEND or IISYSUDUMP DD
card need not be included.
For a
discussioa of the symbolic dumping option,
as well as of other COBOL symbolic
debugging options, see the chapter entitled
"Symbolic Debugging Features."
If an error message is printed by the
debugging modules, the COBOL library module
ILBODBEO is loaded dynamically from
SYS1.COBLIB. This module is not link
edited into the COBOL object program.
If the COUNT option is in effect, the
following DD statement must be used:
To obtain an operating system
hexadecimal dump in case the job is
abnormally terminated by the system, or by
executing the COBOL statemen t CALL
tILBOABNO' USING iAentifier, one of the
following DO statements must be used:
/ /SYSD BOUT DD applicable parameters
IISYSABEND DO applicable parameters.
Pot example, if the output is routed
through the output stream and written on a
system output device, the following may be
used:
IISYSUDUMP OD applicable parameters.
IISYSDBOUT DD SYSOUT=A
The dump provided when the SYSABEND DD
statement is used inclUdes the system
nucleus, the program storage area, and a
. trace table, if the trace table option vas
requested at system generation. The
SYSUDUMP DO statement provides a dump of
the program storage area. The applicable
para meters a re those for a ph ysical
sequential data set. If the dump is routed
through the output stream and written on a
system output device, the following DD
statement may be used:
IISYSUDUMP DD SYSOUT=A
If a COBOL program abnormally
terminates. then a formatted dump is
provided for all COBOL programs compiled
!Qi~:
In addition to the SYSDBOUT DO
statement, the SYSCOUNT OD statement must
also be used:
/ISYSCOUNT
DD
SYSOUT=A
The user may concatenate a library of
selected COBOL Object-time subroutines with
the link library.
(For information on how
this can be accomplished, see the section
"Sharing COBOL Library Subroutines" in the
chapter entitled "Libraries lt ) .
Job Control Procedures
81
This section describes the processing of
non-VSAM files.
A description of VSAM file
processing is in the section "VSAM File
Processing."
!!~::nEFINED
FILES
Files that are processed in a COBOL
program must be described as data sets to
the operating system. Whenever a file is
specified in a program by the following
statement:
SELECT [ OPTIONAL] file-name
ASSIGN TO assignmen t-name
this file must be described in an FD
file-name entry and in a DD statement in
the execution-time job step. The ddname in
the DD statement is a portion of the
assignment-name (sometimes also known as
"system-name tt ) specified in the ASSIGN TO
clause. In the assignment-name
UT-2400-S-TAXRATE
TAXRATE is the ddname portion of the
assignment-name.
li21g:
The device-number specified in the
assign ment-n ame is ignored by the compiler.
Actual device allocation is a function of
the DD statement.
requires changing input/output statements
and recompiling the program. Changing a DD
statement when a program is executed is a
simple procedure.
As an example, consider a COBOL program
that might be used in exactly the same way
for several different master files.
It
might contain the clause
SELECT MASTER ASSIGN TO
DA-3330-D-MASTERA ••••
In that case, the following DD statements,
Y§~t di~!lI_ti~. would assign the
different named data sets to the program:
//ftASTERA
//ftASTERA
//I1ASTERA
DD
DD
DD
DSNAME=MASTER1, •••
DSNAME=MASTER2, •••
DSNAME=MASTER3 ••••
If the first DD statement appears in the
job step that calls for execution of the
program, any reference within the program
to MASTER is a reference to the data set
named MASTER1; if the second DO statement
appears, the reference is to MASTER2; if
the third, the reference is to MASTER3.
However, if a file-name within a program
is always to be applicable to only a single
data set, the names might be written as
follows:
SELECT TAXRATE ASSIGN TO
UT-2400-S-TAXRATE •••
The applicable DD statement might be:
FILE NAMES AND DATA SET NAMES
//TAXRATE
The terms nfile" (COBOL usage) and "data
set" (operating system usage) have
essentially the same meaning. There may,
however, be a difference between the
file-name and the da ta set name. The data
set name always represents a specific data
set. The file-name can. at different
times, represent different data sets. The
DD sta tement allows a programmer to select.
at the time his program is executed, the
specific data set that is to be associated
with a particular file-name.
This facility
can be especially powerful when applied to
input data sets.
The file-name is a name known within the
COBOL progra m. Chanqing a file-name
82
DD
DSNAME=TAXRATE, •••
Of the names, the ddname portion of the
assignment-name that appears in the ASSIGN
clause and the ddname of the DD statement
must always be the same. The file-name and
the data set name may be the same, or they
may be different.
(Of course. the
file-name in the SELECT sentence must be
the same as the FD name.)
If t40 or more files on direct-access
devices have the same ddname and are open
at the same time (i.e., the output from the
files is being merged into one data set),
the files must have no conflicting
attributes. The foregoing also applies to
SYSOUT data sets if they are written on an
intermediate direct-access device.
The use of the DISPLAY~ EXHIBIT, or
READY TRACE verbs causes the library to
open the target ddname (SYSOUT~ SYSPUNCH,
etc.)
If the programmer has also assigned
one of his output files to the same ddna.e,
he must ensure that he has opened, written,
and closed his file before the first
execution of any of the previously
mentioned verbs.
The full range of facilities available
in BPAH are not available to the COBOL
programmer.
A partitioned data set may be
referred to in COBOL only by treating its
.members as physical sequential data sets.
Additional considerations when using the
sort feature are described under
"Additional DD statements" in the chapter
"Using the sort Feature."
DATA SET ORGANIZATION
SPECIFYING INFORMATION ABOUT A FILE
Some of the information about the file
must always be specified in the PO entry,
SELECT sentence, APPLY, and other COBOL
clauses.
at he.r informat ion must be
specified in the DD statement.
For
example, the amount of space allocated for
a mass storage output file must be
specified in the DD statement by the SPACE~
SPLIT, or SUBALLOC parameters.
certain
characteristics of files cannot be
expressed in the COBOL language, and may be
specified on the OD statemen t for the file
by the DCB parameter. This parameter
allows the programmer to specify
information for completing the data control
block associated with the file (see
"Additional File processing Information"
for a discussion of the data control block,
and "Appendix C: Fields of the Data
Control Block").
Each file used in the program must be
referred to by a particular file processing
technique.
Fou r p.rocessinq techniques are
discussed in this publication.
They are
physical sequential (QSAt1), direct (BSAM,
BDAM), relative (BSAM, BDAM), and indexed
(OISAM, BISAH).
A non-YSAM data set used by a COBOL
program can have one of four types of
organization:
physical sequential, direct,
relative, and indexed.
The first type
(sequential) may be on any input/output
device that is supported.
All other types
must be on mass storage devices (see Figure
11 for information in determining the file
processing technique to be used, according
to data set organization).
1.
A £.hz2icU-2~gj!!H!tia! data set is one
in Which records are organized solely
on the basis of their successive
physical positions.
2.
A ~i£g£! data set is one in which
records are referred to by use of
relative trac,! addressing.
An ACTUAL
KEY specifies the track relative to
the first track allocated to the data
set and identifies the record on the
track.
3.
A £elatiY~ data set is one in which
records are referred- to by use of
relative ~£~ addressing.
A NOMINAL
KEY identifies the record location
relative to the first record in the
data set.
4.
An iridexed data set is one in wbich
records are arranged on the tracks of
a mass storage device so as to permit
access in logical sequence (according
to a key that is part of every
record).
A separate index or set of
indexes maintained by the system
indicates the location of each record.
This permits random, as well as
sequential, access to any record.
A fifth processing technique, called
partitioned data organization (BPAM), is·
discussed throughout the publication, when
it is used for program storage.
A eartiti~1 data set (PDS) is composed
of named, independent groups of sequential
data" each of which is called a memb~.
Each member has a simple name stored in a
directory that is part of the data set and
that contains the location of each member's
starting point. Partitioned data sets are
used to store programs, and are often
referred to as li~~ries.
User Non-VSAK File Processing
83
I .
•
.-
i
I
I
I
File Processing
J
Requirements
I
,Write, r~ad, and
f update standard
I sequential file
Permissible
J
I
I
,ACCESS Clause and
Record Formats,
JFile
I
t
)Organization Field..-i
I
Device
IProcessingJorganization J
I(N) in system-namelBlockedlUnblocked,Requirements ,Techniqne ,Clause
f
I
I .
I
+-I
-i
IACCESS SEQUENTIAL IF,V,S JF,V,U
) Mass storage IQSAM
,Sequential
I
I or ACCESS clausel
,
J Magnetic Tape,
, (defaul t)
I
J is omitted
t
I
IUnit Record
J
I
I
I N=S
I
J
I
1
I
•
I
I
I
I
I
-f---------i
I ACCESS SEQUENTIAL I
IF
I Mass Storage laSAM
I Should not be
I or omitted
J
I
I
I
,specified
'N=Rt
I
J
I
I
t
J
II Wri te and read a
I mass storage file
f with relative
J record addressing
I
I--+J Read and update
I ACCESS RANDOM
I a mass storage
I N=R
I file with relative I
I
record addressing
J
I-I
ICreate and read a
IACCESS SEQUENTIAL
I
mass storage file I or omit ted
,with relative
,N=D
I
track addressing
I
I-t! Create, read, update, JACCESS RANDOM
J and insert into a I N=D or W(REWRITE)
I mass storage file -,
,
with relative
I
,I track addressing
•
J
t
I
I
I
I
JF
1
J
J
I
I
)
I
I
IF,V,U,S
I
t
I '
•
I
I
I
I IF, V, U, S
I
t
I
I
I
I
J
I
I-J
I
J
,Create a mass
,ACCESS SEQUENTIAL JF
IF
,
I
I storage file with , or omitted
I indexed sequential I N=I
I
I
organization
I
I
I
I
I-iI
I
,Read and update
IACCESS SEQUENTIAL IF
IF
I a mass storage
t or omit ted
I
J
I filevitb indexed I N=I
I
I
I organization
I
I
I
II
f
I
tRead, update, and
JACCESS RANDOM
IF
IF
, insert into
I N=I
I
I
I a mass storage
I
I
J
,
f ilewith indexed
I
I
I
I random
I
1
I
Il - orqani'Zation
I
"
--...L-L-"
Figure 17.
84
Determining the File Processing Technique
I
I
1
I
I
..
I Mass Storage ,BDAli
I
I t '
I
I
I
I
t
I
I
I
-~
,Mass storage ,BSAM
J
J
t
I
I
I
I
I
I
I
I
+-----i
I Hass Storage I BDAM
I
I
,
f
,
I
,
I
I
•
I
,
•
I
I
-t
Illass Storage JQISAM
I
I
,
I
f
I
I
J
f
I
I
I
~
I~ass storage IQISAM
I
J
I
I
I
I
J
J
I
,
I
I
..
,Mass Storage IBISAM
I
J
f
I
I
I
,
I
,
I
I
I
t
I
I•
J
.1.-_ _ _ _ _ _ _- - - '
is the first character of the data.
If the WRITE BEFOBE/AFTER ADVANCING
statement or the WRITE AFTER
POSITIONING statement is not used,
the first byte of the record is
treated as data by the punch or
printer.
ACCESSING A PHYSICAL SEQUENTkAL PILE
A physical sequential file may only be
accessed sequentially, i.e., records are
read or written in the order in which they
appear on the file.
The file processing
technique used to create and retrieve a
pbysical sequential file is QSAM (Queued
sequential Access Method).
Figure 18 shows
the COBOL clauses that may be used with
these files.
Special considerations for
these clauses are as follows:
1.
2.'
The RESERVE clause can be used to
specify more buffer areas, allowing
overlap of input/output operations
with the processing of data. If this
clause is not used, additional buf.fers
may be specified by using the BUFNO
option in the DD statement. If no
additional buffer areas are specified,
two buffers are reserved by the
system.
When the SA~E AREA clause is
specified for the file, the number of
buffers used is determined from the
RESERVE clause or if the RESERVE
clause is not present, it is given a
default of two. The BUFNO option in
the DD statement is ignored if the
SAME AREA clause is specified.
If a WRITE AFTER POSITIONING statement
is used, the record size specified
in the FD entry must allow for the
carriage control or stacker select
character, even though the character
is not to be printed or punched.
For example, if the record size
specified in the FD entry is 121,
the actual record is 121 characters;
however, only 120 characters are
printed or punched.
If the NOADV compiler is specified
and a WRITE BEFORE/AFTER ADVANCING
statement is used, the situation is
the same as above; the record size
specified in the FD entry must allow
for the control character, even though
the character is not to be printed.
The compiler may direct extra
records, containing the appropriate
control Characters, to the file to
effect printer spacing as. specified
in the WRITE BEFORE/AFTER ADVANCING
sta tement. These extra records are
for spacing purposes only and will
not appear externally if the file is
assigned to an online printer.
However, if the file is assigned to
a device that does not recognize the
control characters (for example. a
tape or a direct-access device), the
extra records are written onto the
file.
These extra records are
produced only if ADVANCING more than
three lines is specified or if both
the BEFORE and AFTER options are
specified for a file.
l.
If the input device is the card
reader, RECORDING MODE IS F should be
specified. If RECORDING ~ODE IS V or
S is specified, the first 8 bytes of
the record viII be interpreted as the
control bytes required for files with
format V or 5 records.
4.
If physical seguen tia 1 files are on
magnetic tape, the record block size
should be at least 18 bytes.
Records
less than 18 bytes in length will be
read vith no problems, unless a parity
check occurs.
If a parity check
occurs while reading a record less
than 18 bytes, it will be treated as a
noise record and skipped over.
5.
The S (standard) option can be
specified in the DCB BECFM
subparameter for a fixed/blocked
record data set with only standard
blocks (i.e •• having no truncated
blocks or unfilled tracks within the
data set, except for the last block of
the last track).
If a fixed/blocked
data set is created through the use of
an American National standard COBOL
program, a truncated physical block
may be written only by the executions
of the CLOSE or CLOSE UNIT (or REEL)
statement. Use of the standard block
option (particularly .for direct-access
devices having the Rotational
positional Sensing feature) results in
significant I/O performance
improvements.
6.
The T (TRACK OVERFLOW) option can be
specified for the DCB RECF~
When the ADV compiler option is
specified and a WRITE BEFORE/AFTER
ADVANCING statement is used, the
record size specified in the FD
entry should be the same as the
record to be printed.
(The compiler
adds one to the length specified in
the FD when it sets the logical
record length in the DCB.)
Not~:
• If the immediate destination of the
record is a device that does not
recognize a carriage control or
stacker select character, the system
assumes that the control character
User Non-YSAK File Processing
85
Data Management
Techniques
Device
Type
Access
Method
KEY
Clauses
QSAM
TAPE
SEQUENTIAL
NOT
ALLOWED
OPEN
Statement
INPUT
Access
Verbs
J
[REVERSED
NO REWIND
CLOSE
Statement
READ [INTO]
AT END
[REEL]
[WCK
]
NO REWIND
POSITIONING
DISP
[LEAVE
]
REREAD
DISP
1-------- -----------WRITE [FROM]
OUTPUT
[O~MN]
LEAVE
REREAD
DISP
[{ BEFORE}
AFTER
ADVANCING]
[AFTER POSITIONING]
1-------EXTEND
QSAM
MASS
STORAGE
SEQUENTIAL
NOT
ALLOWED
INPUT
READ [INTO]
AT END
1------- 1-----------OUTPUT
1--------
1-0
WRITE [FROM)
INVALID KEY
WRITE [FROM)
[{ BEFORE}
ADVANCING]
AFTER
[AFTER POSITIONING)
EXTEND
1---- -
[UNIT)
[LOCK)
---
1----------- 1------READ [INTO)
AT END
WRITE [FROM)
[LOCK)
INV ALID, KEY
REWRITE [FROM)
Figure 18.
COBOL Clause £or Physical seGJuential File processing
subparameter of the DD statement for
QSAM files with RECORDING MODE V, 5,
or F. Specification of the T option
is equivalent to including the APPLY
RECORD-OVERFLOW option in the source
program, but use of the T option in
the DD statement allows the user to
make his selection at object time.
Figures 20 and 21 show the parameters in
the DD statement that may be used with
physical sequential .files. All parameters
except the DCB are descr ibed in "Job
Control Procedures." Additional DCB
subparameters not shown in the illustration
are required for use with the Sort/Merqe
feature (see the chapter "Using the
Sort/Merge Feature"for information on
these parameters).
The DCB subparameters that ca.D be
specified in the DD statement for physical
sequential files are as follows:
86
DCB=[ DEN= CO, 1,213.14} ]
[ ,TRTCH= (CI EfT, ET} ]
[,PRTSP= {O J 1 j213} ]
( ,MODE::: {C J E}
]
[ , STACK: { 1 '2} ]
[,OPTCD={WICJWCITIQ1Z} ]
r ,BLKSIZE=integer ]
[ , B UFNO:integer )
[,EROPT:::(ACCfSKPIABE} ]
[,RECFM=C F IVlulDIB/SITJ[AIMJ1J
(,DIAGNS=TRACE)
( , F tJNe= {I I R J PI Wf 0 J X JT} ]
DE N= {O 11 J 2,3}
can be used with magnetic tape, and
specifies a value for the tape
recording density in bits per inch as
listed in Figure 19. If no value is
specified, 800 bits-per-inch is
assumed for 7-track tape, 800
bits-per-inch for 9-track tape without
dual density and 1600 bits-per-inch
for 9-track tape with dual density,
depending on the inst.al1ation's
generic definitions for unit names.
,
,
i
1
I
1
I
I•
JDEN Valuel
I
0
I
I
1
I
2
I
1
3
I
I
4
I
1
Tape Recording Density
(Bits per inch)
1 Track
•
200
556
800
•
I
I
f
I
,
9 Trac.k
I
I
800
I•
I
1600
6250
t-
---J
Fiqure 19.
DEN
Values
TRTCH={C1EITIET}
is used with 1-track tape to specify
the tape recordinq technique, as
follows:
C -
Specifies that the data-conversion
feature is to be used; if data
conversion is not available, only
format F and format U records are
supported by the control program.
E - specifies that even parity is to
be used; if omitted, odd parity is
assumed.
T -
Specifies that BCD to EBCDIC
conversion is required.
ET- specifies that even parity is to
be used and BCD to EBCDIC
con version is required.
PETS P= {O 11 12 t 3}
specifies the line spacing on a
printer as 0, 1, 2, or 3. If PRTSP is
not specified, 1 is assumed.
The PRTSP subparameter is valid only
if the unit specified for the file is
a printer. It is not valid if the
file is a report file, nor is it valid
if the WRITE statement with the
BEFOREI AFTRR ADVANCING option or WRITE
AFTER POSITIONI NG is specified in the
COBOL source program.
Single spacing
always is assumed for a printer unless
other information is supplied.
MODE= {CI E}
can be used ~ith a card reader, a card
punch or a card-read punch
and specifies the mode of operation
as follows:
C - Specifies card image (column
binary) mode.
E - Specifies EBCDIC code.
If this info.rmation is not supplied
by any source, E is assumed.
ST ACK= {112}
can be used with a card reader, a card
punch, or a card-read punch, and it
specifies which stacker bin is to
receive the card.
Either 1 or 2 is
specified. If this information is not
supplied by any source, 1 is assumed.
STACK should not be used when the
WRITE sta tement :with the AFTER
ADVANCING or POSITIONING option is
used to specify pocket selection.
OPTeD= {WICI TI QI Z}
requests an optional service provided
by the system as follows:
W - To perform a write validity check
(on mass storage devices only).
C - To process using the chained
scheduling method (see the
publication OSLV~_Data Kanag~~l
~ervic~Guid~) •.
T - To request user totaling facility.
Q - To translate to or from ASCII on
tape
Z - TO request the search direct
option (see the publication
QU!~
~A!~_H~n~~m~~~£vic~Guide).
HQ!~
If the validity check is
specified, the system verifies that
each record transferred from main
storage to mass storage is written
correctly. Standard recovery
procedures are initiated if an error
is detected.
BLKSIZ E=integer
is used to specify the block size.
This clause is used only when BLOCK
CONTAINS 0 RECORDS vas specified at
compile time.
BUFNO=number of buffers
is used to specify the number of
buffers to be assigned to the file
when neither the RESERVE nor the SAME
AREA clause is specified for the file
in the source program.
The maximum
number is 255.
EROPT={ACClsKPtABE}
specifies the options to be executed
if an error occurs in writing or
readinq a record as follows:
ACC - To accept the error block for
processing.
User Non-VSAM File Processing
87
SKP -
To skip the error block.
ABE -
To terminate the job.
There are two cases when the
subparameter can be specified:
• If no error processing declarative
(USE sentence) is specified, the
option is taken immediately.
• If an error processing declarative
is specified, the option is taken
after the error declarative returns
control via a normal exit (and only
if that is the case).
If no option is specified, ABE is
assumed.
RECFM={F/vluID[BISIT] [AIM]}
specifles the form-a-t-of-Ehe
records on the data set
(see the JCL manual for the
ways in which these individual
subparameters can be combined).
Only the Sand T subparameters
have meaning for COBOL; COBOL
ignores all others.
F - records are of fixed length.
S - to expect the data set to consist
of standard blocks.
T - to use the TRACK OVERFLOW option
(this specification has the same
effect as including the APPLY
RECORD-OVERFLOW option in the
source program) •
A - records contain ANS device control
characters.
M - records contain machine code
control characters.
DIAGNS=TRACE
specifies the open/Close/EOV trace
option which gives a module-by-module
trace of Open/Close/EOV·swork area
and the DCB.
The Generalized Trace
Facility with the proper options
specified must be active in the system
while the job that requested the trace
is running; the options are MODE=EXT
and TRACE=USR.
FUNC={IJRIPIWIOIXIT}
specifies the type of data set to he
opened for the 3525
Card-Read-Punch-Print as folloWS:
I R -
P V - records are of variable length.
W
D-
U - records are of undefined length.
X -
interpret-punch data set.
read
punch
print
data protection for a punch data
set
printer
two-line printer.
D - ASCII records of variable length.
T -
B - records are blocked.
por the valid combinations of these
values see the publication OSL!~_~l!
Refer~.
r-----------------------------------------------------------------,
Device
I
r---------------------+---------------------T---------___________
~---------------------J
I
Parameter
I Mass Stcrage
I
Tape
I Unit Record
I
I
~ype
~agnetic
~---------------------+---------------------~---------------------~---------------------~
I DSNAME
I
as
I
~---------------------+-----------------------------------------------------------------i
I UNIT
I
as
I
~---------------------+-------------------------------------------T---------------------~
I VOLUME
I
as
I
na
I
~---------------------+---------------------T---------------------+---------------------~
I LABEL
] SI.
I SL
BIP
] NI
I
I
I SUI.
I NL
I. 'IM
I
I
I
I
I NSI.
Al
I
I
J
]
I SUL
AVI.
I
I
~---------------------+---------------------+---------------------i---------------------i
I SPACE
I
as
I
na
I
~---------------------+---------------------+-------------------------------------------~
I SUEALLOe
)
as
I
na
I
~---------------------+---------------------+--------------------------------------~----i
I SPLI'I
I
as
I
na
I
~---------------------+-------~-------------~---------------------T---------------------~
I DISP
I
NEw
{,KEEP
I SySOU~=A,B...
I
I
]
MOC
g PASS
]
I
I
I
l
J
I
,CA~LG
I
,DELETE
I
I
~---------------------t---------------------T---------------------+---------------------~
I DeB Device Dependent] OP~CD=W, WC
I ~R~eH, DEN
I PRTSP, ~CDE, STACK I
~---------------------+---------------------~---------------------t---------------------i
I DCB General
1 OF~ec=e/~, BUFNO, BLKSIZE w EROP~=ABE
I EFOF'I=Ace
I
I
] RECFM=as
I
Unblocked Record
J
t
I
1
I
I
I
I
f
r---------------------------------,
•I
J
Logical Record
J
L--._ _ _ _ __
<
·-----------Fixed Length----------->
J
1.
Figure 60.
t
I
J
-.I
Fixed-length (Format F) Records
Format U is provided to permit the
processing of any blocks that do not
conform to F, V, or S formats.
Format U
records are shown in Figure 61.
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 (FD) entry in the Data
Division. U-mode records may be specified
only for direct or physical sequential
fi lese
If the RECORDING MODE clause is omitted,
and BLOCK CONTAINS [integer-1 TO]
in teger-2. ••
does not specify integer-2
less than the maximum level-01 record, the
compiler determines the recording mode to
be U if the file is direct and one of the
following conditions exist:
• The FD entry contains two or more
level-01 descriptions of different
lengths.
• 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.
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 MoiE
statement.
All other rules of the MOVE
sta tement apply.
!Q!.~:
Illustrations of Format U records do
not take into account either the key field
required when direct organization is used
or ASCII block prefixes.
See "processing
ASCII Files" for more information.
t
I
I
~
I
1
I
I
I
Figure 61.
A record description contains an OCCURS
clause with the
D~PENDING
ON option.
V-mode records# unlike U-mode or F-mode
records, are preceded by fields containing
control information. These control fields
are illustrated in Figures 62 and 63.
The first four bytes of each block
contain control information (eC):
LL -- represents two bytes designating
the length of the block (including
the fCC' field).
BB -- represents two bytes reserved for
system lise.
The first four bytes of each logical
record contain control information (cc):
bb -- represents two bytes reserved for
~
system use.
For unblocked V-mode records (Figure
62). the Data portion + CC + cc constitute
the block.
Format U Record
Logical Record
L-____________________
•
•
11 -- represents two bytes designating
the logical record length
(including the 'cc' field).
Logical Record
r--~
I -_
C _ 1 _ _ _ _Data
L
___________________
• The FD entry contains two or more
level-01 descriptions of different
lengths.
• The RECORD CONTAINS clause specifies a
range of record lengths.
• A record description contains an OCCURS
clause with the DEPENDING ON option.
r-
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 be specified
only for direct or physical sequential
files.
If the RECORDING ~ODE clause is
omitted and BLOCK CONTAINS (integer-1 TO]
integer-2...
does not specify integer-2
less than the maximum level-01 record# the
compiler determines the recording mode to
be format V if the file is physical
sequential and one of the following
conditions exist:
--'
Unspecified (Format U) Records
For blocked V-mode records (Figure 63),
the Data portion of each record + the cc of
each record + CC constitute the block.
Non/VSAM Record Formats
161
r-----------------------------------------,]
I
/
PD
VARIABLE-FILE-l
RECORDING MODE IS V
BLOCK CONTAINS 35 TO 80 CHARACTERS
RECORD CONTAINS 27 TO 72 CHARACTERS
DATA RECORD IS VARIABLE-RECORD-1
LABEL RECORDS ARE STANDARD.
01
VARIABLE-RECORD-l.
LOGICAL RECORD
05 F.IRLD-A
PIC
PIC
05 "FIELD-B
05 FIELD-C OCCURS
DEPENDING ON
FIELD-B
PIC
]
I
4
4
variable
J
] <--bytes-><--bytes--><------tytes------->/
I r----T----T----T----T-------------------, I
LL I EE i I ____
11 I ____
bb I ___________________
Data
// IL----i-___
JI)J
~
~
Figure 62.
J
IL-------_________________________________
~
I~
/
u CC'·
• cc Q
]
I
I
Unblocked V-Mode Records
Variable-length record descriptions, for
input and output files, must not define
space for the control by tes.
Control bytes
are automatically provided when a record is
written and are not communicated to the
user when a file is read. Although they do
not appear in the descriptions of logical
records, control bytes do appear in the
buffer areas of main storage. The compiler
automatically allocates input and output
buffers that are large enough to contain
the required control bytes.
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 RECORDING MODE
clause is omitted, the compiler determines
the mode as V since the record associated
with VARIABLE-FILE-1 varies in length
depending on the contents of FIELD-B. The
RECORD CONTAINS clause is never required.
The compiler determines record sizes from
the record description entries. The BLOCK
CONTAINS clause is also not required, since
the compiler assumes unblocked records if
the clause is omitted.
Note:
Record
length calculations are affected by the
following:
When variable-length records are written
on unit record devices, control bytes are
neither printed nor punched.
They do
appear, however, on other external storage
devices.
V-mode records moved from an
input buffer to a working storage area will
be moved without the control bytes.
• When the BLOCK CONTAINS clause with the
RECORDS option is used, the compiler
adds four bytes to the logical record
length and four more bytes to the block
length.
!21g:
When a READ INTO statement is used
for a V-mode file# the size of the current
record for that file is used in the MOVE
statement.
All other rules of the MOVE
statement apply.
For considerations when
using OCCURS DEPENDING ON, see the section
"Programming Techniques."
• When the BLOCK CONTAINS clause with the
CHARACTERS option is used, the user
must include each cc • CC in the length
calculation.
In the definition of
VARIABLE-FILE-1, the BLOCK CONTAINS
clause specifies eight 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.
Consider the following physical
sequential file consisting of unblocked
V-mode records:
r---------------------------------------------------------------------------------------,
1st
2nd
3rd
I
I
I
I
I
Logical Record
--
Logical Record
Logical Reccrd
-
----.._--./'.....
~
--- --~
r----T----T----T----T-----------T----T----T----------T----T----T----------,
IL ____
LL I ____
EE I ____
11 J ____
tb J ___________
DA~A-l
I ____
11 I ____
bb] __________
DATA-2
/ ____
11 J ____
bb iI __________
DA~A-3
JI
~
~
~
~
/
~
~
~
~
~
I
~
~
I
{block
control
~{record
control~
I
IL______________________________________________________________________________________
bytes)
bytes)
_
Figure 63.
162
Blocked V-Mode Records
In Example 1, assume 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 main storage as shown in Figure 64.
As mentioned previously, the RECORDING
MODE, RECORD CONTAINS, and DATA RECORDS
clauses are unnecessary.
By specifying
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 reserved by the compiler for
each output buffer. If this size is other
than tha t .required, the BLO.CK CONT IINS
clause with the CHARACTERS option should be
specified.
If the block size is to be
specified at execution time by use of the
BLKSIZE subparameter on an associated DD
card, BLOCK CONTAINS 0 CHARACTERS must be
specified.
If the file described in Example 1 had a
blocking factor of 2, the first two reco.rds
would appear on an external storage medium
as shown in Figure 65.
~xample
1:
If VARIIBLE-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:
PD VARIABLE-FILE-2
RECORDING MODE IS V
BLOCK CONTAINS 3 RECORDS
RECORD CONTAINS 20 TO 100 CHARACTERS
DATA RECORDS ARE VARIABLE-RECORD-1,
VARI ABLE-RECOR 0-2
LABEL RECORDS ARE STANDARD.
01
VARIABLE-RECORD-l.
05 FIELD-A PIC X(20).
05 FIELD-B PIC 1(80).
01
VARIABLE-RECORD-2.
05 FIELD-I PIC X(20).
Note: Blocked var iable-Iength records are
permitted only when the file processing
technique is physical sequential.
In Example 2, assume that the first six
records written are five 100-charact.er
records followed by one 20-character
record. The first two blocks of
VARIABLE-FILE-2 vill appear on the external
storage device as shown in Figure 66.
r-------------------------------------------------------------------------------------------------1I
I
1st Block
2nd Block
_____
_
~
I _
I r----T--T----T--T-------T--T-------T-------T----T--T----T T -- -- T--T--T---- --T1
45 I BB
bIFIELD-AI
03 IFIELD-CIFIELD-CIFIELD-C
II LI0040IBBI0036IbbIFIELD-AI02IFIELD-CIFIELD-CI00
____ __ ____ __ _______ __ _______ _______ ____
__ IOO41I
____ b
__
_______ __
_______ _______ _______ JI
I
I
II
I
I Note: Lengths appear in decimal notation for illustrative purposes.
IL __________________________________________________________
I
I
I
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~--------------------------------------J
Figure 64.
Fields in Unblocked V-Mode Records
r---------------------------------------------------------------------------------------,
1st Recerd
2nd Record
I
I
:I 10081IBBI0036IbbIFIELD-AI02IFIELD-CIFIELD-CI0041IbbIFIEID-AI03)FIEID-CIFIELD-CIFIELD-CI
r-~--T--T----T--T---::::T--T-------T----~-T-=---T--T-~-----T--T::::---T---~---T--~-~-, II
I l ____
I
~
I Note:
__
~
___
~_,_~
Lengths
_______
a~pear
~
__
~
_______
~
_______
~
____
~
__
~
_______
in decirral notation fer illustrative
~
__
~
_______
~
_______
~
_______
rur~oses.
JI
I
I
Il _______________________________________________________________________________________ JI
Figure 65..
Fields in Blocked V-Mode Records
Non/VS AM BecordFormat-s
163
r-----------------------------------------------~-------------------------------------------------,
I
I
I
II
1st Block
_
2nd Block
~
r---T--T---T--T----T---T--T----T---T--T---
~
-~-T--T---T--T----T---T--T----T--T--T----'
bb i Da ta
13161BBI1041bbiDatal1041bbiDatal1041
L___ __ ___
____ ___ __ ____ ___ __ i___
2361BBII041bbiDatal1041bbiDatal241bbiDatai
__ ____ ___ __ ____
__ i ____ J
~
~
~_~~
~
~
~
~
~
__~
~
~
~
~
i_~i
I
I
I
II
I
I
I
Note: Lengths appear in decimal notation for illustrative purposes.
I
IL _________________________________________________________________________________________________ JI
Figure 66.
First Two Blocks of VARIABLE-FILE-2
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-PILE-2 is a 20-character record,
it will appear as the first record in the
third block.
This condition can be
eliminated by using the APPLY WRITE-ONLY
clause when creating files of
variable-length blocked records.
Note: Illustrations of unblocked Format V
records do not take into account either the
key field required vhen direct organization
is used or ASCII block prefixes.
See the
description of format D records under
"Processing ASCII Files".
4
•
i
i
•
~
't
-,---,---~---,
1236Jbbl24lbblData)104lbb,DataJl04,bblDatal
Using the APPLY WRITE-ONLY clause causes
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 is created containing six logical
records, as shown below:
l!Q!'~:
The APPLY WRITE-ONLY clause is used to
make optimum use of buffer space when
creating a physical sequential file with
blocked V- mode records.
When using the APPLY WRITE-ONLY
clause, records must not be constructed in
buffer areas.
An intermediat.e work area
must be used with a WRITE FROM statement.
Suppose VARIABLE-FILE-2 is being created
with the following file description entry:
FD
01
01
VARIABLE-FILE-2
RECORDING ~ODE IS V
BLOCK CONTAINS 316 CHARACTERS
DATA RECORDS ARE VARIABLE-RECORD-1,
VARIABLE-RECORD-2
LABEL RECORDS ARE STANDARD.
VA RI ABLE-BECOH 0-1.
05 FIELD-A PIC X(20).
05 FIELD-B PIC X(80).
VARIABI.E-RECORD-2.
05 FIELD-X PIC X(20).
The first three WHITE statements to the
file create one 20-character record
followed by two 10Q-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:
164
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 (BOAM, BSAM) files and
for physical sequential (QSAM) files
assigned to magnetic tape or to mass
storage devices.
When creating files with S-mode records,
if a record is larger than t.he remaining
space in a block, a segment of the record
is wri t. ten to fill the block.
The
remainder of the record is stored in the
next block or blocks, as required.
When retrieving a file with S-mode
records, only complete records are made
available to the user.
Spanned records are preceded by fields
containing control information. Figure £7
illustrates the control fields.
BDF (Block Descriptor pield):
described in the Data Division with the
following file description entry:
LL -- represents tvo bytes designating
the length of the physical block
(including the block descriptor
field itself).
FD
SFItE
RECORD CONTAINS 250 CHAHACTERS
BLOCK CONTAINS 100 CHARACTERS
BB -- represents two bytes reserved for
system use.
SDP (Segment Descriptor pield):
11 -- represents two bytes designating
the length of the record segment
(including the segment descriptor
field itself).
bb -- represents two bytes reserved for
system use.
NQte: 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.
Figure 68 also illustrates the concept
of record segments.
Note that the third
block contains the last 50 bytes of REC-1
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-1 and th€ fiest segment
of REC-2.
The first block contains the
first segment of REC-l and the second block
contains an intermediate segment of REC-l.
S-MODE CAPABILITIES
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 user.
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. Records of a spanned
file may only be blocked when organization
is sequential (QSAM).
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 pos.sible.
The system segments the logical record when
the entire logical record cannot fit on the
track.
Figure 68 is an illustration of block.ed
spanned records of SFILE. SFILE is
Formatting a file in the S-mode allows
the user to make the most efficient use of
external stoeage while organizing data
files with logical recoed 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.
2.
The user is not required to adjust
logical eecord lengths to maximum
physical record lengths and their
device-dependent variants when
designing his data files.
3.
The user has greater flexibility in
transferring logical records across
DASD types.
Spanned record processing viII not be
supported on unit record devices.
SEQUENTIAL S-MODE FILES (QSAM) FOR TAPE OR
MASS STORAGE DEVICES
When the spanned format is used for QSAM
files, the logical records may be either
fixed or variable in length and are
comple tely independen t 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.
Non/VSAM Record Formats
165
r---------------------------------------------------------------------------------------,I
I
I
<--4 bytes---> <--4 bytes--> <----------------Variable bytes------------------>
I
I
I
I
I LL I EE I 11 I bb I
Data Record or Segment
I
I
I
~-----~------~~-----~-----~/------------------------- _______________________ J
I
I
I
I
BDF
SCF
I
L
I _______________________________________________________________________________________ JI
r------T------T------T------T-------------------------------------------------,
Figure 67.
Control Fields of an S-Mode Record
,
,.I
I (--------100 bytes------->
(--------100 bytes------->
J r---------.--------------~
REC-1
_
REC-1
G L----__________________
"1
1
J
I t
J
,
1st Block
J
1 G
<-50 bytes-> <-50 bytes->
~-------------
REC-l
I
REC-2
.L
----'
3rd Block
2nd Block
J
I
I
I
I
I
f
L-_ _ _ __
oJ
Figure 68.
One Logical Record Spanning Physical Blocks
The user 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
• Integer-2 is less than the maximum
length of a variable level-01 FD entry
(i.e., an entry containing one or more
OCCURS clauses with the DEPENDING ON
option).
Except for the APPLY WRITE-ONLY, APPLY
RECORD-OVERFLOW. WRITE BEFORE ADVANCING.
WRITE AFTER ADVANCING, or WRITE AFTER
POSITIONING clauses. all the options for a
variable file apply to a spanned file.
• RECORD CONTAINS [integer-l TO]
integer-2 CHARACTERS
• RECORDING MODE IS S
The size of t h~ 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.
Suppose a file has the following file
description entry:
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 l!ODE IS S clause. If this clause
is omitted, the compiler viII set the
recording mode to S if the BLOCK CONTAINS
inteter-2 CHARACTERS clause vas specified
and either of the following conditions
exist:
166
SPAN-FILE
BLOCK CONTAINS 100 CHARACTERS
LABEL RECORDS ARE STANDARD
DATA RECORD IS DATAREC.
01
DATAREC.
05 FIELD-A PIC X (100).
05 FIELD-B PIC X (50).
Figure 69 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 main
storage.
1.
• Integer-2 is less than the largest
fixed-length level-01 PD entry.
FD
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.
2.
One advangage of S-mode reco.rds over
V-mode records is illustrated by a file
with the following characteristics:
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.
BECORD CONTAINS 50 TO 150 CHARACTERS
2.
BLOCK CONTAINS 350 CHARACTERS
3.
The first five records written are
150, 150, 150, 100, and 150 characters
in length.
No provision is made for the control
fields within the level-Ol entry
DATAREC.
3.
1.
For V-mode records, buffers are
truncated if the next logical record is too
large to be completely contained in the
block (Figure 70).
This results in more
physical blocks and more inter-record gaps
on the external storage device.
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 HODE clause must specify S
(if so desired) since the compiler cannot
determine this by comparing block size and
record size.
HQ1~:
For V-mode records,
truncation occurs:
1.
buffer
When the maximum level-01 record is
too large.
r---------------------------------------------------------------------------------------------------------,
I
4
4
92
<-bytes-><-bytes-><-----------bytes------------->
4
4
58
4
30
I
<-bytes-><-bytes-><---bytes---><-L)ytes-><--nytes---> I
ILL
ILL
L
___
r---T---T---T----T------------------------------,
III
I
bn I ______________________________
DATAREC (1)
L___ IBB
___ ___ I ____
J
~
~
~
~
r---T---T---T----T-------------T---T----T-----------,
I
IBB III I bb I DATAREC ( l ) III I bb IDATld{EC (2) II
~
___
~
___
~
____ _____________
~
1st Block
~
___ ____ L ___________ J
~
I
I
I
I
I
I
I
2nd Block
4
4
92
<-bytes-><-bytes-><-----------bytes------------->
4
4
28
4
bO
<-bytes-><-bytes-><--bytes---><-bytes-><---oytes---->I
ILL
bb I______________________________
DATAREC (2)
L___ IBB
___ III
___ I ____
JI
ILLL
BB III
bb I DA'l'AREC
(2) III
bb I_____________
DAT ALI:.C (3) I II
___ I ___
___ I____
___________
___ I ____
r---T---T---T----T------------------------------,
~
~
~
~
r---T---T---T----T-----------T---T----T-------------, I.
~
~
~
~
~
~
j
~
I
I
_________________________________________________________________________________________________________ JI
4th Block
3rd Block
Figure 69.
First Four Blocks of SPAN-FILE
r------------------------------------------T--------------------------------------------,
RECORDING MODE IS V
]
RECCRDING MODE IS S
I
I
~------------------------------------------+--------------------------------------------~
I
I
I r-----T-----'
II Il _____
150 I _____
150 JI
~
I
I
'--v--'
"--'v--"
Rl
I
I
R2
r-----T-----'
r-----'
G Jl _____
150 I _____
100 JI G IL_____
150 JI
~
"-v--"
R3
'--v--'
R4
"--'v--"
I
1
I r-----T-----T-----'
150 J _____
150 i I _____
50 JJ
]I IL_____
~
1
R5]
'--v--'
Rl
r-----T-----T-----'
G IL_____
100 i I _____
100 i I _____
150 JI
'-v--'" - - - - - - - - - - - - - - - ' - v - "
R2
R3
R4
~
R5
]
I
I
I
II
I
I
I
I
J
~------------------------------------------~--------------------------------------------~
The enclosed diagrarrs are for illustrative purposes only.
Neither takes into
I
laccount
the space required for control fieldsu
L_______________________________________________________________________________________
JI
I Note:
Figure 70.
Ad vantage of S-Mode Records Over V-Mode Records
Non/VSAM Record Formats
167
2.
If APPLY WRITE-ONLY or SAME RECORD
AREA is specified and the actual
logical record is too large to fit
into the remainder of the buffer.
For S-mode records, all blocks are 350
bytes in length 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 70).
A second advangage of S-mode proce~sing
over that of V-mode is that the user 1S no
longer limited to a record length that does
not exceed the track of the mass storage
device selected. Records may ipan tracks*
cylinders, extents, and volumes.
QSAM spanned records differ from other
QSAM record formats because of an
allocation of an area of main 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 dre
contained within a single physical block)
the Logical Record Area is not used.
Regardless, only complete logical records
are made available to the user.
Both READ
and WRITE statements should be thought of
as manipulating comple te log ical records
not record segments.
The allocation of a Logical Record Area
may be a disadvantage to the COBOL user.
Additional main storage, consisting of 36
bytes + the maximum record length, will
always be required. The Logical Record
Area is discussed in detail in "Finding
Data Records in an Abnormal Termination
Dump."
DIRECTLY ORGANIZED S-MODE FILES (BDAM AND
BSAM)
When S-mode is used for directly
organized files. only unblocked records are
permit ted. 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. A track
may contain a segment of a logical record,
or seg ment s of tvo logical records and/or
whole logical records.
Records may span
tracks, cylinders, and extents. but not
volumes.
The user 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
.,
rJ
I
I
I
j
sequential Pile 3
r-----r--------~~--------------,
JL ____
P,1 - 4
I
I
I
I
r-
j
I
J
L
I
I
I
I
1
I
Direct File
R2
R3
- L_____________
I
.J
J
R3
J
J
I
R4
,------,
r---R2
, G 1 R3
I
G Lt _ _ _
_ _ _ -..J
L -_ _ _ _ -J
...--
,
R3
)
'---
.J
r-----------~--------------_,
L - - -_______-L--_____________- - JJ
I R1
'-------I
••• 2nd track •••
R3
,
r
••• 1st track •••
••• 3rd track •••
,..------------.,
r------,
I
R3
f G Jt.-._ _R4
I
_ _ _- J
.J
••• 4th track •••
,------,
J
R4
I
1..-_ _ _.-4
L-
168
I
I
I
I
J
I
I
I
I
J
_ _ _ _ _ _ _ _ .JI
•
Figure 71.
I
I
I
I
I
I
t
Direct and sequential Spanned Files on a Mass Storage Device
will determine the maximum record size from
the record descriptions under the PD.
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
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.
~£Q£g~sillg Di£~~1Y-Q£g~n!~~1_~=tt~Qg_fi!g2
111D AlL.an.L.fl§.AMl...
When processing directly organized
files, there are two advantages spanned
format has over the other record formats:
1.
The physical block size is determined by
either:
1.
The logical record length.
2.
The track capacity of the device being
used.
IQ!~:
Even when the spanned format is
used, the COBOL restriction on the
length of logical records must be
adhered to (i.e., a maximum length of
32,767 characters).
2.
If, for example, the track capacity of a
mass storage device is 7294 characters, any
record smaller than 7294 characters may be
written as a sinqle physical block.
If a
logical record is greater than 7294
characters, the record is segmented.
The
first segment may be contained in a
physical block of up to 7294 bytes, and the
remaining segments must be contained in
succeeding blocks.
In other vords, a
logical record will span physical blocks
if, and only if, it spans tracks.
Figure 71 illustrates four
variable-length records (Rl, 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 7294 CHARACTERS (track
capacity = 7294)
2.
RECORD CONTAINS 500 TO 8000 CHARACTERS
In the sequential file, each physical
block is 7294 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
one logical record or one record segment.
Logical record R3 spans physical blocks
oaly because it spans tracks. The file
consists of seven physical blocks, occupies
more than three tracks, and contains three
inter-record gaps.
Logical record lengths may exceed the
lenqt h restriction of the track
cap~city of the mass storage device.
If, for example, the track capacity of
a mass storage device is 2000 bytes,
this does not represent the maximum
l~ngth of the logical record that can
be specified (even when the device
does not have a Track Overflow
feature) •
s-mode records give the user the same
facility as the Track Overflow
feature.
If neither RECORDING MODE IS
S nor APPLY RECORD-OVERFLOW is
specified, only complete logical
records can be written on any single
track. This means that when a track
has only 900 unoccupied bytes and a
record of 1000 bytes is to be added,
it viII be written on the next
available track.
This is inefficient,
since a 900 byte segment could be
added to the current track by means of
either APPLY RECORD-OVERFLOW or
RECORDING MODE IS S.
IQi~:
If a choice exists between
Track Overflow and S-mode records,
neither has any particular advantage
over the other with regard to the
efficient use of storage space.
The disadvantage of BSAM and EDAM
spanned records is similar to that
mentioned for QSAM.
A segment work area is
always allocated which occupies additional
main storage.
Like QSAM, the processing of B5AM and
BDAM spanned records relies on an
interaction between buffers, segment work
areas, and Logical Record Areas.
For QSAM,
input-output buffers are used as the
segment work area and complete logical
records are assembled in a Logical Record
Area before being made available to the
user if the record is segmented. If the
record is not segmented, the logical
recordis made a vailable to the user wi thin
the buffer unless the SAME ABEl clause is
specified.
For B5AM and BDAM. input-output
buffers are used as a Logical Record Area
and a separate segment work area must be
Non/VSAM Record Formats
169
allocated.
Segment work areas and Logical
Record Areas are described fully in
"Finding Data Records in an Abnormal
Termination Dump."
the buffer size is calculated from the
longest level-01 record description entry __
In Figure 72, the buffer size is determined
by the description of RECORD-1 (RECORD-1
need not be the first record description
under the FD).
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.
The previous sections discussed four
different record formats. Three of them,
V-mode, U-mode, and S-mode. may contain one
or more OCCURS clauses with the DEPENDING
ON option.
During the execution of a READ
statement, the length of each level-01
record description entry in the FD will be
calculated (Figure 72). The length of the
variable portions 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 72, 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-2; the length of
FIELD-3 by the contents of CONTROL-3 and
the length of FIELD-3.
The following 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 ~D)
or Working-Storage sections, or both.
The compiler calculates the length of
records containing an OCCURS clause with
the DEPENDING ON option at two different
times, as follows (the first applies to YD
entries only, the second to both FD and
Working-Storage entries) :
1.
When a file is read and the object of
a DEPENDING ON option is within the
record.
2.
When the object of the DEPENDING ON
option is changed as a result of a
move to it or to a group that contains
it.
(The length is not calculated
when a move is done to an item which
redefines or renames it.)
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 72 will be inappropriate.
In
such cases, if the contents of the object
of the DEPENDING ON option does not conform
to its picture, the length of the
corresponding record will not be
calculated. For the contents of an item to
conform to its picture:
• An item described as USAGE
WORKING-STORAGE SECTION.
77
77
01
CO NTROL-1
WORKAREA-1
PIC 99.
PIC 9(6)V99.
SALARY-HISTORY.
05 SALARY OCCURS 1 TO 10 TIMES
DEPENDING
ON CONTROL-1
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 recalculated.
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 (Figure 72).
If the BLOCK CONTAINS clause is omitted,
170
must
• An item described as USAGE
COMPUTATIONAL-3 must contain internal
decimal data.
•
consider the following example:
DISPLA~
contain decimal data.
An item described as USAGE
COMPUTATIONAL must con~ain binary data.
• An item described as USAGE DISPLAY
or USAGE COMPUTATIONAL-3 must conform
to the rules for the numeric class
test condition:
If the PICTURE for the item does
not contain an operational s~
the item being tested conforms
only if the contents are unsigned
numeric.
If the PICTURE clause for the
item does contain an operational
sign, the identifier being
tested conforms only if the item
is elementary signed numeric.
In the EBCDIC collating sequence for
signed items, valid embedded operational signs are hexadecimal C, D,
and E; for items described with the
SIGN IS SEPARATE clause, valid
operational signs are + (hexadecimal
4E) and - (hexadecimal 60).
,.PD
INPUT-FILE
DATA BECOROS ARE BECORD-1 RECORD-2 RECORO-3.
01
01
RECORD-1.
PIC 99.
02 CONTBOL-1
02 FI EL 0-1 OCCU RS 1 TO 10 TIM.ES DEPENDING ON CONTROL-1
PIC 9 (5) •
RECORO-2.
PIC 99.
02 CONTROL-2
02 PI ELD- 2 OCCURS 1 TO 5 TIMES DEPENDING ON CONTROL-2
PIC 9 (4) •
01
BECORD-3.
PIC XX.
02 FILLER
PIC 99.
02 CONTROL-3
02 FIELO-3 OCCURS 1 TO 10 TIMES OEPEN DING ON CONTROL-3
L-_ _ _ __
Figure 72.
PIC X(4).
calculating Record Lengths When Using the OCCURS Clause with the DEPENDING ON
option
The following example illustrates the
length calculations made by the system when
a READ statement is executed:
3.
The length of TABLE-3 is calculated
asing the contents of field B.
4.
The length of TABLE-a is calculated
using the contents of field E.
FD
01
RECORD-l.
05 A PIC 99.
05 B PIC 99.
05 C PIC 99 OCCURS 1 TO 5 TIMES
DEPENDING ON A.
01
RECORD-2.
05 D PIC XX.
05 E PIC 99.
05 F PIC 99.
05 G PIC 99 OCCURS 1 TO 5 TIMES
DE,PENDING ON F.
WORKING-STORAGE $ECTION.
01
TABLE-3.
05 H OCCURS 1 TO 10 TIMES DEPENDING
ON B.
01
TABLE-4.
05 I OCCURS 1 TO 10 TIMES DEPENDING
ON E.
When a record is read. lengths are
determined as follows:
The user should be aware of several
additional factors that affect the
successful manipulation of variable-length
records. 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.
WORKING-STORAGE SECTION.
01 REC-l.
05 FIELD-1
PIC S9.
05
FIELD-2 OCCURS 1 TO 5 TIMES
DEPENDING ON FIELD-l PIC X(S).
01
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
follow ing:
• The length of REC-l may have been
calculated at some time prior to tbe
execution of this MOVE statement. The
user should be sure that the current
length of REC-l is the desired one.
•
The length of REC-l may never have been
1.
The length of RECORD-l is calculated
using the contents of field A.
calculated at all. In this case, the
result of the move will be
un peed ic ta hIe.
2.
The length of RECORD-2 is calculated
asing the contents of field F.
• After the move, since the contents of
FIELD-1 have been changed, an attempt
Non/VSAM Record Formats
171
will be made to recalculate the length
of REC-l. This recalculation, however,
will be made only if the new contents
of FIELD-l conform to its picture. In
other words, if FIELD-l does not
contain an external decimal item, the
length of REC-l will not be
recalculated.
!!Qig: According to the COBOL description,
FIELD-2 can occ~r a maximum of five times.
If, however, FIELD-l contains an external
decimal item whose value exceeds five, the
length of REC-l will still be calculated.
One possible consequence of this invalid
calculation will be encountered if the ~ser
attempts to initialize REC-l by moving
zeros or spaces to it. This initialization
would inad vertently dele te part of the
adjacent data stored in REC-2.
The following example 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
OCCURS clause with the DEPENDING ON option.
WORKING-STOP AG E SECT rON.
01
VARIABLE-REC.
OS
FIELD-A
PIC X (10).
05 CONTROL-l
PIC S99.
05 CONTROL-2
PIC S99.
05 VARY-FIELD-1 OCCURS 1 TO 10 TIMES
DEPENDING ON CONTROL-1 PIC X(5) .
05 GROUP-ITEM-1.
10 VARY-FIELD-2 OCCURS 1 TO 10
TIMES DEPENDING ON CONTROL-2
PIC X (9) .
01 STORE-VARY-FIELD-2.
03 GROUP-ITEM-2.
05 VARY-FLD-2 OCCURS 1 TO 10
TIMES DEPENDING ON CONTROL-2
PIC X(9) .
172
Assume tbat CONTROL-l contains the value
5 and VARY-FIELD-l contains 5 entries.
In order to add a sixth field to
'ARY-FIELD-l, the following steps are
required:
MOVE GROUP-ITEM-1 TO GROUP-ITEM-2.
ADD 1 TO CONTROL-1.
MOVE 'additional field' TO
VARY-FIELD-1 (CONTROL-1).
MOVE GROUP-ITEM-2 TO GROUP-ITEM-1.
Note: When an FD contains multiple
01-level entries, the following restriction
applies: The object of an OCCURS
DEPENDING ON clause must be in the
fixed portion of all the records within
that FD (not just in the fixed portion of
the record it is described in).
Stated
another way, the minimum size of each
01-level record must exceed the highest
position of the object of an OCCURS
DEPENDING ON clause appearing in any
01-level record in that FD. Thus, the
following coding would be wrong, and could
cause an abend:
FD
01 RECORD-1.
02 FIELDA PIC X (200) •
02 FIELDB PIC 99.
02 FIELDC PIC XX OCCURS 1 TO 25 TIMES
DEPENDING ON FIELDB.
01 RECORD-2.
02 FIELDD PIC X(100).
For a discussion of the use of the
OCCURS DEPENDING ON clause in a sort
proqra m, see "sorting Varia.ble-Length
Records."
VSAM is a high-performance access method
of OS/VS for use with direct-access
storage.
VSAM provides high-speed
retrieval and storage of data, ease of use
(including simplified Jet statements), data
protection against unauthorized access,
central control of data management
functions, cross-system compatibility, and
device independence.
VSAM data sets can be
processed by the COBOL programmer after
they have been defined through use of the
VSAM multifunction utility program known as
Access Method Services. This utility
(described in the publications Q~I~l
A££~§§.J~lhoL§.g£yi£~ a nd Q~Lv SL!~2§
~~lhod~g~vi£g§) will describe data sets,
load records into them if desired, and
perform numerous other tasts--such as
converting existing ISAM and SAM data sets
to VSAM format.
COBOL allows access to the three major
types of VSAM data sets: entry-sequenced
(ESDS), key-sequenced (KSDS) and relative
record (RRDS). The primary difference
between the three is the order in which
tbeir data records are stored and
retrieved.
Records are stored in an entry-sequence
data set without respect to the contents of
the records. The sequence is determined by
the order in whicb the records are
presented for inclusion in the data se~
that is, their entry sequence.
Nev records
are stored at the end of the data set.
Records can be retrieved sequentially only,
that is, in the order they were stored in
the da ta set.
Records are stored in a key sequenced
data set in key sequence: that is, in the
order defined by tbe collating sequence of
the primary key field in each record. Each
record has a unique value in the primary
key field, such as employee number or
invoice number. VSAM uses the key
associated with each record to insert or
retrieve a record in the data set. The
order can be random or sequential.
Records a re stored in a relative record
data set in rela ti ve record number
sequence. The data set may be described as
a string of fixed-length slots, each of
which is identified by a number which gives
its position relative to the first such
slot. new records are inserted either
sequentially in the next available slot,
where they assume that relative record
number, or according to a relative record
number that the programmer specifies.
Records may be retrieved either
sequentially or by specific relative record
namber.
ENTRY-SEQUENCED DATA SETS
An entry-sequenced data set has no index
associated with it.
Records are added at
the end of the data set. The data set can
be accessed sequentially only; the access
is similar to QSAM except that tape s~orage
or unit record devices cannot be used with
VSAM.
KEY-SEQUENCED DATA SETS
The index and distributed free space are
the most distinctive features of a
key-sequenced data set.
The index relates key values to the data
records in the data set.
A record's key
field and position are the same for every
record in the data set; its value cannot be
altered.
VSAM uses the index t.o locate a
record for retrieval and to locate the
collating position for insertion.
Multiple indexing is also available.
means that a record may bave both a
primary key and up to 254 alternate, or
secondary, keys.
An alternate key may be
any field in the data record that has a
fixed length and position.
(Tn spanned
records, the al terna te key must be in the
first control interval.)
Alternate keys
serve the same function in accessing data,
but allow the user additional flexibility
in bis processing.
In contrast to the
primary key, values of these alternate keys
need not be unique.
~his
When a key-sequenced data set is defined
(through Access Method Services), free
space can be distributed in two ways: by
leaving some space at the end of all the
VSAM File Processing
173
used control intervals l and by leaving some
control intervals completely empty.
Space
becomes available within a control interval
when a record is shortened or deleted.
This space can then be used by VSAMwhen a
record is lengthened in place or inserted
into the control interval.
and EXPORT commands provide a way to
transfer data sets from one system to
another. The BLDINDEX command builds
alternate indexes for VSAM KSDS data sets.
The VERIFY command provides a data set
recovery service for VSAM data sets by
verifying that the end of the data set
indicated in the catalog is the same as the
real data set end.
RELATIVE RECORD DATA SETS
THE DEFINE COMMAND
A relative record data set has no index.
In its string of fixed-length slots, only
the rela ti ve record number--a number from
to a, where n is the maximum number of
records that can be stored in the data
set--identifies the record.
Each record
occupies one slot, and is stored and
retrieved according to the relative record
number of that slot.
The record's contents
and entry sequence are unimportant.
Records in a relati ve record data set
are grouped together in control intervals,
just as they are in a entry-sequenced or
key-sequenced data set. Each control
interval contains the same number of slots.
The size of each slot is the record length
specified by the user when he defined the
da ta set.
The DEFINE command must he used to
define:
1.
Master catalog: catalog in which all
VSAM data sets must be entered.
2.
User catalog: optional catalog in
which VSAM data sets may be entered.
J.
Data space:
by VSAM.
4.
VSAM data set{s): data sets that are
to be processed by VSAM.
5.
Any alternate indexes and alternate
paths.
space which is to be used
In order to process a VSAM data set, the
above must be done in the order indicated.
Therefore it is necessary to fully
understand the DEFINE command, its
functions, and its specification.
Access Method Services is a utility
program that must be used before any COBOL
program can process VSAM files.
A number
of user-entered commands initiate the
Access Method Services programs. There are
two types of commands: functional and
modal. The functional commands inyoke the
desired Access Method Services function,
while the modal commands control the
sequence of execution of the functional
commands.
For more information on modal
commands as well as for complete details on
the specification and uses of Access Method
Services, see the publication Q~S Access
~~thod services.
There are a number of important
functional commands:
DEFINE, ALTER,
DELETE, LISTCAT, REPRO, PRINT, IMPORT,
EXPORT, BLDINDEX, and VERIFY. The commands
DEFINE, ALTER, DELET E, and LISTC!! are used
to create, modify, remove and list entries
in the VSA! catalog. The REPRO and PRINT
commands reproduce data sets either as nev
data sets or as printed output. The IMPORT
1
A control interval is the uni t of
information that VSAM transfers between
virtual and auxiliary storage.
174
Functions of the
DEFIU~.!!SU!.9.
An object, in VSAM terminology, is:
• A VSAM catalog
• A VSAM data set (KSDS, RRDS, or ESDS)
• A VSAM data space
• A VSAM KSDS alternate index and path
Data sets must be introduced to the
system and defined as entries in either the
master or user catalog. Non-VSAM data sets
may also be cataloged in a VSAM catalog.
All VSAM and non-VSAft data sets are
introduced to the system with the DEFINE
command.
There are two steps in the creation of
an object:
(1) defining the ob ject to the
system and (2) generating its contents.
The DEPINE command does not generate the
contents of any object except for the
entries in the master and user catalogs.
The process of defining a VSAM object
includes allocation of storage space,
initialization of catalog entry contents,
and, in the case of defining catalogs,
possible initialization of the object's
storage space.
the data space automatically created are
placed in the master catalog.
The following is an example of defining
a VSAM master catalog:
IIIUJOB1
I/STEP
IISYSPRINT
~ecification
of the-I!MINLCoDlmng
The DEFINE command has the following
format:
IIVOL
IISYSIN
EXEC
DD
DO
DD
DEPINE
DEFINE object parameters
JOB
PGM=IDCAMS
SYSOUT=A
DISP=OLD,UNIT=2314,
VOL=SER=MYVOL
*
MASTERCATALOG{NAME
+
(M ASTCATL) FILE (VOL)
t
VOLUME(myvol) RECORDS +
(300 10)
The definable objects are as follows:
• MASTERCATALOG: specifies that the
VSAM master catalog is to be defined.
• OSERCATALOG: specifies that a VSAM
user catalog is to be defined.
+
MASTERP W(111111)
UPDATEPW (222222)
READPW (333333»
+
+
1+
Note the following concerning the JCL
used.
• SPACE: specifies that a VSAM data
space is to be defined.
• PGM=IDCAMS is required to invoke Access
Method Services.
• CLOSTER:
specifies that a data set is
to be defined.
• MYVOL is the volume serial number of
the volume on which the master cataloq
is to reside. I/VOL is the DD
statement identifying that volume.
• ALTERNATEINDEX: specifies that an
alternate index for a KSDS is to be
defined and have space allocated.
• PATH:
establishes the relationship
between an alternate index and its
data set (base cluster) •
• NONVSAM: specifies that a data set
not having the VSAM data set
organization is to be cataloged in a
VSAM ca talog.
For each data set there is an associated
valid parameter list. See the publication
Q~L!S A££g§2~~thQg_~~£yi£~§ for the
specification rules for DEFINE and its
associated objects and parameters.
In this example the following parameters
were used:
• NAME (objectname). This is a required
parameter. The objectname is cataloged
and is the name that must be used in
all future references to the master
catalog.
• FILE (dname). This is a required
parameter identifying the JeL statement
that specifies the device and volume
which are to contain the master
catalog. The associated JCL statement
should specify DISP=OLD.
For dname,
the name of the JCL statement that
specifies the device and volume to
contain the master catalog is
substi tuted •
.I2gfininLa-11a§teL£ataloY..i..~&!':!!i~
ll~ERCAllLOQ
The DEFINE MASTERCATALOG command is used
in YS1 to set up the master catalog.
(In
YS2, this command only creates a user
catalog. The VS2 master catalog is created
at system-generation time.)
It is the first
Access Method Services command ever used
since without a master catalog other
objects cannot be defined.
Defining a
master catalog automatically creates the
data space necessary to contain the
catalog.
Entries for both the master
catalog itself and the volume containing
• VOLUME (volser). This is a required
parameter that specifies the volume to
contain the master catalog.
• RECORDS (primary[ secondary]). This is
a required parameter that specifies the
amount of space to be allocated in
terms of the number of records the
space is to hold.
The capacity of the
allocated space is device independent.
The size of the primary extent is
specified by primary. Once the primary
extent is filled, the data space can
expand to include a maximum of 15
secondary exte-nts if the size of
VSAM File Processing
175
secondary extents is specified through
secondary.
For primary and secondary, the number
of records the master catalog is to be
able to hold is substituted. Note that
every KSDS requires three catalog
entries:
one each for the cluster,
data component, and index component.
Every ESDS requires two catalog
entries: one for the cluster and one
for the data component.
• MASTERPW (password).
This optional
parameter specifies a master level
password for the master catalog being
defined. The master level password is
the highest level that can be
specified; it allows all operations.
If a master level password is not
supplied but other levels are, the
highest level supplied password becomes
the password for all higher levels
including the master level. The master
catalog must be password protected if
any VSAM clusters are to he protected.
• UPDATEPW (password).
This optional
parameter specifies an update level
password. The password permits read
and write operations against the master
catalog.
The master catalog must be
password protected if any VSAM clusters
are to be protected.
• READPW (password). This optional
parameter specifies a read level
password for the master catalog being
defined.
The read level password
permits read operations against the
master catalog. The master catalog
must be password protected if any VSAM
clusters are to be protected.
• CATALOG (mastercatname/password). This
pa rame ter specifies the name and
password of the master catalog that
contains the entry for the user catalog
being defined. This parameter is
required only when the master catalog
is password protected.
For mastercatname, the name of the
master catalog is substituted. Por
password, the update or higher level
pa,sword is substituted.
The DEFINE SPACE command is used to
define VSAM data spaces or to reserve
volumes for future use by VSAM. A VSAM
data space is space on a direct access
volume that is owned and managed by VSAM.
Clusters cannot be de.fined without the
UNIQUE attribute unless a VSAM data space
is defined to contain them.
A VSAM data
space may include several extents on the
same volume but it cannot span volumes.
The volume containing the data space is
owned by the catalog containing the entry
for the space. Data spaces on several
volumes can be defined at one time.
The following is an example of def~ning
a VSAM data space:
//ltYJOB2
//STEP
/ /SYSPRI NT·
//SPACDD
JOB
EXEC
DD
DO
//SYSIN
DO
PGM=IDCAMS
SYSOUT=A
DISP=OLD~UNIT=2314,
VOL=SER=MYVOL
DEFINE
*
SPACE{VOLUME{MYVOL)FILE+
+
(SPACDD)
CYLINDERS(30 5) CATALOG+
(M ASTCATL/22222 2)
*
In this example the following parameters
were used:
The DEFINE USERCATALOG command is used
to set up user catalogs.
When a user
catalog is defined, a data space to
containthe catalog is automatically
created.
An entry for the volume
containing the data space is placed in the
user catalog being defined. Entries for
the user catalog being defined are placed
in the master catalog and in the user
catalog itself ..
The parameters that may be used with
DEFINE USERCATALOG are the same as those
described for DEFINE MASTERCATALOG with one
exception.
There is an additional
parameter that may be used with DEPINE
USERCATALOG as follows:
176
• VOLUMEs{volser[ ••• ]). This required
parameter specifies the volumes to
contain the data spaces. If more than
one volume is specified, each volume
will contain a data space of the same
size.
.• FILE (dname) • This required parameter
identifies the JCL statement that
specifies the devices and volumes to be
used for space allocation. [For dname,
SUbstitute the name of the JCL
statement that specifies the devices
and volumes to be used for space
allocation.] All volumes must be of the
same device type.
• CYLtNDERS(primary[secondary]). This
parameter specifies the amount of space
to be allocat.ed in t.erms of cylinders.
The capacity of the allocated space is
device dependent. Either this
parameter or the TRACKS or RECORDS
parameter must be specified. The size
of the primary extent. is specified by
primary.
O'nce the primary extent. is
filled, the data space can expand to
include a maximum of 15 secondary
extents if the size of secondary
extent.s is specified through secondary.
For primary and secondary, the number
of cylinders to be allocated t.o the
data space is substituted.
• CATALOG(catname(/password][ dname]).
This par aile te.r specifies the name and
password of the catalog in which the
data space is t.o be defined. (For
catname, s~bstitute the name of the
catalog that is to contain the entry
for the data space.] This parameter is
specified if the desired catalog is not
the default catalog (see Defaults
below).
If the catalog is password
protected, the password must be
specified.
If the desired catalog is neither the
master catalog nor a catalog identified
by a JOBCAT or STEPCAT DD statement,
the na me of the DD sta tement
identifying the catalog must be
specified.
For dname, the name of the
DD statement that identifies the
desired catalog is substituted.
Defaults: The data space is defined in
the catalog identified as STEPCAT. If
STEPCAT is not provided, the data space
is defined in the catalog identified as
JOBCAT. If JOBCAT is not provided. the
data space is defined in the master
ca talog.
Figure 73 is an example of defining an
indexed VSAM data set.
DEFINE CLUSTER is
used to define the attributes of all VSAM
data sets and to catalog the data sets in a
VSAM catalog. This command does not put
any records into the VSAM data set. COBOL
permits reference only to a KSDS cluster;
in other words, the KSDS's data and index
components cannot be defined separately.
The DEFINE CLUSTER command establishes
the primary keys for the records. If only
primary keys are to be used, then only this
DEFINE CLUSTER command is needed. If
alternate keys are also to be used (as in
this example), they are established with
the DEFINE ALTERNATEINDEX and DEFINE PATH
commands. In addition (after the base
cluster is filled with records), a
follow-on job must be run to specify the
BLDINDEX command (see the Access Method
Services manual).
In this example the following parameters
were used:
• NAME(objectname}.
This is a required
parameter. It must be specified at the
cluster level.
• FILE identifies the DD statement
specifying the device and volume that
are to contain the VSAM object being
defined.
• VOLUME (volser [ ••• ]).
This is a
required parameter that specifies the
volumes to contain the object.
More
than one volume can be specified; the
volumes actually allocated are listed.
• RECORDS (primary ( secondary]) specifies
the amount of space to be allocated in
terms of the number of records the
space is to hold.
VSAM File Processing
177
,.------
'1
I //MYJOB3
J //STEP
1 //SYSPRINT
I //MYDD
1 / /SYSIN
I
DEFINE
f
J
1
f
I
DEFINE
t
I
•
DEFINE
JOB
EXEC
DD
DD
DD
PGM=IDCAMS
SYSOUT=A
VOL=SER=MYVOL,UNIT=SYSDA,DISP=OLD
•
CLUSTER (NAME (SAMPLE) FILE (MYDD) VOLUME (MIVOL)
+
RECORDS (500 50) RECORDSIZE (45 80)
+
PREESPACE{25 10) SUBAL'LOCATtON INDEXED
+
+
KEYS (8 2) UPDATEPW (RD(iNDWRT) READPW (BEADONLY)
ATTEMPTS(O»,CATALOG(MASTCATL/222 22~
ALTERNATEINDEX(NAME(ALTX) RELATE (SAMPLE)
+ t
PI LE (MYDD 1)
VOLUME (MY VOL)
RECORDS (SOD 50)
KEYS~
15) UNIQUEKEY UPDATEPW(RDANDWRT)
READPW(READONLY)+
ATTEMPTS (0»
CATALOG(MASTCATL/222 222)
UPGRADE
PATH (NAME (PATHX)
PATH ENTRY (ALTX)
UPDATE +
CATALOG (MASTCATL/222 222)
*
~
73.
Defining a VSAM Inde.xed Data Set (KSDS)
• RECORDSIZE(average maximum) specifies
the average and maximum lengths of the
records in the data component of the
cluster. This is a required parameter.
The size specified can be from 1 to
32,761.
The number substituted for average
should be the number of bytes that is
the average length of all logical
records. The number substituted for
maximum should be the maximum length of
the largest logical record.
FREESPACE(cipercen~ capercent])
specifies the amount of space that is
to be left free after any allocation
and after any split of control
intervals and control areas. The
amount is specified as a percentage.
For cipercent, the percentage of unused
space desired in each control interval
is specified. For capercent, the
percentage of unused space desired in
each control area is specified.
• SUBALLOCATION specifies that a portion
of an already defined VSUI data space
is to be 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.
• INDEXED specifies that the cluster
being defined is for a KSDS.
• KEYS (length position) specifies the
length of the keys in a KSDS and their
position within the records. The
length of the keys is specified by
length; the displacement of the keys
within the record is specified by
118
J
I
I
I
I
I
I
I
I
I
J
t
f
I
I
I
J
Figure
•
t
with Both Primary and Alternate Keys
position. The first character in a
record is at displacement O.
• UPDATEPW(password) specifies an update
level password for the data set being
defined. The update level password
permits input and update (READ, START,
DELETE, WRITE, REWRITE) operations
against the logical r~cords of the data
set.
• READPW(passvord) specifies a read level
password for the object being defined.
The read level password permits input
(READ, START) opecations against the
logical records of the data set.
• ATTEMPTS (number) specifies the maximum
number of times the operator can try to
enter a correct password in response to
a prompting message. This parameter
should always specify 0 as the number.
• CATALOG (catname[ /password][ dnam.e])
specifies the name of the catalog into
which the cluster is to be defined.
The name of the catalog is substituted
for catname. If the catalog is
password protected, the password must
also be supplied.
The name of the DD statement
identifying the catalog must be
specified if the catalog is neither the
master catalog nor a catalog identified
by a JOBCAT or STEPCAT DD statement or
if the catalog obtained through the
default is not the desired catalog~
For dname, substitute the name of the
DD statement that identifies the
catalog_
• RELATE specifies the name of the base
cluster, as given in the (NAME(name)}
field of the DEPINE CLUSTER for this
data set. This is a required
parameter.
• UNIQUEKEY/NONUNIQUEKEY specifies
whether each alterna te key points to
only one data record or to more than
one. If to more than one, then
NONUNIQUEKEY must be specified and tke
COBOL program must contain the WITH
DUPLICATES phrase in the associated
ALTERNATE RECORD KEY.
A specification
of UNIQUEKEY requires that the COBOL
program not have such a WITH DUPLICATES
phrase.
modifications, the DEFINE CLUSTER portion
of Figure 73 could be used to define an
RRDS:
1.
Change INDEXED to NUMBERED.
2.
Remove the KEYS parameter.
3.
Remove the FREESPACE parameter.
4.
Change the RECORDSIZE parameter so
that the average and maximum value
specifications are the same.
• UPGRADE specifies that this alternate
index is to be kept up to date when its
base cluster is modified. This is a
required parameter.
• PATHENTHY specifies the name of the
alternate index, as given in the
(NAME(name»
field for the related
DEFINE ALTERNATEINDEX. This is a
required parameter.
• UPDATE specifies that the base
cluster's upgrade set is to be
allocated when the path is opened.
This allows updating of alternate
indexes (see UPGRADE above), and is a
required parameter.
Defining an ESDS is quite similar to
defining a KSDS.
with the following
modifications, the DEFINE CLUSTER portion
of Figure 73 could be used to define an
ESDS:
1.
Change INDEXED to NONINDEXED.
2.
Remoye the KEy'S parameter.
3.
Remove the FREESPACE parameter.
!~DIIIQ!!1-fARAMETER~:
Additional
parameters are valid for DEFINE CLUSTER,
ALTERNATEINDEX, and PATH. Complete details
on the use of these parameters are in the
publication OS/YS_Ac~~ethod_seryice2.
Defining an RRDS is quite similar to
defining a KSDS.
with the following
If a COBOL program wishes to use a VSAM
data set for a workfile (that is, use the
data set again and again during the course
of processing), the REUSE parameter must be
included in the DEFINE CLUSTER
specification. and the data set must be
opened OUTPUT.
(Its status is then
"unloaded.") ESDS and RRDS data sets and
KSDS data sets without alternate indexes
can be reused in this manner.
VSAM File Processing
179
!1iscellaneous
DEFINE~stgk
Considerations
The control interval is the unit of
transmission of data to and from main
storage. VSAM determines the size of the
control interval based upon the amount of
BUFFERSPACE specified and the size of the
RECORDSIZE specified. If BUFFERSPACE is
not specified and if the size of the
records permits, VSAM uses the optimum
size for the data component control
in tervals and 512 as the size of the index
component control intervals.
CQBOL
nil
PROCESS~~IDERAT.IONS
The f il e processing considera ti ons of
importance to the COBOL programmer are:
the file processing techniques available,
the current record pointer, the START
statement, and the error processing options
available.
180
FILE PROCESSING TECHNIQUES
The COBOL user has three different file
processing techniques available to him:
sequential, random, and dynamic fa
combination of sequential and random). The
technique to be used is specified through
the ACCESS clause of the SELECT statement.
An ESDS can only be processed
sequentially. Therefore, the ACCESS clause
need not be specified since the default is
sequen tial.
CURRENT RECORD POINTER
A KSDS or an RHOS can be processed
sequentially, randomly, or both
sequentially and randomly.
To process
sequentially, ACCESS IS SEQUENTIAL is
specified.
To process randomly, ACCESS IS
RANDOM is specified. To process both
sequentially and randomly, ACCESS IS
DYNAMIC is specified.
ACCESS IS DYNAMIC provides the greatest
flexibility since most of the capabilities
of both sequential and random processing
are available.
Subsequent to an OPEN
statement processing can be switched from
sequential to random and vice-versa, as
many times as desired.
The current record pointer (CRP), a
conceptual pointer. is applicable only to
sequential requests for ESDS, RRDS, and
KSDS. Basically, the current record
pointer indicates the next record to be
accessed by a sequential request; the CRP
has no meaning for random processing or
output operat.ions. 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.
In general, the last request on a file
that establishes the CRP (OPEN, READ, or
START) must have been successful in order
for the sequential READ to be successful.
Example 1:
PASSWORD USAGE
If ·the sequence of 1/0 operations on a
file with ACCESS IS DYNAMIC and opened 1-0
is:
The following procedures must be used
when password support is employed with the
VSAM da ta sets:
READ
WRITE
READ NEXT
• Through Access Method Services (at
DEPINE time), the programmer must
passliord-protect the base cluster (as
opposed to the data and its index
separately). This is the password
specified with the RECORD or RELATIVE
KEY.
If the data set is a KSDS with
alternate keys, then the programmer
must also password-protect either the
path to the base cluster via an
alternate index, or the alternate index
itself. This is the password specified
with the ALTERNATE RECORD KEY.
• In the COBOL program, the user must
specify the correct level of the
password:
read-only, update, and so
on.
Failure to do so will cause a
rejection of the action request which
violates the protection.
• In the COBOL program, the password (if
present for the data set) must be
specified for every ALTERNATE RECORD
KEY defined in the program--regardless
of whether any accessing will ever
actually be done using them.
(This
requirement does not apply if the file
is opened only for OUTPUT and the user
does not request a dynamic invocation
of Access Plethod services via the
AIXBLD option.)
the BEAD NEXT will get record 11 if the
previous READ was successful. If the
previous 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 success of the intervening WRITE.
Generally, a READ NEXT must be preceded
by a request that establishes the CRP
(OPEN, START, READ, READ NEXT). If the
request that establishes the CRP is
unsuccessful, the READ NEXT causes the
STATUS KEY to be set to 94.
Example 2:
In this example, ACCESS IS SEQUENTIAL is
specified for a KSDS; therefore, records
are retrieved in ascending key sequence
starting at the position indicated by the
CRP.
(CRP at record with
lowest key in file)
OPEN INPUT
(Set record key to 10)
START
READ
(Set record key to 5)
START
READ
READ.
• All required passwords must be
correctly specified for the file before
the COBOL OPEN viII succeed.
(After setting record key to 10)
(After setting record key to 44)
READ
(CRP at record 10)
(Read record 10)
(CRP at record 5)
(Read record 5; CRP
set to record 6)
(Read record 6; CRP
set to record 7)
(Read record 7:CRP
set to record 8)
VSAM File processing
181
Note that the CRP can be moved around
randomly through the use of the START
statement but all reading is done
sequentially from that point.
The REWRITE failed because record 74 was
not read before the REWRITE was attempted.
If the START request for record key 5
had failed with no record found~ the
subsequent READ requests would have failed
because there would have been no current
record pointer.
In this exa mple ~ ACCESS IS DYNAMIC is
specified for a KSDS with an alternate
record key, AIXKEY, defined. Assume that
the file contains eight records whose
primary and alternate key values are as
follows:
Example 5:
Example 3:
In this example ACCESS IS DYNAMIC is
spec ified. Theref ore~ records are accessed
randomly if a READ is specified and
sequentially if READ NEXT is specified.
The highest key is 44.
OPEN INPUT
(Set record key to
READ
(CRP is set to
lowest key on file)
8th
5)
READ NEXT
READ NEXT
(Read record 5; set
CRP to record 6)
(Read record 6; set
CRP to record 7)
(Read record 7; set
(CRP to record 8
(set record key to 43)
s'r ART
BEAD NEXT
(Set record Key to 47)
START
READ NEXT
(Position CRP to
record 43)
(Read record 43; set
CRP to 44)
(Fails - no CRP)
The last READ NEXT failed because the
preceding START vas unsuccessful; in this
data set there is no record 47.
Example 4:
In this updating example, ACCESS IS
DYNAMIC is specified: the REWRITE statement
does not affect the CRP.
OPEN 1-0
(Set record Key to 10)
RE AD
REWRITE
READ NEXT
(CRP is set to
first record on
file)
(Read record 10; set
CRP to record 11)
(Updates record 10;
CRP remains at
record 11)
(Read record 11;
set CRP to record
12)
(Set record key to 74)
REWRITE
READ NEXT
(Fails - record not
found in this data
set
(Read record 12; set
CRP to record 13)
Note that although the last REWRITE failed,
the following READ NEXT was successful.
182
1st
2nd
3rd
4th
5th
6th
7th
OPEN 1-0
5
10
15
100
70
80
20
25
85
75
30
35
40
50
95
55
(CRP is set to the
first record of file
and the key of
reference is the
primary key)
(set record key to 10)
READ (without KEY clause)
Read second record;
set CRP to third
record)
(set alternate key to 50)
READ KEY IS AIXKEY
(the key of
reference is the
alternate key; read
siith record; set
CRP to eigh th
record)
READ NEXT
(the key of
reference remains
the alternate key;
read eighth record;
set CRP to second
record)
(set primary key to 45
and a1 terna te key to 90)
WRITE
(write ninth record;
CRP remains at
second record; the
key of reference
also remains the
alternate key)
READ NEXT
(read second record;
CRP is set to fifth
record)
(set alternate key to 100)
START KEY = AlXKEY
(CRP is set to first
record; the key of
reference is the
alterna te key)
READ NEXT
(read first record;
CRP is set so that
the next sequential
read results in the
AT END condition)
READ NEXT
(The AT END
condition is raised;
CRP is undefined)
USE OF THE START VERB
In some of the preceding examples, the
START verb vas used to position the CRP.
Then the READ (for ACCESS IS SEQUENTIAL)
and READ NEXT (for sequential pr ocessing
when ACCESS IS DYNAMIC) retrieves the
record pOinted to by the CRP as established
by the START.
Example:
05
RECORD-KEY.
10 GEN11.
15 GEN12
15 GEN13
10 GEN14
PIC 99.
PIC 99.
PIC 9.
In this example, GEN12, GEN11, or
RECORD-KEY could be used as the data-name
in the "KEY IS relational data-name" option
of the START statement. The lengths would
be 2, 4, and 5 respectively.
GEN13 and
GEN14 could not be used as they are not in
the le.ftmost part of RECORD-KEY.
%he Importance
of~1~2-K~Y
All errors in processing a VSAM file,
whether a logic error on the part of the
COBOL programmer or an I/O error on the
external storage media, return control to
the COBOL program.
Upon return to the
COBOL program, the Status Key will indicate
the status of the last request on the file.
Figure 74 indicates the possible value of
the status Key and their associated general
meanings.
Harn,!!Hl: It is essential that all VSAM
files have a status Key associated with
them and that the proqrammer always check
the contents of the status Key after each
IIO request. If status Key is not used
(and an EXCEPTION/ERROR procedure is not
present), serious errors will go
undiscovered by the program--which does nQ!
abend. The continued processing in such a
situation may produce results that are not
only destructive but difficult to detect.
Assume that the value of RECORD-KEY is
01472:
• START file-name KEY=GEN11 would
position the CRP to the first record on
the file whose key has 0147 in the
first 4 bytes.
• START filename KEY > GEN12 would
position the CRP to the first record in
the file whose key has the first two
bytes greater than 01.
If the INVALID KEY option is specified
in the statement causing an invalid key
condition, control is transferred to the
INVALID KEY imperative-statement.
Any
EXCEPTION/ERROR declarative procedure
specified for this data set is not
executed. If the FILE-STATUS clause is
specified, a value is placed into the
Status Key to indicate INVALID KEY
condition.
ERROR PROCESSING OPTIONS
The error processing options available
to the COBOL programmer are INVALID KEY,
EXCEPTION/ERBOR procedure, and STATUS KEY.
These options can be used in combination
with each other.
The EXCEPTION/ERROR procedure is invoked
only when a file is in the open status.
VSAM File Processing
183
.-J
I
--.....,- - - - - ------.----r-
i
•
status Key 11
Value
I
Meaning
I
0
Isuccessful Completion
I
,Status Key 21
I
I Value
,
Meaning
I
,
f
f
1
I
0
iNo Further Information
I
I
f
I
~
J
I
t
2
I Duplicate Key Found, And
I
t
I
I
1 Program Specified the
1
J
I
" D U P L I C A T E S Option
I
I--------t-I
I
.,
I
1
fAt End (no next logical record"
0
,No Further Information
I
J
Jar an OPTIONAL file not avail1
J able a t OPEN time)
J
J
I
I-I
I
.,
I
(
I
0
INo Further Information
I
-------.--1-,--
J '
-+-
I~
-----
I
J
"I
2
t In valid
Key
f
' I
II
I
I
I
I
•
I
J
I
I
I Sequence Error
l------t
J
1
I
2
I
I
I
.,
I
JDuplicate Key Found, But
tDuplicate Keys Not Allowed I
l-------+
..
'J
.,
.,
J
I No Record Found
I
J
..
I
f
I
t
4
I Boundary Violation on WRITEJ
I
' J to VSAM indexed or relative,
I
f
I
I file (space not found to
I
I
I
1
1 add requested record)
I
i-----------fI
J
of
I
]
JPermanent Error (data check,
I
0
,No Further Information
,
J
I pari ty check, transmission"
J
f
I
lerror)
•
4
,Boundary Violation on WRITE,
I
I
J
,to sequential VSAM file
I
I
I
I
I (space not found to add
.1
I
I
I !requested record)
I
i-------+_
--+
i
.,
,9
)other Errors
t
0
INO Further Information
I
I f , .
I
of
I
I
I
1
,Password Failure
t
I I
I-------t
,
t
I
J
2
ILogic Error
I
t
I
t
I
J
3
,Resource Not Available
1
I
I
•
I
---1
1
1
t
4
INo current Record Pointer
I
J
J
I
1Par sequential Request
t
I
II--------t
---1
•
J
I
5
IInvalid Or Incomplete File I
I
I
I
IInformation
I
•
1
1---.
~
J
I
,
6
I No DD Card
f
1
I
~
I
I
I
I
J
J
J
I
i
J
J
J
, r
L
Figure 74.
1-
J
7
I The data set was not pro- I
Iperly closed; an implicit'
I VERIFY has therefore been I
J issued, and the file then I
I successfully opened.
I
_--1-
Status Key Values And Their Meanings
Figure 75 is a table of actions taken
for all the combinations of AT END, INVALID
KEY and EXCEPTION/ERROR Procedure based on
the first character of the status Key
return.
Note that the return is always to
184
I
J
3
the next sentence unless the request that
caused the error contained on AT END or
INVALID KEY clause.
Note also that the
EXCEPTION/ERROR Procedure is executed only
if the file is in the open status.
j
.-
.....
,---
I First Diqi t
of
I
I Statl1s Key
I
rI
I
0
I
I
1-------.. . - I
I
I
1
I
t
j
-T,
1
I
IReturn to AT
JReturn to next sen'END/INVALID KEY)tence after execution
I add['ess.
,of EXCEPTION/ERROR
I
,Procedure.
I
J
-+-
I
I
J
,
I
I
•
I
I
I
I
I
IReturn to next IReturn to next
1sentence.
I sentence.
I
I
I
I
I
,
a-I
,
I
9
IReturn to next JReturnto next
,
Jsentence.
,sentence.
I
I
I
I
I
•
IL-______________-4'J _______________•___ t
3
~,_______________
Figure 75.
-+
,Return to AT
IReturn to next
JEND/INVALID KEYlsentence.
J address..
I
t
,
,Return to AT
,Return to next
'END/INVALID KEYJsentence.
laddress.
I
2
1
,
No EXCEPTION/ERROR P['ocedure
I
wi th EXCEPTION/ERROR P['ocedu['e
I
------------111--,--------------~
J AT END
INo AT END
I AT END
I No AT END
,
lor INVALID KEY lor INVALID KEY
lor INVALID KEY lor INVALID KEY
I
I
-+J
+i
JReturn to next jReturn to next
IReturn to next 1Return to next
,
I sentence.
,sentence.
I sentence.
J sen tence.
I
-+-
JReturn to AT
JReturn to next senlEND/INVALID KEYltence after execution
Jadd['ess.
lof EXCEPTION/ERROR
J
IProcedure.
I
+
IReturn to next )return to next senI senten ce after t tence a ft.er execution
Jexecution of
lof EXCEPTION/ERROR
lEXCEPTION/ERRORIProcedure.
j Procedure.
,
-+-
,
..
1
I
I
I
..
I
I
J
1
,
I
I
J
J
I
...
IReturn to next IReturn to next. sen1
Isentence after Itence after execution I
lexecution of
lof EXCEPTION/ERROR
I
J EXCEPTION/ERRORt P['ocedure.
J
J Procedure.
_____________ I
____________________ JI
~
~
Error Handling Actions Based on COBOL p['ogram Coding.
OPENING A VSAM FILE
• Any other request--w ill fail, wi th
status key set to 92
VSAM files can be opened INPUT, OUTPUT,
EXTEND, or 1-0.
~nd
first
• WRITE--will succeed, if a valid request,
and any subsequent request will be
treated as if made to a loaded file.
2Eening an Unloaded File
An unloaded file is a file that has
never contained records.
opened OUTPUT or EXTEND.
If unloaded file is opened I-v
operation is:
It is normally
While certain types of unloaded files
may also be successfully opened INPUT or
I-a, the following conditions will occur if
atte~pts are then made to access it.
If unloaded file is opened INPUT and
operation is:
• READ sequential--will fail,
• NOTE: A WRITE to a sequentiallyaccessed file is not a valid request
when opened I-a.
• READ sequential (if first
request)--will fail, wit.h status .key
set to 10
• READ random (if first request)--will
fail, with status key set to 23
• START {if first request)--will fail,
with status key set to 23
with status
key set to 10
• READ random--will fail, with status key
set to 23
• START--will fail. with status key set
to 23
• REWRITE/DRLETE sequential (if first
request)--will fail, with status key
set to 92
• REWRITE/DELETE random or dynamic (if
first request)--vill fail with status
key set to 23
VSAM File Processing
185
An empty file is a previously created
file from which all records have been
deleted.' It can be opened EXTEND, INPUT or
1-0.
After opening, the first READ request
viII cause an AT END condition (Status Key
= 10) or an INVALID KEY condition (Status
Key = 23), depending on the access mode of
the file.
An empty file cannot be -opened
OUTPUT.
A file containing records cah be opened
INPUT, EXTEND or I-a. If a KSDS is opened
EXTEND, the first record to be added must
have its record key higher than the highest
record key on the file when it vas opened.
If the record key is not higher the statQS
key will be set to 92.
For an ESDS, the
records are added after the last record on
the file.
An RRDS cannot be opened EXTEND.
If any of the OPEN rules are violated
the file is not opened and the Status Key
is set to the appropriate value. See
Figure 76 for the OPEN Status Key values
and their meanings.
QIB~mic IB~Q£A1ion_Qf-!££~~§~ethog
~gU ices-.t.Q!--K~L~ d
RR DS_Q a t a_~i2.
(NO~:
The following feature is
provided only to assure compliance vith the
1974 ANS COBOL standard X3.23-1974.
Use of
the feature will necessarily adversely
affect execution-time performance.)
186
As described earlier, the user must
employ Access Meth od Ser vices to def ine all
VSAM files and their indexes ahead of
time--outside of the COBOL program.
Normally at this time, the user specifies
the size of the filets records, and (for
KsDs) the lengths and offsets of primary
and any alternate keys. He also builds the
actual alternate indexes.
However, if he wishes, the user may
choose to omit these elements of the
definition procedure and have COBOL
automatically perform them later when the
file is opened for OUTPUT processing.
COBOL does this by obtaining the correct
record and key specifications from the
program's source statements, and then
issuing the Access ~ethod Services ALTER
and BLDINDEX commands.
If this is the user's choice, he must
make it known to COBOL by including the
object-time {GO-step) option A1XBLD.
(He
must also ensure that the Access Method
Services program is available for his COBOL
program to invoke.)
For an RRDS, COBOL will then fill in the
record size information.
For a KSDS, COBOL
will fill in record size, and length and
displa~ement for primary keys.
If the KsDs
has alternate keys, COBOL also fills in
their length and displacement, and issues
the BLDINDEX command.
(Because the
BLDINDEX command can be issued only after a
base cluster is loaded, COBOL first fills
it with dummy records, then issues the
BLDINtiEX command, and then erases them.)
Because the large Access Method services
program must be presen.t when. t.he COBOL
program is run with this feature,
substantial extra main storage is required.
Use of the AIXBLD feature also requires the
user to provide a sYSPRINT DD card for
Access Method Services messages.
If this
card is missing, OPEN failure will result
(status Key = 95).
either COBOL itself detected one of these
conditions •••
•.. or VSAM found
an error and returned
one of the following
VSAM error codes*
00
None
100 (if AIXBLD was
specified)
128 (if file is
optional)
160 (if file was
to be opened
for input)
30
None
132,144,164,176,
184
-
90
Failure of an attempt to write a dummy
record to or delete a dummy record from the
file.
Such a failure may occur in the
following cases:
96,108,116,192,
196,200,204,208,
212,216,220,224,
236,240,244 (plus any
other VSAM codes not
appearing elsewhere in
this table)
If the Status Key
given to the user
was •••
-- an indexed file is opened for OUTPUT and
the access mode is either RANDOM or
DYNAMIC.
a file to be opened I-O has just been
created.
-- the object-time option AIXBLD was
specified and the file has at least one
alternate record key.
Failure of attempt to use a CBMM,macro.
Failure of attempt to ti.se a BLDL system
macro; this macro is used when the
programmer has specified the object-time
option AIXBLD.
91
None
152
92
The file to be opened is already open.
4
* COBOL's VSAM-processing subroutines retrieve the VSAM return code from the
ACBERFLG field of the Access Control Block (ACB) by issuing a SHOWCB macro,
translate it into 0ne of the status key values above (as prescribed by the
ANS standard), and move that value into the STATUS KEY field where it
becomes accessible in the user's program. An explanation of the meanings
of the VSAM return codes can be found in the VSAM Programmer's Guide.
Figure 76.
(Part 1 of 2)
status Key Values for OPEN Requests
VSAM File Processing
187
If the Status Key
given to the user
was •••
93
either COBOL itself detected one of these
conditions •.•
••• or VSAM found
an error and returned
one of the following
VSAM error codes*
COBOL cannot obtain sufficient virtual
storage for:
136
168
-- the general work area used by the COBOL
VSAM-interface modules.
-- the Access Control Block (ACB) address
list area during the OPEN process.
-- the work area required for the
invocation of Access Method Services.
-- processing of the uspr declarative.
95
i
The ENDRBA of a file to be opened OUTPUT
is not zero.
The length and/or offset of the key of
each cluster do not match those in the
catalog.
A KSDS cluster is to be opened as a COBOL
sequential (ESDS) file.
100 (if AIXBLD was
not specified)
104,108,148,
160 (if a file
is not to
be opened
for INPUT)
180,188,232
An attempt was made to either alter the
record size and/or key information of a
cluster or build alternate indexes, and
Access Method Services returned a non-zero
return code.
*
96
No DD card is present for a path to be
opened.
128 (if a file
is not
optional)
97
OPEN is successful for a data set with
alternate keys opened I-a, EXTEND, or
OUTPUT, and an implicit VERIFY has
occurred.
118
COBOL's VSAM-processing subroutines retrieve the VSAM return code from the
ACBERFLG field of the Access Control Block (ACB) by issuing a SHOWCB macro,
translate it into one of the status key values above (as prescribed by the
ANS standard), and move that value into the STATUS KEY field where it
becomes accessible in the user's program. An explanation of the meanings
of the VSAM return codes can be found in the VSAl-1 Programmer's Guide.
Figure 76.
(Part 2 of 2) status Key Values for OPEN Requests
INITIAL LOADING OF RECORDS INTO A PILE
I nitial loading refers to wri ti~g
records into a file after it is opened for
the first time; this is distinctly
different than writing records into an
empty file (a previously created file from
which all records have been deleted).
not conserve any free space in the file
and, as a result# any future inserts
require the file to be dynamically
reorganized.
When the file is unloaded and is opened
EXTEND, it is processed exactly the same as
it would be had it been opened OUTPUT.
WRITING RECORDS INTO A VSAM FILE
It is recommended that initial loadinq
of records into a KSDS always be done
sequentially. This assists in optimizing
performance for the initial loading process
as well as for any subsequent processing on
the file. Loading records randomly does
to a file; it does not replace an existing
188
The COBOL WRITE statement adds a record
record on the file. The record to be
written must not be larger than the maximum
record size specified when the file was
defined.
Records are written sequentially.
The records must be written in ascending
key sequence. If the file is opened
EXTEND, the record keys of the records to
be added must be hiqher than the highest
record key on the file when the file was
opened.
For example, a file containing records
whose records keys are 2, 4, 6. 8 and 10 is
opened EXTEND; the following actions take
place for the sequence of operations shown:
WRITE
WRITE
WRITE
WRITE
{record
{record
{record
(record
key
key
key
key
8)
9)
12)
11)
SK
SK
SK
SK
92
= 92
00
= 21
If many records are to be added to the
end of a file, it is recommended that
sequential processing be used.
It assists
in optimizing processing for both the
addition of records as well as later
retrieval of them.
Ka1!~--&Qnaderat.1.211§_=-1!££M~_IS
iA!rnQUlUNAM.Itl
When a file has alternate keys, the
records must be written using their primary
keys.
For a sequential request, the first
record written will have relative record
number one, the second two, the third
three, and so on. If a RELATIVE KEY data
item was included by the user in the file
control entry statement, the relative
record number of the record just written
will be placed in the data item.
The file must be opened I-O; if not, the
record is not rewritten and the Status Key
is set to 92. The record to be rewritten
must first be read by the COBOL program;
the record may then be rewritten.
If there
was no preceding READ, or if the preceding
READ vas not successful, the record is not
rewritten and the Status Key is set to 92.
If an attempt is made to change the length
of the record to be rewritten, the status
Key is set to 92.
The file must be opened 1-0; if not, the
record is not rewritten and the Status Key
is set to 92. The length of the record can
be changed; the value of the record key
cannot be changed.
For ACCESS IS SEQUENTIAL, or files
containing spanned records, the record to
be rewritten must first be read by the
COBOL program.
The REWRITE then updates
the record that was read.
If the REWRITE
is not preceded by a successful READ of the
record to be rewritten, the rewrite is not
done and the status Key is set to 92.
For ACCESS IS RANDOM/DYNAMIC, and for
records that are not spanned, the record
to be rewritten need not be read by the
COBOL program.
TO update a record, the key
of the record to be updated is moved to the
RECORD KEY data-name and then the REWRITE
is issued.
Reviting must always be done by the
primary key. COBOL does, however, allow a
user to change the alternate key contents
while rewriting the record.
READING RECORDS ON A VSAM FILE
The COBOL READ statement is used to
access records on a file.
The file must be
opened INPUT or 1-0; if not 4 the record is
not read and the status Key is set to 92.
REWRITING RECORDS ON A VSAft FILE
The COBOL REWRITE statement is used to
replace an existing record in the file.
The records are read in the sequence in
which they were written.
VSAM File Processing
189
BA!QOK_£!Q~l~~!Hg:
Records are read
randomly according to the value placed in
the record key field.
Records are read sequentially beginning
at the position of the Current Record
Pointer.
If the Current Record Pointer is
not defined at the time the READ is issaed,
the READ fails and the Status Key is set to
94.
.
The Current Record Pointer is unde£ined
if a START is unsuccessful.
For example:
OPEN 1-0 filename
READ
(Set Record Ke y to 10)
START
READ
(Set Record Key to 20)
S'f ART
READ
READ
RE AD
(Set Record Key to 8)
START
READ
CRP set to first
record on file.
First record is
read.
Fails--no record
fOl1nd. SK=23.
Pails--no CRP.
SK = 94.
success ful.
Record 20 is read.
EOP encountered;
SK= 10.
Logic error;SK=92
Successful.
Record 8 is read.
Records are read in the order specified
in the COBOL program. For example, to
readthe record whose Record Key is 10, the
RECORD KEY field must be set to 10 and then
a READ is issued.
1105 Considerations
If a RELATIVE KEY data item was
.specified for a sequential READ, the
relative record number of the record just
read will be placed in the data item.
DELETING RECORDS ON A FILE
The COBOL DELETE statement is used to
remove an existing record on a KSDS.
DELETE cannot be used with an ESDS.
The file must be opened 1-0; if not, the
record is not deleted and the Status Key is
set to 92.
For ACCESS IS SEQUENTIAL, or files
containing spanned records, the record
to be deleted must first be read by the
COBOL program. The DELETE then removes
the record that was read.
If the DELETE
is not preceded by a successful READ of
the record to be deleted, the deletion
is not done and the Status Key is set to
92.
For ACCESS IS RANDOM/DYNAMIC, and for
records that are not spanned, the record
to be deleted need not be read by the
COBOL program. To delete a record, the
key of the recdrd to be deleted is moved
to the RECORD KEY data-name and the
DELETE is issued.
STATUS KEY SETTINGS FOR ACTION REQUESTS
Records can be read sequentially or
randomly.
The READ NEXT statement is used
for sequential accessing while the READ
statement is used for random accessing.
Within any given program, both sequential
and random processing may be performed.
Figure 77 is a summary of the status Key
values that can occur for action requests.
Status Key 92 has numerous possible causes
as described below.
Status Key 92 can be caused by:
• Any request against a file that is not
open.
~!QQENTIAL PRO£!~!]2:
Records are read
sequentially beginning at the position of
the Current Record Pointer. If the Current
Record Pointer is undefined when the READ
NEXT is issued, the record is not read and
the Status Key is set to 94. The Current
Record Pointer is undefined if the previous
START or READ was unsuccessful. See the
discussion of current Record Pointer for
more details and examples of the effect of
different COBOL statements on the
positioning of the Current Record Pointer.
190
• Any request that is not allowed for the
option that vas specified with the OPEN
statement.
For example, an attempt is
made to read a file that was opened as
OUTPUT or an attempt is made to rewrite
on a file opened as INPUT.'
• Any attempt to write or rewrite a
record longer than the maximum record
size specified when the file vas
defined.
• Any attempted action on a file after
the end-of-file conditio n has occurred.
This is applicable to ESDS. BRDS. and
KSDS; however. on an RRDS or KSDS a
START or READ can be issued to set the
Current Record Pointer to another point
in the file so that processing may
continue. For example:
1.
ACCESS IS SEQUENTIAL
OPEN
READ
READ
READ
START
READ
2.
Successful
EOF encountered
Logic error
To reset Current Record
Pointer
Successful
ACCESS IS DYNAMIC
OPEN
READ
READ
READ
NEXT
NEXT
NEXT
successful
EOF encountered
Logic error
READ
READ
NEXT
Random READ to reset
CRP
Successful
• An attempt to revrite, when access is
sequential, after an unsuccessful READ.
• An attempt to delete, when access is
sequential, after an unsuccessful READ.
This applies to KSDS and RRDS only,
since DELETE is not legal for ESDS.
CLOSING A FILE
If the user attempts to close a file
which has already been closed, COBOL
returns a status key value of 92. When
performing a CLOSE request, VSAM itself may
detect an error and return one of the
following codes to COBOL:
132, 144, 164,
176, or 184. COBOL willtrans1-ate this
VSAM code into a STATUS KEY of 30.
VSAM File Processing
191
If the Status either COBOL itself discovered one of these
Key given to conditions ••.
was •••
or VSAM found an
error and returned
one of the following
VSAM error codes·
-----..- - .
02
Permissible duplicate key follows for READ, or
permissible duplicate key is created on one or
more alternate indexes for WRITE or REWRITE.
(This is the case when the feedback field of the
RPL contains 8 but the LERAD exit is not taken.)
10
READ is issued for the first time to an optional
file.
None
4 (if the request
was not START)
Sequential READ is issued to an empty file
opened for INPUT.
21
None
22
None
23
Random READ or START issued to an empty file
opened for INPUT.
Relational operator GREATER THAN was specified
in a START and the key contains HIGH-VALUE.
-_... -
12,96
8
4 (if the request
was START)
16
192
I Current
record pointer failed for sequential
READ because key used in the previous READ
contained HIGH-VALUE.
24
Relative record key contains a value larger
than allowed.
28 (if the file
is not ESDS)
148
30
SYNAD exit taken due to an I/O error.
140
34
None
28 (if the file
is ESDS)
90
Failure of attempt to use a CBMM macro.
32,64,68,72,76,
80,84,104,112,
116,132,136,144,
196,200
(plus any VSAM
codes not
appearing elsewhere in this
table)
*
COBOL's VSAM-processing subroutines retrieve the VSAM return code from the
RPLFDBK field of the Request Parameter List (RPL) , translate it into one
of the status key values above (as prescribed by the ANS standard) , and
move that value into the STATUS KEY field where it becomes accessible in
the user's program. An explanation of the meanings of the VSAM return
codes can be found in the VSAM Programmer's Guide.
Figure 77.
192
(Part 1 of 2) status Key Values for Action Requests
-.---
--1
If the Status either COBOL itself discovered one of these ---~r VSAM found a~
Key given to conditions •••
I;~ror and returned
I
was •.•
one of the following
VSAM error codes*
92
36,44,92,100,
108,152,204
Impermissible request (action does not match
j file's open mode).
I
!File is not open.
IEnd-of-file condition had been raised by the
previous operation, and a sequential READ is
issued, or a REWRITE is issued when access mode
is sequential, or a DELETE is issued and the
access mode is sequential.
Access m6de is sequential, and the last I/O
request for the file (prior to a REWRITE or
DELETE) was not a successful READ.
READ issued to an optional file is not the first
!READ request.
The key value of a record to be added to an
indexed file opened EXTEND is not the highest
among record key values in the file.
93
Insufficient virtual storage for the user
declarative processing.
20,24,40
94
The current record pointer (maintained by
ILBOVIO) is undefined for this sequential READ.
88
* COBOL's VSAM-processing subroutines retrieve the VSAM return code from the
RPLFDBK field of the Request Parameter List (RPL), translate it into one of
the status key values above (as prescribed by the ANS standard), and move
that value into the STATUS KEY field where it becomes accessible in the
user's program. An explanation of the meanings of the VSAM return codes
can be found in the VSAM Programmer's Guide.
Figure 77.
(Part 2 of 2) Status Key Values for Action Requests
functions are performed.
Most significant
to the COBOL programmer is whether the data
set is defined as ESDS, KSDS or RRDS.
The COBOL language statements which are
directly related to VSAM processing are in
the publication IIHLVS COBQ!::_!Q!:_Q~VS.
The following pa.ragraphs a.re intended only
to highlight and summarize the basic
language statements used in writing a
VSAM-file-processing COBOL program.
WRITING A VSAM DATA SET
The COBOL programmer can use VSAM in
three basic ways: to write, to retrieve,
and to update records in a data set.
However, prior to processing a VSAM data
set, it is an absolute necessity that the
previously discussed Access-Method Services
The COBOL language statements frequently
used to fill in a VSAM data set are
summarized in Figure 78. Examples 1 and 2
illustrate the creation of an ESDS and a
KSDS respectively.
VSAM File Processing
193
ESDS
r---------,,Environment I SELECT
J Division J ASSIG N
FILE STATUS
J
•I PASSWORD
t
J ACCESS MODE
I
J
I
,
J
J
J
I
I
J
I
lJ Data
Division
i
I--
I
1 FD entry
J LABEL RECORDS
I
JProcedure
I OPEN OUTPUT
J Division t OPEN EXTEND
I
1 WRITE
JL-_ _ _ _ _ _ - -I' - CLOSE
Figure 78.
KSDS
RRDS
-,--SELECT
I SELECT
J
ASSIGN
t ASSIGN
I
ORGANIZATION
f ORGANIZATION f
IS INDEXED I
IS RELATIVE)
RECORD KEY
J RELATIVE KEY I
ALTERNATE
I FILE STATUS J
RECORD KEY I
I
FILE STATUS
I
J PASSWORD
PASSWORD
I
I ACCESS MODE
ACCESS MODE
J
I
,
-+-
1
]
FD entry
J FD entry
LABEL RECORDS f LABEL RECORDS J
OPEN OUTPUT
OPEN EXTE.ND
WRITE
CLOSE
-+-OPEN
J
OUTPUT
J WRITE
I CLOSE
I
-'--
-t
I
J
I
I
I
COBOL st atements Frequently Used for Wri ting into a VSAM Data set
Example 1:
This example shows the creation of a
COBOL ESDS. The PILE STATUS facility is
used to monitor all 1/0 operations in the
program.
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FI LE-CONTROL.
SE.LECT I NREC
ASSIGN TO UR-2540R-S-INFILE.
SELECT OUTREC
ASSIGN TO AS-OUTFILE
FILE STATUS IS CHK.
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.
STOP RUN.
CHKRTN.
DI SPLAY • I/O 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 usercreated 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.
Example 2:
DATA DIVISION.
FILE SECTION.
PO INREC LABEL RECORDS ARE OMITTED
DATA RECORD IS INMASTER.
01
INMASTER PIC X(80).
FD OUTREC LABEL RECORDS ARE STANDARD
DATA RECORD IS OUTMASTER.
01
OUTMASTER PIC X(80).
WORKING-STORAGE SECTION.
77
CHK PIC 99 VALUE ZEROS.
PROCEDURE DIVISION.
PARA 1.
OPEN INPUT INREC OUTPUT OUTREC.
IF CHK IS NOT = 00 GO TO CHKRTN.
PARA2.
READ INREC INTO OUTKASTER
AT END GO TO PARA4.
194
This example shows the creation of a
COBOL KSDS; this program performs the same
function as Example 1 except that now a
KSDS is being created.
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT IHREC
ASSIGN TO UR-2540R-S-INFILE.
SELECT OUTREC
ASSIGN TO DA-2319-0UTFILE
ORGANIZATION IS INDEXED
RECORD KEY IS ARG-1
FILE STATUS IS CHK.
DATA DIVISION.
FILE SECTION.
FD
INREC LABEL RECORDS ARE OMITTED
DATA RECORD IS INMASTER.
01
INKASTER PIC X (80) •
PO OUTREC LABEL RECORDS ARE STANDARD
DATA RECORD IS OUTMASTER.
01
OUTMASTER.
05 FILLER PIC X.
05
ABG-1
PIC XXX.
05 REM PIC X(76).
WORKING-STORAGE SECTION
77 CBK PIC 99 VALUE ZERO.
PROCEDURE DIVISION.
PARA1.
OPEN INPUT INREC OUTPUT OUTREC.
IF CHK IS NOT = 00 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 CllK IS NOT = 00 GO TO CHKRTN.
FINIT.
STOP RUN.
CHKRTN.
DISPLAY 'I/O EBROR. 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 usercreated routine can determine the exact
cause of the I/O er~or by checking the
Status Key.
Once the cause is determined r
instructions can be issued according to the
user's desired response to each type of
error.
Example 3:
This example also shows the creation of
a COBOL KSDS, but with the addition 6f an
alternate key; this program serves the same
function as Example 2.
IDENTIFICATION DIVISION.
FILE-CONTROL.
SELECT I.NREC
ASSIGN TO UR-2540R-S-INFILE.
SELECT OUTREC
ASSIGN TO DA-2319-00TFILE
ORGANIZATION IS INDEXED
RECORD KEY IS ARG-1
ALTERNATE RECORD KEY IS ARG-2
FILE S~ATUS IS CHK.
DATA DIVISION.
FILE SECT.ION.
FD INREC LABEL RECORDS ARE OMITTED
DATA RECORD IS IN~ASTER.
01
INMASTER PIC 1(80).
PO OUTREC LABEL RECORDS ARE STANDARD
DATA RECORD IS OUTMASTER.
01 OUTMASTER.
05 FILLER PIC X.
05 ARG-1
PIC XXX.
05 ARG-2
PIC XXXXX.
05 REM PIC Xn1).
WORKING-STORAGE SECTION
77 CHK PIC 99 VALUE ZERO.
PROCEDURE DIVISION.
PARA 1.
OPEN INPUT INREe OUTPUT QUTREC.
IF CHK IS NOT
00 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 OOTREC.
IF CHK IS NOT = 00 GO TO CHKFTN.
PINIT.
STOP RUN.
CHKRTN.
DISPLAY 'I/O 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
user-created routine can determine the
exact cause of the error by checking the
status Key.
Once the cause is determined,
instructions can he issued according to the
user's desired response to each type of
error.
RETRIEVING RECORDS PROM A VSAM DATA SET
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
The COBOL language statements frequently
used to retrieve records from a VSAM data
set are summarized in Fiqure 79.
Examples
3 and 4 illustrate the retrieval of records
from an ESDS and KSDS, respectively.
VSAM File Processing
195
ESDS
RRDS
,
SELECT
ASSIGN
ORGANIZATION IS INDEXED
RELATIVE KEY
ALTERNATE RECORD KEY
FILE STATUS
PASSWORD
ACCESS riODE
I
I
I
I
I
I
I
I
KSDS
r
~--------
I Environment
I
Division
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
SELECT
ASSIGN
FILE STATUS
PASSWORD
ACCESS MODE
SEI,ECT
ASSIGN
ORGANIZATION IS INDEXED
RECORD KEY
ALTERNATE RECORD KEY
FILE STATUS
PASSWORD
I
ACCESS MODE
l---------+--------+------
+-------
I Da ta
I FD entry
I FD entry
I FD entry
I LABEL RECORDS
I
Division I LABEL RECORDS I LABEL RECORDS
I
~
I
--+I OPEN INPUT
I Procedure
I OPEN INPUT
I OPEN INPUT
I
Division I READ ••• AT END I READ
I READ
ILI ____________
CLOSE
I _
CLOSE
I _ CLOSE
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _L
~
Figure 79.
~
This example shows the retrieval of
records from the ESDS created in example 1.
The records are then printed.
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT I NREC
ASSIGN TO AS-OUTFILE
FILE STATUS IS CHK.
SELECT PREC
ASSIGN TO UR-1403-S-PFILE.
DIVISION.
PI LE SECTION.
FD INRBC LABEL RECORDS ARE STANDARD
DATA RECORD IS INMASTER.
01 INMASTER PIC X(80).
FD PREC LABEL RECORDS ARE OMITTED
DATA RECORD IS POUT.
a1 POUT PIC X (80) •
WORKING-STORAGE SECTION.
77 CHK PIC 99 VALUE ZERO.
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 PAPA2.
PARA4.
CLOSE OUTREC PREC.
196
I
I
--t
I
I
JI
COBOL Statements Frequently Used for Retrieving Records From a VSAM Data Set
Example 4.
DllTA
~
IF CHK IS NOT
00 GO TO CHKRTN.
FIN IT.
S!'OP RUN.
CHKRTN.
DISPLAY 'IIO 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 usercreated 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.
Example 5:
This example shows the retrieval of
records from the KSDS 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 DYNAMIC is specified in the
Environment Division.
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT INREC
ASSIGN TO OUTFILE
ORGANIZATION IS INDEXED
ACCESS IS DYNAMIC
RECORD KEY IS ARG-1
FILE STATUS IS CHK.
SELECT PREC
ASSIGN TO UR-1403-S-PFILE.
IDENTIFICATION DIVISION.
DATA DIVISION.
FILE SECTION.
FD INREC LABEL RECOPDS ARE STANDARD
DATA RECORD IS INMASTER.
01 INMASTER.
05
FILLER PIC x.
05
ARG-1
PIC XXX.
05
ARG-2 PIC XX.
as
ARG-3 PIC XX.
as
FILLER PIC X(72).
FD PREC LABEL RECORDS ARE OMITTED
DATA RECORD IS POUT.
a 1 POUT PIC X (80) •
WORKING-STORAGE SECTION.
77 CHK PIC 99 VAL UE ZERO.
PROCEDURE DIVISION.
PARA1.
OPEN INPUT INREC OUTPUT PREC.
IF CHK IS NOT = 00 GO TO CHKRTN.
PARA2.
MOVE 003 TO ARG-1.
START INREC.
PARA3.
READ INREC NEXT AT END GO TO PARA4.
IF CHK IS NOT = 00 GO TO CEKRTN.
IF ARG-2 IS = 02 GO TO PARA4.
IF ARG-3 IS NOT = 73 GO TO PARA3.
WRITE POUT FROM INMASTER.
GO TO PARA3.
PARA4.
MOVE 101 TO ARG-1.
READ INREC INVALID KEY GO TO CHKRTN.
WRITE POUT FROM INMASTER.
MOVE 103 TO ARG-1.
READ INREC INVALID KEY GO TO CHKRTN.
WRITE POUT FROM INMASTER.
PARAS.
CLOSE INREC PREC.
IF CHK IS NOT = 00 GO TO CHKRTN.
FINIT.
STOP RUN.
CHKR TN.
DISPLAY 'I/O 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 user
created routine can determine the exact
cause of the I/O error by checking the
Status Key.
Once the cause is determined,
instructions can be issued according to the
users desired response to each type of
error.
Example 6:
This example shows the retrieval of
records from the KSDS created in example 3.
Since ACCESS IS RANDOM is specified in the
Environment Division, random processing of
the file is done in the Procedure Division.
ENVIRONMENT DIVISION
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT INREC
ASSIGN TO OUTFILE
ORGANIZATION IS INDEXED
ACCESS IS RANDOM
RECORD KEY IS ARG-1
ALTERNATE RECORD KEY IS ARG-2
FILE STATUS IS CHK.
SELECT PREC
ASSIGN TO UR-1403-S-PFILE.
DATA DIVISION.
FILE SECTION.
FD INREC LABEL RECORDS ARE S~ANDARD
DATA RECORD IS INMASTER.
01 INMASTER.
05
FILLER PIC X.
05
ARG1
PIC XXX.
05
ARG-2 PIC xxxxx.
05
ARG-3 PIC XX.
05
ARG-4 PIC XX.
05
FILLER PIC X(67).
FD PREe LABEL RECORDS ARE OMITTED
QATA RECORD IS POUT.
01 POUT PIC X(80).
WORKING-STORAGE SECTION.
77 CHK PIC 99 VALUE ZERO.
PROCEDURE DIVISION.
PARA 1.
-- -OPEN INPUT INREC OUTPUT PFEC.
IF CHK IS NOT = 00 GO TO CHKP.TN.
PARA2.
MOVE 003 TO ARG-1.
PARA3.
READ INREC INVALID KEY GO TO CHKRTN.
IF CHK IS NOT
00 GO TO CHKRTN.
IF ARG-3 IS = 02 GO TO PARAS.
IF ARG-4 IS NOT = 73 GO TO PARA4.
WRITE POUT FROM INMASTER.
ADD 010 TO ARG-1.
GO TO PARA3.
PARA4.
SUBTRACT 001 FROM ARG-1.
GO TO PARA3.
PARAS.
MOVE 101 TO ARG-2.
READ INREC KEY IS ARG-2 INVALID KEY
GO TO CHKR TN.
WRITE POUT FROM INMASTER.
MOVE 103 TO ARG-2.
READ INREC KEY IS AP.G-2 INVALID KEY
GO TO CHKRTN.
WRITE POUT FROM INMASTER.
PARA6.
CLOSE INREC PREC.
IF CHK IS NOT = 00 GO TO CHKRTN.
FINIT.
=
VSAM File Processing
197
STOP RUN.
CHKRTN.
user's desired response to each type of
error.
DISPLAY 'IIO ERROR. STATUS KEY VALUE
IS ' CHK.
GO TO FINIT.
UPDATING A VSAM DATA SET
Note that in this example any Status Key
return other than 00 causes transfer of
control to paragraph CHKRTN.
This user
created routine can determine the exact
cause of the IIO error by checking the
Status Key. Once the cause is determined,
instructions can be issued according to the
198
The COBOL language statements frequently
used to update a VSAM data set are
summarized in Figure 80. Examples 7 and 8
illustrate the updating of an ESDS and KSDS
respectively.
ESDS
RRDS
KSDS
•
i
,
IEnvironment
I Division
I
•
I
I
(SELECT
IASSIGN
IFILE STATUS
I PASSWORD
IACCESS ~ODE
I
,
t
J
I
,SELECT
,ASSIGN
,ORGANIZATION IS INDEXED
I RECORD KEY
I ALTERNATE RECORD KEY
JFILE STATUS
JPASSWORD
IACCESS MODE
r----------~I~------------+I----------·------
,
,
,SELECT
IASSIGN
10RGANIZATION IS RELATIVE
I RELATIVE KEY
1FILE STATUS
IPASSWORD
,ACCESS MODE
I
I
I
I
I
I
,
I
I
+-
~
I Data
J FD en try
I PD entry
I FD en try
I
I Division
ILABEL RECORDSJLABEL RECORDS
JLABEL RECORDS
t
t- ------+-1-+
I
~
I Procedure
IOPEN EXTEND
,For ACCESS IS SEQUENTIAL: ,For ACCESS IS SEQUENTIAL:
t
I Division
IWRITE
J
OPEN EXTEND
I OPEN 1-0
I
I
I CLOSE
J
WRITE
I
READ •• AT END
t
,
I
J
CLOSE
J REWRITE
I
I
I
or
1
t DELETE
J
I
I I
o r t CLOSE
J
I
,OPEN 1-0
I
t
f
I
J READ ••• AT END 1
OPE.N 1-0
I
I
J
I REWRITE
I
READ
AT END
t
1
I
I
I
BEWRITE,
,
1
1CLOSE
I
DELETE
t
J
I
I
CLOSE·
I
t
I '
I
~
I
IFor ACCESS IS RANDOM:
IFor ACCESS IS RANDOM:
t
I
f
OPEN 1-0
,
OPEN 1-0
,
t
I
READ
I
R~AD
,
I
I
W·RITE
,
WRITE
I
,
J
REWRITE
,
REWRITE
t
I
I
DELETE
I DELETE
1
I
J
CLOSE
I CLOSE
I
I
I
,
~
I
,For ACCESS IS DYNAMIC vithlFor ACCESS IS DYNAMIC with
I
I
,Sequentili-froce§§.!!!g
l~gY~ntial_R..r~gssillil
I
I
I
OPEN 1-0
t OPEN 1-0
I
1
I
READ NEXT ••• AT END
J READ NEXT ••• AT END
,
I
I
WRITE
t WRITE
1
•
,
REWR IT E )
REWRITE
1
J
J
START
•
START
J
J
t
DELRTE
,
DELETE
t
I
1
CLOSE
t CLOSE
I
J
I
--+--~
I
JFor ACCESS IS DYNAMIC withlFor ACCESS IS DYNAMIC with
1
1
I Random processing
I Bando.!!_.P ro9Z.§.§ing
1
I
I
OPEN 1-0
J OPEN 1-0
I
I
J
READ
1 READ
I
,
1
WRITE
,
WRITE
,
I
,REWRITE
t REWRITE
,
,
J
DELET.E
J DELETE
t
1
CLOSE
, _____________________________
CLOSE
L-___________,___ I
_JJ
~,__________,
Figure 80.
~
COBOL statements .Frequently used for Updating a VSAl'1 Data set
VSAM Pile Processing
199
Example 7:
This example shows the updating of
records from the ESDS data set created in
Example 1.
IDENTIFICATION DIVISION.
Example 8:
This example shows the updating of
selected records in the KSDS created in
Example 2; the records to be updated by the
contents of CARDPILE. Note the use of the
DELETE statement; this could not be used
with an ESDS.
IDENTIFICATION DIVISION.
ENVIRONMENT DIVISION.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT INREC
ASSIGN TO AS-OUTFILE
FILE ST ATUS IS CHK.
DATA DIVISION.
FILE SECTION.
FD INREC LABEL RECORDS ARE STANDARD
DATA RECORD IS INMASTER.
01
INMASTER.
05 FtD1 PCI X(3)
05 FLD2 PIC X(3).
05 FLD3 PIC X(74).
WORKING-STORAGE SECTION.
77 CHK PIC 99 VALUE ZERO.
PROCEDURE Dr VISION.
PARA1.
OPEN 1-0 OUTREC.
IF CHK IS NOT = 00 GO TO CHKRTN.
PARA2.
READ TNREC AT END GO TO PARA4.
IF CHK IS NOT = 00 GO TO CHKRTN.
PAR A3.
IF FLD2 IS NOT: 373 GO TO PARA2.
MOVE 374 TO FLD2.
REWRITE INMASTER.
IF CHK IS NOT: 00 GO TO CHKRTN.
GO TO PA RA2.
PARA4.
CLOS E IN REC.
IF CHK IS NOT
00 GO TO CHKRTN.
PI NIT.
STOP RUN.
CHKRTN.
DISPLAY tI-O 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 llsercreated routine can determine the exact
cause of the I/O error by checking the
Status Key. Once the cause is determined,
instructions can be issued according to the
users desired response to each type of
error.
200
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT CAR.DFILE
ASS.IGN TO UR-2540R-S-INREC.
SELECT INREC
ASSIGN TO INlItE
ORGANIZATION IS INDEXED
ACCESS IS RANDOM
RECORD KEY IS ARG-l
FILE STATUS IS CHK
DATA DIVISION.
FILE SECTION.
PD CARDFILE LABEL RECORD IS OMITTED
DATA RECORD IS INCARD.
01
INCARD
05 CARDKEY PIC XXX.
05
FILLER PIC X (77) •
PD INREC LABEL RECORDS ARE STANDARD
DATA RECORD IS .INMASTER.
01 IN MASTER.
05FILLEB PIC X.
05
ARG-l PIC XXX.
05
ARG-2 PIC XX.
05 ARG-3 PIC XX.
05 FILL.ER PIC X (72) •
WORKING-STORAGE SECTION.
77 CHK PIC XX VALUE ZEROS.
PROCEDURE DIVISION.
PARA 1.
OPEN INPUT CARDFILE 1-0 INBEC.
IF CHK IS NOT == 00 GO TO CHKRTN.
PARA2.
READ CARDFILE AT END GO TO PARA3.
MOVE CARDKEY TO ARG-l.
READ INREC.
IF CHK IS NOT = 00 GO TO CHKRTN.
IF ARG-2= 01 DELETE INREC RECORD
GO TO PARA2.
IF ARG-3 : 75 MOVE 74 TO ARG-3
REWRITE INMASTER.
GO TO PARA2
PARA3.
CLOSE CARDFILE lNREC.
IF CHK IS NOT = 00 GO TO CHKRTN.
INIT.
STOP RUN.
HKRTN.
DISPLAY ·1/0 ERROR. STATUS KEY
VALUE IS· CHK
'LAST RECORD PROCESSED IS' CARDKEY.
GO TO PI NIT.
lote that in this example any status Key
'eturn other than 00 causes transfer of
:ontrol to paragraph CHKRTN. This user:reated routine can determine the exact
:a use of t he I/O error by checking the
;tatus Key. Once the cause is determined,
.nstr~ctions can be issued according to the
lsers desired response to each type of
~rror.
of the first alternate record key defined
would have to be ABCD1. The ddname for the
alternate path of the second alternate record
key defined would have to be ABCD2, and so on.
If the combination of base cluster ddname
and sequence number exceeds eight characters,
the base cluster portion of the ddname must be
truncated at the right to reduce the concatenated
result to eight characters. For example, if a
base cluster's ddname is ABeDEFGH, then the first
alternate path's ddname should be ABCDEFG1, the
tenth should be ABCDEF10, and so forth.
The following example shows the connection
between a program using two alternate indexes
and the required DD statements. The base
cluster is named XYZ, and the first alternate
index' pathname is PATHONE and the other's
PATHTWO.
~R.QCESSI!Hi
//ABCD
//ABCD1
//ABCD2
JCL is greatly simplified for VSAft since
ill VSAM data sets must be cataloged
through Access Method services. In most
=ases~ specification of the following DD
statement will suffice:
FILE-CONTROL.
SELECT filename ASSIGN TO ABCD
RECORD KEY IS whatever
ALTERNATE RECORD KEY IS CITY
ALTERNATE RECORD KEY IS PRICE
I/ddname
The key CITY relates to the alternate index
whose pathname is PATHONE, and the key PRICE
relates to the alternate index whose pathname
is PATHTWO.
lOB CONT ROL L ANGU AGE
DD
FO!i_.!~!t1.111.~
DSNAME=dsname,DISP={OLDISHR)
The dsname must be the same as the one
specified for this data set through Access
Method Services.
If the user specifies the COBOL option
AIXBLD, then the DD statement must also
include the parameter AMP='AHORG'.
DD STATEMENTS FOR ALTERNATE INDEXES
When alternate indexes are used in
the COBOL program, the user must specify
not only a DD statement for the base
cluster, but also one DD statement for each
alternate path. The ddname for the base
cluster is the one declared in the COBOL
program. However, no language mechanism
exists to explicitly declare ddnames for
alternate paths in the program. Therefore,
the following convention has been established and must be adhered to by the user.
The ddname for each alternate path is to
be formed by concatenating its base cluster
ddname with an integer--beginning with'1 for
the path associated with the first alternate
record defined for that file in the COBOL
program, and being incremented by 1 for
each path associated with each successive
alternate record definition for that file.
For example, if a base cluster's· ddname were
ABCD, then the ddname for the alternate path
DD
DD
DD
DSN=XYZ,DISP=OLD
DSN=PATHONE,DISP=OLD
DSN=PATHTWO,DISP=OLD
DO STATEMENT FOR A USER CATALOG
If a data set in a job step is defined
in a user catalog, it is also necessary to
identi£y the user catalog by means of
either a JOBCAT (Example 1) or STEPCAT
(Example 2) DO statement.
Example 1:
//EX1
/IJOBCAT
JOB
·DD
/1
EXEC
DSNAME=usercatalogname,
OISP=SHR
Example 2:
//EX2
JOB
EXEC
//STEPCAT DD
1/
DSNAME=usercatalogname,
OISP=SHR
DD PARAMETERS USED WITH VSAM
Although the operating system does not
disallow OS/VS DD parameters and
subparameters that do not apply to a VSAM
data set, the COBOL programmer should be
VSAM File Processing
201
aware that some of the DD parameters and
subparameters have certain additional
meanings when used with V5AM. For complete
information on the meanings of the OS/VS DD
parameters and subparameters, as well as
the potential problems which exist if care
is not taken, see Q.UVS-li!:lj!s.!2!.QIaiH~
AC£~~_Metho~'VSA~L_f!oqrs.m~~~_~ig~.
the IS AM interface.
For complete details
on the conversion process, see the VSAM
.EtQ9.11n~.!.2.£Y.i de.
Not all of VSAM's facilities can be used
directly through a COBOL program.
These
unavailable features include:
VSAM-ONLY JCt PARAMETERS
• Alternate indexing for ESDS
VSAM has one JCt parameter of its ovn:
AMP.
AMP, and its associated
subparameters, is used mainly in
conjunction with specifications made
through Access Method Services. The AMP
parameter takes effect when the data set
defined by the nn statement is opened.
For
details on the use and specification of
AMP, see the YllLP r OSll:gj!l!~~!..!L2.YiQg.
• Multiple string processing
• Skip-sequential processing (key-ordered
sequential/direct)
• Addressed-direct processing
• Control-interval (low-level) processing
• Journaling support
• Alternate index as end-use object (as
base cluster instead of path)
processing
Both SAM and 15AM data sets can be
converted to VSAM data sets so that they
may be processed by a COBOL program using
VSAM.
The conversion is done through
Access Method Services.
Essentially, the conversion process
consists of defining a VSAM data set as the
target for the data set being converted.
Then through the appropriate Jct and the
REPRO command, the conversion is
accomplished.
For a complete description of the
conversion process, see OSIIS VSAM Access
l1~.t!lod Servi£!!§..
Existing COBOL programs written to
process 1SAft files can be used to process
VSAM files by going through VSUI's ISAM
interface. To do this, the programmer need
only make some JCL changes in the COBOL
ISAM program.
The EXEC card should specify the desired
processing program, as usual: the DD card
should be changed to a VSAM DD card as
desc.ribed above under "Job Control Language
for VSAM File Processing."
Certain APlP subparameters might be used
for running an ISAa processing program with
202
• GET-previous processing
• Asynchronous processing
It is possible to open a VSAM data
set concurrently under two separate
FDs in a COBOL program if the assign
clauses of the SELECT.statements
refer to the same DDNAME. When the
ACB is generated, COBOL takes the
GENCB default of 'DDN', which indicates
DDNAME sharing to VSAM.
In such a
case, VSAM will share the same buffers
and control blocks for the two ACBs,
and data integrity is preserved.
If the user program attempts to access
records within the same control
interval by using the two separate
file definitions, lock-out may occur.
If the program contains two SELECT
statements for the file but uses
different DDNAMEs, the file can still
be opened. However, data set names
are not shared, and VSAM will use
two completely separate buffer pools
and control block structures.
In
this case, the integrity of the data
set is not preserved, and updates
to the file may be lost.
Note. Even when the spanned format is
used, the COBOL restriction on the length
of logical records must be adhered to
(that is, a maximum length of 32,767
characters) .
The lister feature of the IBM OS/VS
COBOL Compiler can be used by the COBOL
programmer to produce a COBOL source
listing that is reformatted and
cross-referenced to increase
intelligibility and conserve space.
optionally, a reformatted source deck can
be produced. The lister output can be
produced either with or without compilation
occurring.
The lister accepts source programs
vritten in OS/'S COBOL, analyzes the source
statements, and produces the reformatted
and cross-reference source program. The
output is either in the form of a listing
or as a listing and a punched deck.
This reformatted source output follows
indenting conventions imposed by the lister
to increase readability, and contains
cross-references between data items and
Procedure Division statements, between
PERFORM statements and paragraph names,
etc. optionally, the lister produces a new
source deck that matches the output listing
except that cross-reference information is
ollit ted.
Thus the lister can be used to p.rocess
sourCe decks for uniformity of indenting
and for highlighting of statements such as
IF, GOTO, etc., or it can be used to obtain
a cross-referenced source listing as
permanent documentation of a production
program, or for use as an aid in program
analysis and debugging. Various options
permit printing the Procedure Division
listing in two columns to conserve space
and the inclusion of BASIS and COpy
statements.
programs first be compiled using the SYNTAX
option, and syntax errors corrected before
invoking the lister feature. If the lister
function is used and there are syntactical
errors, lister processing will be
terminated. The syntax check~ng in the
lister feature is different from the
checking done by the standard compiler.
Syntax checking is usually more stringent
in the lister than in the compiler. Some
syntax errors that are recognized but
corrected by the standard compiler may be
flagged as errors when using the lister.
The listing produced by LISTER will be
reformatted for that portion of the
program that was syntactically correct.
If LSTCOMP was specified, the SOURCE
option will be forced on.
Since lister reformats the
user's COBOL program, compilation of the
program, if LSTCOMP is in effect, viII be
different from a non-lister compilation of
the same program. Por example:
lurthe~_nQ~2:
1.
different~
2.
SKIP/EJECT cards will have no
functional value with lister.
3.
BASIS card will be dropped from the
lister listings.
4.
FIPS messages will be based on the
reformatted lister listings.
5.
Suppress option of COpy will ha ve no
effect.
6.
sequence checking will not take place
for a lister sum.
7.
Source statements copied from a
user-created library as a result of a
COpy statement are not reformatted.
However, statements which begin in
columns 8-11 will be indented to
column 8 in the lister output, and
those which begin in columns 12-72
will be indented to column 12.
8.
Lister terminates upon detecting a
syntax error in the COBOL source
program. When such an error is
detected, lister issues an error flag
to signal that the following source
cards are to be passed on without
processing. Lister then treats the
balance of the program as comment
cards.
!21~:
Lister ignores the carriage
control statements SKIP and EJECT. When
LISTER is in effect, the NUM option has no
meaning.
PROGRAMMING CONSIDERATIONS
The lister is designed to operate most
efficiently on syntactically correct COBOL
source, and does not have the expanded
error handling of the full compiler. It is
therefore highly recommended that the user
Lister sequence numbers may be
Lister Feature
203
In addition to the condition mentioned
above, unusual termination of lister can
occur if the source program contains:
THE LISTING
The reformatted output listing is
divided into four parts:
•
Too many (approximately 80 or
more) consecutive *-comments
cards.
1.
lone-page introduction.hich
summarizes briefly lister codes,
conventions, uses.
2.
The Identification and Environment
Divisions.
Too many (approximately 100 or
more) consecutive cards for a
single data item.
3.
Detailed, cross-referenced,
reformatted Data and Procedure
Divisions.
If one of the above three conditions
occurs, the file written on SYSUT2 is
incomplete.
4.
The Summary listing.
•
•
Too many (approximately 100 or
more) consecutive blank cards.
204
These (except the introduction) are
described briefly below, and in grea"ter
detail in subsequent sections.
Figure 81 is an example of reformatted
Identification and Environment Divisions.
(The note shown is not produced by the
lister program.)
THE OUTPUT DECK
DATA DIVISION REFORMATTING
The deck produced optionall y by the
lister may be saved either in card form or
in a COPY/BASIS library. This output
reflects the reformatted source program.
The output deck is described in detail
later in this chapter.
REFORMATTING OF IDENTIFICATION AND
ENVIRONMENT DIVISIONS
The lister reformats the Identification
Division statements only by imposing
indenting conventions. Statements are
indented two positions, and continuations,
if any, are indented six additional
positions.
Environment Division statements are
reformatted by imposing indenting
conventions and by appending
cross-reference information to SELECT
statements in the FILE CONTROL section.
Thus, in reading the FILE CONTROL section,
there are direct references to the file
description statements in tbe Data
Division.
The lister reformats the Data Division
principally by imposing indenting
conventions. In addition, it aligns
PICTURE. VALUE and other clauses vertically
to improve readability and facilitate
visual checking. such clauses as REDEFINES
and OCCURS are highlighted as a result of
the alignment. All indenting is with
respect to the left margin, which con tans
the statement number.
FDs and level-77 items are indented
zero, level-01 items are indented two and
level-02 items are indented four. Level 03
and lover are each indented two from the
last higher level item, up to seven levels
of indentation. Use of this convention,
makes the overall structure of each file
and group data item immediately apparent to
the reader of the listing.
The most striking change in the
appearance for the Data Division listing is
1 IDENTlf!CATION DIVISION.
PROGRAM-ID. TESTRUN.
2
3
AUTHOK. PROGRAMMER NAM~.
4
INSTALLATION. NEW YORK PROGRAMMING CENTER.
5
DATE-MRITTEN. JULY 1Z, 19b8.
R:~iRk~~PI~~~·p:g~Ri~'~XI6BEEN WRITTEN AS A SAMPLE PROGRAM FOR
COBOL USERS. IT ~REATES"AN OUTPUT fiLE AND READS IT BACK
AS INPUT.
10 ENVIRON~~NT DIVISICN.
11 CONFIGUkATION SECTION.
1Z
SOURCe-COMPUTER. 18M-3/0-168.
13
OBJECT-COMPUTER. IBM-310-168.
14 INPUT-OuTPUT SECTION.
'
15
fiLE-CONTROL.
16
SEU:CT A~!~tN1TO UT-Z ... OO-S-SAMPLE.
11
SELeCT fILE-Z
ASSIGN TO UT-Z ... OO-S-SAHPLE.
9
1}
229
CD
Note:
CI)
Refers to FD statement numbers in the Data Division.
P'iqure 81.
Sa1lple Identification and En vironBlen t Division Outpu tListing
Lister Feature
204.1
the addition, at the right of each
statement, of cross-references that
identify the statement number of each Data
Division or Procedure Division statement
that redefines, changes, reads, tests, or
otherwise refers to the data item. When
the number of such refe.rences is too great
to fit on the line, the lister prints as
many as there are room for, on the line,
and prints the remainder as a footnote at
the bottom of the page.
D
Data item changed by REDEFINE or RENA"E
Q
Queried by IF, WHEN, or UNTIL
.R
Referred to by a READ, ACCEPT, or
similar statement
u
Da ta i tea unchanged (used as a source
field)
The eight codes used in the Data
Division are:
W
Referred to by a WRITE, GENERATE,
DISPLAY, or similar statement
c
Data item changed (such as by ADD or
MOVE)
x
Used as an index, subscript, or object
of a DEPENDING ON statement
E
Data i tea refe.rred to by Env ironment
Division statement (SELECT) or by some
Procedure Division input/output
operation (OPEN, CLOSE, INITIATE, etc.)
Use of these codes is depicted in Figure
82, which is an example of a reformatted
Data Division.
(The notes shown in the
figure are not produced by the lister.)
Lister Feature
205
18 DATA DIVISION.
20 FILE SECTION.
FD FILc-l
LABEL RECORDS ARE uMlTTED
BLOC K CONT AI NS 5 Rc:CORDS
ReCORD CONTAINS 2u CHARACTERS
R~CORDING MaCE IS r
DATA RECORD IS RECuRD-I.
01 ReCORD-I.
02 FlfLD-A
\28
PICTURE IS X(20).
2<; FD FILc:-2
LABEL RECORDS ARE uMITTED
S,-OCK CONTAI fl.S 5 ReCORDS
ReCORD CONTAINS 20 CHARACTERS
ReCORDING MOCE IS f
DATA RECORD IS RECuRD-2.
35
01 RcCORD-2.
36
02 FIELD-A
PICTURE IS X(20).
37 WORKING-STORAGE SECTION.
38 11 KOUNT
SVNE
PI~TUR~ S99
COMPo
63C ,61C ,69X, llX, 17Q
~g ~r ~Y~f~~.
SVN
PI TUR S99
COMPo
63C,68C,12U
4l
02 ALPHABET PICTURE Xl26J VALUE "ABCDEFGHIJKLHNOPQRSTUVWXVZ".
420
42
02 ALPHA REDEFINES AL~HABET OCCURS 26 TIMES PICTURE X.
41/69U
43
02 D~PENDENTS
PIC A(ZOJ VALUE "01234012340123401234012340-. 440
44
02 DePEND REDEFINES DePENDENTS OCCURS 26 TIMES PICTURE X. ~43111U
45 01 WGRK-RECORD.
5
74W,75W,86R,91W
05 NAME-fIELD
PICTURE X.
69C
46
47
05 FILlER
PICTURE X
VALUE IS SPACE.
48
05 R~CORD-NO
PICTURE 9999.
72C
4
4<;
05 FlLLER
PICTURE X
VALUE IS SPACE.
50
05 LuCATION
PICTURE AAA
VALUE IS "NYC".
!1
05 FILLER
PICTURE X
VALUE SPACE.
!2
05 Nu-Of-DEPENDENTS
PICTURE XX.
11C,~9Q,90C
~~ 0105REE~~~i~
PICTURE X(1)
VALUE ~S SPACES.
55
02 A
PICTURE S9(4)
VALUE 1234.
560
56
02 B REDEFINES A
PICTURE S9(7)
CDHPUTATIONAL-3. 5517(C,10U
rI::
--5 A
42
41
50
58
107
1~0
ALPhA
AlPHADE:T
8
8EGIN
CfBUG-CONTENTS
OEBUG-I TEM
OEtlUG-LlNE
Di:BUG-NAME
OEBUG-l>UB-l
CE8UG-SUB-2
CEBUG-SUB-3
OEPENu
OEPENuENTS
FIElO-A
FIElO-A
FIlE-~
FIlE-..
KCUNT
lABl:l-RETURN
lDCATlON
MORE-LABELS
NAME-rl ElO
No-OF-uEPENOENTS
CURREI~T-DATE:
III
H2
113
lJ.4
115
110
't't
43
28
~6
21
.i.9
.,Il
lui
50
99
40
j2
~9
'>8
48
.j5
;)4
luO
103
lu4
100
lu5
1.12
~(MeEK
PRINT-l>WITCH
RECORu-NO
RECORu-2
RECORuA
Rf TURI~-COOt:
SORT-~.uRE-SIZE
SORT-rilE-SIZE
SOj(T-rtt:SSAGE
SOkT-MuOt-SIZE
SCRT-"I:TURN
STi:P-.1.
STEP-,
STEP-.;j
STEP-4
STEP-;,
STEP-o
STEP-I
STEP-o
TAllY
T IME-uF-OAY
WHEN-~uMPllEO
WORK-Kt:CORO
'-7 RECOR ... -l
01
06
73
16
80
05
&8
'.13
91
108
11.;9
45
The INPUT-0UTPUT ~ection contains references to one data item
in F'ILF-1 a!lrl one nata item in F'II.E-::>.
F'ILF.-1 i~ referencE'c1 once from th" INPtTT-0lJ"'PUT sectiC"ln ann three
times from the Procer'!ure Division.
The Procedure Division contains four intra rE'ferences.
Figure 84.
Sample Summary Listing
Lister FeatUre
209
THE SOORCE LISTING
• Verbs
• EL.SE/OTHERWISE
The source listing 'of the
Identification, Environment, and Data
Divisions ma y be considered as having three
"columns." The leftmost contains a
statement number, or is blank if the line
is either a comment or a continuation of
the preceding statement or line. The
second contains the reformatted COBOL
statements. The third (not present as an
independent column in the Procedure
Division) contains references to 9r from
other statements in the source program.
Thus, each line of the output listing
contains a numbered source statement or its
unnumbered continuation, and a reference or
series of references to all other
statements in t.he source proqrall that refer
to it. If the series of references is too
long to fit on the line, the lister prin·ts
as many as viII fit, followed by a letter
indicating a footnote.
The footnote
contains the remainder of the references.
• AT END (o.nlywhen follow iog SEARCH).,
Inde1\tation of the new statement is made
according to the following rules:
1.
Data Division
• FDs and level 77 items are indented
zero.
• Level 01 items are indented zero in
the Linkage and Working Storage
sections and two in the File and
Report sections
• Each subsequent lower level within
an 01 item is indented two more than
the preceding higher level, up to a
maximum of 14 character positions or
7 levels.
Procedure Division
The source listing of the procedure
Division is normally printed in
double-column format, wi th each column
divided as described above. This format
approximately doubles the span of logic
that can be seen on one page or one
facing-page spread.
• Section names are indented zero
• Paragraph names are indented two
• Unconditionally executed verbs are
indented four
• Verbs executed under a single
condition, such as IF or AT END, are
indented six
Regardless of whether the source code
follows indentation conventions, the lister
indents statements according to their type,
and according to hierarchy where
applicable. This feature of the lister
makes file and record structure immediately
visible and also helps to identify groups
of related statements such as IF/ELSE and
nesting of IFs.
Note:
If blank lines are present in the
orIginal source, the lister eliminates
them and renumbers the statements
accordingly.
12rmat Conventions
New statements are indented from the
left margin, which contains the statement
number. The liste.r treats the followinq as
new statements:
• Division and section headers
• Paragraph names
• Level numbers or level indicators (FD,
RD, etc.)
210
• The first IF in a nest is indented
four, subsequent nested IFs are
indented an additional two at each
level up to a maximum of 14 character
positions or 6 levels.
• ELSEs are indented to the same
position as the IF to which they
co.rrespond.
3.
Continuation lines in all divisions
are indented six with respect to the
first line of the continued statement.
!2~£acing
within a statement and on
continuation lines is usually one space.
within the Data Division, however, PICTURE
and VALUE are aligned as nearly as possible
into columns so that they may be found and
compared easily.
Words are never split at
the end of a line unless the word to be
split is a nonnumeric literal that will not
fit on a single continuation line.
appear to the right of the
statement or continuation line. References
following paragraph or section names appear
immediately to the right of the name,
separated by a blank. References following
other types of statements appear as far to
the right as possible depending on the
~~~B£~
number of blanks available on the line.
Each reference consists of a statement
number and a type indicator.
When references are in series, they are
separated by coamas and are in ascending
~h~
Lister Feature
210.1
if ithin the Data Division, a reference
series may end with an alphabetic footnote
indicator. The footnote contains the
remaining references to that data item.
In the Pr oced ure Di vision, the reference
may also be a footnote indicator, b~t the
footnote is different in appearance. In
the Procedure Division-, the footnote is
actually an on-page replica of the Data
Division statement referred to bI the
footnoted statement. This replica is
complete ·with all other references to the
data item from other portions of the
program. To conserve space in the listing,
the lister does not repeat a footnote if it
appears at the bottom of either of the two
preceding pages but instead reuses the same
footnote letter in the new reference.
As mentioned above, a reference consists
of a statement number and a type indicator.
The type indicator provides immediate
information as to what is being done by the
statement referred to.
Tvo sets of type indicators are used by
the lister: one for the Data Division and
one for the Procedure Division. within the
Data Division, the type indicators are:
C
Data item changed (such as by ADD
or MOVE)
D
Data item REDEFINED or RENAMED
E
Data item referred to by
Environment Division statement
(SELECT) or by some Procedure
Division input/output operation
(OPEN, CLOSE, INITIATE, etc.)
Q
Queried by IF, WHEN, or UNTIL
R
Referred to by a READ, ACCEPT or
similar statement
U
Data item unchanged (used as a
source field)
W
Referred to by a WRITE, GENERATE,
DISPLAY, or similar statement
X
Used as an index, subscript, or
object of a DEPENDING ON statement
G
P
T
GO TO
PERFORM
(PERFORM) THBU
THE SUMMARY LISTING
The summary listi.ng is useful both as an
analysis and as a troubleshooting aid.
USing the summary listing, the user can
ascertain quickly which data areas are most
referred to, which procedures refer to them
most often, and the nature of those
references. The number of references to
undefined symbols and the number of
incorrectly coded COBOL statements can also
be ascertained.
Each division or section header, and
each FD, RD, or SD begins a new entry in
the summary listing. The entry consists of
the header line, and beginning on the next
line, the total number of each kind of
reference to that section from within
itself (INTRA), and from outside itself
(FROM). These are followed by similar
information for references the section
makes to others outside itself (TO). The
type indicators used for references are the
same as those used in the source listing.
In large programs, with either no
sections or very large sections in the
Procedure Division, the lister summary may
not be very helpful. This can be remedied
by adding SECTION statements to the source
program at appropriate points. If SECTION
statements are being added to a program
that already contains some, it is very
important to make certain that both
implicit and explicit reference qualifiers
are not invalidated.
THE OUTPUT DECK
within the Procedure Division, the type
indicators are:
A
B
E
ALTER
(ALTER) TO PROCEED TO
INPUT or OUTPUT PROCEDURE (SORT
Feature)
optionally, the lister can produce a new
COBOL source deck that reflects the
reformatted source listing. This deck eay
be saved in a BASIS library, used directly
as input to the compiler, or punched into
cards. As a result of reformatting, the
nev 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:
Lister Feature
211
1.
References, footnotes. and blank lines
are omi t ted.
2.
Literals will be repositioned if
needed to assure proper continuation.
3.
statement numbers are converted to
card numbers.
a.
The statement n umber is mul tiplied
by 10, and leading zeros added as
necessary to fill columns 1
through 6.
b.
Comment and continuation cards are
numbered one higher than the
preceding card.
The lister feature is specified in the
PARM field of the EXEC card through five
compiler options. The combination of
options that are selected determine both
the format and contents of the lister
output. Either LSTONLY or LSTCOMP must be
specified for the other options to have
meaning, unless BATCH is specified.
In a
batch compilation, if some or all of the
programs are to be compiled using the
lister feature, L120 or L132 must be
specified in the PARM field of the EXEC
card--even if LSTCOMP or LSTONLY are
specified on the CSL card.
The five lister options are described
below.
Note that the IBM-supplied defaults
are indicated by an underscore; they can be
changed when the compiler is installed.
The lister options are as follows:
LSTONLY
LSTCOMP
HQ.1~1
212
indicates whether the lister feature
is to be used. LSTONLY specifies that
a reformatted listing is to be
produced but that no compilation is to
occur. LSTCOMP specifies that both a
reformatted listing is to be produced
and compilation is to occur in the
same jo b step.
FDECK
NOFDECK
--indicates whether a copy of the
reformatted source program is to be
written on the SYSPUNCH data set.
Since FDECK has meaning only with
either LSTONLY or LSTCOMP. the lister
output will be both a reformatted
listing and a reformatted deck. COpy
statements within the source progtam
will be produced as COpy statements,
or, if CDECK is in effect. the
expansion of the COpy statement will
be produced.
CDECK
1!QCDEC!
indicates whether or not COpy
statements are to be converted to
comment statements in the output
listing and the COpy members are to be
expanded. CDECK may be specified with
FDECK or NOFDECK.
With FDECK, the
source deck produced will contain the
expansion of COpy statements; with
NOFDECK, only the expansions of COpy
statements are produced.
LCOL1
LCQL2
indicates whether the Procedure
Division part of the listing is to be
in single-or double- column format.
L120
L132
indicates whether the length of each
line of the reformatted listing is to
be 120 or 132 characters long.
A programmer using the IBM OS/iS COBOL
Compiler under the I Bf! Operating System,
has several methods available to him for
testing and debugging his programs. Use of
the symbolic debugging features are
described in detail in this chapter.
.. Appendix A:
A sample Program t ' contains
an example of a program run without the
symbolic debugging features.
The chapter
"Program Checkout" contains information
useful for finding the instruction that
causes the abnormal termination and then
correcting the problem. The chapters
"Output" and "Using the Checkpoint/Restart
Feature" include a discussion of compiler
output and a description of taking
checkpoints and restarting programs,
respecti vely.
The program product IBM os COBOL
Interactive Debug (Program Number 5734-CB4)
enables the user to debug his COBOL
programs from a TSO terminal. To be
acceptable for Interactive Debug, a program
must be compiled with the TEST compiler
opt.ion. TEST overrides FLOW, STATE, SYMDMP
and COUNT. Hovever, note that TEST may not
be specified with BATCH, since BATCH
overrides TEST. TEST will also be
cancelled if the program con tains USE FOR
DEBUGGING statements. Interactive Debug is
described in greater detail in the "Program
Checkout" part of this publication.
liQl~:
USE OF THE SYl'lBOLIC DEBUGGING FEATURES
As an aid to debugging, compiler options
can be requested that provide additional
diagnostic information for an abnormal
termination other than one caused by
"Canceled by Operator" or exceed ingthe
system-state time slice. Three user
options are available for object-time
debugging -- the statement number option
(STATE), the flow trace option (FLOW), and
the symbolic dump option (SYMDMP).
The STATE option causes the ~umber of
the card for the last verb executed before
termination to be printed out.
The FLOW
option causes a trace of the last
user-specified number of procedures
executed to be printed out (with a default
of 99).
Both STATE and FLOW cause the
PROGRAM-ID, the completion code~ and the
last problem PSi to. be printed olit.
The
SYf!DKP option enables the user to request a
symbolic formatted dump of the data area of
the object program for an abnormal
termination, or to request dynamic dumps of
data areas at strategic points during
execution.
Use of th'ese features requires no sou.rce
language coding; rather the user specifies
these options at compile time, through job
control language. operation of the SYMDf1P
option is dependent on execution-time
control cards. Fig~re 86 illustrates the
output generated for each of these
features.
When any of the debugging options is
specified, the programmer must:
• Request the option at compile time by
specifying it in the PARM field or, if
a cataloged procedure is used. in the
PARM.COB field.
• Itlclude a //SYSDBOUT DD card for the
debug output data set at execution
time.
• Make the COBOL library available at
execution time by specifying the
following DD statement:
//STEPLIB DD DSN=subr-libname,DISP=SHR,
VOL=SER=volser~UNIT=unit
(This is necessary because certain
COBOL library subroutines are loaded
dynamically from the subroutine library
only as needed; they are not
link-edited into the COBOL object
program. )
• If the COBOL program being debugged
is to be invoked from a higher-leVel
non-COBOL program, the programmer must
ensure that the non-COBOL program calls
the COBOL libra.ry subroutine ILBOSTPO
before calling any COBOL program.. For
further information on this point. see
the section "calling and Called
Programs" in this manual.
If the STATE option is in effect and an
abnormal termination occurs, the printed
output includes the compiler-generated card
number or~ if NUM is in effect, the card
sequence number for the last verb executed.
Violation of the rule against mixing RES
and NORES programs in a single run unit may
result in erroneous information from STATE.
Symbolic Debugging Features
213
[-'.2"02 t ion
If the FLOW option is in effect, a
formatted list containing the PROGRAM-ID
and either the compiler-generated card
number or the line number (if NOM is in
effect) of the last n executed procedures
is printed on SYSDBOUT. The number of
procedures traced can vary from 1 to 99 and
is specified by the programmer.
The number of procedures to be traced may
be specified at compile time via either the
PARH parameter or, if a cataloged procedure
is used, the PARK. COB field.
This number
may be overridden at execution time via the
PARS parameter or, if a cataloged procedure
is used, the PARM.GO parameter.
If the
number of procedures traced is specified at
neither compile time nor execution time,
either the default value of 99 or the value
specified at program product installation
viII be employed. When using FLOW or
NOFLOW at execution time, the option JlY.2i
be preceded by a slash t1 /ft.
(See Fi gure 8
for an exa mple. )
If batch compilation is used, FLOW can
be specified at compile time and remain in
effect for every program in the batch. To
suppress a trace for a particular program
within the batch, the programmer should
specify NOFLOW a t execution time as the
last parameter in the PARK field for that
p~oqram, or change the CBL card.
For more
information, see the sections "Options for
the Compiler" and ftoptions for Execu tion.n
By specifying a //SYSDTERM DD card in
addition to the //SISDBOUT OD card, dynamic
dump output will he written onto SYSDTEBM
while the abend dump output will go to
SYSDBOUT. SYMDMP output will be
formatted at 55 lines to ~he page.
NO!~:
The TSO programmer should assign
slSqTERM to the terminal since dynamic dump
outptlt is interruptable. SYSDBOUT should
be flssigned to a direct access data set
which could be listed at the terminal after
the ABEND is complete.
The abnormal termination dump consists
of the following parts:
1.
An abnormal termination message,
including the number of the statement
and of the verb being executed at the
time of an abnormal termination.
2.
selected areas in the Task Global
Table.
3.
A formatted dump of the Data Division
including:
(a) For an SD -- the card number, the
sort-file-name, the type, and the
sort record.
(b)
l!Q.!.~:
The FLOW option is completely
independent of the READY/RESET TRACE
feature of the debugging language.
~MDMP
012.ti.2n
If the SYMDMP option is in effect, a
symbolic formatted dump of the object
program' s data area is produced when the
program abnormally terminates.
(The SYMDMP
option cannot. be llsed if the source program
contains USE FOR DEBUGGING and WITH
DEBUGGING MODE.)
This option also enables
the programmer to request dynamic dumps of
specified data-names at strategic points
dur ing program execu tion. If two or more
COBOL programs are link-edited together and
one of them terminates abnormally, a
formatted dump is produced for all programs
in the calling sequence compiled vith the
SIKDMP option. up to and including the main
program in the reverse order of their
calling sequence.
(The terminating program
itself need not have been compiled with the
51 MDMP option.)
214
For an PD -~ for VSAM:
OPEN/CLOSE
status, card number, organization,
access mode, last IIO operation,
file status, and the fields of the
record. Por non-VSAM:
the card
number, the file-name, the type,
the ddname, the URca and/or DCB
status, the contents of the DRCB
and/or DCB in hexadecimal, and the
fields of the record; also, for
QSAK, the file status.
tc) For an RD -- the card number, the
report-name, the type. the report
line, and the contents of
PAGE-COUNTER and .LINE-COUNTER if
present.
(d) For a CD -- the CD itself in its
implicit format, as well as the
area containing the message data
currently being buffered.
Ie)
For an index name -- the name, the
type, and the contents in decimal
which represents an actual
displacement from the beginning of
the table that corresponds to an
occurrence. Dumber in the table.
The value is calculated as the
occurrence number minus one,
multiplied by the length of the
entry that is indexed by this
index-name.
The symbolic dump opt ion is requested at
compile time via the SYMDMP option, through
the PARM parameter of the EXEC card.
operation of the symbolic dump option is
dependent on object-time control cards
placed io the SYSDBG data set (see also the
"Default SYSDBG Data Set" section that
follows). This data set must consist of
unblocked SO-byte records. If the
~bject-time control cards are not present,
SYKDMP is canceled at execution time.
These cards are discussed below.
8.
Braces enclosing stacked items
indicate that a choice of one item
mY§! be made by the programmer.
9.
All punctuation marks and special
characters shown in the statement
formats other than hyphens, brackets,
braces, and underscores, must be
punched exactly as shown. This
includes commas, parentheses, and the
equal sign.
RQ!~:
Blanks may be SUbstituted for
commas.
.&Qnti!!~iQ.n_~g,£.2:§:
To continue either the
prog.ram-control ca.rd or the line-control
card, the proqramme·r must code a nonblanle
ch aracter in colu mn 72 of the contin ued
card. Individual keywords and data-names
cannot be sp1i t between cards.
The operation of the SYKDMP option is
determined by two types of control cards:
Program-control card -- required if
abnormal termination and/or dynamic
dumps are requested.
Line-control card -- required only if
dynamic dumps are requested.
~nt~!~j:atement rlac~!!l~i:
If a main
program is compiled with the SYMD.MP option,
or if at least one subprogram called by the
main program is a COBOL pr~gram compiled
with the SYMDMP option, the control cards
may either follow or precede the
programmer's data, if any, in the input
stream:
//GO
IIGO.SYSDBG
EXEC
DD
~yntax
Rules: The fields of both the
program-control card and the line-control
card must conform to the fQllo1!fing rules:
1.
Control cards are essentially free
form, i.e., parameters coded on these
cards can start in any column.
However, parameters may not extend
beyond column 11.
PGM=
*
(user s control cards)
1
1*
I/GO.SYSIN
DD
*
{user's data cards, if any}
/*
2.
Each parameter except the last must be
immediately followed by a comma or a
blank.
For an example of the control statements
used to compile a program .with the SYMDMP
option, see Figure 86.
3.
No commas are needed to acco~nt for
optional parameters that are not
specified.
4.
All upper-case letters in IBM
documentation represent specifications
that are to appear in the actual
stateme.nt exactly as shovn.
frog£~J!=~Qntrol Cards:
A program-control
card must be present at execution time for
any program requesting a SYMDMP service.
program-control cards have the following
fo.rmat:
5.
All lower-case letters represent
generic terms that are to be replaced
in the actual statement.
6.
Brackets are used to indicate'that a
specification is optional and is not
alvays required in the statement.
7.
Brackets enclosing stacked items
indicate that a choice of one item
may, but need not, be made by the
programmer.
,ENTRY.
program-id,ddname [ ,NOENTRY
Jr,~ (HEX)
1
(~U [,PDS]
whe.re:
prograll-id
is a 1- to S-character program-name of a
COBOL program compiled with the SYMDftP
option. This parameter is required
and must appear first on the
program-control card.
ddnall_e
is the execution-time ddname of the file
that was produced at compile time on
Symbolic Debugging Features
215
SYSUT5.
This parameter is required
and must follow the program~id.
ENTRY
!!Q.EN.I!U
ENTRY is used to provide a trace of a
program-name when several programs are
link-edited together.
Each t.ime the
program whose PROGRAM-ID matches the
"program-id" parameter is entered, its
name is displayed.
HEX
!Q!!EI
is optional and Iefers to the forma~
of the Data Division area i~ the
abnormal termination dump.
If HEX is
specified, level-Ol items are provided
in hexadecimal. Items subordinat.eto
level-01 items are print~d in EBCDIC,
if possible. Level-77 items are
provided both in EBCDIC and
hexadecimal. If HEX is not specified,
items subordinate to level-Ol items
and level-77 items are provided in
EBCDIC.
If these items are
unprintable, hexadecimal notation is
provided.
PDS
is optional and allows the user to
specify that the debug file, which was
produced at compile time on SYSUT5 and
whose name is ddname, is a partitioned
data :'set. In this case, SYMDMP
assumes that program-id is the name of
a member in that debug file.
This
option is intended to reduce the
number of execution-time DD cards
required for debug files, when many
programs compiled with the SYMDMP
option are executed together in a
COBOL run-unit. Since each such
program requires a unique debug file,
each program-control card could
contain a unique program-id (member),
the same ddname, and PDS.
Note: The user should be aware that
the debug file produced at compile
time contains device-dependent
relative block addresses embedded in
the data blocks and is, therefore,
unmovable. The only way to alter a
member in an existing partitioned
debug file is through recompilation
replacement. User attempts to
compress the data set through IEBCOPY
or move the data set to another data'
set through IEHMOVE will be rejected
by these utilities. Further, the user
should not create a partitioned data
set from several compiler-created
sequential debug files.
SYMDMP will
produce message IKF164I and will cancel
debug output for any program whose
debug file has been moved. The only
exception is. that a sequential debug,
216
file can be moved to another sequential
data set on a,device of the same type.
kine-control Cards: Line-control cards
have the following format:
line-num[, (verb-num) ][ ,ONn[ ,m( ,k]]]
~
[: ::~~~X)] IwALL1(
11[:~~~~) ] ,namel
ITHRU name21 •••
!~
line-num
indicates the card number associated
with the point in the Procedure
Division at which the dynamic dump is
to be taken. The card number is
eith~r the compiler-generated number
or, if NUMis in effect~ the user's
'number in card columns 1 through 6.
The number must be that of a card
containing a section name, procedure
name, conditional verb, or imperative
verb.
verb-num
indicates the position of the verb in
the card indicated by "line-num"
before whose execution a dynamic dump
is taken. When "verb-num" is not
specified, the value 1 is assumed;
when specified, "verb-num" must follow
"line-num" and may not exceed 15.
ON n[,m[ ,it]]
is equivalent to the COBOL statement
ON n AND EVERY m ·UNTIL it... This
option limits the request.ed dynamic
dumps to specifi~d times. For
example, "ON n"would result in one
dump, given the nth time "line-num" is
reached during execution. "ON n,m"
would result in a dump the first time
at the nth execution of "line-num" and
thereafter at every mth execution
until end-of-job. K limits the number
of dumps to the kth occurrence of
"line-num".
HEX
NOHEI
refers to the format of the Data
Division areas provided in the dynamic
dump.
If HEX is specified, level-Ol
items are provided in hexadecimal.
Items subordinate to level-01 items
are printed in EBCDIC, if possible.
Level-77 items are printed in both
EBCDIC and hexadecimal. If HEX is not
specified, items subordinate to
level-Ol items and level-77 items are
provided in EBCDIC. If the items are
unprintable, hexadecimal notation is
provided.
Note that if "namel" is
specified and it represents a group
item and HEX has not been specified,
neither the group nor the elementary
items in the group will be provided in
hexadecimal.
namel [TRRU name2]
represents selected areas of the Data
Division to be dumped. with the TURU
option, a range of data-names
appearing consecutively in the Data
Divisionis dumped. "namel" and
"name2 n may be qualified but not
subscripted. If the programmer wishes
to see a subscripted item. specifying
the name of the item without the
subscript results in a dump of every
occurrence of that item.
results in a dump of everything that
would be du.ped in the event of an
abnormal termination for the program
specified in the "program-idA
parameter in the preceding
program-control card. one use of ALL
allows the programmer to receive a
formatted dump at normal return from
the program. To do this, the
programmer must ensure that the
generated statement nuaber of the line
00 which a STOP RUN, EXIT PROGRAH, or
GOBACK statement appears is specified
as the "line-num lt paramete.r.
DEFAULT
SI~RBG
PATA SET
If the programmer fails to define a
SYSDBG data set, the SYMD~P routines
generate a default SYSDBG data set
equivalent to the following job control
language:
symbolic Debugging Features
216.1
IISYSDBG DD *
prog-id SYSUT5
debugging or COUNT, i.e., FLOW. STATE,
SYMDMP or COUNT options. They must be
executed as a logical pair only once
per COBOL run unit.
If COBOL program A
calls COBOL program B, either A or B or
both can be compiled with debugging,
but only the highest level program
compiled with debugging or COUNT
options should contain CALL 'ILBOSPIO'
statements. The first execution of
ILBOSPIO issues a SPIE macro
instruction to trap the old program PSi
in the event of a program check before
STAB gets control at abnormal
termination. The second execution of
ILBOSPIO resets any previous SPIE at
task normal termination. At abnormal
termination, ILBODBGO will reset the
prev ious SPIE.
1*
where:
prog-id
is the name of the first program
compiled with the SYftDltP option
encountered in the run-unit. If
the programmer has provided a
SY5UT5 DD statement referring to
the file produced during the
compilation of proq-id on SYSUT5.
the effect of this default data
set is to produce normal SYftD~P
output on an abend.
If a run-unit includes one or more
programs that have been compiled with the
S!"D~P option and the programmer desires to
suppress the normal SY~DHP output on an
abend, either of the following methods may
be used:
• omit the SYSUT5 DD statement from the
execution step. This will cause the
following message to be produced and
SYMDMP output to be cancelled:
IKF168I UNSUCCESSFUL OPEN OF DEBUG FILE
• Finally, any CALL 'ILBOSPIO' statements
written in a COBOL program compiled
without any of the above options cause
the subroutine to return control with
no action (SPIE is not issued) •
If IMS will link to a COBOL load module
many times in a job step, the ENDJOB
compiler option should be specified. For
additional information, see the discussion
of the ENDJOB option in the section
"Options for the Compiler" in this manual.
• define the SYSDBG data set as
IISYSDBG DD DUMMY
This will cause the following message
to be produced and SYMDMP to be
cancelled:
IKF174I SYMDMP CANCELLED.
CARDS FOUND.
NO CONTROL
Execution of a COBOL program compiled with
the options STATE, FLOW, SYMDMP, or COUNT
under IMS. requires the COBOL programmer
to write an explicit CALL statement to
subroutine ILBOSPIO in his source program,
i.e., CALL 1ILBOSPIO'.
Figure 86 contains selected portions of
output from a program that utilizes the
Symbolic Debugging feature.
In the
following description of the program and
its output, letters identifying the text
correspond to letters in the program
listing.
(SYMDMP itself provides no page
headings or numberings on its output.)
Because the SYMDMP option is requested
in the PARM parameter of the EXEC
card, the logical unit SYSUT5 must be
assigned at compile time.
®
The PARM parameter specifications on
the EXEC card indicate that an
alphabetically ordered cross-reference
dictionary, a flow trace of 10
procedures, and the SYMDMP option are
being requested along with other
options.
©
An alphabetically ordered
cross-reference dictionary of
data-names and procedure-names is
produced by the compiler as a result
of the SXREF specification in the PARM
parameter of the EXEC card.
• There should be one CALL statement
written at the beginning of the
Procedure Division and following each
ENTRY statement in the program.
• There should be one CALL statement
~ritten at each exit point in the
program, i.e., preceding each GOBACK,
EXIT PROGRAM or STOP RUN statement.
• These CALL statements are effective
only in a COBOL program compiled with
Symbolic Debugging Features
217
®
The file assigned at compile time to
SYSUT5 to store SYMDMP information is
assigned to SYSUTS at execution time.
®
The SYMDMP control cards placed in the
input stream at execution time are
printed along with any diagnostics.
CD
(b) SYSUTS is the ddname of the
SYSUT5 file at execution time.
Q)
®
The second card is a line-control
card which requests a (HEX)
formatted dynamic dump of KOUNT,
NAME-FIELD, NO-OF-DEPENDENTS, and
RECORD-NO prior to the first and
every fourth execution of
generated card number 70.
The third card is also a
line-control card which requests a
(HEX) formatted dynamic dump of
WORK-RECORD and B prior to the
execution of generated card number
81.
The type code combinations used to
identify data-names in abnormal
termination and dynamic dumps are
defined. Individual codes are
illustrated in Figure 8S.
@
The dynamic dumps requested by the
first line-control ca rd.
®
The dynamic dumps requested by the
second line-control card.
Program interrupt information is
provided by the system when a program
termina tes abnormally.
The statement number information
indicates the number of the verb and
of the statement being executed at the
time of the abnormal termination. The
name of the program containing the
statement is also provided.
®
218
• Message IKF1821 appears after any
record N
that is part of a closed
file; the status of a file is described
in M
If the record is part of a
closed file, the contents of the record
are not printed; instead, the message
appears. Message IKF182I is described
more fully in "Appendix K: Diagnostic
Messages" in this publication ..
®
The contents of the fields of the
Working-storage section are provided in
the format requested on the
program-control card.
©
The value associated with each of the
possible subscripts is provided for
each of the data items described with
an OCCURS clause.
®
Asterisks appearing within the EBCDIC
representation of the value of a given
field indicate that the type and the
actual content of the field conflict.
!Ql~:
When the SYMDMP option is used,
level numbers appear "normalized" in the
symholic d UJllP prod uced. For example, a
group of data items described as:
01
RECORDA.
05 FIELD-A.
10 PIELD-A1 PIC X.
10 FIELD-A2 PIC X.
viII appear as follows in SYMDMP output:
o1 RECORDA •••
02 FtELD-A •••
03 FIELD-A1 •••
03 FIELD-A2 •••
A fl08 trace of the last 10 procedures
executed is provided because FLOW=10
vas specified in the PARM parameter of
the EIEC card.
Selected areas of the Task Global
Table are provided as part of the
abnorma I termination dump.
@
The fields of records associated with
each FD are provided in the format
requested on the program-control card.
®
The first card is the
program-control card where:
(a) TESTRUN is the PROGRAM-ID.
@
applicable, are provided in
hexadecimal. For VSAM: the card
number, OPEN/CLOSE status,
organization, access mode, last I/O
operation~ and file status.
For each non-VSAM file-name, the
generated card Dumber, the filet ype,
the file status (if QSAM), the file
organization, the DCB status, and the
fields of the DCB and DECB, if
1.
Reference to the statement number
infor.ma tion 0 provided by t.h.e SYMDMP
option shows that the abnormal
termination occurred during the
execution of the first verb on card
81.
2.
Generated card number 81 contains the
statement COMPUTE B = B + 1.
3.
4.
Through verification of the contents
of B at the time of the abnormal
termination ®
it can be seen that
the usage of B (numeric packe~
conflicts with the value contained in
the data area reserved for B(n umeric
displav) •
The abnormal termination occurred
during an attempt to perform an
addition on a display item.
,
J
..
J
A
I
I
t
I
I
I
B
1
1
I
More complex errors may require the use
of dynamic dumps to isolate the problem
area. Line-control cards are included in
TESTRUN merely to illustrate how they are
used and what output they produce.
Code
I
I
I
Meaning
Alphabetic
Binary
Display
Edited
Subscripted Item
Floating Point
Numeric
Packed Decimal
signed
overpunch Sign Leading
Overpunch Sign Trailing
Separate Sign Leading
Separate Sign Trailing
0
E
*
F
N
p
'S
Ot
aT
SL
ST
L-
Figure 85.
.i.--
Indiv idual Type Codes Used in
SYMDl'1P Output
symbolic Debugging Features
219
IIT~STRUN
II
JOB ('A.~C~U'J,'BETHKE
MSGCLASS=~
1550 J&3',MSGLEVEL=(1,lJ,CLASS=A,
••• ScTUP
TAPE SCRTCH RING=YES
~/I
EXEC VSCBLCLG,
~ -II
PARM.COB='uMAP,P~AP,SXREF,FLOWc10,SYMDMP,QUOTE,NORES',
II
GOOMP='SYSyUT=S',
II
SYSUT5c'&&SY~UT5,0ISP=(,PASS",
II
PARM.lKEOc'LISJ,lfT,XREF'
XXCVS20CLG PROC PROG-IKfC8l00,
XX COBOMP='SYSOUT=A',
XX ~OOMP=DUMMY,
XX ~ARMCOB='LOA',RGN~OBc128K,CONOCOB='(16,LT",
XX PARMLKO='llST,XRE~,LfT',RGNlKED=128K,CONOLKO='(5,LT,COB)',
XX PARMGO=",RGNGO=1~2K,CONOGO='((5,LT,COB,,(5,LT,LKED')',
XX ~OSET='&GOSET',GO='GO',
XX ~1=CBlCOMPL,V1=CBlOEV,Ul=SYSOA,
XX ~2=CBLCOMPL,V2.C6~OEV,U2=SYSOA,
XX ~~=C8LUPM,V3=CBlO~V,J3=SYSOA,
XX ~~=CVS20LIB,V~=CBlOEV,U~=SYSDA,
XX S5=CVS20lIB,V5=CB~OEV,U5=SYSOA,
XX So=CVS20LIB,V6=CB~DfV,U6=SYSOA,
XX ~7=CVS20LIB,V7=CB~OEV,U7·SYSOA,
XX SB=CVS20LIB,V8=CBLOCV,U8=SYSOA,
XX ~9=CVS20LIB,V9='S~R=CBLOEV',U9cSYSOA,
XX SlOc'SYS1.LINKlIB',V10=,UIO=
XXCuB EXEC PGM=&PROG,REGION=&RGNCOB,CONO=&CONOC08,
XX PARM='LOA,NOlIB,SjZE=128K,BUF=12K,PMA,OMA,SXR,OPT,RES,&PARMCOB'
XXSfEPLIB 00 OSN=&Sl,VOL=SER=&Vl,UNIT=&Ul,OISP=SHR
XX
00 OSN=&S2,VOL=SER=&V2,UNIT=&U2,OISP=SHR
XX
00 OSN=&S~,VOL=SER=&V3,UNIT=&U3,0ISP=SHR
IICuB.SYSPRINT 00 ~Y~OUT=S
X/SYSPRINT DO SYSOUT=A
XXSYSUOUMP 00 &COBOMP
XXSYSUTl 00 UNIT=SYSuA,~PACE=(TRK,(25,3»,OSN=&SYSJT1
XXSYSUT2 00 UNIT=SYSuA,SPA:E=(TRK,(2S,3,),OSN=&SYSUT2
XXSYSUT3 00 UNIT=SYSuA,SPACE=(TRK,(ZS,3)),OSN=&SYSUT3
XXSYSUT~ 00 UNIT=SYSuA,SPACE.(TRK,(25,3),OSN=&SYSUT~
~XXSYSUTS DO UNIT=SYSuA,SPA:E=(TRK,(25,3»,OSN=&SYSUT5
~ XXSYSUT6 DO UNIT-SYSuA,SPACE=(TRK,(25,3),OSN=&SYSUT6
XXSYSLIN 00 OSNAME=&~dADSET,OISP=(MOO,PASS),UNIT=SYSOA,
XX ~PACE=(80,(500,10u)J
IICuB.SYSIN 00 •
Figure 86.
220
llMVS031
00001000
00002000
00003000
OOOO~OOO
00005000
00006000
00007000
00008000
00009000
00010000
00011000
00012000
00013000
00014000
00015000
00016000
00017000
00027000
0:)028000
00029000
00030000
00031000
00032000
00033000
0003~000
00035000
00036000
00037000
00:)38000
00039000
OOO~OOOO
000~10(\0
Using the SyftDftP option to Debug the Program TESTRUN (Part 1 of 11)
00001
00002
00003
00004
00005
00006
00007
000·08
00009
00010
00011
00012
00013
00014
00015
00016
00017
00018
00019
00020
00021
00022
00023
00024
00025
00026
00027
00028
00029
00030
00031
00032
00033
00034
00035
00036
00037
00038
00039
00040
00041
00042
00043
00044
00045
00046
00047
00048
00049
00050
00051
00052
00053
00054
00055
00056
00057
100010 IDENTIFICATION DIVISION:
100020 PROGRAM-ID. TESTRUN.
10003'0
AUTHOR. PROGRAMMER NAME.
100040
INSTALLATION. NEW YORK PROGRAMMING CENTER.
DATE-WRITTEN. JULY 12, 1968.
100050
100060 DATE-COMPILED. JUN 11,1974.
REMARKS. THIS PROGRAM HAS BEEN WRITTEN AS A SAMPLE PROGRAM FOR
.100070
COBOL USERS. IT CREATES AN OUTPUT FILE AND READS IT BACK AS
100080
INPUT.
100090
100100
100110
100120
100130
100140
100150
100160
100170
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. iBM-360-H50.
OBJECT-COMPUTER. IBM-360-H50.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT FILE-l ASSIGN TO UT-2400-S-SAMPLE.
SELECT FILE-2 ASSIGN TO UT-2400-S-SAMPLE.
100180
100190
100200
100210
100220
100225
100230
100240
100250
100260
100270
100280
100290
100300
100310
100320
100330
100340
DATA DIVISION.
FILE SECTION.
FD FILE-l
LABEL RECORDS ARE OMITTED
BLOCK CONTAINS 100 CHARACTERS
RECORD CONTAINS 20 CHARACTERS
RECORDING MODE IS F
DATA RECORD IS RECORD-l.
01 RECORD-i.
02 FIELD-A PICTURE IS X(20).
FD FILE-2
LABEL RECORDS ARE OMITTLD
BLOCK CONTAINS 5 RECORDS
RECORD CONTAINS 20 CHARACTERS
RECORDING MODE IS F
DATA RECORD IS RECORD-2.
01 RECORD- 2.
02 FIELD-A PICTURE IS x(20).
100350 WORKING-STORAGE SECTION.
77 KOUNT PICTURE S99 COMP SYNC.
100360
100370
77 NOMBER PICTURE S99 COMP SYNC.
100375
01 FILLER.
02 ALPHABET PICTURE X(26) VALUE "ABCDEFGHIJKLMNOPQRSTUVWXYZ".
100380
100395
02 ALPHA REDEFINES ALPHABET PICTURE X OCCURS 26 TIMES.
02 DEPENDENTS PICTURE X(26) VALUE "0123401234012340123401234
100405
100410"0".
100420
02 ,DEPEND REDEFINES DEPENDENTS PICTURE X OCCURS 2b TIMES.
100440
01 WORK-RECORD.
100450
02 NAME-FIELD PICTURE X.
100460
02 FILLER PICTURE X VALUE IS SPACE.
100470
02 RECORD-NO PICTURE 9999.
100480
02 FILLER PICTURE X VALUE IS SPACE.
100490
02 LOCATION PICTURE AM VALUE 1S "NYC".
100500
02 FILLER PICTURE X VALUE IS SPACE.
02 NO-OF-DEPENDENTS PICTURE XX.
100510
100520
02 FILLER PICTURE X(7) VALUE IS SPACES.
100521
01 RECORDA.
Figure 86.
Using the SYMDMP option to Debug the Program TESTRUN (Part 2 of 11)
symbolic Debugging Features
221
00058
00059
00060
00061
00062
00063
00064
00065
00066
00067
00068
00069
00070
00071
00072
00073
00074
00075
00076
00077
00078
00079
00080
00081
00082
00083
00084
00085
00086
100522
100523
100530
100540
100550
100560
100570
100580
100590
100600
100610
100620
100630
100640
100650
100660
100670
100680
100690
100700
100710
100720
100730
100731
100740
100750
100760
100770
100780
02 A PICTURE S9(4) VALUE 1234.
02 B REDEFINES A PICTURE S9(7) COMPUTATIONAL-3.
PROCEDURE DIVISION.
BEGIN.
NOTE THAT THE FOLLOWING OPENS THE OUTPUT FILE TO BE CREATED
AND INITIALIZES COUNTERS.
STEP-l. OPEN OUTPUT FILE-l. MOVE ZERO TO KOUNT NOMBER.
NOTE THAT THE FOLLOWING CREATES INTERNALLY THE RECORDS TO BE
CONTAINED IN THE FILE. WRITES THEM ON TAPE, AND DISPLAYS
THEM ON THE CONSOLE.
STEP-2. ADD 1 TO KOUNT, ADD 1 TO NOMBER, MOVE ALPHA (KOUNT) TO
NAME-FIELD.
MOVE DEPEND (KOUNT) TO NO-OF-DEPENDENTS.
MOVE NOMBER TO RECORD-NO.
STEP-3. DISPLAY WORK-RECORD UPON CONSOLE. WRITE RECORD-1 FROM
WORK-RECORD.
STEP-4. PERFORM STEP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 26.
NOTE THAT THE FOLLOWING CLOSES OUTPUT 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.
COMPUTE B = B + 1.
STEP-7. IF NO-OF-DEPENDENTS IS EQUAL TO "0" MOVE "Z" TO
NO-OF-DEPENDENTS. EXHIBIT NAMED WORK-RECORD. GO TO
STEP-6.
STEP-8. CLOSE FILE-2.
STOP RUN.
CD
DATA NAMES
DEFN
A
ALPHA
ALPHABET
000058
000044
0000113
000059
000047
0000115
000029
000037
000017
000018
000040
000053
000049
000055
00'0041
000051
000028
000036
000057
000048
B
DEPEND
DEPENDENTS
FIELD-A
FIELD-A
FILE-1
FILE-2
KOUNT
LOCATION
NAME-FIELD
NO-OF-DEPENDENTS
NOMBER
RECORD-NO
RECORD-1
RECORD-2
RECORDA
WORK-RECORD
Figure 86.
222
I
CROSS-REFERENCE DICTIONARY
REFERENCE
000068
000081
000070
000064.
000077
000064
000068
000070
000064
000071
000072
000080
000072
0{)Q072
000080
000068
000077
000085
000070
000082
0000b8
000071
000080
000083
OGOO'/ll
using the SyftDMP option to Debag the Program TESTRUN (Part 3 of 11)
PROCEDURE NAMES
DEFN
BEGIN
STEP-1
STEP-2
STEP-3
STEP-4
STEP-5
STEP-6
STEP-7
STEP-8
000061
000064
000068
000072
000074
000077
000080
000082
000085
CARD
ERROR MESSAGE
14
58
IKF1l83I-W
IKF2190I-W
REFERENCE
000074
000074
000083
000080
IBM-370 IS ONLY VALID COMPUTER-NAME. IBM-360 SPECIFICATION IGNORED.
PICTURE CLAUSE IS SIGNED, VALUE CLAUSE UNSIGNED. ASSUMED POSITIVE.
IEC130I SYSLIB
DD STATEMENT MISSING
IEF142I - STEP WAS EXECUTED - COND CODE 0004
IEF285I
VSCBL1.LMOD
KEPT
IEF285I
VOL SER NOS= DB143 •
IEF285I
SYS74162.T203933.RVOOO.TESTRUN.R0000011
DELETED
IEF285I
VOL SER NOS= 231400.
IEF285I
SYS74162.T203933.RVOOO.TESTRUN.R0000012
DEL~TED
IEF285I
VOL SER NOS= 333001.
IEF285I
SYS74162.T203933.RVOOO.TESTRUN.R0000013
DELETED
IEF285I
VOL SER NOS= 333001.
IEF285I
SYS74162.T203933.RVOOO.TESTRUN.R0000014
DELETE':>
IEF285I
VOL SER NOS= 231400.
IEF285I
SYS74162.T203933.RVOOO.TESTRUN.SYMDBG
PASSED
IEF285I
VOL SER NOS= 333001.
IEF285I
SYS74162.T203933.RVOOO.TESTRUN.R0000015
DELETED
IEF285I
VOL SER NOS= 231400.
IEF2851
SYS74162.T203933.RVOOO.TESTRUN.LKEDINP
PASSED
IEF285I
VOL SER NOS= 333001.
IEF2851
SYS74162.T203933.SVOOO.TESTRUN.R0000016
DELETED
IEF285I
VOL SER NOS= 333001.
IEF285I
SYS74162.T203933.SVOOO.TESTRUN.R0000017
SYSOUT
IEF2851
VOL SER NOS= 231400.
IEF285I
SYS74162.T203933.RVOOO.TESTRUN.S0000018
SYSIN
IEF285I
VOL SER NOS= 231400.
IEF285I
SYS74162.T203933.RVOOO.TESTRUN.S0000018
DELETED
IEF285I
VOL SER NOS= 231400.
IEF3731 STEP /COB
/ START 74162.2054
IEF374I STEP /COB
/ STOP 74162.2058 CPU
OMIN 12.17SEC STOR VIRT 128K
XXIKED
EXEC PGM=lEWL,PARM="XREF,LIST,LET',COND=(S,LT,COB),REGION=128K 00800190
XXSYSLIB
DD DSN=VSCBL1.LIB,DISP=SHR,UNIT=2314,VOL=SER=DB143
00800200
XXSYSLIN
DO DSN=&LKEDINP,DISP=COLD,DELETE)
00800210
xx
DD DDNAME=SYSIN
00800220
XXSYSUT1
DD SPACE=C1024,(SO,20»,UNIT=C2314,SEP=SYSLIN)
00800230
XXSYSLMOD DD DSN= &LMODLIB (MBRNAME) , UNIT= (2314 ,SEP= (SYSLIN, SYSUTl»,
*00800240
XX
DISP=CMOD,PASS),SPACE=(1024,(50,20,l»
00800250
//LKED.SYSPRINT DO SYSOUT=G
X/SYSPRINT DO SYSOUT=A
00800260
IEF236I ALLOC. FOR TESTRUN LKED
IEF237I 233
ALLOCATED TO SYSLIB
IEF237I 250
ALLOCATED TO SYSLIN
IEF237I 234
ALLOCATED TO SYSUT1
IEF237I 235
ALLOCATED TO SYSLMOD
IEF237I 230
ALLOCATED TO 3YSPRINT
Figure 86.
Using the SYKDKP option to Debug the Program TESTRUN (Part 4 of 11)
Symbolic Debugging Features
223
XXSYSLIB DO OSN=&S4,vOl=SER=&V4,UNIT=&U4,DISP=SHR
XX uD DSN=&S5,VOL=SEk=&V5,JNIT=&U5,DISP=SHR
XX UO DSN=&S9,VOL=&V~,UNIT=&U9,DISP=SHR
XXSiSUTI 00 UNIT=(SY~OA,SEP=(SYSLIN,SYSLMOD)),SPACE=(1024,(50,20))
IllKEO.SYSPRINT 00 SYSOUT=S
X/SYSPRINT DO SYSOUT=A
XXG~ EXEC PGM=*.LKEO.SrSlMOO,PARM='&PARMGOI~REGION=&RGNGO,COND=&:ONO~O
XXSTEPlIB DO OSN=&S6,VOL=SER=&V6,UNIT=&U6,OISP=SHR
XX uO OSN=&S8,VOl=SEk=&V8,UNIT=&Ua,DISP=SHR
XX uD OSN=&S1,VOL=SEK=&V1,UNIT=&U1,DISP=SHR
XX uO OSN=&SI0,VOL=&VIO,UNIT=&UI0,0ISP=SHR
IIGu.SYSOUT 00 SYSuUT=S
X/SYSOUT DO SYSOUT=A
XXSYSUOUMP DO &GOOMP
IIGu.SYSDBOUT DO SYSDUT=S
~IIGu.SYSUT5 00 OSN=&&SYSUT5,DISP=(OlD,PASS)
~-~/Gu.SAMPLE DO UNIT=2~00,LABEL=(,NL"DISP=(NEW,OELETE)
IIGu.SYSOBG DO *
00041000
00048000
00049000
00050000
00051000
00052000
00053000
00054000
00055000
00056000
00051000
00058000
II
Figure 86.
224
Using the SYMDMP option to Debug the Program TESTRUN (Part 5 of 11)
~SYMDMP
CONTROL CARDS
~TESTRUN,SYSUT5
(!)-70,ON 1,4, (HEX) ,KOUNT ,I'4AMf-FIELD,NO-OF-DEPENOENTS,RECORD-NO
0- S1 ,(HEX),WORK-RECORD,B
NO ERRORS FOUND IN CONTROL CARDS
C!)........ TYPE
MEAN H'G
~OOt
A
AN
ANt:
o
Dt:
F
FO
Nfl
NB-S
NO
NO-OL
NO-OT
ND-SL
ND-ST
Nf:
NP
NP-S
~~ESTRUN
LaC
Oj5158
•
CODES USED IN SY'MDMP OUTPUT
..
,.
..
,.
..
ALPHABETIC
ALPHANUMERIC
ALPHANUMERIC EDITED
DISPLAY (STERLING NONREPORT)
DISPLAY EDITED (STERLING REPORT)
FLOATING POINT (COMP-1/COMP-2)
• FLOATING POINT DISPLAY (EXTERNAL FLOATING POINT)
.. NUMERIC BINARY UNSIGNED (COMP)
,. NUMERIC BINARY SIGNED
= NUMERIC DISPLAY UNSIGNED (EXTERNAL DECIMAL)
.. NUMERIC DISPLAY OVERPUNCH SIGN LEADING
.. NUMERIC DISPLAY OVERPUNCH SIGN TRAILING
= NUMERIC DISPLAY SEPARATE SIGN LEADING
.. NUMERIC DISPLAY SEPARATE SIGN TRAILING
,. NUMERIC EDITED
.. NUMERIC PACKED DECIMAL UNSIGNED (COMP-3)
.. NUMERIC PACKED DECIMAL SIGNED
,. SUBSCRIPTED
AT CARD 000070
CARD
LV NAME
00004U
77 KOUNT
(HEX)
TYPE
VALUE
NB-S
+01
0001
A
Ci51S8
00004~
02 NAME-FIELD
AN
OiS1A3
00005~
02 No-OF-DEPENuENTS
AN
(HEX)
01579A
TEST~UN
00005!
02 RECORD-NO
(HEX)
NO
AT CARD 000070
Lee
CARD
C;5i58
COO04u
LV NA,ME
77 KOUNT
TYPE
VALUE
NB-S
+05
0005
AN
E
(HEX)
a751Sd
••
••••
00000000
0000
00C04;,J
02 NAME-FIELD
OSiA.;)
oel)osZI
02 NO-OF-OEPENuENT S
AN
3
CiSHA
000054
02 Rf:CORt-NO
NO
0004
figure 86.
Using the SYMDMP OFtion to Debug the Program TESTRUN (Part 6 of 11)
symbolic Debugging Features
225
TESTRUN
LeC
0;~~58
AT CARD 000010
LV NAME
C"RD
ce004u
17 KOUNT
(HEX)
OB1Sd
00004'.t
02 NAME-FI ELD
O!:1A~
00005~
02
C157SA
00005J.
02 RECORD-NO
1 ESTKUN
LeC
VALUE
NB-S
+09
0009
AN
NO-OF-DEPEN~ENTS
AT CARD 000010
LV NAME
CARD
AN
2
NO
0008
TYPE
VALUE
NB-S
+13
0000
02 NAME-fIELD
AN
M
00005;;,
02 NO-OF-DEPENuENTS
AN
00005A.
02 RECORD-NO
NO
e i 5; 58
0OO04u
77 KOUNT
C151S8
aa(,a4~
C157A3
C75 79A
(HEX)
TESTRUN
Lec
TYPE
"T CARD 000010
CARD
LV NAME
TYPE
VALUE
NB-S
+11
0011
02 NAME-FIELD
AN
Q
00005;..
02 NO-OF-DEPENuENTS
AN
0
00('05J.
02 RECORD-NO
NO
0016
'15158
00004u
71 KOUNT
0; 51So
00004':11
a;!: 1A3
51SA
(HEX)
('j
ldlRUN
Lee
"T CARD 000010
CARD
LV NAME
TYPE
VALUE
NB-S
+21
0015
02 NAME-F'IELD
AN
U
00005;;1
02 NO-OF-DEPENuENTS
AN
4
00005J.
02 RECORD-NO
NO
0020
015158
0OO04u
17 KOUNT
Clj79t1
00004~
Oi51H
CiSHA
(HEX)
TESTRUN
LeC
AT CARD 00001C
CARD
LV NAME
TYPE
VALUE
NB-S
+25
0019
02 NAME-FIELD
AN
Y
00005:1
02 NO-OF-DEPENuENTS
AN
3
00005J.
02 RECORD-NO
NO
0024
TYPE
VALUE
CHiSS
00004')
71 KOUNT
Ci 5178
00004:.1
C151A3
OJ 5HA
(E)-rESTRUN
lec
Oi5HS
Oi57C;A
0;51SI:
Ci51CiF
C'i 51A2
C; 51A3
00u04u
01 weRK-RECoRl)
.... "''"'V'7
" ... NAMf=flflO
a BiA5
000051.1
00005!
00005,
00005...,
OOOOS't
00005:1
OOOOSg
C151eo
00005~
Figure 86.
226
(HEX)
AT CARD 000081
CARD
LV NAME
C15 7S8
C157';3
0012
02
02
02
02
02
02
02
(HEX)
A .,
FILLER
RECORD-NO
FILLER
LOCATION
FIllER
NO-Of-OEPENIJENT S
FILLER
AN
NO
AN
A
AN
AN
AN
NP-S
02 B
(HEX)
C140FOFO FOF14005 E8C340FO
40404040 40404040
A
0001
NYC
0
*1*2*3*
F1F2F3C4
Using the SJtlDKP Option to Debug the Program TESTRUN (Part 7 of 11)
COBOL ABEND DIAGNOSTIC AIDS
PFCGIlAM
TEST RUN
(D----lAST PSW BEFO"E AbEND
FF8500u7f:G075F46
SYSTEM COMPLETION CODE = OC7
(D----LAST CARD NUMdt:R/VERB NUM8ER EJlECUTED -- CARD NUMBER OOOOH/VERB NUMBER 01.
r;;'\
\V--TESTRUN
FLOW TRACE
0000"o 000072 000068 u00072 000068 000072 000068 000072 000077 0000(10
DATA DIVISION DUMP OF TESTRUN
CD-IASI<. GLOBAL TABLE
S ~Vt AREA
HITCH
TALLY
sellT SAVE
ENTRY-SAVE
SORT CORE S41E
HT COOt:
sun RET
kOl'I<.ING CELLS
seRT FILE SHE
SORT MODE S.LE
PH-VN TBL
IGT-VN TBL
HSi::RVEO
U/IGTH OF V., TBl
tIlBR RET
RESeRVED
(BG R14SAVE
COBUl I NOIC ... TOR
A( INIT 11
(HUG TA8LE PTR
SLBCOM ADDR
seRT-MESSAGe
S ¥ SuUT DCNAf'lE
" ESERVED
(CBLL 10
C(MPILED POlNTER
COUNT TABLE ADDRESS
HSERVED
CBG RllSAVE
C(UNT CHAIN ADDRESS
PRell CELL PTR
UNLSED
1 A LENGTH
HSI:RVED
PCS LIT PTR
(HUGGING
CC fOR INIT.AL INPUT
(VERFLOW CELLS
LOC
0759Du
0759fu
075A1u
D75A11l
075A 1..
o 75AZ...
01SA2- ..
075AZo
015AZ ..
075AZe
075A3u
075A5u
075A 70
075A9u
075ABu
075ADu
075AFu
075Blu
075B3u
075850
015800
07580'0
075860
075801.
075B 7u
07587'0
075B70
075B 71
07587u
075B7 ..
075B8u
075B8't
075B8d
075B81.
075B9't
015B9~
075B90
075B9u
075B9..
075 BAu
075BAIl
015BAI.
075BBo
075BB't
075B8:.1
0758BI.
0758(; ..
0758C"
0758CI.
(NONE.
EL CELLS
0756011
CECIlADR CELLS
(NONt:)
f Ie CELLS
075601.
CE 8UG TKANSfl:R
(NONEI
(HUG CARD
(NONEI
(tEUG BLL
(NONEI
CEBUG VLC
( NONE~
Cf8UG MAX
(NONEI
HSI:RVED
(NONEI
DEBUG PTR
(NONEI
HI''' STORAGt
0758Eu
Ell CEloLS
075Bco
~LC CELLS
(NONEJ
S8L CELLS
(NONEI
INDEX CELLS
(NONEI
(THR (SEE MI:MORY MAP) 075Bfu
075C1u
I.PSI=OCO('oOuo
Figure 86.
VALUE
0030C4C2
OOOOOOlA
00076176
3D02804B
00000000
00000000
00075C9C
00000000
0000
0000
04400000
000756B8
50077EFO
00000000
20000000
00000000
00075793
000758C8
00075C18
00000000
00000000
00000000
00000000
00000000
00000000
0000
00
00
40075f3C
6007839C
000756B8
00000558
00078098
SYSOUT
E3
80
OOOC
00075740
00000000
00000000
00075C9C
00000000
00075C98
00000000
000000
00000000
00000000
00000000
00000000
00074f80 00074890 50075F24
000758C8 00075688 00075758
00075C 18
600lFC3C 40075F3C 0007AA7() 00075900
0007AA iC 000 7AA 70 00076082 000156B8
50075F24
00075758
46075f36
58800108
00000000
01000000
500760E6
000756B8
00000000
00000000
00075900
00076082
000757F4
5820DlA 8
00000000
60075048
00075960
00000000
00000000
12D474E8
0007AA1C
0007AC10
F870D210
00000000
00075D8C
00018C80
00075758
00000000
00000000
0007AC10
0007BFE8
80075900
C0560700
00000000
00076F6A
0007795A
0007AA1C
00000000
00000000
00075900
000756B8
000000 1A
07F20000
00000000
00075DAO
80075900
00076082
00000000
OOOOOOlA
00075C9C
De FOFOOO
000009C8
00000000
00000000
00075900
000756B(I
00000000
000758CII
00015C18
00000000
00014EOO
00075D9E
OOOOOOlA
OOOOOOlA
00075C9C
00000000
00000000
00
00000000
000756B8 0007AA 70 00075758
00000000
00000000 00000D1C
00000000 00000000
00075779 00075793 00075DF6 00075DF6
OA00098A 15130000
tising the SYMDKP option to Debug
00000000 80075900 OOOODOO() 00000000
th~
Program TESTRUN (Part 8 of 11)
symbolic Debugging Features
227
DATA DIVISION DUMP OF TESTRUN
CARD
Lee
®
• 000017
LV NAME
TYPE
C151f4
Ci! 814
C15834
DCB
00002d
IKf1821
®
01 RECORO-l
02 fIELD-A
AN
UNINlTIALIZED OR INVALID BASE ADDRESS FOR DATA ITEM ABOVE.
• 0000ld
FD FILE-2
QSAM
(if 59()0
015920
DCB
015940
~C1"1O
P
C15158
C15 i 5A
C15160
000030
000037
000041.1
000044
01 RECORD-2
02 FIELD-A
77 KOUNT
77 NCMBER
00004~
01 FILLER
02 ALPHABET
02 ALPHA
00004j
000044
@---015160
0151t!
015162
01516.::1
015164
C/SltS
(15166
C15U7
015768
C15169
01576A
01 SHS
(/516e
C15160
C1516t:
C1516f
015710
C,5111
0;5712ClS"11..;
05174
Pigure 86.
228
FILE: CLOSED
ORGANIZATION: PHYSICAL SEQUENTI~L
LAST SUCCESSFUL 110 STMT: CLOSE
FILE STATUS: 00
00000000 00000000 00000000 00000006
00830000 0001AA01 00004000 000000
46000001 000757BC E2C1D4D7 03e54040
02000048 00000001 08000001 oooooe
00000000 00000001 00000001 00000001
00000014 00000001 00000000 000000
UNINITIALllED OR INVALID BASE ADDRESS FOR DATA ITEM ABOVE.
C!)~------~.~00002~
IKf1821
VALUE
QSAM
FD FILE-1
FILE: OPEN
ORGANIZATION: PHYSICAL SEQUENTIAL
LAST SUCCESSFUL 1/0 STMT: READ
FILE STATUS: 00
00000000 00000000 00000000 00000005
0083C300 0501AAOO 00004000 0007A8
46077F8C 900758C8 00ce4BOO 007DC414
12D474E~ 00BEI01B 01000001 000000
20202020 0007A920 0007AAD4 0007AA70
00000014 00000001 00000000 00~06A
AN
NB-S
NB-S
AN
"'AN
(SUBH
1
2
A 0001 NYC 0
+26
+26
ABCDEFGHIJKL~NOPQRSTUVWXYZ
3
A
B
C
4
5
D
E
6
F
7
8
9
10
G
H
11
12
13
14
15
16
17
18
19
20
21
I
J
K
L
M
N
o
P
Q
R
S
T
U
Using the SYMDMP option to DebQg the Program TESTBUN (Part 9 of 11)
DATA DIVISION DUMP OF TESTRUN
Lee
CARD
015175
C15116
C15777
(;; 5718
Ci 5719
01571A
00004j
000047
LV NAME
TYPE
22
23
24
25
20
02 DEPENDENTS
02 DEPEND
(SUBU--®
1
2
3
4
5
6
0571A
(15116
01571C
Ci511D
C; 571E
(; 571F
C1 ~ lea
Ci 51H
C151Si.
C; 51C~
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
C151BA
C; 518B
01518C
075780
Ci5HE
Oi578F
C,ii 5790
(ilS7H
(1575L
C,151S3
C1S7A2
000040
000049
OC005u
000054
00005,00005.;)
000054
015 7A3
DODOS:;
C151A5
C;51BC
(;5180
3
4
0
1
2
:3
4
0
1
2
3
4
0
1
2
3
4
0
1
2
10
0751S5
Cl5H6
0157e?
(B7El8
Ci51S9
000050
00005]
aC005d
00005~
01
02
02
02
02
02
02
02
02
3
4
0
WORK-RECORD ~
NAME-FIELD
FILLER
RECORD-NO
FILLER
LOCATION
fILLER
NO-OF-DEPENuENTS
FILLER
AN
AN
NO
AN
A
AN
AN
AN
01 RECORDA
02 A
02 B
CARD
LV NAME
A
0001
NYC
0
ND-OT
NP-S
+1234
*1*2*3*;:--0
FlF2F3C4
TYPE
VALUE
(HEX)
lOC
V
W
X
Y
Z
01234012340123401234012340
0
1
2
7
8
9
(i 51C4
(75158
(:;57«;5
0157SA
(ii51SE
C7 57Sf
AN
*AN
VALUE
END OF COBOL DIAGNOSTIC AIDS
Figure 86.
Using the SYMDMP Option to Debug the Program TESTRUN (Part 10 of 11)
Symbolic Debugging Features
229
IEC130I SYSDTERM DO STATEMENT MISSING
A 0001 NYC 0
B 0002 NYC 1
C 0003 NYC 2
D 0004 NYC 3
E 00·05 NYC 4
F 0006 NYC 0
G 0007 NYC 1
H 0008 NYC 2
I 0009 NYC 3
J 0010 NYC 4
K 0011 NYC 0
L 0012 NYC 1
M 0013 NYC 2
N 0014 NYC 3
o 0015 NYC 4
P 0016 NYC 0
Q 0017 NYC 1
R 0018 NYC 2
S 0019 NYC 3
T 0020 NYC 4
U 0021 NYC 0
V 0022 NYC 1
W 0023 NYC 2
X 0024 NYC 3
Y 0025 NYC 4
Z 0026 NYC 0
COMPLETION CODE - SYSTEM=OC7 USER=OOOO
IEF285I
SYS74162.T203933.RVOOO.TESTRUN.LMODLIB
PASSED
IEF285I
VOL SER NOS= DC151 •
IEF285I
VSCBL1.LIB
KEPT
IEF285I
VOL SER NOS= DB143 •
IEF285I
SYS74162.T203933.RVOOO.TESTRUN.SYMDBG
DELETED
IEF285I
VOL SER NOS= 333001.
IEF285I
SYS74162.T203933.SVOOO.TESTRUN.R0000021
SYSOUT
IEF2851
VOL SER NOS= 231400.
IEF285I
SYS74162.T203933.SVOOO.TESTRUN.R0000022
SYSOUT
IEF285I
VOL SER HOS= 33300l.
IEF2851
SYS74162.T203933.SVOOO.TESTRUN.R0000023
DELETED
IEF285I
VOL SER NOS= 333001.
IEF2851
SYS74162.T203933.SVOOO.TESTRUN.R0000024
DELETED
IEF285I
VOL SER NOS= 231400.
IEF285I
SYS74162.T203933.RVOOO.TESTRUN.R0000025
DELETED
IEF285I
VOL SER NOS= L00001.
IEF285I
SYS74162.T203933. RVOOO.TESTRUN. S0000026
SYSIN
IEF285I
VOL SER NOS= 231400.
IEF285I
SYS74162.T203933.RVOOO.TESTRUN.S0000026
DELETED
IEF285I
VOL SER NOS= 231400.
IEF373I STEP /GO
/ START 74162.2059
IEF3741 STEP /GO
/ STOP 74162.2105 CPU
OMIN 09.72SEC STOR VIRT
IEF285I
SYS74162.T203933.RVOOO.TESTRUN.LMODLIB
DELETED
IEF285I
VOL SER NOS= DC151 •
.LEF375I JOB /TESTRUN / START 74162.2054
IEF376I JOB /TESTRUN / STOP 74162.2105 CPU
OM IN 24.96SEC
Figure 86.
230
Using the SyftDMP
opti~n
64K
to Debug the Program TESTRUN (Part 11 of 11)
The compiler, linkage editor, COBOL load
module, and other system components can
produce output in the form of printed
listings, punched card decks, diagnostic or
informative messages, and data sets
directed to tape or mass storage devices.
This chapter describes the outpu t listings
that can be used to document ana debug
programs and the format of the output
modules.
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 a sample program.
The output of the compilation job step
may include:
•
A printed listing of the job control
statements
• Device allocation and deallocation
messages from the job scheduler
•
A printed listing of the statements
contained in the source module
•
A glossary of compiler-generated
information about data
•
A printed listing of the object code
• Compiler diagnostic messages
• System messages
• Disposition messages from the job
scheduler
• An object module
• A cross-reference listing
•
A cond ensed list ing containing source
card numbers and the location of the
generated instruction for each verb
• Compiler statistics
• Reformatted source code, either with or
without a compilation, through the
lister feature of the OS/VS COBOL
Compiler.
For details, see the chapter
"Lister Feature."
Diagnostic messages associated with the
compilation of the source program are
automatically generated as output. The
other forms of out put may be requested in
the PARM parameter in the EXEC statement.
The level of diagnostic messages printed
depends upon the FLAGW or FLAGE options.
All output to be listed is written on
the device specified by the SYSPRINT DD
statement.
Li.ne spacing of the source
listing and the number of lines per page
can be controlled by the SPACEn and LINECNT
options.
Figure 87 contains a portion of the
compiler output listing shown in "Appendix
A:
Sample Program Output. It Each type of
output is numbered. and each format within
each type is lettered. The text following
Figure 87 is an explanation of the
illustration.
output
231
IIT~STRUN
JOB
II
MSGClASS=~
***~ETUP
II
II
II
II
II
CD
EXEC
TAPE SCRTCH
CVS2'OCl G,
1550 J63',MSGlEVEl=(1,1),ClASS=A,
llMVS037
RING=YES
PARM.tOB='uMAP,P~AP,SXREF,FlOW~10,SV~DMP,QUGTE,NJRES',
GODMP='SYSuUT=S',
SYSUT5='&&SY~UT5,DISP=(,PASS)',
PARM.lKED='lISf,lET,XREF'
XXCVS20ClG PROC PROG=I~FCBLOO,
XX ~OBDMP='SYSOUT=A',
XX "UDMP=DUMMY,
XX PARMCOB='lOA',RGN~Oo=128K,CONDCOB='(16,lT)',
XX PARMlKD='lIST,XREf,LcT',RGNlKED=128K,CONOLKD='(5,lT,COB)',
XX PARMGO=",RGNGO=l~2K,CONOGO='(5,lT,COB),(5,lT,lKEDJJ',
XX ~OSET='&GOSET',GO='Gu',
XX ~1=CBLCOMPl,V1=C~LDEV,U1=SYSDA,
XX ~~=CBLCOMPl,V2=C8lDEV,U2=SYSDA,
XX ~3=CBlUPM,V3=CBlD~V,U3=SVSDA,
XX S4=CVS20LIB,V4=CBLDEV,U4=SYSDA,
XX ~5=CVS20lIB,V5=C8LDEW,U5=SVSDA,
XX ~6=CVS20lIB,V6=CBLDEV,U6=SYSDA,
XX ~7=CVS20lIB,V7=C8LDcV,U7=SYSDA,
XX ~8=CVS20lIB,V8=CBLDEV,UB=SYSDA,
XX ~9=CVS20lIB,V9='ScR=:Bl)EV',U9=SYSDA,
XX ~10='SYS1.lINKlIB',V10=,J10=
XXCuB EXEC PGM=&PROG,RE~ION=&R~NCOB,COND=&CONDCOB,
XX PARM='lOA,NOLIB,SlZE=128K,BUF=12K,P~A,D~A,SXR,OPT,RES,&P~RM:OB'
XXSTEPLIB DO DSN=&S1,VOL=SER=&V1,UNIT=&U1,DISP=SHR
XX
DO DSN=&S2,VOL=SER=&V2,UNIT=&U2,DISP=SHR
XX
DO bSN=&S3,VGL=SER=&V3,UNIT=&U3,DISP=SHR
IICuB.SYSPRINT DO ~YSuUT=S
X/S~SPRINT
DO SYSOUT=A
XXSYSUDUMP 00 &COBDMP
XXSYSUT1 DO UNIT=SYSuA,SPACE=(TRK,(25,3),JSN=&SYSUT1
XXSYSUT2 DO UNIT=SYSuA,SPA:E=(TRK,(25,3)),DSN=&SYSUT2
XXSYSUT3 DO UNIT=SYSvA,SPACE=(TRK,(25,3)),DSN=&SYSUT3
XXStSUT~ DO UNIT=SYSuA,SPACE=(TRK,(25,3)),)SN=&SYSUT4
XXStSUT5 DO UNIT=SYSuA,SPACE=(TRK,(25,3)),DSN=&SYSUT5
XXSYSUT6 DO UNIT=SYSuA,SP~:E=(TRK,(25,3»,DSN=&SYSUT6
XXSYSlIN 00 DSNAME=&~OAuSET,OISP=(MOD,PASS) ,UNIT=SYSD~,
XX ~PACE=(80,(500,10v))
IICub.SYSIN DO *
IEf23bI
IEF237I
IEf2311
IEf237I
IEF237I
IEF237I
IEF237I
IEFt37I
IEf237I
IEF237I
IEf237I
IEF2371
IEF237I
IEf237I
ALLOC. FOR TESTRUN C08
5CO ALLOCATED TO STEPl,B
5CO ALLOCATED TO
5CO ALLOCATED TO
JES ALLOCATED TO SYSPR!NT
JES ALLOCATED TO SYSUOJ~P
272 ALLOCATED TO SYSUT~
150 ALLOCATED TO SYSUT~
272 ALLOCATED TO SYSUi~
272 ALLOCATED TO SYSUT~
272 ALLOCATED TO SYSUT~
272 ALLOCATlD TO SYSUTc
272. ALLUCATED TO SYSUN
JES ALLOCATED TO SYSIN
Figure 87.
232
('A=~C~O'),'BETHKE
Examples of Compiler Output (Part 1 of 4)
00001000
00002000
00:)03000
OOOOftOOO
00005000
00006000
00007000
00008000
00009000
00010000
00011000
00012000
00013000
0001ftOOO
00015000
03016000
00017000
03:>27000
00028000
00029000
00030000
00031000
00032000
00033000
OOOHOOO
00035000
00036000
00037000
00038000
J0039000
00040000
00041000
.)(,(.01
J(002
Gu(03
10(01IJ IOENTIFICATION uIVISION.
Tt~TkUN.
WOu2" PROGRAM-IO.
10003IJ
AUTHOR. PROGRAMMLR ~AME.
INSTALLATION. PALO ALTO O~VELOPMENT CENTER.
10u04"
1 0005.)
DATE WRITHN. AJGLlST c, 1976.
10GOt,u DATe-COMPILED. ~UG l4,1976
J(,(;~4
J(,C';5
oece6
Que C2
10074u STEP-7. IF NO-Gr-JtPENOENTS IS EQUAL TO "0" MOVE "Z" TO
lJU751J
NO-OF-OcPENIJE~T!). EXI-'IBIT NAMED 1I0RK-RECORD. GO TO
100701.1
ST=P-6.
10017u STEP-B. CLOSE FlLt-2.
le07tlv
STOP RUIIl.
U..JC E3
COC/:4
00Cb
Ju0co
o
®CD
INTKNl IMr-IE
DNM=1- ... 'ttl
Otl.M=I-,,('8
LVL
FO
01
02
FO
01
02
ON1~=1-.d;j9
CD
ONM=i-c;.u6
ONM=1-",..:6
DNM=1-,.;,. 7
ON "1 =.i.-", ° 7
DNI1= 1-.. 02
ONM=1-.. ~B
DNM=l-JLl
ONM=l-.;.jQ
01'11'1=1-.;)48
DNM=1-.;;c, 8
ONM=1-.d34
ONM=1-"?utl
ONM=1- ... 28
ON'1=1-'t42
ONM=1-"?61
DNM=1-"?7!>
ONM=l-4':13
77
77
01
(2
02
02
02
01
02
02
02
02
02
02
02
02
01
02
02
DN:~=2-",00
ON'1=",-u<:6
ONM=<:-IJ40
01'11'1=2-.)00
ONM=2- . .t11
CD CD
SOURC", '44ME
F IL E-L
RECORu-i
FIELlJ-A
F IlE-,
RECOR..,-Z
FIELD-A
KOUNT
NOMB£n.
F [LLE~
AlPHAoET
ALPHA
OEP':NuENTS
DEPEN.;
BAS E
OCB=OI
Bl= 1
Bl=1
OCf:\=02
Bl=2
BL=2
P·L=3
Bl=3
E1L=3
BL=3
PL=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
WORK-I\E~JkO
NAME-t-Ie:lD
FILLcl\
RECORu-i~u
FIlU:K
LOCAT!u'<
FILlEK
NO-OF-DEPENDENTS
FILLtK
RECOR.)A
A
B
DISH
000
003
000
000
000
002
008
008
008
022
022
040
040
041
042
046
041
04A
04B
040
058
058
058
CD
I NTRNl NAME
DNM=1-148
0·"1 .... = 1-168
ONM=1-1B'3
)NM=1-206
ONM=1-226
DNM=1-247
0~11= 1-267
DNM=I-282
ONM=i-2Q8
DNM=1-312
DNM= 1-3 30
)~"'=1-348
DNM= 1-368
JIIlM=1-384
0'4"'=1-408
DNM=1-428
DNM=1-442
DNM=1-461
ONM=1-475
O~"'= 1-493
ONM=2-000
ONM= 2-026
DNM=2-040
DNM=2-060
GN~=2-071
CD
DEFI'HTlO\j
OS O:LZO
OS 2J(
OS
OS
OS
OS
OS
OS
OS
OS
OS
OS
JS
OS
OS
OS
OS
OS
DS
OS
OS
DS
OS
OCL20
2J(
1-i
IH
OCL52
26C
lC
2t..~
1C
OCl20
1:
IC
4:
IC
3C
1:
2(
1C
OCL4
4C
4P
CD
JSClGE
QSb.M
:;POUP
DJSP
QSAM
R
CD
J
;t
M
F
GP~UP
DIS P
C(l!olP
CQ"IP
GROUP
OISP
[lISP
OISP
)JSP
GROLJP
JISP
DISP
(1
J
[,ISP-~IM
OISP
C'ISP
OISP
()ISP
DISP
GPOUP
DISP-NM
COMP-3
MEMOR¥ MAP
CD
00318
TGT
SAVe: AREA
SWITCH
TALLY
SJRT SAVE
ENTRY-SAVE
00318
00360
00364
00368
0036C
00370
SORT CORE SIZE
lITERAL PLOl (HEX)
00000001
00044000
00:> t:!ll (l IT +0 J
C C5Cl;l (LI 1+Z .. )
DI~PLAY
0"lAIC10
0IJOuuv00
PGT
DEBUG LINKAGE A~EA
OVEkFLOW CELLS
VIRTUAL CEllS
PKUCEOURE NAME ~ELLS
GENEKATED NAME ~ELlS
OCB AuORESS CELLS
VNI CELLS
LITERAL S
iJ[ SPLAY LITERAl~
PROCEDURE BlOC~ CELLS
I
RE ... 6
xEG 7
REG 8
OOOOODOO
48140000
'\o/ORK-RECiJRu'
CD
REGISTER
00000008
LITERALS (BCl))
(iC5D4 (lTl+3,,)
CD
0000001C
COOOOOOO
AS~l
00560
00560
0056C
00570
0059C
0059C
005AO
005A8
005BO
00504
D05EO
GNMEIH
/jl =3
t3L =1
til =2
(D..lORKING-STLJRII ... E STAf
00060A
000610
0006.14
58 FO C 024
05 IF
00uOO040
58 fO C 028
05 ft5d III C 040
50 40 1 024
0": O~ 4011 C 020
511 10 D 234
92- Of o 234
5t1 BO C 080
FCi C 02 ..
0.5 If
sa
®
EQU
EQU
l
L
bALR
DC
*
*
11 ,oao( 0,121
15,024(0,12)
1,15
X'OOOOO030'
EQU
L
BALR
DC
L
BALR
L
L
MVC
ST
MVI
*
15,024( 0,12)
1,15
X'OOOOO040'
15,028(0,12)
H,15
1,040(0,12)
4,024(:),1)
01113,4) ,020(12)
1,23"( 0, 13)
234(13),X'OF'
*STEP-l
CD
6ft
DPEN
*S1AT1STICS*
saURCE
*OPTIONS IN ErfECT*
*OPTIUNS IN EFfECT*
*UPTIONS IN ErfECT*
*OPTluNS IN ErfECT*
*OPTIDNS IN EffECT*
*OPTIUNS IN EifECT*
*OPTIUNS IN EffECT*
PN=03
OTA NAME,)
OEFN
A
ALPHA
ALPI-ABET
DEPENDENTS
FIELO-A
FIELO-A
fiLE-l
FlLE-2
KOl;NT
LOCATION
(;00058
000044
.;00043
,,00059
000041
.100045
;)00029
()00037
000011
000C18
liJOO40
1100053
N~ME-FIELO
:JOO049
ND-Of-DEPENOLNTS
!,;CM8ER
RECORD-NO
RECOKD-l
RECCRD-2
RECGKDA
WCRK-RECORD
000055
UOO041
000051
000028
1100036
000051
liOO048
PROCeDURE "'AMeS
!-EFN
B
OcPE'~D
t
BEGIN
STEP-l
STEP-2
STEP-3
STEP-4
STEP-5
STEP-6
STEP-7
STEP-8
Figure 87.
234
VI IlBOflWlI
V( IlBOOB(4)
DCB=l
V(tLBOEXTO)
SA3=1
SA3'"'1
RECORDa
86
DATA DIVISION STA1EMfNTS =
25
PROCEDURE DIVISION SrArE~ENTS =
21
SIZE = 1~1072 BUF
12288 LINECNT = 57 SPACEl, FLAGW,
SEQ,
SOURCE
DHAP,
PMAP, NOCLIST, NOSUPMAP, NOXREF,
SXREF,
LOAD, NODECK, QUOTE, ~OTPJN:,
FLO~=
10
NOTEkM, NONUM, NOBATCH, NONA~E, COMPILE=Ol, NOSTATE, NJREStDENT, NODYNAM, NDLI8, NQSYNTAX
OPTI~IL~,
SYMDMP, NOTEST,
VERB,
lWB, SYST, NOE~DJOB, NJLVL
NOLST , ~JFOfCK,NOCDECK, LeOL2,
L120,
DUMP, NOADV , NOPRtNT,
~OCOUNI, NOVBSUM, NOVBREF, LANGLVL(2)
DEBUG rlL~ SIZE = 2
tiLOCKS, 1024
BYTES
CROSS-REFERENCE DieT IONARY
®
PBl=l
V( IlBOFUHI
REFERENCE
000068
000081
000070
0000b4
000011
000064
000068
000010
000064
000071
000072
000080
000012
000012
000080
000068
000077
000085
000010
OU0082
000068
000071
000080
000083
000014
REFERENCE
000061
OOOCl64
000068
000072
CiuOO74
000077
000080
,,00082
000085
000014
000074
000083
000080
Examples of Compiler Output '(Part 3 of 4)
CARD
I
®S58
@
ERROR MESSAGE
IKFIOu71-W
IKF21~01-W
I EF1421 TESlRJN COB - STEP WAS EXECUTED - COND CODE 0004
IEF28S1
('tlL .. .:Jt1PL
KEPT
IEf2851
VOL SER NOS= CBLDEV.
IEf2851
CliL(;UMPL
KEPT
IEF28.:11
VOL ~E~ NOS= CBLDEV.
I EF285I
CBLJPM
KEPT
I EFldSl
VOL SER NOS= CBLDEV.
I Ef28'!:)I
JES~.JOBOOOS9.S00103
SYSOUT
I CF2851
JES~.JOBOOO59.S00104
SYSOUT
I EF285 I
SYS70237.T091056.RAOuO.TEST~UN.SYSUTl
DE LETED
I EF285I
VOL SER NOS= 222222.
lEF285I
SYS/o237.T0910S6.RAOuO.TESTRUN.SYSUT2
DELETED
IEf285I
VOL SER NOS= 000000.
I Ef265I
SYS7b237.T091J56.RAOuO.TESTRUN.SYSUT3
DELETED
IEF28S1
VOL SER NOS= 222222.
1 Ef285 I
SYSlb237.T09105b.RAOuD.TESTRUN.SYSUT4
DELETED
IEf285I
VOL SER NOS= 22222~.
I EF285 I
SYSlb237.T091056.RAOvO.TESTRUN.SYSUT5
PASSED
lEf2851
VOL SER NOS= 222222.
I Ef28S1
SYS76237.T091056.RAOuO.TESTRUN.SYSUT6
DELETED
I Ef285 I
VOL SER NOS= 222222.
IH2S~1
SYSlo237.T091056.RA~vO.TESTRUN.LOADSET
PASSED
IEF285I
VOL SER NOS= 22.2222.
IEF2851
JtS~.JOBOOOS9.S10101
SYSIN
IEf37~I STEP IGOB
/ START 761:.:'7.0910
IEF37Z
HrTl~~'
IUOOB:;
1L H'(l'f'~
IlBOOBr.~
171f,
30F~
I~
IlB~O%O
Il'OFlHl
ILSJEKTO
1L'005PO
Il80COMO
5&(
5Q4
IL~OFl"
zou
llP(OFl~
[UI'E1T
1l~(1PSP
[UI'COMO
Ile~Fl~
$U"PESOlVEPt H I
IHOtO.O
IlP(1PEG
$U~~ESOlVEOI HI
®
~g~~ ~~T EXIST "~~ "AS ~E£ hi AuOtO TO PArA SFT
STEP WA ... c.XC:CUTEl' - CONO cooe 0000
,YSloZ37. TO~1056.PAu"O.1 Eo T"U~.LOAJSET
OEUTl U
lEfl't,d TESTP.JN lKt:O [~F~.~I
ltf2H!)1
I r:fL8:.> J
PA5SfO
IEfl~,1
RAuIolO.llSTfI ur-.. GOSET
VUl SEI< M1S= VOOOOO.
B
VLl Hk ~US= CHlOEV.
\~:~:;~
~~~~~~!B;'U5=
KEPT
IEF2d~1
I 7.v·nl
IfF.H"t1 STI.:P IlKEO
/ ~Tl1P
1t- ... .;)7.0-l11 cpu
QMJI'-l
$E:K
~y~ ICJ~.J
Figure 91.
1.
KEPT
CblOioV.
OFLE1t:LJ
SYSOJT
::)1.5'J~FT
Vlj.,-T
Linkage Editor putpu t Show ing !!Iodule ttap and Cross-Reference List
Ih~ob
control statements. These
statements are listed because
ftSGLEVEL= (1,1) is specified on the JOB
statement for this job, shown in
Figure 87.
3.
This message lists the FARM options
that vere specified.
4.
2.
Allocation messages from the joh
These messages provide
information about the device
allocation for the data - sets in the
job step. For example, the message
schedul~.
.IEF2311
~inka~~~ilQ~_!nt~ative~~ssaq~.
Linka~editor
informative messag~.
This is a disposition message
describing the disposition of the load
module.
A.
Name of the load module specified
in the DSNAME parameter of the
SYSLftOD DD statement
B.
Text of message
230 ALLOCATED TO SYSUT1
indicates that the data set for SYSUT1
has been assigned to the device 230.
output
'241
5.
~~~~aE.
The module map is listed
when either the XREF or the MAP option
is specified in linkage editor
processing. The module map shows all
control sections in the output module
and all entry names in each control
section. The control sections are
arranged in ascending order according
to their assigned origins. All entry
names are listed below the control
section in which they are defined.
Each COBOL program is a control
section, and any COBOL library
subroutine is a separate control
section (except as noted under
segmentation) •
A.
B.
C.
D.
6.
2~2
Ent~I.
The entry names within
each control section and their
relative location.
A called
program may have more thaD one
entry point. For a called COBOL
program, the entry points are the
same as the names specified by the
ENTRY statements in the source
program.
Entry addr~§2. The relative
address of the instruction with
which processing of the module
begins.
It will alvays be lNIT1
if the COBOL program is the main
program of the load module.
1Qial lengill. The total number of
bytes, in hexadecimal notation, of
the load module. It is the sum of
the lengths of all control
sections.
Location. The relative location
In the-Program where another
program is called.
B.
~I.mbol referg!!£~.
c.
In control section. The control
se;;tiontbatcOntains the entry
point.
The name of the
entry point of the called program.
For example,
4~O
is the location where
a COBOL subroutine is called.
ILBOSRV1 is the entry point of the
called program.
ILBOSRVO is the
control section that contains the
entry point ILBOSTP1.
~n1!Q!_2~£tiQn.
Under this
heading the name, origin, and
length of each control section is
listed.
Name. The name of the control
section. This name is the
PROGBAM-ID name in the main COBOL
program or a called program. Each
control section that is obtained
from a library by an automatic
library call is indicated by an
asterisk.
2£igin. The relative origin in
hexadecimal notation.
~~g!h.
The number of bytes in
each control section in
hexadecimal notation.
A.
If IBEY is specified, the cross
reference list appears before the
Entry Address.
7.
Q!§RQ§itiQD_~~~gg~_!~Q!_the-iQQ
~ch~!~~.
These messages contain
information about the disposition of
the data sets.
COll!ll!1LQIL th~gy.l!LJ1Sl.R._9.nd
~.fg~n~~_1i~1
CrQ,§2
The severity of linkaqe editor
diagnostic messages may affect the
production of the module map and the cross
reference list.
Since various processing options will
affect the structure of the load module,
the text of the module map and cross
reference list viII sometimes provide
additional information. For example, the
load module may have an overlay structure.
In this case, a module map will be listed
for each segment in the overlay structure.
The cross reference list is the same as
that previously discussed, except that
segment numbers also are listed to indicate
the segment in which each symbol appears.
1!st!Qg_!h~nkag~_lditor control
~~a~gs~!!§:
If the LIST option is
specified, linkage editor control
statements, such as OVERLAY and LIBRARY,
are listed.
Cro.2§~efeu!!£~-1J&1.
T.he cross
reference list, as well as a module
map, is listed if the .XREF option is
specified. The ftlP and IREF options
should not be specified together. The
cross reference list provides the
following information:
The linkage editor generates tvo types
of messages: module disposition messages
and error/warning messages.
A description
of the messages can be found in the
publication OSL~_ki.nka~_!gitor and
~a£~~.
A complete list of the
error/warning messages is included in the
publication OS/ll_Ke§sag~LibrarI':
Linkll~
• A syst em dUllp
!~!.t.2LAn~g~_"e§gg~.
• Debugging information
~:
Loader output consists of a collection
of diagnostic and error messages, and, if
KAP is specified, a storage map of the
loaded program. The output data set,
SYSLOUT is sequential and blocked as
specified by the user in the-DCB. For
better performance, the user can also
specify the number of buffers to be
allocated.
Diagnostic messages include a loader
heading and a list of options requested by
the user.
The error messages, identifying
the source of error, will be written when
the error is detected.
After processing is
complete, an explanation of the error will
be written.
A complete list of loader
error messages is found in the publication
Q~LVS Message L~ll:LL-1i!l1s~e Editor a.ug
LogdeJ;:_~2§gg§·
The map includes the name and absolute
address for each control section and entry
point defined in the program. It is
vr it ten on S ISLOUT concurren tIy vith input
processing so it appears in order of input
ESD items.
The total size and storage
extent also are included. Figure 92 is an
example of a module map.
If a program ends abnormally and
one of the options FLOW, STATE, or SYMDMP
is in effect and the SYSDBOUT DD card has
been included, debugg ing informa tion
appears in the program listing (see the
chapter entitled "Symbolic Debugging
Features").
A dump as well as system diagnostic
messages are generated automatically if a
program contains errors that cause abnormal
termination.
l!Q:t~:
If a COBOL program abnormally
terminates, then a formatted dump is
provided for all COBOL programs compiled
with the SyftDMP option which could include
the abnormally terminating program and its
callers, up to and including the main
program.
For a discussion of the SYMDMP
option as well as of other COBOL symbolic
debugging options, see the chapter entitled
"Symbolic Debugging Features."
Figure 93 shows an example of output
from the execution job step. The following
text is an explanation of the illustration.
1.
Ih~_job_£Qni~Q!_§tate~gnt§.
These
statements are listed because
MSGLEVEL=(1,1) is specified in the JOB
statement for this job.
2.
Ihe_job~!lQ£~liQn..J!g§saggs f£Q.ID._th~
jQ~2chedy!g£.
These messages indicate the device that is allocated for
each data set defined for the job
step.
The output generated by program
execution (in addition to data written in
program output files) can include:
3.
~i22Q§iiiQn_ID.g§§a~ga_t£Q~thg-iQ.h
4.
R£Qg!:il_Q!!i.2y.i_Q!t_I?!::!.llig£.
5.
~2!!..2Q.le
• Data displayed on the console, or on
the printer
• Cards
• Messages to the operator
• system informative messages
• system diagnostic messa;e
2£h~d~le£.
These messages are
contained in the as/vs message
library.
.
The
results of execution of the TRACE and
EXHIBIT NAMED statements appear on
program listing.
outI!ui.
Data is printed on
console as a result of execution of
DISPLAY UPON CONSOLE.
output
243
VS LOADER
OPTIONS USED - PRINT.MAP.LET,CALL.RES,NOTERM,SIZE=98304,NAME=**GO
NAME
TYPE
ADDR
TYPE
NAME
TESTRUN
SD 60010
INCLUDE SYSLIB(ILBODSP)
IEW1141
ILBOCOM *
ILBOCOMO* SD 60940
ILBOSR *
ILBOSRS * LR 60A3A
ILBODSP *
ILBOSTPO* LR 60A42
ILBOEXTO* LR 61SA2
ILBODBG *
ILBODBG4*
ILBODBG3* LR 615CE
I LBOFLW2 *
ILBOFLW1* LR 621FE
ILBOBEGO* LR 6277A
ILBOCMM *
TOTAL LENGTH
ENTRY ADDRESS
IEW1141
60940
60A3A
60DCO
615CO
61502
62202
627E8
NAME
ILBOSRV *
ILBOSRV1*
ILBODSPO*
ILBODBGO*
ILBODBG5*
ILBOMSG *
ILBOCMMO*
2B68
60010
WARNING - CARD RECEIVED NOT AN OBJECT RECORD
Figure 92.
244
LR
LR
SD
SO
LR
LR
SO
ADDR
Module Map Format Example
TYPE
SD
LR
LR
LR
LR
SD
LR
ADDR
60AOO
60A3E
60DC2
615C2
61506
62678
627EA
NAME
ILBOSRVO*
ILBOSTP1*
ILBODSSO*
ILBODBG1*
ILBOFLW *
ILBOMSGO*
I LBOCMM1 *
TYPE
LR
LR
LR
LR
SO
LR
LR
ADDR
60A3A
60A3E
60DC2
61SC6
621F8
6267A
627EE
NAME
ILBOSR3 *
ILBOST *
ILBOEXT *
ILBODBG2*
ILBOFLWO*
ILBOBEG *
TYPE
LR
LR
SD
LR
LR
SD
ADDR
60A3A
60A42
615AO
61SCA
621FA
62778
-_
IEf2361 ALLOC. FOR TESTRUN GO
IEF2371 232
ALLOCATED TO PGM= •• DD
IEF237I 235
ALLOCATED TO STEPLIB
IEP237I 250
ALLOCATED TO DD1
IEf2371 250
ALLOCATED TO SYSDBOUT
IE.2371 250
ALLOCATED TO SYSUDUMP
IEl237I 250
ALLOCATED TO SYSOUT
IEJi2371 250
ALLOCATED TO SYSPUNCH
n:f2371 582
ALLOCATED TO SAMPLE
lXGO
EXEC PGM= •• LKED.SYSLMOD.COND=((5,LT.COE). (5.LT.LKED»
XXSTEPLIB DD DSN=VSCBL1. LIB, DISP=SHR. UNIT=2314. VOL=SER=DB143
XXDDl
DD DSN=iSYMDBG.DISP=(QLD.DELETE)
/ ;GO. SYSDBOUT DD SYSOUT=G
x/SYSDBOUT DD SYSOUT=A
I/GO. SYSUDUMP DD SYSOUT=G
X/SYSUDUMP DD SYSOUT=A
/IGO.SYSOUT DD SYSOUT=G
X/SYSCUT
DD SYSOUT=A
XXSYSPUNCH DD SYSOUT=E
,l/GO.SAMI?:t,E DD UNIT=240Q.),Al;!EL=(.I!!:t..).DISP=(NEW.DELETE)
WORK-RECORD
WCRK-RECORD
WORK-RECORD
WORK-RECORD
WORK-RECORD
WCRK-RECORC
WORK-RECORD
WCRK-RECORD
WORK-RECORD
WCRK-RECORD
WORK-RECORD
WCRK-RECORD
WORK-RECORD
WOR1I:-RECORD
WORK-RECORD
WORK-RECORD
WORK-RECORD
WOR1I:-RECORD
WORK-RECORD
WCRK-RECORD
WOR1I:-RECORD
WORK-RECORD
WORK-RECORD
WOR1I:-RECORD
WORK-RECORD
WORK-RECORD
=
=
=
=
=
=
=
=
=
=
A
B
C
D
E
F
G
H
I
J
= K
= L
= M
= N
= 0
= P
= Q
= R
= S
= T
= U
= V
= W
= X
= Y
= Z
0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
0015
0016
0017
0018
0019
0020
0021
0022
0023
0024
0025
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
00800300
00800310
00800320
00800330
Z
1
2
3
4
Z
1
2
3
4
Z
1
2
3
4
3
4
Z
1
2
3
4
Z
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
11: 0011 NYC 0
L 0012 NYC 1
M 0013 NYC 2
N 0014 NYC 3
o 0015 NYC 4
P 0016 NYC 0
Q 0017 NYC 1
R 0018 NYC 2
S 0019 NYC 3
T 0020 NYC 4
U 0021 NYC 0
V 0022 NYC 1
W 0023 NYC 2
X 0024 NYC 3
Y 0025 NYC 4
Z 0026 NYC 0
IEF1421 - STEP WAS EXECUTED - COND CODE 0000
IEf2851
SYS74163. T204211. RVOOO. TESTRUN. LMODLIB
PASSED
IEf285I
VOL SER NOS= 231402.
IEf2851
V5CBLl. LIB
KEPT
IEF2851
VOL SER NOS= DB143 •
IEf2851
SYS74163.T204211.RVOOO.TESTRUN.SYMDBG
DELETED
IEf2851
VOL SER NOS= 333001.
IEf2851
SYS74163.T204211. SVOOO.TESTRUN. ROOOOOll
SYSOUT
IEf2851
VOL SER NOS= 333001.
IEf2851
SYS74163. T204211. SVOOO. TESTRUN. R0000012
DELETED
IEf2851
VOL SER NOS= 333001.
IEf2851
SYS74163. T204211. SVOOO.TESTRUN. R0000013
SYSOUT
IEF2851
VOL' SER NOS= 333001.
IEF2851
SYS74163.T204211.SVOOO.TE5TRUN. R0000014
DELETED
IEf2851
VOL SER NOS= 333001.
IEf2851
SYS74163.T204211.RVOOO.TESTRUN. R0000015
DELETED
IEF2851
VOL SER NOS= L00001.
IEF2851
SYS7416 3. T204211. RVOOO. TE5TRUN. S0000016
SYSIN
IEF2851
VOL SER NOS= 333001.
IEF2851
SYS74163.T204211.RVOOO.TESTRUN.50000016
DELETED
IEF2851
VOL SER NOS= 333001.
IEF373ISTEP /GO
I START 74163.2056
n.F3741 STEP ;GO
/ STOP 74163.2109 CPU
OMIN 09.47SEC STOR VIRT
IEf2851
5YS74163. T204211. RVOOO. TESTRUN. LMODLIB
DELETED
IEF2851
VOL SER NOS= 231402.
IEF3751 JOB /TESTRUN I START 74163.2046
IEF3761 JOB /TESTRUN / STOP 74163.2109 CPU
OMIN 24. 47SEC
Figure 93.
00800270
00800280
00800290
6411:
Execution Job step output
output
245
Both SYSUDUMP and SYSABEND viII
usually produce the following whe~ an
abnormal termination occurs: some
system control blocks~ work areas (in
addition to user modules), and system
modules, and--under VS2--GTF trace
records if that system service is
running. SYSABEND normally also
produces the system nucleus.
REQUESTS FOR OUTPUT
1.
The programmer can request data to be
displayed by using the DISPLAY
statement and including the following
in the job control procedure:
//SYSOUT
2.
3.
DD
SYSOUT=A
Message to the operator can also be
displayed on the console when
requested in th e so urca program
(DISPLAY UPON CONSOLE').
The programmer can request debugging
informa tioD in case of an abnormal
termination by specifying FLOW, STATE,
or SYMDMP and including the following
in the job control procedure:
//SYSDBOUT
DD
SYSOUT=A
In addition, the SYSUT5 DD statement
is required for compilation and the
SYSDBG DD statement is required at
execu tion time.
Dumps and debugging facilities are further
'explained in "Program Checkout. ff
OPERATOR MESSAGES
The COBO.L load module may issue opera tor
messages. A complete list of these
messages and required operator responses
can be found in "Appendix K: Diagnostic
Messages.·' MCS considerations are
discussed there also.
The following DD statement must be
used to make the COBOL library module
ILBOBEG available at execution time.
/ /STEPLIB DD DS N=subr-libname, DISP=SHR
If an error message is printed by the
debugging modules, the COBOL library
module ILBOBEG is loaded dynamically
from the subroutine library. This
module is not link edited into the
COBOL object program.
By specifying- a //SYSDTERM DD card in
addition to the //SYSDBOUT DD card,
dynamic dump output will be written
onto SYSDTERM while the abend dump
output will go to SYSDBOUT.
l!Q.ig: The TSO programmer should assign
SYSDTERM to the terminal since dynamic dump
output is interruptable. 5YSDBOUT should
be assigned to a direct access data set
which could be listed at the terminal after
the ABEND is complete.
~.
The programmer can request a full
dump, in case his program is
terminated abnormally, by including
one of the following in the job
control procedure:
either
Informative and diagnostic messages may
appear in the listing during execution of
any job step. Further information about
system diagnostics is found in the
appropriate~LIS._!esg~_t.ib£ary
publication. COBOL messages and associated
documentation forth is compiler can be
displayed by running the.ERRMSG program
described earlier in "Output ...
Each of these messages contains an
identification code in the first three
columns of the message to indicate the
portion of the operating system that
generated the message. Figure 94 lists
these codes, along with an identification
of each.
,
,Code
I
,ICE
,lEA
,IEC
,IEF
IIKF
IIER
I lEW
11GB
/ /SYSUDUMP DD SYSOUT= A
or
/ /SY5 ABEND :DD SYSOUT=A
246
•
,
i
I
I
I
I
I
I
I
I
f
,
Identification
A
A
A
A
A
A
A
1
Figure 94.
message
message
message
message
message
message
message
message
from
from
from
from
from
from
from
from
,I
the Sort program.
I
the supervisor.
I
data management.
I
the job scheduler. I
the COBOL compiler.,
the Sort Program.
I
the linkage edt tor. ,
the Sort prograll.
•
J
System Message Identification
Codes
A programmer using the COBOL compiler
under OS/VS has several methods available
to him for testing and debugging his
programs or revising thea for increased
efficiency of operation.
The lister feature provides the COBOL
programmer with reformatted source code
that contains complete cross-reference
information at the source level.
TEST has the following effects on other
compiler options: TEST overrides FLOW,
STATE, SY!DKP and COUNT. However, BATCH
overrides TEST. TEST is also overridden if
the source program contains USE FOR
DEBUGGING and WITH DEBUGGING MODE
statements.
TEST requires the debug file, SYSUT5.
The syntax-checking options can be
specified to save progra mmer and machine
time while checking the source statements
for syntax errors.
The COBOL debugging language can be used
by itself or in conjunction with other
COBOL statements. A dump can also be used
for program checkout. For a discussion of
the COBOL symbolic debugging options, see
the chapter entitle~ "Symbolic Debugging
Features."
The execution frequency statistics
option, COUNT, facilitates testing,
debugging# and optimizing by causing verb
execution counts to be generated at the end
of the execution of a compiled program.
The statistics provide the COBOL programmer
with information that aids user program
optimization by identifying heavily-used
portions of the COBOL source program. They
are also useful to the programmer in
debugging by providing verification that
all parts of a program have been executed.
The program product IBM OS COBOL
Interactive Debug (Program Number S734-CB4)
enables the user to debug his COBOL
programs from a terminal under TSO, the
Time Sharing Option of thoe operating
System. with its own debugging command
language, Interactive Debug gives the user
several object-time debugging capabilities
including: starting and stopping program
execution at selected points, altering the
logical floll of prog ram execution,
manipUlating data, and displaying such
things as selected source statements, file
status and content, and various kinds of
program execution traces. How to
accomplish these operations is described
fully in IBM-2LCOBOLI!l~il,£tive Debug
121~:
%~~:!ina 1 u§g£'~ig!LaJ!~fer~1l£~.
Specifying the TEST compiler option allows
a COBOL program to be debugged by the
Interactive Debug user. A program that is
compiled without the TEST option is
unacceptab leta the Interactive Debug
command processor.
When the user requests the lister
·feature, each COBOL statement is begun on a
'new line and is indented in such a way as
to make tke logie of the program readily
apparent by highlighting level numbers,
nested IF statements, etc. For complete
information, see the chapter "Lister
Feature. "
SYNTAX-CHECKING
ON~CO~I1!!ION
The compiler checks the source text for
syntax errors and then generates the
appropriate error messages, but does not
botber to produce object code. With the
syntaX-Checking feature, the programmer can
request a compilation either conditionally,
with object code produced only if no
messages or just w- or C-level messages are
generated, or unconditionally, with no
object code produced regardless of message
level.
For a discussion of the syntaX-Checking
options, SYNTAX and CSYNTAX, see the
section "Options for the Compiler" under
"Job Control Procedures."
The COBOL debugging language is designed
to aid the COBOL programmer in producing an
error-free program in the sho.rtest possible
time. The sections that follow di sc uss the
use of the various types of debugging
language and other methods of program
checkout.
Program Checkout
247
DEBUGGING LINES
The user can include debugging lines
(any COBOL statement with a D in column 7)
in his program to assist in locating logic
er.rors. Through inclusion of the WITH
DEBUGGING MODE source clause (essentially a
compile-time switch), the statements are
made part of the object code and will be
executed in line vith the rest of the
program.
Removal of th.e WITa DEBUGGING
MODE clause causes debugging lines to be
treated as comments only; they viII not be
executed. A program con ta ining debugging
lines must be syntactically correct in both
these modes.
(The execu tion-time option
DEBUG/NODEBUG has no control over debugging
lines; it only affects USE FOR DEBUGGING
declaratives--as explained belov.)
2.
32K.
3.
A SEARCH or SEARCH ALL statement that
refers to identifier-1 as the table to
be searched viII not result in an
invocation of the-USE FOR DEBUGGING
declarative procedure. If
identifier-1 is referred to elsewhere
in the statement (for example, as an
operand of a WHEN condition), the
associated declarative will be
invoked.
4.
When identifier-l is the object of an
OCCURS DEPENDING ON clause, the
contents of the DEBUG-CONTENTS
subfield of DEBUG-ITEM viII be
unpredictable if all three of the
following conditions are true:
a) ident ifier-1 is changed in the same
statement as the data item whose
size and/or location is affected by
that change, and
DECLARATIVE PROCEDURES--USE FOR DEBUGGING
The USE FOB DEBUGGING featare provides
the user with the ability to create his own
procedures to examine the internal status
of his program during its execution. The
USE FOR DEBUGGING statement identifies
which program elements it wishes to
monitor.
COBOL then gives the associated
procedure control vhen these e.tements are
referenced during execution. The procedure
also is given access to the DEBUG-ITEM
special register. which has been
automatically filled with the pertinent
current status information.
b) the change occurs following the
reference to the data item, and
c) the data item is not subscripted
and/or inde xed.
5.
The USE FOR DEBUGGING procedures can be
controlled by two switches: t.he WITH
DEBUGGING MODE source clause for
compile-time, and the DEBUG/NODEBUG option
for execution-time. WITH DEBUGGING MODE
indicates that the procedures are to be
compiled as executable code; if WITH
DEBUGGING MODE is omitted, the procedures
are treated only as comments.
Specification of the DEBUG option at
execution time indicates that the
procedures compiled into the code are in
fact bo be executed; if NODEBUG is
specified. t.he procedures are bypassed.
The general rules for USE FOR DEBUGGING
declarative procedures and the DEBUG-ITE~
special register can be found in IB~-Y~
~QBOL fQ~Q~L!2.
The following
considerations also apply:
1.
248
Including USE FOR DEBUGGING
declarative procedures and a WITH
DEBUGGING MODE clause precludes the
use of the SYMDMP and TEST options.
If SYMDMP and/or TEST are specified in
such a case, they will be rejected.
The DEBUG-ITEM special register is
variable in length, and depends on the
size of the character string it is to
contain. This length cannot exceed
If identifier-1 appears in a MOVE
statement and is subscripted or
indexed, and if either of the
following is also true:
a)
the subscript or index is changed in
the MOVE prior to the reference to
identifier-1, or
~
an occuns DEPENDING ON object that
affects the size or address of
identifier-1 is changed in the MOVE
prior to the reference to
identifier-l,
then the DEBUG-ITEM values will
reflect identifier-l' s address and
size just prior to execution of that
MOVE.
6.
Procedures performed from a USE FOR
DEBUGGING declarative will .never cause
invocation of another USE FOR
DEBUGGING declarative.
7.
A USE FOR DEBUGGING filename can only
be a VSAM or QSAM file.
Figure 95 shows an elementary example of
USE FOR DEBUGGING. The program is the same
TESTRUN Ilsed several ti mes elsewhere in
this manual. Here it has been slightly
modified through the addition of the
debugging phrase (encircled 1) and a simple
declarative (encircled 2).
In this
example, t he programmer wishes to
temporarily trap certain input items (ALPHA
D's and M's) and boost their index values
by one so that they become E's and N's
(encircled 3).
Notice that the DEBUG-CONTENTS special
register allows the programmer to reference
items without asing subscripting. Notice
also that the subscript value can be
modified in the declarative section without
affecting that value in the body of the
program (i.e., DEBUG-SUB-1 is only a copy).
By removing the WITH DEBUGGING MODE clause
from the CONFIGURATION SECTION and
recompiling, t he programmer can disable the
debugging declarative--even though the
declarative statements are left in the
source program.
Program Checkout
249
~
\!J
IDENTifiCATION UIVISION.
PROGRAM-ID. TE~TDBUG.
AUTHOR. PROGRAMMER NAME.
INSTALLATION. PALJ ALTO DEVELOPMENT CENTER.
DATE WRITTEN. AUGUST S. 1976.
DA~fM~~~~!Lf~isS~~o~~1A9~XS BEEN WRITTEN AS A SAMPLE PRO~R~M fOR
COBOL USERS. IT CREATES AN OUTPUT fiLE AND READS IT BACK AS
INPUT.
\
ENVIRONMENT DIV,SION.
CONfIGURATION S~CTION.
3~~~~~:~g~~~l~~: Ig~:~~8-rl~~ DEBUGGING MODE.
INPUT-OUTPUT SE~TION.
fI LE-CONTROL.
SELECT fILE-1 ASSIGN TO UT-2400-S-SAMPLE.
SELECT fILE-2 ASSIGN TO UT-2400-S-SAMPLE.
DATA DIVISION.
FILE SECTION.
fD fILE-1
LABEL kECORUS ARE OMITTED
BLOCK CONTAl NS 100 CHARACT ERS
RECORO CONTAINS 20 CHARACTERS
RECORDING MuDE IS f
DATA RECORD IS RECORD-I.
01 RECORD-l.
02 FIELD-A PICTURE IS XI20J.
fD FILE-2
LABEL RECORUS ARE OMITTED
BLOCK CONTA,NS 5 RECORDS
RECORD CONTAINS 20 CHARACTERS
RECORDING MuDE IS f
DATA RECORD IS RECORD-2.
01 RECORD-2.
02 fIELD-A PICTURE IS XI20J.
WORKING-STORAGE SECTION.
77 KOUNT PI(.. TURE S99 COMP SYNC.
77 NOMBER PICTURE S99 COMP SYNC.
01 FILLER.
02 ALPHABET PICTURE X(26J VALUE "ABCDEFGHIJKLMNOPQRSTJV~XYZ·.
02 ALPHA REuEflNES ALPHABET PICTURE X OCCURS 26 TIMES.
02 DEPENDENrS PICTURE XI26J VALUE "0123401234012340123401234
"0".
02 DEPEND R~DEFINES DEPENDENTS PICTURE X OCCURS 26 TIMES.
01 WORK-RECORu.
\
02 NAME-fIELD PICTURE X.
02 FILLER P1CTJRE X VALUE IS SPACE.
02 RECORO-Nu PICTURE 9999.
02 fILLER PICTURE X VALUE IS SPACE.
02 LOCATION PICTURE AAA VALUE IS "NYC".
02 FILLER P,CTURE X VALUE IS SPACE.
02 NO-OF-Df~E~DENTS PICTURE XX.
02 FILLER P,CTuRE X(7) VALUE IS SPACES.
PROCEDURE DIVIS,ON.
DECLARATIVES.
DEBUG-SECTION S~CTION.
USE FOR DEBuGGING ON ALL REfERENCES OF ALP~A.
IF DEBUG-COI'4TENTS = "0" OR "M"
ADD 1 Tv Dt8UG-SUB-1
MOVE ALPHA(DEBUG-SUB-1J TO NAME-FIELD.
END DECLARATIVE~.
BEGIN.
NOTE THAT ThE FDLLOWING OPENS THE OUTPUT FILE TO ~E :REATED
AND INITIAL,lES COUNTERS.
STEP-I. OPEN OUTPUT FILE-I. MOVE ZERO TO KOUNT NOMBER.
NOTE THAT THE FOLLOWING CREATES INTERNALLY THE RECORDS TO BE
CONTAINED II~ THE FILE. WRI TES THEM ON TAPE. AND DISPLAYS
THEM ON THE CONSOLE.
STEP-2. ADD 1 Tv KOUNT. ADD 1 TO NOMBER. MOVE ALPHA IKOUNTI TO
NAME-FIELD.
MOVE DEPEND IKOUNTJ TO NO-Of-DEPENDENTS.
MOVE NO~BER TO RECORD-NO.
STEP-3. DISPLAY HORK-RECORD UPON CONSJLE. WRITE RECORD-1 FROM
WORK-RECORD.
STEP-4. PERfORM STEP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 26.
NOTE THAT ThE fOLLOWING CLOSES OUTPUT AND REOPENS IT AS
INPUT.
STEP-5. CLOSE F,L~-l. OPEN INPUT FILE-2.
NOTE THAT THE FOLLOWING READS BACK THE FILE AND SINGLES OUT
EMPLOYEES W,TH NO DEPENOENTS.
STEP-6. READ FILE-2 RECORD INTO WORK-RECORD AT END GO TO STEP-8.
STEP-7. If ND-Of-L>EPENDENTS IS EQUAL TO "0" MOVE "Z" TO
NO-OF-'DEP EN"ENTS. EXHI BIT NAMED WORK-RECORD. GO TO
STEP-6.
STEP-So CLOSE f,LE-2.
STOP RUN.
WORK-RECORO = A 0001 NYC Z
hG~K-RECORD = 8 0002 NYC 1
hORK-RECORD = C 0003 NYC 2
~CIIK-RECORC = E 0004 NYC 3
hGRK-RECORD = E 0005 NYC 4
hORK-RECORD = F 0006 NYC Z
hC/OK-RECORD = G 0007 NYC 1
NYC 2
CD~:~=~:~~Eg:g
~ ~ ggg~ NYC 3
h(IIK-RECORD = J 0010 NYC 4
hGIIK-~ECORD = K 0011 NYC Z
h(IIK-RECORD = l 0012 NYC 1
HORK-RECORD = N 0013 NYC 2
WORK-RECORD = N 0014 NYC 3
"ORK-RECORD = 0 0015 NYC 4
WORK-KECORD = P 0016 NYC Z
~ORK-RECORD = W 0017 NYC 1
hORK-RECORD = R 0018 NYC 2
WCRK-RECORD = S 0019 NYC 3
WCliK-RECORC = T 0020 NYC 4
hC/OK-RECORD = U 0021 NYC Z
IIORK-RECORO = V 0022 NYC 1
I'IOIlK-RECORD = W 002~ NYC 2
hORK-RECORD = X 0024 NYC 3
haRK-RECORD = Y 0025 NYC 4
"CRK-RECORD = l 0026 NYC Z
~
Pigure 95.
250
Program with USE POR DEBUGGING.
TRACE, EXHIBIT, AND ON
Three additional debugging language
statements are TRACE, EXHIBIT, and ON. Anf
one of these statements can be used as
often as necessary. They can be
interspersed
throughout a COBOL source program, or they
can be in a packet in the input stream to
the compiler.
statement can be used to isolate the
problem record. The statement should be
placed where control passes only once for
each record that is read.
When the
contents of the counter equal the number of
the record (as specified in th~ ON
statement), a trace can be taken on that
record. The following example shows a way
in which the processing of the 200th record
could be selected for a TRACE statement.
Col.
Program debugging statements may not be
desired after testing is completed.
A
debugging packet can be removed -after
testing.
This allows elimination of the
extra object program coding generated for
the debugging statements.
8
1
RD-BEe.
RD-REC.
PARA-NM-l.
DEBUG
The ou t pu t prod uced by th e TR ACE and
EXHIBIT statements is listed on the system
logical output device (SYSOUT). If these
statements are used, the SYSOUT DD
statement must be specified in the
execution time job step.
The following discussions describe ways
to use the debugging language.
The READY TRACE statement causes the
compiler generated card numbers for each
paragraph na me to be listed on the system
output unit when control passes to that
point. The output appears as a list of
card numbers.
If the VERB option is in
effect during compilation, paragraph-names
rather than card numbers will be displayed.
To reduce e.xecution time, 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.
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 the
area. The two trace statements can be used
together where ·the flow of control is
difficult to determine, e.g., with a series
of PERFORM statements or with nested
condi tionals.
Another way to control the amount of
tracing, so that it is done conditionally,
is to use the ON statement with the TRACE
statement.
When the COBOL compiler
encounters an ON statement, it sets up a
mechanism such as a counter that is
incremented during execution whenever
control passes through the ON statement.
For example, if an error occurs when a
specific record is processed, the ON
ON 200 READY TRACR.
ON 201 RESET TRACE.
If the TRACE statement were used without
the ON statement, the processing of every
record would be traced.
A common program error could be either
(1) failing to break a loop, or
(2) unintentionally creating a loop. If
many iterations of the loop are required
before it can be determined that there is a
program error, the ON statement can be used
to initiate a trace only after the expected
number of iterations has been completed.
Notes:
1.
If an error occurs in an ON statement,
the diagnostic message may refer to
the previous statement number.
2.
When READY TRACE encounters a
·paragraph that is repetitively
executed, it does not write out a
separate record for each individual
execution of the paragraph. Instead,
it simplifies its output by keeping
an internal count, and writing out a
single summary record only when the
paragraph iteration finally finishes.
This record identifies the number of
times the paragraph was executed.
READY TRACE output is built to contain
multiple paragraph entries on each
print line.
3.
In the event the paragraph iteration
is a nonending loop, READY TRACE
output does not include the current
print line being built. Therefore,
READY TRACE output never identifies
the paragraph as having been entered
at all.
In the event of an ABEND,
the last print line of READY TRACE
data may not be printed. When either
a non-ending loop or abnormal ending
of a task occurs ,- the current print
Proqram Checkout
251
line is available in the current
SYSOUT buffer.
A programmer can display the value of a
data item during program execution by using
the EXHIBIT statement. The three forms of
this statement display (1) the names and
values of the identifiers or nonnumeric
252
literals listed in the EXHIBIT statement
(EXHIBIT NAMED) whenever the statement is
encountered during execution, (2) the
values of the items listed in this
statement only if the value has changed
since the last execution (EXHIBIT CHANGED)
and (3) the names and values of the items
listed in the statement only if the values
have changed si.nce the previous execution
(EXHIBIT CHANGED NAMED).
The first time
such a statement is executed, all values
are considered changed and are displayed.
The preceding is an example of checking
at regular intervals (every tenth record).
A check of any unusual conditions can be
made by using various combinations of COBOL
statements in the debug packet.
For
example:
IF OVERTIMEHRS GREATER THAN 2.0
EXHIBIT NAMED PAYRCDHRS
In connection with the previous example,
this statement could cause the entire pay
record to be displayed whenever an unusual
condition (overtime e~cee~ing ivo hours) is
encoun tered.
The EXHIBIT CHANGED statement also can
be used to monitor conditions that do not
occur at regular intervals.
The values of
the items 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
as shown in Figure 96.
l!Q.t~:
The combined total le.ngth of all
items displayed vi th EXHIBIT CHANGED and
EXHIBIT CHANGED NAMED cannot exceed 32,767
bytes.
The length of anyone operand must
be less than or equal to 256 bytes. The
length of a "NAME" must be less than or
equal to 120 characters.
Data can be used to check the accuracy
of the program.
For example, the
programmer can display specified fields
from records, work the calculations
himself, a nd com pare his calculations vi th
the output from his program.
The coding
for a payroll problem could be:
Col.
1
r-----------------------------------------,
J
I
I
I
I
1
8
1
I
~
--------J-
~
READ INPUT
DATA FOR.
CITY
1
GROSS-PAY-CALC.
COMPUTE GROSS-PAY
BATE-PER-HOUR
(HRSWKD
+ 1.5
OVERTIKEHRS).
NET-PAY-CALC ..
*
*
I
I
,
NET-PAY-CALC
SAMPLE-1. ON 10 AND
EVERY 10 EXHIBIT NAMED
RATE-PEB-HOOB, 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.00HRSWKD :: 40.0
OVEBTIKEHRS = 0.0 GROSS-PAY:: 160.00
RATE-PER-HOUR = 4.10 iRSWKD
40.0
OVERTIMEHRS = 1.5 GROSS-PAY:: 113.23
RATE-PER-HOUR :: 3.35 HRSWKD
40.0
OVERTIMEHRS : 0.0 GROSS-PAY = 134.00
=
=
l!Q!!!:
Decimal points are included in this
example for clarity, but actual printouts
depend on the data description in the
program.
]
I
V
r-----------,
]
I
I
l-----T----- J
I
J
CITY
1
]
J
DEBUG
---T---
1 CALCULATE I
~ RATE FOR
I
I
I
I
I
I
I
I
<------®
I
V
r-----------,
I
I
EXHIBIT
CHANGED
J
I
l-----T----- J
I
]
I
~
1
I
1
)
J
I
I
)
]
I
I
V
I
~
I
I
I
I
I
I
I
I
L---__ ~-----------------------------------J
Figure 96.
Example of Program Flow
Program Checkout
252.1
The EXHIBIT CHANGED statement in the
program could be:
EXHIBIT CHANGED STATE CITY RATE
The output from the EXHIBIT CHANGED
statement could appear as:
01
02
03
01
10
02
15
03
04
10
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 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 shown
in Figure 97.
01
02
0.3
04
20
01
10
15
rI
,
...---------,
J
I
I
The first column contains the code for a
state 6 the second column contains the code
for a citY6 and the third columB contains
the code for the postage rate. The value
of an item is listed only if it is changed
since the previous execution. For example,
since the postage rate to city 02 and 03 in
state 01 are the same 6 the rate is not
printed for city 03.
The EXHIBIT CHANGED NAMED statement
lists the na me of the da ta item and the
value of that item if the value has
changed.
For example 6 the program might
calculate the cost of various methods of
shipping to different cities.
After the
calculations are made, the following
statement could be in the program:
J
J
,
~
I
•I
1
I
I
V
J
.
L--
L--_ _ _ _ _ _ _ _ _- - - ,
r--------,
1
J
t
A
I
J,
J,
I
I
I
I
I
I
I
I
I
1
I
I
t
I
I
I
START
1•
1
f
I
I
t
--,
r-
,•
I
I
I
DEBUG
PACKET
FOR A
I
1
I
I
I
.J
,
-.J
I
.---
V
f
J
B
I
1.
J
4
EXHIBIT CHANGED NAMED STATE CITY RAIL
BUS 'rRUCK AI R
The output from this statement could appear
as:
STATE = 01 CITY = 01 RAIL = 10
BUS = 14 TRUCK = 12 AIR = 20
CITY = 02
CITY
= 03
= 04
CITY
TRUCK
BUS = 06 AIR = 15
= 02
,
I
RAIL = 30 BUS = 25
= 28 AIR = 34
TRUCK = 20 AIR = 30
Note that the name of the item and its
value are listed only if the value has
changed since the previous execution.
•
'--
I
V
r-------l
J
J
J
C
•
I•
I
I
,,
f
I
Figure 91.
I
I
I
r--
I
I
I
DEBUG
PACKET
FOR C
.J
-"
.I
r-
I
V
I
STATE = 02 CITY = 01 TRUCK = 25
CITY
I•
I
I
t
f
1
STOP
RUN
,
I
I
I
Selective Testing of B
In this program, A creates data, B
processes it, and C prints it. The debug
packet for A simula tes test data. It is
first in the program to be executed.
the packet, the last statement is GO TO B,
In
Program Checkout
253
which permits A to be bypassed.
After B is
executed with the test data, control passes
to the debug packet forC, which contains a
GO TO statement that transfers control to
the end of the program, bypassing C.
be included. This pr intou t is called an
abnormal termination dump and in VS1 is
identified by the heading
***
ABDUMP REQUESTED
***
If a SYSABEND DD statement is specified,
the contents of the nucleus is also
printed.
If a program runs correctly but changes
or additions can make it more efficient, a
debug packet can be used to test changes
without modifying the original source
program.
If neither a SYSUDUMP nor a SYSABEND DD
statement is included in the execution~time
job step, or its specification has been
destroyed, an indicative dump is produced.
This dump does not contain a printout of
main storage and is not given under OS/VS2.
If the changes to be incorporated are in
the middle of a paragraph, the entire
paragraph, v ith 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.
All dumps include a completion code
designating the condition that caused the
termination. The completion code consists
of a system code and a user code. Only one
of the codes is nonzero.
A nonzero system
code indicates that the control program
detected the error.
There are usually several ways to
perform an operation.
Alternative methods
can be tested by putting them in debug
packets.
The COBOL programmer can request dynamic
dumps via a compile-time option. The
SYKDMP option, requested in the PARM
parameter of the EXEC statement, produces a
symbolic formatted dump of the data area of
the object program if the program
abnormally terminates •. At execution time,
the user can also request a dynamic dump at
any point in the Procedure Division.
The source program library facility can
be used for program checkout by placing a
source program in a library (see
"Libraries"). 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.
If a serious error occurs during
execution of a program, the job may be
abnormally terminated; any remaining steps
are bypassed, and a 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 the abnormal termination does not go
to completion, a dump is not produced.
This situation may cause duplicate name
definition when the next job is run, and is
discussed at the end of this section.
If a SYSUDUKP DD statement has been
included in the execution-time job step,
the system will provide the programmer with
a p.cintout. in hexadecimal and EBCDIC
format, of main storage. Those areas
occupied by the problem program and its
data at thet.ime the error occurred., viII
254
• If a COBOL program abnormally
terminates, then a formatted dump is
produced for all COBOL programs
compiled with the SYMDMP option which
could include the abnormally
terminating program and its callers, up
to and including the main program.
• The explanation of the system-genera ted
completion codes and a complete
description of the dumps are contained
in the appropriate Deb~ggill~~uidg.
For a discussion of the COBOL sym bolie
debugging options, see the chapter
entitled "symbolic Debugging Features. It
USER-INITIATED DUMPS
The COBOL programmer can cause a dump at
any pre-specified point in his program by
coding a call to t he libra ry suhr~ utine
ILBOABNO, in the following manner:
71
MOVE
COMP-CODE PIC S999 CaMP.
nnn TO COMP-CODE.
CALL • ILBOABNO t
USI NG COI!P-CODE.
in the file may be invalid. The
compiler does not generate a test to
check the sign position for a valid
configuration before the item is used
as an operand.
The three-digit number nnn vill become the
identifier in the Unnn user abend code
produced with the resultant dump.
ERRORS THAT CAN CAUSE A DUMP
3.
Following is a discussion of some error
conditions that can cause a program to be
abnormally terminated and a dump to be
listed.
Note: A Numeric class test, "IF
Numeric", for signed data items,
allows C, D, and F as valid signs.
For external decimal items this
includes X'C1' through X'C9' and
X'D1' through X'D9' and X'F1' through
X'F9' as valid last bytes. For
internal decimal items, this includes
X'1C' through X'9C', X'1D' through
X'9D', and X'1F' through X'9F' as
valid last bytes. Certain invalid
numeric data items, such as EBCDIC A
through R in the last byte of an
external decimal numeric it~m, and
EBCDIC <, *, %, @, (, ) ,
"
, I ,-i, ?, and" in the last byte of an
internal decimal item, are considered
valid numeric items for an "IF
Numeric" test.
Errors can occur while a COBOL file is
being processed. For example, during data
transmission, an input/output error may
occur that cannot be corrected. In some
situations, this will result in the job
being terminated (see Figures 52 and 53).
Referring to an input area
(non-VSAM/QSAM) before both an OPEN and a
READ statement are issued can cause
unpredictable results, because base locator
(BL) cells and registers are not properly
initia 1i%ed.
Another error that can cause termination
is an attempt to read a file whose records
are of a different size than those
described in the source program. The
section "Add itional File Processing
Information" contains more information
about input/output errors.
4.
Tbe SIZE ERROR option is not specified
for tbe COMPUTE statement and the
result of the calculation is larger
than the specified resultant
COMPUTATIONAL data name.
Using the
result in a subsequent calcula tion
might cause an error.
5.
The SIZE ERROR option is not specified·
for a DIVIDE statement. and an attempt
is made to divide by zero.
6.
The USAGE specified for a redefining
data item is different from the USAGE
specified for the redefined item.
An
error results wheri the item is
referred to by the wrong name for the,
current content.
7.
A record containing a data item
described by an OCCURS clause with the
DEPENDING ON Qat~~~~ option. may
cause data items in the record to be
affected by a change in the value of
Abnormal termination of a job occurs
when a data item with an invalid format is
processed in the Procedure Division.
Some of the program errors are:
1.
A data item in the Working-storage
Section is not initialized before it
is used, causing invalid data to be
picked up.
2.
An input file or received message
contains invalid da ta or data
incorrectly defined by its data
description.
For example, the
contents of the sign position of an
internal or external decimal data item
If a group item is moved to a group
item and the subordinate data
descriptions are incompatible, the nev
data in the receiving field may not
match the corresponding data
descriptions.
(conv~rsion or editing
is not performed in a move involving a
group item.)
Program Checkout
255
gllg=!!sl!~ during the course of program
execu tion. This may result in
incorrectly described data.
Addit lonal informa tion about how to
correct this situation is included in
"programming Techniques."
8.
9.
10.
The data description in the Linkage
section of a called program does not
correctly describe the data defined in
the calling program.
A subscript or index set at zero will
address data outside the range of the
t.ab Ie.
15.
If either HIGH-VALUE or LOW-VALUE is
moved to internal or external decimal
fields and those fields are used for
comparisons, computations, or
subscripting, a data exception will
occur. HIGH-VALUE and LOW-VALU E a.re
the hexadecimal values X'PF' and
X'OO., respectively (unless these
values have heen altered by a
user-defined collating sequence).
Some common errors that occur when
clearing group items in storage are:
a.
PJovingALL ZEROS to a group level
item to clear several counters
causes an invalid sign to be
generated in all of the elementary
fields except the lowest order
field.
b.
ftoving SPACES to a group level
item will put invalid data in any
numeric field in that group.
c.
Moving 0 to a group level item
moves one zero and pads the rest
of the fields with blanks.
Failure to initialize counters
produces incorrect results.
No
initial values are generated by the
compiler unless specifically
instructed to do so with a VALUE
clause.
If such fields are defined as
decimal, internal or external, invalid
signs may result in addition to
unpredictable initial values.
If
defined as binary, they will cause
unpredictable results and, further, if
used in subscripting, may exceed the
range of the associated OCCURS clause
and cause data to be fetched or stored
erroneously. An addressing exception
may occur if the uninitialized
subscript generates a bad address.
12.
Not testing to insure that a
or index does not exceed the
the associated OCCURS clause
to fetching and storing data
to some incorrect locations.
256
14.
Blanks read into data fields defined
as numeric generate an invalid sign.
11.
13.
An addressing exception may occur if
the Initi alized inde.x generates an
address outside the range of the
machine, or a protection exception if
data is stored outside the partition
of this program.
Addit ional 1/0 errors may occ ur tha t
viII result in an abnormal termination
(these are listed below).
For QSAM files,
however, the user can employ the FILE
STATUS clause to intercept many of these
errors; bis program can then identify and
deal with them, and thus prevent the abend
from occur ing.
1.
No DD statement is included for a file
described in the source program and an
attempt is made to access the file.
When an OPEN statement for the file is
executed, the system console message
is written. The programmer can elect
to direct the operator to continue
processing his program, but any READ,
WRITE, REWRITE, or START associated
with the unlocated file will fail.
(A
READ for a missing optional file#
however, will follow end-of-file
processing rules.)
A similar
situation exists when a file is closed
WITH LOCK and an attempt is made to
reopen it.
2.
A file is not opened and execution of
a READ or WRITE statement for the file
is attempted, or a MOVE to a record
area in the file is attempted.
3.
A GO TO statement, with no procedure
name following it, is not properly
initialized with an ALTER statement
before the first execution of the GO
TO sta temen t.
4.
Reference is made to an item in a file
after end of data. This includes the
use of the TERMINATE statement of the
subscript
range of
may lead
from and
Failure to initialize an index
produces incorrect resl11ts.
No
initial values are generated by the
compiler unless a SET statement is
executed.
When indexinq is then
specified, the range of the OCCURS
clause may be exceeded and cause data
to be fetched or stored erroneously.
Report writer feature, if the CONTROL
FOOTING, PAGE FOOTING, or REPORT
FOOTING contain items that are in the
file (e.g., SOURCE data-name, where
data-name refers to an item in the
file) •
5.
6.
In a blocked and/or multiple-buffered
file, information in a record is
unavailable after a WRITE.
7.
A READ is issued for a data set
referenced on a DO DUMMY statement.
The AT END condition is sensed
Block size for an F-format file is not
an integral multiple of the record
lengt h.
Program Checkout
256.1
immediately and any reference to a
record in the data set produces
unpredictable results.
8.
A STOP RUN statement is executed
before all files are closed.
9.
A SORT did not execute successfully.
The programmer may check SORT-RETURN.
10.
An input/output statement is issued
for a file after the AT END branch is
taken, without closing and reopening
the file.
11.
A SEND or RECEIVE statement is issued
when a message control program is not
running.
12.
A SEND or RECEIVE statement is issued
for a QNAK! (i. e. , the "QNAKE="
parameter of the DD card) that is
unknown to the message cont rol
program.
2.
In addition to errors that can result in
an abnormal termination, errors in the
source program can occur that cause parts
of the program to be overlaid and the
corresponding object code instructions to
become invalid.
If an attempt is then made
to execute one of these instructions~ an
abnormal termination may result because the
operation code of the instruction is
invalid, the instruction results in a
branch to an area containing invalid
instructions, or the instruction results in
a branch to an area outside the program,
such as an address protected area.
043--Error occurred during the
attempted opening of a TCAM
application program data set, as
described below.
a.
A value of 01 in reg~ster 0
indicates the attempted opening of
a TCAM application program data
set without an active message
control program (MCP) in the
system.
b.
A value of 02 indicates that the
QNAME= parameter of a DD statement
associated with an input or output
DCB for a COBOL program is not the
name of a process entry defined in
the terminal table.
c.
A value of 03 indicates that the
process entry named by the QNAME=
parameter of a DD statement
associated with a COBOL program is
currently being used by another
COBOL progra m.
d.
A value of 04 indicates that
insufficient main storage was
available in the MCP to build
internal control blocks associa ted
with the COBOL program interface.
Specify a larger region or
partition size in the JOB
statement for the MCP.
e.
A value of 05 indicates that
insufficient main storage was
available in the COBOL work area
to build internal control blocks.
specify a larger region or
partition size in the JOB
statement for the COBOL program.
Some COBOL source program errors that
can cause this overlaying are:
1.
Using a subscript whose value exceeds
the maximum specified in the
associated OCCURS clause.
2.
Using a data-name as a counter whose
value exceeds the maximum value valid
for tha tcoun ter.
3.
046--Error occurred during the
termination of the TeAM MCP
because the COBOL program data
set was still open.
specify the
STOP RUN statement when COBOL
processing is complete. Ensure
that all COBOL programs have
terminated processing before
deactivating the MCP.
4.
OC1--0peration Exception:
SYSTEM COMPLETION CODES
The following cases represent some of
the errors that can occur in a COBOL
program and the interrupt or completion
code associated with them.
These errors do
'not necessarily cau,se an abnormal
term~nation at the time they are recognized
and do not always hold true.
(See Appendix K
for COBOL-initiated u-type completion codes.)
1.
013--Check register 2 of registers at
the entry to ABEND. This address
points to the DCB in conflict.
a.
When the interrupt is at 000048 or
at 004800, look for a missing DD
card or an unopened file.
b.
When the interrupt is at 000050,
look at register 1 of the
registers at entry to ABEND.
Add
hexadecimal 28 to the address
found in register 1. This should
point to the ~D name of a missing
DD statement.
Program Checkout
257
c.
When the interrupt is at 00004A,
look for a missing card, i.e.,
a.
Data field was not initialized.
b.
Input record numeric field
contains blanks.
c.
Subscript o.r index value exceeded
maximum and invalid data vas
refe.renced.
d.
Data vas moved from the DISPL'AY
field to the COMPUTATIONAL or
COftPUTATIONAL-3 field at group
level. Therefore, no conversion
vas provided.
e.
The figurative constants ZERO or
LOW-VALUE moved to a group level
numeric field.
f.
Omission of USAGE clause or
erroneous USAGE clause.
g.
Incorrect Linkage section data
definition, passing parameters in
wrong order~ omission or inclusion
of a parameter, failure to carry
over a USAGE clause when
necessary, or defining the length
of a parameter incorrectly.
//SYSOUT DD SYSOUT=A
any missing JCL card, or the wrong
name of a JCL card.
Add
hexadecimal 28 to the address
found in register 1 at entry to
ABEND. This should point to the
DD name of the DD statement in
error.
d.
5.
6.
OC4--Protection Exception:
a.
Check for the block size and
record size being equal for
variable record input or output.
b.
Check for missing SELECT
statement.
c.
If inte.rrupt is at 004814, check
for an attempt to READ an unopened
input file or a missing DD card.
d.
Check for an uninitialized index
or subscript.
e.
If a QSAM file with FILE STATUS
opened OUTPUT, check for a missing
DD card.
Subscript or index value may have
exceeded maximum and instruction
or table area was overlaid.
b.
Check for an improper exit from a
procedure being operated on by a
PERFORM statement.
c.
Check for duplicate close of an
input or output file if DS
formatting discontinued.
d.
A sort is being attempted with an
inc orrect ca tal og proced ure.
e.
Attempting to reference an
input/output area before a READ or
OPEN statement, respectively.
f.
258
8.
001--1/0 Error:
a.
Register 1 of the SVRB points to
the DCB which caused the
input/output problem.
Look for
input record and blocking errors.
That is, the input does not agree
with t·he reco.rd and blocking
descriptions in the DCB, the COBOL
file description, or the DD
statement LREeL parameter.
b.
Attempted to READ after EOF has
been sensed.
c.
Attempted to write to a QSAM file
that has previously encountered
end of file (taken a B37 exit),
and set the file status to X'34'
and/or entered the INVALID KEY
routine.
OCS and OC6--Addressing and
Specification Exception:
a.
7.
When interrupt is at 00004F, look
for inconsistent JeL or check the
system-name in the COBOL program.
Check for initialized subscript or
index value.
OC7--Data Exception:
9.
002--Register 2 of registers at the
entry to ABEND contains the
address of the DCB for the file
causing the input/output problem.
Check the DCB list for the
specific file.
10.
013--Error during execution of an OPEN
EXTEND statement.
Ensure that
the· system OPEN EXTEND facility
is available. OPEN EXTEND
requires at least OS/VS1 Release
6, or OS/VS2 Release 7 with SU8.
11.
213--Error during execution of OPEN
statement for data set on mass
storage device, as follows:
a.
DISP parameter of DD statement
specified OLD for output data set.
Program Checkout
258.1
b.
12.
13.
Input/output error cannot be
corrected when reading or writing
the DSCB. Recreate the data set
or resubmit the job.
214--Error during CLOSE for data set
on tape; there is an input/output
error that cannot be corrected
either in tape positioning or
volume disposition. Resubmit the
job and inform the field engi~eer
if error persists.
08 An uncorrectable input/output error
occurred when the control program
attempted to search the directory
of the library indicated as
containing the requested program.
18.
BOA--Insufficient contiguous main
storage for linkage to some phase
of the compiler. The programmer
should see if secondary data-set
allocation has caused an extra
DEB to be built at lower main
storage addresses within the
region. If sOv this problem can
be corrected by assigning
sufficient primary extents for
the data set in question. See
ttData set Requirements" for
further information. If this
error occurs When a non-COBOL
program (such as IMS or an
installation-defined assembler
program) links to a COBOL load
module many times in a job step.
the programmer should determine
if the NOENDJOB option was used;
if so, specifying the ENDJOB
option may correct the problem.
19.
813--Error during execution of an OPEN
statement in verification of
labels:
237--Error at EOV:
a.
Incorrect volume serial number
specified in SER subparameter of
VOLUME parameter of DD statement.
b.
Incorrect volume mounted.
c.
Incorrect labels.
14.
400--1f this completion code is
generated during a compile step,
the member to be compiled has not
been extracted from the source
library for compilation.
15.
413--Error during execution of an OPEN
statement for a data set on tape:
a.
Volume serial number was not
specified for input data set.
b.
Volume could not be mounted on the
a llocated device.
c.
There is an input/output error in
reading the volume label that
cannot be corrected.
a. Volume serial number specified in
VOLUME parameter of DD statement
is incorrect.
b. Data set name spe"cified in DSNAME
16.
804--The error occurred dnring a
GETMAIN. If this error occurs
when a non-COBOL program (such as
IMS or an installation-defined
assembler progra~ links to a
COBOL load module lIany times in a
job step, the programmer should
determine if the NOENDJOB option
was used; if so, specifying the
ENDJOB option may correct the
problem.
17.
806--The error occurred during
execution of a LINK, XCTL,
ATTACH, or LOAD macro
instruction. An error was
detected by the control program
routine for the BLDL macro
instruction. The contents of
register 15 indicate the nature
of the error:
04 The requested program was not found
in the indicated private, job, or
link library.
parameter is incorrect.
c. Wrong volume is mounted.
20.
906--The system use count limit was
exceeded during the execution of
a LINK, XCTL, LOAD, or ATTACH
macro. If this error occurs when
a non-COBOL program (such as 1MS
or an installation-defined
assembler program) links to a
COBOL load module many times in a
job step, the programmer should
determine if the NOENDJOB option
was used; if so, specifying the
ENDJOB option may correct the
problem.
Finding L0£9.11.Q!!._2U!:QQrall InterruptiQ!L.in.
£Q~Q1_liQY!:£~_fIQg[a~-Y2in~_th~_Condensed
1isting
To determine the location of the
interruption, the programmer should proceed
as follows:
Program Checkout
259
1.
From first page of dump:
a.
Get coapletion code and prograa
interruption storage location.
Not~:
The information in this section
about the use of the abnormal termination
dump applies only when running under
OS/VS1. For information about the abnormal
termination dumps under OS/VS2, see the
publication,~2 Deb~g!lliLQ.y.ig~.
b.
2.
3.
4.
Determine the starting address of
the program (PRB address+20).
Froll Ii nkage editor listing:
a.
Determine storage address for each
module.
Add starting -address of
the program to origin of each
module.
b.
Determine module in which
interrapt storage location falls.
c.
Determine relative address.
Subtract module storage address
from interrupt location.
From Procedure Division map:
a.
Find the highest previous relative
address in the condensed listing.
That statement is in error.
b.
Get line number and verb of COBOL
source statement.
From source listing find the line
number and verb of source statement
causing program interruption.
USING THE ABNORMAL TERMINATION DUMP
The programmer can also determine the
cause of an abnormal termination with the
following material:
1.
The COBOL program object code listing.
2.
A knowledge of the layout of the COBOL
object module.
3.
The full abnormal termination dump in
conjunction with the linkage editor
map or cross reference list.
A description of the linkage editor
output and of the COBOL object code listing
is found in "output." Figure 91 shows the
layout of the COBOL program object module.
260
The abnormal termination dump provides
the address at which the load module has
been loaded (load address) and the address
of the instruction that caused the
interrupt.
The programmer computes the
load module area by adding the load address
to the load module length* as shown in the
linkage editor output.
It is now possible
to determine whether the instruction falls
within the load module.
If it does not*
the interrupt could have resulted from an
improper branch to a point outside the load
module or an error occurring in another
part of the system.
If the instruction does fall within the
load module. the programmer now determines
in which part:
the main program, a COBOL
library subroutine* or a called program.
The ranges of the various parts are
determined by adding their relative
origins, as showb in the linkage editor
output. to the load address.
If the instruction occurred in an object
module generated for a COBOL program.
(i.e., the main program), the programmer
can determine whether or not the
instruction vas one of the generated object
code instructions.
He can determine the
address of the first instruction in the
Procedure Div~sion (as found in the object
code listing) by adding its relative
location to the location of the object
module (load address plus relative "origin).
If it was one of the object code
instructions, a similar technique can be
used to locate the exact instruction.
If
it was not one of these instructions. the
error has occurred in another part of the
object module.
Control possibly went there
because of an improper branch.
If the instruction that initiated the
dump occurred in a COBOL library
SUbroutine. or if the original program
called another program and the instruction
occurred in the called program* the
instruction can be located by a similar
teChnique.
The linkage editor cross
reference list indica tes the locations
where the call to th~ program or subroutine
in question was made.
The following general rules can be used
to determine the cause of the dump and the
error.
1.
Determine the COBOL statement that
generated the code leading to the
program check.
a.
The top of the system dump will
tell the address of the PC
(Program Chec~ instruction and
the type of PC.
Locate the
instruction in the core dump.
b.
Determine the relocation factor of
the program from the linkage
editor map. subtract the
relocation factor from the address
of the invalid instruction.
c.
The address that results may be
located in the procedure division
map generated by the MAP option.
(The coding shown at this location
of the map should correspond to
the instruction located in step
one. )
d.
Preceding the address and code
found in step three, find the
sequence number of the
corresponding COBOL statement in
the listing and the number of the
element in the sentence that
gen era ted t he cod e.
2.
Be sure the COBOL statement is coded
properly.
3.
If tbe statement is coded properly, go
back to the main storage dump and
determine the type of PC.
a.
If it is a data exception, the
programmer will probably find tha t
the instruction is a decimal
instruction, and that one of the
fields either will not have a
valid sign or will contain digits
other than 0 to 9. To determine
tbis, it will be necessary to find
the fields in main storage.
Inspect bits 4 through 7 of the
lOlli-order byte for a valid sign
(A through F). If one is not
present, this is the cause of the
pc.
If one or both of the fields
being operated on are d,efined as
external decimal, the programmer
will find one or more pack
instructions immediately ahead of
the pc instruction. From these
determine the address of the
external decimal field that
generated the invalid sign.
several common causes of data
exceptions are given in "Errors
Caused by Invalid Data."
b.
If it is a protection except~on,
one possible cause is that a base
register used in the instruction
has not been initialized.
Base
registers in COBOL are initialized
at different times. For QSA~ and
VSAM input files the register is
initialized at OPEN; for other
input files, the register is not
initialized until the first
§~~§~!B! read.
For output
files, the registers are
initialized ~uring the p~ocessing
of the OPEN statement. When faced
with a protection exception, the
programmer should go to the COBOL
source program to ascertain that
no data has been moved prior to
the time when base registers are
initialized.
c.
If an addressing or specification
exception occurs, the programmer
may find upon inspection (but not
always) that registers have been
unexpectedly modified and the
problem becomes one of finding out
how. Two possible approaches are:
(1) Check the addresses in
registers 14 and 15 against
the address of the PC
instruction.
If the address
of the PC instruction is equal
to or slightly larger than the
address in register 15, the
address probably is in a
subroutine, and the address in
register 14 should be the
return address.
A BAL or BALR
instruction probably viII
precede the return address.
The programmer should look for
this particularly when the
problem is not with a COBOL
statement. If the PC
instruction has an address
equal to or a bit larger than
the address in register 14,
then the programmer probably
has just returned from a
subroutine, and register 15
should still be pointing to
the entry address of the
subroutine. The proqrammer
should check the coding to see
if this could reasonably be
so, and check the entry points
listed on the linkage editor
map. If this approach bears
further action, a listing of
the subroutine vould be needed
Program Checkout
261
Thus, the range is from ® to
@ + ®. Since the address @ falls
within this range, the instruction
initiating the dump must be within the
load module.
or the instructions from the
dump must be interpreted.
(~
If the foregoing step does not
locate the error, the
programmer should check back
through the dump to see what
exists between the PC
instruction and the last
unconditional branch in order
to determine the possible
course of events.
3.
within the load module of the
instruction indicated in the INTERRUPT
entry, subtract the load address from
the address of the instruction.
4.
To determine whether or not the
instruction occurred in the object
module generated for the program,
compare its relative location Q) - ®
with the total length, @, of the
object module.
If the relative
location were greater than the size of
the object module, then the error
would not be part of this program.
A
relative location between the size of
the object module, @ , and the total
length ® would indicate that the
abnormal termination had occurred in
one of the COBOL library subroutines.
Such an error could be located by
comparing the relative location with
the relative origin of the subroutines.
In this example, (6) - Q) is less than
the object module size (2), so the
instruction occurred in the main
program.
5.
To determine whether or not the
abnormal termination occurred in one
of the object code instructions
generated as a result of a statement
in the Procedure Division of the
source program, compare its relative
location with the relative location of
the first generated instruction in the
Procedure Divisi-on, ®.
In this
example, the relative location of the
instruction is greater than that of
the first generated instruction and so
it can be found by locating the
corresponding relative location.
The
immediately preceding object code
instruction then is the instruction
that initiated the dump, (J).
In this
example, it is an instruction
generated as a result of a COMPUTE
statement. Checking back to the
source program listing, the
corresponding statement 18, ® , is
located and tB' is seen to be the
data-name that caused the trouble.
Data item B is defined in the Data
Di vision,
as a COKPUTATIONAL- 3 or
internal decimal item, but the value
at B is there as a result of a VALUE
clause for A, the item that B
redefines. This value is in external
decimal format since there is no USAGE
clause specified. The configuration
of A is invalid for B and results in
an interrupt.
The sample COBOL program ABEND and its
output, shown in Figure 98, illustrates in
detail the way in which an object code
listing, a cross-reference table, and an
abnormal termination dump can be used
together to debug a program. The circled
numerals in the figures are cited in the
associated text.
Note that all values are
expressed in hexadecimal format unless
otherwise indicated.
In that example, the completion code in
the dump,
indicates the condition
causing the abnormal termination. If the
system part of the code is nonzero, the
explanation can be found in the appropriate
Qg!!!!ggill.LGuidg.
In the program ABEND, the
completion code is OC7; invalid data is the
reason for termination.
CD,
suggested below are general procedures
for locating and correcting the source
statement responsible for abnormal
termination.
1.
The INTERRUPT hhhhhb. entry, @, gives
the hexadecimal address of the
instruction following the instruction
that initiated the interrupt and
caused the dump_ This address can be
used to determine the relative
location of the instruction in the
load module (see item 4 below).
2.
To determine the main storage area
occupied by the load module, add the
total length of the module, in
hexadecimal format, to its load
address. The load address can be
obtained from the EPA entry, ®, of
the CDB specification. The last six
digits of this entry are the address
of the entry point (INIT1) in the
COBOL program.
The total length of the load ~odule
is indicated in the TOTAL LENGTH
entry,
in the linkage editor
output.
The highest location in the
load module is:
®,
®
262
+@
TO determine the relative location
®,
~~terminin~th~Q£a£iQll-2f_sn_A~~!Q When
Ry.!!!!inLlll!!2.mically:
When running
dynamically, the programmer should do the
following to determine whether the abend
occurred in the main program.
1.
Figure 99 is a Load List of the same
program shown in Figure 98, but
compiled with the DYNAM option.
The
compiler produces a Load List that
contains the COBOL subroutine library
names and the addresses used in the
program.
These are anything beginning
with ILBO. ® The programmer is
particularly interested in any ILBO
subroutine that does not end in a
zero, such as ILBORNT, ILBOREC,
ILBODSP, etc.
2.
In this case, the abend has occurred
at
To determine whether this is
with1n the main program, go to the
Load List, and look for the subroutine
with its address closest to that of
the abend, which is at ®
3.
Look below to the second part of the
Load List. This contains the length
of the subroutines that begin at the
address specified above.
In this case
at ® ' under the LN column, the
®.
program Checkout
263
OOOul
,cee2
O("1l03
C('CC4
OOCC5
OCiCC6
00007
lloce8
O';CCS
COCIC
OOOH
0("012
CC C.L3
CO 0 14
OUC15
COC;16
00(17
OOC;ld
uOCH
00001
00002
00003
00()04
000(i5
00006
00007
0(;008
00009
00010
00011
00012
00013
00014
a001S
00016
00017
00018
00019
IuENTIfICATION uIVlSION.
PROGRAM-ID. AdEhD.
REMARKS.
THIS IS A ~ROGRAM TO ILLUSTRATE THE
TERM£NATION OF A PROGRAM.
ENVIR~NHfNT DIViSION.
CONfIGURATION SeCTION.
SOURCE-~HPUTER. I&H-370-168.
OBJECT-COMPUTER. IbM-37U-168.
ABNOR~AL
DATA DIVI SION.
wORKING-STORAGE SE~TIDN.
01 RECORDA.
02 A PICTU~E 59(4J VALUE 1234.
02 B KEDEf!~tS A PICTURE S9(7J COMPUTATIONAl-3.
PROCEDURE DIV fS£ON.
ft:'\
CGMPUTE B = B to 1. \!J
STOP RUN.
LVL
01
02
02
INTRNL NAMt:
DNM=J.-u32
DNM=1-u52
DNM=1-vb3
SLlURCe NAME
RECOR&JA
A
BASE
Bl=l
Bl=l
BL=l
B
(!)
OISPL
000
000
000
INTRNL
N~ME
DNM=1-032
DNM=i-052
DNI1=1-063
OEF INI TION
DS OCL4
os 4C
DS 4P
US~GE
DISP~N"I
COMP-3
MEMOKr MAP
LITE~AL
TGT
000A8
SAVE AREA
SWITCH
TAllY
SOH.T SAVE
ENTRY-SAVE
SORT CORE SIZE
RH CODE
SORT RET
WUH.KING CEllS
SORT fILE SIZE
SORT MODE SIZE
PGT-VN TBl
TGT-VN TBL
RES':RVED
OOOA8
OOOFO
OOOf4
OOOFS
OOOFC
00100
00104
0010b
00108
00238
0023C
00240
00244
00248
UNCIL CEllS
PfMC TL CElLS
PfMSAV CELLS
VN CEllS
SAVE AREA =2
SAVE AREA =3
XSASW CEllS
XSA CELLS
PARAM CEllS
RPTSAV AREA
CHECKPT CTR
002CO
002CO
002CO
002CO
002CO
002eO
002CO
002CO
002eO
002eO
002eO
PGOL ,HEXJ
OCZCU (LIT+OJ
lC
PGT
OVERfLOW CElLS
VIRTUAL CEllS
PROCEDURE NAME ~ELlS
GENERATED NAME ~ELLS
DCB ADDRESS CELLS
VNI CELLS
II TERALS
DISPLAY LITERAL~
002eo
002eo
002CO
002Ce
002Ce
00200
00200
00200
00201
HGISTER AS')IGNMENT
REb
b
BL =1
~ORKING-STORA~~
Figure 98.
264
(l
GRJUP
STARTS AT LOCATIUN OJOAO fOR A LENGTH OF 00008.
COBOL Program That will Abnormally Terminate (Part 1 of 3)
R
Q
ld
l'i
COMPuTE
000202
000202
000208
00020E
0002E4
0002i:4
0002E8
0002EA
STOP
ooooae
000014
000018
00001A
000011:
000020
000024
000020
OC002A
00002e.
0(,0030
000034
000038
00003C
000040
000044
000048
000084
000088
000090
000098
*STAT,STICS*
SOURCE
*OPTIDNS IN EffECT*
*OPTIUNS IN EffECT*
*OPTluNS IN EffECT*
*OHlDNS IN Effl:CT*
*OPTIONS IN EffECT*
*CfTIUNS IN ErFECT*
®F8
START
10 0 208 C 010
FA 43 0 20B 6 000
Fd 33 6 000 D 20C
GN=Ol
5& FU e 008
01 FF
51.1 00 5 008
INIT2
EQU
*206(8,13),010(1,12)
CD7 ZAP
AP
20B(5,13),000(4,6)
000(4,6),20C(4,13)
ZAP
EQU
l
BCR
ST
CL",2c.~D5e4404040
01
BCR
LA
BCR
AOCON
ADCON
ADCON
ADCON
ADCON
AOCON
ADCON
OS
DC
DC
DC
DC
OOIJOO~CO
00vOOOA8
00v00202
OUv002 EA
001.100000
F If-24BF4F24BF 5F2
ChAC 140F lF66B40
FH-9F7F6
lIT+D
DNM=1-63
TS=D4+1
ONM=1-~3
*
15,008(0,12)
15,15
13,008(0,5)
DC
DC
BCR
LI4
BCR
E5J;209Fl
07 00
9d 9f F 024
07 fF
90 02 1 034
01 FE
41 F(; 0 001
07 FE
001JOO:i2A
001.100000
00",00000
TS=Ol
TS=04
V(
IlBOSRVU
X'C1e2C505C4404040'
X'E5E2D9F1'
0,0
9,15,024(15)
15,15
034(l),X'02'
15,14
15,001(0,0)
15,14
L4( INIT3)
L4(INITl)
L4(INITU
L4(PGT)
L4 CTGT)
L4( START)
L4(1NIT2)
15F
X'OOOOOOOO'
X'F1F24BF4F24BF5F2'
X'C1E4C140F1F66B40'
X'FlF9f1F6'
19
DATA DIVISION STATEMENTS =
3
PROCEDURE DIVISIQ~ STATE~E~TS =
SIZE = 1~1012 BUF
12288 LINECNT = 51 SPACE1, FLAGW,
SEQ,
SOJRCE
DHAP,
PMAP, NOCLIST, NOSUPMAP, NOXREf,
SXREF,
LOAD, ~ODECK, APO~T, ~OTRUNC, NOFLO~
NOTERM, NuNUM, NOBATCH, NONAME, COMPILE=Ol, NOSTATE, NORESIDENT, NDDYNA~, ~JLIB, NQSVNTAX
NOOPTIMIZ~, NOSYMOMP, NOTEST,
VERB,. ZWB, SYST, NOENDJOB, NOLVL
NOLST , NuFDECK,NOCDECK, LCOL2, L120,
DUMP, ~OADV , NOPRINT,
NOCOUNl, NOVBSUM, NOVBREF, LANGLVU2)
RECORD~
2
Ft4-LEVEL LIhKAGE EDITtJR OPTluNS SPECIFIED L1ST,LET,XREF
D~FAULT OPTION(S) USJ;O SIlE=(196606,65536)
CROSS REFERENCE TABLE
ENTRY
CCNTROl SECTION
I'\AME
OldGIN
AefND
LlO
ILBOCOMO*
390
ILE(;SRV *
5uO
LENGTH
390
LOCATION
NAME
LOCATION
NAME
LQCA fION
NAME
lO:ATt [w
ILBOCOM
390
I LBOSRVO
ILBOSRVl
50A
50E
48E
990
128
ILtLCI'IM *
ABS
38B
E4~
NAME
169
ILBUBEG *
ILeOMSG *
CD
ILBOBEGO
992
I LBOCMMO
ABA
I LBOMSGO
E4A
I LBOS R5
ILBOSTP1
50A
50E
IUlaCMM1
ABE
50A
512
lLBDSR3
I LBOST
I UJSR.
lLBOSTP)
50A
512
F2
LeCAT ION _ Rt:fERS TO SYMBOL
I LBOSRVO
2eo
ILBOSRV1
2e8
ILBOCllM
850
858
I LBOBEGO
ILBOSND2
860
tl'\TRY ALORE:S~
00
!I\I
CONTROL SEC TI ON
ILBOSRV
I LBOSRV
ILBOCOMO
I lBOBEG
$UNRE SOL VEO ( W)
LOCATI ON
2C4
2bO
854
B5C
REFERS TO SYMBOL IN CC'NTIlOL SECT lC'N
ILBOSR5
ILBOSRV
ILBOCO~O
ILBOCO~O
ILBOCM~O
ILBOCMM
IlBO'"'SG
ILBOMSGO
TCTAL LENGTH
F40CD
DOtS NOT E:XlST BuT HAS BEEN ADDEO TO OATA SET
~***Gu
Al.THOKIZATION CODE: IS
u.
Figure 98.
COBOL Program That will Abnormally Terminate (Part 2 of 3)
Program Checkout
265
JGE AdENO
STEP GO
CGMPlE:TICN COuE
SYSTEM = vC7
PSW AT ENTRY TO ABEND
DATE 76229
TIME 124329
10
000
PAGE 0001
CD
ILC 6
078020Uu 0007539E
I NTC 0007
ASCS UOFE8A2B
~SC
"UCB
MCC
.:.MCT
TeB
70312B
fwUP
SPL
RSM
XWH
Fill
TCBS
ouxa
JBNI
SWTl
C 1E2C3C2
00000000
007FF548
89737AIF
007Ff008
00000039
00FE89C8
00000000
(JOOOOOOO
ASCB
WSP
LUA
ewST
uUMP
007F0900
007fC5A8
01074fBO
00000000
007f004C
00000000
00703250
00000000
E3C3C240
00000000}
00000000
xdP
r-lSS
/"SA
LTC
:. TAB
KESV
eXT2
TMSAV
,,10
KPT
eVENT
PIE
t'K-flG
TCB
IQf:
TCT
lOBRC
.. ECB
"B(R
xPtJ.
uBTB
KESV
00fE7E68
OOF E8Af 8
00FE88E8
02235000
FFFFOOOO
00000001
00FF2A48
00FE8370
00001410
00000000
80010000
00000000
00000000
807FC960
00000000
00000000
00000000
00000000
00000000
00000000
BWOP
CPUS
CSCB
JSTl
TMCH
LOCK
FMCT
J8NS
SRBT
DEB
FLG
TME
ECB
USER
XCPO
RESV
RESV
ESTA
SWAS
RESV
00FE6B08
00000001
00FE8BI0
0000011 E
00000000
00000000
002'00000
00FE8B20
00000000
00708798
OOOOFFFF
00000000
81 74
00000000
00000000
00000000
00000000
00000000
00709F30
00000000
oon
C'1SF
10SQ
TS6
ECB
ASXa
LSQH
XMPQ
LGCB
ATME
TID
LLS
JST
TSF
SQF
EXT
BAK
FOE
UKY
SC B
RES
00000000
001 EOOOIt
00000000
807F0790
007FF300
00000000
00000000
00000000
03336000
007C 0020
00703640
00703128
20000000
00000000
00000000
007FCAOO
00000000
007C8600
00000000
00000000
SVRB
lOOP
EJST
US ET
SilCT
QECB
IQEA
VGTT
CMP
JL6
NTC
O-PQE
"1010
BITS
RTMWII
SWA
CPVI
GTF
RESV
00000000
E242) 07B
00000000
8973742F
02570000
00000000
000):)00:)
0(0)00:)0
9JOC7JJO
007C B~ 50
00000000
007fF548
00000000
OOOOOJOJ
007DE:98
0070C050
0040FFFF
00000000
0)000) J:l
TPN
JPQ
OTC
AQE
JSCB
OAP
lOTI'
RESV
B'fTl
SYN:
00000000
OF 180: 00
10731000
OOlFF630
0)0:»)00
'tJOOOOOO
OJOOOOOO
OOOOJJOO
sro~
XJST
QSCV
SSP.l'
MECB
RTIIA
PCTT
00000000
007D3ltEO
007FCAOO
007C8Cl~
007FBF8't
OOJOOOOO
00000000
00000000
480'tOO:l)
SV~8 00000000
~ ES V 00000000
ACl lilt: RBS
7C9F9B
xESV
00000000 RcSV 00000000
RTPSWl 07802000
0001539E
RTPSW2 00060007
0007COCO
flG1
00000000
WI..-L-IC 00060007
xESV
00000000
APSW
00000000
SZ-STAB 001100B2
FL-COE 007034EO
PSW 07802000
0007539E
IoI/TTR 00000000
WT-LNK
00703128
KG 0-7
00703B50
00074FF8
00000040
007F26F4
007F2600
007F:AOO
007C0018
FDOOOOOO
xG 8-15
007C8150
807FC960
00000000
007FCFEO
70DCA602
00074FBO
40DCAeFC
007:8180
SVRB 7F0900
00000000
RTPSW2 00000000
xESV
00000000
xESV 00000000
RTPSII1 00000000
JOOOJ"OO
flG1
20000000
wC-L-IC 00020033
Fl-COE 00000000
PS~ :HOrlOOJ
00Dlt[l59J
I\I::SV
OCOOOOuO
"PSloI
00000000
SZ-STAB 001900;::2
"/TTR 00000000
.. T-U~K
007C9F98
007F25 F4
00:H53A4
50075416
00075160
0007536F
xG 0-7
00(,00000
50075432
00000040
000750(0
0007531.10
00J7516/\
OJ075392
5JJ753 EC
xG 8-15
00075370
000753EA
000750(0
007F0900
00FE8A28
0003AA64
00000000
00703128
"XTSA
00000000
50075432
00018C30
900C 7000
0070EC98
FF000368
40000101
00000000
00000000
RESV
00000000
00000000
00000000
00000000
;,CB
PRB
LOAe LIST
NE OOuOOOOO
RSP-COE uOH7660
CNT 00010001
CD
CDE
NCOE 0000000 ...
NCDE 00FEH7.;
7D34EO
FE7660
Xl/MJ 007C3000
XLlMJ 00FE7680
EPA 000750CO
EPA 00F2AOOO
RSP 007C9F98 NM GO
RBP 00000000 NM IGG019DK
JS E 000100JO
USE 000300JJ
un
0620000
ATTR 1')22000
SAVE AREA TRAI..E
GO
SA
MAS eNTERED VIA LINK
u74FBO
.. 01 00000000
00074FF8
FOOOOOOO
HSA 0;)000000
R:.< 00000040
R8
007C8150
LSA 00075168
R3
007F26F4
R9
807FC960
RET 00018C80
R4
007F2600
RIO 00000000
EPII 000750CO
R5
007FCAOO
Rll 007FCFEO
RO
007D3B50
R6
007COO18
R12 700CA602
wD1 00000000
HS" 0007H BO
R2 00000000
R8
00000000
lSA 00000000
R3
00000000
R9
00000000
RET 00000000
R4
00000000
R10 00000000
EPA 00000000
R5
00000000
Rll 00000000
RO
00000000
P6
OOOOOOOJ
R12 00000000
HSA 00074FBO
R2 00000000
R8
00000000
lSA 00000000
R3
00000000
R9
00000000
RET 00000000
R4
00000000
RIO 00000000
Rll
EPA 00000000
R5
00000000
00000000
RO
00000000
P6
00000000
R12 00000000
Xl
x7
SA
0751b8
00000000
00000000
K1
x7
INTERkUPT AT u7539E
CD
PRCCf:I:DING 8AI..K VIA REG 13
SA
075168
GO
.. 01 00000000
1<1
00000000
1\7 00000000
WAS eNTERED VIA LINK
REGS AT ENTRY TO A8END
fLTR 0-6
OOOOOOOOOOOuOOOO
0000000000000000
0000000000000000
0000000000000000
REGS 0-7
REGS 8-1:>
00000000
00015370
00000040
000750(0
000753A4
00075380
00075160
00075392
LOAC MODULE
C"i 5(CO
C15CEO
(j~lGG
01H20
Ci5HO
007F26F4
000750CO
50075416
0007516/\
0007536F
500753EC
GO
90ECUOOC
9602J.034
0007:.392
OOOOuOOO
OOOOuOOO
Figure 98.
266
:;.0075432
,,00753,,11
185D05FO
07FE41FO
000753AA
00000000
00000000
458vFOI0
000 ... 07fE
000",0000
OOOuOOOO
Flf,4Bf4
CIC2C505
000753EA
OOuOOOOO
00000000
F24BF5F2
C4404040
000750CO
00000000
00000000
C1E4C740
E5 E£ D9F1
000750CO
00000000
00000000
FlF66B40
0700989 F
00075380
00000000
00000000
F1F9F7F6
F02407FF
00075168
00000000
00000003
00000000
*••••••• O•• O. AB END
VSR 1 •••• O•••
*
* ••••••. 0 •••••••••••••••••••••••• *
*••...••....•.•.•.....•........•. *
* •••••••.••..•••••••.••••.••.•..•. +:
*•••.•••• 12.42.52AUG
H,. 1976 ••••
COBOL Program That Will Abnormally Terminate (Part 3 of 3)
*
LOAD 1I ST
NE 0018EbE8
NE 001CA008
NE 00 .. 00000
RSP-CDE .. Of:3558
RSP-CDE v07l:iE918
RSP-CDE .. 07CAE30
CNT 00010001
CNT 00010000
CNT 00010000
RSP-CDE )018E6F8
RSP-COE 0078E958
NE 0018E8F8
NE 001CH20
(NT OO(HOCOO
(NT (l00100»
CDE
7fC860
fC3558
78E6f8
,78E718
78E918
78E938
78E958
78E978
7CAE30
7CAE50
NCDE
NCDE
NCDE
NCDE
NCDE
NCDE
NCDE
NCDE
NCOE
NCDE
OOOOOOOv
7FC240
fC3578
78E8E8
78E908
7CA180
7FCC90
Sl 00000010
Sl 00000010
SZ 00000010
SZ 00000010
SZ 00000010
Sl 00000010
00fC31~v
0078E93"
0078E6fd
0078E97a
0078E91o
007CAE5u
007BE95..
007fC8bv
007CAE3u
RBP
R8P
R8P
RBP
RBP
RBP
R8P
RBP
007CA5C8
00000000
007fD900
00000000
007FD900
00000000
007FD900
00000000
R8P 007FD900
RBP 00000000
NM GO
NM
NM
NM
NM
NM
NM
NM ILBONTR
O
NM
NM
,II RBEBi
EPA 00015BE8
XlIMJ 007Fe 240
LIS E 00010000
000755F2
000755E8
0007611A
00076118
()007b4AA
EPA 000764AA
007BE718
007BE8E8
OHBE93B
0078E908
007BE978
007CAl BO
007CH50
007FCC90
OO):>()())
00010000
00000000
0001(\000
0000(\000
000100JO
0000(\000
00010000
NO
Nu
NO
NU
NO
NO
OOUOOOOI
00000001
OUOOOO01
00UOOO01
00000001
00000001
80000418
80000100
80000490
80000390
CEe
102760
7D27AO
7027CO
7u.21EO
702600
C87D'tODO
00240000
E2E2Li6C2
OC70c.798
Of 000900
OlC5E2F2
00140010
00704000
0001.10000
OOOuOOOO
007Li278C
OOOuOOOO
0070FE68
00000000
00000000
00000000
~
00702810
8f074030
00000000
007027F4
8S8H1U
ADR
LN
XL
e~l
LN
B
AOP.
LN
~.TTP
OB20000
l11COOO
1320000
3110000
3~20000
3710000
3320000
1710000
13200CO
--
02 B R~uEFINES A PICTURE S9(7) COMPUTATIONAL-3.
10053.; PROCeDURE DIVISiON.
10054<1 BEGIN.
10055.;
NOTE THAT ThE FOLLOWING OPENS THE OUTPUT FILE TO BE CREATED
100561.1
AND INITIAL~ZES COUNTERS.
10057<1 STEP-1. OPEN OUTPUT FILE-1. MOVE ZERO TO KOUNT NO~BER.
100581.1
NOTE THAT THE FGLLOwlNG CREATES INTERNALLY T~E RECORDS TO BE
1C059(1
CONTAINED IN THE FILE, WR1TES THEM ON TAPE. AND DISPL~YS
l0060u
THEM ON THE CONSOLE.
10061u STEP-2. AOD 1 Tu KJUNT, ADD 1 TO NOMBER, ~OVE AL~HA IKOUNT) TO
100b20
NAME-FIELO.
10063u
MOVE DEPEND (KUUNT) TO NO-OF-DEPENDENTS.
MOVE NOMBER TO RECORD-NO.
10064"
10065u STEP-3. DISPLAY WO~K-~ECORD UPON CONSOLE. WRITE RECORD-1 FROM
WORK .... RECORD.
100661.1
100671.1 STEP-4. PERFORM STEP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 26.
1006SU
NOTE THAT TnE fOLLOWING CLOSES OUTPUT AND REOPENS IT AS
1C069u
INPUT.
l0070u STEP-5. CLOSE FlLE-l. OPEN INPUT FILE-2.
1001lu
NOTE THAT THE FOLLOWING READS BA:K THE FILE AND SINGLES OUT
lOC72u
EMPLOYEES WiTH NO DEPENDENTS.
10073U STEP-6. READ FI~E-~ RECORD INTO WORK-RECORD AT END GO TO STEP-~.
COMPUTE ti = B + 1.
10013J.
10C74u STEP-7. IF NO-Qt"-DEPENDENTS I S EQUAL TO "D" MOVE HZ" TO
No-OF-DEPENuENTS. EXHIBIT NAMED WORK-RECORD. GO TO
10075u
10076U
STEP-6.
100770 STEP-8. CLOSE F1LE-Z.
10078u
STOP RUN.
Figure 100.
Program with Data Interrupt (Part 1 of 5)
Program Checkout
269
I NTRNL NAME
ONH;I-448
DNM;I-H.8
ONM;I-489
ONM;1-,06
ONM;I-,26
ONM;I-';47
ONH;I-,1>1
ONI1;I-,82
ONM;1-,98
ONM;I-.H2
ONM;1-.;>~0
DNM;I-.;I48
ONI1;I-.)68
DNM; 1-.;; 84
ONM;1-.. 08
ONM=I-'t211
ONM=I-442
ONM;l-..ol
ONM;1- .. 75
ONM=1-~93
ONM;2-uiH)
DNM;2-1.126
DNM;2-u40
ONM=2-lJoO
0,~M;2-1J71
LVL
fO
01
02
fO
01
02
77
77
01
02
02
02
02
01
02
02
02
02
02
02
02
02
01
SOURCe; NAME
BAS E
OCB=Ol
Bl=l
Bl=l
OCB;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
FIlE-~
RECORu-l
fI ELIJ-A
fllE-.::
RECORu-2
fIElD-A
KOUNT
NOM8En
f i l l E"
AlPHAoET
ALPHA
OEP EN"E'lT S
OEPENu
~ORK-KECORO
NAME-t- I El 0
fILlEn.
RECORu-~J
FIlLEl\
lOCAT!ON
flLlEn
NO-Of-DEPENDENTS
fILLE"
RECORuA
g~ ~-E
61
t4
64
<4
61:
0005E4
0005E4
(1005E4
0005E8
0005EC
0005EE
5btlUC080
5d FO C 024
05 i f
00vOu()3D
PN=OZ
START
0005F2
0005F2
0005F6
0005F8
0005FC
000600
000602
OOOt:Ob
00060A
000010
000614
000618
00061C
000620
000626
00062A
0006.?C
u00630
00063b
00063A
00063C
000640
000646
58 FO C 024
05 1F
00uOO\.l40
5d FO C 028
05 Ef(140
58 10
58 40
024
DL 02 4 Cll
50 10 0 234
92 OF D 234
90 80 D 234
41 lJ o 234
Dol 03 o 060
58 F(' C 030
0:> EF
58 10 C 040
UZ 03 D 360
sa FO C 030
05 EF
5d 70 o 200
02 01 6 000
02 01 6 002
00064C
00064C
000650
000652
000656
00065A
00065E
000662
000666
00066A
000t:6E
0000"12
000670
JG067A
00067C
000680
00068 ..
000688
00068E
000692
000690
00069A
00069C
ODObAIl
0006A4
Fu C 024
05 iF
00vOuu .. 4
48 3(; C 0:'2
4A 30 6 000
40 3\.1 6 000
4~ ~Li C 052
4A 30 6 002
40 30 6 002
41 4\.1 6 008
48 30 6 COO
5C 20 COSO
lA 43
5B 4\.1 C 050
5u 40 D 220
58 Ul 0 220
Do<: 00 6 040 E 000
41 40 6 0<:'2
4<1 3U 6 000
5L 2U C 050
lA 43
58 itO C 050
50 40 o 224
58 fU o 224
EQU
EQU
L
L
BAlR
DC
*
*
11,080(0,lZ)
15,024( (1,lZI
1.15
X' 00000030'
EQU
L
BALR
DC
L
BALR
L
L
MVC
ST
MVI
*
15,024(0,12)
1,15
X' OOOOOO~O'
15,028( O,1Z)
14,15
1,040(0,12)
4,024(0,11
? BL= 1
V( Il!'OFllo'lI
*STEP-l
OPEN
MOVE
PN=03
C 020
01
LA
MVC
L
BALR
l
"'VC
L
BAlR
l
MVC
"IVC
C 057
C 05B
C 050
C 050
V(! lBOFUH I
V(
IlBOO~G41
DC6=1
011(3,41,02D(I~)
1,23410,131
234(13I,X'OF'
234( 13) ,X' BO'
1, 234( 0,131
06) 14,131,)57( 12)
15,03010,121
14,15
1, OltO (0, 1Z1
060 14,13) , 056 ( 121
15,O30(0.111
14,15
7,20010,131
000(2,61,)5)112)
002 ( 2,61 ,050 ( 12 I
V( IL3COTOI
SA3 =1
SA3=1
S A3=1
SA3=1
rlC= 01
V(lLBO;)IOOI
DCB.-1
WC=01
LIT+7
LIT+ll
V(IL!,[)~IJOI
!H =1
DN'1=1-267
DNM=1-2B2
LIHO
LIT+O
*STEP-2
cE
ADD
oS
ADO
68
MJVE
70
STARTS AT lOCAr ION OOOAO FOR A LENGTH DF 00060.
*IlEGI,~
MUVE
Fiqure 100.
PN=04
5~
EQU
L
BAlR
DC
LH
AH
S TH
LH
AH
S TH
LA
Lt-l
'4
AR
S
ST
l
MVC
lA
LH
",
All.
S
ST
l
*
15, 024( 0,121
1,15
X' 0000004lt'
3, 052( 0,121
3,000(0,61
3,00010,61
3, )52(0.121
3,002(0.61
3,00210,61
4,OJ8(0,61
3,000(0,61
2, 050( 0,121
4,3
4,05010,121
4,220(0,131
14,220(0,131
04011,6),000(141
4,022(0,61
3,000(0,6)
2,05010.121
4,3
4,050(0,121
4,224(0.13)
15,22410,131
VIIUlGFUHI
lIT+2
DNM=1-261
DNM=1-U 7
LIT+2
DNM=1-2 ~ 2
DNM=1-Z82
DN"l=1-330
DNM=1-2 ~ 7
lIT+O
LI T+O
SBS= 1
SBS=l
DN"'=1-408
DNH=1-3E:e
DNM=1-267
L IT+O
D~!"=1-330
LIT+O
SBS=2
SBS=2
Proqram with Da ta Interrupt (Part 3 of 5)
Program Checkout
211
STEP GO
JOB TeSTRUN
CC~PLETION
TIME 202B35
DATE 76236
PAGE' 0('01
000
10
SYSTEM '" uC7
COOE
P Slol AT ENTRY TO ABEND
0180200 ... (i0015F46
ILC 6
INTC 0001
ASCB uOFCOCAO
ASCS
1 OSP
LOA
r;WST
uUMP
IISC
... uce
I~I,;C
:;MCT
r;B
7COB60
KilP
/ISS
FSA
LTC
:> TAB
Ki::SV
eXT2
fMSAV
dID
kPT
"VENT
FW')P
SPL
RSM
XWST
Fill
TebS
OJXB
JaNI
SWTl
C lE2C3C2
00000000
001FF548
891CAF22
OC1FFOOa
00000058
00FCOC40
00000000
00000000
001FD900
00101690
o 1014FBO
00000000
001FD04C
00000000
001COC88
00000000
E3C3C2't0
00000000
00000000
!'IE
PK-FlG
rCB
! QE
TCT
JObf(C
AEC6
AbCR
kTMl
u8Til
KESV
00FE83FB
00FC0070
00FCOB60
4016BOOO
FFFFOOOO
00000001
00FF2CC8
00fE8B98
00001410
BW)P
CPUS
CSCB
JSTL
TMCH
LOCK
FMCT
JBNS
SRBT
DEB
FlG
THE
ECB
USER
XCPD
RESV
RESV
ESTA
SWAS
RESV
00000000
80010000
00000000
00000000
a01FC010
00000000
00000000
00000000
00000000
00000000
00000000
DOFBCA2B
00000001
00FCDD88
OOOOOllE
00000000
00000000
00290000
00fCD098
00000000
00703B80
OOOOFFfF
00000000
0010EFB4
00000000
00000000
00000000
00000000
80000000
00100F30
00000000
CMSF
IOSQ
TSB
ECB
ASX8
lSQH
. XMPQ
lGCB
ATME
0000:>000
00200006
00000000
801F0190
001FF300
OOOOJJOO
00000000
00000000
33E16000
TID
00105020
0010EA'€0
001:0860
20000000
00000000
00000000
001FCAOO
00000000
UKY (J07011AO
SCB OOOOOOOJ
RES 00000000
SVRB
lOOP
EJST
USET
SWCT
QECB
IQEA
VGTT
CMP
JlB
NTC
D-PQE
MOlD
BITS
RTMWA
SWA
CPVI
GTF
llS
JST
lSF
SOF
EXT
BAK
FOE
HSV
JJJ)JJ:>
114E0079
OOOOOO!)!
891C998,6.
1AOCOOOO
0000(1000
00000000
00000000
900C1000
D:>7D1fOO
00000000
001FF548
00000»:>
00000000
0J1C01DO
00101820
0040FF F F
OOOOOJ()O
00000000
J)O(»JOO
OF35ECOO
FFOF2000
O:HFF630
00000000
4)OOJJOO
OJO()JOOO
00(100000
SYNC
STOP
XJ ST
QSCV
SSR8
"IECe
PTWA
p:rr
TRN
JPQ
OTe
AQE
JSCB
DAR
lOT"
RESV
00000000
001AC(l90
001FCAOJ
001:0:F8
:>0700F6ft
00000000
00000000
00000000
eVTl 48040000
SVAB OOJ()()OOO
RESV 00000000
ACT IVt; RBS
PRB
00015F46 RTP SII2 00060001
00000000
ReSV 00000000
RTPSWI 01802000
000160FF
02000000
W.. -L-IC 00060001
00000000
SZ-STAB 00110082
Fl-COE 00101 E08
PSI' :>7902JJJ
00000000
AI'SW
00:> 15F"'!>
... /TTR 00000000 Wl-lNK 007CDB60
0()10501B
00000040
001F26F4
007F26DO
001FCAOO
FDOOOOOO
k.G 0-7
007CFOIO
00074FF8
807FCOI0
00000000
001FCCOB
10OC4602
0001ftF!l0
kG d-15
0010EF90
007DEFCO
"'JDC~8 FC
1CF040
KESV
f'LGl
"ES~
SVRB 1F0900
KES \I 00000000
RTPSWI 00000000
00000000
RTPSW2 00000000
00000000
KESV
00000000
20000000
."C-L-I C 00020033
flGl
00000000
SZ-S TAB 00190022
KESV
00000000
AP5W
Fl-: DE 00000000
PSW 010:1000
000"'85'1J
001CF040
o,//TTR 00000000
IIT-lNK
1)1)01515!!
40015F3C
0001AA10
40015F3C
0000001A
000158C8
00015!>[18
kG 0-7
0001UlC
kG 8-15
0001AA10
00076082
000156BB
00015C9C
00015C 18
00015900
50015F24
E>OOlFC 3C
0001AA10
EXTSA
40015F3C
00018C30
001C0860
0J7F0900
OOFCOCAO
0003AA64
00000000
FFOO0368
001C0100
40000101
900C 1000
O()OOOOOO
00000000
00000000
00000000
00000000
OOJOO:lOO
RES V
:'CB
SVRB 1F0900
kESli 00000000
RTPSW1 00000000
00000000
RTPSW2 000:>0000
kESV 00000000
00000000
02000000
>iC-L-IC 0002000C
fLGl
APSW
SZ-STAB 00190022
Fl-COE 00000000
:l00:>B20E
KESV
00000000
00000000
PS~ J7)C2JJJ
.T~lNK
001F0900
.. /TTR 00000000
KG 0-1
OOOOOO~O
007C0600
00FE4040
0080E600
001COB60
0070800
500 ... B01C
007C0100
KG 8-15
00700E68
00000000
00700F50
00100ECO
0J7C07FO
001CD91t4
50D482e::
00000000
eXTSA
00000:l00
001C0418
000003B4
001F0964
0)00:>:>0:)
20FOOOOO
00000000
00000:)00
00000000
00000000
00000000
00000000
00000000
:'CB
00000000
00000000
00000000
00000000
RESV
OOJO:>JJ:>
LOAD LI ST
NE
NE
NE
NE
NE
001DEOBO
OOlACOSO
0070EOEO
00lDEB4a
OOuuOOOO
RSP-CDE
RSP-CDE
RSP-CDE
RSP-CDE
RSP-COE
IJOFE8[)[)0
.. OFECFOO
IJOFa02AO
u07DE140
1J01D1928
CNT
CNT
CNT
CNT
CNT
00010001
00010001
00010001
00010000
00010000
CDE
10lE08
H80DO
FE8EBO
fECFOO
1AC010
1 AC090
FBD2AO
FCD100
IDE140
7DEB28
70EB58
1DEACO
701928
7CB01O
Figure 100.
272
NCOE
NCOE
NCDE
NCDE
NCOE
NCDE
NCOE
NCDE
NCDE
NC DE
NCOE
NCOE
NCOE
NCDE
OOOOOOOu
00FE9n",
00FE08~u
00FEE18u
0010EB2o
001AC07u
00FCD10 ...
00FCE18"
0010EACu
0010El't ...
001CBOlu
001DES!)"
001DIEO ..
0010192c!
RBI'
RBP
RBP
RBP
RBP
RBP
RBP
RBP
RBP
R8P
RBP
R8P
RBP
RilP
001CF040
00000000
00000000
00000000
001FD9DO
00000000
00000000
00000000
007FD900
00000000
001FD900
00000000
007F0900
00000000
NM
NM
NM
NM
NM
NM
NH
NM
NM
NH
NM
N"
NM
NM
GO
IGG019DK
I[;G019AA
IGG019AQ
IlBOD220
IlBOD22
IGG019CW
IGG019CU
IlB00210
IlB0021
I lB00200
IlB0020
IlBODOI0
IlBODOl
NE
NE
NE
NE
001ACOBO
0010EOOO
0070E120
00101918
~
EPA 000156B8
EPA 00F2AOOO
EPA 00F1 EF60
EP~ 00BEI018
EPA 0007C6FA
EPA 0001C6FS
EPII 00806A40
EPA 00061898
EPA 00019614
EPA 00019678
EPA 00079C ... 2
EP4 00019::40
EPA 000753B4
EPA 000753A8
RSP-CDE
RSP-COE
SP-COE
RSP-COE
~
XlIMJ
XlI'IJ
XlIHJ
XlIMJ
XlIMJ
Xl/MJ
Xl/HJ
XlIHJ
XlIMJ
Xl/HJ
Xl/HJ
Xl/MJ
XlIMJ
XlIMJ
)OFEBEBO
OOHC:)70
00FC0100
001DEB58
001CFOOO
00FE80FO
OOFE8 EDO
OOFECFFO
001A::090
001 AC060
00FB02CO
OJFCD120
007DE B2S
0070E 130
0010EACO
001CBH8
001C8010
001CBOOO
Program with Dat.a .Interrupt (Part 4 of 5)
USE
USE
~S E
USE
USE
USE
USE
~SE
USE
USE
USE
USE
USE
LISE
CNT
CNT
CNT
CNT
OOtHOOOl
JOnOO)J
00010001
000100:>:>
JJJlJOJ:l
00010000
00020000
000300()0
00000000
JJJlJOJJ
00020000
00020000
JJOO:lOJ()
00010000
000(10000
00010000
00000000
:):l:>lJOJ()
un
OB20000
ATTR B022000
aTn 8022000
HlP B922000
HT~ 3710000
3320000
ATTI!. 1!023000
AlTP 8122000
HTP 3110000
ATT~ 3320000
Arr~ 3110000
ATTR 3320000
HlR 3110000
HTR 3320000
un
I NTERRUPT AT 075f46
PROCEEDING BACK VIA REG 13
SA
075900
11101 0030C4C2
0007AA70
0007AAIC
ru
k7
HSA ()()074fBO
Rl 00075900
RJ 0007AA70
RET 50075f24
R4
000758C8
RIO 000756B8
EPA 6001fC3C
R5
00075688
Rll 00076176
RO 40075fH
P6 00075758
R12 00375C18
LSA 00075900
R3 007F26f4
R9 i07fC010
RET 00018C80
R4 007f2600
RIO 00000000
EPA OJ075688
R5
007FCAOO
RU 007fCC08
RO 007CfO 10
R6
00705018
R 12 700CA602
WAS t:NTEREO VIA LI NK
GO
10101 00000000
HSA 00000000
R1
00074fF8
R2 00000040
K7
fDOOOOOO
R8 0070Ef90
VTAH NOT ACTlV E fOR THIS CALL
SA
LSA 00074B90
R3
ooooooIA
R9
00076082
074fBO
REGS AT ENTRY TO ABEND
FLTR 0:-6
000000000001,10000
0000000000000000
000000"0 " " ' ' ' \000000000 0000'00
REGS 0-7
kEGS 8-1!i
40075f3C
0007AA70
40075 F3C
00075OB8
000758C8
00075C18
L£jH MODULE
1.1007 AA70
u0076082
0156CO
, j 56EO
( j 51"
®
90ECOOOC
0700989F f02407fF 96021034
00075C18 00075900 00075: 9[;
00000000 00000000 00000000
185005FO
07FE41FO
00076042
00000000
45801-010
0001u7fE
ceoouooo
LINE 07~720
C15140
f2FO .. 8fl
015760
CIC2C3C4
015780
FlF2f3F4
0157AO
E8C3 .. 0FO
01 SleD
00000000
C151EO
00001.1000
(;15800
0000U006
015820
03C5,*040
'15E40
OOOOuOOl
015800
00001.1000
E3C5E2E3 09E .. 0540
00076082 000l56b8
00000000 0001.10000
SAME AS ABOVt;
f848f5f4 CIE.. C7'tO
e5CbC7C8 C90L0203
FOFlF2F3 F4f.. Flf2
40404040 404u4040
00000000 0001.10000
00000000 000 .. 0000
00830000 OOOlUOl
02000048 OOU.. O(/Ol
00000014 OOOuO;)Ol
00000000 OOOuOOOO
E5E209fl
000750B8
00000000
075680
00000000 ooouOOOO
SAME AS ABOV t;
00000000 OOOuOOOO
00000001 0001.10000
00000000 OOuuOOUO
900758C8 00C .. 4800
0007A920 0007AA04
00000000 OOOuOIlOO
00140804 OOOUOOOO
00000000 OOOuOOOO
00000000 OOOuOOOO
40075F3C 0001AA70
0007AA70 000160b2
00075C9(; OOOuOOOO
00075900 000u001A
000756B8 00075C 9C
0000001A 08f"FUUO
07F20000 000U09C8
00000000 OOOuOOOO
000750AO OOuuOOOO
80C75900 000759uO
00076082 00075bB8
00000000 OOOuOOOO
00000000 OOuuOOOO
00000558 00078096
00000000 00075:9[;
00000000 OOOuOOOO
oa00001C 0001.10000
80075900 OOOUOOOO
00076C 18 00018900
0007.,082
0007:> 7F4
5820iJIA8
OOOOuOOO
6007!)D48
0007:>960
OOOOuOOO
OOOOuOOO
0000,,000
000hbB8
OOOOuOOO
00001)000
OOOOuuOO
0000..,000
C7FBJOOO
0007b172
0007:;OFb
0004.. 000
f2f36B40
flF9F7Fb 00000000 OOlAOOU 00000000
04050007
0809E2E3 E4E5E6E7 E8E9FOFl F2F3F4FO
F3f4FOfl
F2F3F4FO 00000000 C140FOFO FOFl4005
00000000 (D/flf2F3C4/ 00000000 00000000 00000000
0507795A
0007500E 00000001 00000001 00000000
00000000
80000000 00000000 00000000 00000000
00004000
00000001 46000001 00:>757Be E2CI0407
08000001
00000004 00000000 00000001 00000001
00000000
00000001 05EF:>70() 00000000 00000000
00900000
00000000 02000001 00140014 00000000
0007AA1C
6001FC3C
LAH PSIol 8EfOKE ABEND
00000000
00000000
0507AAOO
00BEI018
00000001
00000000
00000000
00000000
00074FBO
000758C8
00075C18
50075F24
00075758
46075F36
58800108
00000000
01000000
500760E6
000756B8
00000000
00000000
00000000
E380000C
00000000
0007AA70
00075793
16340000
00076176
00075F36
00000008
0609C400
0507795A
00000000
00004000
07000001
00000000
00900000
00000000
00000000
00074890
00075688
3002804B
12F1EF60
0007AAIC
0007AC10
F8700210
00000000
0007508C
00018C80
00075758
00000000
00000000
40075F3C
00075740
00000000
00075758
00()750F6
50BOOI08
0007845A
000757F4
00000000
00075C9C
0007560E
80000000
0007A8BB
00000064
00B06A40
00000000
00000000
00000000
50075F24
00075758
00000000
0007AC10
0007BFE8
80075900
C0560700
00000000
00076F6A
0007795A
0007AA1C
00000000
00000000
6007B39C
00000000
000:) O()OO
00000000
000750F6
58BOC01C
000779AE
00015900
48140000
5880C080
*
•••.•.•
0*
* •• 0. TESTPUN VSP 1 •••• 0 •••••••••• 0*
* •••••••••••••••••••••••••••••••••
* •••••.••..••..••..••.•...••.•... *
*20.18.54AUG 23. 1976 •••••••••••• *
*A8COEFGHIJKL MNOPQRSTUV"XYl 012340*
0001 N*
*YC 0
•••• 1230 ••••••••••••
.1234012~401234012340 •••• A
*
*••.....••.•...••.•..•....•.•....• *
* •.•.•..••••••.••••.••...•.•.•..• *
* ••••••••••••••••••••••••••• SII"IP*
*LE
••••••••••••••••••••••••••••
*
* •....•••....•••.•.••.•.......•.. *
* ..•..•.............•............ *
* •••••••••••••••••••••••••••••••• *
* •••••••••••••••••••••••••••••••• *
* •••••••••••••••••••••••••••••••• *
* •••••••••••••••••• C•••••••••••• *
* ••••••• H ••••••••• l •••••••••••••• *
" ••••••••••• M••••••••••••••••••• *
* •••••••••••••••••••••••••••••••• *
* . . . . . . . . . . . . . . . . . . . . ••••••••••• *
* •• '•••••••••••••••••••••••••••••• *
* •••••••••••••••••• 01' •••••••••••• *
H••••••••
* •••••••••••••••••••••••••••••••••
* •••••••••••••••••••••••• 1 •••••• *
* ••••••••••••••• H••••••••••••••• y*
* ••••••••••••••••••• 0 •••••••••••• *
* ••• 4 ••••• 00 ••••••••••• JQ8.K ••••• *
* •• J •• 2 ••••• H •••••••••••••••••••• *
* •••••••••••••••••••••••••••••••• *
* ••••••••••••••••••••••• \! •••••••• *
* ••••••••••••••••••• 1-' •••••••••••• *
* ••••••••••••••••••••••
*
*•••••••••••••••••••••••••••••••• *
*
* ••••••••••••••••••••••••••••••••
* . . . . . . . . . . . . . . . . . . . . . . . . . •••••• *
* •••••••••••• SYSOUT
T. ••••• • ••• *
* •••••••••••••••••••••••••••••••• *
*•••••••••••••••••••••••••••••••• *
*
*
*
*
*
*
••••••••••••••••••••••••••• 6 ••• 6*
•••••••••••••••••••••••••• JQ •••• *
•••••••••••••••••••••••••••••••• '"
••••••••••• S ••••••••••••••• 4 •••• *
••• 6 ••••••••••••••••••••••••••••
••••••••••• I'O~K.RECORO ••••••••• *
*
COBOL ABEND DIAGNOSTIC AJOS
TES~RUN
PHGRAM
00075758
5()075F24
GO
C156AO
0/
0000001A
00075C9C
Ff8500u7ElI075f46
SYSTEM COMPLETION CODE = OC7
LAST CARD NUM"ER/VERB NUMBER EXECUTED -- CARO NUMBER 00008l/VERB NUMB ER 01.
TESTRUN
FLOW TRACE
0000.,8 000072 000068 1)00072 000068 000072 090068 000072 000077 000080
Figure 100.
Program with Data Interrupt (Part 5 of 5)
Program Checkout
273
r---------------------------------------------------------------------------------------,
21
24
I
DCB
~----------T------~---T------------------------~
~
J DCBBUFCB I
-----------~----T-----~------------------------
r---------------
I
12
8
V
Buffer
Area
r-----------T--------T-------------------------~
IA (Area) I
Buffers
I
l-----------~---T----~-------------------------J
<-----BUFCB-----+---->
I
r---------------
I
V
Logical
Record
Area
I
J
I
I
I
I
5
J
24
6
32
r-------T---T------------T--------T-------------I
I
I
J
I
l _______
~
___
~
____________ ________
~
~"
control
data
~
_____________ _
~
I
I
I
I
variable
data record
origin
J
displacement
field
l _________________________________________________________
Figure 101.
~
_____________________________ J
Locating the QSAM Logical Record Area
Area-Address points to the origin of
the Logical Record Area.
Q~jl:
QSAM (sequential) spanned records
allocate a Logical Record Area in Which
complete logical records may be assembled
(see "Record Formats").
Figure 101
illustrates the relationship between the
DCB, the Buffer Areas, and the Logical
Record Area.
1.
The DCB contains the DCBBUFCB field at
a displacement of 21 bytes from the
origin of the DCB. The contents of
DCBBUFCB points to the origin of tb~
Buffer control Block (BUFCB) in the
Buffer Area.
2.
The BUFeB field contains an
Area-Address (A(Area»
at a
displacement of 8 bytes from the
origin of the Buffer Area. The
274
3.
The Logical Record Area contains a
displacement field at a displacement
of 5 bytes from its origin. This
field contains a value from 0 to 8
indicating the number of bytes the
record has been displaced. The
contents of this 1-7 byte field must
be added to the value 24 (the first
byte in the variable data record
origin area) in order to locate the
beginning of the logical data record
within the Logical Record Area.
Note
tha t the first 4 bytes of the Logical
Record Area are control data
indicating the length of the Logical
Record Area (including the 4 bytes of
control data).
!iQ.i£: The Logical Record Area is .not
alloca ted for QS AM records formatted in V,
u, or l' mode.
r---------------------------------------------------------------------------------------,
variable
4
variable
<----bytes----><-bytes-><----------bytes---------->
r--------------T----T--T--------------------------~
IL______________
REC-ID
I ____
LL 1111
Maximum 01
~
__ L ____________________________
~
~
~
Logical Record Area
J
18
variable
4
variable
<--------bytes-------> <--bytes--><-bytes-><--------bytes-------->
I
I
J
r----------------------T---------T----T----T----------------------~
IL ______________________
BUFCB
I _________
REC-ID I ____
LL' ____
III ____________________
Data Segment
~
I
I
I
----------~---~----- -----------------~----------------I
Buffer
Segment Work Area
I
Control Block
I
IL ______________________________________________________________________________________ _
~
Figure 102.
~
~
~
Logical Record Area and Segment Work Area for BDAM and BSAM Spanned Records
~~A~-And_]DA~:
BSAM and BDAM (direct)
spanned records allocate a Segment Work
Area. This work area is used for temporary
storage of record segments before a
complete logical record is assembled in the
Logical Record Area.
Figure 102
illustrates the Logical Record Area and the
Segment Work Area.
2.
The DECB address plus 12 bytes points
to the beginning of the Logical Record
Area.
1.
The DECB address plus 12 bytes points
to the beginning of the Segment Work
Area.
2.
The DCB address plus 100 bytes points
to the beginning of the Logical Record
Area.
The segment work area is not
allocated for BSAM and BDAM records
formatted in v, U, or F mode.
Noi~:
The following discussion illustrates the
relationship between the DCB, the Logical
Record Area, and the segment Work Area as
shown in Figure 102.
1.
The DeB address plus 100 bytes points
to the b~ginning of the BUFCS (Buffer
Control Block).
2.
The contents of the BL assigned to the
level-Ol entry in an FD points to the
Logical Record Area labeled "Maximum
01" in Figure 102 (see Figure 98 for
an example of the BL pointer.)
In a teleprocessing application, control
blocks, called fU!~!lSLhlQ£!'§, are created
for a given partition/region.
For input
operations, the number of queue blocks
created agrees with the number of queues
accessed. For output operations r however r
only one queue block is created for each
partition/region. The numerals within the
boxes in Figures 103 and 104 refer to the
numbered paragraphs below.
1.
!!~Alt out~y!
1.
~
The DeB address plus 76 bytes points
to the beginning of the BUFCB (Buffer
Control Block).
The TGT address plus 440 bytes points
to the SUBCOM field (see Figure 184 in
Appendix J: "pields of the Global
Table"). The fullword at X'50' bytes
into SUBCOlt points to the first
RECEIVE queue block. The fullword at
Program Checkout
275
X'S4' off SUBCOM points to the SEND
queue block. In both =ases, the first
field contains the data control block
(DC B) •
Hela ti ve
Location
0
58
2.
At X'S8' bytes into either a RECEIVE
or a SEND queue block, the first byte
of the 4-byte field indicates whether
the address that follows represents a
TCAM buffer or a BSAM buffer. If the
two high-order bits are on, the
address contained in the next three
bytes is for a TeAM buffer.
5C
5E
60
61
62
!.21~:
For TCAM there is only one
buffer; for BSAft there is one buffer
for each queue.
64
68
6C
Rela ti ve
Location
,
Field
0
RQBDCB
,
RQBUFAD
I
J
j
58
I
70
-,
r-
2
Field
,
I
IHADCB
lI
l-
SQBUFAD
I
t
i
f
r
74
f
I
t
I
I
lJ
lI
lI
I
I
SQBUFSIZ
2
3
J
-I
SQlIORER 8
I
f
SQBENDIC 10 I
SQBRECDL
12
Reserved
SQBDNLH
,.
SQBlIPLFH
•
SQBPBFH
17
18
t
I
f
I
I
I
i
I
~
19
lI
,
SQBFSTOA
20
I
SQBFSTOL
21
I
t
I
..
I
L--
Figure 104.
Fields of the SEND Queue Block
I---------~
SC
I
RQBUFSIZ
.3
5E
•I
RQBSUMGV
4
60
74
18
7A
90
98
99
9A
9B
9C
AO
Figure 103.
t---
,
.,
,
I
5
t
RQBNEXT
6
J
f
I
RQBAMTL
7
J
l-
I
f
RQBDTS 9
I
I--BQBDDNAM 11
,
I
I-
~
12
13
14
I--1
I
I
I
I
Reserved
RQBNBL
RQBQN AlIE
4.
The BQBSOllGV field of the RECEIVE
queue block indicates the number of
bytes of data given to the user for
this request.
-
5.
The RQBDECB field of the RECEIVE queue
block contains the data event control
block (DECB).
6.
In the RECEIVE queue block, the
RQBNEXT field provides the address of
the next queue block.
If this field
is zero_ there are no additional queue
blocks.
1.
The RQB1MTL field of the RECEIVE queue
block indicates the amount of data
being held from the last request.
8.
For BSA! only, the SQHORER field of
the SEND queue block indicates the
number of unused bytes left in the
buffer.
9.
The 22-byte RQBDTS field of the
.
RECEIVE queue block contains the date
and time of the last message received
from this queue, as well as the source
of the message.
I
I---
RQBRECDL
I
I--RQBHELDC
I
I--RQBISITP
I
In ei ther a RECEIVE Or a SEND queue
block, this field specifies the size
of the buffer, whose format is
pictured in Figure 105.
(For a list
of codes used in the TCAM control
byte, see Figure 106.)
I
RQBDECB
I
I
3.
15
16
J
,
,
,
I
I
I
I
I
I
I
I
Fields of the RECEIVE Queue
Block
10.
216
The SQBENDIC field of the SEND queue
block contains the end indicator (in
zoned decimal) specified in the COBOL
source statement.
11.
The RQBDDNAM field contains the ddname
for the queue block specified in the
COBOL teleprocessing program.
12.
The RQBRECDL field in the RECEIVE
queue block and the SQBRECDL field in
the SEND queue block contain the
record delimiter specified in the MCP.
13.
The RQBHELDC field in the RECEIVE
queue contains a character that, in
some instances, is the next data
character.
14.
The RQBISITP field in the RECEIVE
queue block is a switch byte.
15.
The RQBNBL field contains the
enable/disable link.
The RQBQNAME field contains the TCAM
queue name.
11.
The SQBDNLH field contains the head of
the DNL (destination name list).
18.
The SQBMPLFH field contains the free
list head of the MPL {message phrase
list).
19.
The SQBPBFH field contains the free
list head of the PB (phase buffer).
20.
The SQBFSTOA field contains the free
storage pointer.
21.
The SQBFSTOL field contains the free
storage length.
5
6
•
A dump (ABDUMP) is produced by the
system.
• The data sets in the job steps are
disposed of as specified in the DISP
parameter (i.e., kept, deleted, etc.).
This is indicated in the job scheduler
disposition messages produced for the
job step.
• Temporary data sets, including those
passed from previous job steps, are
deleted.
16.
1
If a job is abnormally terminated and
the abnormal termination process goes to
completion, the following procedures are
carried out:
When the abrrormal termination process
does not go to completion (i.e., no end of
dump message is present), none of these
procedures will be carried out. Those
data sets in the job step that were in
existence previous to the point at which
the error condiiion occurred will remain
in effect.
For data sets on direct access
volumes, the names will remain tabulated
in the Volume Table of Contents (VTOC) of
the volume (see "Additional File
processing Information" for details on the
VTOC).
The result of an incomplete
abnormal termination is that space needed
by a subsequent job will be unavailable,
or, if the same job is then Dermn,
duplicate name definition will result for
those dat. sets that are newly created in
the job step. This is true for temporary
data sets for which the system has
assigned the name, as well as data sets
for which the programmer has assigned the
name.
14
========I===I===============I===~_~=====_
~'-v-'~
V
prefix
TCAM Source 1D
control
Byte
_ _-
~
__
Data
Note:
The prefix, the TCAM control byte.
and the source 1D must be user specified
for a SAM file~
However, if the user
invokes the SEND statement to create a
SAM 'file for subsequent input" then the
COBOL compiler adds bytes 1 through 13
(see Figure 148 in the chapter entitled
"Using the Teleprocessing Feature").
Figure 105.
structure of a TCAM Record
Program Checkout
271
r-
,
,
I Code IMeaning
~
I
I X'Fl'tThe first block of a multiblock
I
J message
,
I
J X'F5'JThe first block of a multiblock
I
I
message, wi th end of segment
I
I
indicated
I
I X'40'JAn intermediate data block
,
I
J
X'F4 t )An intermediate data block, with
•
• end of segment indicated
I-I
I X'F2'IThe last block of a multiblock
1
Jmessage
r
I
~
I
,
J
I
I
I
~
I
I
I
I
-i
I
I
I
t
t X'F6',The last block of a multiblock
I
t message, with end of segment
f
I
indica ted
I
f
J
r-~
i
1
I
, Xt F7')A single block message, with end
I
1
1
I X'P3'IA single block message
I
Jot segment indicated
1--
I
Information on how to use these utility
programs is contained in the publication
OS/VS Utilities.
OBTAINING EXECUTION STATISTICS
Execution statistics are invoked via the
COUNT option at compile time and the
presence of SYSDBOUT and SYSCOUNT DD
statements at execution time.
No source
language coding changes are required.
COUNT facilitates testing, debugging, and
optimizing by providing the programmer with
verb counts at the following times:
I
•
Figure 106.
If the programmer wishes to obtain a
listing of the names of all the data sets
on a volume, including system-assigned
internal names, he can use the uti.lity
program IEHLIST. This program provides a
listing of the VTOC of the volume.
Codes Used in the TeAM Control
Byte
•
•
•
•
STOP RUN
GOBACK in the main program
Abnormal termination of a job.
At CANCEL time, verb counts for the
canceled program and any of its
subprograms.
SCRATCHING NON-VSAM DATA SETS
When COUNT is specified, the following
items should be taken into account:
To avoid duplicate name definition and
to ensure that space will be a vailable for
newly created data sets, the programmer can
scratch his direct-access volume data sets
hy using the utility program IEHPROGM. To
scratch such a data set means to remove its
data set label (which includes its name)
from the VToe and to make the space
assigned to it available for reallocation.
Scratching does not uncatalog any cataloged
data sets. This is done by the UNCATLG
option of the IEHPROGM.
If a DSNAME parameter has been specified
in the DD statement for the data set, the
IEHPROGM utility program requires the name
of the data set. Fdr data sets named by
the programmer, the specified name is the
dsname. For data sets for which the
DSNAME=&&name convention has been used, an
internal name
1.
When COUNT is specified, the compiler
divides the program into blocks of
verbs. When the statistics are
printed, the last block o.f verbs
executed in each program u~it 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.
2.
If COUNT is requested, the user may
need to increase the REGION 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 (seethe
compiler output statistics). The
requirements for each program uni tare
rounded to the next 128-byte boundary.
3.
The OTHERWISE verb is treated as if
the user coded the ELSE verb.
4.
Both the SYSDBOUT and SYSeOUNT DD
statements must be specified at
execution time.
SYSyyddd.Ttttttt.axnnn.jobname.name
is assigned by the system, where job!ig,~ is
the name of the job and M!!~ is from the
&&name. If no DSNAME parameter is
specified, an internal name is assigned by
the system. For data sets with no DSNAME
param~ter there exists an option by which
the programmer can specify that all such
data sets on the volume be scratched,
without having to specify their names.
278
2.
All infrequently used paragraphs or
sections should be grouped together
and apart from frequently-used
routines.
3.
The most frequently-referenced data
items should be placed in the
beginning of the Working-Storage
section.
The execution statistics clearly
identify the following areas of the
program:
• untested and weakly tested areas of the
proqram
• The last blocks entered and executed
• Possible sources of unnecessary code
• The most heavily ~sed parts of the
program; that is, those parts most
susceptible to changes.
OPTI~IZATIONMETHODS
Based on execution frequency, the
following types of optimization can be
implemented by the user:
Insight into SYMDMP
out~!
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.
• Resequencing the program
• Insight into
SY~DMP
~Q~mon
Expression
Elimina~iQQ
• Common expression elimination
• Backward movement
• Unrolling
• Jamming
• Unsw itch ing
• Incorporatimg procedures in line
This technique is designed to eliminate
unnecessary arithmetic calculations.
An
arithmetic expression calculation is
considered unnecessary if it represents a
value calculated elsewhere that wi~l always
be used without modification. One such
example would be an arithmetic expression
whose operands are not .redefined or
reeval ua ted, but the expression is
recalculated.
• Tabling
• Efficiency guidelines
Backward
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.
Sg2~guencing
the Prog£A!
The COBOL Procedure Division should be
organized as follows:
1.
111 frequently-used paragraphs or
sections should be located near the
routines that use them.
Movem~nl
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 PERFORM
procedure (using a Format 2, 3, or 4
PERFORM statement) which always yields the
same value for that PERFORM statement could
be calculated inline or in another
procedure which would be executed just
prior to the regularly executed PERFORM
procedure.
Another example might be an
expression which is calculated in many
procedures which are often executed by va y
of a·PERFORM in succession. This
expression could be removed from all the
procedures and calculated just once prior
to the procedures.
Program Checkout
279
ADD 1 TO WEEK-NUM.
ADD GROSS-SALARY {WEEK-NU~
TO YEARLY-G ROSS.
ADD NET-SALARY (WEEK-NUM)
TO YEARLY-NET.
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,
PERFOR M
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
PERFORM
KOUNT=O
PERFORM
YEARLY-GROSS-CALC VARYING
WEEK-NO
FROM 1 BY 4 UNTIL WEEK-NO
GREATER TH AN 52.
YEARLY-GROSS-CALC.
ADD
GROSS-SALARY
GROSS-SALARY
GROSS-SALARY
GROSS SALARY
YEARLY-GRO SS.
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
(WEEK-NO),
(WEEK-NO.1),
(WEEK-NO.2),
(WEEK-NO.3) TO
In addition, indexing might be useful in
this exa mple.
JOBS-TOTAL-CAL JOB-NUM TIMES.
JOB-TOTA.L-CAL ..
ADD 1 TO KOUNT
ADD JOB-COST (KOUNT) TO TOTAL-JOB-COST.
IF SWITCH = 0 ADD JOB-EXPENSE (KOUNT)
TO TOTAL-EXPENSES ELSE
ADD JOB-EXPENSE (KOUNT) OVERHEAD TO
TOTAL-EXPENSES.
ADD JOB-INCOME (KOUNT) TO TOTAL INCOME ..
IF SWITCH = 0 ADD JOB-PROFIT (KOUNT) TO
TOTAL-PROFITS ELSE
COMPUTE TOTAL-PROFITS = TOTAL-PROFITS •
JOB-INCOME (KOUNT) JOB-COST (KOUNT) - JOB-EXPENSE (KOUNT)
- OVERHEAD.
by
In some instances, tvo procedures can be
merged into one procedure, thereby saving
some procedure overhead.
An example of
this might be replacing
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.
280
KOUNT = 0
IF SWITCH = 0
PERFORM JOB-TOTAL-CAL-O
JOB-NUft TIMES ELSE
PER FORM JOB-TOTAL-CAL-l
JOB-NUM TIMES.
JOB-TOTAL-CAL-O.
ADD 1 TO KOONT.
ADD JOB-COST. (KOUNT) TO TOTAL-JOB-COST.
ADD JOB-EXPENSE (KOUKT) TO
TOTAL/EXPENSES.
ADD JOB-INCOISE (KOUNT) TO TOTAL-INCOKE.
ADD JOB-PROFIT (KOnNT) TO
TOTAL-PROFITS.
JOB-TOTAL-CAL-1.
ADD 1 TO KOUNT
ADD JOB-COST (KOUNT) TO TOTAL-JOB-COST
ADD JOB-EXPENSE (KOUNT), OVERHEAD TO
TOTAL- EXPENSE
ADD JOB-INCOME (KOUNT) TO TOTAL-INCOliE
COMPOTE TOTAL-PROFITS = TOTAL-PROFITS •
JOB-IHCOME (KOUNT)
- JOB-COST (KOUNT) - JOB-EXPENSE
(KOUNT) ~ OVERHEAD.
Ia£Q£22r~ting
Procedures
I~
Based on module size, number of
repetitions, modification activities,
future expansion considerations, and
frequency statistics, small procedures can
be moved inline to minimize overhead
require.ents.
This technique is designed to replace
many IF statements by one table-look-up
statement, 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
consec uti ve sta temen ts of the form "IF
data-item-1 = some-constant GO TO
some-procedure" could be replaced by one
computed GO TO statement.
Based on execution frequency statistics,
the following types of coding
inefficiencies may be removed.
1.
Unaligned decimal places in arithmetic
or numer ic comparison operand s.
2.
Different size operands in moves,
comparisons, or arithmetic operations.
3.
Mixed usage in arithmetic or numeric
comparison operands.
4.
Display usage in arithmetic operands
or one numeric operand and one display
operand in a comparison.
5.
SYNC missing for COMP or COMP-1, -2,
or -4 items.
6.
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.
7.
certain calls to object-time
subrout ines.
8.
Indexing instead of subscripting and
vice versa.
9.
Noncomputational subscripts.
Program Checkout
281
Some techniques for increasing the
efficiency of a COBO.L program are described
in this chapter. It is divided into seven
parts. The first four parts deal in
general with coding a COBOL program. The
fifth is concerned with the Report writer
feature, the sixth with table handling, and
the seventh with queue structure
descript ion.
• All frequently used subroutines should
be loaded near each other. This can be
done via linkage editor control cards.
• PDs for files that will be opened at
the same time should be grouped
together.
• 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:
There are four statements that can be
coded in any or all of the four divisions
of a source program: SKIP1, SKIP2, SKIP],
and EJECT. These statements provide the
user with the ability to control the
spacing of a source listing and thereby
improve its readability.
a.
All frequently used paragraphs or
sections should be located near the
routines that use them.
b.
All infrequently used paragraphs or
sections should be grouped together
and apart from frequently used
routines.
These suggestions will aid efficiency:
• Use the RES option and place frequently
used COBOL subroutines into the Paged
Link Pack Area.
• Avoid repetitive sequences of
CALL
CANCEL
for the same subprograms.
• If a short subprogram is referenced
only once or twice (and is not an
unusual situation routine), then its
code should be incorporated in the
calling program, if convenient.
• subprograms should be loaded near the
programs which use them.
This can be
done via linkage editor control cards.
To make optimum use of buffer space
allocated when creating a physical
sequential file with blocked V-mode
records, the programmer may use the APPLY
WRITE-ONLY clause for the file.
Use of
this option causes a buffer to be truncat.ed
only when the next record does not fit in
the buffer.
(If the APPLY WHITE-ONLY
clause is not specified, the buffer is
truncated when the maximum size record will
not fit in the space remaining in the
buffer.)
When using APPLY WHITE-ONLY, all
the WRITE statements must have FROM
options.
None of the subfields of the
associated records may be referred to by
procedure statements and they may not be
the object of the DEPENDING ON option in an
OCCURS clause.
• Se gman ta tion in many cases is no longer
desirable.
• Data-names of constant value should be
grouped together. Data-names whose
values vary during execution should
also be grouped together and should be
separate from those of constant value.
282
Except for APPLY WRITE-ONLY, ADVANCING,
POSITIONING. and APPLY RECORD-OVERFLOW, all
the options for variable length record
files apply to spanned records.
For non-VSAM files~ the APPLY
RECORD-OVERFLOW clause makes more efficient
use of direct access storage space by using
the Track overflow feature. If APPLY
RECORD-OVERFLOW is specified, a record that
does not fit on a track vill be partially
written on that track and the remainder
vill be written on the next available
track.
OVERALL CONSIDERATIONS
The absolute maximum of the Data
Division (excluding Linkage Section)
is 1,044,480 bytes.
(This includes
File, Working-Storage, Communication,
and Report Sections.)
Other maximum
lengths (in bytes) are:
The use of the APPLY RECORD-OVERFLOW
option requires that Track Overflow be
specified at system generation time.
• data description entry -- 32,767
• variable length table -- 32,767
• fixed-length group item (including
fixed~length table) in Working-Storage
or Linkage section -- 131,071
To minimize processing time with indexed
sequential files accessed randomly, the
programmer should use the APPLY CORE-INDEX
clause. Use of this option causes the
highest level index to be brought into main
storage for input/output operations. This
speeds processing by eliminating the extra
time needed to search the index on the
volume.
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-PILE
01
The use of BDAM-W for file organization
results in less system generated coding
than for BDAK-D. When BDAM-D is used and a
WRITE statement is issued, extra code must
be generated to compare the contents of the
ACTUAL KEY of the WRITE statement with the
key of the preceding READ statement to
determine whether the system should add or
update a record. If the keys are the same
the record is updated.
If the keys are
different the record is added.
BDAM-W eliminates this comparison step.
The system adds a record when a WRITE
statement is issued and updates a record
when a REWRITE statement is issued.
ih2
MASTER-INPUT-RECORD.
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. Por example, if three files
all have a date field, instead of DATE,
DAT, and DA-TE, use MASTER-DATE,
DETAIL-DATE, and REPORT-DATE.
Using a
unique prefix for each level-01 and a11
subordinate fields makes it easier for a
person 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 asing the MOVE statement with the
CORRESPONDING option and referring to
individual fields, redefine or rename
programming Techniques
283
«corresponding" names with the prefixed
unique names. This technique eliminates
excessive qualifying. For example:
01
MST-WORK-AREA.
p**)
05 SAME-NAMES.
10 LAST-NAME PIC •••
10 FIRST-NAME PIC •••
10 PAYROLL PIC •••
05
01
DIFF-NArtES REDEFINES SAME-NAMES.
10 MST-LAST-NAME PIC •••
10 MST-FIRST-NAME PIC •••
10 MST-PAYROLL PIC •••
RPT-WORK-AREA.
05 SAME-NAMES.
(***)
10 PAYROLL PIC •••
10 PILLER PIC •••
10 FIRST-NAME PIC •••
10 FILLER PIC •••
10 LAST-N AM EPIC •••
The programmer should use the RECORD
CONTAINS integer CHARACTERS clause in order
to save himself as well as any future
programmer the task of counting the data
record description positions. Also, the
compiler can then diagnose errors if the
data record description conflicts with the
RECORD CONTAINS clause.
COMMUNICATION SECTION
The Communication Section of a COBOL
program must be specified if the program is
to take advantage of the Teleprocessing
Feature (TP). Through the inclusion of
communication Description (CD) entries, the
programmer establishes communication
between the COBOL object program and the
Message Control Program (KCP).
PROCEDURE DIVISION.
IF MST-PA~ROLL IS EQUAL TO HDQ-PAYROLL
AND MST-LAST-NAME
IS NOT EQUAL TO PRRV-LAST-NAME
MOVE CORRESPONDING
MST-WORK-AREA
TO RPT-WORK-AREA.
!Qte:
Fields marked with a triple asterisk
(***) in the foregoing listing must have
exactly the same nalles for their
fields in order to be
considered corresponding. The same names
must not be the redefining ones, or they
viII not be considered to correspond.
When specified, the communication
Section must contain at least one CD entry.
For example, a single CD entry vould be
sufficient for applications with either an
input or an output message but not both.
A
COBOL TP. program that is both to receive
and to send messages must contain at least
two! CD entries, as below.
subo~dinate
CD cd-name FOR INPUT.
CD cd-name FOR OUTPUT.
The CD entry may instead be pre-written
and included in the user-created library.
The prog.rallmer may then include the entry
in a COBOL program by means of a COpy
statement.
CD cd-name COpy library-name.
The programmer should use videly
incremented level numbers, i.e., 01_ 05,
10, 15, etc., instead of 01, 02, 03, 04,
etc •• in order to allov rooll for future
insertions of group levels. For
readability, indent level numbers.
Use
level-8S numbers for codes. Then. if the
codes must be changed, the Procedure
Division coding for tests need not be
changed.
The input CD contains such information as
input queue and sub-queue nalles, message
date and time, the source, the Ilessage text
length_ the end key. the message status
key, and the message count. The output CD
contains the text length, the destination
count, a status key and error key (both
possibly repeating), and the name of the
output queue. For inforaa tion about t.he CD
formats possible, see the publication I.Bft
IS
FILE SECTION
284
COBOL_t2!-2~!~.
'Multiple input and output CD entries may
be specified.
No~:
The required inclusion of the
parameter DATE=YES in all input TPROCESS
entries whose destination is ~ COBOL
program results in the placing of the date
and time of message entry in the input CD
(see the section "Additional Interface
Considerations" in the chapter entitled
"Using the Teleprocessing Feature").
Alternatively, the programmer may locate
this section in object-time dumps by
including the following two statements in
the program, in the order given:
77
FILLER PICTURE X(44), VALUE "PROGRAM
IXXIXXXX WORKING-STORAGE BEGINS HERE".
01
FILLER PICTURE 1(42), VALUE "PROGRAM
IXXI1XXX WORKING-STORAGE ENDS HEREII.
WORKING-STORAGE SECT ION
In a large program, the programmer
should plan ahead for breaking the programs
into separately compiled modules, as
follows:
These tvo nonnumeric literals will
appear in all dumps of the program,
delineating the Working-Storage Section.
The program-name specified in the
PROGRAM-ID clause should replace the
XXXXXIII in the literal.
DATA DESCRIPTION
1.
2.
3.
4.
When employing separate modules, an
attempt should be made to combine
entries of each Working-storage
section into a single level-01 record
(or one level-O 1 record for each 32K
bytes). Logical record areas can be
indicated by use of level-02, level-OJ
etc., entries. A CALL statement with
the USING option is more efficient
when a single item is passed than when
many level-01 and/or level-77 items
are passed. When t his method is
employed, mistakes are more easily
avoided.
Areas that do not have VALUE clauses
should be separated from areas that do
need VALUE clauses. VALUE clauses
(except for level-aa items) are
invalid in the Linkage section.
When the Working-storage section is
one level-01 item with no 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.
The Procedure Div ision opera tions that
most often require adjustment of data items
include the MOVE statement, the IF
statement when used in a relation test, and
arithmetic operations. Efficient use of
data description clauses, such as
REDEFINES, RENAMES PICTURE, and USAGE,
avoids the generation of extra code.
!~~IR~~IA-!R~~:
The main storage area
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 "ork area for the records of several
input files that are not processed
concurrently:
WORKING-STORAGE SECTION.
WORK-AREA-FILE 1.
(largest record description for FILE1)
01
See" Use of segmentation FeatUre" for
more in formation on how to modularize
the Procedure Division of a COBOL
program.
01
WDRK-AREA-FILE2 REDEFINES
WORK-ABEA-FILE1.
(largest record description for FILE2)
1£Q.£ating.-the~rkillil-ston~_~g£ti2!lJ.!l
DUll!!
When anyone or more of the options
PMAP, CLIST, and DKAP are specified, both
the location and the length (in
hexadecimal) of the Working-storage
Section, if any, are provided (see the
section "Options for the compiler" in the
chapte.r entitled IIJob control Procedures tt ) .
!1!~!~!T!_§RQQe~~ND
DE~~RIPIIQ~~:
Program data can often be described more
efficiently by providing alternate
groupings or data descriptions for the same
data. For ex~mple# a program refers to
both a field and its subfields, each of
which is more efficiently described with a
Programming Techniques
285
different usage. This can be done with the
REDEFINES clause as follows:
66
66
01
PAYROLL-RECORD.
05 EMPLOYEE-RECORD PICTURE 1(28).
05 EMPLOYEE-FIELD REDEFINES
EMPLOYEE-RECORD._
PIC X(23).
10 NAME
10 NUMBERX
PIC S9(5) COMP SYNC.
05 DATE-RECORD
PIC X(10).
66
15 FILE-3 PICTURE x.
SUM-X REHAMES FIELD-I.
SUM-Xt REHABES FIELD-X THRU FIELD-Y.
SUM-XIZ RENA8ES FIELD-X THRU FIELD-Z.
If each level-15 item contained either an A
or an I, a programmer could find out how
many files contained an A by doing a
complete tally of files in QUT-BEC:
EXAMINE SUM-IYZ TALLYING ALL "A"
As an example of different data
descriptions specified for the same data,
the following illustrates how a table
{TABLEA) can be initialized:
05
VALUE-A.
10 A1 PICTURE S9(9) COMPUTATIONAL
VALUE IS ZEROES.
10 A2 PICTURE S9(9) COMPUTATIONAL
VALUE IS 1.
10
05
or a programmer might just want to tally
the files in FIELD-X:
EXAMINE
SUM~X
TALLYING ALL "A"
In short, renaming fields can lead to
better utilization of coding, storage. and
time by facilitating the streamlining of
Procedure Division operations.
A100 PICTURE S9(9)
COMPUTATIONAL VALUE IS 99.
TABL EA REDEFINES VALUE-A
PICTURE S9{9) COMPUTATIONAL
OCCURS 100 TIMES.
Note: Caution should be exercised when a
~;~;fining or redefined item is used as a
subscript. If the value of a redefining
item is changed in the Procedure Division
and the redefined item is used as a
subscript, or vice versa, then no new
calculation for the su bscript is performed.
DECIMAL-POllL!.Ll2!l1ENI: 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 ~te.s can be executed.
This is referred to as ~all~.
Assume, for example, that a program
contains the following instructions:
WORKING-STORAGE SECTION.
A PICTURE S999V99.
B PICTURE 599V9.
77
77
By permitting a programmer to rename
various fields, the RENAMES clause enables
alternate, possibly overlapping, groupings
of elementary data.
The following example
shows how three fields of a record can be
rena med:
01
286
OUT-REC.
05 FIELD-X.
10 SUMMARY-GROUPX.
15 FILE-l PICTURE
15 FILE-2 PICTURE
15 FILE-3 PICTURE
05 FIELD-Y.
10 SUMMARY-GROUPY.
15 FILE-l PICTURE
15 FILE-2 PICTURE
15 FILE-3 PICTURE
05 FIELD-Z.
10 SUMMARY-GROUPZ.
15 FILE-1 PICTURE
15 FILE-2 PICTURE
x.
x.
x.
X
x.
PROCEDURE DIVISION.
ADD ATO B.
Time and internal storage space are
saved by defining Bas:
77 B PICTURE S99V99.
If it is inefficient to define B
differently. a one-time conversion can be
done, as explained in "Data Format
Conversion ••t
X.
X.
X.
FIELDS OF UNEQUAL LENGI!!:
When a data ite.
is moved to another data item of a
differen t 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 generates 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 equal to or
greater than the receiving field~
y§~_of
S!g~:
The absence or presence 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.
!!g,£imal_It~§:
The sign position in an
internal or external decimal item can
contain:
1.
A plus or min us sign. If S is
specified in the PICTURE clause, a
plus or minus sign is inserted when
either of the following conditions
prevails:
a.
The item is in the Working-storage
section and a VALUE clause has
been specified.
b.
A value for the item is assigned
as a result of an arithmetic
operation during execution of the
program.
If an external decimal item is
punched, printed, or displayed, an
overpunch vill appear in the low-order
digit. In EBCDIC, the configuration
for low-order zeros normally is a
nonprintable character. tov-order
digits of positive values will be
represented by one of the letters A
through I (digi ts 1 through 9); loworder digits of negative values will
be represented by one of the letters J
through R (digits 1 through 9).
2.
A hexadecimal F. If S is not
specified in the PICTURE clause, an F
is inserted in the sign position when
either of following conditions exists:
a.
The item is in the Working-storage
Section and a VALUE clause has
been specified.
b.
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
aDnormally terminated.
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 P is stored in the sign
position of the unsigned item. For
example, if an arithmetic operation
in volves signed opera+lds 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.
t!!!!,§,ll~item§.>
For internal and external decimal items
used as input, it is the user'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 involved in a mQY~,
the data is mo ved wi thout 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
moves involving group items with
subordinate numeric fields or vi th other
group operations such as READ or ACCEPT.
This clause, which specifies both the
position and the mode of the operational
sign for a numeric data description entry,
is required only when an explicit
description of the sign's properties is
necessary.
The SIGN clause may be
specified for either a numeric data
description entry whose PICTURE contains
the character ~ or a group item that
contains at least one such numeric data
description entry.
The numer ic data description entries to
which the SIGN clause applies must be
described, implicitly or explicitly, as
USAGE IS DISPLAY. Only one SIGN clause may
be associated with any given numeric data
description entry.
The format of the SIGN clause is as
follows:
Programming Techniques
287
SI~~
IS
LEADING
{
l
[SEPARATE CHARACTER]
TRAILING
Q§~_of_iA~~~fAR!~_fHARACTE~_QptiQll:
The
programmer can elect to consider the
character ~ in the PICTURE character string
as a separate character or not, as he
chooses.
If the SEPARATE CHARACTER option
is specified:
• The position of the character
taken to be a digit position.
~
The following eight cases show how data
conversions are h~ndled on mixed elementary
items for names, data comparisons, and
arithmetic operations. Moves to and from
group items, without the CORRESPONDING
option, as well as comparisons involving
group items, are done without conversion.
is not
I~Ll!2.!g_Q!!:!!:
• The character S is counted in
determining th; size of the data item.
• The characters ,+, and ,_t are used for
the positive and the negative
operational signs, respectively.
Converts DISPLAY data to
COMPUTATIONAL-3 data.
I.Q_&Q.!!!.P!£~-ILlla:
converts DISPLAY data
to COMPUTATIONAL-3 data.
.I~~rforLAr.i!:.h!MU.i~Q'pg£ll.iQ!l§:
• If neither the character ' . ' nor the
character t_' is present in the data at
object time, an error takes place and
the program ABENDS.
Whether or not the SEPARATE CHARACTER
option is in effect, the operational sign
is assumed to be associated with either the
LEADING or the TRAILING digit position, as
spec;ified, of the elementary numeric data
item.
This clause should be written at the
highest level possible.
Converts DISPLAY data to COMPUTATIONAL-3
data.
I2-Move~~a:
Converts DISPLAY data to
COMPUTATIONAL-3 data and then to
COMPUTATIONAL data.
Converts DISPLAY to
COMPUTATIONAL-3 and then to
COMPUTATIONAL or converts both DISPLAY
and COMPUTATIONA.L da ta to
COMPUTATIONAL-3 data.
I2-£ompa~Qata:
~.f~rfQD!LAr i!l!H ti~per a!;.i.2n.2:
Converts DISP~AY data to COMPUTATIONAL-3
or COMPUTATIONAL data.
~Al!-fQliMAT CONV~~!Q!:
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, perfora
any necessary conversion, and then execute
the indicated operation.
Often, too, the
result may have to be converted in the same
way (see Figure 101).
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 causes 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.
Using
this technique, the conversion is performed
only once, instead of each time an
operation is performed.
288
I2-~QYg~a:
Moves COMPUTATIONAL-3
data to a work field and then converts
COMPUTATIONAL-3 data to COMPUTATIONAL
data.
Da ta: Converts COMPUTATIONAL
data to COMPUTATIONAL-3 or vice versa,
depending on the size of the field.
l.Q_~ml?are
I~.f~~tQ£~-A~thn~ii~~ratio~§:
Converts COMPUTATIONAL data to
COMPUTATIONAL-3 or vice versa, depending
on the size of the field.
10 Move Data!
Con verts COMPUTATION AL
data to COMPUTITIONAL-3 data in a vork
field, then moves the work field.
10 Compare Data:
Converts COMPUTATIONAL
to COMPUTITIONIL-3 data or vice versa,
depending on the size of the field.
•J Converted
r--------~------
I
I
I
I
,
I
J Bytes Required
• Usage
fI
IDISPLAY 11 per digit (except
J(externallfor V)
I decillal) I
I
I
,I
,
for
I
I Arithmetic
I
Typical Use
loperations ,Special Characteristics t
I
--t
--+
I
IInput froll cards~1
Yes
1Kay be used for numeric I
I output to
I
fields up to 18 digits.
I cards. 1 istingsl
J long.
I
I
I
IFields over 15 digits
I
I
I
J
I
1 require extra inI
I )
t
I
I structions if used in J
I
I
,
I
I computations.
I
rI
I
I
+
-f
IDISPLAY
,1 per character (ex- JInput from cards.,
Yes
,Converted to
I
I (externallcept for V)
J output to
I
I COMPUTATIONAL-2
I
Ifloating I
I cards~ listingsl
I format via COBOL
,
Ipoint)
I
1
I
I library subroutine.
,
.1
------ll~
I
I
..
ICOMP-3
,1 byte per 2 digits
IInput to a reportlso.etimes ,Requires less space thanl
f(internallplus 1 byte for the
I item
Iwhen a
I DISPLAY.
I
,decimal) Ilow-order digit and
J
Ismall
I
J
t
,sign
I Arithmetic fieldsl COMP-3
I convenient form for
J
I
I
I
J item is
J
decimal alignment.
I
"
J
J used with
I
I
f
J
,Work areas
Ja small
ICan be used in
I
f
I
1
JCOMP
I arit.hmetic computaI
"
I
I item.
J tions without
I
J
1
I
I
J converS1on.
I
I
f
J
J
IFields over 15 digits
1
I
t
I
J
I require a subroutine t
I
J
J
J
I when used in
I
I
1
I
I
J computations.
t
~-----~
ICOMP
I (binary)
,
I
,
•
I
J
r-
12 if 1SN~4
I
14 if 5SN~9
I
18 if 10SN~18
,where N is the number
lof 9s in the PICTURE
tclause
+----
lCOftP-1
,4
I (internal,
Ifloating J
Ipoint)
I
I
J
J
J
J
I
~
(short-precisio~
i
-+
.,
,Subscripting
I Sometimes
I
f for both
IArithmetic fieldsjmixed and
I
tunmixed
J
Jusages
1
I
,
I
J
t
I
I
IFractional expo- t No
I
nentiation
I
I
+----
ICOMP-2
18 (long-precision)
I (internal,
If loating I
,point)
I
L
I t '
I
I
,
1
I
I
I
I
f
,Fractional expo- I
• nentiation whenl
I more precision I
J is required
I
I
Figure 107.
1
•
No
,
IRounding and testing forI
J the ON SIZE ERROR con-l
I dition are cumbersome I
I if calculated result J
J is greater than 9(9). 1
,Fields of over 9 digits t
I require more handling. I
t
~
ITends to produce less
I accuracy if more than
J
11 significant digits
J are required and if
J the exponent is big.
J Requires floatingI point feature.
J
ISame as COMPUTATIONAL-1
I
f
1
.
I
I
I
t
I
I
J
-f
J
J
1
1
J
Data Format Conversion
Programming Techniques
289
10
P~~m Arll.h!!fll..i&-2~rati2D§:
Converts COMPUTATIONAL to
COMPUTATIONAL-3 data or vice versa,
depending on the size of the field.
~OMPUTAIIONAL
to Numeric DISPL!!:
IQ_~Data:
Converts COMPUTATIONAL data
to COMPUTATIONAL-3 data and then to DISPLAY
data.
IQ._£ompare ~atg: Converts DISPLAY to
COMPUTATIONAL or both COMPUTATIONAL and
DISPLAY data to COMPUTATIONAL-3 data,
depending on the size of the field.
!Y.!I!.l!I~..R!~fL1Y
FIELD.§: 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.
~Q~!IIONAL-l
IQ Perform Arithmetic Ol!!KgtiQ.n§:
Depending on the size of the field,
converts DISPLAY data to COMPUTATIONAL
data, or both DISPLAY and COMPUTATIONAL
data to COHPUTATIONAL-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.
AND COMPUT!TIOHAL-l-lIEbQ~:
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.
~Q!1f.YtllI.QNAL::.J._~I~1Q~:
The compiler does
not have to generate instructions to insert
high-order zeros for ADD and SUBTRACT
statements that involve COMPUTATIONAL-)
data. The zeros are inserted by the
instruction set.
I2_llQ!.!LQ.g,ta: Con verts COMPUT ATIONAL-3
data to DISPLAY data.
IQ_£Qmpar~~atg!
Converts DISPLAY data to
COMPUTATIONAL-3 data. The result is
generated in a COHPUTATIONAL-3 work area
and is then converted and moved to the
DISPLAY result field.
:r.Q_EerfQll_!rithm~ti~!ll?!!1::At.iQ!!§:
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.
The various COBOL data formats and how
they appear in the computer in EBCDIC
(Extended Binary-Coded-Decimal Interchange
Code) format are illustrated by the
following examples. More detailed
information about these data formats
appears in the publication I!H1_~Y2!~!!Ll1Q
Principles-2f o~rati2!, order
No. GA22-1000.
Numeric_~I~fk!I_l~xi~£~~Q~imail:
Suppose the value of an item is -1234, and
the PICTURE and USAGE are:
PICTURE 9999 DISPLAY.
or
~~!.grnal_Floating,::Point
to_A!U.-Qlher: When
an external floating-point item is to be
used in an airthmetic operation or in data
manipulation, precision errors may occur
due to required conversions.
!!!!~l_lloati!!g=fQiJ!L1Q-A!l.LQther:
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
floa ting- point. If necessary, the internal
floating-point result is then converted to
the format of the other data item.
290
PICTURE S9999 DISPLAY.
The item appears in the computer in the
following forms respectively:
Il -___
Fi i I ____
F2 i I ____
F3 I ____
F4 JI
~
--.--
Byte
Il - -__
Fi I F2 I F3 I D4 I
i ____ i ____
L~J
Byte
1111
Hexadecimal F is treated arithmetically as
plus in the low-order byte. The
hexadecimal character D represents a
negative sign.
1011
0010 I 1110 I
- - ' - - -_ _ J
sign
position
COftPUT.!IIO!i!L-3_lInt~l
Deci!all:
Suppose the value of an item is +1234. and
its PICTURE and USAGE are:
PICTURE 9999 COMPUTATIONAL-3.
or
PICTURE S9999 COMPUTATIONAL-3.
The item appears in the computer in the
following forDls, respectively:
~in~~I_I~~~~ni£gl~t!Qn:
A binary item is
allocated storage ranging from one halfword
to two words, depending on the number of 9s
in its PICTURE.
Figure 108 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 to be stored in the item.
For
example, PICTURE S9{Q) implies a maximum
value of 9,999, although it could actually
hold the number 32,767.
Because most binary items are
manipula ted according to their allotted
storage capacity, the programmer can ignore
this situation. For the following reasons,
however, there are some cases where he must
be careful of his data:
IL ____
01 J.I ____
23 ..1I=.J
I 4F I
Byte
IL ____
01 .l.-___
I 23 J.-:;.;:::::;:;:.J
I 4C )
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 imperative
statements specified by the error
option.
2.
When a binary item is displayed or
exhibited, the value used is a
function of the number of 9s specified
in the PICTURE clause.
3.
When the actual value of a positive
number is significantly larger than
its picture value, a 1 could result in
the sign position of the item, causing
the item to be treated as a negative
number in subsequent operations.
Byte
Hexadecimal F is treated ari thmetically as
positive. The hexadecimal character C
represents a plus sign.
l!Q!£:
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.
Note that a leading zero is inserted in the
fo.regoing exam ple.
~OMPUTATIONAL
jBinaJ;.Il.: suppose the value
of an item is 1234, and its PICTURE and
USAGE are:
PICTURE 59999 COMPUTATIONAL.
The item appears in the computer in the
following form:
0000
0100
1101
0010
sign
position
Figure 109 illustrates three binary
manipulations.
In each case, the result
field is an item described as PICTURE 59
CO!PUTATIONAL.
One halfvord 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.
CO"PUXA'l'IOnL-l-2~_~QROTAI.IOl'!!lt.=£
1l1oatinLf2intl.:
A O-bit in the sign position means the
number is positive.
Negative numbers are
represented in two's complement fora; thus,
the sign position of a negative number viII
always contain a 1-bit.
For example -1234 would appear as
follows:
Suppose the value of an
item is +1234. and that its USAGE is
COMPUTATIONAL-1, the item appears in the
computer in the following form:
101100 001110100 1101 0010 0000 0000 00001
_______ --L--___ _
~'-4'
S 1
31
1 8
Programming Techniques
291
r-
J
,
J
PICTURE
1---------------+
J 59 through 59 (4)
J
I
I
159 (5)
I
tb rough S9 (9)
S9 (10) through S9 (18)
I
J
r-
1
f Case t
t---t-
I A
iB
I
i-
,
t
Assigned storage
I
I
f
I
I
I
,
2,147,483,647J one fullword
I•
I
9,223,372,036,854,775,8071 two fullwords
------.1
----------------------~
Relationship of PICTURE to storage Allocation
Hexadecimal Result of
Binary Calculation
,
Decimal
Equivalent
0008
I
I
I
f
I
C
J
,
32,767) one halfword
I
J _________________________~__
L
Pigure 108.
Maximum Working Value
OOOA
Cl50
8
10
50000
,
Ac tual Decimal Value I
Display or I
in Halfword of storage I Exhi bi t Value I
+8
+10
-15536
L-
I
I
f
I
-+
I
~
8
0
6
.&.
Figure 109.
is the sign position of the number.
Bits 1 through 7 are the exponent
(characteristic) of the number.
Bits 8 through 31 are the fraction
(mantissa) of the number.
Main-Line RQutine
A O-hit in the sign position indicates
tha t the sign is pI us.
A
1
,
of
.I
Treatment of Varying ValUes in a Data Item of PICTURE S9
maintain and document. In addition,
modularization makes it simple to break
down a program using the segmentation
feature, thereby resulting in a more
efficient segmented program.
Modularization of the Procedure Division
involves organizing it into at least three
functional levels: a main-line routine,
processing subrolltines, and input/output
subroutines.
S
I
of
l-bit in the sign position indicates
that the sign is minus.
This form of data is referred to as
floating-point. The example illustrates
short-precision floating-pOint data
(COl'1PUTATIONAL-1) • In long-precision
(COMPUTATION AL-2), t he fraction length is
56 bits.
(For a detailed explanation of
floating-point representation, see the
publication LBM_~ste~Ll10-frin£ipl~of
Q2~tatiQn, Order No. GA22-7000.
This routine should be short, simple,
and contain all the major logical decisions
of the program. This routine controls
which second-level SUbroutines are executed
and in what order. All second-level
subroutines should be invoked from the
main-line routine by PERPOR8 statements.
PROCEDURE DIVISIQ!
A program can often be made more
efficient or easier to debug in the
Procedure Di vision with some of the
techniques described below.
KODULARIZING THE PROCEDURE DIVISION
When the Procedure Division is
modularized, programs ar~ easier to
292
These 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. The processing
subroutines can perform only lower level
subroutines; return to the higher level
subroutine (processing subroutine) must be
made by a GO TO statement, which references
the EXIT statement.
ln~t/Output
Subroutines
These should be the lowest level
subroutines, since all higher level
subroutines should have access to them.
There should be one OPEN subroutine and one
CLOSE subroutine for the program, and only
one functional (READ or WRITE) subroutin~
for each file.
One READ or WRITE
subroutine per file, which is always
performed, has several advantages:
1.
Coding can be added to count records
on a file, transform blanks into
zeros, check for 9s padding, etc.
2.
Input and output files can be
reformatted without changing the logic
of the prog ram.
3.
DEBUG statements can be added during
testing to create input or to DISPLAY
formatted output, instead of having to
create a test file.
COLLATING SEQUENCES
The combination of the PROGRAM COLLATING
SEQUENCE clause and the SPECIAL NAMES
alphabet-name clause(s) offers the
programmer flexibility in estahlishing or
al tering the collating seq uence used in the
following operations: the various forms of
non-numeric comparisons, HIGH/LOW-VALUE,
SEARCH ALL, and SORT/MERGE. The alphabet
used may be EBCDIC (d~noted as NATIVE,
which is also the defaul~, ASCII (denoted
as STANDARD-1>, or one or more
programmer-defined alterations of the
EBCDIC sequence.
The alphabet identified through the
PROGRAM COLLATING SEQUENCE clause will be
used for all occurences of non-numeric
compares, HIGH/LOW-VALUE, and SEARCH ALL.
However, each separate SORT/MERGE operation
can override that general specification by
including its own COLLATING ~EQUENCE
clause.
For QSAM files, the CODE-SET clause of
the FD statement can be used to identify
the file as being either EBCDIC or ASCII.
When an ASCII file is identified in this
manner, the corresponding DD card need not
specify DCB=(OPTCD=Q ••• ) or
DeB= (RECFM=D ••• ).
USE OF THE UPSI SWITCHES
The flexibility of programs can be
greatly increased through use of the
execution-time svi tches UPSI-O,
UPSI-1, ••• UPSI-7 (see "Options for
Execution t' in the section "Job Control
procedtlres"). A program can be written to
deal with many potential situations, and
then directed (when it is to begin
execution) as to which particular
situations are current during that run.
For example, a program might be designed
to read File A and create File B; these two
procedures are always to be done. However,
on certain irregular occasions, a sp~cial
report is also to be written to Pile C.
These special occasions are externally
determined--the program could not normally
know of or internally determine them. But
by using an UPSI switch, this difficulty
can be overcome.
The code for the production of File C is
written predicated on an IF statement that
tests the associated condition name of an
UPSI switch:
if on, the special report is
produced; if off, it is skipped. For
everyday executions of the program, the
installation supplies the UPSI object-time
parameter with that particular switch set
to zero. When occasion demands that the
special report be printed, the installation
sets the UPSI object-time parameter switch
to one, and the program's logic then writes
out the report.
Because there are eight UPS! switches,
controlled variation of a much more complex
nature can be obtained by a user.
INTERCEPTING I/O ERRORS
COBOL offers a variety of techniqUes the
programmer can employ to intercept and
handle I/O error situations. Use of these
techniques (INVALID KEY, USE AFTER
ERROR/EXCEPTION~ and FILE STATUS) gives a
programmer not only the power to prevent
abnormal termination, but also flexibility
in his response. FILE STATUS--valid for
'SAM and QSAM files--can be used separately
or in combination with one of the other two
teChniques. COBOL automatically fills in
the key field immediately after every I/O
operation, so tbat the program can be
designed to examine it and take action
accordingly.
(If FILE STATUS is specified
but not interrogated by a program after an
I/O operation, results are unpredicatble.)
programming Techniques
293
If a logic error occurs because thel1ser
attempts a READ or WRITE against an
unopened file, an associated USE ERROR
declarative will not get control. If such
a.n error occurs when the file has been
closed but not reopened, the wrong USE
ERROR decla.rative may get control.
However, such a situation can be
circumvented by using FILE STATUS to test
for successful open before performing the
READ/WRITE.
2.
the length of the scaled divisor plus
the length of the scaled dividend is
greater than 16 bytes. The lengths of
the operands are internal decimal.
3.
the 2.ca1eg diviggng is greater than 30
digits.
(A scaled dividend is a
number that has been multiplied by a
power of ten in order to obtain the
desired number of decimal places in
the quotient.)
INTERMEDIATE RESULTS
The compiler treats arithmetic
statements as a succession of operations
and sets up intermediate result fields to
contain the results of these operations.
Examples of such statements are the
arithmetic statements, and statements
containing arithmetic expressions. The
publication IB~_VS_~OBQt-1Q£_~L!2
describes the algorithms used by the
compiler to determine the number of places
reserved for intermediate result fields.
If an operation involving binary
operands requires an intermediate result
greater than 18 digits, the compiler
converts the operands to internal decimal
before performing the operation. If the
result field is binary, the result will be
converted from internal decimal to binary_
Whenever the number of digits in a
decimal intermediate result is greater than
30, the field is truncated to 30 digits.
A
warning message viII be generated at
compile time, and program flow will not be
interrupted at execution ti·me. This
truncation may cause a result to be
incorrect.
If binary or internal decimal data is in
accord with its data description, no
interrupt can occur because of an overfloW
condition in an intermediate result. This
is due to the truncation described in the
preceding paragraph.
If the possibility exists that an
intermedia te result field may exceed ]0
digits, truncation can be avoided by the
specification of floating-point operands
(CORPUTATION AL- 1 or COMPUTATION AL- 2) ;
however, accuracy may not be maintained.
If an intermediate result will not be
greater than nine digits, the operation is
performed most efficiently on binary data
fields.
l~i~£!~gig~~2Qlts ang_E!Qating~fQi!!
DaY_Il£!!!2
In t e il§uli~.:t£ Res ul1§.-and ~ 0 BQL1ib I:~.r.Y
~ub£Qy.tin.~§.
If a decimal multiplication operation
requires an intermediate result greater
than 30 digits, a COBOL library subroutine
is used to perfo.rm the multiplication. The
result of this multiplication is then
truncated to 30 digits.
A COBOL library subroutine is used to
perform division if:
1.
294
the scaled divisor is equal to or
greater than 15 dig its.
If a floating-point operand has an
intermediate result field in which exponent
overflow occurs, the job will be ahnormally
terminated.
If the exponent is a Iloating-point
item or has a PICTURE specifying decimal
places, the subroutine ILBOFPWO is
called,and the exponentiation is executed
in floating-point arithmetic.
Note: The base is always treated as a
positive number, regardless of sign, and
the answer is always a positive number.
Caution should therefore be exercised
when using noninteger exponents.
Caution:
A COMPUTE or DIVIDE statement
which-stores its intermediate results in
only a floating-point field may produce a
slightly different final answer than a
similar COMPUTE or DIVIDE statement which
stores its intermediate results in both a
floating-point and a fixed point field.
This is because of the different precisions
of the fixed- and floating-point fields.
Programming Techniques
294.1
I!li~gdiate~.2.Yl!:§-2Jlg-1he~!,!_SIZE
ERRQll
Q£!:ion
The ON SIZE ERROR option applies only to
the final calculated results and not to
intermediate result fields.
COBOL processing environment. That is, a
CANCEL statement issued for a subprogram
that bas been dynamically loaded causes the
storage occupied by the subprogram to be
freed.
As a result, a subsequent call to
the subprogram functions as if it were the
first.
CANCEL CALLED-PROGRAM.
VERBS
!Qi~:
A program other than the original
caller may issue a CANCEL statement
referring to a called program.
The CALL statemen t permits communication
bet. ween a COBOL object program and one or
more COBOL subprograms or other language
subprograms.
A called program may be
entered either at the beginning of the
Procedure Division or later in the program.
When a subprogram is called, it may already
be main storaqe resident and be link-edited
with the main program, or it may be
specified as dynamic and link-edited into a
separate load module. Dynamic loading, via
the CALL statement, enables the user to
load a subprogram only when it is actually
needed.
The first dynamic call to a subprogram
brings in a fresh copy of that subprogram.
Any subsequent calls to the same
subprogram, by either the original caller
or another subprogram in the same
region/partition, cause a branch to the
same copy of the subprogram in its
last-used state, until the user deletes it
(see the section on the "CANCEL
Statement").
The ON OVERFLOW phrase can be included
in the CALL statement to circumvent
abnormal termination when there is
insufficient main storage available for
dynamically loading the called program.
The imperative statement associated with
the ON OVERFLOW will gain control in such a
situation, allowing the user to handle the
problem in a manner of his own choosing and
continue execution.
(The conditions
handled by ON OVERFLOW are equivalent to
the following completion codes:
106C, 804,
BOA, and 878.)
For examples of both static and dynamic
CALL statements, see the section "Dynamic
subprogram considerations" in the chapter
entitled "Calling and Called Programs."
The CANCEL statement permits dynamic
deletion of COBOL subprograms from the
There are two ways in which to use the
CLOSE statement when closing several files:
CLOSE DETAIL-FILE MASTER-FILE.
or
CLOSE DETAIL-FILE.
CLOSE MASTER-FILE.
Each CLOSE statement for a file requires
the use of a storage ar~a that is directly
proportional to the number of files being
closed. Closing more than one file with
the same statement is faster than when
using a separate statement for each file.
However, separate statements require less
storage.
COMPUTE Statement
The use of the COMPUTE statement
generates more eff icient coding than does
the use of individual arithmetic statements
because the compiler can keep track of
internal work areas and does not have to
store the results of intermediate
calculations. It is the user's
responsibility, however, to insure that the
data is defined with the level of
significance required in the answer.
Nested and compound IF statements should
be avoided as the logic is difficult to
debug_
Programming Techniques
295
When a HOVE statement with the
CORRESPONDING option is executed, data
items are considered CORRESPONDING only if
their respective data names are the same,
including all implied qualification, up to,
but not including, the data-names used in
the HOVE statement itself.
PERFORM is a useful verb if the
programmer adheres to the following rules:
1.
Always execute the last statement of a
series of routines being operated on
by a PERFORM statement.
When
branching out of the routine, make
sure control will eventually return to
the last statement of the routine.
This statement should be an EXIT
statement.
Although no code is
generated, the EXIT statement allows a
programmer to recognize immediately
the extent of a series of routines
within the range of a PERFORM
statement.
2.
Always either PERPORM routine-name
THRU routine-name-exit, or PERFORM
section-name.
APERFORM
paragraph-name can cause trouble for
the programmer trying to maintain the
program. For example, if a paragraph
must be broken into two paragraphs,
the programmer must examine every
statement to determine whether or not
this paragraph is within the range of
the PERFORM statement.
Then all
statements referencing the
paragraph-name must be changed to
PERFORM THiU statements.
For example,
AA
01
05
05
01
BB
10
10
EE
10
XX
05
CC
DD
05
FF
BB
10
10
yy
10
CC
DD
FF
The statement MOVE CORRESPONDING AATO xx
will result in moving cc and DD but not FF
because FF of EE does not correspond to FF
of IY).
Note: The other rules for MOVE
CORRESPONDING, of course, must still be
satisfied.
An asterisk (*) should be used in place
of the NOTE statement, because there is the
possibility that when NOTE is the first
sentence in a paragraph, it will
inadvertently cause the whole paragraph to
be treated as part of the NOTE.
Use READ INTO and WRITE FROM, and do all
processing in the Working-Storage Section.
This is suggested for three reasons:
1.
Debugging is much simpler.
working-storage areas are easier to
locate in a dump than are buffer
areas.
And, if files are blocked, it
is much easier to determine which
record in a block was being processed
when the abnormal termination
occurred.
2.
Trying to access a record area after
the AT END condition has occurred (for
example, AT END MOVE HIGH-VALUE TO
INPUT-RECORD) can cause problems if
the record area is only in the Pile
Section.
3.
WRITE FROM allows multiple writes of
the same record (not possible when using
the record area because of buffering
techniques) .
QfEN Statement
There are two ways in which to use the
OPEN statellentwhen opening several files:
OPEN INPUT INFILE UPDATES OUTPU'l' OUTFILE
or
OPEN INPUT INFILE
OPEN INPUT UPDATES
OPEN OUTPUT OUTFILE
Each OPEN statement for a file requires
the use of a storage area that is directly
proportional to the number of files being
opened. Opening more than one file with
the same statement is faster than using a
separate statement for each file.
However,
separate statements require less storage.
296
BQt~:
The programmer should be aware that
additional time is used to execute the mOVe
operation involved in each READ INTO or
WRITE FROM instruction-.
e.
The END-OF-PAGE imperative is
executed (if one was
specified).
The features LINAGE, WITH FOOTING, and
END-OF-PAGE imperative-statement give the
programmer added flexibility and control in
physical sequential (QSAM) output
operations. When these featllres are used
in combination with the BEFORE/APTER •
ADVANCING nn LINES clause of the WRITE
statement, however, care must be exercised.
In the discussion below, notice that
END-OF-PAGE imperatives are executed after
WRITEs, and theLI BAGE-COUNTER may be
p~inting to the next logical page (instead
of to the current footing area)vhen the
imperative gains control.
Note: Files using LINAGE are treated
as-if the ADV compile option had been specified.
•
When only AFTER is specified for the
file, ASA control characters are
used.
For ADVANCING nn LINES, COBOL first
calculates the sum of LINAGE-COUNTER and
nne
(For ADVANCING PAGE, see Case 2
below.)
Subsequent actions depend on the
size of this value, as follows:
•
When only BEFORE is specified for the
file, machine control characters are
used.
•
When both BEFORE and AFTER are
specified for output operations,
machine control characters are used.
When the ADVANCING option is used for
the WRITE statement, library subroutine
ILBOSPA is called to handle the spacing.
The carriage control characters are
determined as follows:
£~§~--If
advance would be within the
current logical page body (i.e.,
value is not greater than the
established LINAGE value):
a.
b.
The WRITE takes place (either
before or after advancing nn
lines, as specified in the
program).
LINAGE-COUNTER is incremented
by nne
c.
If FOOTING was speciifed, and
the advance falls within the
footing area (that is, greater
than or equal to the
established FOOTING value), the
END-OP-PAGE imperative is
executed (if one vas
specified).
£~2g_~--If
advance lIould go beyon4 the
current logical page body (i.e.,
value is greater t han the
established LINAGE value):
a.
A new value is established for
LINES-AT-TOP.
h.
The WRITE takes place before or
.after (as specified by the
prog ram) the dey ice is
positioned to the first line of
the next lO1 program of BI
J
I
I
J Calling
program of ct
I
I
f
I
J
I
>.
,
I
.I
----I
I
I
t
I
I
I
,
t
.J
L-
Figure 121.
,
C
Calling and Called Programs
LI NKAGE IN A CALLI NG COBOL PROGR AM
LINKAGE IN A CALLED COBOL PROGRAM
A calling COBOL program must contain the
following statement at the point at which
another prog ram is to be called:
A called COBOL program must contain two
st.a temen ts.
CALL
litera1-1
{
}
One of the following statements must be
inserted to name the point where the
program is to be entered:
identifier-l
(USING identifier-list]
[ON OVERFLOW imperative-statement].
ENTRY literal-1
[USING identifier-list].
or
Literal-1 or the contents of identifier-1
must be either the name of the program that
is being called or the name of an entry
point in the called program.
The first
eight characters of literal-1 or
identifier-1 are used to make the
correspondence between the calling program
and the called program. The
identifier-list is one or more data-names,
called identifiers and separated by blanks,
that are to be passed to the called
progra m.
If the called program is an
'assembler-language program, the identifier
in the USING phrase may also he a file-name
or a procedure-name.
If the identifier in
the USING phrase is a file-name, the COBOL
compiler passes the address of the DCB for
a queued file, or the address of the DECB
for a basic file, as this entry of the
identifier-list. The identifier may not be
a VSAM file name. This can be used to test
bits in the DCB or DECB or to enter some
options in the DCB.
However, when changing
a field of the DCB, precautions should be
taken not to contradict the information in
other fields or the information in the
object code supplied by the compiler, job
control langUage, or other sources.
When
the identifier in the USING phrase is a
procedure-name, the value passed is the
beginning address of the procedure. If no
identifiers are passed, the USING clause is
omit ted.
If a non-standard return is executed to
a procedure name in a program compiled with
OPT, RES, or DYN options, unpredictable
results may occur.
The ON OVERFLOW imperative statement
will gain control if the called program
cannot be dynamically loaded during"
execution time (situation equivalent to
completion code 106-C, 804, 80A, or 878).
This allows the user to continue
processing. ON OVERFLOW only has meaning
if a program is to be dynamically loaded
(see the "Dynamic Subprogram Linkage'·
section later in this chapter).
PROCEDURE DIVISION [USING
identifier-list].
The literal-1 or PROGRAM-ID 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 that the compiler uses. The
identifier-list is one or more data-names
that correspond to the identifier-list of
the CALL statement of the calling program.
Each data name of the identifier-list must
be defined in the Linkage section of the
Data Division and must have a level number
of 01 or 77.
One of the following statements must be
inserted at the point at which control is
to be returned to the calling program:
GOBAeR.
or
EXIT PROGRAM.
The GOBAeK or EXIT PROGRAM statement
enables restoration of necessary registers
and returns control to the point in the
calling program immedia tely following the
calling sequence.
Note:
The GOBACK and EX!T PROGRAM
statements may be used in a main program,
with the result that any COBOL program can
be used as either a calling or a called
program, if written with this end in mind.
If a GOBICK statement appears within the
main program, control is returned
immediately to the system; if an EXIT
PROGRAM statement appears, it is simply
regarded as a null instruction.
A called program may pass a completion
co.de to its caller by storing a value in
RETURN-CODE. The calling program may
interrogate RETURN-CODE after a return is
made from a called program to determine the
comple tion code.
Calling and Called Programs
311
!Qi~:
RETURN-CODE may also be used to pass
a completion code to the system at the end
of a run uni t.
only CALL identifier statements are
dynamic; when NODYNAM is in effect, CALL
literal statements are static.
(For a
discussion of the formats possible with the
CALL statement, see the publication lfiL!~
£QB01_foLQ~L!~· )
with the dynamic subprogram linkage
feature, a called program need Dot be
link-edited with the main program. It may
instead be link-edited into a separate load
module, so that at execution time it is
loaded if S!!d onIY_i! it is called.
Accordingly, the first dynamic call to a
subprogram obtains a fresh copy of the
subprogram. Subsequent calls to the same
subprogram, by either the original caller
or any other subprogram in the same
region/partition, result in a branch to the
same copy of the subprogram in its
last-used state until the subprogram is
canceled. The first call following a
CANCEL statement results in a branch to a
fresh copy of the subprogram.
Specification of the DYNAM option in the
PARM field of the EXEC statem~nt (see the
section on "Compiler Options" in the
chapter entitled "Job Control Procedures~
makes all calls dynamic.
If NODYNAM is in
effect, through either user specification
at compile time or as the default option.
318
For an example of a COBOL program that
takes advantage of the dynamic CALL/CANCEL
feature, see Figure 122.
1.
When th~ dynamic CALL is used, the
main program and all subprograms in
one region/partition should take
advantage of the COBOL Library
Management Facility (see the
1t Librar ies" cha pter) •
Progra ms
compiled under pre-Version 4 COBOL
compilers cannot be dynamically
called. Even when the DYNAM option is
not specified a program with CALL
identifier or CANCEL identifier
state~ents requires the Library
Management Feature.
2.
The USING option should be included in
the CALL statement only if there is a
USING option in the called entry
point.
3.
It is recommended that calling
programs use the ON OVERFLOW facility.
r-
II/CALLJOB
II/STEP1
II/COB.SYSIN
JOB
user information
EXEC
COBUCL,PARM.COB=·DYNAM,RESIDENT'
DD
*
IDENTIPICATION DIVISION
PROGRAM-ID. SUBPROG1.
AUTHOR. J. SMITH
REMARKS.
THIS SUBPROGRAM IS CALLED BY THE MAIN PROGRAM.
IT ISSUES A MESSAGE TO INDICATE WHETHER IT IS
IN INITIAL OR LAST-USED STATE, AND THEN RETURNS
TO THE MAIN PROGRAM.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.
IB8-370.
OBJECT-COMPUTER. IBM-370.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 SWITCH PIC 9 VALUE O.
PROCEDURE DIVISION.
IF SWITCH=O DISPLAY 'SUBPROG1 CALLED -- IN
INITIAL STATE'
GO TO RETURN-POINT.
DISPLAY 'SUPROG1 CALLED -- IN LAST-DSED STATE'.
RETDRN-POINT.
AD D 1 TO SWITCH.
EX IT PROGRAM.
-,
1
I
I
I
I
I
•
I
t
I
I•
I
t
I
I
I
t
I
I
I
I
I
I
t
I
/*
J
I/LKED.SYSLMOD DD
DSN=SUBPROGS(SUBPROG1) ,UNIT=2114.VOL=SER=XXXXXX,
II
DISP= (NEW, KEEP) , SPACE= (TRK, (5,1,1»
I
I
.,J
1*
t-
IliQl~:
When a subprogram is called dynamically, the (NAME andlor ALIAS) option of the
Ilinkage editor is used to identify the module that is accessed by an as/vs LOAD macro
tat execution time (see the section entitled "Link-editing COBOL Programs").
I
I
•
•
Figure 122.
.J
Sample Calling and Called Programs Using Dynamic CALL and CANCEL statements
(Part 1 of 3)
Calling and Called Programs
319
r
•
IIICALLJOB2
'1ISTEP1
II/COB.SYSIN
f
•
I
I
I
I
f
•
r
t
I
I
•
,
I
I
1/*
1//LKED.SYSI.f10D
JOB user information
EXEC COBUCL,PARM.COB:'DYNAM,RESIDEN'.r'
DD *
.
IDENTIFICATION DIVISION.
PROGRAM-ID. SUBPROG2.
AUTHOR. J. SMITH
REMARKS.
THIS SUBPROGRAft IS CALLED BY THE MAIN PROGRAft.
IF IT IS IN INITIAL STATE, IT ISSUES A MESSAGE
TO THAT EFFECT AND RETURNS TO THE MAIN PROGRAM.
IF NOT, IT ISSUES A MESSAGE ~HAT IT IS IN THE
LAST-USED STATE, CANCELS SUBPROG1 VIA A CANCEL
IDENTIFIER, AND RETURNS TO THE MAIN PROGRAM.
ENVIRONMENT DIVISION.
CONFIGURATION DIVISION.
SOURCE-COMPUTER. IBM-370.
OBJECT-COMPUTER. IBM-370.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 SWITCH PIC 9 VALUE O.
77 CANCL-ID PIC 1(8).
PROCEDURE 01 VISION.
IF SWITCH=O DISPLAY 'SUBPROG2 CALLED -- IN INITIAL STATE'
GO TO RETURN-POINT.
DISPLAY 'SUBPROG2 CALLED -- IN LAST-USED STATE'.
DISPLAY 'SUBPROG2 CANCELLING SUBPROG1'.
MOVE lSUBPROG1' TO CANeL-ID.
CANCEL CANeL-ID.
RETURN-POI NT.
ADD 1 TO SWITCH.
EXIT PROGRAM.
DD
DSN=SUBPROGS (SUBPROG2) ,UNIT=2314,VOL=SER=XXXXXX,DISP:OLD
1/*
~
Figure 122.
320
I
I
I
I
I
I
I
I
I
I
J
I
•
I
I
~
Sample calling and Called Programs Using Dynamic CALL and CANCEL Statements
(Part 2 of 3)
-------------------,I
r
1//CALLJOB3
II/STEPl
IlcOB.SYSII
JOB user information
EXEC COBUCL,PARK.COB='DYNAK,RESIDENT'
DD
IDENTIPICATION DIVISION.
PROGRAK-ID. MAINPROG.
AUTHOR. J. SIUTB
REMARKS.
THIS IS A MAIN PROtRAK.
IT CALLS SUBPROGl AND
SUBPBOG2 TWICE. ON THE FIRST CALL, EACH SUBPROGRAK
SHOULD BE A PRESH COpy (THAT IS, IN INITIAL STATE).
ON THE SECOND CALL, EACH SUBPROGRAM SHOULD BE IN ITS
LAST-USED STATE.
WHEN SUBPROG2 IS CALLED THE SECOND
TIME, IT CANCELS SUBPROG1. THEN MAINPROG CALLS
SUBPROGl AGAIN, AND AGAIN AFRESH COpy OF THIS
SUBPROGRAlt SHOULD BE KADE AVAILABLE.
THE OUTPUT PROK· THIS RUH SHOULD READ AS FOLLOWS:
'BEGIN MAINPROG.
8AINPROG CALLING SUBPROG1.
SUBPROGl CALLED -- IN INITIAL STATE.
ftAINPROG CALl.ING SUBPROG2.
SUBPROG2 CALLED -- IN INITIAL STATE.
MAINPROG CALLING SUBPROG1.
SUBPROGl CALLED -- IN LAST-USED STATE.
ftAINPRQG CALLING SUBp·aOG2.
SUBPROG2 CALLED -- IN LAST-USED STATE.
SUBPROG2 CANCELLING SUBPROG1.
MAINPROG CALLING SUBPROG1.
SUBPROG1 CALLED -- IN INITIAL STATE.
ftAINPROG CANCELLING SUBPROGl AND SUBPROG2.
END MAINPROG.'
ENVIRONMENT DIVISION.
CONPIGURATION SECTION.
SOURCE-CO~PUTER. IBM-370.
OBJECT-COMPUTER. IBM-370.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 SWITCH PIC 9 VALUE O.
71 CALLID PIC X(8).
PROCEDURE DIVISION.
DISFLAY 'BEGIN 8AINPROG'.
ST AR T-CAtL S.
IF SWITCH IS LESS THAN 2 PERFORM CALL1,
PERFORM CALL2,
GO TO START-CALLS.
PERF ORlt CALL 1.
DISPLAY 'MAINPROG CANCELLING SUBPROGl AND SUBPROG2'.
CANCEL 'SUBPROG1'.' SUBPROG2'.
DISPLAY 'END ftAINPROG'.
STOP RUN.
CALL 1.
MOVE 'su BPROG l' -ro CALLI D.
DISPLAY 'KAINPROG CALLING SUBPROG1'.
CALL CAL LID.
CALL2.
KOVE 'SUBPROG2' TO CAtLID.
DISPLAY 'ftAINPROG CALLING SUBPROG2'.
CALL CALLID.
ADD 1 TO SWITCH.
I
I
*
J
I
I
1
J
I
,
,
1
I
I
I
J
!
I
I
,
I
I
t
1
I
I
I
I
j
I
I
t
I
I
I
I
t
I
I
I
t
I
I
I
J
t
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
I
1*
I/ILKED.SYSLftOD DD DSN=SUBPROGS(8AINPBOG).UNIT=2314,VOL=SER=XXXXXX,DISP=OLD
II/GO EXEC PGK=ftAIHPROG
IIISTEPLIB
DD DSN=SUBPROGS,UNIT=23l4, VOL=SER=XXXXXX,DISP=OLD
IIISISOUT
DD SYSOUT=A
1/*
I
Figure 122.
.J
Sample Calling and Called Programs Using Dynamic CALL and CANCEL Statements
(Part 3 of 3)
Calling and Called programs
321
~Q£r es I?Q!H!!m£!L2.Lllg.n.ti fi~2-in._~~lling:
~u~_Ca!leg-f£ogr~2
The number of data-names in the
identifier list of a calling program must
be the same as the number of data-names in
the identifier list of the called program.
There is a one-to-one correspondence; that
is, the first identifier o£ the calling
program is passed to the first identifier
of the called program, the second
identifier of the calling program is passed
to the second identifier of the called
program, and so forth.
Only the address of an identifier list
passed. Consequently, the data-name
that is an identifier of the calling
program and the data-name that is the
corresponding identifier of the called
program both refer to the same locations in
main storage. The pair of names, however,
need not be identical, but the data
descriptions must be equivalent. For
example, if an identifier of the calling
program is a level-77 data-name of a
character string of length 30, its
corresponding identifier of the called
program could also be a level-77 data-name
of a character string of length 30, or the
identifier of the called program could be a
level-01 name with subordinate names
representing character strings whose
combined length is 30.
~s
Although all identifiers of the called
program in the ENTRY statement must be
,.I Register I Register
1 Number I
Use
tI
t
Jidentifier
I
I
I
13
JSave Area
I
I
I
j
J
14
I Return
f
J
I
I
I
I
i
15
I Entry Point l
I
I
described with level numbers of 01 or 77,
there is no such restriction made for
identifiers of the calling program in the
CALL statement.
An identifier of the
calling program may be a qualified name or
a subscripted name.
FILE-NAME ARGUMENTS
A calling COBOL program tha t ca lIs an
assembler-language prog.ram can pass
file-names, in addition to data-names, as
identifiers. For a queued file, the
file-name is passed as the address of the
DeB (Data Control Block) and for a basic
file, the file-name is passed as the
address of the DECB (Data Event control
Block). A VSAM file name cannot be passed.
LINKAGE IN A CALLING OR CALLED
ASSEMBLER-LANGUAGE PROGRAM
In a COBOL program, the expansions of
the linkage statement provide the saVe and
return coding that is necessary to
establish linkage between the calling and
the called programs.
Assembler-language
programs must be prepared in accordance
with the basic linkage conventions of the
oper~ting system.
Figure 123 shows the
conventio.ns for use of general registers as
linkage registers.
•
I
I
I
---I
I
I Address of the list that is passed to the called program.
I
I
f Address of a n area (of 18 fullwords) to be used by the called I
program to save registers.
I
•
t
I
I Address of the location in the calling program to which
f
control should be returned after execution of the called
I
f
program.
I
f
I
I
I Address of the entry poi.nt in the called program to which
•I
I
control iS,to be transferred.
J
Con tents
____~I~------------------------------------------------
t-
Regis,ter 15 is also used as a return code register. The return code indica tes
• whether or not an y exceptional conditions occurred during execution of the called
I program.
When control is returned to the COBOL program, it automatically moves the
IL-______________________
contents of register___
15 into the special register RETURN-CODE.
•
1
Figure 121.
322
Linkage Registers
,
~
I
I
I
f
~~!U.smtiQJHL. Use g,.J..!L.L~IIiB.g
!§~Ule!:-Languagg_f[.ogr9J!
A calling assembler-language progra.
must reserve a save area of 18 vords,
beginning on a fullvord boundary. to be
used by the called program for saving
registers.
It must load the address of
this area into register 13. If the program
is to pass identifiers, an identifier list
must be prepared, and the address of the
identifier list must be loaded into
register 1. 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.
The identifier list is a group of
contiguous fuilifords, each of which is an
address of a data item to be passed to the
called program. The identifier list must
begin on a fullvord boundary. The
high-order bit of the last identifier, by
convention, is set as a flag of one to
indicate the end of the list. Figure 125
shows a portion of an assembler-language
program that illustrates the conventions
used in a calling program.
chain pointer from there, and executes a
RETURN to the caller of the main program.
Execution of the GOBACK statement in a
COBOL subprogram causes a return to the
routine that called it. However, execution
of this statement in a COBOL main program
causes STOP RUN processing to occur (see
above) •
The compilation option ENDJOB causes the
STOP RUN subroutine to free all main
storage acquired during the run unit, and
to delete any subprograms or subroutine
library modules that were loaded during the
run unit. The only parts of the run unit
left after a STOP RUN with ENDJOB has
executed are any load modules that were
loaded by an assembler-language program
rather than a COBOL proq.ram. and the
library subroutine ILB05TT. These must be
deleted by an assembler-language calling
program.
If the compilation option RESTDENT is used,
it must be used by all COBOL programs in a
run unit. It causes linkage to library
subroutines to he established at execution
time, rather than at link edit time, and
maintains a list of all subroutine library
modules for which it has issued a LOAD.
7he-A§§~bler-1an~~_b~11er-A2_Main
f~gra.!!:
In an all-COBOL environment, the
first COBOL program in the run unit that is
invoked for execution becomes the main
program.
It may be invoked via an EXEC JCL
card. or by linkage from some other
program.
The fact that it is the first one
invoked under the task establishes it as a
main program. The main pcogram calls a
library subroutine which (1) initializes
the subroutine communications data area
ILBOCOM, and (2) saves a pointer to the
register save area of the main program.
(A
main program also executes a GOBACK
statement is if STOP RUN had been coded.
See below.)
Any COBOL program in voked after the COBOL
main program has begun to execute is
considered a subprogram.
A COBOL
subprogram knows it is a subprogram rather
than a main program because when it gets
control, ILBOCOM has already been
in it ia .li zed.
Execution of the STOP RUN statement by any
COBOL program causes a library subroutine
to be called which terminates the run unit.
This subroutine closes COBOL DCBs (such as
SYSIN, SYSOUT, and SYSDBOUT), and resets
certain flags and fields in ILBOCOM.
If
ENDJOB (see below) is in effect, it
performs further cleanup. Then it picks up
the main program save area (register 13)
pointer that was saved when ILBOCOM vas
initialized, follows the save area back
The compilation option DYNAH causes dynamic
LOADs and DELETEs to be done for
subprograms specified in CALL and CALL
CANCEL statements in COBOL programs in a
run unit.
It maintains a list of all
subprograms it loads in the run unit.
When a COBOL program is invoked by Job
Management via an EXEC JCL card, the
situation is straightforward. The COBOL
progra m so invo.ked is the main program and
begins the run unit.· A STOP RUN statement
causes a return to the system. RESIDENT
and DINAH may be used to improve efficiency
of main storage utilization. The ENDJOB
option is not important, in this case,
because Job Management frees main storage
and deletes load modules used by the
jobstep task when it terminates.
A COBOL program may also be invoked by
use of CALL, LOAD and CALL, LINK, or
ATTACH. If this is done, then the
following cautions must be observed:
1.
Use the ENDJOB option to make sure the
region or partition is cleared of
GETMAIN-acquired storage and loaded
modules when the run unit ends.
Then,
after the run unit has ended, have the
calling program issue a DELETE for
module ILBOSTT.
If LOAD was used in
an assembler language program to bring
in any subprograms, a DELETE should
also be issued for those modules.
Calling and Called Pcograms
323
2.
COBOL does not support concurrent
running of multiple COBOL subtasks in
one reg~on or partition.
If a COBOL
subtask is attached, it must terminate
before the next one is attached.
Multiple subtasks may work in very
limited circumstances. The following
would definitely prevent multiple
subtasking from working:
RESIDENT or
DYNAM options, or use of the same data
set by two different subtasks.
The COBOL subroutine library provides a
means whereby an assembler-language program
rna y become a main progra m; t bis is
accomplished by a call to the library
subroutine entry point ILBOSTPO, which
causes ILBOCOM to be loaded and
initialized.
If this is done first, all
COBOL programs subsequently called will
behave as subprograms.
This provides
several other ad vantages for certain types
of applications: execution of a GOBACK to
the calling assembler-language routine will
not cause STOP RUN processing--COBOL DCBs
will remain open, no storage will be freed,
no subroutines deleted; the
assembler-language main program can
continue calling its sub programs and adding
to its open data sets until one of the
subprograms executes a STOP RUN.
Execution
of a STOP RUN will cause return to the
caller of the assembler-language program,
rather than to the assembler-language
program itself.
f
t
t-
t Called COBOL
Called COBOL
Progr.am Compiled
with NORESIDENT
option
L-
324
The CALL to ILBOSTPO may not be used
if the COBOL program is invoked by
LINK or ATTACH.
5.
If DYNAH is used, all COBOL programs
must be link edited in separate load
modules.
Case 1. Caller should have a v-type
address constant for ILBOSTPO and should
call ILBOSTPO using it.
Library
subroutine ILBOSRV must be included in
the link edit, but ILBOCOM must not be.
The COBOL program may then be called
as a subroutine.
Case 2.
Caller should have a V-type
address constant for ILBOSTPO and should
call ILBOSTPO using it. Library
subroutine ILBOSRV. must be included in
the link edit of the caller, but ILBOCOM
must not be.
No library subroutines
should be included in the link edit of
the called COBOL program. After the call
to ILBOSTPO, caller should issue a LOAD
for the called COBOL program.
The COBOL
program may then be called as a subroutine.
-,
t Together
f
I Case 1
Case 2
f
I
I Case 3
J
I
I
J
I
,
I
t----------t
I
J
I
I
4.
Caller and COBOL I
prog ram Linked
i
separately
f
t Program compiled J
t wi th RES ID ENT
1
, opt.ion
If NORESIDENT is used, all programs
and subroutines must be link edited
together.
Case 3. Caller should have a V-type
address constant for ILBOSTPO and should
r--------------~--------------------r-----
I Caller and COBOL
I progr am Linked
3.
In Cases 1, 2, and 3, the CALL to
ILBOSTPO interface is being used.
In Case
4, it is not.
The subroutine ILBOSRV must be
included in the link edit of the
calling program.
J
If RESIDENT is used, ILBOCOM must not
be included in any link edit.
Please
note that the link edit of ILBOSRV
to serve the ILBOSTPO interface must
~eave a weak external reference for
ILBOCOM unresolved.
The following table distinguishes the
procedures for initialization with several
representative types of program linkage.
If this type of processing is desired,
the assembler-language program must issue a
CALL to the library subroutine entry point
ILBOSTPO before making any call to a COBOL
program.
(Please note that ILBOSTPO
destroys the contents of Registers 0 and
1.) The following considerations apply to
the use of the CALL to ILBOSTPO (within a
single run unit):
1.
2.
,
Case 4
I
I
I
I
--'
call ILBOSTP using it. The COBOL program
may then be called as a subroutine. with
the NORES option, all subroutines vill be
link edited into the load module.
Case 4. Caller must LOAD the COBOL
module, then call it. Caller may
use LINK or ATTACH instead of LOAD,
CALL, and DELETE.
Figure 124 is an example of Case 2 and
illustrates one fairly typical and useful
configuration for assembler-language
programs calling COBoL-language routines.
COBOL1 is a transaction processor of some
type. ASM1 collects transactions and
passes them to 15M2, which passes them one
at a time to COBOL1.
When all transactions
are done, 15M2 calls COBOL2 to execute a
STOP RUN, perform ENDJOB cleanup, and
.return to 1SM1.
Because ASM2 has first called ILBOSTPO,
all COBOL programs in the run unit will
behave as subprograms. Thus when COBOL1
returns control to ASM2 after a call, it
remains in main storage in its last-used
state. There is no overhead ior clean~p
or for reinitialization on the succeeding
call. COBOL1 can return control by
either an EXIT PROGRAM or a GOBACK.
(Because it is behaving as a subprogram,
GOBACK is equivalent to EXIT PROGRAM.)
ENDJOB processing is not done for any of
the exits from COBOL1-.--It is only done
once, in response to the STOP RUN in
COBOL2.
Two of the several possible ways to
compile and link edit this application are:
1.
Compiling with ENDJOB and NORESIDENT.
A5M2, COBOL 1, COBOL2, and all required
library subroutinesliould be link
edited together. ASM1 would issue a
LOAD,f?r, ASM2, then CALL it. Upon
rece~v1ng control again, ASM1 would
DELETE ASM2."
2.
Compiling with ENDJOB and RESIDENT.
ASM2 and ILBOSRV would have to be
link edited together. COBOL 1 could
also be included.
In that case,
ASM1 would issue a LOAD for ASM2,
then CALL it. ASM2 would have to
issue a LOAD for COBOL2 before
calling it. When control is returned
to ASM1, it must issue a DELETE for
ASM2, COBOL2, and ILBOSTT.
CALL
ASMI
.-
CALL
ILBOSTPO
ASM~
LOAD-f-
CALL
---0
COBOLI
EXIT PROGRAM
or GOBACK
CALL
EXIT PROGRAM
or GOBACK
CALL
EXIT PROGRAM
or GO BACK
CALL
COBOL~
STOP RUl\.
Figure 124.
Effect of STOP RUN Statement
A called assembler-language program must
save the registers and store other
pertinent information in the save area
passed to it by the calling program (the
layout of the save area is shown in Figure
127). A called program must also contain a
return routine that (1) loads the address
of the save area back into register 13,
(2) restores the contents of other
registers, loading the return address in
register 14, and (3) optionally, sets flags
in the high-order eight bits of word 4 of
the save area to 1's to indicate that the
return occurred. It can then branch to the
address in register 14 to complete the
return.
Figure 126 (Part 6) shows a portion of
an assembler-language program that
illustrates the conventions used in called
p~ogram$ that are also calling programs.
F~gure 133 shows the JCL suggested for
compiling, link-editing, and executing a
calling assembler-language program and a
called COBOL program.
Calling and Called Programs
325
.r-
I
t
J
I
LA
13,AREA
LOADS THE ADDRESS OF THIS PROGRAM'S SAVE AREA INTO
* R E G I S T ER 13.
t
1
f
I
I
,
I
AREA
OS
18F
I
I
RESERVES 18 WORDS FOR THE SAVE AREA
l
•f
f
I
I
I
I
J
j
J
I
J
*
*
*
*
CALLING SEQUENCE
LA
1,ARGLST
CALL
COBREGN2
*
*
*
I
I
LOADS INTO REGISTER 1 THE ADDRESS OF THE IDENTIFIER I
LIST TO BE PASSED. TRANSFERS CONTROL TO THE ENTRY
I
POINT OF TUE CALLED PROGRAM.
(THE CALL MACRO
J
INSTRUCTION GENERATES CODING THAT LOADS A V-TYPE
,
ADDRESS CONSTANT -- COBREGN2 -- INTO REGISTER 15 ANDI
PLACES INTO REGISTER 14 THE RETURN ADDRESS, THAT IS"
THE ADDRESS OF THE FIRST BYTE FOLLOWING THE MACRO
I
EXPANSION.
I
J•
I
I
f
• *
PARAMETER LIST
J
I
OS
OF
THIS PAR AMETER LIST CONTAINS ONLY ONE ARGUMENT.
I
ARGLST
DC
xtSO'
FIRST BYTE OF LAST ARGUMENT (ONLY
I
•
f
DC
AL3(ARGUMEN~
ARGUMENT IN THIS PROGRAM) SETS BIT 0
I
I
ARGUMENT DC
C'1'
TO 1.
I
l\
-f
I JiQ.t~: Since the calling program containing this coding could previously have been
I
I called by a nother program, it also could establish linkage between the save area it has I
Ireceived and the save area it passes to the called program.
It vould store in word
I
,three of the old save area the address of the new save area, and it would store in tlordl
t two of the new sa ve area the address of the old save area.
I
.I
L-
Figure 125.
Sample Linkage Coding Used in a calling Assembler-Language Program
COMMUNICATION WITH OTHER LANGUAGES
An American National Standard COBOL
program may communicate at object time
with programs written in other source
program languages, such as COBOL F, PL/I,
and FORTRAN. However, such communication
must follow the same conventions discussed
above under' "Linkage in a Called or Calling
Assembler-Language Program." The
relatively few problems that may arise
in using American National Standard COBOL
with COBOL F usually have to do with
slightly different boundary alignments,
slack-byte insertion, different meanings for
the same reserved word, and so on.
There is a greater disparity between
American Nat ional standa.rd COBOL and
FORTRAN, much of it stemming from the basic
differences in the applications for which
these languages were developed.
(FORTRAN
is process oriented and does comparatively
li ttle file processing; COBOL, on the other
hand, is definitely file oriented and is
not mathematically self-sufficient.)
Care
must be taken, therefore, in attempting to
pass arguments between American National
Standard COBOL and FORTRAN programs.
326
The use of COBOL and PL/I together
requires a number of important
considerations. See the pUblications OSLvS
linkage Editor and Loader and either Q~
'llLLQptiJ!i;inL£oml!ileLf!:Q9.~~lIlm~~~2
GU!Q~, Order No. SC33-0006 ot:
PLII
as
Checkout compiler:
Prollg,.!!.m.g~S
Order No. SC33-0007.
GuiQ~,
Abnormal terminations in non-COBOL
programs calling COBOL programs compiled
with either the STATE or the SYMDMP option
(see the chapter entitled "symbolic
Debugging Features") cause generation of
the following .m.isinformation:
• Incorrect number for the statement
responsible for the abnormal
termination. The last COBOL statement
in the called program executed before
the return to the calling non-COBOL
program is given in the "Last Card
Number Executed" message.
• Incorrect PROGRAM-ID when sucll an
abnormal termination occurs after
return from the called COBOL program.
ThePROGRAM-ID message contains the
user-specified name for the called
COBOL program ..
The following set of programs- (Figure
126) contains a sample COBOL main-line
program. COB MAIN, which calls COBOL and
assembler-language programs using arguments
that represent a data-item and a file-name.
Some of the called programs (COBOL1,
COBOL1B, and ASSMPGM) are themselves
calling programs.
Program COBREGNO is
called by several programs, each of which
enters at a different entry point within
the program.
,
IDENTIFICATION DIVISION.
PROGRAR-ID.
COBKAIN.
E NVIRONftENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.
IBM-370.
OBJECT-COMPUTER.
IBH-310.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT FILE-X ASSIGN TO UR-2540R-S-INFILE.
I-O-CONT ROL.
DATA DIVISION.
FILE SECTION.
FD ll~~=.!RECORD CONTAINS 80 CHARACTERS
LABEL RECORD IS OMITTED.
o 1 I N-=.RE~.~
05 TYPEN PIC I.
105 HOLDER PIC X.
05 FILLER PIC 1(78).
WORKING-STORAGE SECTION.
77 SIGNAL PIC X(8).
PROCEDURE DIVISION.
I
I
I
I
I
I
I
I
I
I
t
I
I
1
I
I
I
•J
t
1
I
t
I
I
t
I
I
I
I
,
,
I
I
1
OPEN INPUT FILE-X.
tn~-jaf FiLE-iA'l'END GO TO CLOSE-FILE.
I
t
I
I
CALL 'COBOL1' USING IN-REC.
J
I
t
J
I
I
t
I
I
I
I
I
CALL 'COBREGN1' USING IN-REC.
f
t
I•
CALL 'ASSMRTN' USING SIGNAL.
1
,
I
,
I CLOSE-FILE. CLOSE FILE-X.
I
I
I
IL-______________________
STOP RUN.
.__________________------.________________. _______
I
J
t
I
1
I
J
Figure 126.
Sample calling and Called Programs (Part 1 of 7)
Calling and Called Programs
327
r-------------------
------------------------------------------------------------,I
I
I IDENTIFICATION DIVISION.
I PROGRAft-ID. COBOL1.
I ENVIRONMENT DIVISION.
I CONFIGURATION SECTION.
I SOURCE-COMPUTER.
IBM-370.
I OBJECT-COMPUTER. IBM-370.
I INPUT-OUTPUT SECTION.
I FILE-CONTROL.
I-O-CONTROL.
DATA DIVISION.
FILE SECTION.
WORKING-STORAGE SECTION.
77 TRANS-CO.BL PIC X (7).
LINKAGE SECTION.
01
PASS-REC.
05 FILLER PIC X.
05 TRANS-VALUE PIC X.
05 FILLER PIC X(78).
PROCEDURE DIVISION USING PASS-REC.
I
f
I
I
I
I
I
I
I
CALL 'COBOL1A' USING TRANS-COBL.
CALL 'COBOLIB' USING TRANS-COBL.
GOBACK.
Figure 126.
Sample Calling and Called Programs (Part 2 of 7)
.,
.---
I IDENTIFICATIO N DIVISION.
I PROGRAM-ID. COBOL1A.
J ENVIRONMENT DIVISION.
I CONFIGURATION SECTION.
IB~-370.
I SOURCE-COMPUTER.
• OBJECT-COMPUTER.
IBM-370.
J INPUT-OUTPUT SECTION.
I FI LE-CONTROL.
I I-O-CONTROL.
I DATA DIVISION.
I FILE SECTION.
1 WORKING-STORAGE SECTION.
I LINKAGE SECTION.
t 77 TRANS-COB 1 A PIC X(7).
I PROCEDURE DIVISION USING TRANS-COB1A.
I
j
I
t
GOBACK.
I
I
t
J
I
I
t
I
I
t
,
I
I
I
I
I
I
J
I
-'
Figure 126.
328
Sample Calling and Called Programs (Part 3 of 7)
,
.---
IDENTIFICATION DIVISION.
PROGRAM-ID.
COBOL lB.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.
IBM-370.
OBJECT-COMPUTER.
IBM-370.
INPUT-OUTPUT SECTION.
PI LE-CONTROL.
I-O-CONTROL.
DATA DIVIS ION.
FILE SECTION.
WORKING-STORAGE SECTION.
77 TRANS-CQBREGN PIC X(7).
LINKAGE SECTION.
77 TRANS-COB1B PIC X(7).
PROCEDURE DIVISION USING TRANS-COB1B.
I
I
1
I
t
I
I
,
1
1
I
I
t
J
I
J
I
t
I
,,
CALL 'COBREGNO' USING TRANS-COBREGN.
t
1
GOBACK.
1
.J
Figure 126.
Sample calling and Called Programs (Part 4 of 7)
r-----
----''1
IDENTIFICATION DIVISION.
PROGRAM-ID.
COBREGNO.
ENVIRONftENT DIVISION.
CONFIGURATION SECTION.
IBM-370.
SOURCE-COMPUTER.
OBJECT-COMPUTER.
IBM-370.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
I-O-CONTROL.
DATA DIVIS ION.
FILE SECTION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
77 TRANS-COB PIC X(7).
77 TRANS-ASSM PIC 1(4).
01
P1SS-R EC.
05 PILLER PIC x.
05 TRANS-VALUE PIC X.
05 FILLER PIC 1(18).
PROCEDURE DIVISION USI NG TRANS-COB.
t
I
,
I
I
I
I
,
,
I
t
I
I
1
I
I
I
t
I
I
,
,
I
I
B.
GOBACK.
ENTRY 'COBREGN1' USING PASS-BEC.
I
I
t
C.
•J
GOBACK.
ENTRY 'COBREGN2' USING TRANS-ASSM.
I
I
I
t
I
_ _ _ _ _ _ _ _,,J
GOBACK.
1-
Figure 126.
Sample Calling and Called Programs (Part 5 of 7)
Calling and Called Programs
329
rj
ASSMPGM
1
START a
PRI NT NOGEN
ENTRY ASSMRTN
I
I
ESTABLISHES ASSMRTN AS AN EXTERNAL NAME THAT CAN BE 1
J
REFERRED TO I.N ANOTHER PROGRAM.
f
*
USING ASSMRTN,15
J
I
J
I
* SAVE ROUTINE
I
ASSMRTN
SAVE
( 14,12)
STORES THE CONTENTS OF REGISTERS 14, 15, 0, AND 1
•
J
IN WORDS 4, 5, 6, AND 7 OF THE SAVE AREA.
I
f
*
THESE ARE CONVENTIONAL LINKAGE REGISTERS.
f
I
*
REGISTERS 2 THROUGH 12, WHICH ARE NOT
•
t *
ACTUALLY USED FOR LINKAGE, ARE SAVED IN SUBSEQUENT,
I
*
WORDS OF THE SAVE AREA.
THE EXPANDED CODE OF THE J
I *
SAVE
MACRO
INSTRUCTION
USES
REGISTER 13, WHICH
I
I
*
CONTAINS THE ADDRESS OF THE SAVE AREA, IN
f
J *
EPFECTING THE STORAGE OF REGISTERS.
I
f
*
LR
10,15
I
t
DROP 15
I
I
USING ASSMRTN,10
I
I
LR
11,13
LOADS THE ADDRESS OF THE SAVE AREA INTO REGISTER 11"
1
WHICH WILL SUBSEQUENTLY BE USED TO REFER TO THE
I
I
*
SAVE AREA.
J
I *
I
J
LA
13,AREA
LOADS THE ADDRESS OF THIS PROGRAM'S SAVE AREA INTO
J
t
REGIST ER 13.
I
I
*
I
I
13,8(11)
STORES THE ADDRESS OF THIS PROGRA~'S SAVE AREA INTO I
ST
f
WORD 3 OF THE SAVE AREA OF THE CALLING PROGRAM.
I
I *
I
f
11,4(13)
STORES THE ADDRESS OF THE PREVIOUS SAVE AREA INTO
ST
I
j
WORD 2 OF THIS PROGRAM'S SAVE ARRA.
I
*
B
PROCESS
I
I
DS
AREA
18F
RESERVES 18 WORDS FOR THE SAVE AREA.
I
I•
LOADS INTO REGISTER 2 THE ADDRESS OF THE IDRNTIFIER-,
L
2,0(1)
J PROCESS
LIST PASSED TO THE PROGRAM.
THE ADDRESS OF THE
I
J *
IDENTIFIER-LIST IS ALWAYS PASSED IN REGISTER 1,
I
f
*
WHICH IS USED HERE AS THE BASE REGISTER TO GET THEI
I
*
ADDRESS.
SUBSEQUENT REFERENCES TO THE IDENTIFIER I
J *
WILL USE REGISTER 2 AS THE BASE REGISTER FOR THAT I
*
ADDRESS.
(IF A VARIABLE-LENGT~ IDENTIFIER-LIST
•
I• *
COULD BE USED IN CALLING THIS PROGRAM, EACH
I
f
*
IDENTIFIER WOULD BE TESTED FOR A ONE IN THE
I
t *
HIGH-ORDER BIT.)
I
*
I
I
{User-written program statements}
t
I
I
I
I
I
* CALLING LASEQUENCE
LOADS INTO REGISTER 1 THE ADDRESS OF THE IDENTIFIER-I
1,ARGLS'f
t
LIST TO BE PASSED.
I
I
*
I
I
CALL COBREGN2
TRANSFERS CONTROL TO THE ENTRY POINT OF THE CALLED 'J
J
PROGRAM.
[TBE CALL MACRO INSTRUCTION GENERATES
I
*
CODING THAT LOADS A V~TYPE ADDRESS CONSTANT -J *
COBREG N2 -- INTO REGISTER 15 AND PLACES INTO
I
I
*
REGISTER 14 THE RETURN ADDRESS (THAT IS, THE
I
I *
ADDRESS OF THE FIRST BYTE FOLLOWING THE MACRO
I
t *
EXPANS ION) ].
I
J *
I
I
{User-written program statements}
I
L- _______________________________
I
,
,
,
,
,
,
•
Figure 126.
330
,
~------------------
Sample Calling and Called Programs (Part 6 of 7)
I
-----,
f
*
CALLING SEQUENCE
LA
1, ARGl.ST
*
CALL
*
*
*
*
*
*
COBREGN2
,
LOADS INTO REGISTER 1 THE ADDRESS OF THE
IDENTIFIE"RLIST TO BE PASSED.
I
J
I
J
TRANSFERS CONTROL TO THE ENTRY POINT OF THE CALLED
PROGRAM.
[THE CALL MACRO INSTRUCTION GENERATES
CODING THAT LOADS A V-TYPE ADDRESS CONSTANT -COBREGN2 -- INTO REGISTER 15 AND PLACES INTO
REGISTER 14 THE RETURN ADDRESS (THAT IS, THE
ADDRESS OF THE FIRST BYTE FOLLOWING THE MACRO
EXPAN SION) ].
I
I
I
J
I
I
I
I
I
I
RETURN ROUTI NE
1
L
13,4( 13)
LOADS THE ADDRESS OF THE PREVIOUS SAVE AREA
1
BACK INTO REGISTER 13.
I
I
RETURN(14,12) ,T,RC=(15) THIS RETURN MACRO INSTRUCTION RESTORES THE SAVED
I
REGISTERS (14, 15, AND 0 THROUGH 12). THE RETURNI
ADDRESS IS RESTORED TO REGISTER 14, AND THE
I
EXPANSION INCLUDES A BRANCH TO THAT INSTRUCTION. J
THE Ir' IN THE RETURN MACRO INSTRUCTION CAOSES
I
THE EIGHT HIGH-ORDER BITS OF WORD 4 OF THE SAVE
1
AREA TO BE SET TO ONES AS AN INDICATION THAT THE ,
RETURN HAS OCCURRED. THE RC=(15) PARAMETER
I
INDICATES THAT THIS PROGRAM IS PASSING A RETURN
1
CODE IN REGISTER 15.
t
(User-written program statements}
*
*
*
*
*
*
*
*
*
*
PARAMETER LIST
OF
DS
ARGLST
DC
X' 80'
AL3 (ARGUMENT)
DC
ARGUMENT DC
C' l'
END
Figure 126.
t
THIS PARAMETER LIST CONTAINS ONLY 1 ARGUMENT.
FIRST BYTE OF LAST ARGUMENT (ONLY ARGUMENT IN
THIS PROGRAM) SETS BIT 0 '1'0 1.
J
J
J
J
1
t
Sample Calling and Called Programs (Part 7 of 7)
Each time an entry point is specified in
a called program, an ext~gL!!.a.!!lQ is
defined (except when a program is compiled
using the DYNAH and RESIDENT compiler
options).
An external name is a name that
can be referred to by another separately
compiled or as~embled program.
Each time
an entry name is speCified in a calling
program, an ~~~al_ref~~£~ is defined
except when a program" is compiled using the
DYNAM and RESIDENT compiler options.
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 references and combines calling and
called progr ams into a forma t sui table for
execution together, i.e., as a single load
module except when programs are compiled
with dynamic CALL statements and/or the
RESIDENT option (see the section entitled
"Programs Compiled with the DYNAH and/or
RESIDENT options").
Load modules of both calling and called
programs are used as input to the linkage
editor. There are two kinds of inputr
primary and additional. ~£ima£~ input
consists of a sequential data set that
contains one or more separately compiled
object modules and/or linkage editor
control statements.
The primary input can
contain object modules that are either
calling or called programs or both.
,!ggiti2!lg! input consists of object modules
or load mod ules that are not part of the
primary input data set but are to be
included in the load module.
The
additional input may be in the form of (1)
a sequential data set consisting of one or
more object modules with or without linkage
editor control statements, or (2) libraries
containing object modules with or without
linkage editor control statements, or (3)
libraries consisting of load modules.
Note
that the secondary input (all libraries
and/or data sets) must be composed of
either all object modules or all l..Qg,g
modules, but it cannot contain both types.
The additional input is ~pecified by
Calling and Called Programs
331
r-------------------------------------------------------------------------..
-------------,I
I Word
Area
I No.
No.
Contents
I
~-------------------------------------------------------------.--------------------------~
I 1
AREA
Used by COBOL.
I
I
I
I
I
I
I
I
I
I
I
2
AREA +4
Address (passed by the calling program) of the save area used by the
calling program. This is the address of a save area that was
passed to the called program by the program that called the called
program.
3
AREA +8
Address (stored by the called program) of the next save area, that
is, the save area that the called program provides for a program
that it calls.
The called p~ogram need not reserve a save area if
it does not, in turn, call another program.
4
AREA +12
Return address (contents of register 14) stored by the called
program.
5
AREA +16
Entry pOint address (contents of register 15) stored by the called
program.
6
AREA +20
Contents of register 0 (stored by the cal.1..ed program).
7
AREA +24
Contents of register 1 (stored by the called program); that is, the
address of the identifier list passed to the called program.
8
AREA +28(
Contents of registers 2 through 12 (stored by the called program).
I
I
AREA +68
Il ______________________________________________________________________________________
18
_
~
Figure 127.
Save Area Layout and Contents
linkage editor control statements in the
primary input and a DD statement for each
additional input data set.
Addi tional
input may contain either calling or called
programs or both.
!21~:
Each additional input data set may
itself contain external references or names
and linkage editor control statements that
specify more additional input.
SPECIFYING PRIMARY INPUT
The pri rna ry input data set is specified
for linkage editor processing by the SYSLIN
DD statement. The linkage editor must
always have a primary inpu t data set
specified by a SYSLIN DD statement whether
or not there are called or calling programs
and even if the primary input data set
contains only linkage editor control
statements. The SYSLIN DD statement that
specifies the primary input is discussed in
"Linkage Editor Data Set Requirements" (see
"Example of Linkage Editor Processing" for
a discussion of how to specify a primary
in pu t data set that cont ains more than one
object module along with linkage editor
control statements).
332
SPECIFYING ADDITIONAL INPUT
Additional input data sets are specified
by linkage editor control statements and a
DD statement for each additional input data
set.
The linkage editor control statements
that specify additional input are INCLUDE
and LIBRARy.1 A primary input data set may
consist entirely of such statements. The
INCLUDE and LIBRARY statements may be
pla~ed before, bet ween, or after object
modules or other control statements in
either primary or additional input data
sets. One method of using these statements
is shown in Figure 134.
!Q1~:
Additional input often contains
members of libraries (see "Specifying
Libraries as Additional Input" in
uLibraries").
1The operation field in a linkage editor
control statement must start after column
1.
The operand field must be preceded by
at least one blank.
The INCLUDE statement is used to include
an additional input da·ta set. that is either
a member of a library or a sequential data
set. The format is:
r------------~--------------
I operation
Operand
t-------+-I INCLUDE
I
I
,
L-___________
~
---------------,I
,
ddname( (member-name
I
[,member-name] ••• ) ]
I
[,ddname[(member-name
[ _, member-name
])_]]
•••
____
_ •••
__
__
_ _ _ JI
•
The ALIAS statement specifies additional
names for the output library member, and
can also display names of additional entry
points. If a load module has more than one
entry point or more than one CSECT and the
user wishes to access that alternate entry
at execution time via a dynamic CALL, he
should specify an ALIAS with the same
symbolic name as the desired entry point or
CSECT. The format is:
.
~
JOperationl Operand
,
I
I
'lsymbol
[,SymbOl
IALIAS
I
,external
I
I external name\
l
where ddname indicates the name of the DD
statement that specifies the library or
sequential data set, and member-name is the
name of the library member t hat is to be
included. Member-name is not used w'hen the
additional input data set is not a member
of a partitioned data set.
The LIBRARY statement is used to include
additional input that may be required to
resolve external references. The format
is:
where symbol specifies an alternate name
for the load module, and external name
specifies a name that is defined as a
control section name or entry name in the
output module.
If the linkage-editor input includes an
ALIAS statement, the symbolic name
specified is identified with the relative
location of the entry point or CSECT name
that matches the ALIAS.
If there is no
matching entry point or CSECT name, the
ALIAS is identified with relative location
zero in the load module.
liQ!~:
If the us~r plans to dynamically
call a subprogram at an ENTRY point, an
ALIAS card is required in the link-edit
step for that entry point.
r-
t operation
Operand
r-----------~----
I LIBRARY
I
I
I ______________
~L
~
ddname(member-name
[,member-name] ••• )
[,ddname(member-name
C,member-name ••• ]) ] •••
_________________________________
J
where ddname indicates the name of the DD
statement that specifies the library, and
member-name is the name of the member of
the library.
The LIBRARY statement differs from the
INCLUDE statement in that libraries
specified in the LIBRARY statement are not
searched for additional input until all
other processing, except references
reserved for the automatic library call, 1S
co.pleted by the linkage editor.
Any
additional module specified by an INCLUDE
sta teaent is incorporate d immediately,
vheneyer the INCLUDE statement is
encountered.
The NAME statement specifies the name of
the load module created from the preceding
input modules and serves as a delimiter for
input to the load module.
The NAME
statement may be used to assign a symbolic
name to a load module. This symbo.lic name
is entered in the directory of the
partitioned data set that contains the
module, and allows the module to be
accessed at execution time by an OS/VS
LOAD, LINK, XCTL, or ATTACH macro.
The
format is:
operation
Operand
NAME
member-name ( (R) ]
L - -_ _ _
~
where member-name specifies the name to be
assigned to the load module tha t is created
Calling and Called Programs
333
from the preceding input modules, and {R)
indicates that this load module replaces an
identically named module in the input
module library.
(If the module is not a
replacement, the parenthesized value (R)
has no effect.)
If the linkage-editor input includes a
NAME statement, the symbolic name specified
is always identified with relative location
zero in the load module, unless there is an
ENTRY statement specifying a different
location.
The PAGE statement aligns a control
section or named common area on a 4K page
boundary in the load module.
For OS/VS2,
if the ALIGN2 attribute is specified on the
EXEC statement for the linkage editor job
step, use of the PAGE statement aligns the
specified control sections or common areas
on 2K page boundaries within the load
module.' Its format is:
The ENTRY statement specifies the
symbolic name of the first instruction to
b~ executed when the program is called by
its module name for execution.
An ENTRY
statement should be used whenever a module
is reprocessed by the linkage editor. If
more than one ENTRY statement is
encountered, the first statement specifies
the main entry point; all other ENTRY
statements are ignored. Its format is:
I
,
r-
"1
loperation IOperand
a
I
'ENTRY
lexternalname
.,
L-
the name of the control section to be
sequenced, and P specifies that the
starting address of the control section or
named common area is to be on a page
houndary within the load module.
When P is
specified, the control sections or common
areas are aligned on 4K page boundaries
unless the ALIGN2 attribute is specified on
the EXEC statement.
J
_____________,--J
wh.ere extern alname is defined as either a
control section name or an entry name in a
linkage editor input module.
i
----------,
JOperationlOperand
I
•
.,
I PAGE
I
f
J~common-area-name{ [
f
Ifsectname
~
I
~
I
------------~
I
Ikommon-area-namelJ
'
J
~sectname
~
I
________-4'__,______________
J
~
~~
where common-area-name is the name of the
common area to be aligned on a page
boundary, and csectname is the name of the
control section to be aligned on a page
boundary.
QiDER Statemen1
The ORDER statement specifies the
sequence in which control sections or named
common areas are to appear in the output
load module.' When multiple ORDER
statements are used, their sequence further
determines the sequence of the control
sections or named common areas in the
output load module; those named on the
first statement appear first, and so forth.
Its forma t i s :
r-
,
-,
I operation ,operand
lI
IORDER
~ommon-area-name}
[ (P) ] [
sectname
I
I
l-
•
•l -
~ ommon-a rea-name}
J sectname
I
[ (P) ]
I
--f
J
.,•
J
]
where common-area-name is the name of the
common area to be sequenced, csectname is
334
•
--'
PROGRAMS COMPILED WITH THE
~,P_!.~i~AND/OR
RESIDENT OPT.IONS
In the usual called/calling situation,
all references to any subprogram or library
subroutines generated in an object program
result in a V-type address constant ('CON)
that mast be resolved by the linkage
editor. Therefore, at link-edit time, the
modules referred to by VCONs are made a
part of a single load module containing the
object program and all required subprograms
and library routines.
When the object
program is executed, all those required
routines are present in the user region for
the entire execution step, even though they
may have been used only at the beginning of
the main program and never invoked again.
with dynamic linkage, on the other hand,
the user can invoke a called program when
it is needed and retain it for only the
period needed.
Subprograms invoked through the CALL
literal statement are dynamically loaded
using the operating System LOAD macro if
DYNAK is specified.
Before the CALL
subprogram is executed, linkage is effected
for all COBOL library subroutines required
by the subprogram.
Simila.rly, use of the
CANCEL statement makes i t possible to
dynamically delete subprograms at object
time.
r--,
I
I CALL
,.----,
I
I CALL
.----,
I
I
ICOBA~'-------->tcoBB~'-------->lcOBC.
I
tliteral
"'---_J
I
Iliteral
'----.J
----------------Figure 128. CALL
I
,
L--J
with DYNAM and RESIDENT
~ecif1ing NODYNAM/RES!~~liI
Figure 122 is an exam'ple of a job
compiled with th~ ~YNaM and RESIDENT
options.
Pigurei 128 through 131 in this
section illustrate for called/calling
programs the relationship betvee~ the
possible combinations of the DINAH/RESIDENT
options and the identifier, and literal
options of the CALL and CANCEL statements.
Figure 131 shows the JCt necessary for
compiling, link-editing, and executing a
calling COBOL program and a called COBOL
program when both of the prog,rams in voke
the DINAH and RESIDENT compiler options.
When a program is compiled with DIN AM
and RESIDENT, no external references are
generated.
Therefore, while the program
may refer to other modules, no references
are resolved by the linkage editor.
In
such a case, the only input to the linkage
editor is the program itself.
Any module
the program refers to must exist in load
module form in a library that is available
to the system at execution time.
The link-editing that takes place varies
with the combinations of the DYNAM(NODYNAM)
and RESIDENT (NOR ESIDENT) options in effect.
What would seem to be the most
representative link-edit situations are
discussed in the sections that follow.
Wh~n NODYNAM and RESIDENT are specified
Jor the called/calling situation pictured
in Figure 129, a dynamic situation occurs
'because of the inclusion of CALL identifier
in the calling programs. That is, because
the name of the called subprogram is not
available until execution time, a CALL
identifier sta tement cannot be used in a
static situation.
In Figure 129, if NORESIDENT had been
'either s~ecified or implied by default, it
would have been overridden with RESIDENT.
The compiler automatically recognizes the
requiremen t for the library management
feature by the presence of either a CALL
identifier or CANCEL identifier in the
source program.
.t!otg: A printed indication of the compiler
options in effect appears in the statistics
section of the compiler output.
(Por
examples of compiler statistics, see the
chapter entitled "out put.lJ)
r--1
Figure 129.
When both DYNAH and RES IDENT are
specified for the called/calling situation
pictured in Figure 128, first the main
program COBA is compiled and link-edited;
then each of the tvo subprograms COBB and
COBC is compiled and link-edited
separately,· thereby producing th.ree
separate modules. Then the main program is
executed.
In this situation, 'all external
references are dynamically resolved.
Therefore, no VCONs are generated for the
address of an external symbol that would be
used in a static situation (that is, a CALL
literal without the DYNAH option) to effect
branches to other programs.
...-----,
,.---,
I
J CALL
t
I CALL
I
I
jCOBAr----->ICOBB'
> ICOSCI
1
lidentifierf
lidentifierl
CALL With NODYNAM and RESIDENT
In contrast with Figure 128, the
called/calling situation pictured in Figure
130 invokes the CALL literal option.
Again
the,proqrams are compiled in the order
COBA, COBB, and COBC.
The CALL literal
statements included in programs COBA and
COBB result in static calls that must be
resolved by the linkage editor. Therefore,
the three program units are ,enjoined as a
single module.
However, with the COBOL
Library Management Feature in effect,
linkage to the library is dynamic. That
is, the required COBOL object-time library
subroutines are not link-edited, bu~
linkage is effected dynamically at object
time.
IQ!~:
When including both dynamic and
static CALL statements in the same run
unit, the programmer should not dynamically
Calling and Called Programs
335
call a ny sub programs tha t are otherwise
called statically.
To do so might cause
multiple copies of the called program to be
created and, therefore, produce
unpredictable results.
The combination of RESIDENT and NODYNAM
should be used only if required library
subroutines are in fact permanently
resident, or if all calls to COBOL
subprograms are dynamic.
If the library
subroutines are not permanen t1y resident,
they will be loaded into the region or
partition during program execution. This
could cause storage fragmentation if a
sta.tic call is made to a COBOL subprogram,
because the subroutines required by a
subprogram can only be removed from the
region by a CANCEL statement for the
subprogram, and a CANCEL is invalid for a
subprogram that is statically called.
CALL
literal--->
COBA
COBB
Management Feature is not in effect, and
all CALL statements result in static calls
that must be reso1Yed by the linkage
editor. one load module is produced for
the programs COBA, COBB, COBC, and all of
the necessary COBOL library subroutines.
The NODYNAM/NORESIDENT set of options
should be used only when the user does not
intend to use the CALL or CANCEL identifier
statement or the Library Management
Peature. If either a CALL identifier or a
CANCEL identifier statement appears in any
one program, the Library Management Feature
is in effect for tha!. program only. This
situation may result in a duplication of
subprograms and COBOL library subroutines
within the user region/partition, thereby
causing unpredictable results.
CALL
literal-->
CALL
literal---)
COBC
rI
I COBA
1
COBB
CALL
litera1--)
COBC
i
ICOBOL Library Subroutinesl
'--
Figu.re 130.
CALL with NODYNAM and RESIDENT
With CALL Literal Option
For the called/calling situation
pictured in Figure 131, the COBOL Library
336
Pigure 131.
CALL With NODYNAM and
NONRESIDENT
,I//JOBY
II/STEPl
,
JOB
EXEC
1
PGM=IKFCBLOO,PARM='LOAD,DYNAM,RESIDENT'
f
I
I
t
I
I
II/SYSLIN
II/SYSIN
DO
DD
I•
{SiOllrce modille for COBMAIN, a calling COBOL proqram}
I
I
1/*
al/STEP2
IIISYSLMOD
II/SISLIN
'I/SYSIN
I NAME
11*
IIISTEP3
II/SYSLIN
IIISYSIN
I
I
11*
IIISTEP4
IIISYSLMOD
IIISYSLIN
II/SYSIN
I NAME
41*
II/STEPS
II/STEPLIB
t
DSNA8E=&&LINKOS1,DISP=(MOO,PASS).UNIT=SYSSQ,SPACE=(TRK, (10,10»
I
I
*
I
t
,
I
CALL 'COBSUB'
I
I
EXEC
PGM=HEWL
DD
DSNAME=£&GOFILE,DISP=(ftOD,PASS),UNIT=SYSSQ,SPACE={TRK,(10,10,10»
DO
DSNAME=&&LINKDS1,OISP=(OLD,DELETE)
DO
COBMAIN
I
t
*
EXEC
DD
DD
I
I
I
I
1
I
PG M=IKFt:;BLOO, PARM=' LOAD, DY NAM, RESID.ENT'
OSNAME=&&LINKDS2,DISP=(MOO,PASS) ,UNIT=SYSSQ,SPACE=(TRK, (10,10»
*
t
{Sollrce module for COBSUB, a called COBOL program}
1
J
EXEC
PGM=HEVL
DO
DSNAME=&&GOFILE,DISP=(OLD.PASS)
DD
OSNAMR:&&LINKDS2,DISP=(OLD,DELETE)
DO
COBSUB
)
I
J
I
*
EXEC
DD
)
I
,
PG M=COBMAI N
OSNAME=&&GOFILE,DISP=(OLD,DELETE)
J
11*
J
L.
Figure 132.
.J
Sample JCL for Called/Calling Proqrams Compiled with the DYNAM and RESIDENT
Options
Calling and Called "Programs
337
r-
IIICALLPEOG
I IISTEP 1
I
JOB
EXEC
I
I
PGM=IKFCBLOO¥PARft= (LOAD,NClDECK)
f
I
t
IIISYSLIN
tI I
IIISYSIN
t
1/*
IIISTEP2
til
fllSYSGO
IIISYSIN
J
I
1/*
IIISTEP3
III
DD
DSN=&&TEMPLIB1,UNIT=SYSSQ,DISP=(NEW,PASS),
SPA C E= (TR K, (1 0, 1) )
DD
*
{Source module for COBSUB¥ a called COBOL program)
X
EXEC
PGM=ASMBLR,PARM=(LOAD,NODECK),
COND=(9,LT,STEP1)1
DD
DSN=&&TEMPLIB1,DISP=(MOD,PASS)
DD
*
(Source module for ASSMMAIN, a calling assemblerlanguage program)
X
I
I
I
I
I
I
J
I
I
I
I
I
I
J
J
EXEC
PGM=HEWL,PARM=(LIST,XREF,LET),
CO ND= { (9, LT , S TEP 1 ) , (5 , LT, STEP 2) )
I
f
t
I
I
I
X
J
t
I
IllPROGLIBl
IIISISLIN
I
I
f/*
IIISTEP4
III
111SYSOUT
DD
DD
INCLUDE
ENTRY
DSN=&&TEMPLIB1,DISP=(OLD~PASS)
*
,
,
I
I
I
I
PROGLIB1~
ASSMMAIN3
EXEC
PGM=*.STEP3.SYSLMOD,COND=({9,LT,STEP1),
(5,LT,STEP2), (5,LT,STEP~)
DD
SYSQUT=A
X
~
J
~
,lThis example was chosen to illustrate the testing of condition codes.
,
12See the discussion under the INCLUDE stateJlent.
f
13 Because the COBOL program is compiled first and the linkage editor cannot identify the
I proper entry point, the ENTRY statement must be included.
•
~
Figure 133.
J
Sample JeL Used for a Calling Assembler-Language Program and a Called COBOL
Program
LINKAGE EDITOR PROCESSING
The linka ge edi tor fi rst processes the
primary input and any additional input
specified by INCLUDE statements.
All
external references in the primary that
refer only to other modules in the included
input are resolved first. If there are
still unresolved references after this
inpu t is processed ,the automatic call
library, which includes libraries specified
by the SYSLIB DD statement and by the
LIBRARY statements, is searched to resolve
the references. The automatic call library
generally will contain the COBOL library
338
subroutines.
(Externar references to these
subroutines are generated by the COBOL
compiler when statements in the source
module require certain functions to be
performed, such as some da ta conversions.)
If the additional input contains
external references andlor linkage editor
control statements, the references are
resolved in the same way.
Data sets
specified by the INCLUDE statement are
incorpora ted when the s ta temen t is
encountered. Data sets specified by the
LIBRARY statement are used only when there
are unresolved references after all of the
other processing is completed.
,
r-
IIIJOBI
IllSTEPl
JOB
EXEC
I•
I
I
II/SISLIN
II/SYSIN
I
I
I
DD
DD
11*
I
I
I
I
I
I
I
I
f
I
1
PGK=IKFCBLOO,PARM=LOAD
DSNAME=&&GOFILE,DISP=(MOD,PASS), UNIT=SYSSQ,SPACE= (TRK, (10,10,)
*
(Source module for COBftAIN)
IIISTEP2
I
I
I
EXEC
PGM=IKFCBLOO,PARM=LOAD
IIISYSLIN
DD
DD
DSNAME=*.STEP1.SYSLIN,DISP=(MOD,PASS)
I•
I
I
I
I
f
,
IIISISIN
I
I
*
J
I
I
I
I
I
I
I
I
I
(Source module for COBOL1)
I
11*
IIISTEP3
EXEC
PGM=IKFCBLOO,PARM=LOAD
DD
DD
DSNAME=*.STEP2.SYSLIN,DISP=(MOD,PASS}
I
f
•I
IIISYSLIN
Il/SYSIN
I
I
I
*
I
I
J
I
I
I
(Source module for COBOL1A)
I
1/*
IIISTEP4
I
,
EXEC
PGM=IEWL
J
I
I
I
J
f
I
IIISYSLIB
IIISYSU10D
III
IIIOBLIB
IIIADDLIB
IIISYSLIN
III
I
I
DD
DD
DD
DO
DD
DD
INCLUDE
LIBRARY
DSNAME=SYS1.COBLIB,DISP=OLD
DSNAKE=PGMLIB(CALPGM),DISP=(NEW,KEEP),UNIT=3340,X
SPACE= (1024, (50,20,2» ,VOLUME=SER=LIBPAK
DSNAME=OBJLIB, DISP=OLD
DSNAME=MYLIB,DISP=OLD
DSNAME=&&GOFILE,DISP={OLD,DELETE)
X
J
J
1
I
t
t
*
OBLIB (CO BOL 1 B, ASSHPGK)
ADDLI B (COBREGNO)
1
~
1/*
I
L
J
Figure 134.
Specifying Primary and Additional Input to the Linkage Editor
Figure 134 shows the control statements
for a job that separately compiles three
source modules (one is a calling program
and two are called programs) and places
them in one data set as primary input for
the linkage editor. The linkage editor
then links them together with additional
input {called programs that are members of
the specified librarie~ to form one load
module.
STEPl compiles a source module call ed
COBKlIN, STEP2 compiles a source module
called CDBOL1, and STEP3 compiles a source
module called COBOL1A. The object module
from each step is placed in the sequential
data set called &&GOFILE.
(Since MOD and
PASS are specified for &&GOFILE in the
SYSLIN DD statement in STEP1, the object
modules COBOL1 and COBOL1A are placed in
the data set behind the ob ject mod ule
COB~AIN.
When SYSSQ is not a mass storage
device, the SPACE paramete.r is ignored.)
Calling and Called Programs
339
Through the linkage mechanism, CALL
COBOL1 ••• , all subprograms plus COBMAIN
must be link-edited together to form one
module 42,000 bytes in size. Therefore,
COBl1AIN would require 42 ,000 bytes of
storage in order to be executed.
In STEP4, the linkage editor uses the
&&GOFILE data set as primary input, and
thecataloged libraries MILIB, OBJLIB, and
SYS1.COBLIB as additional input.
(The
INCLUDE. anel LIBRARY statements become part
of the primary input through the DD
statement following the SYSLIN DD
statement.
*
If the subproqrams needed do not fit
into main storage, the following two
techniques of overlay are available to the
COBOL programmer:
The object modules of the data set
&&GOFILE and the members COBOL1B and
~SSMPGM of OBJLIB are processed first.
If
there are unresolved references after this
input is processed, the linkage editor
searches the automatic call library, which
includes the COBOL subroutine library and
member COBREGNO of MYLIB, to resolve these
references. OBJLIB is specified in the
OBLIB DD statement and MYLIB in the ADDLIB
DD sta tement.•
• preplanned overlay using the linkage
editor
• Dynamic overlay using assembler
language macro instructions during
execution
~:
After linkage editor processing is
completed, a new library, PGMLIB, is
crea ted with CALPGM. as a member. CALPGM
contains COBMAIN, COBOL1, COBOL1A, COBOL1B,
ASSMPGM, and, possibly, COBOL subroutines
and COBREGNO.
If it is necessary to conserve main
storage, it can be accomplished by applying
the overlay technique to called and calling
programs. Called programs that do not need
to be in main storage at the same time can
be given the same relative storage address
and then loaded at di.fferent times during
execution when they are needed.
In this
way, the same storage space can be used for
more than one called program.
Note: The use of execution-time
debugging aids (SYMDMP, STATE, FLOW,
COUNT, and so forth) when utilizing
overlay structures is not recommended.
Doing so may result in uppredictable
operations within the STAE and debugging
,routines, or even abends.
Assume that the six programs illustrated
in Figure 125 have the following load
mod u Ie si 'Zes:
program
Module SiZe (in Bytes)
,
~•
eOBM AIN
CO BO.L 1
COBOL1A
COBOL 1B
COBREGNO
ASSMPGM
11,000
4,000
6,000
5,000
3,000
13,000
I
I
J
J
I
I
r-
I
I-J
J
I
1
I
f
L-
340
--L-
.J
The largest load module that can be
processed under OS/VS1 is 524,288 bytes.
If a load module exceeds this limit, i t
should be divided.
Onder OS/VS2, larger
load modules are permitted. The ON
OVERFLOW phrase should be used with the
CALL statement to handle any such size
errors.
The preplanned linkage editor facility
permits the Leuse of storage locations
already occupied.
By judiciously
modulari'Zing a program and using the
linkage editor overlay facility, a program
that is too large to fit into storage at
one time can be exec~ted.
In using the preplan ned overlay
technique, the programmer specifies to the
linkage editor which subprogLams are to
overiay each other. The subprograms
specified are processed as part of the
program by the linkage editor, so they can
be automatically placed in main storage for
execution when requested by the program.
The resulting output of the linkage editor
is called an overlay structure.
It is possible, at linkage edit time, to
set up an overlay structure by using the
COBOL source language linkage statement and
the linkage editor OVERLAY statement.
These sta temen ts enable a user to call a
subprogram that is not actually in storage.
The details for setting up the linkage
editor control statements for accomplishing
this procedure can be found in the
publication Q~L!~_1inKa~Ed;itQ.Land
b.Q9.~!ll:·
In a linkage editor run, the programmer
specifies the overlay points in a program
by using OVERLAY statements. The linkage
editor treats the entire input as one
program, resolving all symbols and
inserting tables into the program. These
tables are used by the control program to
bring the overlay subprograms into storage
automatically when called.
Figure 135 is an overlay tree structure
illustrating how the six programs in Figure
Calling and Called Progrcuns
340.1
-or-
I
I
I
Root Segment
COBMA! N
COBREGNO
,
j
I
r-
I
I
Segment 2
(CO.BOL1}
I
I
Segment 5
{ASSMPGM}
I
I
t
J
,
r
J
J
Segment 3
{COBOL1 Ti}
I
I
I
I
I
Segment 4
{COBOL 1 B}
I
I
t
I
I
I
I
J
I
I
J
_.L-
J
J
--L-
i
I
I
I
1
J
t
-L-
Figure 135.
Overlay Tree structure
126 could be positioned in main storage at
execution time using preplanned linkage
editor overlay.
Figure 136 shows the deck arrangement
required to achieve the overlay illustrated
in Figure 135. The OVERLAY statements
specify to the linkage editor that the
overlay structure to be established is one
in which the called programs of COBOL1
(COBOL1A and COBOL1B) overlay each other
when called for execution, and that ASSMPG8
and COBOL1 and its called program overlay
each other when called.
Rou tine COBREGNO is placed wi th COB8AIN
in the root segment of the overlay
structare because it is called by three of
the routines in the program, the largest of
which is ASSMPGM.
Utilizing COBREGNO as an
individual overlay segment would not have
resulted in a net decrease in the amount of
main storage required for execution because
the minimum amount of main storage needed
wonld have to contain COBPJAIN" ASS8PGPl. and
COBREGNO at the same~ime. creating
another overlay segment for COBREGNO would
only have added to the amount of time
required for program execution.
In preparation for the dynamic overlay
each part of the program brought
into storage independently should be
processed separately by the linkage edi tor.
(Hence, each part must be processed as a
separate load module.)
To execute the
entire program" the programmer must:
techni~ue"
1.
specify the main program in the EXEC
sta tement.
2.
Bring the separately processed load
modules into storage when they are
required# by asing the appropriate
supervisor linkage macro instructions.
This is accomplished during execution.
Calling and Called Programs
341
r-----------------JOB
IIIOVERLAY
II/STEPl
II/SY5LIB
II/SYSPRINT
t I/SYSUT 1
"ISYSLMOD
EXEC
DD
DD
DD
DD
NY83937800,COS!O.MSGLEVEL=1
PGM=IEWL,PARM='OYLI,LIST,XREP',LET'
DSNAftE=SYS1.COBLIB.DISP=SHR
SYSOUT=A
UNIT=SYSDA,SPACE=(1024, (50,20»
----------------,I
I
,t
I
I
I
t
I
I
I
I
DSNA~E=&GODATA(~UN),DISP=(NEW,PASS),UNIT=SYSDA, X
tl/
SPACE=(1024,(50,20,1»)
DO
I//SYSLIN
I
{COBMAI N
f
(COBREGNO
I
,
object deck}
object deck}
,OVERLAY ALPHA
I
{COBOLl
object deck}
*
,
I
t
IOVERLAY BET A
I
{COBOL1A
I
I
I
I
object deck}
J
fOVERLAY BETA
I
{COBOL1B
,
I
object deck}
1
IOVERLAY ALPHA
t
(ASSMPGM
l/*
'-
___
Figure 136.
I
I
object deck}
Sample Deck for Linkage-Editor Overlay Structure
The dynamic overlay technique can be
used to overlay subprograms during
execution.
To accomplish dynamic overlay
of subprogra ms, the programmer must write
an assembler language subprogram that
employs the LINK macro instruction to call
each COBOL subprogram.
For a detailed
description of the LINK macro instruction,
see the publication QU!L~Y£~I.viso.t:
~g£~icg§~nd
Ma££Q_!nstr~1!Q~2.
In using the dynamic overlay techn.l.que,
the main program communicates with the
assembler language subprogram by using the
COBOL language CA'LL statement.
The CALL
statement can be used to pass the name of
the COBOL subprogram (to he linked) and the
spec ified pa rame ter list to the assembler
language subprogram.
This procedure is the
same for each CALL used in the main
program.
Hence, each CALL results in
linking with a subprogram through the
assembler language subprogram.
When the COBOL subprogram is finished
executing, i t returns control to the
assembler language subprogram, which in
turn returns to the main program. The
process is repeated for each CALL to the
assembler-language subprogram.
Dynamic overlay requires that a
programmer have detailed knowledge of the
linkage conventions, assembler language,
and the LINK macro instruction with its
features and restrictions.
342
I
I
,---------.1
Figure 137 contains an example of a
COBOL main program, PROGMAST, and an
assembler language subprogram, LINKRTN.
The two programs are link-edt ted 'together
as a single load module.
At execution
time, the assembler-language subprogram
dynamically fetches COBOL subprograms (OPH,
BILL, CRDT, TRNF, and LCK, none of which
are shown in the example) for the main
progra m using the LI NK macro instruction.
The COBOL subprograms are stored in a
private library, DYNLINK.
The parameter list passed to LINKRTN
contains three identifiers, TRANS-REC,
COM-WORD, and SWITCH, two of which
(TRANS-REC and SWITCH) are referenced by
LINKRTN, and two of which (TRANS-REC and
COM-WORD) are referenced by the COBOL
subprograms fetched.
LINKRTN passes the
same parameter list i t receives to the
COBOL subprograms fetched.
LINKRTN determines from identifier
TRANS-REC which subprograms to fetch, and
from SWITCH when to open and close the
library DYNLINK.
!!Qt~:
In st ructur ing a progra m wi t.h either
the preplanned overlay techniqUe or the
dynamic overlay technique, special
consideration must be given to the presence
of the TRANSFORM table and the class test
tables, which are members of the COBOL
object-time library (see "Appendix B:
COBOL Library Subroutines"). The TRANSFORM
table is link-edited with a COBOL program
if the TRANSFORM statement is used.
Similarly, one or more of the class test
tables is present in a COBOL load module if
a class test is performed or if the OCCURS
DEPENDING ON option is used.
For these tables, which contain no
executable code and are not branched to but
are merely referenced, the compiler
designates A-type address constants
(ADCONs) and EXTRN references, rather than
v-type address constants (VCONs).
Accordingly, the overlay structure segment
containing the table(s) must be either the
root segment or a segment that is higher in
the same leg as the segment containing the
reference (s) to the table (s) •
r
,
I
I
I
I
I
IDENTIFICATION DIVISIOL
PROGRAft-ID.
PROGMAST.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.
IBM-370.
OBJECT-COMPUTER.
181'1-370.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT FILE-Y ASSIGN TO UR-2540R-S-INFILE.
I-O-CONTROL.
DATA DIVISION.
FILE SECTION.
PD FILE-Y
RECORD CONTAINS 80 CHARACTERS
LABEL RECORD IS OMITTED.
01 TRANS- REC.
05 ACCOUNT- NU MBEE PIC 9 (1 0) •
05 TRANSACTION PIC 9(4).
05
NAME PIC X(20).
05 LOCATION PIC 1(20).
05 METER-READING PIC 9(6).
05 DA YTE PIC 9 (6) •
05
FILLER PIC X (8).
05 AMOUNT PIC 9(6).
WORKING-STORAGE SECTION.
77 COM-WORD PIC X(12}.
77 SWITCH PIC 9 VALUE ZERO.
PROCEDURE DIVISION.
t
t
,
f
1
t
I
I
t
I
I
I
J
t
J
B..
C.
t
,
•
I
OPEN INPUT FILE-Y.
READ FILE-Y AT END GO TO END-RUN.
CALL 'GETUM' USING TRANS-BEC COM-WOBD SWITCH.
t
I
J
I
I
1
f
END-RUN.
CLOSE FILE-Y ~
MOVE 2 TO SWITCH.
PERFORM c.
STOP RUN.
~
Figure 137.
J
Sample COBOL Main Program and Assembler-Language Subprogram Using Dynamic
Overlay Technique (Part 1 of 3)
Calling and Called Proqrams
343
,
r-
,
,,
I
LINKRTN
t
J
2
1
I
J
,
I
t
I
I
•I
*
*
*
*
*
*
*
*
*
*
*
START 0
PRINT NOGEN
ENTRY GETUM
THE SECOND WORD CONTAINS THE ADDRESS OF
COM-WORD, TO WHICH THIS PROGRAM DOES NOT
REFER BUT WHICH IS USED BY ROUTINES THIS
PROGRAM LATER LINKS TO.
THE THIRD WORD CONTAINS THE ADDRESS OF
SWITCH USED BY THIS PROGRAM TO CHECK THE
STATUS OF THE PRIVATE LIBRARY DYNLINK
GETUM
J
1
t
I
t
I
J
1
USING
SAVE
LR
DROP
USING
GETUM,15
(14,12)
10, 15
15
GETUM, 10
I.R
11,13
LA
1 3, SAVE AR E A
ST
13,8(11)
ST
11,4(13)
L
5,0(1)
USING PARAMLST,5
I
I
*
B
J
SAVEAREA
DS
t
I
f
I
I
t
J
I
J
,
,
t
I
OPENLIB
*
*
*
*
*
I
t
I
I
I
,
6,8 (1)
0(6),C'l'
IN1TREG
SH
CLOSLIB
OPEN
(DYNLINK)
01
O(6),C·1·
L
I NITREG
LA
2,RTNlST
3,6
TRANS ACT, 0 (2)
LA
FINDRTN
*
ERRMSG
EXIT
t
*
etc
BE
LA
BCT
HVC
WTO
L
SR
REGISTER 5 LOADED WITH ADDRESS OF TRANS-BEC
REGTER 5 IS USED AS THE BASE REGISTER TO
REFERENCE TRANS-BEC.
REGISTER 6 LOADED WITH ADDRESS OF SWITCH.
CHECK SWITCH STATUS.
IF SiITCH = 1, DYNLINK IS ALREADY OPEN;
INITIALIZE REGISTERS.
IF SWITCH> 1, DYNLINK IS NO LONGER NEEDED;
CLOSE DYNLINK.
IF SWITCH = 0 THE FIRST TIME THROUGH, OPEN
DYNLINK.
SET SWITCH SO THAT OPEN IS BYPASSED ON FUTURE
ENTRY.
INITIALIZE REGISTERS 2 AND 3 FOR LOOK-UP.
TRANSACT CONTAINS THE TRANSACTION CODE THAT
DETERMINES iHICH ROUTINE TO FFTCH.
GETRTN
I
I
I
I
I
J
1
I
I
I
I
I
I
I
I
I
t
I
I
I
I
•
I
I
I
I
I
I
I
I
PRODUCE ERROR MESSAGE IF tRANSACT CONTAINS
AN INVALID CODE.
t
t
I
SET REGISTER 15 TO ZERO.
I
PARAMETER INDICATES THAT THIS
I
PROGRAM IS PASSING A RETURN CODE IN REGISTERI
15.
I
THE RC=(15)
I
DYNAMIC OVERLAY ROUTINE
GETRTN
*
*
L
1,24(11)
LA
LINK
4,4(0,2)
E PLOC=(4) ,DCB=DYNLINK
B
I
RESTORE REGISTER 1 TO ORIGINAL STATUS.
PASS REGISTER 4 TO NAME OF ROUTINE TO BE
FETCHED.
HAVE THE CONTROL PROGRAM
FETCH THE ROUTINE POINTED TO BY
REGISTER 4 FROM PRIVATE LIBRARY DYNLINK.
EXIT
L-
Figure 137.
344
,
I
I
2,12(0,2)
3,FINDRTN
ERRMSG+28(4) ,TRANSACT
'INVALID TRANSACTION'
13,4(13)
15,15
RET UR N ( 1 4 ., 1 2) , T , RC= (' 5 )
I
I
I
I
I
I
OPENLIB
18F
ell
BE
,
J
TABLE LOOK-UP ROUT IN E
I
I
I
I
I
f
UPON ENTRY TO THIS PROGRAM, REGISTER 1 POINTS I
TO A FIXED-LENGTH PARAMETER LIST OF THREE
I
WORDS.
I
THE FIRST WORD CONTAINS THE ADDRESS OF
I
RECORD TRANS-REC.
f
I
I
I
I
I
I
-'
Sa~ple
COBOL Main Program and Assembler-Language subprogram Using Dynamic
Overlay Technique (Part 2 of 3)
r-
I
I
I
I
CLOSLIB
I
RTNLST
I
*
*
t
CLOSE (DYNLINK)
B
EXIT
*
AS THE TABLE SEARCHED BY THE TABLE LOOK-UP
I
ROUTINE, RTNLST CONTAINS A LIST OF ALL VALIDI
t
TRANSACTION CODES AND THE NAMES OF THE
ROUTINES FETCHED TO HANDLE THE TRANSACTIONS!
DC
DC
DC
DC
DC
DC
DC
DC
DC
DC
C'0100'
CL8'OPN'
C'0200'
CL8'BILL'
TRANSACTION CODE
I
ROUTINE NAME ASSOCIATED WITH ABOVE TRANSACTIONI
I
I
EQU.
AMOUNT
1
t
CLa'CRDT'
I
1
C '0400'
CLa I TRNF'
C'OSOO'
CLatLCK'
t
t
*
DDNAME=SYNLNKDD,DSORG=PO,MACRF=U)
DCB TO DEFINE PRIVATE LIBRARY REFERRED TO IN
LINK MACRO INSTRUCTION.
DSECT
DS
DS
DS
DS
DS
DS
DS
DS
DS
END
t
C '0300'
*
*
I
I
OF
*
*
TRANSREC
ACCTNUM
TRANSACT
NAME
LOCATION
METERRD
DATE
1
EQO
DeB
PARAMLST
•
DS
*
DYNLINK
CLOSE PRIVATE LIBRARY.
OCL80
CL 10
CL4
CL20
CL20
CL6
CL6
CLa
CL6
I
I
I
I
t
I
I
I
DSECT USED BY REGISTER 5 TO REFER TO TRANSREC.
THE RECORD DESCRIPTION CORRESPONDS TO t
~HAT OF TRANS-REC IN PROGMAST.
1
,
t
1
1
J
t
t
I
I
t
I
IQ1~:
Had a job or step library (requiring either a JOBLIB or STEPLIB DO statement in J
the job control for execution of the main program) been used instead of a private
I
library (which for this example requi.res a DD statement named DYNLNKDD) , responsibility)
for the opening and closing of the library would have been with the control program andl
not with LNKRTN.
I
I
The use of a private library, in conjunction with the LINK DCB parameter, reduces tol
fa minimum the amount of ________
search .______________________________
time needed to retrieve member __
modules
from a library.
.________________
.--------J1
~
Figure 131.
Sample COBOL Main Program and Assembler-Language subprogram Using Dynamic
Overlay Technique (Part 3 of ~
Calling and Called Programs
345
The loader resolves external names and
references and combines calling and called
programs into a format slli table for
execution as a single load module. For
information on invoking the loader, see
"Using the cataloged Procedures."
When the dynamic call is used, all
subprograms to be called dynamically must
have been processed by the linkage editor.
The loader may be used only to resolve
references to subprograms invoked by static
calls. otherwise, load modules of both
calling and called programs are used as
input to the loader.
There are tvo kinds
of input, primary and additional. £.rima£!
input consists of one or more separately
compiled object modules and/or load
modules. ~llditioD~l input consists of
object modules or load modules that are not
part of primary input data sets but are to
be included in the load module. The
additional input may be in the form of
{1) libraries containing object modules, or
(2) libraries containing load modules.
Addi tional input may contain either calling
or called programs or both.
If these sabroutines reside in the Link
Pack Area, their external references are
not resolved.
When the RES loader option
is specified, the loader always searches
the Link Pack Area for modules before
searching the SISLIB data set.
If the RES
compiler opt. ion is specified, subroutine
ILBONTRO controls all subroutine
intercommunication SO that unresolved
external references in the Link Pack Area
present no problem. If, however, the NORES
compiler option is specified, ILBONTRO is
346
not invoked and unresolved external
references in the Link Pack Area may
prevent successful subroutine execution.
'Therefore, in order to prevent the loader
frolt searching the Link pack Area, the
NORES loader option should be specified in
conjunction with the NORES compiler option.
This viII cause the loader to search for
,required modules in the SYSLIB data set,
bypassing the Link Pack Area search. If
COBOL subroutines that have external
references which vould need to be resolved
do not reside in the Link pack Area, either
the RES or NORES loader option is
acceptable.
(Subroutine external
references are listed in Pigure 174.)
SPECIPYING PRIMARY INPUT
The pri mary input data set is speci fied
for loader processing by the SISLIN DD
statement. The loader must always have a
primary input data set whether or not there
are calling or called programs. The SISLIN
DD statement that specifies primary input
is discussed in the section "Data Set
Requirements."
SPECIFYING ADDITIONAL INPUT
Additional input data sets are specified
by the SYSLIB DD statement. The SYSLIB DD
statement is discussed in the section "Data
Set Requirements."
Note: The overlay facility can not be used
with the loader.
Libraries are an integral part of the
operating system. Some libraries have
system-supplied names and system-supplied
data. Other libraries have system-supplied
names but may contain user-specified data.
Still other libraries have both
user-supplied names and user-supplied data.
Libraries, in general, are made up of
partitioned data sets.
Any library with a
user-supplied name and user-supplied data
is always a single partitioned data set,
which is a collection of independent sets
of sequentially organized data, called
members.
All of the members within a
partitioned da ta set ha ve the same
characteristics as that of record format.
When used to store programs, a partitioned
data set containing load modules can
contain only load modules; it cannot
contain both load modules and object
modules.
A member of a partitioned data set can
be replaced o.r deleted.
The system
actGally accomplishes this by modifying or
deleting the directory pointer to the
member. T he space occupied by the origLnal
member is not available for reUse either
until the MOVE or COpy control statement of
the IEHMOVE utility program is used or the
compress facility of the IEBCOP! utility
program is used. The space previously
occupied by the replaced or deleted member
is thus made available.
(Por further
details, see the publication Q~~
J1.:.t.ilit!~1U~· )
Each partitioned data set is headed by a
directory of entries pointing to the
members that make up the library. Each
member has a unique member name.
A
partitioned data set must reside on a
single mass storage device, but some
libraries can consist of a concatenation of
more than one partitioned data set.•
Figure 138 shows the format of a library
that is a single partitioned data set of
four members. Space for the members of
such a library and its directory is
requested in the SPACE parameter of the DD
statement when the library is created.
Additional members can be added to a
library at a later time.
Additional space
cannot be allocated for the directory,
however.
Directory space is allocated for
the entire library when the library is
created.
If the original allocation was
not large enough, the IEHMOVE utility
program can be used to expand the directory
size. If the directory is filled, no
addi tio.nal members can be added to the
library. Following is an example of a DD
statement that might be used to create a
lib.rary:
IIDD1
II
1/
1/
/1
DO DSNAME=FILELIB (FILE1) ,
DISP=(NEW,CATLG),
UNIT= 2314,
SPACE=(TRK, (40,10,3»,
VOLUME=SER=111111
This statement specifies that a library
nailed FILELIB is to be created and
cataloged in this job step.
Its first
lIember is named FILE1. Initial space
allocated for data sets is to be 40 tracks,
with addit ional allocation to be made, as
necessary, in units of 10 tracks. In
addition, space for three 256-byte records
is to be allocated for the directory. The
volume serial number is 111111.
x
KINDS OF LIBRARIES
A programmer can use libraries already
provided by the system, or he can create
libraries of his own.
In addition, certain
library names recognized by the system may
be assigned to partitioned data sets
provided by the system. by the programmer,
or both.
These libraries and their uses
are discussed in the following paragraphs.
SISTEK LIBRARIES USED IN COBOL APPLICATIONS
The link library is a partitioned data
set. that contains load modules to be
executed.
Unless non-resident control
program routines and IBM-supplied
processing progra ms specified otherwise, a
load module name in an EXEC statement is to
be fetched from the link library.
Operating system programs, such as the
COBOL compiler, are usually contained in
this libra ry.
X
X
X
The link library can be used by the
programmer to store executable load modules
at link-edit time.
However. any attempt to
Libra.ries
347
r------------T-------------T-------------T-------------T--------------,
1 Entry for I Entry for ) Entry for I
l Entry for
Directory
{
__
1
~-~=~~=~-~---l--~=~~=~-~---l--~=~~::-=---l--~:~~:~-~--_l ~~~=_~------~
1
I
Member C
~
INote
I
21
r----------------------------------------T-------------T-------i------~
J
~
)
I
Note 2
Member B
I
I
Member K
I
I
~----------------------------------------~-------------~--------------~
1
1
I
Library
Members
Member K
I
r--------------------------------T------------------------------------~
J
I
]
I
Member K
Member A
I
I
t------------T-------------------~------------------------------------~
1
I Member A
)
I
J
Note 3
I
r------------~--------------------------------------------------------~
)
I
IL_______,______________________________________________________________
Note 3
JI
Notes:
~pace available in directory.
2.
3.
Figure 138.
Space available from deleted members. Space can be recovered
through utility programs IEHMOVE and IEBCOPY.
Space available in library.
Format of a Library
write in this library will cause a message
to be issued to the operator if the library
is write-protected or if its expiration or
retention date has not yet occurred.
Under
these conditions, no data may be written
unless authorized.
The link library is identified in a job
control statement as SYS1.LINKLIB, or by
default as specified by the system link
list.
The procedure library is a partitioned
data set whose members are the cataloged
procedures at an installation. They may
include the cataloged procedures provided
by I BM.
Procedures writ ten at the
installation can be added to the procedure
library with the IEBUPDTE utility program
(see "Using the Cataloged Procedures").
The system name for the procedure
library is SYS1.PROCLIB.
348
~rt
Library
The sort library is a partitioned data
set that contains load modules from which
the sort program is produced.
It may be identified. by the name
SYS1.S0RTLIB (see "Using the sort/Merge
Featllre").
The COBOL subroutin'e library is a
partitioned data set that contains the
COBOL library subroutines in load module
form. These subroutines may be included in
a COBOL load module or dynamically loaded
to perform such functions as data
conversion and dOUble precision arithmetic.
The COBOL programmer does not refer
directly to these subroutines; in most
cases calling sequences to them are
generated at compile time from certain
Procedure Division statements, and they are
incorporated into the load module at
link-edit time or loaded at program
initialization time.
A listing of
subroutine names, functions, entry points,
and size is given in Appendix B; also noted
are those subroutines explicitly called by
the COBOL program.
Availability at Execution-Time: Usually,
COBOL library subroutines needed in the
user's program will be automatically
link-edited into the load module, and the
user need not concern himself with their
availability.
However, certain situations
will require that subroutines not normally
linked be available during program
execution. To satisfy this requirement,
the user can either make sure that the
COBOL library is available to the system
loader at execution time, or specifically
include the subroutines in his load
module--by using an INCLUDE SYSLIB
(subroutine names) in the link edit SYSLIN
data stream.
LIBRARIES CREATED BY THE USER
A programmer can create members of the
link library, the procedure library, and
the job library.
fie can also create
partitioned data sets for use in the copy
library, the automatic call library, and
the job library.
In addition, he can
create partitioned data sets to be used as
libraries for additional input to the
linkage editor, and he can create libraries
whose members are source program entries.
The situations, and the subroutines
required, are as follows:
1.
STATE compiler option was specified.
Subroutine ILBOSTNO will be required
if an abend occurs.
2.
TEST compiler option was specified.
ILBOCOMO will be required.
3.
COUNT compiler option was specified.
ILBOTC2 and ILBOTC3 will be required.
4.
SYMDMP compiler option was specified.
ILBOD01, ILBOD10 through ILBOD14,
and ILBOD20 through ILBOD26 will be
required.
5.
COUNT, FLOW, STATE, or SYMDMP compiler
option was specified.
If an informative
message needs to be issued, ILBODBEO
will be required.
6.
Execution-time options (PARM field on
EXEC statement) will be passed.
ILBOPRMO will be required.
In the event the DYNAMIC or RESIDENT
compiler option was specified, then all
subroutines will be loaded (and required
to be available) at execution time.
The automatic call library, defined by
the SYSLIB DD statement in the link-edit
job step, contains load modules or object
modules that may be used as secondary input
to the linkage editor.
If the library
contains object modules, it may also
contain control statements.
External
symbols that are undefined after all
primary input has been processed cause the
automatic library call mechanism to search
the automatic call library for modules that
will resolve the references, unless the
NeAL option is specified. The COBOL
subroutine library must be specified for
the automatic call library if any of the
subroutines will be needed to resolve
ext.ernal references.
Other partitioned
data sets may be concatenated as shown in
the fo11owing example:
IISYSLIB
DD DSNAME=SYS1.COBLIB,DISP=SffR
//
DD DSNAME=MYLIB,DISP=SHR
In this case, both the COBOL subroutine
library and the partitioned data set named
KILIB are available to the automatic
library ca 11.
The system name for the COBOL subroutine
library may be SYS1.COBLIB.
Libraries
349
-----------------------------------------------,I
r-
IIICATALOG
III
1//SYSUT2
III
III
III
III
IIISYSPRINT
IIISYSIN
•. I
'·1
I
I
t
I
'.1
11*
JOB
EXEC
DD
user information
PGM=IEBUPDTE,PARK=(NEW)
DSNAKE=COPYLIB,UNIT=J330,
DISP=(NEW,KEEP),
VOLUME=SER=111111,
SPACE~(TRK,(15,10,2),
DCB=(LRECL=80,BLKSIZE=80,RECFM=F)
SYSOUT= A
I
,
X
I
,
I
X
X
X
I
I
f
I
I
I
I
I
I
I
I
DO
DO
*
ADD
NAME=CFI LEA, L£VEL=OO, SOURCE=O, LIST=ALL
NUMBER NEW1=10,INCR=5
BLOCK CONTAINS 13 RECORDS
RECORD CONTAINS 120 CHARACTERS
LABEL RECORDS ARE STANDARD
DATA RECORD IS FILE-OUT.
ENDUP
"-
Fiqure 139.
r--
IIIU PDATE
III
IIISYSUT1
Entering Source Statements into the COpy Library
JOB
EXEC
DD
III
til
III
t/ISYSUT2
III
III
II/SYSPRINT
I/ISYSIN
1./
,
I. /
DD
user information
PGM=IEBUPDTE,PARK=(MOD)
DSNAME=COPYLIB,UNIT=3340,
DISP=(OLD,KEEP) ,
VOLUME=SER=111111,
DCB=(RECFM=F,BLKSIZE=80)
DSNAME=COPYLIB,UNIT=3340,
DISP=(OLD,KEEP) ,
VOLUME=SER=111111
SYSOUT=A
DD
DD
*
CHANGE NAME=CFILEA,LEVEL=Ol,SOURCE=O,LISf=ALL
BLOCK CONTAINS 20 RECORDS
ENDUP
,
'------,
x
X
X
I
I
I
J
I
X
X
X
00000010
t
I
J
I
I
I
,t
11*
I
"-
.J
Figure 140.
Updating Source Statements in a COpy Library
!2!~:
If the partitioned data set named in
the SYSLIB DD statement contains load
modules, any data set concatenated with it
must also be a load module partitioned data
set. If the first contains object modules,
the others must also contain object
modules.
The linkage editor LIBRARY control
statement has the effect of concatenating
any specified member names with the
automatic call library.
programmer. The programmer can inclUde
these statements or programs into a program
at compile time.
He calls them with the
COBOL COpy statement or BASIS card.
To enter or update source statements in
the copy library, a utility program must be
used. IEBUPDTE is the IBM-supplied utility
program used to catalog procedures. A full
discussion of the sta tements used in this
program may be found in the publication
Q~L!LUti!.ilie2·
!1i!ximulLBl2.£LSiz~L
The maximum block size for the copy
library is restricted to 16K.
~ltiEl~_Lib£arie2:
The COBOL copy library is a user-created
library consisting of statements or entire
COBOL programs frequently used by the
350
If more than one copy
library is being used. the COpy statement
must include the phrase INIOF library-name,
where library~name is the ddname
identifying the particular partitioned data
set to be copied from.
(If this qualifying
phrase is omitted, the default ddname
becomes SYSLIB or its alternate.)
!!l!dating sou££~~:t~!!ts: Figure 140
illustrates the method to update source
statements in a copy library member
inserted in the previous example.
la!e&in~~~g~ate!~nts:
SISUT1 and SYSUT2 describe the data
sets. Note that changes may be made on the
same data set (identified on the DSNAME
parameter). The utility statement CHANGE
indicates that the new entry of CFILEA
replaces the old entry.
Alternatively, the
UPDATE IN PLACE parameter of the change
statement could have been used to avoid
moving the entire member, (CILEA, to the
1irst available area in the file.
The
sequence number of the altered statement
must be supplied. This number, 00000010,
is indicated in columns 13 through 80 of
the replacement source statement.
Note
that, although in the insert example (see
Figure 139 -- NU~BER statement) the number
was coded as 10 without leading zeros, the
program assigns an 8-characterfield to a
sequence number and pads with leading zeros
if necessary. When updating a sequence
number in a library, these leading zeros
must be included.
Figure 139
illustrates the method to insert source
statements into a copy library member.
The . / ADD statement is a utility
statement that copies CFItEA into the
library called COPYLIB. CFILEA describes
an FD entry. The NUMBER statement assigns
a sequential numbering system to the
statements in the library. The first
statement is assigned number 000010 and
each succeeding statement is incremented by
5.
The entries following the utility
statements are the actual source statements
to be stored. The ENDUP statement signals
the end of the entries to be inserted.
The same procedure can be used to store
entire source programs.
Libraries
350.1
At compile time, COPYLIB is identified
on a DD statement; for example:
IISYSLIB
II
II
DD
DSNAME=COPYLIB,
VOLUME=SER=111111,
DISP=SHR,UNIT=2314
x
The statements included in the DOWORK
procedure viII immediately follow the
paragraph-name, replacing the words COpy
DOWORK.
X
1.
The SUPPRESS option of the COpy
statement viII be ignored if LISTER or
FIPS is requested.
2.
Results may be unpredictable if a
CURRENCY SIGN IS = is specified (only
alloved with LANGLVL(l)
and a PICTURE
character string is part of
pseudo-text and contains a floating
currency sign.
R~UievilHL~.Qll£~~tatements:
Members of
the cataloged library can be retrieved
using the COpy statement or BASIS card.
3.
first line of the COpy statement
itself.
A copy statement itself can
never be a debugging line; if it
contains a D and WITH DEBUGGING mode
is not specified, the COpy statement
will nevertheless be processed.
PD FILEA COpy CFILEA
4.
The compiler translates this instruction to
read:
FDFILE A
BLOCK CONTAINS 2 ORE CORDS
RECORD CONTAINS 120 CHARACTERS
LABEL RECORDS ARE STANDARD
DATA RECORD IS FILE-OUT.
Note that CFILE! itself does not appear in
the statement. CEILEA is a name
ide tifying the entries.
It acts as a
header record but is not itself retrieved.
The compiler source listing, however, will
print out the COpy statement as the
programmer wrote it.
The COpy statement permits the
programmer to include previously stored
source statements into any portion of the
program.
Assume a procedure named DOWORK vas
stored with the following statements:
•1
,.1
•1
ADD
NAME=DOWORK,LEVEL=OO,
SOUR CE=O, LIST=ALL
NUMBER
SEQ1=400,INCR=10
COMPUTE QTY-ON-HAND =
TOTAL-USED-NUftBER-ON-HAND.
MOVE-QTY-ON-HAND TO PRINT-AREA.
BNDUP
To retrieve the stored member, nOWORK, the
programmer writes:
paragraph-name.
In order for the text copied to have a
o inserted in column 7 (debugging line
indicator), the D must appear on the
The COpy statement permits the
progra mmer to include stored source
statements in any of the four divisions.
If the programmer wishes to retrieve the
member, ClILEA, stored in the previous
examples, he writes the statement:
No more than 150 COPY-REPLACING pairs
may be specified in a source program.
If this limit is exceeded, message
IKFI20I is issued by the compiler,
and COPY statements over the limit
are ignored.
Frequently used source programs, such as
a payroll program, can be inserted into the
copy library. The BASIS card brings in an
entire source program at compile time.
Calling in a program eliminates the need
for the programmer to handle a program each
time he wants to compile it. The
programmer may, however, alter any
statement in the source program by
referr ing to its COBOL sequence number vi th
an INSERT or DELETE statement. The INSERT
statement viII add new source statements
after the sequence number indicated.
The
DELETE statement viII eliminate the
statements indicated by the sequence
numbers.
The programmer may delete a
single statement with one sequence number •
or he may delete more than one statement,
separating by a hyphen -the first and last
sequence numbers to be deleted.
Note: The COBOL sequence number is the
6-diqit number that the programmer aSSigns
in columns 1 through 6 of the source cards •
This sequence number has nothing to do with
the sequence numbers assigned in simulated
columns 73 through 80 by the IEBUPDTE
utility program. The sequence numbers
COPY nOWORK.
Libraries
351
.--
----"
IEBUPDTEI
Sequence,
I COBOL
I Sequence
1M y.:ID. be.£2_
.ID!.!!!h~£2_J
,000730
J000735
,000740 TAX-PAYR.
1000750
,000760 PAY-WRITE.
1000770
I
I
IF ANNUAL-PAY GREATER THAN 15,000 GO TO PAY-WRITE.
000001051
IF ANNUAL-PAY GREATER THAN 15,000 - BASE-PAY GO TO LAST-TAX. 000001101
000001151
COMPUTE TAX-PAY = BASE-PAY * .025
000001201
MOVE TAX-PAY TO OUTPUT-TAX.
000001251
MOVE BASE-PAr TO OUTPUT-BASE.
00000130,
ADD BASE-PAY TO ANNUAL-PAY.
,000850
STOP RUN.
,
I
I
I
000002401
L-
Figure 141.
COBOL Statements to Deduct Old Age Tax
--------------------------------"f
.-I
I
I
I
J
IBASIS PAYROLL
ID~LETE
I
I
I
I
000730-000740
1000730
1000735
1000740 TAX-PAYR.
Figure 142.
IF ANNUAL-PAY GREATER THAN 17800 GO TO PAY-WRITE.
IF ANNUAL-PAY GREATER THAN 17800 - BASE-PAY GO TO LAST-TAX.
COMPUTE TAX-PAY -= BASE-PAY * .044.
•
____ - J
Programmer Changes to Source Program
assig~ed by IEBUPDTE are used to apdate
source statements in the copy library.
Changes made using these numbers are
intended to be permanent changes. The
COBOL sequence numbers are used to update
COBOL source statements at compile time.
Such changes are in effect for the one run
only.
Assume that a company payroll program is
kept as a source program in the copy
library. The name of the progra m is
,PAYBOLL. During a particular year, old age
tax is taken out at a rate of two and a
half percent each week for all personnel
until earnings exceed $15,000. The coding
to accomplish this is sh own in Figure 141.
NoW, ho:wever, due to a change in -the old
age tax laws, tax is to be taken out until
earnings exceed $17,800 and a new
percentage is to be placed. The programme~
cab code these changes as shown in Figure
142.
The altered program viII contain the
coding shown in Figure 143.
Note that changes lIaae through use of
the INSERT and DELETE statements remain in
effect for the one run only.
Note: If both the COpy statement and the
BASIS card are used, the library containing
the member specified in the BASIS card must
be defined first. The COpy libraries
concatenated with the B'ASIS library may be
d.efined and re.ferenced in any order (see
"Appendix I: _Checklist for Job Control
~r------------------------------------------------------------------------------------------,
1000730
1000735
1000740 TAX-PAYR ..
1000750
1000760 PAY-WRITE.
1000770
I
I
I
t000850
IF ANNUAL-PAY GREATER THAN 17800 GO TO PAY-WRITE.
IF ANNUAL-PAY GREATER THAN 17800 - BASE-PAY GO TO LAST-TAX.
COMPUTE TAX-PAY = BASE-PAY * .044.
~OVE TAX-PAY TO OUTPUT-TAX.
MOVE BASE-PAY TO OUTPUT-BASE.
ADD BASE-PAY TO ANNUAL-PAY.
STOP RUN.
L-
Figure 143.
352
I
I
I
I
t
I
I
I
I
I
.I
Changed COBOL Statements to Source COpy Library Statements
procedures"). For a discussion of special
considerations when using BASIS with'the
BATCH option. see "Batch Compilation."
A library of load modules can be created
by use of the SYSLMOD DO statement in the
linkage editor job step, as discussed in
"Job ,Library."
The job library consists of one or more
partitioned da ta sets that contain load
modules to be executed. It is specified by
the JOBLIB DD statement that must precede
the EXEC statement of the first step of a
job.
Partitioned data sets assi9n~dto the
job library are concatenated with the link
library so that any load module is obtained
automatically when its name appears in the
PGM= parameter of the EXEC statement. The
following statements illustrate how three
cataloged partitioned data sets can be
assigned to the job library:
Use of the COBOL Library Management
Feature makes it possible for all programs
in the 'same or different regions/partitions
to share one copy of the COBOL library
subroutines. That is. the most economical
use of main storage is made when the most
frequently used COBOL library subroutines
are placed in the OS/VS2 link pack area
(LPA), or the OS/VS1 resident reenterable
routine (RRR) area, rather than in each
region/partition. To make the most
effective use of the Library Management
Feature, and to use the IBM cataloged
procedures whether or not Library
Management is needed, the user should
concatenate the COBOL subroutine library
with the system link library, or specify it
to be used as such a library in the
appropriate system parameter library
member.
//l1YJOB
//JOBLIB
//
//
//STEPl
JOB
DD DSNAME=MYLIB1.DISP=(OLD.PASS)
DD DSNAM E=MYL IB2, DISP= (OLD. PASS)
DD DSNAME=MYLIB3,DISP=(OLD,PASS)
EXEC
//STEP2
EXEC
These statements specify that the job
library containing th.e data sets MYLIB1,
MYLIB2. and MYLIB3 is to be concatenated
with the link library.
When a load module
is named in an EXEC statement in any step
of the job. the directories of the job
library viII be searched for the name.
When a job library is specified for a job.
the link library is searched for a named
load module only when the module is not
found in the job library.
Partitioned data sets'used in the job
library can be created by specifying the
partitioned data ,et name and the member
name in the SYSLMOD DD statement when each
member is processed by the linkage editor.
!~litio~l
11UUlLt-2_ the LinJi~Mll2!::
Libraries of object modules (with or
without linkage editor control statements)
and libraries of load modules can be used
as additional input to the linkage editor.
Members are specified by use of the INCLUDE
and LIBRARY linkage editor control
statements.
A library of obj~ct modules and control
statements can be created by use of the
IEBUPDTE utility program.
The user may request the COBOL Library
Management Feature at compile time, via the
RESIDENT option (see the section "Options
for the Compiler" in the chapter entitled
"Job Control Procedures").
CONCATENATING THE SUBROUTINE LIBRARY
TO concatenate the subroutine library
wi th the link libra ry, the user execu tes
the IEBUPDTE utility program to add a
member named LNKLSTOO to SYS1.PARML1B,
specifying the library desired (that is,
either the entire COBOL subroutine library
or a pri va te library containing
user ....selected COBOL library subroutines).
Note that the library containing the
subroutines must be cataloged.
An installation that is planning to use
the Library Management Feature will find it
convenient to include frequently used COBOL
library subroutines in the 05/VS2 LPA or
the OS/VS1 RRR area. Infrequently used
subroutines are then brought into the
region/partition as required. To add COBOL
subroutines to the RRR area. the user
invokes the IEBUPDTE utility program to add
a member named IEAIGGXX (see Note 2 in
Figure 143) to SYS1.PARMLIB, specifying all
names and aliases for the COBOL library
subroutines to be included. Then, at an
initial program load (1PL) time, the
operator ident ifies the link list to the
Libraries
35.3
·. system, which subsequently places the
identified COBOL subroutines in main
storage in the RRR area.
Figure 144 illustrates how an
installation can accomplish both these
functions in one operation. The encircled
letters in the figure refer to the JCL
suggested A to concatenate the COBOL
subroutine library (SYS1.COBLIB) with the
system link library (SYS1.LINKLIm, and
then B to place the user list of desired
COBOL library subroutines and their aliases
to the RRR.
(For further information, see
the publication ~LX.L£QBO.L£Q!!!.£ilg: and
l£!brarY-l..nstalla ti2n~f~~!lce Materi~!.)
1.
If the user does not wish to place any
COBOL subroutines in the RRR area, he
need not execute the portion of the
IEBUPDTE utility program that adds
IEAIGGXX to SYS1.PARML1B shown above.
He may still make use of the Library
Management Feature.
However, all
required library subroutines will be
loaded into his own region/partition
when they are needed by one or more
programs, and deleted when they are no
longer needed.
Thus, not all library
subroutines needed by all programs in
•f//CATLG
,./
1.. /
ADD
,//SYSPBINT
II/SYSUT 1
II/SYSUT2
I/ISYSIN
,
2.
If one or more programs in a given
region/partition request the COBOL
Library Management Feature, then the
main program and all subprograms in
that region/partition must use it.
Otherwise, the multiple copies of
COBOL library subroutines resident at
one time may cause unpredictable
resul ts.
A programmer can create or change a
partitioned data set in one of three ways:
(1) through the use of DO statements,
(2) through the use of utility programs,
and (3) through the use of certain linkage
editor control statements.
,
JOB
EXEC
DD
DD
DD
DD
REPL
'1/
the region need be resident a t the
same time. In this case, however, the
user must supply a job control card at
execution time pointing to the COBOL
subroutine library or to his own
private library of COBOL subroutines.
(For a discussion of the various COBOL
library subroutines available to the
programmer, see "Appendix B: COBOL
Library Subroutines. tt)
user information
PGM=IEBDPDTE,PARM=MOD
SYSOUT=A
DSN=SYS1.PARMLIB,DISP=SHR
DSN=SYS1.PARMLIB,DISP=SHR
I
I
*NAME=LNKLSTOO,LIST=ALL
I
J
I
I
I
SYS1.LINKL1B,SYS1.COBLIB
NAME=IEAIGG01,LIST=ALL
SYS1962(562Bl,NAME1,ALIAS1, •••
SYS1.L1NKLIB,NAME,ALIAS
J
I
I
1.H21~
,
,
I
t 1.
t
I
J
'.1
1/*
ENDUP
~
I--
J
I
•12.
I
I
I
I
I
I
,3.
J
I
I
The name used on the card after the REPL statement must identify the data set
(SYS1.COBLIB) to be concatenated with the system link library, and is selected by
the installation.
(Note that this data set must be cataloged.)
I
I
I
I
The last two digits of the member-name specified in the ADD statement can vary, butt
the digit.s specified here must also be specified in the RAM·: parameter used at IPL I
time.
For example, if IEAIGG02 were specified, 'RAM=02' would be required at 1PL I
time. For OS/VS2 Release 1 * modify the IEA1GGOO member of SYS 1. PARMLIB as
I
explained in OSL!S2-I1!itializati21L21HL1.!!ning_2.Yide, GC28-0681.
For OS/VS2 Releasel
2 and later# use IEALPOO instead of 1EAIGGOO.
I
f
The names and aliases of the COBOL library subroutine members to be made resident 1
must be specified by the installation in the ADD statement. The system searches
J
the last name first; in this case# ALIASl is searched last. The user should,
I
therefore, specify the most frequently used name last.
_ _ _ _ _ _ JI
1.-
Figure 144.
354
I
I
Concatenating the Subroutine Library
The DD statement can be used to create
libraries as is discussed at the beginning
of this chapter.
In addition, DD
statements can be used to add members to
existing libraries, including the link
library, and to retrieve members of
existing libraries.
Utility programs can be used to create
libraries such as those used in the copy
library or as secondary input to the
linkage editor. In addition, utility
programs can be used to move, copy, and
replace members of an existing library; to
add, delete, and renumber the records
within an existing library; and to assign
sequence numbers to the records of a new
library.
Linkage editor control sta tements can be
used to make changes to members of a
library of load modules. The name of a
member can be changed or additional names
can be specified.
Additional entry points
can be identified, existing entry points
can be deleted, and portions of a load
module can be deleted or replaced.
For
further information, see the publication
Q~L1~1in~~g_~~iiQ£_~nd LQ~~g~.
Libraries
355
A cataloged procedure is a set of job
control statements placed in a partitioned
data set called the procedure library
(SYS1.PROCLIB) _ It can be retrieved from
the library by using its member name in an
EXEC sta teme nt of a job step in the input
stream. Frequently used procedures, such
as those used for compiling and linkage
editing, can be cataloged to simplify their
subsequent use.
A cataloged procedure can contain
statements for the processing of an entire
job, or it can contain statements to
process one or more steps of a job, with
the remaining steps defined by job control
statements in the input stream.
A job can
use several cataloged procedures, each
processing one or more of the job steps. A
job can also call for execution of the same
cataloged procedure in more than one job
step.
This chapter describes the following:
proc~dure
COBUC to process the job step
STEPQ.
A job step that calls for execution of a
cataloged procedure can also contain DD
statements that are applicable to the job
steps of the cataloged procedure. A job
that calls for execution of a cataloged
procedure may. in other steps, call for
execution of other cataloged procedures,
call for other executions of the same
cataloged procedure. or call directly for
execution of load modules.
The following
example shows a job control procedure that
calls both cataloged procedures and load
modules.
//JOBl
//STEPA
lICOB.SYSIN
JOB
EXEC
DD
CQBUC
*
(source mod ule)
1*
I/STEPl.
EXEC
PG!!=IEWL
• How to call cataloged procedures
• The types of cataloged procedures,
including those supplied by IBM for use
with COBOL source programs
(DD statements for the linkage editor)
• How to add procedures to the procedure
library
• How to modify existing procedures for
the current job step only
//STEPE
EXEC
PGM=*.STEPL.SYSLMOD
• How to override and add to cataloged
procedure~
(DD statements for user-defined files)
• How to use the DDNAME parameter in
ca ta loged proced ures
A cataloged procedure is called by a job
that appears in the input stream. The job
must consist of a JOB statement and an EXEC
statement that specifies the cataloged
procedure name in the positional parameter
(either procnalle or PROC=procname).
For
example:
The IBM-supplied cataloged procedure
COBUC for compilation is used to process
STEPA.
The COB.SYSIN DD statement is
required to define the input to the
compiler. The remaining statements in the
procedure refer to execution of the linkage
editor and the subsequent load module.
//STEPQ EXEC cosue
//STEPQEXEC PROC=COBUC
Either of these EXEC sta tements could be
used to call the IBM-supplied cataloged
356.
Data sets produced during execution of a
ca taloged procedure can be used in
subsequent job steps. They can also be
called as follows:
//jobnaae
JOB 1234,J.SltITH
/ISTEPA
EXEC PROCED
//PROC1.SYSIN DD *
2.
A DD statement with JOBtIB in the
name field
3.
A DO statement wi th an
operand field
4.
A DD statement with DAT.A in the
operand field
5.
The delimiter statement
(source module)
1*
Ilstepname
EXEC PGM=*.STEPA.PROC2.SYSLMOD
*
in the
(DD statements for user-defined files)
The cataloged procedure PROCED is
composed of tvo job steps, PRoel and PROC2,
that compile and linkage edit the source
module.
The programmer can write his own
procedures" and catalog them, o.r he can use
the five COBOL cataloged procedures
provided by IBM.
PROGRAMMER-WRITTEN CATALOGED PROCEDURES
The programmer can write cataloged
procedures, consisting of EXEC and DD
statements, vhich incorporate job control
proced ures he uses frequen tl y. For
example, the programmer may wish to catalog
an EXEC statement and the associated DD
statements for a job step that ,specifies
execution of a program. In this way, the
DO statements need not be specified each
time the program is executed.
In writing a procedur,e for cataloging,
the programmer must follow these rules:
• Another ca taloged procedure cannot be
referred to, i.e., only the
,
PGM=proqname form in an EXEC statement
can be used.
Note, however, that a cataloged
procedure may contain a DD statement
that refers to a cataloged data set.
• SYSABEND or SYSU DUMP DD statements
should not be cataloged because they
cannot be overridden.
• The .following statements cannot be used
in a cataloged procedure:
1.
The JOB statement
A procedure can be tested before it is
placed in the procedure library by
converting it into an in-stream procedure
and executing it any number of times during
a job. For further information about
in-stream procedures. refer to the section
"Testing a procedure as an In-Stream
Procedure".
The IEBUPDTE utility program is used to
add procedures to the procedure library. A
description of the use of this program is
given in the publication Q~L!~_utiliti~.
In Figure 145, two procedures are added
to the procedure library (SYS1.PROCLIB).
All control statements are in the input
stream.
The first procedure is for a COBOL
compilation. Mass storage volumes are
specified for the four utility data sets,
and 100 tracks are allocated for each
utility data set. This cataloged procedure
is named COBD!.
The second procedure is also for a COBOL
compilation. Unlabeled tape volumes are
specified for three utility data sets; for
the fourth, SISUT1, a mass storage device
must be specified. This cataloged
procedure is named COBTP.
Job control statements: the EXEC card
specifies that the IEBUPDTE program is to
be executed, and PARM=NEW is used because
all data is read from one source, i.e., the
input stream.
utility statements: the ADD statement
specifies the member name of the procedure,
the level modification ~O, first run} and
the source of the modification (0,
user-supplied) • The NUMBER statement
specif~es the sequence numbers for records
in the member. The first record of the
cataloged procedure is numbered 00000010,
and subsequent records are incremented by
tens.
Using the Cataloged Procedures
357
,.._--I Job
,Control
• Language
I Sta tements
I
I
IUtility
IStatements
IIADPROC
IISTEP1
JOB
EXEC
IISYSPRINT "DD
DD
DD
IIS1SUT2
IISYSIN
1234,J.DUBOB
PGM=IEBUPDTE,PARM=NEW
SYSOUT=A
DSNAME=SYS 1. PROCLIB,DISP=OLD
DATA
,
·1
.1
ADD
NUMBER
NAME=COBDA, LEVEL= 00. SQURCE=O
NEW1=00000010,INCR=00000010
J
IICOB
IISYSUT1
IISYSUT2
IISYSUT3
IISYSUT4
EXEC
PG8=IKFCBLOO
UNIT=SYSDA,SPACE= (TRK, (100,10»
UNIT=SYSDA,SPACE= (TRK, (100,10)
UNIT=SYSDA,SPACE=(TRK,(100,10»
UNIT=S1SDA,SPACE= (TRK. (100,10»
I
I
I First
JProcedure
•I
I
fUtility
1Sta tements
t
,
DD
DO
DD
DO
IISYSPRINT DO
IISYSPUNCH DO
.1
·1
ADD
NUMBER
EXEC
DD
DO
IISYSUT2
DD
IISYSUT3
DO
IISYSUT4
IISYSPRINT DO
IISYSPUNCH DD
IICOB
IISYSUT1
I
ISecond
I Procedure
I
I
I
I
,Delimiter
,Statements
L-
.1
SYSOUT=!
SYSQUT=B
NAME=COBTP,LEVEL=OO,SOURCE=O
NEll l= 10, I NCR= 10
PGM=IKFCBLOO
UNIT=S1SDA,SPACE=(TRK, (100,10»
UN1T=2400, LABEL= (, NL)
UNIT=2400,LABEL=(,N~
UNIT=2400,LABEL~(,N~
S1SOUT=A
SYSOUT=B
ENDUP
1*
.I
Figure 145.
Example of Adding Procedures to the Procedure Library
Note that leading zeros in the NUMBER
statement are not necessary, as indicated
in the example for the COBTP procedure.
IBM-SUPPLIED CATALOGED PROCEDURES
IBM distributes cataloged procedures
with the program product, which can be
incorporated when the system is generated.
Five of the procedures are for use with
co BO L prog ra ms.
1.
COBUC provides for compilation.
2.
COBUCL provides compilation and
linkage editing.
3.
COBULG provides linkage editing and
execution.
4.
COBUCLG provides for compilation,
linkage editing, and execution.
5.
COBUCG provides for compilation and
loading.
358
These procedures may be used with any of
the job schedulers released as part of the
IBM operating system. When parameters
required by a particular scheduler are
encountered by another scheduler that does
not require those parameters, either they
are ignored or alternative parameters are
substi tuted automa tically.
The five cataloged procedures are shown
in Fig ures 146 through 150.
(Space
allocations in these procedures are in
terms of record lengths on the 2314 disk
storage de vice. ) Note tha t when DSN AM E=&&
is used in a DD statement the specified
data set is given a unique name by the
operating system. and it is assumed to be a
temporary data set that will be deleted
when the job is completed. If the data set
is to be kept, the DD statement can he
overridden with a permanent data set name,
and the appropriate parameters can be
specified.
!!.Q!&: If the compiler options are not
explicitly supplied with the procedure,
default options established at the
installation apply. The programmer can
override these default options by using an
EXEC statement that includes the desired
options (see "Overriding and Adding to
EXECStatements" and "Overriding Cataloged
Procedures Using Symbolic Parameters").
Procedure names begin with the
abbreviated name of the processor program#
which, in the case of the COBOL procedures,
is COB.
The processor's abbreviated name is
followed by the processor's level indica tor
(U) and then by C (compile), L (linkage
edit), G (go -- i.e., execute), or
combinations of them.
Hence, procedure
COBUC is a single-step procedure that
compiles a program using the COBOL
processor; COBUCLG is a 3-step procedure
wherein the first step compiles a program
using COBOL, the second step link-edits the
output of the first step, and the third
step executes the output of the linkage
editor.
Data Set Names in
Procedur~§
When DSNAME=&&name is used in a DD
statement, the specified data set is given
a unique name by the scheduler, and it is
assumed to be a temporary data set that
will be deleted when the job terminates.
If the data set is to be retained, the DD
statement must be overridden with a
permanent data set name and appropriate
DISP parameters.
The eOBUC procedure is a single-step
procedure to execute the COBOL compiler.
It produces a punched object deck.
Figure
145 shows the statements that make up the
COBUC cataloged procedure.
The following DD statement must be
supplied in the input stream:
IICOB.SYSIN DD
*
(or appropriate
defining an
input data set)
~arameters
optionally, the delimiter statement (/*)
may follow the source module.
In a cataloged procedure, the step name
is the same as the abbreviated processor
name (LKED).
The step that executes a
compiled and link-edited program is named
GO.
For example, in the procedure named
COBUCLG, the first step is named COB, the
second step is named tKED, and the third
,step is named GO.
The COBUCL procedure is a two-step
procedure to compile and link-edit using
the COBOL compiler.
Figure 146 shows the
statements that make up the cataloged
procedure.
The COB job step produces an object
module that is input to the linkage editor.
Other object modules may be added as
illustrated in Example 5 under "Using the
DDNAME Parameter."
The tvo unit names used in IBM-supplied
cataloged procedures are as follows:
SYSSQ
any magnetic tape or mass
storage device
SYSDA
any mass storage device
The following DD statement, indicating
the location of the source module, must be
supplied in the input stream:
IICOB.SYSIN DD
A pool of units must be assigned to
these unit names during the system
generation procedure. For example, only
2314 Disk storage Drives might be assigned
to the SYSSQ name.
Thei again, both 2400
Magnetic Tape units and 2314 Disk storage
Drives might be assigned to the SYSSQ name.
Once a pool of devices is assigned to these
classes, device selection is done by the
Job Scheduler.
*
(or appropriate
parameters)
The COBULG cataloged procedure is a
tva-step procedure to link-edit and execute
the output of a COBOL compilation. Figure
148 shows the statements that make up the
procedure.
using the Cataloged Procedures
359
The following DD statement indicating
the location of the object module must be
supplied in the input stream:
statement must also be supplied in the
input stream.
IIGO.SYSIN
IILKED.SYSIN DD *
If the COBOL program refers to SYSIN in
the execution step, the following 00
.-
IIICOB
DO *
(or appropriate
parameters)
(or appropriate
parameters)
If the COBOL program refers to other
data sets in the execution step such as
user-defined files, DD statements that
define these da ta sets must also be
provided.
I/ISYSUT4
EXEC PGM=IKFCBLOO,PARM='DECK,NOLOAD,SUPMAP',REGION=128K
DO SYSOOT=A
DO SYSQUT=B
DD UNIT=SYSDA,SPACE=(460,(100,100»
DD UNIT=5YSDA,SPACE=(460,{100,100»
DD UNIT=SYSDA,SPACE=(460,{700,100j)
DD UNIT=SYSDA,SPACE={460, (700,100)
Figure 146.
statements in the COBUC Procedure
IIISYSPRINT
JIISYSPUNCH
f /ISYSOTl
1115YSOT2
IIISYSUT3
------,
I
I
I
f
I
I
I
,
r
IIICOB
f/ISYSPRINT
1/ISYSUTl
1//SY5UT2
'1ISYSUT3
IIISYSUT4
IIISYSLIN
1//
I//LKED
1//
IIISYSLIN
III
I/ISYSLMOD
III
t 115YSLIB
1/ISYSUT 1
III
1115 YS PRINT
EXEC PGM=IKFCBLOO,REGION=128K
DD SYSOOT=A
DD UNIT=SYSDA,SPACE=(460,(700,100»)
DD UNIT=SYSDA,SPACE=(460,{700,100)
DD UNIT=SYSDA,SPACE=(460, (100,100»
DD UNIT=SYSDA,SPACE=(460,(700,10~)
DD DSNAME=&&LOADSET,DISP=(MOD,PASS),UNIT=SYSDA,
SPACE= (80, (500,100»
EXEC PGM=IEWL,PARM='LIST,XREP,LET',COND=(5,LT,COB),
REGION=96K
DD DSNAME=&&LOADSET, DISP= (OLD ,DELETE)
DD DDNAME=SYSIN
DD DS NAME=&&G05ET, DISP= (NEW, PASS) , UN1T=SI5D A,
' SPACE= (1024, (50,20,1)
.DD DSNAME=S IS 1. COBLIB. D1SP=SHR
DD UN IT = (SY SD A, SEP= (SYSLIN, Syst !tOD) ) ,
SPACE=(1024,{SO,20)
DD SYSOUT=A
t
X
X
X
X
.-
IIILKED
II/SYSLIN
'I/SY5LMOD
III
IIISYSL1B
'1ISYSUT1
III
IIISYSPRINT
ItlGO
360
I
I
I
I
I
I
I
•
statements in the COBUCL Procedure
,
EXEC PGM=IEWL,PARM='LIST,IREF,LET',REGION=128K
DD DDNAftE=S ISIN
DD DSNAME=&&GOSET (GO) ,DISP={NEW ,PASS) ,UNIT=SYSDA,
SPACE={1024,{SO,20,1))
DD DSNAME=SYS1.COBLIB,DISP=SHR
DD UNIT=(SYSDA,SEP={SYSLIN,SYSLKOD»,
SPACE= (1024, (50,20) )
DD SYSOUT=A
EXEC PGM=*.LKED.SYSLBOD,COND=(S,LT,LKED)
,
I
X
X
J
I
I
I
I
I
I
.J
'-
Figure 148.
•f
J
'--
Figure 147 •
I
I
I
I
I
I
I
Statements in the COBULG Procedure
,
,
IIICOB
IIIGO
EXEC PGM=IKFCBLOO~ PARK=SUPftAP ~ REGION= 128K
DD SYSOUT=A
DD UNIT=SYSDA,SPACE=~60~(700~100»)
DD UNIT=SYSDA~SPACE=(460,(700,100»
DD UNIT=SYSDA.SPACE=(460,(700~100»
DD UNIT=SYSDA~SPACE=(460,(700,100»
DD DSNAME=&&LOADSET,DISP=(MOD,PASS),UNIT=SYSDA,
SPACE: (80, (500,100»
EXEC PGH=IEWL,PARK='LIST,IREF ,LET' ,COND= (S,LT,COB) ,
REGlON=96K
DD DSNAME=&&LOADSET,DlSP=(OLD,DELET~
Dn DDNAKE=SISIN
DD .oSNAHE=&&GOSET(GO) ,DISP=(NEW,PASS),UNIT=SISDA,
SPACE= (1024, (50,20,1»
DD DSNAME=SYS 1. COSL IB;.oISP=SHB
DD UNIT=(SISDA,SEP=(SYSLIN,SISL~OD» ,
SPACE=(1024,(50,20»
DO SISOU'1'=A
EXEC PGM=*.LKED.SISLMOD,COND=«5,LT,COB) ,(5,LT,LKED»
Figure 149.
Statements in the COBUCLG Procedure
II/SISPRINT
,//SYSUT1
IIISYSUT2
II/SYSUT)
'1ISYSUT4
II/SISLIN
1//
.IILKED
III
'/ISISLIN
tIl
IIISYSL80.o
tIl
II/SYSLIB
IIISISUT1
III
IIISYSPRINT
•
t
X
X
X
X
.J
r-
IIICOB
I/ISYSPRINT
II/SISUTl
II/SISUT2
IIISISUT3
II/SISUT4
IIISISLIN
III
IIIGO
II/SYSLIN
IIISYSLOUT
IIISISLIB
EX EC PGM=IK FCBLOO ,PARM=' LOAD' ,R EGlON= 12 8K
DD SYSOUT=A
DD UNIT=SYSDA,SPACE=(460, (700,100))
DD UNIT=SISDA,SPACE=(460,(700,10~}
DD UNIT=SYSDA~SPACE=(460,(700,100»
DO UNIT=SYSDA,SPACE=(460,(700,100»
X
DD DSNAME=&&LOADSET.DISP=(MOD,PASS)~
UNIT=SYSDA.SPACE=(80,(500,100»
EXEC PGM=LOAOER,PARM=·MAP,LET'.COND:(5~LT,COB),REGION=106K
DD DSNAl'tE=* .COB. SIS LIN. DISP= (OLD, DELETE)
DD SYSOUT=A
DD DSNAME=SYS1. COBLIB,DISP=SHR
.
I
Figure 150.
Statements in the COBUCG Procedure
location of the input data set must also be
supplied:
The COBUCLG procedure is a three-step
procedure to compile, link-edit~ and
execute using the COBOL compiler. Fiqure
149 shows the statements that make up the
procedure.
The COB job step produces an object
module that is input to the linkaqe editor.
Other object modules may be added as
illustrated in Example 5 under "Using the
DDNAKE Parameter."
The followinq DD statement, indicating
the location of the source module, must be
supplied in the input stream:
IICOB.SYSIN DD
*
(or appropriate
parameters)
If the COBOL program refers to SY SIN,
the following DD statement indicating the
IIGO. SISI N DD
* (or appropriate
parameters)
If the COBOL program refers to other
data sets, DO statements that define these
data sets must also be supplied.
The COBUCG procedure is a two-step
procedure to compile, load, and execute
using the COBOL compiler and as loader.
Figure 150 shows the statements that make
up the procedure.
The COB job step produces an object
module that is input to the loader.
using the Cataloged Procedures
361
a cataloged procedure step is to be
tested, the name of the step in' the
procedure (procstep) must be qualified
by the name of the step that called
for execution of the cataloged
procedure (stepname).
The following DD statement, indicating
the location of the source module. must be
supplied in the input stream:
/ICOB.SYSIN DD
*
(or appropriate
parameters)
2.
If the COBOL program refers to SYSIN.
the following DD statement indicating the
location of the input data set must also be
supplied:
specify in the operand field of the
EXEC statement calling the procedure
only the keyword parameters and
sub parameters, for example:
COND=(subparameters)
//GO.SYSIN
DD
*
If a multistep procedure is being
called, the specified parameters (with
the exception of PARM) apply to all
steps in the procedure. The PARM
keyword subparameters override the
first EXEC statement and nullify any
subsequent PARM keyword subparameters.
The COND and ACCT parameters apply to
all steps in the procedure. To
override PARM parameters in job steps
other than the first, the pre vious
method can be used.
(or appropriate
parameters)
If the CO BOL program refers to other
data sets, the DD statements that define
these data sets must also be supplied.
Existing cataloged procedures can be
permanently modified by using the IEBUPDTE
utility prog ram descrihed in the
publication OSLY~ Utili!ie2_
IQ!~:
A parameter in an EXEC statement
cannot be partly overridden; it must be
overridden in its entirety.
Any parameter
not overridden remains as originally
defined.
1~~Qt~~iding_~g_Adding_1Q_~!~£
~at~ts
Any parameter in a cataloged procedure
except the PGM=progname parameter in the
EXEC statement can be overridden.
Parameters or statements not specified in
the procedure can also be added.
When a
cataloged procedure is overridden or added
to, the changes apply only during one
execution.
OVERRIDING AND ADDING TO EXEC STATE!ENTS
An EXEC statement can be overridden or
added to in one of two ways:
1.
362
This section contains examples of
overriding and adding to the EXEC
statement. The procedures overridden or
added to are the IBM procedures shown in
Figures 146 through 150.
!~~~E1~1:
The following example shows the
overriding of one parameter in the EXEC
statement of the one procedure step in the
IBft-supplied COBUC procedure. The
statements appear in the input stream as
follows:
Iljobname
IISTEPA
/1
JOB 1234,J.SMITH
EXEC COBUC,PARM.COB='DECK,
NOLOAD,BOP=4000,
x
X
SIZE=9600'
Specify, in the operand field of the
EXEC statement calling the procedure,
the keyword, the procedure step-name
and the subparameters, for example:
/1
//COB.SYSIN DD
COND.procstep=(subparameters)
1*
If a multistep procedure is being
modified, parameters in the calling
EXEC statement must be specified step
by step; i.e., t.he parameters for one
step must be specified before those of
the next step.
If the return code of
!Q~~:
In actual use the PARM.COB parameter
cannot be continued in this manner. In the
PARM parameter that is overridden, the DECK
and NOLOAD options were specified. They
are incl ud ed again si nee the parameter must
be overridden in its entirety. The
*
(source module)
information is here enclosed in single
quotation marks, since subparameters that
contain equal signs must be enclosed in
this manner.
Note that all overriding parameters for
one step of the procedure must be specified
before those for the next step.
~!!!1!£lg_l.:
Ex~~£1g_!:
The following example shows the
overriding of two parameters and the adding
of another in the EXEC statement of one
procedure step of the IB~-supplied COBUCLG
procedure.
The statements appear in the
input stream as shown:
/Ijobname
IISTEPA
II
II
II
IICOB. SYSIN
JOB 1234,J.SMITH
EXEC COBUCLG, PAR". LKED=
X
(MAP,LIST) ,ACCT=(1234), X
COND.LKED=(9,LT,
X
STEPA. COB)
DD
*
The following example shows the
overriding of parameters on all EXEC
statements in the IBM-supplied COBUCLG
procedure.
The statements appear in the
input stream as shown:
Iljobname JOB
1234,J.SMITH
/Istepname EXEC
COBUCLG,
X
II
PARM= (LOADrPMAP) ,
X
II
COND=(3,LT)r
X
II
ACCT=(123456,DEPTQ)
/ICOB.SYSIN DO
*
(source module)
(source module)
1*
1*
Note:
In actual use the COND.LKED and
piii.LKED parameters cannot be continued in
this manner.
For the linkage editor job
step in the above example, the COND and
PARM parameters have been overridden and
the ACCT parameter added.
The PARM options are added to the procedure
step COB and nullify-t.he PARM options in
the LKED and GO steps.
The COND and ACCT
parameters apply to all steps in the
proced ure.
E.~ampl!t_l:
The following example shows the
overriding of individual parameters in more
than one procedure step of the IBM-supplied
COBUCLG procedure.
The statements appear
in the input stream as shown.
Iljobname
Iistepnaroe
II
II
II
IICOB. SYSIN
JOB 1234,J.SMITH
EXEC COBUCLG,PARM.LKED=OVLY, X
COND.GO=«5,EQ,
X
stepname.COB),
X
(5,EQ,stepname.LKED»
DD
*
TESTING A PROCEDURE AS AN IN-STREAM
PROCED URE
A procedure can be tested before it is
placed in the procedure library by
converting it into an in-stream procedure
and executing it any number of times during
a job.
In-stream procedures are described
in detail in the publication oS/vs~£1
~rvic~.
(source module)
1*
!Qte: In actual use the COND.GO statement
cannot be continued in this manner. The
PARM option OiLY replaces the PARM
sub parameters of the link-edit job step.
The COHD option EQ (equal to) replaces the
option LT (less than) in the execution job
step.
An in-stream procedure is a series of
job control language statements enclosed
within a PROC statement and a PEND
statement.
The following example shows how
to convert the eOBUC procedure (Figure 146)
into an in-stream procedure and execute it
twice.
pemember that in actual use the
parameters cannot be continued in this
manner. )
Using the Cataloged Procedures
.363
IICONVERT
IIINSTREAM
JOB
parameters, individual subparameters
may be overridden.
1234, YOUR NAME
PRoe
IICOB
EXEC PGM=IKFCBLOO,PARM=' DECK,
NOLOAD, SUPS Apt,
REGION=128K
SYSOUT=A
IISYSPRINT DD
SYSOUT=B
IISYSPUNCH DD
DD
DSNAME=&&SYSUT1,
IISISUTl
UNIT=SY SOA,
II
SPACE={460,6700,100»
II
OSNAME=&&SYSU"T2,
OD
IISYSUT2
UNIT=SYSDA,
II'
SPACE={460,6700,100»
II
DD
115YSUT3
OSNAME=&&SYSUT3,
UNIT=SYSDA,
II
SPACE=(460,6700,100»
1/
DD
DSNAME=&&SYSUT4,
IISYSUT4
ONIT=SYSD A,
/1
SPACE={460,6700,100»
II
PEND
IIEND.PROC
EXEC INSTREAM
II
...
IICOB. SYSIN DD
X
X
X
X
• To nullify a keyword parameter (except
the DeB and AMP parameters), write, in
the overriding DD statement, the
keyword and an equal sign followed by a
comma.
For example, to nullify the use
of the ONIT parameter, specify UNIT:,
in the overriding DD statement.
X
X
X
X
X
• A parameter can be nullified by
specifying a mutually exclusive
parameter. For example, the SPACE
parameter can be nullified by
specifying the SPLIT parameter in the
overriding DD statement.
X
(input data)
• The DUMMY parameter can be nullified by
omitting it and specifying the DSNAME
parameter in the overriding DD
sta temen t.
OVERRIDING AND ADDING TO DO STATEMENTS
• To override DD statements in a
concatenation of data sets, the
programmer must provide one DD
statement for each data set in the
concatenation. only the first DD
statement in the concatenation should
be named. However, if a DD statement
to be changed follows one (or more) DD
statement(s) to be left intact, the
first overriding statement(s) should
ha ve a blank operand.
A DD statement can be overridden or
added to by using a OD statement whose name
is composed of the procedure step-name that
qualifies the ddname of the DD statement
being overridden, as follows:
• If the DDNAME=ddname parameter is
specified in a cataloged procedure, it
cannot be overridden; rather it can
refer to a DD statement supplied at the
time of execution.
1*
II
EXEC INSTREAM
IICOB.SYSIN DD
*(input data)
1*
Ilprocstep.ddname
DD
(appropriate
parameters)
~~~21~2_Qt-Q~~££i~!ng_an~_Addi~to_Q~
~tatn~n1§
Entire OD statements can also be added.
There are rules that must be followed
when overriding or adding a DD statement
within a ste p in a procedure.
• Overriding DD statements mast be in the
same order in the input stream as they
are in the cataloged procedure.
• DO statements to be added must follow
overriding DD statements.
There are some special cases that should
be kept in mind when overriding a DD
statement.
• All parameters are overridden in their
entirety, except for the DCB and AMP
parameters. Within the DCB and AMP
364
This section contains examples of
overriding and adding to parameters in DD
statements. The procedures overridden or
added to are the IBM procedures shown in
Figures 146 through 150.
The DDNAME parameter is not used in
these examples, although it can be useful
with the cataloged procedures. The use of
the DDNAKE parameter is described in detail
later in this chapter.
Rxample 1: The following example shows the
overriding of DD statements in the
IBM-supplied COBUCLG procedure.
Iljobname
Ilstepname
IICOB.SISLIN
IICOB. SYS.IN
JOB 1234,J.SftITH
EXEC COBUCLG
DO
DSNAME=GOFILE
DD
*
(source 1I0dule)
1*
IILKED.SYSLIN
DO
II
OSNAftE=*.COB.SYSLIN,
DISP=(OLD,CATLG)
in the procedure and must precede those
statements being added.
x
JOB
EXEC
DD
DD
Iljobname
Iistepname
IICOB.?YSUT2
IICOB.SYSLIN
II
II
1*
DD
IICOB. SYSIN
(other DD statements for
user-defined files)
1234,J.SMITH
COBUC,PARM.COB=(LOAD)
SPACE=,UNIT=SYSSQ
DSNAME=&&GOFILE,
DISP=(MOD.PASS),
UNIT=SYSSQ
x
X
*
(source module)
1*
1*
(subsequent job steps)
The name of the data set in SYSLIN in the
procedure step COB is changed to GOFILE.
The name of the data set of SYSLIN in the
proced ure step LKED is changed to a
reference to the SYSLIN DD statement in the
COB procedure step, and the data set name
GOFILE is cataloged.
The following example shows the
adding of DO statements to the IBM-$upplied
COBUCLG procedure.
~~A~~~1:
Iljobname
/Istepname
JOB 1234,J.SMITH
EXEC COBUCLG,
PARM. COB= (D.ECK, LOAD, Pl'lAP)
II
SYSOUT=B
IICOB.SYSPUNCH DD
//COB.SYSIN
DD
*
x
(source module)
1*
IIGO.TRANSACT
DD
The device class on the COB.SYSUT2 DD
statement is changed to SYSSQ, and the
SPACE parameter is nullified. Therefore,
mass storage devices cannot be allocated.
Any tape volumes to be assigned must have
standard labels. The COB.SYSLIN DD
statement is changed so that it passes the
object module to subsequent job steps.
DSNAME=JUNE,DISP=OLD
(other DD statements for
user-defined files)
1*
lfQte: In the foregoing ex am pIe TRAN SACT is
a cataloged data set. When a data set is
cataloged, it is sufficient to refer to it
by DSNAl'lE and DISP=OLD.
The PARM.COB option DECK and the SYSPUNCH
DD sta teBlent are added to obtain a punched
object module. The PARM option Pl'lAP is
added to obtain a listing of the assembler
language expansion of the source mod ule.
~I.~~_~:
The following example sho,vs
overriding and adding to DD statements at
the same time in the IBM-sllpplied COBUC
proced ure. Note tha t overriding statements
must be in the same sequence as they appear
The following example shows how
to concatenate a data set with a data set
defined in the COBULG procedure.
nampl~!:!.:
Iljobname
/Istepname
JOB
EXEC
1234,J.SMITH
COBULG
IILKED.SYSLIB
II
DD
DD
(blank operan d field]
(parameters]
1*
Instead of the blank operand field,
parameters could have been used to override
the SYSLIB statement; the data set defined
by the unnamed DD statement would then be
concatenated to the data set that was
redefined by overriding.
Note that a number of libraries could be
concatenated to the SYSLIB data set. For
example:
I/LKED.SYSLIB
II
II
DD
DD
DD
DSNAME=USERLIB,DISP=OLD
DSNAME=MYLIB,DISP=OLD
Using the cataloged Procedures
365
When using the DDNAME parameter, the
programmer should also keep the following
in mind:
The DDNAME parameter is used to define a
dummy data set that can assume the
characteristics of an actual data set,
defined by a subsequent DD statement within
the step.
If a matching DD statement is
found, its characteristics, with the
exception of its ddname, replace those of
the statement using the DDNAME parameter.
If a matching DD statement is not found
within the step, the data set defined by
the DDNAME parameter remains a dummy.
This section contains examples shoving
the use of the DDNAME parameter with
ca ta loged procedures.
• The name of the DD statement referred
to does not replace the name of the
referencing statement.
• If a statement that contains the DDNAME
pa rame ter is overridden, it is
nullified.
• If overriding is performed with a
statement that contains the DDNAME
parameter, all parameters in the
overridden statement are nullified.
The following OD statements:
liS 1
IID1
IID2
The rules for using the DDNAME parameter
are as follows:
liD 3
EXEC
DD
DD
DD
PGM=progname
DDNAME=D3
(parameters!. Y, Z)
(parameters U, T, V)
will result in the same data definition
produced by the following statements:
• A backward reference (e.g., *.ddname)
to a DD statement referred to by a
DDNAME paramet.er cannot be used because
the statement that is referred to loses
its identity.
• A backward reference to a statement
containing a DDNAME parameter can be
used, but only after the statement to
which the DDNAME parameter refers has
been encountered. If a backward
reference is used before the dummy data
set (defined by DDNAME) has been given
real characteristics, these real characteristics will not be transferred to
the DD statement that contains the
backward reference. For example, if
DCB=*. dd name is used (where ddna me is
the name of a statement containing an
unresolved DDNAME parameter), the DCB
fields that are transferred are blank.
• Unnamed DD statements can be placed
after a statement containing the DDNAME
parameter (indicating concatenation),
but unnamed DD statements cannot be
placed af·ter a statement referred to by
a DDNAME parameter.
• The DONAME parameter can be used a
maximum of five times in a step, but
each DDNAME parameter must .refer to a
different statement.
• The ODNAME parameter cannot be used in
a JOBLIB statement.
• The DDNAME parameter is not to be used
to refer to a DD statement with the
DYNAM pa rameter specified ..
366
IIS1
IID1
1102
EXEC PGM=progname
DO
(parameters U,T,V)
DD
(parameters X, Y, Z)
EXAMPLES OF USING THE DDNAME PARAMETER
ExamI!lLl:
The following example shows how
to override the first DD statement in a
cataloged procedure with a DO * statement,
and allow subsequent statements to be processed.
The cataloged procedure (PROC3) is
as follows:
IISTEP 1
IIDD1
IIDD2
EXEC PGM=progname
DD
(any para meters)
DD
(any parameters)
The job procedure in which the overriding
takes place appears in the in~ut stream as
follows:
/IJOB1
liS 1
IISTEP1.DDl
IID1
JOB 1234,J.SMITH
EXEC PROC3
DD
DDNAME=Dl
DD
*
The STEP1.DDl statement overrides the
DDl statement; the DD2 statement is processed; th en the D1 statement is processed.
ExamElLl:
Tnefollowing example shows how
to override the first DD statement in a
cataloged procedure with a DD * statement
and how to add a DD statement. The
cataloged procedure (PROe3) is as follows:
IISTEPl
IIDD1
IIDD2
EXEC PGM=prognalle
DO
(any parameters except
DATA or *) ,
DD
(an y parameters e.xcept
DATA or *)
The job procedure in wbich the overriding
takes place appears in the input stream as
follows:
IIJOB2
1151
IISTEP1.DOl
IISTEP1. D03
lIDO 4
JOB l234,J.5KITH
EXEC PROe)
DD
DONAME=DD4
(any parameters except
00
DATA or *)
DO
*
The DD4 statement effectively overrides
the DDl statement, after the DD2 statement
has been processed and the 003 statement
has been added.
!~uple-1:
The following example sholfs how
to concatenate a data set in the input
stream with a data set defined by a DO
statement in a cataloged procedure. The
cataloged procedure (PROC3) is as follows:
IISTEPl
11001
IIDD2
EXEC PGM=progname
DD
(any parameters except
DATA or *)
DD
(any parameters except
DATA or *)
DATA or *)
(any parameters except
DATA or *)
DO
IIDD2
The job procedure in which the concatenation takes place appears in the input
,stream as follows:
IIJOB4
IIS1
JOB
EXEC
I/STEP1.DD2 OD
DD
II
IISTEP1.D03 DO
DO
11004
1234, J.SMITH
PROC3
(blank operand field)
DDNAME=DD4
(any parameters except
DATA or *)
*
Example~:
The following example shows how
the statement DD DDNAME=SYSIN in the
IBM-supplied COBUCLG procedure can be used
to add more object modules as input to the
linkage editor. The statements appear in
the input stream as follows:
Iljobname
Iistepname
JOB
EXEC
IICOB.SYSIN
DO
·1234,J.SMITH
COBUCLG
*
(source deck)
1*
IILKED.SYSIN
DD
*
(first object module)
The job procedure in Which the
concatenation takes place appears in the
input stream as follows:
JOB
IIJOB3
EXEC
1151
IISTEP1.DDl DD
DD
II
DD
IIDD3
1234,J. Sf! ITH
PROe3
(blank operand field)
DDN AME=DD3
*
The data set in the input stream is
concatenated with the data set defined by
the DDl statement after the 0.02 statement
has been processed.
Ixample 9: Ifhe following example shows how
to concatenate a data set in the input
stream ~ith a data set defined by a DD
statement in a cataloged procedure and how
to add a DD statement. The cataloged
procedure (PROe3) is as follows:
//STEPl
IIDDl
EXEC PGft=progname
DD
(any parameters except
(last object module)
1*
(IIGO.
car ds)
The COBUCLG procedure contains the
following tvo statements in the linkage
edit step:
1/5YSL1N DD DSNAME=&&LOADSET,
II
OISP=(OLD,DELETE)
II
DD DDNAME=SYSIN
x
The result of concatenating SYSIN with
SISLIN is that when SISLIN (input to
linkage editor) is read, SYSIN is also read
and linked with it. For example, if
ILBODSPO is one of the object modules in
the SYSIN stream, it will be linked with
SISLIN. The ILBODSPO module from
SIS1.COBLIB will not be used.
Using the Cataloged Procedures
367
To use the Sort/Merge feat~re of the
OS/VS CO BOL Compiler, sort/merge fea ture
statements are written in the COBOL source
program.
These statements are described in
tae publication IBM_~£Q~Q~_!Q£_OSL!~.
The Sort/Merge program itself is described
in the appropriate ~QrtLMeilSl-Rt.Qg,t:~n~~§
of the system-name in an ASSIGN clause in
the COBOL source program.
When the GIVING
option is specified, the compiler generates
an output procedure that will open the data
set, return the records, write the records,
and close the data set.
Guig~.
Use of the full COBOL sort/Merge feature
requires the program product OS/VS
sort/Merge, 5740-S111. The os Sort/Merge,
5734-S.M1, may only be ased if COBOL sort
alone is used--without alternate collating
sequence and without merge.
(If 5134-SM1
is used, it may issue message IGH067I,
"INVALID EXEC OR ATTACH PARAMETER." This
will have no effect on operations, and may
be safely ignored.)
DD statements must be written in the
execution-time job steps of the procedure
to describe the data sets used by the
sort/merge program.
DD statements for data
sets used during the sort/merge process are
described below.
~Qte:
The sort/Merge Checkpoint Restart
feature is available to the programmer
through the use of the RERUN statement.
Three types of data sets can be defined
for the sort program in the execution time
job step: input, output, and work. In
addition~ data sets must be defined for
the use of the system during the sorting
'Operation.
·For MERGE, work DD statements are required.
The maximum number of files that can be
merged is 8.
SORT INPUT DD STATEMENTS
The input data set is associated with a
ddname that appears as the ddname portion
of the system-name in an ASSIGN clause in
the COBOL source program. When the USING
option is specified, the compiler will
generate an input procedure that will open
the data set, read the records, release the
records a nd close the da ta set.
SORT OUTPUT DD STATEMENTS
The output data set is associated with a
ddname that appears as the ddname portion
368
SORT WORK DD STATEMENTS
The sort program requires at least three
work data sets. The ddname for each DD
statement is in the form SORTWKnn, where nn
is a decimal number. The ddnames for the
required data sets must be SORTWK01~
SORTWK02, and SORTWK03.
Additional work
data sets may be defined, but their ddnames
must be consecutively numbered, beginning
with 04.
Intermediate data sets (i.e., SQRTWKnn
data sets) for a sort/merge may be assigned
to either magnetic tape or mass storage
devices.
All of the intermediate storage
for one sort/merge must be assigned to the
same device type. These may not be on both
7-track and 9-track tape units in the same
sort. Anyone of the following devices may
be used for intermediate storage:
IBM 2400-series Magnetic Tape Unit (7or 9-track)
IBM 3400-series Magnetic Tape unit
(9-track)
IBM 2314/2319 Direct Access storage
Facility
IBM 3330 Direct Access storage
Facility
IBM 3340 Direct Access Storage
Facility
IBM 3350 Direct Access storage
Facility
The ~£!LH~£~f£Qg£~~~~2 Gui~ contains
detailed informa tion about these devices.
Since spanned records can be input to
and output from the sorting operation, it
is the user's responsibility to assign the
sort work files to mass storage devices
whose track sizes are larger than the
logical record size of the records being
sorted. An s-mode file whose logical
record length is greater than its track
size may be sorted by assigning the work
files to a magnetic tape unit.
If data sets not involved in the sorting
or merging operation are assigned to tape
units, t~ese tape units may be used as sort
work files by using the UNIT=AFF parameter.
Por exaaple, if PAYROLL is specified as the
ddname of the ASSIGN clause in a SELECT
statement, the tape unit assigned to
PAYROLL could be used as a sort work file
by using the following DD statement:
SORXWKnn DD statement§
SORTWKnn data sets may be contained on
tape or mass storage volumes.
When mass
storage space is assigned, only the primary
allocation is used by the sort, and it must
be con tiguous.
Note that the SORTWKnn data sets:
//PAYROLL DD UNIT=2400, •••
//SORTWK02 DD UNIT=AFP=PAYROLL •••
The input data set must reside on a
physical device, a magnetic tape unit, a
mass storage device, or in the system input
stream. The following example shows DD
statement paralleters that could be used to
define a cataloged input data set.
//1 NSORT
II
DD
DSNAME=INPT,
DISP=(OLD,DELETE)
x
1.
May nQi be spread over more than one
device type.
2.
May R2i be on 1-track tape when the
input data set is on 9-track tape.
3.
May be on 1-track tape when the
output data set is on 9-track tape.
4.
Cannot use the data conversion feature
if they are on 7-track tape. The
TRTCH subparameter must reflect this.
5.
May be on 9-tracK tape when the input
data set is on 7-track tape.
These parameters cause the system to search
the catalog for a data set named INPT
(DSNAME parameter) •
When found, the data
set is associatedvith the ddname INSORT
and used by the sort program. The control
program obtains the unit assignment and
volume serial number from the catalog, and
displays a mounting message to the
operator. The DISP parameter indicates
that the data set has already been created
(OLD).
It also indicates that the data set
should be deleted (.DELETE) after the
current job step.
~Ull!ill_~~le_!:
The output DD statement must define all
of the characteristics of the output data
set. The following example shows DD
statement parameters that could be used to
characterize an output data set:
~QRTWKnn_~~g~le B:
The following DO
statement parameters could be used to
define a mass storage intermediate storage
data set:
//OUTSORT
II
DD
DSNAftE=OUTPT, UNIT=2400,
DISP= (NEW, CATLG)
The DISP parameter indicates that the data
set is unknown to the operating system
(NEW) and that it should be cataloged
(CATLG) under the name OUTPT (DSHAME
parameter). The UNIT parameter specifies
that the data set is on a 2400-series tape
unit.
x
The following DD
statement parameters could be used to
define a tape intermediate storage data
set:
IISORTWKOl DD
II
x
UNIT=2400,LABEL=(,NL),
VOLUME=SER=DUMMY
These para meters spec ify an unlabeled data
set on a 2400-series tape unit. Since the
DSNAME parameter is omitted, the system
assigns a unique name to the data set. The
omission of the DISP parameter causes the
system to assume that the data set is new
and that it should be deleted at the end of
the current job step. The 2400-series tape
units are explicitly of the 9-track format.
IISORTiKOl DD
II
UNIT=2314,
SPACE=(TRK, (200) "CONTIG)
X
These parameters specify a mass storage
data set with a standard label (LABEL
parameter default value).
The SPACE
parameter specifies tha t the data set is to
be allocated 200 contiguous tracks. The
system assigns a unique name to the data
set and deletes it at the end of the job
step.
Using the sortlMerge Feature
369
• The input data set and the output data
set.
ADDITIONAL DD STATEMENTS
The sortlmerge program .requires two
additional DD statements:
IISYSOUT
DD
The AFF subparameter of the UNIT
parameter can be used to associate the
input data set with either the SORTWK01
data set or the output data set. The
subparameter can appear in the DD statement
for SORTWK01 or output.
SYSOUT=A
which defines the system output data set.
IISORTLIB
II
DD
DSNAME=SYS 1. SORTtIB,
DISP=SHR
x
which defines the library containing the
SORT/MERGE modules.
!Ql~:
At OS/VS sortlMerge installation
time, t.he programmer can designate that
SortlMerge diagnostic messages be printed
on a specified data set. The FLAG option
determines whether t.he messages directed to
this data set are either
uncorrectable-error messages or both
informational and uncorrectablele-error
SortlMerge messages.
In either case,
uncorrectable-error messages are displayed
on the console. SYSOOT is the default data
set that is modified by the FLAG option.
If there are DISPLAY or EXHIBIT statements
in the COBOL program, the SortlMerge
messages cannot be routed to the same data
set designated for the output of the
DISPLAY andlor EXHIBIT statements.
Therefore, one of the following courses of
action should be considered:
• The SortlMerge default data set should
be changed at installa tion time by
specifying the PRINT=parameter and
selecting a DD name other than SYSOUT.
At execution time, the selected DD name
must be specified on a DD statement.
• In the COBOL source program, a DD name
other than SYSOur should be placed in
the SORT-MESSAGE special register prior
to the SORT statement. At execution
time, the selected DD name must be
specified in a DD statement.
• At compile time, the SYSOUx option can
be used to designate a file for COBOL
DISPLAY output other than SYSOUT.
Therefore, sort/Merge messages can go
to the SYSOUT file.
USlNG_MOgE_IH!!-Q!~_~QEIL~~RGt-STATE~~NT_I!
.L~Q!!
More than one SORTIMERGE statement may
be used in a single program or in two or
more programs that are combined into a
single load module.
SORT PROGRAM EXAMPLE
The control cards in Figure 151 could be
used with the sample program that
illustrates the Sort feature.
A
description of the Sort Feature can be
found in the publication I!!lL.l~~Q!!Q!:_fQ.£
OS~.
•IIISORTEST
JOB
III
III
EXEC
DD
IIISORTJS3
JIICOB.SySIN
J
J
I
J
I
I
I
I
'1IGO.SORTWK01 DO
III
III
IIIGO.SORTWK02 DD
III
11/
'1IGO.SORTWK03 DD
III
III
DD
III
• The inpu t data set and the first
intermediate storage data set
(SORTWKO 1) •
370
*
(COBOL source program)
IIIGO.OUTSORT
A single t~pe unit may be assigned to
two sort data sets when the data sets are
one of the following pairs:
NY838670165,
'J.SMITH',
MSGLEVEL=l
COBUCLG
ill
IIIGo.SYSOUT
IIIGO. SORTL! B
JI/
IIIGO.INFILE
III
III
DD
DO
DD
XI
I
I
I
I
I
I
I
I
I
,
I
UNIT=2314,
xt
SPACE=(TRK,(200),
XI
,CONTIG)
I
UNIT=2314,
SPACE=(TRK,(200),
XI
,CONTIG)
I
UNIT=2314,
XI
SPACE={TRK,(200),
XI
,CONTIG)
I
UNIT=183,
XI
LABEL=(,NL),
XI
VOLUME=SER=NONE
1
SYSOUT=A
I
OSNAME=SYS1.S0RTLIB,Xi
OISP=SHR
I
UNIT=182,
XI
LABEL= (, NL) ,
XI
VOLUME=SER=DUMMY
I
~
Figure 151.
,
XI
X,
J
Sort Feature control Cards
The minimum number of SORTiKnn data sets
are used; the sort operation can be
optimized by using additional work data
sets (see the appropriate So£1~~
o
16
Successful completion of
Sort/Merge
Unsuccessful completion of
Sort/Merge
g~Q~~me~~~~).
SUCCESSFU1_~OMPLETlQN:
When a Sort/Merge
application has been successfully executed,
a completion code of zero is returned and
the sort terminates.
since repeated use of the sort/Merge
feature often involves the same execution
time DD statements. the user may wish to
catalog them (see "Using the Cataloged
Procedures").
communication between the Sort/Merge
program and the COBOL program is maintained
by the COBOL library subroutine ILBOSMGO.
This routine links to the sort/Merge
program using the load module name SORT.
It is the user's responsibility to set up
his LINKLIB/STEPLIB in such a way that an
alias or load module name of SORT/MERGE
points to the first module of the
Sort/Merge program he wishes to use. The
programmer must also designate via the
appropriate SORTLIB DD statement the
library of the sort/Merge program he wishes
to use.
If the INPUT PROCEDURE option of the
SORT/MERGE statement is specified, exit E15
of the Sort/Merge program is used. The
return code indicating "insert records" is
issued vhen a RELEASE statement is
encountered, and the return code indicating
"do not return" is issued when the end of
the procedure is encountered.
If the OUTPUT PROCEDURE option is
specified, exit E35 of the Sort/Merge
program is used. The return code
indicating "delete records" is issued when
a RETURN statement is encountered, and the
return code indicating "do not return" is
issued when the end of the procedure is
encountered.
(For additional information,
about the Sort/Merge program, see the
appropriate Sort/M~r~l:Q~uur' s Gull~.)
The Sort/Merge program returns a
comp letion code upon termina tion. This
code may be interrogated by the COBOL
program. The codes are:
UN~UCCESSFUL_COMP1.ETIQli:
If the
sort/merge, during e.xecution, encounters an
error that will not allow it to complete
successfully, it returns a completion code
of 16 and terminates.
(Poss.ible errors
include an out-of-sequence condition or an
input/output error that cannot be
corrected.)
The s.Q.rtLt1.~r.9.g-f£Qg£~m.!!tg~~
§Yil~ contains a detailed description of
the conditions under which this termination
will occur.
The returned completion code is stored
in a special register called SORT-RETURN by
the COBOL library subroutine; an
unsuccessful termination of the sort may
then be tested for and appropriate action
specified.
Note that the contents of
SORT-RETURN will change with the execution
of a SORT statement. The following is an
example of the use of SORT-RETURN with the
sort feature:
SORT SALES-RECORDS ON ASCENDING KEY
CUSTOMER-NUMBER, DESCENDING KEY DAYTE,
USING FN-1, GIVING PN-2.
IF SORT-RETURN BOT EQUAL TO ZERO,
DISPLAY 'SORT UNSUCCESSFUL- UPON
CONSOLE, STOP RUN.
If no references to SORT-RETURN are made in
a program, an unsuccessful sort will
generate the following message:
IKF888I- UNSUCCESSFUL SORT FOR SD
SORT-FILE DDNAME
See "Appendix K: Diagnostic Messages" for
a description of action to be taken.
A normal Sort/Merge operation will
produce the following messages from the
OS/iS Sort/Merge program: ICE036I,
ICE0371, ICE038I, ICE045I, ICE049I,
ICE052I. ICE0541, and ICE055I. Other
messages may appear depending on the COBOL
options specified.
If the OS Sort/Merge program product is
used, the same messages will appear with
the same numbers, but the three-character
prefix will be different.
Using the Sort/Merge Feature
311
TERMINATING THE SOBT PROGRAM FROM THE COBOL
PROGRAM
By placing the value 16 in the special
register SORT-RETURN during the execution
of an input or output proceaure~ the COBOL
program can terminate the OS Sort/Merge
program product immediately after executing
the next RELEASE or RETURN statement. When
control returns to the statement following
the Sort statement~ the special register
SORT-RETURN will contain 16 to indicate an
unsuccessful completion.
Records defined under a COBOL SD are
assigned a BLL {Base Locator for Linkage
Section) ~ or a BL (Base locator) if SAME
RECORD AREA is specified. Location of a
given data item in an object-time dump when
the record in which it is contained
references a BLL can be determined as
follows:
1.
From the compilation
determine:
a.
2.
The displacement of the item (see
Data Division Map).
h.
The relati ve address of the BLL
CELLS (see the Memory Map Table).
c.
The BLL number.
From the dump~ determine the
relocation factor (USE/EP).
Add the relative address of the BLL
CELLS to the relocation factor to
obtain the absolute BLL CELLS address
in the dump.
4.
Each BLL is 4 bytes long: they are
located in ascending sequence~
beginning in the dump at the address
computed in Step 3 BLL=1 is the first
4 bytes, BLL=2 is the second 4 bytes,
etc.
Find the appropriate 4 bytes.
372
1.
From the Data Division map, determine
the BLL number of the SORT/M.ERGE file
being processed at the time of program
termination.
Assume it is BLLn.
2.
From the Task Global Table map,
determine the location of the BLL
cells in the COBOL object program.
3.
The ~th BLL in the main storage dump
will point to the last record released
to SORT/MERGE.
Note:
This BLL is initialized vhen control
Is-first transferred to the input
procedure.
Thus, if the program terminates
before control ever goes to the input
procedure, the BLL will not be initialized.
Also, with a USING clause in a SORT
statement, the BLL viII not be initialized.
listing~
3.
5.
For debugging purposes, it ~s sometimes
useful to determine the last input record
released to the Sort/Merge program.
The
following procedure should be used:
The 4 bytes obtained in step 4 contain
the absolute base address of the
desired record.
Add the item's
displacement to it to obtain the
absolute address of the leftmost byte
of the field in the dump.
~RT/MERGE
CHECKPOINT/REST!!!
The CHECKPOINT/RESTART feature is
available to the programmer using the COBOL
SORT/MERGE sta tement.
In order to ini tiate
a checkpoint, the programmer uses DO
statements and the RERUN clause.
The DD
statement for use in taking a checkpoint is
discussed in "Using the Checkpoint/Restart
Feature •••
The RERUN clause is used to indicate
that checkpoints are written, at logical
intervals determined by the sort/merge
program, during the execution of all
SORT/MERGE statements in the program.
This
RERUN clause is fully described in the
publication I~~Q~_Fu!! Amg~~D-!atio~l
~ll!!dal:g_~Q]Hll! •
The information you give the sort/Kerge
program about the application i t is to
perform he~ps the sort and merge phases to
produce a fast, efficient sort or merge.
when you do not supply information such as
data set size and record format, the
program must make assumptions, which, if
incorrect, lead to ineffiency.
DATA SET SIZE
The most important information one can
give is an accurate data set size using the
SORT-FILE-SIZE special register. If the
exact number of records in the input data
set is known, that number should be used as
the value.
If the exact number is not
known, an estimate should be made.
When
the Sort/Merge program has accurate
information about data set size, it can
make the most efficient use of both main
storage and intermediate storage.
MAIN STORAGE REQUIREMENTS
If the maximum amount of main storage to
be used by the sort/Merge progra m was not
specified at installation time, the program
assumes a ma ximu.m of 15,500 bytes. The
sort program requests 12,000 bytes leaving
3500 bytes for system functions.
Performance usually improves as the program
is given more main storage. A minimum of
44K bytes of main storage is normally
needed for efficient execution of the
sort/merge program, and performance may
increase as more main storage is made
a va ilable.
If the amount of main storage was
specified at system generation time, it is
the programmer's responsibility to ensure
that the Sort/Merge program has at least
that much main storage available in
addition to the space needed for Data
Management and the COBOL program. If this
amount of main storage is not available,
the program will terminate abnormally.
The programmer may alter, dynamically
within the COBOL program, the main storage
default values for the Sort/Merge program.
The SORT-CORE-SIZE special register may be
used to communicate changes to the
Sort/Merge program.
In general, a positive
value placed in SORT-CORE-SIZE denotes the
amount of storage the progra mmer is
allocating for use by the Sort/Merge
program.
For example, the statement "MOVE
30000 TO SORT-CORE-SIZE" means that 30000
bytes of storage are available to the
Sort/Merge program. Accordingly. if 30000
is moved to SORT-CORE-SIZE, COBOL
communicates to sort/Merge that 30000 bytes
of storage are available to it. There are,
in addition, two other uses for
SORT-COR E- SI ZE.
Special considerations apply when a
Sort/Merge program product is used.
If the
program prod uct is installed with the
SIZE=MAX option, the program allocates all
reaa1n1ng available main storage in a
region for its own use. If an input
procedure then attempts to open a file, an
80A abnormal termi na tion may resul t if
buffers and necessary data management
modules have not already been loaded, since
no more space is available.
If i~stead, a negative value is placed
in the special register prior to execution
of the sort, the program uses the default
SIZE option specified at installation, but,
if S!Z E=MAX was speci fied, sets aside tha t
a.bsolu te value before obtaining the
remainder.
Also, if ALL '9' (or +999999)
is moved to SORT-CORE-SIZE prior to a sort
operation, the program executes with the
SIZE=MAX option, regardless of the
installed value, while reserving 6K bytes
of main storage for use by the data
management routines and buffers.
The sort/Merge program product may also
be installed with a default reserved main
storage parameter that will be used if no
negative value is passed from COBOL.
For
additional information about these options
see the appropriate ~QI..tL!1flI.9..LIn§.iaJ..!atiQJl
~glgI.~n£g_~anYal·
Changing the main storage allocation can
be useful when a sort/merge application is
to be run in a multiprogramming
environment. By reducing the amount of
main storage allocated to sort/merge, so
that other programs can have the storage
they need to operate simultaneously, the
performance of sort/merge is impaired.
However, if this allocation is increased,
so that a large sort/merge application runs
more efficiently, the performance of other
jobs sharing the multiprogramming
environment is impaired, if not made
altogether impossible.
The messages generated by the sort/Merge
programs Feature are listed in the
appropriate ~QI.iL~~£g~_In§.1~1!~liQn
igfereli£~~anY~l and ~Q£!L~gI.~g
uogran~I.~-1iuid~.
When the Sort/Merge program is
installed, the user can elect to have
messages sent to the printer, in which case
a DD card with a ddname of SYSQUT must be
included in the job step. The programmer
can dynamically alter the ddname of the
file on which Sort/Merge is to vrite its
messages. If Sort/Merge has been installed
with provision for routing its messages to
the printer, then the programmec can place
in the SORT-MESSAGE special register the
ddname that Sort/Merge is to substitute
Using the sort/Merge Fea ture
.373
forSYSOUT, for message routing.
For
example, when the statement MOVE "SORTDDNM"
'1'0 SORT-MESSAGE is executed before sort is
initiated, then the sort writes its printer
messages to the data set SORTDDNM rather
than to SISOUT. If SORT-MESSAGE is not
refered to in the program, the ddname that
was specified at sort/Merge installation
time is the default value.
One technique for specifying the
sort/merge print file ddname vould be to
include source language and job control
language statements as follows:
SORTING VARIABLE-LENGTH RECORDS
Figure 152 illustrates one way to sort
variable-length records described by the
OCCURS clause with the DEPENDING ON option.
If the FD's (file-name description) and the
SD's (sort·file-name description) are
defined as in this figure, where the record
descriptions of the FDts and the SD
correspond, possibilities for error arise.
It is suggested, therefore, that the user
consider the following:
1.
01 SORT-PARAMETERS.
05 PARAMETER-COUNT PIC 9(4) USAGE COMP.
05 SORT-DDNAME PIC X(8).
•
SORT SORT-FILE USING INPUT-FILE •••
Imme!!illelY_1ll::g£edinLth~2Qtl
oper~lio.!!
vould probably lead to incorrect
results.
This statement implies a
READ ••• INTO
statement; that
is, after INPUT-FILE has been read~
the record is moved to AAA.
However,
because the user must set the length
of this recei vinq field prior to
moving 1 to AAA but cannot do so, the
compiler may use an incorrect length
that results in abnormal termination.
Instead, the user should substitute an
input procedure for the USING option,
as in the section of code labeled
PARA2B in the example.
IF PARAMETER-COUNT IS NOT EQUAL TO 0
MOVE SORT-DDNAME TO SORT-MESSAGE.
//GOSTEP EXEC PGM=program-name,
PARM:' SORTDDNM t
!Q!~:
This technique of assigning a unique
value to SORT-MESSAGE without modifying or
recompiling the program can also be applied
to the special registers SORT-CORE-SIZE,
SORT-MODE-SIZE, and SORT-FILE-SIZE.
specification of the statement
2.
Similarly, the statement
SORT SORT-FILE...
If the input Decords used are of
variable length, the record length that
occurs most freguentl y in the input data
set (modal lengt~ should be put into the
spec ia I register SORT-MODE-SIZE. This
value is used to help define a data set
based on a particular length. If a value
is not specified, the SORT/MERGE program
assumes it is equal to the average of the
maximum and minimum record lengths in the
input data set. If, for example, the data
set contains mostly small records and just
a few long records, the SORT/MERGE program
would assume a high modal length and would
allocate a larger record storage area than
necessary.
Conversely, if the data set
contains just a few short records and many
long records, the SORT/MERGE program would
assume a low modal length and might not
allocate a large enough record storage area
to sort data.
For a complete discussion,
see the appropriate SortLlag!:.ili! Programmer' 2
Qgidg.
374
GIVING OUTPUT-FILE
would probably yield incorrect
results.
Before OUTPUT-FILE is
written out, the record is moved to
AA. The correct length of this
receiving field must be set before the
moye~ but use of the GIVING option
precl udes this.
To a void error, the
user should substitute an output
procedure for the GIVING option, as in
section PARA3B of the example.
3.
If a SORT record contains an item with
an OCCURS DEPENDING ON clause and the
size of the SORT record description
with the minimum number of occurences
of the item represent the smallest
SORT record, the minimum SORT record
length is not reflected in the minimum
record length parameter passed to
SORT.
This may result in inefficient
SORT performance. The problem can be
avoided by specifying a dummy SORT
record of a fixed length (no OCCURS
DEPENDING ON) with the size of the
smallest SORT record described with
OCCURS DEPENDING ON clauses.
to be sorted or merged.
No buffer offset
may be given with the sort/merge feature.
For sorting ASCII files, the normal
EBCDIC collating sequence is provided
unless the user specifies otherwise.
To specify a sort/merge using the ASCII
collating sequence, the proqrammer may
include and identify a program collating
sequence of STANDARD-1 (equivalent to
ASCII). If LANGLVL(1) is specified, the
programmer may alternatively include the
"C" organization entry in the ASSIGN clause
for the file-name associated with the file
Through use of the COLLATING SEQUENCE
clause of the sort/merge feature, the
programmer can ident ify other (non-EBCDIC
and non-ASCII) collating sequences to be
used. See "Collating Sequences" in the
section "Programming Techniques."
Using the sort/Merge Feature
315
Part 1
r-
IIDENTIFICATION DIVISION.
IPROGRAft-ID.
VLSORT.
IENVIRONBENT DIVISION.
,INPUT-OUTPUT SECTION.
I FI.LE-CONTROL.
t
SELECT ••••
I
SELECT ••••
a
SELECT ••••
I DATA DIVISION.
,FILE SEC'rION.
fFD INPUT-FILE.
I
LABEL RECORDS ARE OMITTED
I
DATA RECORD IS A.
,01 A.
I
02 B PIC 99.
J
02 C OCCURS 1 TO 10 TIMES
DEPENDING ON B.
03
D PIC 99.
J
03
E PIC xx.
J
IF'D OUTPUT- FILE
LABEL RECORDS ARE OMITTED
I
DATA RECORD IS AA.
I
101 AA.
02 BB PIC 99.
I
02 CC OCCURS 1 TO 10 TIMES
J
DEPENDING ON BB.
J
03 DD PIC 99.
03
EE PIC xx.
SD SORT-FILE
DATA RECORD IS AAA.
01 AAA.
02 BBB PIC 99.
02 CCC OCCURS 1 TO 10 TIMES
DEPENDING ON BBB.
03
DOD PIC 99.
03
EEE PIC xx.
,
~----------------,
Part 2
•I
I
I
J
I
•I
J
J
I
j
J
J
I
J
J
J
J
j
,
•
•
J
I
I
•
using a sort input procedure, the RELEASE ••• FROM clause, which implies a MOVE
and then a RELEASE, should always be preceded by a MOVE that sets the length of the
receiving' field (AAA, in this example).
2When using a sort output procedure, the RETURN _ •• INTO
clause, which implies
the RETURN and then a MOVE, should ~!~~ be used. There is no way for the user to set
the correct length of the receiving field.
1 When
Figure 152.
316
,
IPROCEDURE DIVISION.
I
IPAR1 SECTION.
I
1
SORT SORT-PILE ASCENDING KEY BBB
I
t
INPUT PROCEDURE PAR2
I
I
OUTPUT PROCEDURE PAR3.
I
STOP RUN.
•
JPlR2 SECTION.
I
JPAR2A.
I
I
OPEN INPUT INPUT-FILE.
I
,PAR2B.
I
I
READ INPUT-FILE AT END GO TO PAR2C.
I
I
MOVE B TO BBB.
I
RELEASE AAA FROM A.l
I
I
GO TO PAR2B.
I
IPAR2C.
I
I
CLOSE INPUT-FILE.
I
I PAR2-EXIT.
I
EXIT.
I
,PAR3 SECTION.
I
,PAR 3A.
I
t
OPEN OUTPUT OUTPUT-FILE.
I
I PARlB.
I
,
RETURN SORT-FILE AT END GO TO PAR3C.2
J
MOVE BBB TO BB.
I
WRITE AA FROM AAA.
I
GO TO PAR3B.
,PAR3C.
I
CLOSE OUTPUT-FILE.
IPAR3-EXIT.
I
EXIT.
I
I
I
Sorting Variable-Length Records Whose File-nalle Description and
Sort-File-name Description correspond
os/vs SORT/MEJGE DEBUG
F~!IYj1
A DEBUG control statement may be included a t execution time to assist in debuggin g
sort/Berge problems. The ABEND operand of the DEBUG' statement can be used to override
the HOIBERD default of the installation keyword ERRET. The format of the COBOL
SORT-DEBUG statement is:
bDEBUGb operands
The operands and their meanings are as follows:
ABEND }
{ NOABEND
overrides the generated defaul t for action to be taken when the
program encounters an uncorrectable error.
CLOCK
Instructs the program to measure elapsed and CPU times for the
different PEER phases.
FLAG (x+ [,x< ••• ,XO])
Instructs the program to print PEER informa tion messages
(ICE120-124). The values which may be given to x are as
follows:
li)
0
C
P
R
E
Messages from all phases (ICE120-124)
Phase 0 messages ICE120)
Phase 1 messages (ICE 121)
Phase 2 (partit ion) messages (ICE124)
Phase 2 (reduct ion) messages (ICE122)
Phase 3 messages (ICE123)
CTRO=value
The program should keep a count of work I/O operations; when
the count reaches "value", it should ABEND.
EM=value
"Value" should be used as the maximum number of string s to be
merged in the final merge pass.
RM=value
"Value" should be used as the maximum number of strings to be
merged in intermediate merge passes.
CB=value
"Value·' is the number of Phase
RB=value
"Value If is the num ber of Phase 2 work buffers.
EB=value
"Value fl is the number of Phase 3 work buffers.
BT=value
Instructs the program to calculate the blocking factor for
intermediate storage in such a way that ttvaluettis the number of
buffers per track.
For more detailed information on the
DEBUG feature and the messages generated by
the use of the above operands, see the
publication OS/V~~rt/l1er~~gram~2
Q.ui9.!!Operands must be separated by commas.
Operands may be continued on a second card
either by following the last operand on
card 1 by a comma and continuing on card 2
in columns 2-16, or by having a nonblank
character in column 72 of card 1 and
work buffers.
continuing in column 16 of card 2.
Comments may be continued on a second card
by having a nonblank character in column 12
of card 1 and continuing in column 16 of
card 2.
Use of the COBOL SORT-DEBUG sta tement
requires the following DD statemen t:
//SRTCDS DD *
DEBUG Statement
OS/VS Sort/Merge Debug Feature
311
,
Although Release 2 of the OS/VS COBOL
compiler will accept a source program
containing segmentation specifications, it
will not produce an actual overlay
structure.
Instead, it combines all
segments into one single object program in
segment order, and allows the paging of the
VS operating system to perform any overlay.
The absence of actual COBOL-performed
overlay is usually not a problem in the
OS/VS environment, since adequate main
storage is available for even the largest
programs.
IDENTIFICATION DIVISION.
PROGRAM-ID.
ENVIRONMENT DIVISION.
OBJECT-COMPUTER. IBM-370
SEGMENT-LIMIT IS 15.
The following discussion is provided
only for those users who--while recognizing
that this compiler will not provide
overlay--nevertheless wish to write or
maintain programs that include segmentation
statements.
segmentation provides a means of
dividing the Procedure Division of a source
program into sections. Through the use of
a system of priority numbers, certain
sections are designated as fixed segments
(either fixed permanent or fixed
overlayable) and others as independent
segments.
suppose that the program SAVECORE is
segmented as shown in Figure 153. Only
those segments having priority numbers less
than the segment limit of 15 are designated
as fixed permanent. Sections in the fixed
permanent segment (SECTION-1, SECTION-2,
and SECTION-4) are those that must be
available for reference at all times, or
those to which reference is made
frequently.
They are distinguished here by
the fact that they have been assigned
priority numbers less than the program's
segment limit.
Fixed overlayable segments are sections
that are less frequently used. These
sections are sometimes made available in
the state in which they were last used (see
I~~_VS CQ]Q~_!Q£_Q~Ll~).
They are
distinguishable here by the fact that they
have been assigned priority numbers greater
than the segment limit, but less than 50.
Independent segments are those assigned
priority numbers greater than 49 and less
than 100 (section-5 and section-7 in this
example).
378
SAVECORE.
DA TA DIVISION.
,
I
,
PROCEDURE DIVISION.
SECTION-1 SECTION 8.
I
1
SECTION-2
SECTION 8.
I
I
I
I
SECTION-3
SECTION 16.
SECTION-4
SECTION 8.
SECTION-5
SECTION 50.
SECTION-6
SECTION 16.
SECTION-7
SECTION 50.
,
J
I
J
t
I
I
I
I•
I
t
J
1
J
J
t
I
f
1..--
Figure 153.
----'
Segmentation of Program
SAVECORE
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 priori ty-nl1mber is less
than the segment limit can have within
itsra nge only (a) sectionslili th
priority-numbers less than 50, and (b)
sections wholly contained in a single
segment whose priority-number is
greater than 49.
jQtg: As an extension to American
National Standard COBOL, the as/vs
COBOL Compiler 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)
OS/VS Sort/Merge Debug Fe'atures
378.1
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. limi t.
liQte:
As an extension to American
National Standard COBOL, the OS/VS
COBOL Compiler allows sections with any
priority-number to fall within the
range of a PERFORM statement.
• When a procedure-name in a segment with
a priority-number less than the segment
limit referred to by a PERFORM
statement in a segment with a
priority-number greater than the
segment limit, the independent segment
will be reinitialized upon exit from
the PERFORM.
segment.
Called subprograms are loaded
with the fixed portion of the main program
and assigned a priority of zero.
otherwise, the program executes just as if
it were not segmented.
LANGLVL OPTION AND RE-INITIALIZATION
The LANGLVL compile option chosen by the
user affects the degree and manner of
re-initialization COBOL will perform on
independent segments, since there is a
difference between the 1968 and 1974 ANS
definitions.
For further details, consult
the language manual I~~-Y~_CO~1-f~Q~L!~.
COMPILER OUTPUT
OPERATION
Execution of the object program begins
in the root segment; i.e., the first
segment in the permanent segment. If the
program contains no permanent segments, or
if the first section to be executed in the
program is not part of the root segment,
the compiler generates a dummy segment
thatwill initiate the execution of the
first independent segment.
All global
t~bles, literals, and data areas" are part
of the root segment.
Called object-time
subroutines are also part of the root
The output produced by the compiler is a
group of segments organized by priority
number. Segments whose priority is greater
than the segment limit (or 49, if no
SEGMENT-LIMIT clause is specified) consist
of executable instructions only. The PMAP
output is given in this sequence:
the root
segment first, followed by all other
segments in ascending order by priority
number.
Figure 154 shows the output of a sample
segmentation program.
Using the Segmentation Feature
319
OOOCl
coe02
C0003
00004
COC05
000C6
00007
ccce8
(0009
C(;010
00011
000l~
OCC13
00014
GOe15
\le016
00C17
00018
00C19
00020
cooa
00022
00023
OCC24
00025
OCC26
00027
00028
OCC':5
00030
OOC~l
00e32
00033
CCC34
0(;035
00036
cceH
00038
eOC35
oce40
OOCH
0()e42
00043
00044
C0045
00e46
~OC47
00048
00e49
OOC~C
00C51
{)OC~2
OOO!:";
00e54
00055
00e56
00057
00006u
00007u
000081.1
00009u
OOOlOu
OOOllu
000121.1
00013u
000141.1
000151.1
00016IJ
000171.1
00018IJ
u()019u
00020u
000211.1
000221.1
00023IJ
00024u
000251.1
0(0261.1
000271.1
000281.1
00029u
00030u
00031u
00032IJ
00033u
00034u
000351.1
000381.1
00039u
0()040u
000411.1
00042<1
000431.1
u0044U
00045.)
000461.1
000471.1
0004eu
00049\J
00050u
000511.1
00052u
000531.1
00054u
000551.1
00056u
00057u
00058u
000591.1
000601.1
000611.1
000621.1
000631.1
000641.1
Fiqure 154.
380
IDENTIFICATION uIVISION.
PROGRAM-ID. SE~-SAMPLE.
AUTHOR. PROGRAMMER-NAME.
REMARKS.
SPECIAL OPEKATUR INSTRUCTIONS - NONE.
INPUT REQUIKED - NONE.
PURPOSE
TO CREATE A SINGLE FILE ON DISK USING
QSAM/DTFSD, AND READ IT BACK.
PROGRAM UStS SEGMENTATION
WITH FILE PROCESSING SPREAD OVER
THE PERMANENT, OVERLAYABLE FIXED,
AND INDePENDENT SEGMENTS.
EXPECTED RE~ULTS
START TeST SEG-SAMPLE
(EACH SeGMENT DIS~LAYS ITS SEGMENT NUM8ER
AND FUNI.TlUN)
END TEST SEG-SAMPLE SUCCESSFUL RUN
SECTION~ WHILE WRITING APPEAR
IN ORDeK BU, 20, 30, 60, 40.
SECTION~ WHILE READING APPEAR
IN ORD~K 80, 60, 30, 40, 20.
ERROR INDICATIONS
**ERROR DISK SEQ 1/0**
**ERROR END OF EXTENT WRITING AFTER (RECORD) ••
**ERROK UNeXPECTED EOF READING AFTER
RECuRD (RECNO)**
**ERROR EOf NOT FOUND**
**RECORu IS (RECNO)
SHOUlu BE (RECNO)**
PROGRAM CONTAINS PERFORMS FROM 8ASE SECTION
TO PERMANENT, OVERLAYABLE FIXED, AND INDEPENDENT
SEGMENh.
ALSO COnlTAINS PERFORMS FROM INDEPENDENT TO PERMANENT
AND fROM OVERLAYABLE FIXED TO PERMANENT SEGMENTS.
ALSO CUj~TAINS PERFORMS ENTIRELY WITHIN A SEGMENT IN
IN EACH CATEGORY.
ENVIRONMENT DIV4S1UN.
CONFIGURATION S~CTION.
SOURCE-COMPUTER. 18M-370.
OBJECT-COMPUTER. IBM-370
MEMORY SIZt 6~000 CHARACTERS
SEGMENT-LIM4T IS 25.
INPUT-OUTPUT SEI.TION.
FILE-CONTROL.
SELECT FILt-l ASSIGN TO
DA-2314-S-DKSQ01A.
DATA DIVISION.
FILE SECTION.
FD FILE-1
RECORDING MuDE IS f
LABEL RECORuS OMITTED
DATA RECORD IS RECfDl.
01 RECFDl PICTuRE X(83J.
WORKING-STORAG~ SECTION.
77 ERRORSW PIC A VALUE SPACE.
77 ERC TFL PIC SS9 VALUE ZERO.
77 MSGHDR PIC X(~2) VALUE '**ERROR DISK SEQ 1/0*.'.
Sample segmentation Program (Part 1 of 14)
00154790
00154820
00154830
00154e40
00154850
00154860
00154870
00154880
00154~90
00154900
00154910
00154920
00154940
00154950
00154970
00154980
00154990
00155000
00155010
00155020
00155030
00155040
00155050
00155060
00155070
001550l'0
00155110
00155120
00155130
00155140
00155150
00155160
00155170
001551l'0
00155190
00155200
00155210
00155220
00155230
00155240
00155250
00155260
00155270
00155280
00155290
00155300
00155310
00155320
00155330
00155340
00155350
00155360
OCJe58
OC(!:S
00060
OOOH
000€:2
00e63
eCC€:4
00e65
OeC6i:
ooe67
00e68
COC6S
00C70
00071
ooell
Lloon
(;OC;;4
OCC75
00016
0((77
00078
Loe 7S
CtC ec
00C81
00Cf2
00ce3
OOC84
OOCSS
00086
aocn
00088
coe8Ci
cc.C9C
aocH
0C.CS2
a(JOS3
00094
ac.cCiS
OOOS6
ooeC;l
OOOCi8
00099
OOlCO
00101
00102
001C3
OOl04
00105
00106
00107
001e8
OOles
00110
OOHl
OOll2
00113
00114
000651i
00006.)
000671i
000681i
000691i
D00701i
ooe71u
ooonu
OOD73v
000741.1
00075v
00076tJ
000771i
00078u
OC079tJ
00080u
00081u
00082u
00083u
00084tJ
000851i
000861i
0008711
00088u
OG089u
000901.1
000911.1
00092tJ
000931.1
00094u
000951i
000961i
00097tJ
00098u
000991i
001001i
00101tJ
00l02v
00103v
001041.1
001051i
001061i
00107tJ
00108v
()0109v
OOllOv
OOlllv
001121i
001l3u
001l4tJ
001151.1
(J01l6v
0011N
001l8v
00lJ.9u
001",Ov
00121v
Figure 154.
77
MSGEOX PIC AC3b)
VALUE '**ERKOR END OF EXTENT WRITING AF~ER ' .
MSGEOF PIC X(37)
VALUE '**ERKOR UNEXPECTED EOF READING AFTER '.
77 MSGNEF PIC X(,3) VALUE. '**ERROR EOF NOT FOUND •• ••
01 REC1.
02 REC-ID.
03 REC-HD PI' X(4) VALUE ·RECD·.
03 REC-NO PIC S9(4) VALUE ZERO.
02 FILLER PIC A(75) VALUE SPACES.
66 RECIO ReNAMES REC-ID.
01 VER-REC.
02 VER-ID.
03 VER-HD PIC X(4J VALUE ·RECD·.
03 VER-NO PIC S9(4) VALUE ZERO.
PROCEDURE DIVIS£ON.
BASE-SECTION SE~TION O.
DISPLAY 'START TEST SEG-SAMPLE·.
OPEN OUTPUT FIL E-l.
PERFORM W-8tJ-0 THRU W-80-9.
PERFORM W-3v-0 THRU W-30-9.
PERFORM W-ou-O THRU W-60-9.
PERFORM W-4u-0 THRU W-40-9.
BASE-50.
CLOSE FILE-L.
OPEN INPUT ~ILc-l.
PERFORM R-8U-O THRU R-80-9.
GO TO R-60-v.
BASE-60.
PERFORM R-4u-0 THRU R-40-9.
READ FILE-l INTO RECl AT END GO TO BASE-70.
DISPLAY MSGriDR DISPLAY MSGNEF
MOVE 'E' TO ERRORSW.
BASE-70.
CLOSE FILE-h
BASE-90.
IF ERRORSW LS eQUAL TO 'E'
DISPLAY 'ENu TeST SEG-SAMPLE UNSUCCESSFUL RUN' ELSE
DISPLAY 'ENu TtST SEG-SAMPLE SUCCESSFUL RUN'.
STOP RUN.
SECTION-20 SECTLON 20.
W-20-0.
DISPLAY 'SE~TION 20 WRITE'.
NOTE ENTEREu BY PERFORM FROM W-80-0.
PERFORM W-£L-O THRU W-21-9 5 TIMES.
W-20-9.
EX IT.
W-21-0.
WRITE RECFDL FROM RECl INVALID KEY
DISPLAY MSGHDR
DISPLAY MSGcOX RECIO
MOVE 'E' TO ERRORSW
GO TO BASE-;)O.
ADD 0001 TO REC-NO.
W-21-9.
EXIT •
R-20-0.
00155370
00155380
00155390
00155400
00155410
00155420
00155430
00155440
00155450
00155460
00155470
00155480
00155490
00155500
00155510
00155520
00155530
77
00155550
00155560
00155510
00155580
00155590
00155600
00155610
00155620
00155630
00155640
00155650
00155660
00155610
00155680
00155690
00155700
00155710
00155120
00155730
00155760
00155770
00155780
00155790
00155800
00155810
00155820
00155830
00155840
00155850
00155860
00155870
00155880
00155890
00155900
00155910
00155920
00155930
Sample Segmentation Program (Part 2 of 14)
Using the segmentation Feature
381
ce1l5
co lJ.6
ce1l7
00118
00J.l9
001,,0
00121
00122
OC1,,3
00124
00125
00126
00127
OC128
00129
00130
00131
00132
00123
00134
COU5
OOUe
00137
CCUB
001221J
001231J
001241J
001251.1
001260
00l27u
00128v
001291.1
001301.i
001311.1
001321J
001331.1
001341.i
001351.1
001361.i
001371.1
00138u
001391.1
00140;)
001411.1
001421.i
0014301
001441.1
001451J
0013<;
00146.J
COHO
00147;)
001481.1
001491.1
001501.1
001511.1
001521.1
001530
00154v
oe155u
001561.1
001571.1
001581.1
001591.1
001601.1
001611.1
001621.1
001631.1
0(;1641.1
001651.1
001661J
00167u
001681.1
001691.1
001701.1
001711.1
001721.1
001731.1
001741.1
001751J
001761.i
00n7u
001781.1
CO 141
a0142
00143
00144
00145
C(146
00147
0014e
00149
(0150
C0151
001!2
a 01!3
Cul!4
00155
00156
00157
00158
CO l5S
00160
OOHI
caHl
001(:3
a( It4
CO it5
00166
00167
00168
00169
CC 17(;
00171
Figure 154.
382
DISPLAY 'SE~TIUN 20 READ'.
NOTE ENTEREO BY PERFORM FROM BASE-40.
PERFORM R-2.-0 THRU R-21-9 5 TIMES.
R-20-9.
EXIT.
R-21-0.
READ FILE-1 INTO RECl AT END
DISPLAY MSGMDR DISPLAY MSGEOF
ADD 4 TO ER~TFL MOVE 'E' TO ERRORSW
GO TO R-21-:i.
IF REC-ID I~ NuT EQUAL TO VER-ID
DISPLAY MSGHDR DISPLAY 'EXPECTED' VER-ID ' FOUND' REC-ID
ADD 1 TO ER~TFL MOVE 'E' TO ERRORSW
MOVE REC-ID TO VER-ID.
ADD 1 TO VE~-Nu.
R-21-9.
IF ERCTFL l~ GREATER THAN 3
GO TO BASE-70.
SECTION-30 SECT!ON 30.
W-30 .... 0.
DISPLAY 'SE~TIuN 30 WRITE'.
NOTE ENTEREu bY PERFORM FROM BASE-SECTION.
PERFORM W-3!-0 THRU W-31-9 11 TIMES.
W-30-9.
EXIT.
W-31-0.
WRITE RECFD~ FROM RECl INVALID KEY
DISPLAY MSGMDR
DISPLAY MSG~OX RECIO
MOVE 'E' TO ERRORSW
GO TO BASE-~O.
ADD 0001 TO RtC-NO.
W-31-9.
EXIT.
R-30-0.
DISPLAY 'St~TIUN 30 READ'.
NOTE ENTEREu BY GO TO FROM R-60-0.
PERFORM R-3~-0 THRU R-31-9 11 TIMES.
GO TO BASE-oO.
R-31-0.
READ FILE-l INTO RECl AT END
DISPLAY MSGMDR DISPLAY MSGEOF
ADD 4 TO ER~TFL MOVE 'E' TO ERRORSW
GO TO R-31-:7.
IF REC-ID l~ NOT EQUAL TO VER-ID
DISPLAY MSGHDR DISPLAY 'EXPECTED' VER-ID ' FOUND ~ REC-ID
ADD 1 TO ER~TFL MOVE IE' TO ERRORSW
MOVE REC-IO TO VER-ID.
ADD 1 TO VEK-NU.
R-31-9.
IF ERCTFL I~ GREATER THAN 3
GO TO BASE-70.
SECTION-40 SECT!ON 40.
W-40-0.
DISPLAY 'SE~TIUN 40 WRITE'.
NOTE ENTEREu BY PERFORM FROM BASE-SECTION.
PERFORM W-4.-0 THRU W-41-9 17 TIMES.
Sample Segmentation Program (Part 3 of 14)
00155940
00155950
00155960
00155970
00155980
00155990
00156000
00156010
00156020
00156030
00156040
00156050
00156060
00156070
00156080
00156090
00156100
00156110
00156120
00156130
00156140
00156150
00156160
00156170
00156180
00156190
00156200
00156210
00156220
00156230
00156240
00156250
00156260
00156270
00156280
00156290
00156300
00156310
00156320
00156330
00156340
00156350
00156360
00156370
00156380
00156390
00156400
00156410
00156420
00156430
00156440
00156450
00156460
00156470
00156480
00156490
00156500
00172
00173
00174
00175
00176
00177
00178
00179
00180
00181
00182
00183
00184
00185
00186
00187
00188
00189
00190
00191
00192
00193
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
001790
001800
001810
001820
001830
001840
001850
001860
001870
001880
001890
001900
001910
001920
001930
001940
001950
001960
001970
001980
001990
002000
002010
002020
002030
002040
002050
002060
002070
002080
002090
002100
002110
002120
002130
002140
002150
002160
002170
002180
002190
002200
002210
002220
002230
002240
002250
002260
002270
002280
·002290
002300
002310
002320
002330
002340
002350
Figure 154.
W-40-9.
EXIT.
W-41-0.
WRITE RECFDl FROM REC1 INVALID KEY
DISPLAY MSGHDR
DISPLAY MSGEOX RECID
MOVE 'E' TO ERRORSW
GO TO BASE-50.
ADD 0001 TO REC-NO.
W-41-9.
EXIT.
R-40-0.
DISPLAY 'SECTION 40 READ'.
NOTE ENTERED BY PERFORM FROM BASE-60.
PERFORM R-41-0 THRU R-41-0 7 TIMES.
PERFORM R-20-0 THRU R-20-9.
R-40-9.
EXIT.
R-41-0.
READ FILE-1 INTO RECl AT END
DISPLAY MSGHDR DISPLAY MSGEOF
ADD 4 TO ERCTFL MOVE 'E' TO ERRORSW
GO TO R-41-9.
IF REC-ID IS NOT EQUAL TO VER-ID
DISPLAY MSGHDR DISPLAY 'EXPECTED' VER-ID • FOUND' REC-ID
ADD 1 TO ERCTFL MOVE 'Eu TO ERRORSW
MOVE REC-ID TO VER-ID.
ADD 1 TO VER-NO.
R-41-9.
IF ERCTFL IS GREATER THAN 3
GO TO BASE-70.
SECTI0N-60 SECTION 60.
W-60-0.
DISPLAY ·SECTION 60 WRITE'.
NOTE ENTERED BY PERFORM FROM BASE-SECTION.
PERFORM W-61-0 THRU W-61-9 13 TIMES.
W-60-9.
EXIT.
W-61-0.
WRITE RECFDl FROM RECl INVALID KEY
DISPLAY MSGHDR
DISPLAY MSGEOX RECID
MOVE 'E' TO ERRORSW
GO TO BASE-50.
ADD 0001 TO REC-NO.
W-61-9.
EXIT.
R-60-0.
DISPLAY 'SECTION 60 READ'.
NOTE ENTERED BY GO TO FROM BASE-50.
PERFORM R-61-0 THRU R-61-9 13 TIMES.
GO TO R-30-0.
R-61-0.
READ FILE-1 INTO REC1 AT END
DISPLAY MSGHDR DISPLAY MSGEOF
ADD 4 TO ERCTFL MOVE 'E' TO ERRORSW
GO TO R-61-9.
00156510
00156520
001565:30
00156540
00156550
00156560
00156570
00156580
00156590
00156600
00156610
00156620
00156630
00156640
00156650
00156660
00156670
00156680
00156690
00156700
00156710
0015'6720
00156730
00156740
00156750
00156760
00156770
00156780
00156790
00156800
00156810
00156820
00156830
00156840
00156850
00156860
00156870
00156880
00156890
00156900
00156910
00156920
00156930
00156940
00156950
00156960
00156970
00156980
00156990
00157000
00157010
00157020
00157030
00157040
00157050
00157060
00157070
Sample segmentation Program (Part 4 of 14)
Using the segmentation Feature
383
00229
C0230
00231
00232
. CC233
e 0234
00235
C0236
00231
(;0238
00239
(;(;240
00241
002~2
0024':
00244
CC245
C024t
OC241
00248
OC249
00250
00251
00252
002!:3
00254
00255
e025€:
C0251
(;0258
00255
00260
002H
002€:2
002t3
U(;264
002(;5
00U6
00261
00268
002l:S
cone
00211
CC212
00213
00214
002361.1
If REC-ID I~ NuT EQUAL TO VER-ID
00237v
DISPLAY MSGnDR DIS~LAY 'EXPECTED' VER-ID ' FOUND' REC-ID
0023Bu
ADD 1 TO ER~Tfl MOVE 'E' TO ERRORSW
00239u
MOVE REC-IO TO VER-ID.
00240u
ADD 1 TO VEI(-Nu •
002411.1 R-61-9.
002421,)
IF ERCTFL I~ GREATER THAN 3
00L43u
GO TO BASE-/O.
002441.1 SECTION-BO SECTION BO.
002451.1 H-BO-O.
002461.1
DISPLAY 'SE~TION BO WRITE'.
002471.1
NOTE ENTEREU BY PERFORM FROM BASE-SECTION.
0024Bu
PERFORM W-ol-O THRU H-Bl-9 7 TIMES.
00249IJ
PERFORM W-21,)~0 THRU W-20-9.
(;e250u W-So-9.
00251u
EXIT •
00252v W-BI-0.
00,,531.1
WRITE RECfD~ FROM RECl INVALID KEY
002541,)
01 SPLAY MSGnDR
002551.1
DISPLAY MSG~OX RECIO
002561,)
MOVE 'E' TO ERkORSW
002571,)
GO TO BASE-jO.
0025Bv
ADO 0001 TO REC-NO.
002591.1 W-Bl-9.
00260v
EXIT.
002611,) R-SO-O.
002621.1
DISPLAY 'SE~TION 80 READ'.
002631.1
NOTE ENTEREu BY PERFORM FROM BASE-50.
002641.1
PERFORM R-S~-O THRU R-81-9 17 TIMES.
002651,) R-SO-9.
002661.1
EXIT.
00267IJ R-81-0.
OC26BI,)
READ fIlE-l INTO RECl AT END
002691,)
DISPLAY MSGHDR DISPLAY MSGEOF
00270u
ADD 4 TO ER~TFl MOVE 'E' TO ERRORSW
002711.1
GO TO R-Bl-~.
002721,)
IF REC-ID l~ NuT EQUAL TO VER-ID
OC273u
DISPLAY MSGHDR DISPLAY 'EXPECTED' VER-ID ' FOUND' REC-ID
00274u
ADD 1 TO ER~Tfl MOVE 'E' TO ERRORSW
00215U
MOVE REC-ID TO VER-ID.
002761,)
ADD 1 TO VE~-N().
002771,) R-BI-B.
0027BIJ
IF ERCTFL I~ GREATER THAN 3
002791.1
GO TO BASE-IO.
002BOl) R-Bl-9.
OC281U
EXIT •
I NTRNL NAME
DNM=2-,,~4
DNM=2-,,54
ONM=2-,,73
DNM=2-~93
ONM=2-~09
DNM=L-~25
ONM=2-~41
ONM=2-~57
ONM=2-~73
DNM=2-~90
DNM=2-'t09
ONM=2-.. ~5
ONM=2-'t'tl
ONM=2-'t52
ONM=2-'t70
DNM=2-490
DNM=3-uOO
ONM=3-1,).L6
Figure 154.
384
lVl
FO
01
S()URC~
FILE-~
RECfD~
77
17
17
77
77
17
ERRO~~W
01
02
03
03
02
66
01
02
03
03
ERCTFI..
MSGHDI(
MSGE01.
MSGEOf
MSGNE~
RECl
REC-Iu
REC-HIJ
REC-Nu
FILLEI(
RECIO
VER-R~C
VER-iu
VER-Hu
VER-Nu
NAME
8ASE
OCB=OI
BL=1
Bl=2
BL=2
BL=2
BL=2
Bl=2
BL=2
BL=2
BL=2
BL=2
BL=2
BL=2
BL=2
BL=2
BL=2
BL=2
BL=2
DISPL
000
000
001
003
019
030
062
080
080
080
084
088
080
OD8
008
OOB
OOC
00151080
00157090
00157100
00157110
00157120
00157130
00157140
00157150
00157160
00151170
00157180
00151190
00157200
00157210
00157220
00157230
00157240
00157250
00157260
00157270
00157280
00157290
00157300
00157310
00157320
00157330
00157340
00157350
00157360
00157370
00157380
00157390
00157400
00151410
00157420
00157430
00157440
00157450
00157460
00157470
00157480
00157500
00157510
INTRNL NAME
DNM=2-234
DNM=2-254
DNM=2-273
DNM=2-293
DNM=2-309
ONM=2-325
ONM=2-341
DNM=2-357
DNM=2-373
DNM=2-390
ONM=2-409
DNM=2-425
DNM=2-441
DNM=2-4-52
DNM=2-470
DNM=2-ft90
DNM=3-000
DNM=3-016
Sample Segmentation Program (Part 5 of 14)
DEFINITION
OS
OS
OS
OS
OS
OS
OS
OS
OS
OS
OS
OS
OS
OS
OS
83C
lC
2C
22C
36C
37C
23C
OCL~3
OCl8
4C
4C
75C
OCL~
oeLe
OClS
os 4:
OS 4C
USAGE
QSAM
DIS P
DISP
DISP-NM
DISP
DISP
DIS P
DISP
GPOUP
GP.OUP
DISP
DISP-NM
DISP
GROUP
GROllP
GROUP
DIS P
01 SP-NM
R
0
Q
M
F
MEMORY' MAP
TGT
00290
SAVE AREA
SWITCH
TALL Y
SORT SAVE
ENTRY-SAVE
SORT CORE SIZE
RET CODE
SORT RET
WORKING CELLS
SORT FILE S IlE
SORT MODE SIZE
PGT-VN TBL
TGT-VN TBL
RESERVED
LENGTH OF VN TB~
LABEL RET
RESERVED
DBG R14SAVE
COBOL I NDICATOK
A(INITU
DEBUG TABLE PTR
SUBCOM PTR
SORT-MESSAGE
SYSOUT DDNAME
RESERVED
COBOL 10
COMPILED POINTErt
COUNT TABLE ADUrtESS
RESERVED
DBG Rll SAVE
COUNT CHAIN ADurtESS
PRBLl CEll PTR
RESERVED
TA LENGTH
RESERVED
PCS LIT PTR
DEBUGGING
CD FOR INITIAL 4NPUT
OVERFLOW CEllS
Bl CEllS
DECBADR 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
PFMCTL CELLS
PFMSAV CEllS
VN CEllS
SAVi AREA =2
SAVE AREA =3
XSAS.., CEllS
XSA CEllS
PARAM CEllS
RPTSAV AREA
CHECKPT CTR
Figure 154.
00290
002D8
002DC
002EO
002E4
002E8
002EC
002EE
002FO
00420
00424
00428
0042C
00430
00434
00436
00437
00438
0043C
00440
00444
00448
0044C
00454
00455
00456
00458
0045C
00460
00468
0046C
00470
00414
00419
0041C
00484
00488
0048C
00490
00490
00498
00't98
004AO
004A8
004A8
004A8
004A8
004BO
004BO
004BO
004BO
004BO
00480
004D8
00520
00580
00580
00588
005B8
00588
00588
0,0588
Sample segmentation Program (Part 6 of 14)
Using the Segmentation Feature
385
LITERAL POOL (HEX)
OC6A~
OO~CO
(l 11+0)
(LIT+2J
OC704 (LTL+9,d
CC 13e (L Tl+l'rd J
CC 714 (L Tl+2&.14.J
007AC (lTL+2"O)
'START TEST ~EG-SAMPLEEND TEST SEG-SAMPlE UNSUCCESSFUL RU'
'NENO TEST S~G-SAMPlE SUCCESSFUL RUNSECTION 20 WRITESECTI'
'ON 20 READEAPECTED FOUND SECTION 30 WRITESECTIDN 30 REA'
'DSECTION 40 WRITESECTION 40 READSECTION 60 WRITESECTION '
'60 READSECT~ON 80 WRITESECTION 80 READ'
PGT
005CO
DEBUG LINKAGE AKEA
OVERFLOW CEllS
VIRTUAL CelLS
PROCEDURE NAME ~EllS
GENERATED NAME ~ElLS
DCB ADDRESS CEL~S
VNI CELLS
LITERALS
DISPLAY LITERAL~
PROCEDURE BLOCK CELLS
REGISTER
REG 6
REG 7
005CO
005CO
005C4
005E4
005E4
00610
00614
006A8
006CC
00704
AS~IGNHENT
Bl =2
BL =1
WORKING-STORAuE STARTS AT LOCATION OOOAO FOR A lENGTH OF OOOEO.
fFCCEOURE
PBL =
peL =1
B~OCK
.>TARTS
Figure 154.
386
ASSIGNMENT
REG J.1
AT
LOCATIOj'4 000708
STATEMENT 75
SEGMENT
ROOT
Sample Segmentation Program (Part 7 of 14)
***************ROOT ~EGMENT****************
1'1
15
7C
000108
*BASE-S EeT ION
000108
DISPLAY
000108
000108
()001OC
0001EO
0001E2
0001E4
0001ES
0001E8
0001Ee
0007EE
OPEN
a001FO
Figure 154.
PN=Ol
EQU
*
PN=02
START
58 BO C 214
58 FO C OOC
05 1F
001.11
10
OuuOl:>
Oe~OOl. OC
OOuO
FFt-F
5ij lU e 050
EQU
EQU
L
L
BALR
DC
DC
DC
DC
De
DC
L
*
*
11, 214( 0, 121
15,OOC(O,12)
1,15
X' 0001'
X'10'
X'OOOOlS'
X'OCOO010C'
X'OOOO'
X'FFFF'
1,050(0,12)
000048
000D4C
000D4E
58 FO C 01C
05 EF
41 FO B 51A
L
BALR
BC
lS,01Cl 0,12)
14,15
15,57 A( 0,11)
0·00000
000004
00C006
000008
oooooe
000014
000018
OOOOlA
00001E
000020
000024
000026
00002A
00002e
000030
000034
000038
00003C
000040
000044
000048
000084
000088
000090
00C098
90
18
05
4.5
STM
LR
BALR
BAL
DC
DC
BCR
LM
BCR
01
BCR
LA
BCR
ADCON
ADCON
ADCON
ADCON
AOCON
ADCON
AOCON
OS
DC
DC
DC
14,12,OOC(13)
5,13
15,0
8,010(0,15)
X'E2C5C7FOE2C1D4D7'
X' E5 E2D9Fl'
0,0
9,15,024(15)
15,15
034( 1) ,X'OZ'
15,14
15,001(0,0)
15,14
L4( INIT3)
L4( I NITU
L4(1 NI Tl)
l4( PGT)
L4 (TGTl
L4( START!
L4(INIT2)
15F
X'OOOOOOOO'
X'F1F74BF4F64BF3F6'
X'C1E4C74040F46B40'
X ' F 1 F9 F 1 F6 '
EC D OOC
SD
FO
80 F 010
E2~se7FOE2elD4D7
E5~2D9Fl
07 00
98 9F F 024
01 FF
96 02
034
07 FE
41 FO 0 001
07 FE
OOuOloEE
001.)00000
OO~OOOOO
00v005CO
00uOO~90
001.100108
OOUOlbAE
OOuOOOOO
Flf14bF4F64BF3F6
Clc4C74040F46B40
FU-9F7F6
1 NITl
DC
PBL=1
V( 1 LBOaSSO)
L IT+36
DCB=1
V(ILBOGD011
PN=016
Sample Segmentation Program (Part 8 of 14)
Using the Segmentation Feature
381
********* ******SEGME,d (Jf PTY 30****************
133
*SECT lON-30
134
*W-30-0
000052
135
131
DISPLAY
PERFuRM
000052
000052
000056
000058
000D5A
000058
000D5E
000062
000064
000066
58 FO C OOC
05 IF
OOul
10
00uOl0
OCuOO196
OOtiO
FFfF
02 03 o 268
000F90
000F94
000F96
58 FO C 01C
05 EF
47 FO B 7C2
o
PN=016
EQU
*
PN=017
EQU
L
BALR
DC
DC
DC
DC
DC
DC
MVC
*
15,00C( 0,12)
1,15
X'OOOl'
X'10'
X'OOOO10'
X'OCOOO196'
X'OOOO'
X'FFFF'
268(4,13),268(13)
L
BALR
BC
15,01CC 0,12)
14,15
15,7C2(0,llJ
2B8
V( ILBOOSSO)
LlT+174
PSV=9
VN=06
V(ILBOGOO1)
PN=024
***************SEGMENT OF PTY 40****************
167
*SECTlON-40
161:
*W-40-0
169
111
000F9A
DISPLA Y
PERFwkM
Figure 154.
388
PN=024
EQU
*
PN=025
000F9A
OOOF9A
000F9E
OOOFAO
000FA2
000FA3
000FA6
OOOFAA
OOOFAC
OOOFAE
58 FO C OOC
05 IF
OOul
10
00uOl0
OCIJ001B5
OOuO
FFi'F
02 03 D 210 o 200
EQU
L
BALR
DC
DC
DC
DC
DC
DC
MVC
*
15, ooce 0,12)
1,15
X'OOOl'
X'10'
X'000010'
X'OCOO01B5'
X'OOOO'
X'FFFF'
270(4,13),200(13)
001lF6
OOllFA
OOllFC
58 FO C 01C
05 EF
47 FO 8 A28
L
BALR
BC
15, Ole (0,12)
14,15
15,A28( 0,11)
sample segmentation Program (Part 9 of 14)
V( IlBOOSSO)
LlT+205
PSV=l1
V(ILBOGD01)
PN=033
VN=09
**********~****SEGHE''iT
203
*SECTlON-60
201t
*W-60-0
2G5
2C1
OISPI.AY
PERFuRM
OF PTY 60************ •• **
001200
PN=033
EQU
*
001200
001200
001204
001206
001208
001209
00120e
001210
001212
001214
PN=034
58 FO C ooe
05 1F
OOu1
10
00u010
0(u00104
OOuO
FFFF
02 03 0 21C o 2FO
EQU
L
BALR
DC
DC
DC
DC
DC
DC
MVC
*
15,OOC(O,12)
1,15
X'OOOl'
X'10'
X'OOOO10'
X' oeooo104'
X'OOOO'
X' FFFF'
21C(4,13),2FO(13)
00144A
00144E
001450
58 FO C 01C
05 EF
41 FO B C 1C
L
BALR
Be
15,01C(O,12)
14,15
15,C1C(0,11)
V(IlBOOSSO)
L1T+236
PSV=14
VN=013
V(ILBOGOO1)
PN=041
***·***********SEGME,,,T OF PlY 80****************
231
*SECTION-BO
238
*w-so-o
001454
23<;
241
DISPI..AY
PERFuRM
Figure 154.
0014"54
001454
001458
00145A
00145C
001450
001460
001464
001466
001468
001166
001168
00176C
00116E
001712
001114
001118
00177e
001180
001184
00118A
00118E
PN=041
EQU
*
PN=042
58 FO C OOC
05 1F
00u1
10
00u010
OCu001 F3
OOuO
FFfF
02 03 o 284 o 308
EQU
L
BAlR
DC
DC
De
DC
DC
DC
Mve
*
15,00e(0,12)
1,15
X'OOOl'
X'10'
X'000010'
X' OCOO01F3'
X' 0000'
X'FFFF'
284(4,13),308(13)
05
58
1i
41
1E
50
81
58
58
02
58
01
BAlR
L
LTR
BC
ALR
ST
BXlE
L
L
MVC
L
BCR
1,0
0,000(0,8)
0,0
8,-010( 0,11
0,11
0,000(0,8)
8,6,000 (11
6,204(0.13)
1,200(0,13)
290(144,13),054(12)
14,054(0,13)
15,14
10
00
00
80
OB
00
86
60
10
8F
EO
FE
8 000
010
8
1
0
0
0
0
000
000
204
200
290 C 054
054
V( ILBODSSO)
LIT+261
PSV=16
VN=016
Bl =2
"Bl =1
VN=Ol
VNI=l
Sample segmentation Program (Part 10 of 14)
Using the segmentation Peature
389
SOURCE
*STATlSTICS*
*OfT IONS IN EfFECT*
*OPT UlNS IN EFFECT*
*OPTIONS IN EFFECT*
*OPTIONS IN E~FEC T*
*OPT UlNS IN EfFECT*
*OPTlONS IN EFFECT*
DATA DIVISION STATEMENTS =
18
PROCEDURE DIVISION STATEME~TS =
21ft
165
SEQ,
12288 LI NECNT
SOURCE
131012 BUF
51 SPACEl, FLAGW,
SIZE
PMAP,
LOAD,
NODECK,
APOST,
NOTRUNC,
NOFlOW
SXREF,
DHAP,
NOClIST, NOSUPHAP, NOXREF,
NOTERH, NONUM, NOBATCH, NONAME, COMPILE=Ol, NOSTATE, NORESIOENT, NOOYNAM, NOlIB, NOSYNUX
OPTIMIZE, NOSYHDMP, NOTEST,
VERB,
ZIIB, SYST, NOENDJOB, NOlVL
DUMP, NOAOV , NOPRINT,
NOlST , NuFDECK,NOCDECK, lCOl2, 1120,
NOCOUNT, NOVBSUM, NOVBREF, lANGLVL(2J
RECORD~
=
=
CROSS-REFERENCE DICTIONARY
[ATA NAMES
DfFN
REFERENCE
ERCTFl
000056
ERROKSW
000055
000123
000231
000090
000197
000076
000191
000122
000108
000089
000212
000089
000121
000235
000094
000214
000082
000211
000156
000143
000107
000226
000131
000263
000109
000227
000083
000225
000192
000171
000122
000230
000151
000261
000123
000231
000088
000246
000226
000213
000126
000241
000161
000211
000121
000249
000092
000261
000262
000248
000142
000262
000125
000230
000111
000088
000261
000108
000088
000261
000126
000232
000146
000106
000128
000265
000180
000121
000159
000266
000216
000141
000160
000268
000251
000155
000143
000106
000117
000121
000213
000141
000248
000155
000125
000230
000129
000126
000232
000163
000128
000265
000199
000159
000266
000233
000160
000268
000269
F IlE-1
LJOOOft6
MSGEOF
MSGEOX
MSGt-OR
000060
000058
000051
MSGl\iEF
REC-HO
REC-ID
000062
000065
000064
REC-NU
RECFU1
000066
000053
RECIO
REC1
000068
000063
VEIl-HD
VEIl-I0
000071
(100070
VEFi-NO
VER-kEC
000072
000069
Figure 154.
390
sample seqmentation Proqram (Part 11 of 14)
000165
000193
000191
000201
000227
000144
000263
000106
000151
000261
000121
000161
000118
000193
000141
000155
000175
000156
000266
000160
000116
000192
000196
000162
000195
0001~6
000198
000229
000175
000191
000211
000225
0002H
000115
000191
000211
000225
00024-6
000162
000195
000196
('100198
000229
PROCEDURE NAMES
DEFN
B~ S E-SEC T ION
BASE-50
BASE-60
eASE-l0
000014
000081
000086
e~SE-90
(JOO093
000114
000118
000120
000130
000149
000154
000164
000183
000188
000190
000200
000219
000224
000234
000254
000258
000260
000210
000213
000098
000133
000161
000203
000231
uOO099
000103
000105
000112
000134
000138
000140
000141
000168
000112
uOO114
000181
000204
000208
000210
000217
000238
000243
(J00245
000252
R-20-0
~-20-9
R-21-0
R-21-9
~-30-0
R-31-0
R-31-9
R-40-0
R-40-9
R-41-0
R-H-9
R-60-0
R-61-0
R-H-9
R-So-O
R-80-9
R-81-0
R-81-8
R-Si-9
S ECTlON-20
SECTlON-30
SECTlON-40
SECT lON-60
SECTION-80
111-20·0
W-20-9
"-21-0
101-21-9
101-30-0
"-3(;-9
W-31-0
"-31-9
w-40-0
W-40-9
k-H-O
.. -41-9
101-60-0
"-6C-9
W-61-0
k-H-9
"-8C-0
.. -80-9
.. -81-0
101-81-9
Figure 154.
000D91
REFERENCE
000110
000153
000088
000181
000181
000111
000111
000223
000152
000152
000081
000081
000186
000194
000085
000222
000222
000084
0000S4
000251
000251
000145
000119
000215
000250
000132
000166
000202
000236
000272
000124
000158
000228
000264
000132
000166
000202
000236
0002 .. 2
000242
000102
000102
000018
000018
000131
000131
000080
000080
000111
000111
000019
000019
000201
000201
000071
000011
000241
000241
Sa.pIe seqmentation Program (Part 12 of 14)
Using the segmentation Feature
391
F64 ... LEVEL LINKAGE EDITOR OPTIONS SPECIFI ED LIST ,~Bj:F_
DEfAULT OPTION(S) USED - SllE=(196608,65536)
ENTRY SEGOSAMP
I EWOOOO
J EW0201
CROSS REFERENCE TABLE
ENTRY
COI\TROL SECTION
NAME
ORIGIN
SEGOSAMP
00
",190
IlBOCOMO*
LENGTH
1790
169
IleOOSS *
1900
40A
lLEOEXT *
1010
50
1
JlBOGoO *
1060
114
1
Il80QIO *
lE18
56E
llBDSRV *
23E8
48E
IlBOSYN *
2818
440
ILBGBEG *
2CB8
128
IleOCHN *
20EO
1BO
IUOCHM *
2f90
388
ILBOMSG *
3320
F2
SEG. NO.
1
1
NAME
I LBOCOM
1790
ILBOoSSO
1902
IlBOEXTO
NAME
LOCATION
NAME
lOCATION
ILBOEXT1
1016
1062
ILBOGoOl
1066
ILBOGo02
lO6A
IlBOQIOO
1E1A
fLBOSRVO
ILBOSRV1
23F2
23F6
ILBOSR5
ILBOSTP1
23F2
23F6
IL80SR3
fLBOST
23F2
23FA
ILBOSR
ILBOSTPO
23F2
23FA
Il80SYNO
ILBOSYN4
281A
288A
IlBOSYN1
ILBOSYN5
281E
288E
flBOSYN2
2882
IlBOSYN3
2~86
I L808EGO
2CBA
ILBOCHNO
2DE2
ILBOCMMO
2f92
IlBOCMM1
2F96
IlBOMSGO
3322
SEG. NO.
1
1
1
1
1
1
1
LOCATION
5C8
500
508
5EO
2738
2140
2148
REfeRS TO SYMBOL IN CONTROL SECTION SEG. NO.
ILBOSR5
Il~OSRIf
1
ILBOSYN1
fLBOSYN
1
ILBOQIOO
ILBOQIO
1
ILBOSRV1
ILBOSRV
1
fLBOCOM
ILBOCO'40
1
Il808EGO
ILBOBEG
1
ILBOSN02
SUNRESOLVEOC W)
1
3418
TGTAL LENGTH
** .... GO
DOES NOT EXIST BUT HAS BEEN ADDED TO DATA SET
All IHORIZATION CODE IS
o.
392
lOCATION
1012
REfeRS TO SYMBOL IN CONTROL SEC TI ON
ILBOSRV
IL8GSRVO
I LBOoSS
ILBOOSSO
sec
ILBOEXTO
ILBOEXT
504
IL8CGOO1
ILBOGOO
50C
ILBOCllMO
I LBOCOMO
448
1L80CHM
ILBOCMMO
~13C
I lBOMSGO
I LBOMSG
Li44
I LBOCHN
IlBOCHNO
2C40
El\lRY ADDRESS
00
Figure 154.
NAME
IlBOGoOO
1
lOCAT ION
5C4
LOCATION
Sample segmentation Program (Part 13 of 14)
START TEST SEG-SAMPLE
SECTION 80 WRITE
SECTION 20 WRITE
SECTION 30 WRITE
SECTION 60 WRITE
SECTION 40 WRITE
SECTION 80 READ
SECTION 60 READ
SECTION 30 READ
SECTION 40 READ
SECTION 20 READ
END TEST SEG-SAMPLE SUCCESSFUL RUN
Figure 154.
Sample Seg.entation Program (Part 14 of 14)
Using the Segmentation Feature
393
The IBM operating system Checkpoint/
Restart feature is designed to be used with
programs running for an extended period of
time when interruptions ma y halt processing
before the end of the job. The feature may
be used when the programmer anticipates any
type of interruption, i.e., interruptions
caused by machine malfunctions,
input/output errors, or intentional
operator intervention, etc. It allows the
interrupted program to be restarted at the
job step or at a point other than at the
beginning of the job step. The feature
consists of two routines: Checkpoint and
Restart.
The Check.E.QinL£2 uti!!.~ is invoked from
the COBOL load module containing the user's
program.
It moves information stored in
registers and in main storage into a
checkpoint record at user-designated points
during execution of the program. The
programmer specifies these points using the
COBOL RERUN clause in the Environment
Division.
The Restart routine restarts an
interrupted program:--Restart can occur at
the beginning of a job step, or at a
checkpoint if a checkpoint record has been
written.
The checkpoint record will
contain all information necessary to
restart the program.
Restart can be
initiated at any time after the program was
interrupted; that is, 1t may be run
immediately after the interrupt has
occurred, as an automatic restart, or at a
later time convenient to the programmer, as
a deferred testart.
The COBOL RERUN clause provides linkage
to the system checkpoint routine. Hence,
any cautions and restrictions on the use of
tbe system Checkpoint/Restart feature also
apply to the use of the RERUN clause.
The Checkpoint/Restart feature is fully
described in the publication Q.~LVS
Ch~£JsEgi n!LR~ ta .rt.
In order to initiate a checkpoint, the
programmer uses job control statements and
the COBOL RERUN clause. The programmer
associates each RERUN clause vit.h a
particular COBOL file.
The RERUN clause
indicates that a checkpoint record is to be
written onto a checkpoint data set whenever
a specified number of records on that file
are processed or when end of volume is
reached while processing a file.
The
programmer decides when he wants the
checkpoints taken as he codes the RERON
clause. T he checkpoint records are written
on the checkpoint data set defined by the
DD statement and are referenced by
system-name in the RERUN clause.. The DO
statement describes both a checkpoint data
set and a checkpoint method.
Checkpoint records on ASCII-collated
sorts can be taken, but the system-name
indicating the checkpoint data set must not
specify an ASCII file.
Note: If checkpoints are to be taken
durIng a sorting operation, a DD statement
called SORTCKPT must be added when the
program is executed.
The programmer may elect to store single
or multiple checkpoints.
2in51le: Only one checkpoint. record exists
at any given time.
After the first
checkpoint record is written, any
succeeding checkpoint record overlays the
previous one. This method is acceptable
for most programs.
It offers the advantage
of saving space on the checkpoint data set
and allows the programmer to restart his
program at the latest checkpoint.
~ltip~multiEle
contigYQY§l:
Checkpoints are recorded and numbered
sequen tially. Each checkpoint is sa ved.
This method is used when the programmer may
wish to restart a program at a checkpoint
other than the latest one taken.
DD STATEftENT FORMATS
The programmer records checkpoints on
tape or direct access devices.
Following
are the DD formats to define checkpoint
data sets.
For Tape:
r-----------------------------------------,XI
I//ddname DD DSNAME=data-set-name.
1//
1//
VOLUME=SER=volser,
UNIT=deviceno_
1//
XI
XI
MOD
is specified for the multiple
contiguous checkpoint method.
NEW
is specified for the single checkpoint
method.
xl
DISP=( {NEW} w PASS >.
1
MOD
I
1//
DCB=(TRTCH=C>.LABEL=(.NL)
l _________________________________________
JI
PASS
is specified in order to prevent
deletion of the data set at the
successful completion of the job step,
unless it is the last step in the job.
If it is the last step, the data set
viII be deleted with PASS.
Note: The DCB parameter is necessary only
for 7-track tape conversion; for 9-track
tape it is not used.
KEEP
is specified in order to keep the data
set if the job step abnormally
terminated and may be restarted.
For Mass Storage:
r-----------------------------------------,
DD DSNAME=data-set-name.
XI
!//ddname
1//
1//
1//
1//
VOLUME=(PRIVATE,RETAIN,
SPACE=(subparms>~
XI
XI
XI
XI
://
DISP={ {NEW} "PASS,KEEP)
X:
SER=volser>~
UNIT=deviceno,
The following listings are examples that
define checkpoint data sets.
Il _________________________________________
MOD
JI
where:
ddname
is the same as the ddname portion of
the system-name used in the COBOL
RERUN clause to provide a link to the
DD statement.
• To write single checkpoint records
using tape:
IICHECKPT
II
II
II
subparms
specifies the amount of track space
needed for the data,.set.
x
X
X
RERUN ON UT-2400-S-CHECKPT EVERY
5000 RECORDS OF ACCT-FILE.
• To wri te single checkpoint records
using disk (note that more than one
data set may share the same
external-name) :
IICHEK
II
II
deviceno
identifies the device.
For tape it
indicates the device number for
7-track or 9-track tape. For mass
storage. it indicates the device
number for disk or drum.
VOLUME=SER=ND003,
UNIT=2400,DISP=(NEW,KEEP),
LABEL= (. NL)
ENVIRONMENT DIVISION.
da ta-set-name
is the name given to each particular
data :.et used to write checkpoint
records. This name identifies the
checkpoint data set to the Restart
procedure (see "Restarting a
Program .t).
volser
identifies the volume by serial
number.
DD DSNAME=CHECK',
II
II
DD
DSNAME=CBECK2,
X
VOLUME=(PRIVATE,RETAIN,
X
SER=DB030,
UNIT=2314,DISP=(NEW,KEEP),
SPACE= (TRK,300)
X
X
ENVIRONMENT DIVISION.
BERUN ON UT-2314-S-CHEK EVERY
20000 RECORDS OF PAICODE.
RERUN ON UT-2314-S-CHEK EVERY
30000 RECORD OF IN-FILE.
Using the Checkpoint/Restart Feature
395
• To write multiple contiguous checkpoint
records (on tape):
IICHEKPT
II
II
II
nD
DSNAM E=CHECK 3,
VOLUME=SER=111111,
UNIT=2400,DISP=(MOD,PASS),
LABEL= (, NL)
x
X
X
ENV IRONlIENT DIVIS 10 N.
RERUN ON UT-2400-S-CHEKPT EVERY
10000 RECORDS OF PAY-FILE.
[IHJ004I jobname (ddname,unit,volser)
CHKPT checkid]
where checkid is the identification name of
the checkpoint taken.
Checkid is assigned
by the control program as an 8-digit
number. The first digit is the letter C,
followed by a decimal number indicating the
checkpoint. For example, checkid C0000004
indicates the fourth checkpoint ta ken in
the job step.
RESTARTING A PROGRAM
.HQ!.~:A
checkpoint data set must have
sequential or partitioned organization.
The system Restart routine retrieves the
information recorded in a checkpoint
record, restores the contents of main
storage and all registers.
DESIGNING A CHECKPOINT
The Restart routine can be initiated in
one of two ways:
The programmer should design his
checkpoints at critical points in his
program so that data may be easily
reconstructed.
For example, in a program
using mass storage files, changes to
records in these files will replace
previous information; thus the programmer
should be sure he can identify previously
processed records.
Assume that a mass
storage file contains loan records that
periodically are updated for interest due.
If a checkpoint is taken, records are
updated, and then the proqram is
interrupted, the records updated after the
last checkpoint will be updated a second
time in error unless the programmer
controls this condi tion.
(He may set up a
date field for each record and update the
date each time the record is processed.
Then, after the restart, by in vestigating
the date field he can determine whether or
not the record was previously processed.)
For efficient re posi tion ing of a print
file, the programmer should take
checkpoints on that file only after
printing the last line of a page. At
system generation time, those ABEND codes
for which the checkpoints are desired
(DEFAULT) must be specified.
MESSAGES GENERATED DURING CHECKPOINT
The system checkpoint routine advises
the operator of the stat us of the
checkpoints taken by displaying informative
messages on the console.
When a checkpoint has been successfully
completed. the following message will be
displayed~
396
• Automatically at the time an
in terr uption stopped the program
• At a later time as a deferred restart
The type of restart is determined by the RD
parameter of the job control language.
The iD parameter may appear on either
the JOB or the EXEC sta tement. If coded on
the JOB statement, the parameter overrides
any RD parameters on the EXEC statement.
If the programmer wishes to have his
program restart automatically, he codes
RD=R or Ro=RNC. RD=R indica tes that
restart is to occur at the latest
checkpoint. The programmer should specify
the RERUN clause for at least one data set
in his program in order to record
checkpoints. If no checkpoint is taken
prior to interruption, restart occurs at
the beginning of the job step.
RD=RNC
indicates that no checkpoint is to be
written and any restart will occur at the
beginning of the job step.
In this case,
RERUN clauses are unnecessary; if any are
present, they are ignored.
If the RD
parameter is omitted, the CHKPT macro
instruction remains activated, and
checkpoints may be taken during processing.
If an interrupt occurs after the first
checkpoint, automatic restart will occur.
Thus, if the user does not want automatic
restart, he should always include the RO
pa rame ter wi th a code of ei ther RO=NR or
RD=NC, both of which suppress the automatic
re s·tar t proced ure.
If the programmer wishes his program to
be restarted on a deferred basis, he skould
code the BD parameter as RD=NB. This form
of the parameter suppresses automatic
restart but allows a checkpoint record to
be written provided a RERUN clause has been
specified.. At restart time, the programmer
lIay choose to restart his program at a
checkpoint other than at the beginning of
the job step ..
The programmer ma y also elect to
suppress both restart and writing
checkpoints.
By coding RD=NC, the
programmer, in effect, is ignoring the
features of the CheckpointlRestart
facil~ty.
Automatic Restart
Automatic Restart occurs only at the
latest checkpoint taken.
(I f no checkpoint
was taken before interruption, Automatic
Restart occurs at the beginning of the job
step) •
In order to restart automatically, a
program must satisfy the following
conditions.
• A program must request restart by using
the RD parameter or by taking a
chec kpoi nt.
• An ABEND that terminated the job must
return a code eligible to cause
restart.
(For further discussion on
this requirement, see the publication
Whe neve r au toma tic restart is to occu r,
the system viII .reposition all devices
except unit-record machines.
Deferred restart may occur at any
checkpoint, not necessarily the la test one
taken.
The programmer requests a deferred
restart by means of the RESTART paraMeter
on the JOB card aarl a SYSCHK DD statement
to identify the checkpoint data set. The
formats for these statements are as
follows:
x
Iljobname JOB , MSGLEVEL=1.
RESTART={request,[checkid])
II
//SYSCHK DD DSNAME=data-set.-name*
x
DISP=OLD,UNIT-deviceno,
X
II
VOLOME=SER=volser
II
where:
MSGLEVEL=l (or MSGLEVEL= (1. y) where y is
either 0 or 1)
is required.
RESTART=(request,[checkid])
identifies the particular checkpoint
at which restart is to occur. Request
may take one of the following forms:
*
to indicate restart at the beginning
of the job
stepname to indicate restart at the
beginning of a job step
~I~_Checkpoint/Res1a£t.)
• The operator authorizes the restart,
with the following pro'cedure'!
The system displays the following
message to request a uthoriza tion of the
restart:
xxIEF225D SHOULD
jobname.stepname.procstep
RESTART [checkid]
The operator must reply in the
following form:
REP LY xx, • {YES I NOJ HOLD} •
where YES authorizes restart, NO
prevents restart, and HOLD defers
restart until the operator issues a
RELEASE command, at which time restart
will occ uc.
stepname.procstep to indicate restart
at a procedure step within the
jobstep
checkid
identifies the checkpoint where
restart is to occur.
SYSCHK
is the DDNAME used to identify a
checkpoint data set to the control
program. The SYSCHK DD statement must
immediately precede the first. EXEC
sta tement of the resubmi tted job, and
must follow any JOBLIB statement.
da ta-set-name
must be the same name that was used
when the checkpoint was taken. It
identifies the checkpoint data set
Using the CheckpointlRestart Feature
397
deviceno and volser
identify the device number and the
volume serial number containing the
checkpoint data set.
following the restart step if they
contai.n the form stepname or
stepname.procstep referring to a step
preceding the restart step. However,
if these parameters are used, the
preceding step referred to must be
specified in the resubmitted deck.
As an example illustrating the use of
these job control statements, a restart of
the GO step of a COBUCLG procedure, at
checkpoint identifier (CHECKID) CODODOD],
might appear as follows:
Iljobname JO B
II
1/
/ISYSCHK DD
//
1/
,I1SGLEVEL= 1,
RESTART=
(stepname.GO,COODODD3)
DSNAME=CHEKPT,
DISP=OLD,UNIT=2400,
VOLUI1E=SER=111111
x
X
x
X
When a deferred restart has been
successfully completed, the system will
display the following message on the
console:
IHJ0081
johname
RESTARTED
Control is then given to the user's program
that executes in a normal manner.
CHECKPOINT/RESTART DATA SETS
{DD statements similar to original deck}
The Restart routine uses information
from DD statements in the resubmitted job
to reset files for use after restart;
therefore, care should be taken with any DD
statements that may affect the execution of
the restarted job step. Attention should
be paid to the following:
• During the original execution, a data
set meant to be deleted at the end of a
job step should conditionally be
defined as PASS rather than DELETE in
order to be available if an
interruption fo.rces a restart. If the
restart is at the beginning of a step,
a data set created in the original
execution (defined as NEW on a DD
statement) must be scratched prior to
the restart. If the data set is not
deleted, the DD statement must be
changed to define it as OLD.
• At restart time, input data sets on
cards should be positioned as they were
at the time of the checkpoint. Input
data sets on tape or direct access
devices will be automatically
reposi tioned by the system.
• At restart time, the EXEC statement
parameters PG~ and COND, and the DD
statement parameters SUBALLOC and
YOLUME=REF Jlust not be used in steps
If the RERUN clause was executed during
the original execution of the processing
program, checkpoint entries were written on
a checkpoint data set. To resubmit a job
for restart ~ben execution is to be resumed
at a particular checkpoint, an additional
DD statement must be included. This DD
statement describes the data set on which
the checkpoint entry was written and it
must have the ddname SYSCHK. The SYSCHK DD
statement must immediately precede the
first EXEC statement of the resubmitted job
and must follow the DD statement named
JOBLIB, if one is present.
For both deferred and automatic
checkpoint/restart, if Direct SYSOUT writer
for the restarted job vas active at the
time the checkpoint was was taken, it must
be available for the job to restart. For
further in format ion, see the publication
Q~VS_~hg~kpoin1LBg§~~i·
If the checkpoint data set is
multivolume, the sequence number of the
volume on which the checkpoint entry vas
written must be included in the VOLUME
parameter. If the checkpoint data set is
on a 7-track magnetic tape with nonstandard
labels or no labels, the SYSCHK DD
statement must con tain DCB: (TRTCH=C, ••• ) •
Figure 155 illustrates a sequence of
control statements for restarting a job.
r-----------------------------------------------.----------JOB
MSGLEVEL=l ,REGION=80K, RESTART= (STEP1 ,CHECKPT4)
II/PAYROLL
IllJo.BLIB
IIISYSCHK
1//
II/STEP1
Figure 155.
398
DD
DD
EXEC
DS NAME=PRIY. LIB3,DISP=OLD
DSNAME=CHKPTLIB, UNIT=2314, VOL=SER=456789,
DI.SP= (OLD, KEEP)
PGI1=PROG4,TI!E=5
Restarting a Job at a Specific Checkpoint step
1
I•
I
t
I
------------------------~
x
If a SYSCHK DD statement is present in a
job and the JOB statement does not contain
the RESTART parameter, the SYSCHK DD
statement is ignored. If a RESTART
parameter without the CHECKID subparameter
(as in Figure 157) is included in a job, a
SYSCHK DD statement must not appear before
the first EXEC statement for a job.
Figure 156 illustrates the use of the RD
parameter. Here, the RD parameter requests
step restart for any abnormally terminated
job step. The DO statement DDCKPNT defines
a checkpoint data set. For this step, once
a RERUN clause is executed, only automatic
checkpoint restart can occur, unless a
CHKPT cancel is issued.
from the restarted job. The RESTART
parameter has been added to the JOB
statement and indicates that restart is to
begin with the first job step. The DD
statement WORK originally assigned a
conditional disposition of KEEP for this
data set. If this step did not abnormally
terminate during the original execution,
the data set was deleted and no
modifications need be made to this
statement. If the step did abnormally
terminate, the data set vas kept. In this
case, define a new data set as shown in
Figure 157, or change the data set·s status
to OLD before resubmitting the job. A new
data set has also been defined as the
check.point data set.
Pigure 157 illustrates those
modifications that might be made to control
state.ents before resubmitting the job for
step restart. ~he job name has been
changed to distinguish the original job
Figure 158 illustrates those
modifications that might be made to control
statements before resubmitting the job for
checkpoint restart.
rIIIJ1234
,
JOB
EXEC
DD
386,SftITH, ftSGLEVEL= l,RD=R
"YPROG
IIIS1
DSNAftE=INVENT,UNIT=2400,DISP=OLD,VOLUftE=SER=91468, X
IIIINDATA
LABEL=RETPD=14
III
DD
SYSOUT=A
IIIBEPORT
DD
DSNAME=T91468, DISP"= (,., KEEP) , UNIT=SYSDA,
X
IIIWORK
SPACE=(3000, (5000,500» ,VOLUKE=(PBIVATE,RETAIN,,6)
'II
DD
UNIT=2400,DISP={ftOD,PASS,CATLG),DSNAKE=C91468,LABEL=(,NL)
IIIDDCKPNT
L---______________
__
,
,,
,
I
I
I
I
---I
Figure 156.
Using the RD Parameter
,,
,
r------------------------IIIJ3412
JOB
386,SKITH,ftSGLEVEL=1,RD=R,RESTART=*
IIIS1
IIIINDATA
EXEC
DD
IIIREPORT
IIIWORK
DD
DD
III
III
MYPROG
DSNAPlE=INVENT,UNIT=2400,DISP=OLD,VOLUKE=SER=91468,
LABEL=BETPD=14
SYSOUT=A
DSNAftE=S91468,DISP=("KEEP) ,UNIT=SYSDA,
X
X
SPACE=(JOOO,(5000,500»,VOLUME=(PRIVATE,RETAIN,,~
'IIDDCHKPHT
DD
UNIT=2400, DISP= (PlOD,PASS, CATLG) ,DSBAftE=R91468 ,LABEL= (, Nt)
Figure 157.
ftodifying Control Statements Before Resubmitting for step Restart
Using the Checkpoint/Restart Feature
I
I
I
I
J
J
399
----,
r-
II/J3412
JOB
II/SYSCHK
DD
IIIS1
II/INDATA
III
EXEC
DD
IIIREPORT
II/WORK
DD
IIIDDCKPNT
DD
III
III
DD
386,SMITH,8SGLEVEL=1,RD=R,RESTART=(*,C0000002)
DSNAltE=C91468, DISP=OL D
ltYPROG
DSHA~E=IBVENT,UNIT=2400,DISP=OLD,
VOLtH!E=SER=91468, LABEL=RETPD= 14
5YSOUT=A
DSHAME=T91468,DISP=("KEEP),UNIT=SYSDA,
SPACE= (3000. (5000,500» , VOLUftE= (PBIVATE, RETAIN" 6)
UNIT=2400, DISP= (MOD ,KEEP, CATLG) ,DSNAltE=C91468,
LABEL = (, NL)
I
I
f
X
I
I
X
J
,
.I
80difying control statements Before Resubmitting for Checkpoint Restart
The job name has been changed to
distinguish the original job from the
restarted job. The RESTART parameter has
been added to the JOB statement and
indicates that restart is to begin with the
first step at the checkpoint entry named
C0000002. The DD statement DDCKPNT
originally assigned a conditional
disposition of CATLG for the checkpoint
data set. If this step did not abnormally
terminate during the original execution,
the data set vas kept. In this case, the
SYSCHK DD statement must contain all of the
information necessary to retrieve the
400
I
t
L-
Figure 158.
,
x:
checkpoint
abnormally
cataloged.
parameters
statement,
DSNAl'tE and
!iQ.t~:
data set. If the job did
terminate, the data set was
In this case, the only
required on the SYSCHK DD
as shown in Figure 158, are the
DISP parameters.
If a checkpoint is taken in a job
that is runnin~ when V=R is specified, the
job cannot be restarted antil adequa te
nonpageable dynamic storage becomes
available.
A communication environ.ent consists of
a central computer. reaote or local'
stations. and communication lines between
such stations and the central computer.
Use of the Communication Feature enables
the COBOL programmer to create
device-independent programs for
communication applications.
Communication applications requi~e a
spec ia 1. user-vritte n assembler-language
program that controls the flow of data
between the central computer and the remote
stations. This message control program
(RCP) also performs such additional tasks
required only in a communication
environment as dial-up. polling, (or
contacting each remote station). and
synchronization, as veIl as such
device-dependent tasks as character
translation and insertion of control
characters.
The KCP consists of routines that
identify the communication network to the
operating system, establish line control
between the computer and the various kinds
of stations, and process messages in a vay
tailored to meet the needs of the user.
A
"message" is the data flowing either froa a
remote station to the central computer or
from the central computer to a remote
station.
An KCP is required in a
communication system operating under TCAM.
Depending on the needs of the
installation. one or more COBOL programs
may be required to process the contents of
the messages. An example of a job needing
no application program is message
switching, an operation consisting only of
forwarding messages unaltered (except for
such processing as the KCP may perform) to
one or more other stations~
The MCP itself can perform limited
processing (for example, examination of the
first portion of a message to determine
certain routine information and message
code translation). Further, the RCP can
II station whose control unit is connected
directly to a computer data channel by a
local cable.
obtain the time of day a message is
received from a station and transmit this
information to a COBOL program. It can
also check the input messaqes to determine
whether an error message should be sent to
the des~gnated station.
This section describes the flow of a
single-segment message through a system
operating under TeAM, from the time it is
entered at the remote station to its
transmission to a destination station.
Figure 159 outlines the flow of a message
segment through a TCAM system. The
encircled numerals in the flow diagram
correspond to the steps listed in the
description that follows.
Because of the possible variety of both
message types and destinations, it is often
helpful for the user to precede the message
"text" with a message "header" so that the
user can transmit to the MCP information
essential to handling the text. It is the
user who determines which part of the
message is the header and which part ls the
text.
steps 1 ang~:
The input message is
prepared at the remote station and entered
on the line. The message may be keyed in,
or i t may be entered from a card or tape
reader. The originating station enters the
message via a communication line, the
transmission control unit, and the
multiplexor channel.
step 3: The message enters the central
computer and is stored, together with the
internally generated buffer prefix, in a
main storage buffer.
As message data fills
the buffer, TCAM inserts the necessary
control information in the prefix.
Before
the message characters are placed in the
first buffer, TCI~ may reserve space in the
buffer for later insertion of the time,
date, and sequence number for the message,
and for control characters, if appropriate.
Once a buffer is filled with the first
segment of the message, the MCP controls
the flow of tbe buffer through the
communication network. The heart of the
MCP consists of the message handlers (M8)
constructed by the user to process messages
from the various lines or line groups.
Using the Communication Feature
401
MCP
buffer
Figure 159.
402
Outgoing Group
of MH specified
for the line
Message Flow between Remote sta tions and a COBOL Program
~tep-!:
The incoming message is routed to
the incoming group of the ~H specified for
the line (by the KH= operand of the DCB
macro for the line group in which the line
is included). The message is passed, a
buffer at a time, through the incoming
group, which performs sach user-selected
functions on the message header as origin
checking, and input sequence-number
checking. Similarly, such functions may be
performed for the message segment as
translating the segment from line code to
EBCDIC and causing an error message to be
sent to the originating station when the
incoming group detects any user-specified
error in the segment. In performing its
functions, the incoming group of the MH
scans and processes header fields based on
the relative order of the individual KH
macro instructions. The incoming group
then rOll tes the message to the destination
queue.
st~-2:
After processing by the incoming
group, the message is placed on a
destination queue for either the COBOL
program, for processing, or an accepting
station.
(If no message processing is
necessary, the next action performed is
that described in step 13.)
All messages
requiring text processing are routed to t.he
destination queue for the COBOL program
that processes that type of message. The
user controls this routing via the message
header by placing the name of the
destination queue for the. COBOL program in
a destination field of the message header
or by MH macro instructions such as ftSGTYPE
that ma y be used t.o direct messages of a
particular type t.o a particular queue.
~t~L2.a.2L-~!i:
The message from a
destination queue for a COBOL program is
placed in a main-storaqe buffer; the
outgoing group of an MH (the MH .is created
especially for the application program and
is assigned to it by the MH= operand of the
PCB macro in the KCP) places it on the
read-ahead queue, a special queue that
allows overlap of KCP and application
program processing of messages queued for a
particular destination.
il~:
Each time the COBOL program issues
a RECEIVE statement, TCAM passes message
data from the read-ahead queue to a
user-specifiedvork area in the COBOL
program.
As the message d~ta is moved to
the work area, TCAK removes the header or
text. prefix from the buffer.
After
receiving the message data, the COBOL
program processes it as required and then
genera tes a response message, if any is to
be returned to a station. The destination
queues act as buffers between the COBOL TP
program and the remote stations. Thus, the
COBOL communication program can accept
messages from Rep destination queues and
place these messages in MCP destination
queues as if th.e queues were seque ntia 1
files within a conventional COBOL program.
(The sample COBOL program TESTTP 1, shown in
Figure 165, reads a sequential file and
then sends each record to a destination
queue, creating a TCAM data set for the
COBOL communication program TESTTP2, shown
in Figure 169, making it possible to test a
COBOL TP program without terminals.)
~l~~lQ~nd
11: When the COBOL program
issues a SEND statement, TCAM moves the
data from the work area into an MCP buffer
before it is handled by the incoming group
of the MH designed for the COBOL program.
A header or text buffer prefix is created
when data is moved to the buffer, as for
other incominq messages. As the message
data fills the buffer, TCAM inserts control
information in the prefix field. The
response message generated by an
application program can be any
user-selected length.
After the buffer is
filled. the message is handled by the
incoming group of the MH assigned to the
application program by the I1H= operand of
the PCB macro instruction that provides an
interface between the MCP and the COBOL
program.
ll~lLl~:
If further processing of the
message is required in another application
program, the message is queued for that
destination (and Steps 5 through 11 are
repeated). If however, no other
application program processing is needed,
the processed message is placed on the
destination queue for an accepting station.
The destination is that specified by the
COBOL programmer in the file referenced by
the SYMBOLIC DESTINATION clause of the
output CD.
It may be for an application
program or a station.
St.ID2-11: The destination queue for an
accepting station, like the destination
queue for an application program, is a part
of the message queues data set. TCAM
obtains message segments from the
destination queue on a first-ended
first-out (PEFO) basis within priority
groups.
~~~~ng_l~:
The message segment is
placed in a buffer, and the outgoing group
of the MH specified for the line processes
the message. The ~H performs such
user-selected functions as converting the
code of the message to the transmission
code for the station (if necessary),
inserting the time and data in ~he heaqer,
10gg1n 9 messages, and u pda t ing Ilessage
counts. These operations are performed iq
the buffers that receive the message
segments from the destination queue.
Using the Communication
Fe~ture
4Q3
st~-1§':
TCAM transmits the message. minus
the header and text prefixes. to the
appropriate station.
• Determine the appropriate destination
queue for a message and route the
message to that queue
• Queue the message in the appropriate
destination queue
jiITIN~!
MESSAGE CONTROL
PROGRA~
The COBOL programmer can write a message
control program (MCP) designed specifically
for his communication needs using
telecommunications access methods (TCAM)
macro instructions. Using a group of TCAM
macro instructions, the user follows in
general the coding requirements and
restrictions of any other
assembler-language macro instruction.
Guidelines f orwri ti ng an MCP are contained
in the publication as/vs TCAM Pr09£~~~
§.uid~.
The uper must tailor these general
sta t.ements to meet t he needs of the
installa tion.
The sample message control program that
appears in Figure 160 in thi~ cbapter is a
hypothetical program designed for specific
COBOL applications.
The needs of the user
will undoubtedly vary from installation to
installation.
Nevertheless, the sample MCP
together with the sample COBOL programs
TESTTP1 and TESTTP2 (shown in Figures 168
and 169) ca~ serve as an excellent example
of COBOL programs and an MCP written for
teleprocessing applications.
Note that
references to LOG are shown as comments,
which would have to be changed to valid
statements if that feature was required.
If the MCP to be written must conform to
the 1974 ANS standard, then Figure 160 must
be modified (as explained later in this
section) •
• Place response messages generated by
application programs on queues for
subsequent transmission
• Retrieve messages from destination
queues and prepare them for
transmission to remote stations
• Perform message-editing functions for
outgoing messages
• Take periodic checkpoints of the system
• Provide operator-to-system
communications through system control
terminals
• Initiate corrective action when an
error or unusual condition is detected
• Cancel incoming messages containing
errors
• Reroute messages with erroneous control
information to a special queue
• Transmit error messages
However, not all of these functions are
required of an acp.
~any of the optional
TCAM macros allow the user to write an MCP
that includes functions that would
otherwise have to be executed by the COBOL
program. There are, nevertheless, some
functions the MCP must alvays provide and
in so doing follow certain conventions.
These requirements are discussed under
~·U ser Tasks."
FUNCTIONS OF THE MESSAGE CONTROL PBOGRAM
USER TASKS
Depending on the requirements of the
installation, the user can create an Mep to
perform any of the following functions:
- Enable and disable communication lines
-Invite terminals to transmit messages
• Receive messages from terminals
• Dynamically assign buffers to incoming
messages
• Handle messages on the basis of
user-specified priorities
• Perform message-editing functions for
incoming messages
404
Guidelines for writing an MCP are
contained in the publication OSLY~_I~!!!
f~ogr~m~~£~~~Y!d~:
The user must tailor
these general statements to meet the
specific needs of his installation.
For
example, a message can be transmitted from
one terminal to another, from a terminal to
an application program, or from one
application program to another. Moreover,
the message may contain anyone of several
types of data.
Regardless of the specific requirements
of the user, the MCF writer must always be
concerned with four major tasks, as
follows:
• Defining the main storage buffers used
by the "CPfor handling, queueing, and
transferring message data between
communication lines and queueing
devices.
• Defining the data sets referred to by
the "CP, and providing for their
activation and deactivation.
• Defining the various terminal and line
control areas used by the "CP (that is,
the operating procedures and signals by
which a teleprocessing system is
controlled).
• Defining the message handlers .(the sets
of routines that examine and process
control information in message headers,
prepare message segments for forwarding
to their destination, and route
messages to their proper destination).
In carrying out each of these tasks, the
user codes a variety of assembler-language
macros in a specified order~
Some of these
macros must be included in every ltCPi
others the user specifies according to the
needs of his installation.
Required as
well as optional macros' are illustrated in
the sample "CP given in Figure 160. The
encircled numerals in the discussion that
follows refer to sections of code that are
similarly labeled in the figure.
Using the Communication Feature
405
PAGE
LOC
OBJECT CODE
ADDRl ADDR2
STMT
SOURCE STATEMENT
3
ASM 0102 19.28 06/07/74
1 •••
2 •
3 • MESSAGE CONTROL PROGRAM
4 •
000000
Figure 160.
406
5 MCP
CSECT
6
PRINT NOGEN
7 •
8 • IN THE FOLLOWING MACRO-9 •
PROGID MAY BE OMITTED--IF USED, IT IS PLACED AT THE
BEGINNING OF THE EXECUTABLE CODE IN THE MCP
10
DISK=YES
IS THE ASSUMED OPERAND--IFNO MESSAGE QUEUES DATA
11
12 •
SETS ARE ON DISK,CODE DISK=NO
13 •
CPB= USED IN READING FROM AND WRITING TO DISK--NEEDED IF
14 •
DISK=YES--NO. DEPENDS ON NO. OF LINES, AMOUNT OF MESSAGE
15 •
TRAFFIC AND SIZE OF BUFFER UNITS
16 •
CIB=NO. OF COMMAND INPUT BLOCKS--BUFFER-LIKE AREAS USED TO
17 •
CONTAIN OPERATOR CONTROL MESSAGES FROM SYSTEM CONSOLE-FREED ONCE A MESSAGE PROCESSED--2 ASSUMED AND MAX. IS 255
18
PRlMARY=SYSCON--THIS IS ASSUMED AND SPECIFIES THE SYSTEM
19
20 •
CONSOLE AS THE PRIMARY OPERATOR CONTROL TERMINAL FOR
21 •
ENTERING AND ACCEPTING OPERATOR CONTROL MESSAGES--IF A
22 •
TERMINAL IS SPECIFIED, IT MUST BE ON A NON-SWITCHED LINE
23 •
AND BE ABLE TO ACCEPT AND ENTER MESSAGES
24 •
CONTROL=--USED TO IDENTIFY OPERATOR CONTROL MESSAGES TO SYSTEM
25 •
WHEN RECEIVED FROM OTHER THAN SYSTEM CONSOLE--O IS DEFAULT
26 •
AND IS VALID ONLY IF ALL OPERATOR COMMANDS ARE TO BE
27 •
ENTERED FROM SYSTEM CONSOLE
28 •
KEYLEN=--SIZE OF BUFFER UNIT--BETWEEN 33 AND 255-29 •
CAN ALSO SPECIFY BY UNITSZ= RATHER THAN KEYLEN=
30 •
LNUNITS=--NO. OF BUFFER UNITS TO BE USED IN BUILDING BUFFERS
31 •
FOR INCOMING AND OUTGOING MESSAGE SEGMENTS--IF TOO FEW ARE
32 •
SPECIFIED, INCOMING MESSAGE DATA MAY BE LOST--TOO MANY
33 •
WASTES STORAGE SPACE
34 •
MSUNITS=--NEEDED IF HAVE MAIN STORAGE MESSAGE QUEUES DATA SET
35 •
--NO. OF BUFFER UNITS ASSIGNED TO THIS DATA SET--IF NO DISK
36 •
BACK-UP IS SPECIFIED, MESSAGE SEGMENTS MAY'BE LOST IF NOT
37 •
ENOUGH UNITS
38 •
MSMAX=--PERCENTAGE OF UNITS IN MAIN STORAGE MESSAGE QUEUES
39 •
DATA SET WANT USED BEFORE BIT IN ERROR RECORD SET-40 •
70 ASSUMED
41 •
MSMIN=--PERCENTAGE OF UNITS IN MAIN STORAGE MESSAGE QUEUES
42 •
DATA SET WANT UNUSED BEFORE BIT SET NOTIFYING NO LONGER
43 •
CROWDED--MUST BE LESS THAN MSMAX-44 •
50 ASSUMED
45 •
(NOTE--THIS BIT ALWAYS SET IF SPECIFIED PERCENTAGE OF UNITS
46 •
UNUSED)
47 •
DLQ=--OPTIONAL--USED TO SPECIFY A TERMINAL TO RECEIVE MESSAGES
48 •
HAVING' INVALID DESTINATIONS AS DETERMINED BY FORWARD MACRO
49 •
INTVAL=--AN OPERATOR CONTROL MESSAGE TELLS TeAM TO ENTER THIS
50 •
DELAY TO MINIMIZE UNPRODUCTIVE POLLING--WHEN ALL MULTIPOINT
51 •
LINES ARE INACTIVE, THE INTERVAL COMMENCES--LINES TO
52 •
SWITCHED STATIONS AND NONSWITCHED CONTENTION LINES LEFT
53 •
ACTIVE--THE OPERATOR COMMAND IS A MODIFY COMMAND REFERRED
54 •
TO AS 'INTERVAL'--THE NO. SPECIFIES THE NO. OF SECONDS
55 •
STARTUP=-IF THIS OPERAND IS OMITTED, THE USER WILL BE GIVEN
A Message control Program for Communication Application (Part 1 of 20)
PAGE
LOC
OBJECT CODE
ADDR1 ADDR2
6B, then C
6
If C > maximum block size permitted
for any device a utility data set is
on, then the maximum block size is the
value chosen for C. The minimum block
size for SYSUT1, SYSUT2, SYSUT3, and
SYSUT4 is 256 bytes.
The COBOL compiler can be invoked by a
problem program at execution time through
the use of the ATTACH or the LINK macro
instruction, i.e., dynamic invocation.
Dynamic invocation of COBOL compiled
programs can be accomplished through the
use of the LINK, ATTACH, or LOAD macro
instruction.
option list.
specifies the address of a variable
length list containing the COBOL
options specified for compilation.
For additional details, see the
description of the EXEC statement in
the chapter "Job Control Procedures."
This address m~st be written even
though no list is provided.
INVOKING THE COBOL COMPILER
The option list must begin on a
halfword boundary. The two high-order
bytes contain a count of the number of
bytes in the remainder of the list.
If no options are specified, the count
must be zero. The option list is free
form with each field separated from
the next by a comma.
No blanks or
zeros should appear in the list.
The problem program must supply the
following information to the COBOL
compiler:
• The options to be specified for the
compilation
• The ddnames of t'he data sets to be used
during processing by the COBOL compile.r
• The header to appear on each page of
the listing
r-
I
-,-
--,
'Name
J Operationl Operand
•
J
.[symbol]1 LINK
I
I ATTACH
I
J
I
I
I
IEP=IKFCBLOO,
I PARAM= (optionlist
I (,ddnamelist],
I [, headerlist ]) , VL= 1
L-
•
•
I
of
I
•
•
,
where:
EP
specifies the symbolic name Qf the
COBOL compiler.
The entry point at
which execution is to begin is
determined by the control program
(from the library -directory entry).
PARAM
specifies, as a sublist, address
parameters to be passed from the
problem program to the COBOL compiler.
The first fullwordin the address
parameter list contains the address of
the COBOL option list. The second
fullvord contains the address of
ddname list. If standard ddnames are
to be used and no header list is
specified, this list may be omitted.
If standard ddnames are to be used and
a header list is specified, this entry
should contain the address of a
halfword of binary zeros, aligned on a
halfword. The last fullword contains
the address of the header list. This
list may be omitted.
Appendix E:
ddname list
specifies the address of a variable
length list containing alternative
ddnames for the data sets used during
COBOL compiler processing. If
standard ddnames are used, this
operand may be omitted.
The ddname list must begin on a
halfword boundary. The two high-order
bytes contain a count of the number of
bytes in the remainder of the list.
Each name of less than eight bytes
must be left justified and padded with
blanks. If an alternate ddname is
omitted from the list, the standard
name will be assumed.
If the name is
omitted within the list, the 8-byte
entry must contain binary zeros.
Names can be omitted from the end
merely by shortening the list.
All utility data sets passed to the
compiler must be physical sequential
(for example, DSORG=PS must be their
type of organization) •
The sequence of the 8-byte entries in
the ddname list is as follows:
ddname
8-bn~tr:t
1
2
3
4
5
6
7
8
9
10
Name for
ihi£h~ubsti1Ylgg
SYSLIN
not applicable
not applicable
51SL1B
SYSIN
SYSPRINT
SYSPUNCH
SYSUT1
SYSOT2
SYSUT3
Invocation of the CO BOL Compiler and COBOL compiled Programs
499
11
12
13
14
S YSUT4
SYSTERK
SYSUT5
SYSUT6
header list
specifies the address of a
variable-length list containing
information to be included in the
heading on each page of the listing.
The list must begin on a halfvord
boundary. The two high-order bytes
should contain a 4 (the count of the
number of bytes int.he new heading
information). The next four bytes of
the list should contain the page
number at which the heading is to
start~ in EBCDIC format.
VL
specifies that the sign bit is to be
set to 1 in the last full·word of the
address parameter list.
500
When the COBOL compiler completes
processing, a return code is placed in
register 15. For additional details~ see
the discussion of the COND parameter in the
chapter "Job control Procedures."
INVOKING COBOL COMPILED PROGRAMS
Linkage editor control cards should be
specified as follows:
1.
For the PROGRAM-ID program-name, a
NAME card.
2.
Por each ENTRY literal-1, an ALIAS
card should be specified in a COBOL
program that is to be dyna mically
invoked.
This appendix contains information to
aid the programmer in determining how his
source program affects usage of space at
compilation time and linkage editing time.
CO~PILER
CAPACITY
The capacity of the COBOL compiler is
limited by two
"C;;:;::;;-
'"
......... "".
60
f-
I-
1-+-
D~ ~
,~ ~
Icrr
~
~
~
11 ill [5
ILIL
I"
IDII" 1111:
111);1'00 11&1_
[AI~
IIlII
~~
la
~ R
III liMn-
~
~
II
IU
Ie
IIIMIT
II
II
I
ITII
IF
1=12
II I"
In
Ii
IIlHtr
~~.~ ~-
f--
I·~ -
~~.~
~
I-
IO~
I",,", 1"11. Ill}
18 NIU ~IA 1)11
1&:1,
~II
I~I"I!:
I"I~
I)
~-
....... '. 1I.\.~.
STMEM(NT
{
"
"
EMID
1*
jV Lk ED ~S 'fS L~ OD
7i
Figure 196.
~~"d
,.
EDIIT.1. ::IALII "IFI,
"
FR ,,10=
30
"
"
"
10
"
C"'_"'.
~S
..
ID tlA E=S
.1. I~ Ala EL lIB i(F RL ~a PM 1)1) ]) Is =0 LJ
Format Record Assembly Coding Example
NUMatli
....."".
--
1.,.",,1,(0'100'1
"
H- ~- -
-
D
0'
T:AI:D (unl:O
I
PUN(H
OATE
IPAGI
T
0.APHI(
~UNCHING
,
-
I-I-~
[)
INSTRUCTIONS
0,........
f~
,.-
IBM Sylllm/360 .....mblor Coding Form
No_
~
~-
I-~
PItOGIIAM
"'ltOGlAWMI
- I- -
I~f
'X
1--1--
lit I.. Iii
1111
IBM
556
I~
I)
r.lil
Illilll ITlc I", I"
~ ITll
I.:
14
INllJlCI 1\
IZ
to IT IA I. till! ~II:
II II: IDlsl:. II
II
~
10
1-1-
f--
f~
Ii 11
lell l I"~ lIlT III)
lull III Inlf:
to h'I.lI=
II
1.1)
I,
III
II
Ill::.
1~1t: 1"111:
II
1111 III,
-
"
~
-I- I-~
X
"
oo
Line 1
Header Record:
(20 Bytes)
Data Record:
(130 Bytes)
01011000000000000000
DALEoE.oSTUEMKEoooooo ... 0
--------~----------~
Pad to
130 Bytes
Pol icyholder
Field
Line 2
Header Record:
(20 Bytes)
Data Record:
(130 Bytes)
02021000000000000000
ROCHESTER,oMINNESOTA269403860249750o ... 0
Policy
Number
Address
Field
Am7u~P;d to 130 Bytes
Due
I
Code
Line 3
Header Record:
(20 Bytes)
Data Record:
(130 Bytes)
03031000000000000000
OOOOOOOb ... 0
-Amount
Paid
~igure
~he
197.
Pad to
130 Bytes
Sample Data
Figure 198 shows the COBOL source statements used to process the data in Figure 191.
JCt to run the program is also included in Figure 198.
Appendix M: 3886 optical Character Reader processing
551
,.------_
.
•• **************************************************************************************
1*********
S A ft P L E O C R
PRO G RAM
*********
1***************************************************************************************
lID DIVISION.
I
PROGRA!-I D. DOCLIST.
,ENVIRON8ENT DIVISION.
IINPUT-OUTPUT SECTION.
• FILE-CONTROL.
J
SELECT PRINTER. ASSIGN TO SYS009-UR-1403-S.
,DATA DIVISION.
I FILE SECTION.
JFD
PRINTER LABEL RECORDS ARE OMITTED.
101
PRINT-RECORD.
PIC X.
•
05 FILLER
PIC X (130).
I
05 PRINT-LINE
IWORKING-STORAGE SECTION.
PIC 9
VALUE 1.
177 PRINT-CONTROL
VALUE
PIC X (24)
177
MSG-PERftANENT-ERROB
t
'PERMANENT ERROR OCCURREDt.
PIC 1(19)
VALUE
177 MSG-MARK-CHECK
I
t MARK CHECK OCCURRED'.
177 MSG-MARK-AND-EQUIP-CHECK
PIC X(39)
VALUE
i
'MARK CHECK AND EQUIPftENT CHECK OCCURRED'.
177 MSG-INCOMPLETE-SCAN
PIC 1(24)
VALUE
I
'INCOMPLETE SCAN OCCURRED'.
177 MSG- NONRECOVERY-ERR OR
PIC X (26)
VALUE
J
'NONRECOVERY ERROR OCCURRED'.
177 MSG-BAD-DATA
PIC X(50)
VALUE
I
'THE FOLLOWING LINE WAS MISREAD. THE LINE HEADER : ' .
101
MSG-TER8INATION.
I
05 FILLER
PIC X (44)
VALUE
I
'TERMINAL ERROR OCCURRED - OCR-STATUS-KEY = ,
•L-________________________________________
05 MSG-TERM-STATUS-KEY
PIC XX._
Figure 198.
558
Sample COBOL OCR Processing Program (Part 1 of 3)
r------------------------------------------01
OCR-PILE COpy ILBDOCRD.
05
----------------------------------------,I
NOTICE-OF-P AYKERT-DUE REDEFINES OCR-DATA-RECORD.
I
10 LINE-l.
I
15 Ll-.POLICYHOLDER-lfA!.E
PIC 1(20).
I
10 LINE-2 REDEFINES LINE-l.
I
15 L2-CITY-AND-STATE
PIC 1(20).
I
15 L2-POLICY-NUftBER
PIC 1(8).
I
15 L2-AMOUNT-DUE
PIC 9 (4) V99.
I
15 L2-PAY!ENT-VERIFY-CODE
PIC 9.
I
10 LINE-3 REDEFINES LINE-l.
I
15 L3-AMOUNT-PAID
PIC 9 (5) '99.'
J
PROCEDURE DIVISION.
J
STOP RUN.
I
PIO-START.
J
MOVE 'SYS010' TO OCR-FILE-ID.
I
"OVE 'FORMAT' TO OCR-FORMAT-RECORD-ID.
I
PERFOR" OCR-OPEN.
I
OPEN OUTPUT PRINTER.
I
PIa-HEAD.
I
"OVE ALL '*' TO PRINT-LINE.
I
PERFOR! PRINT-ROUTINE.
I
ftOVE 1 TO OCR-STACKER.
I
PIO-READ.
I
PERFORM OCR-READ.
IF OCRS-NONRECOVERY-ERROR,
GO TO PIO-EOP-ERR.
I
IF ORCH-LINE-GOOD,
GO '1'0 PIO-GOOD.
I
IF OCRH-LINE-BLANK,
GO TO PIa-GOOD.
I
IF OCBH-LINE-NON-CRITICAL-ERR,
GO TO PIO-GOOD.
I
IF ORCH-END-O.F-PAGE,GO TO PIO-EOP.
I
****IF ORCH HAS A NY OTHER CODE, CONSIDER THE DATA AS BAD
I
PIO-BAD.
t
MOVE MSG-BAD-DATA TO PRINT-LINE.
I
PERFORM PRINT-ROUTINE.
I
MOVE 2 TO OCR-STACKER.
PIO-GOOD.
J
MOVE OCR-DATA-RECORD TO PRINT-LINE.
J
PERFORM PRINT-ROUTINE.
I
MOVE 1 TO PRI NT-CONTROL.
I
IDD 1 TO OCR-LINE-NUMBER, OCR-LINE-FORMAT.
I
IF ORCH-LINE-NUMBER IS LESS THAN 3, GO TO .PIO-READ.
I
PIO-EOP.
J
MOVE 3 TO OCR-LINE-NUMBER.
I
PERFORM OCR-EJ.ECT.
J
,PIO-EOP-ERR.
I
MOVE 1 TO OCR-LINE-NUMBER, OCR-LINE-FORMAT.
I
a
MOVE 3 TO PRI NT-CONTROt..
I
________________________________ JI
I
GO TO PIO-HEAD.
,
****
•
•
Figure 198.
Sample COBOL OCR Processing Program (Part 2 of 3)
Appendix M: 3886 Optical Charact er Reader Processing
559
r------------------EXCEPTION PROCESSING
I***~**
ROUTINE **************
..
IOCR-EXCEPTION-ROUTINE.
I
I"F OCRS-END-OF-PILE.
GO TO P20-EOP.
J
IF oenS-MARK-CHECK,
j
MOVE MSG-MARK-CHECK TO PRINT-LINE.
I
GO TO P20-RETURN.
I
IF OCRS-NONRECOVERY-ERROR,
I
MOVE MSG-NONRECOVERY-ERROR TO PRINT-LINE,
t
GO TO P20-RETUB N.
I
IF OCRS-INCOMPLETE-SCAN,
t
MOVE MSG-I NCOMPLETE-SCA N TO PRINT-L INE,
I
GO TO P20-RETURN.
,
•
I
IF OCRS-MARK-AND-EQUIPKENT-CHECK,
MOVE MSG-MARK-AND-EQUIP-CHECK TO OCR-LINE.
I
GO TO P20-PRINT-EOF.
•
IF ocaS-PERMANENT-ERROR,
I
MOV E MSG- PERMANENT-ERROR TO PRINT-LINE,
1
GO TO P20-PRINT-EOP.
I ****** IF NONE OF THE ABOVE ERRORS, GIVE TE.RMI NATION KESSAG.E ******
t
MOVE OCR-STATUS-KEY TO MSG-TERM-STATUS-KEY.
I
MOVE MSG-TERMINATION TO PRINT-LINE.
I
GO TO P20-PRINT-EOP.
I P20-RETURN.
I
PERFORM PRINT-ROUTINE.
GO TO OCR-CALL-EXIT.
•
I P20-PRINT-EOF.
I
PERFORM PRINT-ROUTINE.
I P20-EOF.
I
PERFORM OCR-CLOSE.
t
CLOSE PRINTER.
I
STOP RUN.
I PRINT-ROUTINE.
I
WRITE PRINT-RECORD AFTER ADVANCING PRINT-CONTROL.
IOCR-COPIED-PROCEDURES. COpy ILBDOCRP.
1/*
IIILKED.SYSIN DD*
I
ENTRY DOCLIST
1/*
IIIGO.SYSPRINT DD SYSOUT=A
IIIGO.SYSUDUMP DD SYSOUT=A
II/GO.SYS010
DD DUrtMY ,
L---________.____________
Figure 198.
Tape records produced from the IBM 3886,
Model 2, are almost identical in format to
the header and data records returned by the
!odel 1. The main differences between the
records are:
560
J
I
I
I
I
I
I
I
I
I
I
t
The Kodel 2 tape contains a document
trailer record after the line output
records for each document. The
content of this trailer record differs
from that of line output records.
Becaase of the similarity, however, the
nata Division COpy member defined for the
Model 1 may be tailored to describe the
Model 2 tape records. To do so, the
programmer should puncb out tbe COpy
member, modify it according to the
installation requirements, and recatalog
it.
Specific information on the formats and
contents of the Model 2 tape records is
contained in the !~!-~86 Optical Cha£~1~£
~~~~~~l-Info£.ation Manual
(G A2 1- 9146) •
2.
,
Sample COBOL OCB .processing Program (Part 3 of 3)
PROCESSING TAPES FROM THE 3886 OCR, KODEL 2
1.
I
I
I
The codes used in certain fields of
the header record differ between the
two models.
INDEX
As an aid to readers, this index contains not
material in this Programmer's Guide, but also
in the COBOL language manual. Entries having
Entries having only asterisks point to IBM VS
only the conventional references to
references to material that can be found
page numbers refer to pages in this manual.
COBOL for OS/VS (GC26-3857). For example:
Able 347
Baker·
Charlie 89,.
Dog 23, 106
Easy
additional information.
sub-one 33
sub-two 400
These entries would indicate that information on the subject "Able" is available on page
347 of this manual, and information on "Dog" is available in this manual on pages 23
and 106. Information on "Baker" does not exist in this manual; it can nevertheless be
found in the language manual (by looking up "Baker" in that manual's index). The entry
for "Charlie" indicates that some information is available in this Programmer's Guide
(on page 89), and additional information can be found in the language manual (again, by
looking up "Charlie" in its index). The entries for "Easy" indicate that its "sub-one"
and "sub-two" aspects can be found in this manual (on pages 33 and. 400, respectively);
additional information on "Easy" is also available in the language manual.
(period)*
< (less than character) *
o
(parentheses) *
+ (see plus symbol)
$ (currency sign)*
* (see asterisk)
** (exponentiation)*
(semicolon) *
(see either hyphen, or minus symbol)
/ (slash) 48,*
, (comma) *
> (greater than character)*
= (equal sign) *
(apostrophe, single quote) *
" (quotation mar~*
&&name subparameter 58
*. ddname subparameter 57
*. procstep subparameter 57
*. stepname subparameter 57
1* delimiter statement 21, 70
11* comment statement 23
A, as a device class 21
A, used in PICTURE and CURRENCY SIGN clauses*
abbreviations
for compiler options 38
for source statements*
ABDUMP (see dumps)
ABEND (see abnormal termination)
ABEND request subroutine 254, 481
abnormal termination
avoided by
*Consult VS COBOL for OS/VS (GC26-3857)
FILE STATUS 293
ON OVERFLOW 295
causes 254-259
completion codes 257-259, 529
COND parameter 35-37
dump
causes 254-259, 529
DD statement required for 81
definition 254
example 262-268
finding records in 268-273
how to use 260-262
including problem program storage
area 69
including system nucleus 69
of data sets 69
requesting 80-81, 254
required DD statement 81
using 254
errors causing 254-259
EVEN subparameter 37-38
failure to occur 183
for COBOL files 143-154
incomplete 277
INVALID KEY clause 148, 153-154
ONLY subparameter
restarting a job 36
restarting a job step 47
resubmitting a job 36
USE AFTER ERROR declarative 148-154
sort/merge considerations*
U-type code~ 529
absolute LINE and NEXT GBOUP*
Index
561
ABSTR subparameter
alphanumeric item*
description 61
ALSO option*
in QISAM 124
ALTER statement*
ACCEPT statement
altered GO TO*
additional information*
alternate collating sequence subroutine
relationship to SYSIN DD statement 80
(see also collating sequence)
subroutine for 477
alternate indexes (VSAM KSDS)
ACCESS IS phrases*
"..---, ..."...---1'-.'-_..~
ddnames for 201
access method services (VSAM)
173-180, 186, -4'8~ defining 177
access methods for
\'-----.____---.---...c....-.---.-~-c~ described 173, 174
direct file
examples 182, 195, 197
randomly 97-98
processing 181, 190
sequentially 98
writing 189
indexed file
alternate keys (see alternate indexes)
randomly 129-131
alternate paths 174
sequentially 127-129
alternate record key*
queue structures 312
(see also alternate indexes)
relative file
ALTERNATE reserved word*
randomly 112-113
ALTERNATEINDEX command 175, 178
sequentially 111-112
ALX subparameter 61
standard sequential file 85-88
American National Standard (see ANS
ACCESS MODE clause*
standard)
accounting information
American National Standard Code for
EXEC statement 34, 20
Information Interchange (see ASCII)
JOB statement 26, 20
AMP parameter 201, 69, 56
accuracy of results 294, *
~ND logical connective*
action requests, status key settings
~NS standard
(VSAM)
190-193
additional information*
actual decimal point *
requirements for MCP 432
actual key 83, 92-94
selecting 38
(see also ACTUAL KEY clause)
APOST compiler option 40
ACTUAL KEY clause
APPLY clause
(see also actual key)
CORE-INDEX option 283
in BDAM 92-94. 83·
RECORD-OVERFLOW option 283
in BSAM 92-94, 83
WRITE-ONLY option 282
in file processing techniques 492, 493
arabic numerial*
randomizing techniques
Area A and Area B*
division/remainder method 102
arguments
relative addressing 101
data-name passed as 317, 322
synonym overflow 108
file-name passed as 317, 322
ADCON table (see Text Punch Table)
procedure-name passed as 317, 322
ADD statement *
arithmetic expression*
addition operator*
arithmetic operator*
address constant table (see Text Punch Table)
arithmetic statements*
ADDRSPC parame~€r
arithmetic subroutines 475-476
and REGION parameter 31, 51
ASCENDING/DESCENDING Key*
description 31, 51
ASCII
ADV compiler option 44
addit ional informa tion*
ADVANCING 297, *
block prefix 90
AFF parameter 58, 59
collating sequence 293
AIXBLD option 186, 48, 201
creating 89
AL subparameter 66
description 89-90
algebraic sign*
label processing 90, 158-159
ALIGN subparameter 69
numeric data items 90
alignment rules*
opened 90
ALL literal figurative constant*
processing 90
ALL options*
requesting for QSAM 90
allocating mass storage space
sort for 375
SPACE parameter 61
assembler language
SPLIT parameter 62
programs, linkage to 322-325
SUBALLOC parameter 164
using EXEC statement 32-37
allocation messages 235, 241, 243
ASSIGN clause
alphabet-name*
additional information*
alphabetic characters*
for ASCII file 89-90
alphabetic class test*
in BDAM 82
alphabetic item*
in BSAM 82
alphanumeric class*
in QSAM 85
alphanumeric edited item*
rela~ionship to DD statement
82-83
562
*Consult VS COBOL for OS/VS (GC26-3857)
48
assigning index values 306-307, *
assignment name 82, 100, *
assumed decimal point*
assumed values in PAGE clause*
asterisk 56, *
AT END 56,
ATTACH macro-to invoke compiler 499
AUL subparameter 66
automatic call library 349
automatic restart (see Checkpoint/Restart)
~utomatic page overflow*
automatic volume recognition option
(AVR)
58
automatic volume switching 99
availability of records*
average record-length sub parameter
for SPACE 61
for SPLIT 62
AVR (automatic volume recognition
option)
58
AWAITING REPLY*
*
B, as a device class 21
B, used in PICTURE and CURRENCY SIGN
clauses*
b- a-c-k-w-a-r-d-- --m-o-v--e-m-en-t (-op t-i mi z a t ion)
2 79
base and displacement 246
BASIS card
additional information*
and batch compilation 71-73
in a debug packet 254
use of 351-352
BASIS library 76
batch compilation 71-73
BATCH compiler option 42
BDAM
data sets 134
DD statement parameters 1C9
defining a data set in 82-83
definition 83
direct organization 91
error processing for
143-154, 509
locating data areas in 275
relative organization 110-112
permissible COBOL clauses 118, 108
programming techniques 283
with spanned records
261
BEFORE ADVANCING*
BEFORE/AFTER option of INSPECT*
beginning address of a file
62
binary (see also computational fields)*
BISAM
(see also QISAM, indexed files)
considerations when using 129-131, 119
data sets 134
defining a data set in 82-83
definition 83
error processing for
143-154, 509
processing with 129-131, 119
blank line*
BLANK WHEN ZERO clause*
blanks
additional information*
in job control notation 25
BLDINDEX command 174, 186
*Consult VS COBOL for OS/VS (GC26-3857)
BLKSIZE
for compiler data sets 496-498
in DCB 491-495
in file processing techniques 87
in QSAM 125
with data sets 79-80
BLOCK ctiNTAINS clause
additional information*
and UNIT subparameter 59
description 59
block length (see BLKSIZE)
block prefix 90
block size
causing errors 256
description 59
for utility data sets 496-498
blocked records
fixed-length 160
spanned 164-166
variable ~ength 161-164
blocking, automatic*
BLP subparameter 66
body group*
bottom page margin*
boundary alignment*
boundary violation*
braces in job control notation 25
Ibrackets in job control notation 25
BSAM
data sets 133
DD statement parameters 109
defining a data set in 82-8~
definition 83
error processi~ for
143-154, 509
locating data areas in 275
permissible COBOL clauses 108, 118
subroutines 478
user label totaling 156
with direct file 91
with relative file 110-112
with spanned records 261
BUF compiler option 38
buffer offset 89
buffer unit 426
bu ffers
additional information*
for TCAM 426
optimizing with APPLY clause 164
size of compiler's 497
specifying number
for indexed files 124
for standard sequential files 87
BUFNO subparameter 124
BUFOFF subparameter 90
byte, definition*
c
as compiler message level 238, 35
as COpy indicator 235
as FIPS level 40
in source*
CALL loader option - 48
CALL macro 323, 326
CALL statement
additional information*
and CANCEL statement 295, 323-326
and subprograms 295
definition 295
Index
563
dynamic loading 335-336
~amples
327-331
calling/called programs and s~bprograms
additional information* .
additional input 332, 346
identifiers 322
input
additional 332, 346
primary 332, 346
linkage 316-326
loading 346
primary input 332, 346
sample 327-331
'CANCEL statement
additional information*
and static CALL statement 295
and subprograms 323-326
description 295
format 295
capacity records 93
card files*
card image*
carriage control character 44, *
catalog, system 18
cataloged data sets
creating 136
description 141
on a volume 155
retrieving 138
cataloged procedures
adding to the procedure library 357-358
adding to DD statements 364
bypassing steps within 35-37
calling 356
COBUC 359, 360
COBUCG 361, 360
COBUCL 359, 360
COBUCLG 361, 360
COBULG 359-360
data sets produced by 356-357
DD statements 51
ddname parameter 366-367
definition 21
dispatching priority 50
IBM-supplied 358-359
in-stream testing 363
limiting execution time of 51
modifying 362
naming 359
overriding 362
PEND statement 70
PROC statement 70
programmer-written 357
required device class names for 58, 59
restarting programs with 28-29
return code 34-36
using the DD statement 364-368
using the EXEC statement 34, 362
with COND parameter 35-37
categories*
CATLG subparameter 67, 141
564
CBL card
and batch compilation 71-73, 42-43
and lister options 44
CD entries 284, *
cd-name*
CDECK option of lister 44, 212
CF*
CH*
changing values*
channel, definition*
character codes*
character delimiters 24
character positions*
character set
additional information*
UCS parameter 60
character-string*
characters allowed*
CHARACTERS option*
checkid 29, 396-397
checklist for job control
p~ocedures
514-518
Checkpoint
(see also Checkpoint/Restart)
additional information*
CHKPT macro instruction 28-29, 396
considerations 396-397
data set 28-29
how taken 49-50
initiating 394
in a job 28-29
in a job step 49-50
messages 396
multiple 394
RERUN clause 49-50, 394
restart 49, 397-398
(see also Restart)
single 394
Checkpoint/Restart
chetkpoint 394-396
(see also Checkpoint)
data sets 398-400
DD statements 394-396
deferred 69
designing 396
in a job 28-29
in a job step 49
messages 396
methods 394
RD parameter
with checkpoint 396-397
for a job 28
in a job step 49
restart 397-398
(see also Restart)
subroutine 478
SYSCHK DD statement 397-400, 69
with Sort/Merge 372
CHKPT macro instruction 28-29, 49
CJS (see Communications Job Scheduler)
.class condition*
CLASS parameter 30
*Consult VS COBOL for OS/VS (GC26-3857)
class test subroutine 476
classes of data*
clause sequence*
CLIST compiler option 39
CLOSE REEL statement 85
CLOSE statement
additional information*
BSAM subroutines 478
creating multivolume files
with direct organization 98
with relative organization 112
efficient use 295
VSAM files 191
CLOSE UNIT statement 98, 112
closed subroutine*
cluster considerations (VSAM)
180
CMS (Conversational Monitor System)
operating system 19
VM/370 19
COBOL copy libraries 73, 76
COBOL sequence numbers 351
entering source statements 349
IEBUPDTE sequence numbers 351
retrieving source statements 351
BASIS card 351, 35
COPY statement 35, 351
updating source statements 350
COBOL file processing (see file, processing
techniques)
COBOL Interactive Debug (see Interactive
Debug)
COBOL language usage with VSAM 193-201
COBOL library management*
COBOL library subroutines 472-489, 348
(see also library)
concatenating 353
sharing 353
COBOL program structure*
COBOL RERUN clause 49-50, 394
COBOL reserved word list*
COBOL sample program 461-471
COBOL sequence numbers 351, 39
COBOL subroutine library 348, 472
(see also library)
need to concatenate 81
COBOL subroutines in link pack area 346
COBOPIN 432
COBOPOUT 432
COBOPT 433-434
COBTPOUT 449
COBTPQD 449
COBUC 359, 360
COBUCG 361
COBUCL 359, 360
COBUCLG 361
COBULG 351, 360
COBURDR -procedure 437
CODE clause*
CODE-SET phrase 90, 293, *
codes, completion 257-259
for Sort/Merge program 371
collating sequence
additional information*
and ACTUAL KEY 94
effect on QISAM 129
for QS1M 90
for Sort/Merge 375
qeneral 293
*Consult VS COBOL for OS/VS (GC26-3857)
COLUMN clause*
combined condition and function*
combining arithmetic operations*
comma*
command statement 70
comment-entry*
comment line*
comment statement 71
comments
continuing 24
field 24
statement 71, 20
common end point*
common expression elimination 279
Communication Description (CD) entries
additional information*
and Communications Section 284
and Teleprocessing (TP)
284
format 284
.
Communication Feature (see also
Communications Job Scheduler) *
Communication Section 284, *
communication with other languages 326
Communications Job Scheduler
general 436
illustrations 439-441
preparing 438
using 438
compare subroutine 476
comparison rules*
compatibility (LANGLVL)
38
compilation
(see also compiler)
additional information*
batch 71-73
cataloged procedure 356-360
checklist for job control
procedures 514
data set requirements 73-76
definition of 18
example of job control
statements 514
invoking compiler at execution
time 499-500
sample program 461-471
source program size assuming minimum
configuration 501
syntax checking 247
using REGION ~arameter 457
COMPILE= indicator 237
compiler
(see also compilation)
additional information*
blocking factor for data sets 496
buffer space 497
calling 499
capacity 501
data set requirements 73~76
block size 496
internal name 236
invoking 499
machine requirements 457
optimization 496-498
options 38-46
significant characters 38
output
allocation messages 235
cross-reference dictionary 237-238
Index
565
diagnostic m~~sages 238
global table 236-237
glossary 235-236
job control statements 235
object code 237
object module 239-240
sample output 232-236
source module 235
PARM options 38-46
problems, resolving 543
return code 500
segmentation output 379
specifying in EXEC statement 32
compiler-directing statement*
completion codes
description 257-259, 529
in Sort program 371
complex conditions*
composite of operands*
compound condition*
computational fields
conversion subroutines 473-475
conversions involving 288-290
description 288
COMPUTATIONAL*
COMPUTE statement*
computer-name*
concatenating
. data i tems*
libraries 69
COND paramet.er
EVEN, ONLY subparameter 36
in cataloged procedures 372-373
in EXEC statement 35-37
in JOB statement 27
condensed listing, used to find program
interruption 259
condensed listing, using CLIST 38
condition* '
condition-code*
condition-name*
conditional, as a severity level
(C)
38, 35
conditional expressions and statements*
conditional syntax-checking compilation 41
conditional variable*
conditions terminating execution 27, 35-37
conditions valid in serial search*
Configuratio~ Section
282-283, *
connective words*
console message*
CONSOLE typewriter*
CONTIG subparameter
description 61
with direct files 100
with indexed files 124
contiguous items*
continuation
additional information*
of .job control statements 24
control breaks*
(see also CONTROL clause)
control cards
for CJS 438
for SYMDMP 215-216
control characters 436, *
566
CONTROL clause*
control flow*
CONTROL FOOTING*
CONTROL HEADING*
control hierarchy*
control program 18
control statements
character delimiters 24
command statement 70, 20
comment statement 71, 20
continuing 24
DD statement 51-70
delimiter statement 70, 20
EXEC statement 32-51, 20
fields 23-24
formats 23
functions 22
JOB statement 25-32, 20
notation used for 25
null statement 70, 20
PEND statement 70
preparing 23-24
PROC statement 70, 20
processing 22
use 20
control transfer (see also calling
programs and called programs)*
Conversational Monitor System (see CMS)
conversion of data 473, *
conversion subroutines 473-475
COPIES parameter 60
copy library (see COBOL copy library)
COpy statement
additional information*
DD statement requirements 515
effect of CDECK option 44
use 349-351, 35
core fragmentation, preventing 43
core storage (see main storage)
core storage availability to sort*
CORRESPONDING option*
COUNT compiler option 44
DD statement 81
program checkout 247, 278
count field in INSPECT*
COUNT IN, UNSTRING*
COUNT subroutines 482
counter rolling*
counting characters*
CR r used in a PICTURE clause*
creating files, DD statement
considerations 131-137
direct 134
in the output stream 134
indexed 134
on magnetic tape 133
relative 111-112
sequential, on mass storage device 133
credit (CR)*
unit record 133
cross-footing*
cross- reference
dictionary 237-238
list
description 242
of verbs (VBREF)
44
used in dumps 262-263
*Consult VS COBOL for OSjVS (GC26-3857)
CRP (current record pointer)
181
CSP-function-name*
CSYNTAX compiler option 41
CURRENCY-SIGN clause*
CURRENT-DATE special register 481, *
current record pointer (CRP)
181, *
CYL subparameter
for SPACE
considerations for indexed files
description 61
for SPLIT 62
cylinder overflow area 122-123
,CO 1 through C12 function name*
specification of 82
data set member 83
data sets
adding records to 67
(see also MOD subparameter)
allocating space for 61-64
blocked' 79-80
~ataloging
124
D
as message level 35, 228, 529
in source*
indicating debugging lines 248
data alignment 288-292
data areas, locating in a TCAM
program 275-277
data attribute*
data classes*
data control block
(see also DeB parameter)
description 142
fields 490-495
identifying 143
overriding fields 142-143
data conversion 288-292, *
data-count fields*
data definition 51-69, 20
(see also DD statement)
data description*
.
data delimiter for input 56
Data Division additional information*
maximum size 283
Data Division dump (with SYMDMP)
and FD 214
and index-name 214
and RD 214
and SD 214
Data Division programming techniques 283-292
Data Division reformatting 204-205
data extent block 73
data formats 285-289
data group, generation 141-142
data hierarchies*
data item*
data manipulation statements*
data-names*
additional information*
missing from listings 42, 238
data-name clause*
data organization*
DATA parameter
in DD statement 56
restriction with UNIT parameter 59
data receiving fields*
DATA RECORDS clause*
data reference*
data representation*
data set control block 155, 56-68
data set labels
description 154-159
relati~nship to DD statement
154
*Consult VS COBOL for OS/VS (GC26-3857)
description 67
indexed files 141
checkpoint 398-400
c~ncatenating
364
copies of 60
creating 131-137, 174-180
definition 18
deletion of 67
delimiting in input stream 70
describing attributes of 51-56
direct 83, 91-97
disposition of, in general 131
after abnormal termination 277-278
description 67-68
errors involving 255-259
ESDS 173
execution time 79-81
extending 142
for symbolic debugging 246, 215, 216
for VSAM 201-202
generation data groups 141-142
identifying
description 57
for compilation or linkage
editing 57
in the input stream 56
in the output stream 68-69
indexed 119-131
ISAM 202
KSDS 173
labels, relationship to SELECT and DD
statements 144
\
magnetic tape 133
multivolume, processing 98
names
description 142
relationship to file names 82
nontemporary 63
number of copies 60
organization 83
partitioned 347-355
physical sequential 85-89
postponing definitio~ of 57
produced by cataloged
procedures 356-357
relati ve 83.
retaining 67
requirements
for compilation 73-76
for execution 79-81
for linkage editing 76-78
for loading 78-79
retrieving 138-140, 1951
(see also retrieving data sets)
RRDS 174
scratching 277-278
sharing 67
standard (physical) sequential 85-89
system catalog of 18
temporary 63
Index
567
unit record 133
updating (VSAM)
198-199
used by Checkpoint/Restart
used by Sort 349-351
VSAM 173-202
data transfer*
data truncation*
data values REDEFINES*
Date-and-Time subroutine 481
380-382
2~5, *
DATE special register 481, *
DATE-WRITTEN paragraph*
DAY special register 481, *
DB, used in a PICTURE clause*
DCB exit subroutine 479
DCB macro instruction 490
DCB parameter 58
(see also data control block)
for defining checkpoint data
sets 398-400
description 143
error processing with 143-146
identifying information'in 143
retrieving previously created data
sets 138-140
subparameters
for direct files
accessed randomly 493
accessed sequentially 492
for indexed files
accessed randomly 139, 495
accessed sequentially 128, 494
for physical sequential files 86-89
for relative files
accessed randomly 493
accessed sequentially 120, 492
DD statement 51-69
adding to a cataloged procedure,
description 21
additional information*
error recovery option, for physical
sequential files 143-146
facilities, additional 69
format 52-56
name field 56
overriding in cataloged
procedures 364-365
parameters 52-68
AFF 58
AMP 69
asterisk 56
COPIES 60
DATA 56
DCB 58
DDNAME 57
DISP 66-68
DLM 56
DSNAtiE 57
DUMMY 56
DYNAM 57
FCB 68
LABEL 62
OUTLIM 60
QNAME 58
5EP 58
SPACE 61
5PLIT 62
SUBALLOC 62
DATE~COMPILEDparagraph
568
SY50UT 68
TERM 60
UCS 60
UNIT 58-59
VOLUME 63-66
relationship to ACCEPT statement 80
relationship to DISPLAY statement 79-80
relationship to SELECT statement 144
requirements for
ASCII files 90, 159
changing a library 357
compilation, job step 514, 515
compiler data sets 73-76
creating files (see creating files,
DD statement considerations)
direct files 109
execution job step 515, 516
execution time data sets 141
extending data sets 139
indexed files 123-129, 510-513
linkage editing
data sets 76-78
job step 515, 516
loader data sets 78-79
physical sequential files 85-89
relative files 110, 138-140
retrieving data sets 138-140
sort/merge 368-371
specifying unit record devices 141
standard (physical) sequential
files 85-89
unit record devices 141
using cataloged procedures 357-361
using COBOL copy library 349-350
using the sort/merge feature 368-371
VSAM files 201
sort/merge~ used in
368-371
subparameters
DISP 67
DSNAME 57
FCB 68
LABEL 66
SPACE 61
SPLIT 62
5UBALLOC 62
5Y50UT 68
TERM 60
UNIT 59
UCS 60
VOLUME 65
used to complete the DCB 142-143
user catalog (VSAM( 201
DDNAME parameter 57
ddname subparameter (see ddname
subparameter)
description 57
in cataloged procedures 366
ddname sub parameter 57
and calling and called programs 34
and cataloged procedures 364-365
and creating files 133-134
and indexed files 123-127
and retrieving files 138-140
and subprogram linkage 337-339
and VSAM 201
as DDNAME subparameter 57
(see also DDNAME parameter)
as DSNAME subparameter 57
*Consult VS COBOL for OS/VS (GC26-3857)
as INCLUDE oper'and 338
as LIBRARY operand 338
as PGM subparameter 34
as stepname qualifier 364-365
as SUBALLOC parameter 62-63
checklist of use in JeL
procedures 515, 516
in DD statement format 53
in EXEC statement format 34
in name field of DD statement 56
used to allocate space 62-63
using with queue structures 313
with Checkpoint/Restart 394, 396
DEBUG card 236, *
debug control statement, sort/merge 377
debug control subroutine 482
DEBUG-CONTENTS field 249, *
DEBUG-ITEM special register 248, *
DEBUG fields in PGT 525
DEBUG option 48, 248
DEBUG-LINE*
DEBUG-NAME*
DEBUG-SUB*
debug, interactive (see Interactive Debug)
debugging features 213-230, 247-254, *
debugging language 247-254
(see also TRACE statement and EXHIBIT
statement)
debugging lines 248, *
debugging packet 251, *
debugging a program (see program debugging)
debugging, symbolic 213-230
example 217-230
FLOW 214
STATE 213
SYMDMP 214-215
TEST 213
under IMS 217
DECB, linking with 317
decimal point
additional information*
alignment in PICTURE clause 286
DECIMAL-POINT IS COMMA clause*
DECK compiler option 39
'declarative save area chaining
subroutine 480
declaratives
additional information*
USE AFTER ERROR 143-154
USE FOR DEBUGGING 248
decrementing*
defaults
additional information*
for data sets 498, 216
f or options 46
DEFER subparameter 59
deferred restart 397-398
SYSCHK statement 69
DEFINE command
cluster considerations 177
ESDS 179
functions '174
KSDS 177
MASTERCATALOG 175
RRDS 179
specification of 174
USERCATALOG 176
VSAM data space 176
*Consult VS COBOL for OS/VS (GC26-3857)
DELETE statement 137, 352, *
in VSAM 190
DELETE subparameter
, and cataloged data sets 141
definition 67
deleting modules 43
DELIMITED BY*
delimiter
additional information*
in job control statement 24, 70
DEN subparameter 86
DEN values 86
DEPENDING ON option 305, *
depth of a report page*
descending key*
destination*
DETA IL*
detail reporting*
determining file space 101
device allocation 235
device class
and compiler data sets 73-76
and execution time data sets 79
and linkage editing data sets 76-78
and UNIT parameter 59
blocking restrictions 59
definition 18
examples of names 21
names required for cataloged
procedures 59
diagnostic messages
compilation 238-239, 529
linkage editing 240-241
object-time 529
sort/merge 3JO
with ON statement 214
DIAGNS subparameter 88
dictionary, cross-reference 237-238
dictipnary table 502
digit position*
direct access (see mass storage)
direct data sets
creating 94-97
description 91-94
direct file
ACTUAL KEY clause 91
creating 94-99
randomly 96-97, 99
sequentially 94-95
description 91-94
error processing 143
multivolume 98
processing 91-109
randomizing technique 100
reading
randomly 97
sequentially 97
sample program 106-107
space allocation 94
TRACK LIMIT clause 94
writing 99-100
direct indexing*
Direct SYSOUT Writer 134
directory-quantity JCL subparameter 62
DISABLE statement
.
additional information*
general 297, 432-434
subroutine for 4BO
Index
569
definition 69, 254
disaster, as a severity level (D)
35, 228, 529
determining location of error 259-260
disk (see mass storage)
DUMP option 44
DISP parameter 66-70
dynamic 251-254
data set uses
and compile-time option 251
cataloging 141
SYHDMP 254
creating 133-134
locating records in 268-273
retrieving 138-140
locating working-storage in 237
default values of 67
requesting
description 66
using ILBOABNO subroutine 254-255
in JOBLIB DD statement 67
using SYSABEND DD statement 81
in sort/merge feature 369-370
subparameters 67-68
using SYSUDUMP DD statement 81
displacement*
types of
displacement and base 236
abnormal termination 260, 254
DISPLAY option of USAGE clause
DUMP option 44
additional information*
indicative 254
and comparisons and moves 288, 290
use of 254
and data format conversion 289
user-initiated 254
external decimal format 290-292
duplicates, alternate keys 173, *
DISPLAY statement
duplicates, names*
DYNAH option 334-336
additional information*
DYNAM parameter for TSO 57
and COBOL output files 79-80
conversions involving 288-290
dynamic access*
relationship to DD statement 79-80
dynamic CALL 334-336, *
dynamic dump, symbolic debugging 213
DISPLAY subroutine 477
DISPLAY usage*
dynamic invocation of Access Method
displaying data values during
Services 186
execution 251-253
dynamic subprogram linkage 317-321
disposition messages from job
and static CALL statement 295
scheduler 241, 239
CALL 318
disposition of a file, in general 131
CANCEL statement 295
DIVIDE statement*
DYNAM option 334-336
division header, description*
example 319-321
division operator*
NODYNAM 336
division/remainder method for
dynamic values in table*
randomizing 102
DMAP compiler option 39
document description (OCR)
550
document design (OCR)
549
E (error severity level)
238, 35
dollar sign*
EBCDIC
additional information*
DPRTY parameter 51
as program collating sequence 293
DSNAME parameter 57
as label format 155
and single-volume files 125-126
for MODE= specification 87
and file creation 131
editing*
and file processing techniques
efficiency guidelines (optimization) 281
direct 109
efficient programming (see programming
indexed 123
techniques)
relative 119
EGI (end-of-group indicator)*
standard sequential 88
elementary entries*
definition 57
elementary item*
forma t of 53
ellipsis ( ••• ) in formats 25
subparameters 57
ELSE NEXT*
DSNAME subparameters 57
embedded PERFORM*
DSORG
EMI (end-of-message indicator) *
direct files 109
ENABLE statement
indexed files 128
additional information*
relative files 120
general 297, 432-434
dummy data set, defining 366
subroutine for 480
DUMMY parameter
END DECLARATIVES*
definition 56
end indicators*
format 53
end key*
restriction 74
end of execution 43, 323, *
dummy records 93, 186
end-of-file 56,*
DUMP compiler option 44
end-of-group indicator (EGI)*
dumps
end-of-message indicator (EMI) *
and symbolic debugging 213
end-of-page condition 297, *
completion codes 251-259, 529
end-of-procedure*
DD statements to request 81
570
*Consult VS COBOL for OS/VS (GC26-3857)
end- of- program*
END OF REEL*
end-of-segment*
end of sort/merge*
end of table*
end of transmission*
ENDJOB compiler option 43, 323
ENTER statement*
entry name 334, 317
entry-point
of called programs 334
of loaded programs 48
entry-sequenced VSAM data sets 173
ENTRY statement 334, *
Environment Division
additional information*
programming techniques 282-283
reformatting 204
EOP*
EP loader option 48
equal sign*
equal size operands.
EQUAL TO*
EROPT subparameter 87, 146
error
additional information*
as a severity level (El
238, 35
completion codes with 35, 257-259, 529
conditions
input/output 504-509
invalid data 257-259
escaping detection 294
messages
condition code 35, 529
compile time 238-239, 529
linkage editor 240, 242
loader 243
numbered 77
object time 529-542
system 246, 243
severity codes 35, 238
U-type 529
processing for COBOL files
144-154
recovery 142-154
error intercept subroutine~ 478
error processing, RECEIVE*
error processing for COBOL files
COBOL language features for 143
error declarative 148-154
EXCEPTION/ERROR procedure (VSAM)
183
flow of logic and control 147
GIVING option example 150-152
INVALID KEY option 148, 183, 508-509
VSAM 183-185
outline of error recovery 143-146
status key (VSAM)
183
summary of error recovery 154
error records*
ESD (see external symbol dictionary)
ESDS data sets (VSAM)
defining 179
general 173
opening 189
processing 180, 189, 196
writing 193-194
ESI (end-of-segment indicator)*
*Consult VS COBOL for OS/VS (GC26-3857)
establishing a priority
f or a job (PRTY)
30
for a job step (OPRTY)
50
evaluation rules*
EVEN subparameter 36
EXAMINE statement*
EXCEPTION/ERROR
a~ditional information*
for non-VSAM 148
for VSAM 183-185
EXEC statement 32-52
accounting informa tion
(ACCT)
34
bypass/execution conditions
(CONO)
35- 37
compiler options of PARM
parameters 37-47
definition 20
dispatching priority (DPRTY)
50
identifying
procedure (PROe)
34
program (PGM)
32-34
step (stepname)
34
keyword parameters 34-51
linkage editing options of PARM
parameter 47
loader options of PARM parameter 47, 48
PARM parameter 37-48
passing information between programs 37
requesting restart (RO)
49
setting time limit (TIME)
50
specifying region size (REGION)
51
execution, flow and rules*
execution, steps in 18
execution statistics 278
executio n time
data sets 79-81
definition 19
job control checklist 514-518
options 48-51
output example 245, 461-471
storage allocation 458-459
with REGION parameter 457
EXHIBIT statement
additional information*
and program debugging 251-253
and required DD statement 80
EXHIBIT subroutine 477
exit from Declarative procedure*
exit list codes 158
exit point for procedures*
EXIT PROGRAM statement*
EXIT statement*
EXPOT subparameter 66
explicit information*
exponent*
exponentiation operator*
EXTEND 142, *
extended source program library*
extending data sets 142
external data concepts*
external decimal items*
external decimal subroutines 473-476
external floating-point*
external floating-point subroutine 474
external references, COBOL subroutines 346
external symbol dictionary (ESO)
240
Index
571
FINAL control*
F recording mode*
final results*
fall through*
FIPS level 40, *
false evaluation of IF*
FIRST*
FCB parameter 68
fixed insertion editing*
FD
fixed-length item*
additional information*
fixed-length record format 160, *
programming techniques 283
fixed-length table*
relationship to DCB 491-495
fixed line size*
with WRITE ADVANCING 85
fixed overlayable segments 378, *
FDECK option of lister 44, 212
fixed permanent segment 378, *
Federal Information Processing standard
fixed portion*
level 40
FLAGE/FLAGW compiler option 40
field count*
floating insertion editing*
figurative constant*
floating-point items
file
(see also computational fields)
additional information*
additional information*
and COBOL clauses 84, 283-284
intermediate results 294
and DD statement 82-83
floating-point subroutines 472, 475
and SELECT sentence 82
FLOW compiler option 41, 214
beginning address 62
f low of control*
converting to VSAM 201-202
flow trace subroutine 482
definition 82
FOLD subparameter 60
initial loading (VSA 1'1)
188
FOOTING 297, *
member 83
FOR REMOVAL*
name 82
processing techniques 83-131
format
additional information*
ASCII
direct 83, 91-109
changing (see lister feature)
indexed 83, 119-131
record (see record formats)
partitioned 83 .
format of lister listing 210-211
physical (standard) sequential 83, 85-89 forms control image 68
relative 83, 110-118
fragmentation of core, preventing 43
VSAM 180-184
FREESPACE parameter in VSAM 179
space allocation for 61, 59
fullword alignment*
specifying information about a 83
FUNC subparameter 88
user defined 82-83
function-name*
VSAM (see VSAM files)
FILE-CONTROL paragraph
additional information*
SELECT clause 82
general registers, using to locate
file description (OCR)
552
data 268
File Description entry*
GENERATE statement*
generation data set (group)
141-142
file-name
additional information*
generic key*
argument in calling program 322
GETCORE subroutine 480
GETMAIN usage and ENDJOB 43
definition 82
GIVING option 150-152, 368, .*
prefixes used with 283
relationship with DD statement 82
global table
description 236
file positioning*
file-processing
DMAP, PMAP options 39
additional information*
program 526-528
non-V SAM 83-129
task 519-526
VSAM 173-202
glossary (DMAP)
File Section
definitions 239
additional information*
description 235-236
non-VSAM 283-284
requesting through EXEC statement 39
VSAM 185-186
symbols used 240
file space, determining 101
GO TO statement 481, *
FILE specification in VSAM 177
GOBACK statement
additional information*
FILE STATUS
and assembler language 323
additional information*
and lOB 154
and ENDJOB option 43
description 293
greater than symbol*
for QSAM 146-148, 255-256
group entry*
GROUP INDICATE clause*
for VSAM
lists of keys 187-188, 192-193
group item*
use urged 183
group mo ves*
group report*.
FILLER*
572
*Consult VS COBOL for OS/VS (GC26-3857)
halfword alignment*
header labels 154-159, *
HEADING*
hierarchy 283, *
HIGH-VALUE (HIGH-VALUES) figurative
constant*
HOLD macro for TCAM 434
holding a job for later execution 31
horizontal spacing*
hyphen 25, *
(see also minus symbol)
I-O CONTROL paragraph*
1-0 files*
I-O options*
I/O (see input/output)
IBM-supplied cataloged procedures 356-363
Identification Division
additional information*
reformatting 203-204
identifier*
identifiers in linkage argument
list 316-326
IEBUPDTE subroutine 348, 349
IEFRDER DD card 438
IF statement 295, *
ILBO ••• subroutines 412-489
'ILBOABNO, user call to 254-255
ILBOMCPN replacement 433
ILBONBLQ macro 434
.IL:I3Q~RM.. _~IlgI?arameters ,48
ILBOSPIO and IMS calls 483
ILBOSTPO, assembler-language call to 324
ILBOSTTO
calling from assembler language 323
with ENDJOB option 43
imperative statement*
implicit items*
IMS (see Information Management System)
IN qualifier connective*
IN subparameter 66
INCLUDE statement 333, 338-339
incomplete abnormal termination 277
incrementing*
indentation*
independent overflow area 122
independent segment 378, *
index
additional information*
area 122
cylinder 122, 121
data item 305
assigning values to 306-307
master 128
names 305, 306
assigning values to 306
overflow area 122
prime area 122, 123
quantity SPACE parameter 62
track 121, 120
index data item*
index-name*
INDEX usag e*
indexed access methods (see BISA!, QISAM)
INDEXED BY option*
indexed data sets (see indexed files)
indexed files
(see also BISA!, QISAM, ESDS, KSDS)
~~C~!3~~ecbniq~~s .127-131, 173
.*Consult VS COBOL for OS(VS (GC26-3857)
adding to 127-128
additional information*
APPLY clause 131
calculating space requirements for 127
cataloging 126
creation and retrieving, in
general 510-513
creating of 123-126
DD statements required 123-126, 201
description 119-131, 173
index area 122
invalid key condition 148, 183
master index 127
overflow area 122-123
prime area 122
processing 119-131,180-192
random access 129-131
READ statement 129
RECORD KEY clause 119
reorganizing 128
REWRITE statement 129
sequential access 127-129
START statement 128
updating 127-128
VSAM 173-202
WRITE statement 129
indexed sequential access method
processing VSAM files 202
'
indexed sequential data sets (see indexed
files)
indexes*
indexing a table 305-306
indexing*
~nd~cative dump, description
254
~nd~rect addressing
101
~nformation Management System
object-time debugging 483
symbolic debugging 217
informative messages (see messages)
initial clause and state*
initialization*
INITIATE statement*
~nline procedures (optimization)
280
~nput CD*
input file*
IlfPUT option*
input phase of sort*
input/output
additional information*
bypassing of 56
error conditions
completion codes for 257-259
INVALID KEY 148
standard error 143-141
summary of 504-509
USE AFTER ERROR declarative 148-154
VSAM 184-188, 192-193
facilities described in DD
statement 51-69
OCR 544-560
subroutines 477-480
VSAM 173-202
input/output statements (see ACCEPT, CLOSE,
DISPLAY, OPEN, READ, REWRITE START
WRITE *)
"
input phase of sort*
INPUT PROCEDURE*
input queue*
Index
573
input stream
control statements for 21, 56
defining data in 56
delimiter in 56
INSERT statement*
insertion editing*
insertion symbol*
INSPECT statement 477, *
INSTALLATION paragraph*
in-stream procedures 70
instruction addressing causing
interrupt 257-259
integer*
Interactive Debug 247, 213
interface between COBOL and MCP 401, *
intermediate control*
intermediate results 294, 295, *
internal data*
internal decimal items*
internal decimal subroutines 473-476
internal floating-point*
internal floating-point
subroutines 473-476
internal representation*
inter-occurrence slack bytes*
INTER-PROGRAM COMMUNICATION*
interrupt address, examples 257-259
INTO option*
intra-record slack bytes*
INTRa macro 433, 426
invalid data 140, *
INVALID KEY
additional information*
general 148, 508, 509
in VSAM 183
ISAM used to process VSAM files 202
jamming (optimization)
270
job
accounting information 26, 20
address space 32
class assignment 31
control statement display 27
definition 18
holding for later execution 31
ident ifyinq 25
library 353-354
priority assignment 30
request for restart 28-29
setting time limits 30
storage specification 31
terminating 27
Job Control Language
character delimiters 24
coding 22-25
examples of
compilation 514-515, 231-235
linkage editing 240-241
fields of 23-~
notation 25
parameter for VSAM only 201
statement continuation 24
types of statements
command statement 70, 20
comment statem~nt
71, 20
574
DD statement 51-69, 20
delimiter statement 70, 20
EXEC statement 32-52
JOB statement 25-32, 20
null statement 70, 20
PROC statement 70, 20
VSAM file processing 201
job control procedures 20-81
cataloged procedures 356-367
checklist for 514-517
Checkpoint/Restart 397-400
definition 20
libraries 347-349
sort/merge 368-371
for user files (see file, processing
techniques)
job management routines 22
job schedulers
description 22
disposition messages from 241, 239
in communications 436
subroutine 479
utili ty (CJS)
436, 480
JOB statement 25-32, 20
accounting information 26
definition 25
forma t
26
parameters
ADDRSPC 32
CLASS 30
COND 27
MSGCLASS 31
MSGLEVEL 27
PRTY 30
RD 28
REGION 31
RESTART 29
TIME 30
TYPRUN 31
programmer identification 27
job step
bypassing
using JOB statement 27
using EXEC statement 35-37
definition 18
dispatching priority 50
restarting 48-49
JOBCAT DD statement 70
JOBLIB DD statement
description 69
example of use 516-517
restriction with cataloged
procedures 357
restriction with DDNAME
parameter 366
jobname 25
jo!nirig data items*
JUST*
JUSTIFIED clause*
KEEP subparameter 67
KEY for a table*
Key of reference*
KEY option*
(see also ACTUAL KEY clause and RECORD
KEY clause)
*Consult VS COBOL for OS/VS
(GC26-3857)
COBOL subroutine 348, 472-489
compilation, use of 73
concatenating 79
copy 349-351
creating 354-355
definition ,83
directory 347
for PGM parameter 32, 34
job 353
JOBLIB statement 69
link 347-348, 76-78
partitioned data set 83
pri vate 34, 69
procedure 32, 35
for program checkout 239
relationship to JOBLIB DD
statement 69, 78
relationship to SYSLIB DD statement 76
L, invalid in CURRENCY SIGN*
sharing 353
,label handling subroutine 478
sort 348
LABEL parameter 65-67
source program 349-353
LABEL RECORDS clause*
STEPLIB statement 70
label specification*
subroutines
LABEL subparameter 66
arithmetic 476, 475
labels
COBOL 348, 472-489
data set, rel~tionship to SELECT and DO
conversion 473-475
statements 144
input/output 477-480
nonstandard 156-157
intermediate results 294-295
routine return codes 159
sharing 353
standard 155
SYSLIB statement 76
standard user 155
system 34, 76
user 155-158
temporary 34
user totaling 156
user 349-353
volume 154-156
library management facility 353
nonstandard 156
LIBRARY module*
standard 155
library-name*
LANGLVL option
LIBRARY statement 333
and ASCII 91
LINAGE 297, *
and 'F IPS 40
line advancing*
and segment re-initialization 379
LINE clause*
general 38
line continuation*
language concepts and considerations*
line-control
216, *
language name*
LINE-COUNTER special register*
language structure*
line-number*
LAST DETAIL*
LINECNT compiler option 39
last printable line*
LINES AT BOTTOM/TOP 297, *
last-used state*
link library 347-348, 76-78
LCOL1 option of lister 44, 212
LINK macro to invoke compiler 499
LCOL2 option of lister 44, 212
left padding, justification, and truncation* linkage conventions 316-326
linkage, dynamic subprogram (see dynamic
length of figurative constant*
subprogram linkage)
less than «) character*
linkage
editor
LET loader option 48
additional input 332
level indicator*
calling compiled programs 500
level number
capacity 502-503
additional information*
checklist 515
normalized in glossary 236
data set requirements 16-78
level- 01 i tems*
definition 19
level 02-49 items*
external names 331
level- 66 i tems*
input
level-77 items*
additional 332
level-88 items*
primary
332
LIB compiler option 42
LIBRARY control statement 333
library
messages 240, 242
and BASIS card 351-352
options 47
automatic call 78, 349
output 240-242
changing 355
PARM options 47
COBOL copy 349-351
primary input 332
key-sequenced VSAM data sets
additional information*
AIXBLD usage with 186
defining 177-179
examples 181-183, 194-198
general 173
reading 190
writing 189
key words*
KEYS parameter in VSAM 179
keyword parameter of control
statements 23-24
KSDS data sets (see key-sequenced VSAM
data sets)
*Consult VS COBOL for OS/VS (GC26-3857)
Index
575
proces.sing 338- 34 0
user-specified data sets 16-18
with libraries 353-355
with preplanned overlay 340-341
linkage registers 322
Linkage section*
LINKlIB 16-18, 341-348
LIST linkage editor option 47
lister feature 203-212
additional information*
Data Division reformatting 204
description 44
Environment Division
reformatting 204
format conventions 210-211
Identification Division
reformatting 204
operation of 203
options 44-45, 212
output deck 204, 211
.
procedure Division reformatt1ng
reformatting 204-207
restrictions 203
source listing 210
specifying 212, 44
summary listing 211
type indicators 211
literal*
literal pool 231
literal table 502
literals, size considerations 502
LOAD compiler option 39
load list, example 267
LOAD macro to invoke compiler 499
load module
additional information*
as input to linkage editor 332
definition 19
length of 262
output 243-245
specificatio~ in EXEC statement
loader
cataloged procedure 360
data set ~equirements 78, 346
definition 19, 346
input
additional 346
primary 78
requirements 18
invoking 360
module map 244, 243
output 243, 244
PARM options 47-48
RES restriction 346
loading programs
additional input 346
cataloged procedure 360
primary output 346
locations in records*
LOCK option*
logical connectives*
logical operators*
logical page*
logical record
additional information*
length 13, 496-491
OUTLIM parameter 60
576
logical record area 168, 169
logical record length 13, 496-491
logical record size
for SYSIN 491
for SYSLIB 491
for SYSPRINT 491
for SYSPUNCH 497
LOW-VALUE (lOW-VALUES) figurative constant*
lower-case letters in notation 25, *
LRECl 13, 496-491
LSTCOMP option of lister 44, 212
LSTONlY option of lister 44, 212
LTM subparameter 66
LVL option of compiler 40
L120 option of lister 45, 212
L132 option of lister 45, 212
207
32
machine considerations 451-460
macro instructions
ATTACH 499
CALL 323-325
CHKPT 395, 396
DCB 490
GETMAIN 43
LINK 499
LOAD 499
magnetic tape
additional information*
data sets
sharing devices, sort/merge 310
using DEN and TRTCH
subparameters 86-81
devices
compiler optimization using 496
labels 154-159
in ~ort/merge feature 368, 370
volume
private 63-64
removable 64
reserved 64
scratch 64
main line routines 292
main program, definition 323, *
main storage
(see also storage allocation and storage
considera tions)
REGION parameter 51, 31
requirements for Sort/Merge 373, *
major control*
map
loader storage 243, 244
memory 234
module 244
MAP option
for linkage editor 47
for loader 41
mass storage
device 99, 100
space allocation
SPACE parameter 61
SPLIT parameter 62
SUBALLOC parameter 62
volume labels 154-156
volume status 63-65
vol umes 63-65
*ConsultVS COBOL for OS(VS (GC26-3857)
mass storage files*
master catalog (VSAM)
175-176
maximum length
additional information*
in Data Division 283
of blocks in COpy library 349
maximum number
additional information*
of logical records (SYSOUT)
60
maximum size (see maximum length)
maximum value*
MCP (see Message Control Program)
member, definition 83
MEMORY SIZE clause*
merge (see sort/merge feature)
merge subroutine 481
message access*
message code*
message concepts*
message control information*
Message Control program (MCP)
activating 426, 455
ANS requirements 432-443
building
assembling 445
executing 445
link-editing 445
communication with COBOL program 449-456
data sets 427
checkpoint data sets 445
group data sets 446
message queue 446
defining buffers 426
defining interface 449
defining process control blocks 455
defining terminal area 427-429
functions of 404
interface with COBOL program 449-456
JCL for 444
macros
CLOSE 426
DCB 427
INTRO 426
INVLIST 428
OPEN 426
PCP 427
READY 426
RETURN 426
TERMINAL 428
TLIST 428
TPROCESS 428
. TTABLE 428
message flow 401-404
message 537
RECEIVE statement 297
SEND statement 297
user tasks 404-405
writing a 404
Message Control System*
MESSAGE COUNT 479, *
MESSAGE DATE*
message delimiters*
message indicators*
message handler (MC~). 426-432
delimiter macros 429-430
for application programs 431-432
for terminal line groups 430
functional macros 429-43..0
*Consult VS COBOL for OS/VS (GC26-3857)
message queues*
message reception*
message release and return*
MESSAGE TIME*
message transfer*
message transmission*
message unavailable*
messages
additional information*
allocation
compiler 235
linkage editor 241
checkpoint 396
compile-time 569
compiler, summary of
238-239
disposition
compiler 238
linkage editor 241
error 35
ERRMSG 238-239
execution-time (see object-time)
identification codes 246
linkage editor 240,242
MCS considerations 537
numbered on SYSTERM 37
object-time 529-542
operator 246,538
queue analyzer
539-542
severity level of
compiler 35
linkage editor 35
sort/merge 371
unnum bered 538
U-type 529
Method B, to randomize 103
method of data reference*
minimun size*
minimum value*
minor control in a report*
minus sign and symbol*
mnemonic-name*
MOD subparameter 67
in Checkpoint/Restart 395
in compilation 75
definition 67
MODE subparameter 87
modular levels 292-293
module map 244
monitoring queues 436
MOVE statement 296,*
MOVE subroutines 476
MSGCLASS parameter 31
MSGLEVEL parameter
description 27
with restart 397
multidimensional table search*
multiple checkpoints 394
multiple file*
MULTIPLE FILE TAPE clause*
multiple indexing (VSAM)
173
multiple libraries for COpy 349
multiple redefinitions*
multiple results*
multiplication operator*
MULTIPLY statement*
multistep job 35-37
Index
577
multivolume files
additional information*
direct. 99-100
volume switching 99
MXIG subparameter 61
name, definition*
NAME compiler option 43
name field
of DD statement 56
of job statement 23
NAME statement 333
name subparameter of DD statement 58
names
cataloged procedures 57
data set, conventions used in 142
generation 57
procedure 502
qualification of 57
RENAMES clause 286
temporary 58
NATIVE collating sequence 293,*
negated condition*
negative data and sign*
nested statements*
"new" language (LANGLVL)
38,*
NEW subparameter 67
next executable statement*
NEXT GROUP clause*
NEXT options*
NL subparameter 66
NOADV option of compiler 44,160
NOAIXBLD option 48
NOBATCH option of compiler 42
NOCALL option of loader 48
NOCDECK option of lister 44,212
NOCLIST option of compiler 39
NOCOUNT option of compiler 44
NOCSYNTAX option of compiler 41
NO DATA option*
NODEBUG option 48
NO DECK option of compiler 39
NODMAP option of compiler 39
NODUMP option of compiler 44
NODYNAM option of compiter 43
no end indicator*
NOENDJOB option of compiler 43
NOFDECK option of lister 44,212
NOFLOW option of compiler 41,48
NOLET option of loader 48
NOLIB option of compiler 42
NOLOAD option of compiler 39
NOLVL option of compiler 40
NOLST option of lister 44,212
NOMAP option of loader 47
NOMINAL KEY clause 129-130
NONAME option of compiler 43
noncontiguous items*
nondeclarative reference*
nonfooting body group*
noninteger*
nonnumeric comparisons*
nonn urn er ic it em*
nonnumeric literals*
nonnumeric operands*
nonreentrant subroutines 484-489
578
nonreusable subroutines 484-489
nonstandard labels 157
nonswitched line*
NONUM option of compiler 42
non unique keys*
non-VSAM file, converting to VSAM 202
non-VSAM file processing (see user file
processing)
nonzero data*
NOOPTIMIZE option of compiler 41
NOPMAP option of compiler 39
NOPRINT option
of compiler 47
of loader 48
NOPWREAD subparameter 66
NORES option of loader 48
NORESIDENT option of compiler 43
NO REWIND option*
normalized level numbers in glossary 236
NOSEO option of compiler 39
NOSOURCE option of compiler 39
NOSTATE option of compiler 40
NOSUPMAP option of compiler 40
NOSXREF option of compiler 42
NOSYMDMP option of compiler 41
NOSYNTAX option of compiler 41
NOT*
NOTE statement 296
NOTERM option of compiler 47
NOTEST option of compiler 47
NOTRUNC option of compiler 40
NOVBREF option of compiler 44
NOVBSUM option of compiler 44
NOVERB option of compiler 39
NOXREF option of compiler 42
NOZWB option of compiler 40
NSL subparameter 66
NUCLEUS module*
null group*
null statement 72
NULLFILE DD parameter 58,74
NUM compiler option 42
NUMBERED specification in VSAM 179
numerals*
numeric category*
numeric characters*
numeric class*
numeric comparisons 255, *
numeric edited*
numeric first character*
numeric item*
numeric literal*
numeric operands*
object code listing 237
OBJECT-COMPUTER paragraph*
object module
contents 239-240
deck 239
definition 18
dumps using 258-268
listing 237
size considerations 501-502
object of OCCURS DEPENDING ON*
object of REDEFINES *
object of relatioI) condi tion*
*Consult VS COBOL for OS/VS (GC26-3857)
object program*
object-time control cards~YMDM~
continuation cards 215
control statement placement 215
example of 220-230
line-control cards 216
program-control cards 215
syntax rules 215
object-time options
list of
48-49
subroutine for 472
object-time overlay 340-343
object-time subroutine library 384,472-489
occurrence number*
OCCURS clause
additional information*
. causing errors 255
DEPENDING ON option 304-305
OCCURS DEPENDING ON clause
additional information*
relationship to record formats 170-172
table 502
OCR (optical character reader)
"old" language (LANGLVL)
38
OLD subparameter 67
OMITTED option*
ON SIZE ERROR option
binary items 291
intermediate results 291
ON statement 251, *
ON OVERFLOW 295,317, *
one*
online printing*
ONLY subparameter 36,37
OPEN statement
additional information*
EXTEND 142,258
for several files 296
multiple use of 459
VSAM files 185-188
operand field
bypassing I/O 56
data definition 56
on control statement 23
operands*
operating system environment
Conversational Monitor System 19
OS/VS 1 19
OS/VS2 19
operation field 23
operation order*
operational sign*
operator
commands 70
intervention*
messages 246,529,538
OPTCD subparameter 87
optical character reader (OCR)
additional information*
COBOL capabilities 544
COpy member 546-549
document design 549
exception handling 552
file description 552
format record assembly 553-554, 556
I/O requests 544
implementing an application 549
parameter data area 545
*Consult VS COBOL for OS/VS (GC26-3857)
procedural code 552
processing tapes from Model 2 560
record description 552
sample data 557
sample document 555
sample processing program 558-560
sample program 553
status key 545
status key values 550-551
optical character reader interface
subroutine 481
optimization, compiler 496-498
optimization methods 279-281
backward movement 279
common expression elimination 279
efficiency guidelines 281
inline procedures 280
jamming 280
resequencing program 279
SYMDMP output 279
tabling 280
unrolling 279
unswitching 280
OPTIMIZE compiler option 41, 237
optimizing sort performance*
optional clauses*
optional entries*
optional phrase*
optional services (see OPTCD subparamet
optional word *
options
error processing (VSAM)
163
for compilation 38-47
for execution 48
for linkage editing 47
for lister 44,212
for loader 47-48
PARM summary 46
OR*
order of*
ORDER statement 334
ordering records using sort/merge*
ORGANIZATION clause*
OS/VS COBOL*
OS/VS1
ADDRSPC parameter 32
control program 19
OUTLIM parameter 60
SCAN action 31
TERM parameter 60
OS/VS2.
ADDRSPC parameter 32
control program 19
DYNAM parameter 57
intermediate data sets 458
REGION parameter 458,21
SCAN error 31
TERM parameter 6C
with TSO 57
OUT subparameter 66
OUTLIM parameter 60
output 231-246
compiler 231-239
(see also compiler, output)
copies of data set 60
display of all compiler
messages 238-239
displaying control statements 27
Index
579
ERRMSG program to display
~essages
238-239
execution of load module 243-245
linkage editor 240-242
lister deck 204,211
load module execution 243-245
loader 243
messages
compiler 238-239
linkage editor 242
load module execution 243
reformatted listing 44
requesting various kinds 246
return codes 35-37
sample program 461-471
stream data sets 134
suppressing 496-497
SYSOUT parameters 68
system 246
output CD*
output deck, lister 204,211
output device*
output file*
output listing format
FCB parameter 68
lister feature 44
of compiler 231-239
output mode*
output option*
output procedure*
output record limit (SYSOUT)
60
overflow area (see QISAM)
overflow condition
additional information*
index 122
synonym 108
overlapping delimiters and operands*
overlay
dynamic 341-343
preplanned 340-341
statement 340-342
structures 340
overlayable segments*
overriding DD statements 364-366
OVFLOW 125
OVLY linkage editor 47
P in PICTURE and CURRENCY SIGN*
packed decimal item*
padding*
page advancing*
page areas*
page body*
page breaks 301-302, *
page change in a'report*
PAGE clause*
PAGE-COUNTER special register*
page end*
page fit test*
PAGE-FOOTING*
page format control*
PAGE HEADING*
page margins*
PAGE option*
page overflow*
page placement*
580
pagp positioning*
Eage size*
PAGE statement 334
paging 51
paragraph*
parameter data area (OCR)
545
parameters
compared to arguments 322,323
key-word 23-24
positional 23
subparameters 23
. VSAM only (JCL)
201
parentheses*
PARM 48
PARM option
compiler options 38-47
job card 48-49
linkage editor options 47
restrictions 37
significant characters 37
summary 46
with equal sign 37
partial key*
partial list of prime numbers 105
partial message*
partitioned data sets
description 83
directory 333,61
member 83
primary quantity for 61,62
secondary quantity for 61
system library 34
temporary libraries 34
PASS subparameter 67
PASSWORD clause*
PASSWORD subparameter 66
passwords in VSAM 181
PATH command 175,178
PATHENTRY specification in VSAM 179
pathname as data set name 201
PSS (see partitioned data set)
PERFORM statement 296,378,*
performed procedures*
period*
permanent segment 378,*
permanently resident volumes· 63-64
permissible comparisons and options*
PGM in EXEC statement 32,34
PGT (see program global table)
phrase, definition*
physical page*
physical record 61-62,*
physical sequential file
accessing 85-89
additional information*
data control block for 491
data set 133
DD statement parameters 123-126
description 85-89
error processing 143-154,508,87
EXTEND 142
locating data ares 268
sort feature, uses 6 368
subroutone for 479
user label totaling 155
with spanned reco~ds 274
*Consult VS COBOL for OS/VS (GC26-3857)
process definition*
PICTURE CLAUSE
processing of files*
additional information*
processing program 18
efficient use of 285-287
processing rules*
storage allocation 287
processing subroutines 292
plural figurative constant*
procstep.ddname 56
plus sign 287,*
procstep subparameter 63
PMAP compiler option 39
program
POINTER*
(see also programming techni~ues)
position in record*
called 317-318,325
positive data*
calling 317-325
POSITIVE sign*
checkout 247-278
prefixes 283
collating sequences 293
preplanned linkage editor 340-341
COUNT option 247,278
presentation rules, TYPE*
debugging 247
PRESRES, member of SYS1.PROCLIB 64
(see also symbolic debugging;
preventing core fragmentation 43
lister feature)
primary input, for called and calling
completion code 257-259
. programs 332,346
dumps 254-257,260-263
primary keys, (VSAM)
173,189
errors
PRIME, in QISAM 122
I/O 258
prime area (QISAM)
122
invalid data 255-256
prime number list 105
other 256-257
prime record key*
examples 262-273
print files*
execution statistics 278
print line size in repor~*
I/O errors 258
PRINT option
incomplete abnormal termination 277
for compiler 47
interruption, finding location
for loader 48
of 259
print suppression*
invalid data errors 255-256
printer, determining line spacing 85
language 247
printer channel control*
other errors 256-257
printer character set 60
execution
printer device, SEND*
from private library 34
printer spacing*
from system library 34
priority, assinging
from temporary library 34
for a job 30
multistep job 35-37
for a job step 50
interrupt 259
priority numbers 378,*
linkage editor 338-340
priority schedulers 22
resequencing 279
priority scheduling system
sample 461-471
EXEC statement parameters 50
selective testing of 217-219,253-254
JOB statement parameters 30
techniques (see programming techniques)
sharing data sets 67
PROGRAM COLLATING SEQUENCE (see collating
SYSOUT parameter for 68
sequence)
PRIVATE subparameter 65
program-control cards 215
private volume 64
program global table (PGT)
237,527-528
problems with compiler, resolving 543
PROGRAM-ID 213,*
PROC statement 70
program-name*
procedure*
program relationships*
procedure branching statement*
program segments*
Procedure Division
program structure*
additional information*
program switch*
intermediate results 293,294
program syntax*
modular levels 292
program termination*
programming techniques 292-299
programmer identification 27
reformatting 207-208
programming nptes*
report writer considerations 299-304
programming techiques 282-315
state,emts (see compiler directing
(see also program)
statements, conditional statements,
Data Division 282-315
imperative statements)
Environment Division 282-283
string manipulation considerations 298-299
general 282
table handling considerations 304-309
optimization methods 278-281
teleprocessing condiderations 309-315
Procedure Division 292-299
verbs 295-298
queue structure considerations 309-315
procedure library 34,348
rep~rt writer
299-304
procedure-name,*
sort feature 372-373
procedure-name table 502
procedures, in-stream 70
*Consult VS COBOL for OSLVS (GC26-3857)
Index
581
table handling 304-309
VSAM 180-193
PRTSP suboarameter 87
PRTY parameter 30
pseudo data set 56
pseudo-text*
public volume 64
punch device*
punch files*
punctuation character*
punctuation rules
Q routines 472
QISAM
(see slao BISAM, indexed files)
considerations when using 128-131
data control block 128
data sets 134
creating 123-125
definition 82
deleting records in 129
reorganizing 129-130
DD statement parameters 128-129
error processing for 143-147, 508
indexes, description 122-123
master index 127
overflow area, description 122, 123
prime area, description 122
single volume file 125-126
QNAME parameter 58
QSAM
data control block 491
data set 133
DD statement parameters 123-126
description 85-89
error processing for 143-154,508,87
extending 142
locating data areas 268
sort feature, uses of 368
subroutine for 479
user label totaling 155
with spanned records 274
qualification*
qualified data name*
qualifiers*
queue access*
Queue Analyzer Routine 309-315
queue blocks
and locating TCAM data areas 275-276
sample program 275
queue concepts*
QUEUE DEPTH field and IF statement 280
queue messages*
queue name 449, *
QUEUE object-time option
49,438
queue relationships*
queue structure
accessing with COBOL 312-315
additional information*
example 310,311
Queue Structure Description routine 315
SCAN subroutine 479
SYMBOLIC QUEUE name 309
quotation mark 40,*
QUOTE compiler option 40
QUOTE (QUOTES)
figurative constant 40,*
quotient*
582
R, in currency sign*
random access*
randomizing techniques 101-103
range of procedures, PERFORM*
ranges of value*
RD Entry*
RD parameter
for a job 28
for a job step 49
with checkpoint 396-397
with deferred checkpoint 69
READ INTO option 296
READ statement
additional information*
in BISAM 130
in QISAM 127-130
in VSAM 189-190
READY TRACE statement 251,39,*
RECEIVE statement 297,*
receiving device*
receiving item*
receiving field*
RECFM subparameter
in compilation 497
in DISPLAY statement 79-80
record
additional information*
addressing 83
blocked 80
capacity 93
dummy 93
duplicate 504
formats 84
fixed-length 160
spanned 164-165
unspecified 161
variable-length 161-164
segments 165-166
size, logical
for SYSIN 497
for SYSLIB 497
for SYSPRIWT 497
for SYSPUNCH 497
size restriction, physical 61
sort/merge fields 372
record area*
record availability*
RECORD CONTAINS clause 284,*
record discription (OCR)
552
record discription entry
in BISAM 129-130
in QISAM 129
record formats 160-172
effect of OCCURS clause 170-172
fixed length 160
spanned 164-170
unspecified 161
variable length 161-164
RECORD KEY*
re cord level:«
·record-name*
record seguencing*
record size*
recording mode*
records in error*
RECORDS option*
REDEFINES clause 285-286,*
REEL options*
*Consult VS COBOL for OS/VS (GC26-3857)
ceentrant subrotiti,nes, list of 484-489
~EF subparameter
65
ceference frequency*
ceference summary*
ceferencing tables 304
~EGION parameter
ADDRSPC parameter 51,31
for OS/VS2 21,458
in EXEC statement 51
in JOB statement 31
main storage 31
used in compilation 458
used in execution 458
register assignment, location in
output 237
~einitialization*
~ELATE specification
~elation character*
~elation condition*
~elational-operator*
~elative files
for VSAM
178
accessing 112
additional information*
allocating space for 112
COBOL clause for 118
creating 111-112
error processing 143-154
Job Control Language for 120
NOMINAL KEY, use of
110,111
processing 110-117
random access 112-113
sample program 114-117
sequential access 112
VSAM 174
~elative indexing*
~elative indexing*
tELATIVE key*
~ela ti ve line*
~elative NEXT GRoup*
~elative organization*
~elative record data sets (VSAM)
defining 179
described 174
reading 181,190
writing 189
~elative record number*
tELEASE statement in sort*
~eleasing a job (RELEASE)
31
~elocation list dictionar.y (RLD)
503
~eminder*
tEMARK papagraph*
~emote station*
~emovable volumes
63,64
tEMOVAL option*
~emoving file records*
tENAMES clause 286,*
~epeti tion of i tem*
~epetitive execution*
:eplacement editing*
:eplacement of file records*
~eplacement rules for library-text*
tEPLACING option*
~eport c alcula tions*
tEPORT clause*
~port description (RD)*
~eport file*
tEPORT FOOTING*
teport Group 299-300, *
~Consult
VS COBOL for OS/VS (GC26-3857)
REPORT HEADING*
report-line*
report-name*
report page depth*
report printing online*
report processing*
Report section*
report, writer
additional information*
CODE clause 302
Data Division considerations
floating first detail 303-304
output footings 303
output line overlay 301
Procedure Division considerations 299-304
size considerations 303,304
SUM 300-301
tables 502
reports, decribing*
requesting a message class 31
requesting a unit 58-59
required clauses, entries, items, words*
RERUN clause
additional information*
and JCL 49-50
and RD parameter 394,396
RES loader option 48
resequencing program (optimization)
279
RESERVE clause 85,*
reserved volumes 64
reserved words*
RESET option of sum*
RESET TRACE statement 251
RESIDENT
'example 337
linkage 335
specifying 335,336
RESIDENT compiler option 43
resolving compiler problems 543
Restart
(see also Checkpoint/Restart)
automatic 397
checkpoint 394
(see also Checkpoint)
deferred 397-398
for cataloged procedure 48-49
in a job 28-29
in a job step 48-49
initiating 394
RD parameter 396-397
system routine 396
RESTART parameter (see RD parameter)
restarting a program*
restrictions*
result field*
RETAIN subpa~ameter 65
RETPD subparameter 66
retrieving data sets
cataloged 138
example of 140
noncatloged 139
passed
139
through an input stream 139-140
VSAM 195-198
with additional output 139
return code 35,158,*
RETURN-CODE special register 317,322,*
return mechanism (sort/merael*
Index
583
return of control*
returij register 322
RETURN statement for sort/merge*
reusable subroutines, list of 484-489
reusable VSAM data sets 179
REUSE parameter in VSAM 179
rewinding of tape files*
REWRITE statement
additional information*
in BISAM 130
in QIS.AM 128
in VSAM 189
rightmost sign specification*
right- pa dding*
right parenthesis*
RLD (see relocation list dictionary)
RLSE subparameter 61
ROUND subparameter 61
ROUNDED option*
routine-name*
RRDS (see relative record data sets)
RT subparameter 60
rules*
r un un it 32 3 , *
S, PICTURE clause symbol*
S-mode records 164-165,*
SAME clause*
sample program output 461-471
save area layout 332
scaling 286,*
SCAN with HOLD 31
schedulers
job 22
!:laster 22
priority 22
SD entry*
SEARCH statement
additional information*
subroutine for 481
use of 307-309
searching a table 307-308
secondary quantity subparameter
for SPACE 61
for SPLIT 62
section*
section header*
section-name*
SECURITY paragraph*
SEGMENT-LIMIT clause*
segment of a message*
SEGMENT option*
segment work area 165,169-170
segmentation
additional inf6rmation*
and PERFORM statement 378
effect of LANGLVL 379
output 379-393
program organization 378
subroutine 481
SELECT clause
additional information*
relationship to DD statement
with user files 82
SELECT OPTION clause*
SELECT OPTIONAL statement 56
584
144
selective summation*
SEND statement 297,*
sending field*
sentence*
SEP parameter 58
SEPARATE option of SIGN
clause 288,*
separate programs*
separate sign*
separator*
SEQ compiler option 39
sequence*
sequencing records using sort/merge*
sequential access*
sequential data sets
DUMMY parameter 56
for VSAM 173,180
on 'mass storage devices 133
sequential files*
sequential single volume files*
SER subparameter 65
serial search of a table 308,*
series connectives*
SET statement 305-306,*
SETEOF macro 455
setting time limi~s
on a job 30
on a job step 50
severity levels 35, 238
sharing
data sets 67
COBOL library subroutines
353
sharing storage*
SHR subparameter 67
sign, efficient use of 287-288
sign character*
SIGN clause 287-288,*
sign condi·tion*
sign control*
sign in numeric literal*
SIGN IS SEPARATE*
signed numeric*
significance order*
simple condition*
simple insertion editing*
single checkpoint 384
single entry report group*
single IF*
single message*
single quotation mark*
single-segment message 297
single-statement paragraph*
single values*
singular figurative constant*
SIZE ERROR option 255,*
size of operands*
SIZE option
for compiler 38
for loader 48
SIZE, STRING delimiter*
SL subparameter 89, 90
~sl ack by 1:es*
slash (/) 48,*
SORT-CORE-SIZE special register 373,*
sort debug subroutine 481
sort file*
SORT-FILE-SIZE special registei373,*
sort library 311~ 3~8
*Consult VS COBOL for OS/yS (GC26-3857)
sort/merge debug feature 377
Sort/Merge Feature 368-376
additional information*
alternate collating sequence 293,375
and Checkpoint/Restart feature 372
ASCII considerations 375
cataloging 371
collating sequence 375
completion codes 371
considerations 460
Data Division considerations 374
data set size 373
DD statements 368-371
for ASCII files 375
linkage with SORT/MERGE 373
main storage registers 373
main storage requirements 373
messages 373-374
program example 370
record fields 372
sample program 370
sharing devices 370
SPACE parameter 369
storage allocation 373
subrouting~SQ
terminating 371
variable length records 374,376
with Checkpoint/Restart 372
with spanned records 368
Sort-Merge File Description (SD)*
SORT MESSAGE special register*
SORT-MODE-SIZE special registe.r*
SORT-RETURN special register 371-372,*
SORT statement*
sort subroutine 348,480
sort work-file 368,*
SORT CDS DD card 377
sorted recol;ds*
sorting variable-length records 374, 376
SORTLIB DD statement 370
SORTWKnn DO statement 368-369
SOURCE clause*
SOURCE compiler option 39
SOURCE-COMPUTER paragraph*
source/destination and MCS*
source item*
source listing by lister 210-211
source module 215,18
source program 501-503,*
source program library 349-350
(see also COBOL copy library)
source program library feature*
SOURCE-SUM correlation 300
space*
SPACE (SpACES) figurative constant*
SPACE parameter 61-62
in BSAM 88,89
in creating data sets 132-134
in QISAM 124
in sort feature 369
SPACEn option 40
subparameters 61-62
SPACE subparameter 61-62
SPACEn compiler option 40
spaces*
spacing*
*Consult VS COBOL for OS/VS (GC26-3857)
spanned records 164-170
blocked 164-165
description 164-165
direct processing 169-170
formatting 164-165
locating in dumps 274-275
logical record area 166
segment work area 164
sequential processing 164-165
specification 164,168-169
wit.h sort 368
special character*
special characters in job control
language 25
special collating sequences*
special features*
special insertion editing*
special level-number concepts*
SPECIAL-NAMES paragraph*
special registe~s
additional*
DEBUG-ITEM 248
for date and time 481
RETURN-CODE 317, 322
SOFT-CORE-SIZE 373
SORT-RETURN 371-372
time and date 481
special situations, STOP useful for*
specification order*
specifying address space parameter
description 32
with REGION parameter 31
specifying data set status and
disposition 67-68
specifying loader input 78
SPIE subroutine 483
SPLIT parameter
description 62
in creating data sets 132-134
in QISAM 124
SPLIT subparameters 62
square brackets in formats 25, *
STACK subparameter 87
stacked items, in job control notation
standard ali~nment rules*
standard COBOL format*
standard data format*
standard labels 155-156;*
STANDARD option*
standard selection (LANGLVL)
38
standard sequential file (see physical
sequential file)
standard system I/O error routine*
standard user labels 155-156
STANDARD-1 collating sequence 293,*
STAiT statement 298,*
START verb (VSAM)
183
STATE compiler option 4C
subroutines 482
statement*
statement number subroutine 482
static CALL statement 318,*
static values of a table*
statistics in output 237
Status Key (OCR) 545,550-551
Index
25
585
status Key (QSAM and VSAM)
additional information*
QSAM 255-256,87,148
VSAM 183,184-188,192-193
step restart
in a job 29
in a job step 48-49
STEPCAT DD statement 70
STEPLIB DD statement 69
stepname 34,63
steps to resolve compiler problems 543
STOP RUN initialization subroutine 472
STOP RUN messages subroutine 472
STOP RUN statement
additional information*
and assembler language program 323-325
and ENDJOB option 43
STOP RUN t~rmination subroutine 472
STOP statement*
storage allocation
(see also main storage and storage
considera tions)
additional information*
for compilation 73,501
for execution, job step 51
for linkage editing 502-503
for overlay processing 340-345
for sort feature 373
for source program 501-502
storage considerations 501-502
(see also main storage and storage
allocation)
storage format, USAGE*
storage layout of table*
storage map, for loader 244,243
storage, mass (see mass storage)
storage of records*
storage sharing*
storage volume 63-65
STRING statement 297,*
structure of COBOL*
sub-queue structures 309-315,*
SUBALLOC parameter 62
SUBALLOC subparameter
description 62-63
in creating data sets 132
subdivisions of page*
subfield contents of DEBUG-ITEM 249,*
subject*
subordinate entries*
subordinate report group*
subparameters 23
subprogram
additional information*
and CANCEL statement 335
and dynamic CALL 317,318
and static CALL 318
subprogram linkage feature*
subroutine library (see library.~
subroutines
(see also library)
arithmetic 475-476
conversion 473-475
data management 477-480
data manipulation 476-477
external references 346
for linkage 472
for special features
483
input/output 477-480
586
subscript*
subscript redefinition 286
subscriped data name*
subscriping*
substitution field*
SUBTRACT statement*
subtraction operator*
SUL subparameter 66
SUM clause*
SUM counter*
SUM statement 300-301
summary listing by lister 209,211
summary reporting*
summation*
superscript in job control notation 25
SUPMAP compiler option 40
SUPPRESS option*
suppression of report groups*
suppression of sequence checking*
suspension of execution*
switches (see UPSI switches)
switch-status condition*
switched line*
SXREF compiler option 42
symbol orer, PICTURE*
symbolic debugging 213-230
flow trace option 213-214
(see also FLOW compiler option)
interactive debug option 213
(see also TEST compiler option)
run unit considerations 216
statement nember option 213
(see also STATE compiler option)
symbolic debug option 214-216
(see also SYMDMP co mpiler option)
object-time control cards 215-216
sample program 217-230
TSO considerations 214
type codes 218
under Information Management System
(IMS)
217
symbolic destinations 435,*
symbolic dump subroutine 482
SYMBOLIC QUEUE
accessing queue structures 312-313
additional information*
Q Analyzer routine 309-315
SYMBOLIC SOURCE*
SYMBOLIC SUB-QUEUE 309,311-312,*
symbols used in PICTURE clause*
SYMDMP compiler option 41
(see also symbolic debugging)
abnormal termination dump 214
abnormal termination message 214
and data-names 214
Data Division dump 214
general considerations 216
object-time control cards 215-216
operation of 214
sample program 217-230
specifying through PARM
parameter 214-215
subroutines 482
type codes 218
SYMDMP error message subroutine ~~1
SYNCHRONIZED clause*
synonym overflow 108
syntax-checking compilation 247
*Consult VS COBOL for OS/VS (GC26-3857)
SYNTAX compiler option 41
syntax of program*
SYSABEND DD statement 69,80-81,246
SYSCHK DD statement 69,398
SYSCJS DD statement 437
SYSCOUNT DD statement 81
SYSCP 21
SYSDA 21
SYSDBG data set
default for 216
requirement for 246
use of 215
SYSDBOUT DD card 213,246
for COUNT option 81
system logical input unit*
SYSDTERM DD card 214,246
SYSIN DD statement
concatenating with SYSLIN 367
for compilation 74
in cataloged procedures 359-363
logical record size for 497
relationship to ACCEPT statement 80
SYSIN-SYSOUT 458
SYSLIB DD statement
for compilation 76
for copy 349
for linkage editing 78
for loading 78
logical record size for 497
SYSLIN DD statement
concatenating with SYSIN 367
for compilation 75
for linkage editing 76
for loading 78
logical record size for 497
SYSLMOD DD statement
for linkage editing 77-78
with job library 353
SYSLOUT DD statement for loading
79
SYSOUT system logical output unit*
SYSOUT parameter 68
and COPIES parameter 60
effect of SYST option 43
in sort feature 370
relationship to DISPLAY statement 79-80
subparameters 68
use of 68
SYSOUT subparameters 68
SYSPRINT DD statement
for compiler 74
for linkage editor 76
for VSAM 186
loqical record size for 497
SYSPUNCH definition*
SYSPUNCH DD statement
for compiler 74
logical record size for 497
relationship to DISPLAY statement 79-80
SYSSQ 21,59
SYST compiler option 43
system catalog, creating 18
system considerations, subprogram linking*
system console*
system dependencies*
system diagnostic messages 246
system error recovery 143-149,*
system-generated code*
system independent binary items*
*Consult VS COBOL for OS/VS (GC26-3857)
system informa tion transfer,. ACCEPT*
system input device*
system logical output device*
system-name (assignment-name)
90,100,"*
system output messages 246
system parameter library 64
system restart routine 396
System/370 unit record processing*
SYSTERM DD statement 74,77
SYSUDUMP DD statement 69,246
SYSUT1
block size 496
for compilation 73
for linkage editing 78
SYSUT2 73,496
SYSUT3 73,496
SYSUT4 73,496
SYSUT5
block size 498
for compilatiion 73
required by SYMDMP and TEST 41,217
SYSUT6
blocksize 498
for compilation 73
required by LVL 40
SYS1.COBLIB 348
SYS1.LINKLIB 348
SYS1.PROCLIB
adding procedures to 356-357
description 348
SYS1.S0RTLIB
description 348,370
storage allocation for 373
SYS1.TELCMLIB 447
S01 and S02 function-names*
table elements 304-309,*
table handling 304-309,*
table layout*
table of moves*
table references*
table values*
tables
building 309
handling considerations 304-308
storage limitations 501-502
subscripts 304
tabling (optimization)
280
TALLY special register*
TALLYING option*
tape (see magnetic tape)
tape fi1e*
tape volume state 64
tapes from 3886 OCR 560
task global table 236-237
fields of 527
use to locate data-names 268
using SYMDMP to examine 214
TeAM (telecommunications access method)
data areas 275-276
locating 275-276
queue blocks 276
RECEIVE statement 276
SEND statement 276
service facilities 456
writing compatible programs 446
Index
587
TCLOSE facility
74
(communications feature)
(see also MCP, message control program)
and CD entries 284
and Communication Section 284
and MCP 401,404
ANS standard requirements 432
environment 401
sample MCP 406-425
temporary data set
creating 135
description 63
temporary library 34
temporary names 58
TERM compiler option 47
effect of LVL option 40
TERM parameter 60
terminal device, SEND*
terminal error messages 35-36
TERMINAL option*
terminal table 433-436
TERMINATE statement*
terminating file processing*
termination of execution*
termination of job 27
TEST compiler option 47,213
requires SYSUT5 73
TESTRUN sample program 461-471
TEXT LENGTH*
text name*
text punch table 501
text word*
TGT (see task global ta~le)
three-dimensional table*
three operands, varying*
TIME-OF-DAY special register 481,*
TIME parameter
for a job 30
for a job step 50
TIME special register 481,*
TIMES option of PERFORM*
TO options*
top page margin*
totaling, user label 155
TPROCESS entries 432
trace option 88
TRACE statement
description 251-252
relationship to SYSOUT DD statement 80
TRACE subroutine 482
track
addressing 83,91
capacity 101,102,103
identifier 91
index 120-122
space for 94,95
TRACK-LIMIT clause 94,95
trailer labels 159,*
TRAILING option*
transfer of control*
transfer of data*
TRANSFORM statement 298,*
TRANSFORM subroutine 477
transformation rules*
transmission to messages by SEND*
TRK subparameter 61
TRTCH subparameter 87
true condition*
telep~ocessing
588
TRUNC compiler option 40
truncation of data*
truth value*
TS sub parameter 60
two-dimensional table*
two operands, varying*
twos complement form*
TYPE clause*
type indicators for lister
TYPRUN parameter 31
211
U-type abend 529,254
UCS parameter 60
unary operator*
unblocked files*
unblocked records
fixed-length 160-161
permissible file techniques 84
spanned 164-165
variable-length 161-163
unblocking, automatic*
UNCATLG subparameter 68
unconditional GO TO*
unconditional syntax-checking compilation
undefined length records (see unspecified
length records)
unequal fields 286-287
unequal size operands in nonnumeric
comparisons*
unique table references*
UNIQUEKEY specification (VSAM)
179
unit, requesting 58
UNIT option*
UNIT parameter
creating data sets with 131
description 58
multivolume data sets using 99-100
retrieving data sets with 139
sort programs using 369
subparameters 59
unit record data set 133
unit record device,DD statement for 141
unit record file*
UNIT sub parameters 59
unloaded files (VSAM)
185
unrolling (optimization)
279
unsigned data, USAGE*
unsigned integer, stop*
unsigned numeric literal*
unsigned operand*
unspecified length records, fo:··mat 161
unspec~fied record format (see U-mode
records)
UNSTRING statement 299,*
unswitching (optimization)
280
UNTIL option*
UPDATE Specification in VSAM ~79
updating files*
UPGRADE specification in VSAM 179
upon options*
upper-case letters. in job control
notation 25
UPSI.switches 293,48.*
41
*Consult VS COBOL for OS/VS (GC26-3857
USAGE clause
additional information*
causing errors 255
efficient use of 288-290
example 236
USE AFTER ERROR option
description 148-149,183-184
in file processing techniques 491-494
USE BEFORE REPORTING*
USE FOR DEBUGGING
additional information*
controlled by DEBUG option 48
effect on SYMDMP option 41
effect on TEST option 47
example 250
general 248-249
subroutine for 482
USE PROCEDURES*
USE statement (see declaratives)
user abends 529,254,44
user catalog (VSAM)
176
user completion code 529,254, 44
user-defined files 82
user-defined word*
user file processing
non-VSAM files 82-159
ASCII files 89-90
data set organization 83
direct file processing 91
error processing 143-154
indexed sequential 119-130
label processing 154-159
names 82
physical sequential 85-89
processing techniques 83-130
relative file processing 110-118
standard (physical) sequential 85-89
VSAM files 173-202
access method services 174-180,186
COBOL language usage 193-201
converting non-VSAM files 201-202
current record pointer 181
error handling 183-184
features unavailable 202
initial loading of records 188
ISAM programs with 201-202
JCL for 201
password usage 181
programming consideration 180-191
status key values 183
for action requests 192-193
for OPEN requests 184-188
types of data sets 173-174
warning 183
user-initiated dumps 254
user label procedure 156-157
user labels 155-159
(see also labels)
and ASCII files 158-159
exit list codes 158
exits 158
return codes 158
totaling 156
• user libraries 349-354,69
'<
user parameters for execution 48
User Program Status Indicator
(see UPSI switches)
.Consult VS COBOL for OS/VS (GC26-3857)
user-specified collating sequences
(see collating sequence)
user-specified data sets 78-79
USING option
for execution parameters 48,*
in sort/merge 368,*
utility da~s sets
and job control procedures 21
for compilation 73,75
for linkage editing 78,77
utility programs
IEBUPDTE 348,349
IEHLIST 278
IEHMOVE 347
IEHPROGM 277
utility subroutines for communications
ILBDCJS 436-438,480
ILBOQSU 479,487
V, in CURRENCY sign and PICTURE clause*
V recording mode*
valid and invalid elementary moves*
valid execution sequence, PERFORM*
validity checking*
VALUE clause*
VALUE OF clause*
value of numers literal*
value range of conditional GO TO*
variable-length item*
variable-length record size specification*
variable-length records
additional information*
and OCCURS DEPENDING ON 170-172
description 161
format 161-164
variable-length table*
variable line lengths*
variable page spacing*
variable record sizes*
varying operands and options*
VB REF compiler option 44
VBSUM compiler option 44
verb*
VERB compiler option 39,237
verb cross-reference 44
verb summary 44
verb usage (count)
44
verbs, techniques with 295-299
VERIFY .
FCB 59
implicit in VSAM 184
UCS 60
vertical page positioning*
vertical spacing*
virtual storage access method (see VSAM
and user file processing)
volume
definition 18
labels 154-159
ASCII 159
nonstandard 151.
standard 155-156
magnetic tape 64
mass.storage 63,64
nonspecific 63
Index
589
prameter (see VOLUME parameter)
permanently resident 63
pri vate 64
public 64
reference 64
removable 64
reserved 64
specific 63
state 64
storage 64
volume, switching 99
volume-count subparameter 65
volume lables*
VOLUME parameter 63-65
creating data sets with 133
description 63-64
retrieving data sets with 139
subparameters 65
with UNIT parameter 59
volume removal*
volume-sequence-number subparameter
volume swi tch*
VSAM (virtual storage access method)
additional information*
AFF subparameter 59
AMP parameter 69
DEFER subparameter 59
DUMMY parameter 56
features not available 202
file processing (see user file
proc ess in g)
JOBCAT statement 70
SEP subparameter £;9
SHR subparameter 68
STEPCAT statement 70
user catalog 70
warning about 183
VSAM subroutines 479
separate modules 285
WRITE FROM option 296
WRITE ADVANCING 297,*
WRITE AFTER ADVANCING option
"additional information*
ADV option 44
restriction with PRTSP parameter
use of 85
WRITE AFTER POSITIONING option
restriction with PRTSP parameter
use of 85
WRITE FROM option 296
WRITE statement
additional information*
causing errors with 257
in VSAM 193-195
65
files
87
87
x, in CURRENCY SIGN and PICTURE clause*
XREF option
for compilation 42
for linkage editing 47
Z, in CURRENCY SIGN and PICTURE clauses*
'zero*
ZERO (ZEROES, ZEROS) figurative constant*
zero filling*
ZERO sign test rules*
zero suppression*
zero value*
zoned decimal item*
ZWB compiler option 40
W (warning severity level 238,35
wait state time limit 21
wait status*
wait subroutine 478
warning
used as a severity level
(W)
35,238
using status key with VSAM
183
WHEN-COMPILED special. register*
WHEN option of SEARCH ALL*
W1TB
D~aUGGING MOP~
additional information*
controlled by DEBUG option 48
effect on SYMDMP 41
effect on TEST 47
general 248-249
with footing*
with NO REWIND*
with phrase of SEND*
word 62,*
workfile under VSAM 179
Working-Storage section
additional information*
finding in dump 285
location and length, determining 237
REA~ INTO option
296
590
*Consult VS COBOL for OS/VS (GC26-3857)
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 : 2013:03:06 14:57:58-08:00 Modify Date : 2013:03:06 17:14:27-08:00 Metadata Date : 2013:03:06 17:14:27-08:00 Producer : Adobe Acrobat 9.52 Paper Capture Plug-in Format : application/pdf Document ID : uuid:eac9ae65-85be-4519-97e9-264d18f2cd47 Instance ID : uuid:5b1802b6-67dd-4d12-aa80-989da4d77bf4 Page Layout : SinglePage Page Mode : UseNone Page Count : 630EXIF Metadata provided by EXIF.tools