IBM OS/390 & VM COBOL software Programming Guide

COBOL for OS/390 & VM
Programming Guide
Version 2 Release 2
SC26-9049-05
COBOL for OS/390 & VM
Programming Guide
Version 2 Release 2
SC26-9049-05
Note!
Before using this information and the product it supports, be sure to read the general information under “Notices” on
page 609.
Sixth Edition (September 2000)
This edition applies to Version 2 Release 2 of IBM COBOL for OS/390 & VM (program number 5648-A25) and to all
subsequent releases and modifications until otherwise indicated in new editions. Make sure you are using the
correct edition for the level of the product.
Order publications by phone or fax. IBM Software Manufacturing Solutions takes publication orders between 8:30
a.m. and 7:00 p.m. Eastern Standard Time (EST). The phone number is (800) 879-2755. The fax number is (800)
445-9269.
You can also order publications through your IBM representative or the IBM branch office serving your locality.
Publications are not stocked at the address below.
A form for readers’ comments appears at the back of this publication. If the form has been removed, address your
comments to:
IBM Corporation, Department HHX/H3
P.O Box 49023
San Jose, CA 95161-9023
USA
or fax it to this U.S. number: 800-426-7773
or use the form on the Web at:
http://www.ibm.com/software/ad/rcf/
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 1991, 2000. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
About this book . . . . . . . . . . . xi
How this book will help you. . . .
Abbreviated terms . . . . . . .
How to read syntax diagrams . . .
How examples are shown . . . .
Comparison of commonly-used terms
Summary of changes . . . . . .
Major changes . . . . . . .
.
.
.
.
.
.
.
.
. xi
. xi
. . . . . xii
. . . . . xiii
. . . . . xiii
. . . . . xiv
. . . . . xiv
.
.
.
.
.
.
.
.
.
. 31
. 32
. 32
Chapter 3. Working with numbers and
arithmetic . . . . . . . . . . . . . 33
27
Chapter 4. Handling tables . . . . . . 53
.
.
. 5
. 6
.
.
.
.
.
.
.
.
.
.
.
. 6
. 6
. 6
. 7
. 7
. 8
. 9
. 9
. 10
. 12
. 13
.
.
.
. 15
. 16
. 17
.
.
. 17
. 21
Chapter 2. Using data . . . . . . . . 23
© Copyright IBM Corp. 1991, 2000
.
.
.
23
23
23
24
24
24
25
25
26
Chapter 1. Structuring your program . . 5
Using variables, structures, literals, and constants .
Variables . . . . . . . . . . . . . .
Data structure: data items and group items . . .
Literals . . . . . . . . . . . . . . .
Constants . . . . . . . . . . . . . .
Figurative constants . . . . . . . . . .
Assigning values to data items . . . . . . . .
Examples: initializing variables . . . . . . .
Initializing a structure (INITIALIZE) . . . . .
Assigning values to variables or structures
(MOVE) . . . . . . . . . . . . . .
Assigning arithmetic results (MOVE or
COMPUTE) . . . . . . . . . . . . .
Assigning input from a screen or file (ACCEPT)
Displaying values on a screen or in a file (DISPLAY)
Displaying data on the system logical output
device . . . . . . . . . . . . . . .
Using WITH NO ADVANCING . . . . . .
Using intrinsic functions (built-in functions) . . .
.
.
.
Defining numeric data. . . . . . . . . . .
Displaying numeric data . . . . . . . . . .
Controlling how numeric data is stored . . . . .
Formats for numeric data. . . . . . . . . .
External decimal (DISPLAY) items . . . . . .
External floating-point (DISPLAY) items . . . .
Binary (COMP) items . . . . . . . . . .
Native binary (COMP-5) items . . . . . . .
Packed-decimal (COMP-3) items . . . . . .
Floating-point (COMP-1 and COMP-2) items . .
Examples: numeric data and internal representation
Data format conversions . . . . . . . . . .
Conversions and precision . . . . . . . .
Sign representation and processing . . . . . .
NUMPROC(PFD) . . . . . . . . . . .
NUMPROC(NOPFD) . . . . . . . . . .
NUMPROC(MIG) . . . . . . . . . . .
Checking for incompatible data (numeric class test)
Performing arithmetic . . . . . . . . . . .
COMPUTE and other arithmetic statements . .
Arithmetic expressions . . . . . . . . .
Numeric intrinsic functions . . . . . . . .
Nesting functions and arithmetic expressions . .
ALL subscripting and special registers . . . .
Math and date Language Environment services
Examples: numeric intrinsic functions . . . . .
General number handling . . . . . . . .
Date and time . . . . . . . . . . . .
Finance . . . . . . . . . . . . . . .
Mathematics . . . . . . . . . . . . .
Statistics . . . . . . . . . . . . . .
Fixed-point versus floating-point arithmetic . . .
Floating-point evaluations . . . . . . . .
Fixed-point evaluations . . . . . . . . .
Arithmetic comparisons (relation conditions) . .
Examples: fixed-point and floating-point
evaluations . . . . . . . . . . . . .
Using currency signs . . . . . . . . . . .
Example: multiple currency signs . . . . . .
Part 1. Coding your program . . . . 1
Identifying a program . . . . . . . . .
Identifying a program as recursive . . . .
Marking a program as callable by containing
programs . . . . . . . . . . . .
Setting a program to an initial state. . . .
Changing the header of a source listing . .
Describing the computing environment . . .
Example: FILE-CONTROL entries . . . .
Specifying the collating sequence . . . .
Defining symbolic characters . . . . . .
Defining a user-defined class . . . . . .
Defining files to the operating system . .
Describing the data . . . . . . . . . .
Using data in input and output operations .
Comparison of WORKING-STORAGE and
LOCAL-STORAGE . . . . . . . . .
Using data from another program . . . .
Processing the data . . . . . . . . . .
How logic is divided in the PROCEDURE
DIVISION . . . . . . . . . . . .
Declaratives . . . . . . . . . . .
Types of intrinsic functions . .
Nesting functions . . . . .
Using tables (arrays) and pointers .
27
28
29
29
30
31
Defining a table (OCCURS) .
Nesting tables . . . . .
Subscripting . . . . .
Indexing . . . . . .
Referring to an item in a table
Subscripting . . . . .
Indexing . . . . . .
Putting values into a table .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
33
34
35
36
36
36
37
37
38
38
38
39
40
41
41
41
41
42
43
43
43
44
45
45
45
47
47
47
47
48
48
49
49
49
50
50
51
52
53
54
54
55
55
56
57
58
iii
Loading a table dynamically. . . . . . .
Initializing a table (INITIALIZE) . . . . .
Assigning values when you define a table
(VALUE) . . . . . . . . . . . . .
Example: PERFORM and subscripting . . .
Example: PERFORM and indexing. . . . .
Creating variable-length tables (DEPENDING ON)
Loading a variable-length table . . . . . .
Assigning values to a variable-length table . .
Searching a table . . . . . . . . . . .
Doing a serial search (SEARCH) . . . . .
Doing a binary search (SEARCH ALL) . . .
Processing table items using intrinsic functions .
Example: intrinsic functions . . . . . . .
. 58
. 58
. 58
. 60
. 61
62
. 63
. 64
. 65
. 65
. 66
. 67
. 68
Chapter 5. Selecting and repeating
program actions . . . . . . . . . . 69
Selecting program actions . . . . . .
Coding a choice of actions . . . . .
Coding conditional expressions . . . .
Repeating program actions . . . . . .
Choosing inline or out-of-line PERFORM
Coding a loop . . . . . . . . .
Coding a loop through a table . . . .
Executing multiple paragraphs or sections
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
69
69
73
76
76
77
78
79
Chapter 6. Handling strings . . . . . . 81
Joining data items (STRING) . . . . . . . .
Example: STRING statement. . . . . . . .
Splitting data items (UNSTRING) . . . . . . .
Example: UNSTRING statement . . . . . .
Manipulating null-terminated strings . . . . . .
Example: null-terminated strings . . . . . .
Referring to substrings of data items . . . . . .
Reference modifiers. . . . . . . . . . .
Example: arithmetic expressions as reference
modifiers . . . . . . . . . . . . . .
Example: intrinsic functions as reference
modifiers . . . . . . . . . . . . . .
Tallying and replacing data items (INSPECT) . . .
Examples: INSPECT statement . . . . . . .
Converting double-byte character set (DBCS) data
DBCS notation . . . . . . . . . . . .
Nonnumeric to DBCS data conversion
(IGZCA2D) . . . . . . . . . . . . .
DBCS to nonnumeric data conversion
(IGZCD2A) . . . . . . . . . . . . .
Converting data items (intrinsic functions) . . . .
Converting to uppercase or lowercase
(UPPER-CASE, LOWER-CASE) . . . . . . .
Converting to reverse order (REVERSE) . . . .
Converting to numbers (NUMVAL, NUMVAL-C)
Evaluating data items (intrinsic functions) . . . .
Evaluating single characters for collating
sequence . . . . . . . . . . . . . .
Finding the largest or smallest data item . . .
Finding the length of data items . . . . . .
Finding the date of compilation . . . . . .
81
81
83
83
85
86
86
87
88
88
89
89
90
90
90
92
94
94
95
95
96
96
97
98
99
Chapter 7. Processing files . . . . . 101
iv
Programming Guide
File organization and input-output devices
Choosing file organization and access mode
Format for coding input and output . .
Allocating files . . . . . . . . . .
Checking for input or output errors . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
101
103
103
105
106
Chapter 8. Processing QSAM files . . 107
Defining QSAM files and records in COBOL . . .
Establishing record formats. . . . . . . .
Setting block sizes . . . . . . . . . . .
Coding input and output statements for QSAM
files . . . . . . . . . . . . . . . .
Opening QSAM files . . . . . . . . . .
Dynamically creating QSAM files with CBLQDA
Adding records to QSAM files. . . . . . .
Updating QSAM files. . . . . . . . . .
Writing QSAM files to a printer or spooled data
set . . . . . . . . . . . . . . . .
Closing QSAM files . . . . . . . . . .
Handling errors in QSAM files . . . . . . .
Working with QSAM files under OS/390 . . . .
Defining and allocating QSAM files . . . . .
Retrieving QSAM files . . . . . . . . .
Ensuring file attributes match your program
Using striped extended-format QSAM data sets
Accessing HFS files using QSAM . . . . . . .
Restrictions and usage . . . . . . . . .
Identifying QSAM files to CMS . . . . . . .
Using FILEDEF. . . . . . . . . . . .
Using LABELDEF . . . . . . . . . . .
Labels for QSAM files . . . . . . . . . .
Using trailer and header labels . . . . . .
Format of standard labels . . . . . . . .
Processing QSAM ASCII files on tape . . . . .
Requesting the ASCII alphabet . . . . . .
Defining the record formats . . . . . . .
Defining the ddname . . . . . . . . . .
Processing ASCII file labels . . . . . . . . .
107
108
115
117
117
118
119
119
119
120
120
121
121
123
124
126
127
127
128
128
129
129
130
131
132
132
132
132
133
Chapter 9. Processing VSAM files . . 135
VSAM files . . . . . . . . . . . . . .
Defining VSAM file organization and records . .
Specifying sequential organization for VSAM
files . . . . . . . . . . . . . . .
Specifying indexed organization for VSAM files
Specifying relative organization for VSAM files
Specifying access modes for VSAM files . . .
Defining record lengths for VSAM files. . . .
Coding input and output statements for VSAM
files . . . . . . . . . . . . . . . .
File position indicator . . . . . . . . .
Opening a file (ESDS, KSDS, or RRDS) . . . .
Reading records from a VSAM file . . . . .
Updating records in a VSAM file . . . . . .
Adding records to a VSAM file . . . . . .
Replacing records in a VSAM file. . . . . .
Deleting records from a VSAM file . . . . .
Closing VSAM files . . . . . . . . . .
Handling errors in VSAM files . . . . . . .
Protecting VSAM files with a password . . . .
136
137
138
138
139
141
141
143
144
145
147
148
149
149
150
150
151
151
Example: password protection for a VSAM
indexed file . . . . . . . . . . . .
Working with VSAM data sets under OS/390 and
OS/390 UNIX . . . . . . . . . . . .
Defining VSAM files under OS/390 . . . .
Creating alternate indexes . . . . . . .
Allocating VSAM files . . . . . . . .
Sharing VSAM files through RLS . . . . .
Defining VSAM data sets under CMS . . . .
Improving VSAM performance . . . . . .
. 152
.
.
.
.
.
.
.
152
153
154
156
157
158
159
Chapter 10. Processing line-sequential
files . . . . . . . . . . . . . . . 163
Defining line-sequential files and records in
COBOL . . . . . . . . . . . . . . .
Allowable control characters . . . . . . .
Describing the structure of a line-sequential file
Defining and allocating line-sequential files . . .
Coding input-output statements for line-sequential
files . . . . . . . . . . . . . . . .
Opening line-sequential files . . . . . . .
Reading records from line-sequential files . . .
Adding records to line-sequential files . . . .
Closing line-sequential files. . . . . . . .
Handling errors in line-sequential files . . . . .
Chapter 11. Sorting and merging files
163
164
164
165
165
166
166
167
167
168
169
Sort and merge process . . . . . . . . . .
Describing the sort or merge file . . . . . . .
Describing the input to sorting or merging . . .
Example: describing sort and input files for
SORT . . . . . . . . . . . . . . .
Coding the input procedure . . . . . . . .
Describing the output from sorting or merging . .
Coding the output procedure . . . . . . . .
Coding considerations when using DFSORT on
OS/390 . . . . . . . . . . . . . .
Example: coding the output procedure when
using DFSORT . . . . . . . . . . . .
Restrictions on input and output procedures . . .
Defining sort and merge data sets under OS/390
Defining sort and merge files under CMS . . . .
Sorting variable-length records . . . . . . .
Requesting the sort or merge . . . . . . . .
Setting sort or merge criteria . . . . . . .
Example: sorting with input and output
procedures . . . . . . . . . . . . .
Choosing alternate collating sequences . . . .
Sorting on windowed date fields . . . . . .
Preserving the original sequence of records with
equal keys . . . . . . . . . . . . .
Determining whether the sort or merge was
successful . . . . . . . . . . . . . .
Stopping a sort or merge operation prematurely
Improving sort performance with FASTSRT . . .
FASTSRT requirements for JCL (OS/390 only)
FASTSRT requirements for sort input and
output files . . . . . . . . . . . . .
Checking for sort errors with NOFASTSRT . . .
Controlling sort behavior . . . . . . . . .
170
170
171
171
172
173
173
174
174
175
175
176
176
177
177
178
179
179
180
180
181
181
181
181
183
184
Sort special registers . . . . . . . . .
Changing DFSORT defaults with control
statements . . . . . . . . . . . .
Allocating storage for sort or merge operations
Using checkpoint/restart with DFSORT under
OS/390 . . . . . . . . . . . . . .
Sorting under CICS . . . . . . . . . .
CICS SORT application restrictions . . . .
. 184
. 185
186
. 186
. 187
. 187
Chapter 12. Handling errors . . . . . 189
Requesting dumps . . . . . . . . . .
Creating a formatted dump. . . . . . .
Creating a system dump . . . . . . .
Handling errors in joining and splitting strings .
Handling errors in arithmetic operations . . .
Example: checking for division by zero . . .
Handling errors in input and output operations
Using the end-of-file condition (AT END) . .
Coding ERROR declaratives . . . . . .
Using file status keys . . . . . . . . .
Example: file status key . . . . . . . .
Using VSAM return codes (VSAM files only)
Example: checking VSAM status codes . . .
Coding INVALID KEY phrases . . . . .
Example: FILE STATUS and INVALID KEY .
Handling errors when calling programs . . .
Writing routines for handling errors . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
189
189
190
190
191
191
191
193
194
194
195
196
196
198
198
199
199
Part 2. Compiling and debugging
your program . . . . . . . . . . 201
Chapter 13. Compiling under OS/390
203
Compiling with JCL . . . . . . . . . . .
Using a cataloged procedure . . . . . . .
Writing JCL to compile programs. . . . . .
Compiling under TSO . . . . . . . . . .
Example: ALLOCATE and CALL for compiling
under TSO . . . . . . . . . . . . .
Example: CLIST for compiling under TSO . . .
Starting the compiler from an assembler program
Defining compiler input and output . . . . . .
Data sets used by the compiler under OS/390
Defining the source code data set (SYSIN) . . .
Specifying source libraries (SYSLIB) . . . . .
Defining the output data set (SYSPRINT) . . .
Directing compiler messages to your terminal
(SYSTERM) . . . . . . . . . . . . .
Creating object code (SYSLIN or SYSPUNCH)
Creating an associated data file (SYSADATA)
Defining the output IDL data set (SYSIDL) . .
Defining the debug data set (SYSDEBUG) . . .
Specifying compiler options under OS/390 . . .
Specifying compiler options with the PROCESS
(CBL) statement . . . . . . . . . . .
Example: specifying compiler options using JCL
Example: specifying compiler options under
TSO . . . . . . . . . . . . . . .
Compiler options and compiler output under
OS/390 . . . . . . . . . . . . . .
Compiling multiple programs (batch compilation)
Contents
203
204
213
215
215
216
216
218
218
220
220
221
221
221
222
222
222
223
223
224
224
224
226
v
Example: batch compilation . . . . .
Specifying compiler options in a batch
compilation . . . . . . . . . . .
Example: precedence of options in a batch
compilation . . . . . . . . . . .
Example: LANGUAGE option in a batch
compilation . . . . . . . . . . .
Correcting errors in your source program . .
Generating a list of compiler error messages
Messages and listings for compiler-detected
errors . . . . . . . . . . . . .
Format of compiler error messages . . .
Severity codes for compiler error messages
.
. 226
.
. 227
.
. 228
.
.
.
. 229
. 230
. 230
.
.
.
. 231
. 231
. 232
Chapter 14. Compiling under OS/390
UNIX . . . . . . . . . . . . . . . 235
Setting environment variables under OS/390 UNIX
Specifying compiler options under OS/390 UNIX
Compiling and linking with the cob2 command
Defining input and output . . . . . . . .
Creating a DLL . . . . . . . . . . . .
Example: using cob2 to compile under OS/390
UNIX . . . . . . . . . . . . . . .
cob2 . . . . . . . . . . . . . . .
cob2 input and output files . . . . . . . .
Compiling using scripts . . . . . . . . . .
235
236
237
237
238
238
239
240
241
Chapter 15. Compiling under CMS
243
Accessing the compiler (CP LINK and ACCESS)
Specifying a source program to compile . . .
COBOL2 . . . . . . . . . . . . .
Using compiler-directing statements . . . . .
Specifying compiler options under CMS . . .
Using parentheses in COBOL2 . . . . .
Abbreviating compiler options . . . . .
Using logical line-editing characters . . . .
Additional compiler options under CMS . .
Differences in compiler options under CMS .
Precedence of compiler options under CMS .
Files used by the compiler under CMS . . .
Naming generated files under CMS . . . . .
Overriding FILEDEF . . . . . . . . .
Using system-generated names . . . . .
Correcting errors . . . . . . . . . . .
Error messages from COBOL2 . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
243
244
244
245
246
246
246
247
247
248
248
248
251
251
251
252
252
Chapter 16. Compiler options . . . . 257
Option settings for COBOL 85 Standard
conformance. . . . . . . . . .
Conflicting compiler options . . . .
ADATA . . . . . . . . . . .
ANALYZE . . . . . . . . . .
ADV . . . . . . . . . . . .
ARITH . . . . . . . . . . .
AWO . . . . . . . . . . . .
BUFSIZE . . . . . . . . . . .
CMPR2 . . . . . . . . . . .
COMPILE . . . . . . . . . .
CURRENCY . . . . . . . . . .
DATA . . . . . . . . . . . .
vi
Programming Guide
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
259
259
261
261
262
262
263
263
264
265
265
266
External data . . . . .
QSAM input/output buffers
DATEPROC . . . . . . .
DBCS . . . . . . . . .
DECK . . . . . . . . .
DIAGTRUNC . . . . . .
DISK/PRINT . . . . . .
DLL . . . . . . . . .
DUMP . . . . . . . .
DYNAM . . . . . . . .
EXIT . . . . . . . . .
EXPORTALL . . . . . .
FASTSRT . . . . . . . .
FLAG . . . . . . . . .
FLAGMIG . . . . . . .
FLAGSTD . . . . . . .
IDLGEN . . . . . . . .
INTDATE . . . . . . .
LANGUAGE . . . . . .
LIB . . . . . . . . . .
LINECOUNT . . . . . .
LIST . . . . . . . . .
MAP . . . . . . . . .
NAME . . . . . . . .
NUMBER . . . . . . .
NUMPROC . . . . . . .
OBJECT . . . . . . . .
OFFSET . . . . . . . .
OPTIMIZE . . . . . . .
Unused data items: . . .
OUTDD . . . . . . . .
PGMNAME . . . . . . .
PGMNAME(COMPAT) . .
PGMNAME(LONGUPPER).
PGMNAME(LONGMIXED)
PGMNAME usage notes. .
QUOTE/APOST . . . . .
RENT . . . . . . . . .
RMODE . . . . . . . .
SEQUENCE . . . . . . .
SIZE . . . . . . . . .
SOURCE . . . . . . . .
SPACE . . . . . . . .
SQL . . . . . . . . .
SSRANGE . . . . . . .
TERMINAL . . . . . . .
TEST . . . . . . . . .
TRUNC . . . . . . . .
TRUNC example 1 . . .
TRUNC example 2 . . .
TYPECHK . . . . . . .
VBREF . . . . . . . .
WORD . . . . . . . .
XREF . . . . . . . . .
YEARWINDOW . . . . .
ZWB . . . . . . . . .
Compiler-directing statements .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
267
267
267
269
269
269
270
270
271
272
272
272
273
274
275
275
277
278
279
280
280
281
281
282
283
283
284
285
285
286
286
287
287
288
288
288
289
289
290
291
291
292
293
293
294
295
295
297
298
299
300
301
301
302
303
304
304
Chapter 17. Debugging . . . . . . . 309
Debugging with source language .
Tracing program logic . . .
.
.
.
.
.
.
.
.
.
.
. 310
. 310
Finding and handling input-output errors .
Validating data . . . . . . . . . .
Finding uninitialized data . . . . . .
Generating information about procedures .
Debugging using compiler options . . . .
Finding coding errors . . . . . . .
Finding line sequence problems . . . .
Checking for valid ranges . . . . . .
Selecting the level of error to be diagnosed
Finding program entity definitions and
references . . . . . . . . . . .
Listing data items . . . . . . . . .
Getting listings . . . . . . . . . . .
Example: short listing . . . . . . .
Example: SOURCE and NUMBER output .
Example: embedded map summary . . .
Terms used in MAP output. . . . . .
Symbols used in LIST and MAP output .
Example: nested program map . . . .
Reading LIST output . . . . . . . .
Example: XREF output - data-name
cross-references. . . . . . . . . .
Example: XREF output - program-name
cross-references. . . . . . . . . .
Example: embedded cross-reference . . .
Example: OFFSET compiler output . . .
Example: VBREF compiler output . . .
Preparing to use the debugger. . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
311
311
311
312
313
314
315
315
316
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
317
318
319
320
323
325
326
326
328
328
.
. 340
.
.
.
.
.
.
.
.
.
.
DB2 coprocessor .
.
.
.
.
.
.
.
.
.
. 358
Chapter 20. Running COBOL
programs under IMS . . . . . . . . 359
Compiling and linking COBOL programs for
running under IMS . . . . . . . . .
.
. 359
Chapter 21. Running COBOL
programs under OS/390 UNIX . . . . 361
Running in OS/390 UNIX environments . . .
Setting and accessing environment variables . .
Setting environment variables that affect
execution . . . . . . . . . . . . .
Resetting environment variables . . . . .
Accessing environment variables . . . . .
Example: accessing environment variables . .
Calling UNIX/POSIX APIs . . . . . . . .
fork, exec, and spawn . . . . . . . .
Samples . . . . . . . . . . . . .
Accessing main program parameters . . . .
Example: accessing main program parameters
. 361
. 362
.
.
.
.
.
.
.
.
362
363
363
363
364
364
365
365
366
341
341
342
343
343
Chapter 22. Running COBOL
programs under CMS . . . . . . . . 369
Part 3. Targeting COBOL programs
for certain environments . . . . . 345
Chapter 23. Accessing COBOL
programs interactively with ISPF . . . 371
Chapter 18. Developing COBOL
programs for CICS . . . . . . . . . 347
Part 4. Developing object-oriented
programs . . . . . . . . . . . . 373
Coding COBOL programs to run under CICS .
Coding file input and output . . . . . .
Retrieving the system date and time. . . .
Displaying the contents of data items . . .
Calling to or from COBOL programs . . .
Coding a COBOL program to run above the
16-MB line . . . . . . . . . . . .
Determining the success of ECI calls. . . .
Preparing COBOL programs to run under CICS
Using the CICS translator . . . . . . .
Compiling your CICS program . . . . .
CICS reserved-word table . . . . . . .
Handling errors by using CICS HANDLE . . .
Example: handling errors by using CICS
HANDLE . . . . . . . . . . . .
.
.
.
.
.
347
348
348
348
348
. 349
. 349
350
. 350
. 350
. 351
. 352
. 352
Chapter 19. Programming for a DB2
environment . . . . . . . . . . . . 355
Coding SQL statements . . . . . . . .
Using SQL INCLUDE . . . . . . .
Using binary items . . . . . . . .
Determining the success of SQL statements
Compiling with the SQL option . . . . .
Compiling in batch . . . . . . . .
Separating DB2 suboptions . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
355
355
355
356
356
357
357
Run-time restrictions under CMS .
Handling QSAM files under CMS
Run-time message IGZ0002S . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 369
. 369
. 370
Chapter 24. Writing object-oriented
programs . . . . . . . . . . . . . 375
Example: mail-order catalog . . . . . . .
Subclasses . . . . . . . . . . . .
Defining a class . . . . . . . . . . .
CLASS-ID paragraph for defining a class . .
REPOSITORY paragraph for defining a class
WORKING-STORAGE SECTION for defining a
class . . . . . . . . . . . . . .
Example: defining a class . . . . . . .
Defining a class method . . . . . . . . .
METHOD-ID paragraph for defining a class
method . . . . . . . . . . . . .
Overriding a method . . . . . . . . .
INPUT-OUTPUT SECTION for defining a
method . . . . . . . . . . . . .
DATA DIVISION for defining a method . .
PROCEDURE DIVISION for defining a method
Coding special methods . . . . . . . .
Example: defining a method . . . . . .
Defining a client program . . . . . . . .
REPOSITORY paragraph for defining a client
WORKING-STORAGE SECTION for defining a
client . . . . . . . . . . . . . .
Contents
.
.
.
.
375
377
378
378
379
. 379
. 380
. 381
. 381
. 381
. 382
. 382
383
. 383
. 384
. 389
389
. 390
vii
Creating and freeing instances of classes . . .
Manipulating object references . . . . . .
Invoking methods . . . . . . . . . . .
Example: defining a client . . . . . . . .
Defining a subclass . . . . . . . . . . .
CLASS-ID paragraph for defining a subclass
REPOSITORY paragraph for defining a subclass
WORKING-STORAGE SECTION for defining a
subclass . . . . . . . . . . . . . .
Defining a subclass method . . . . . . .
Example: defining a subclass (with methods)
Defining a metaclass . . . . . . . . . . .
CLASS-ID paragraph for defining a metaclass
REPOSITORY paragraph for defining a
metaclass . . . . . . . . . . . . . .
WORKING-STORAGE SECTION for defining a
metaclass . . . . . . . . . . . . . .
Defining a metaclass method . . . . . . .
Changing the definition of a class or subclass
Changing a client program . . . . . . . .
Example: defining a metaclass (with methods)
390
391
391
392
393
394
394
395
395
396
405
406
.
.
.
.
415
415
416
417
.
.
.
.
.
.
.
.
.
.
418
420
420
421
422
Chapter 26. Using SOM IDL-based
class libraries . . . . . . . . . . . 425
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
425
426
427
427
428
429
432
435
440
442
443
443
443
443
445
446
447
448
450
Chapter 27. Wrapping or converting
procedure-oriented programs . . . . 451
OO view of COBOL programs. . . .
Wrapping procedure-oriented programs
viii
Programming Guide
.
.
.
.
.
.
.
.
.
.
.
453
454
454
454
455
Part 5. Working with more
complex applications . . . . . . . 457
Chapter 28. Using subprograms . . . 459
406
406
407
407
408
.
.
.
.
SOM objects . . . . . . . . . . . . .
SOM IDL . . . . . . . . . . . . . .
Mapping IDL to COBOL . . . . . . . .
Using IDL operations. . . . . . . . .
Expressing IDL attributes . . . . . . .
Common IDL types . . . . . . . . .
Complex IDL types . . . . . . . . .
Passing COBOL arguments and return values
Example: using a SOM IDL-based class library
Handling errors and exceptions . . . . . .
Passing environment variables. . . . . .
Checking the exception type field . . . .
Handling exceptions . . . . . . . . .
Example: checking SOM exceptions . . . .
Creating and initializing object instances . . .
Looking at the IDL file . . . . . . . . .
Avoiding memory leaks . . . . . . . . .
Example: COBOL variable-length string class
Source code for helper routines . . . . . .
. 452
452
. 453
406
Chapter 25. System Object Model. . . 415
SOM Interface Repository . . . . . . .
Accessing the SOM Interface Repository .
Populating the SOM Interface Repository .
SOM environment variables . . . . . .
Example: sample JCL for an object-oriented
application . . . . . . . . . . .
SOM services . . . . . . . . . . .
SOM methods and functions . . . . .
Class initialization . . . . . . . . .
Changing SOM class interfaces . . . .
Coordinating procedural code with interface
actions . . . . . . . . . . . . .
Integrating procedural code into OO systems
Changing procedural code . . . . . . .
Converting from procedure-oriented to OO
programs . . . . . . . . . . . . . .
Identifying objects . . . . . . . . . .
Analyzing data flow and usage . . . . .
Reallocating code to objects . . . . . .
Writing the object-oriented code . . . . .
. 451
. 452
Main programs, subprograms, and calls . . .
Ending and reentering main programs or
subprograms . . . . . . . . . . . .
Transferring control to another program . . .
Making static calls. . . . . . . . . .
Making dynamic calls . . . . . . . .
Performance considerations of static and
dynamic calls . . . . . . . . . . .
Making both static and dynamic calls . . .
Example: static and dynamic CALL statements
NODYNAM restriction (CMS only) . . . .
Calling nested COBOL programs . . . . .
Making recursive calls . . . . . . . . .
Calling to and from object-oriented programs .
Using procedure pointers . . . . . . . .
Calling a C function-pointer . . . . . .
Calling to alternate entry points . . . . .
Making programs reentrant . . . . . . .
. 459
.
.
.
.
460
461
462
462
. 464
. 465
465
. 467
. 468
. 472
. 472
. 472
. 473
. 473
. 474
Chapter 29. Sharing data . . . . . . 475
Passing data . . . . . . . . . . . . .
Describing arguments in the calling program
Describing parameters in the called program
Coding the LINKAGE SECTION . . . . . .
Coding the PROCEDURE DIVISION for passing
arguments . . . . . . . . . . . . .
Grouping data to be passed . . . . . .
Handling null-terminated strings . . . . .
Using pointers to process a chained list . .
Passing return code information . . . . . .
Understanding the RETURN-CODE special
register . . . . . . . . . . . . .
Using PROCEDURE DIVISION RETURNING .
.. . . . . . . . . . . . . . . .
Specifying CALL . . . RETURNING . . . . .
Sharing data by using the EXTERNAL clause. .
Sharing files between programs (external files) .
Example: using external files . . . . . .
. 475
477
477
. 477
.
.
.
.
.
478
478
478
479
482
.
.
.
.
.
.
.
482
482
483
483
483
484
Chapter 30. Creating a DLL or a DLL
application . . . . . . . . . . . . 489
Dynamic link libraries (DLLs) . . .
Compiling programs to create DLLs .
Linking DLLs . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
. 489
. 490
. 491
Prelinking certain DLLs . . . . . . . .
Example: sample JCL for a procedural DLL
application . . . . . . . . . . .
Using CALL identifier with DLLs . . . .
Search order for DLLs in HFS . . . . .
Using DLL linkage and dynamic calls together
Using procedure-pointers with DLLs . .
Calling DLLs from non-DLLs . . . . .
Example: calling DLLs from non-DLLs . .
Using COBOL DLLs with C/C++ programs .
Using DLLs in OO COBOL applications . .
.
. 492
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
492
493
494
494
495
496
496
498
498
Chapter 31. Interrupts and
checkpoint/restart . . . . . . . . . 501
Setting checkpoints . . . . . . . . . . .
Designing checkpoints . . . . . . . . .
Testing for a successful checkpoint . . . . .
DD statements for defining checkpoint data sets
Messages generated during checkpoint . . . .
Restarting programs . . . . . . . . . . .
Requesting automatic restart . . . . . . .
Requesting deferred restart . . . . . . . .
Formats for requesting deferred restart . . . .
Resubmitting jobs for restart . . . . . . .
Example: restarting a job at a specific
checkpoint step. . . . . . . . . . . .
Example: requesting a step restart . . . . .
Example: resubmitting a job for a step restart
Example: resubmitting a job for a checkpoint
restart . . . . . . . . . . . . . . .
501
502
502
503
504
504
505
505
506
507
507
507
507
508
Chapter 32. Processing two-digit-year
dates . . . . . . . . . . . . . . . 509
Millennium language extensions (MLE) . . . .
Principles and objectives of these extensions . .
Resolving date-related logic problems . . . . .
Using a century window . . . . . . . .
Using internal bridging . . . . . . . . .
Moving to full field expansion. . . . . . .
Using year-first, year-only, and year-last date fields
Compatible dates . . . . . . . . . . .
Example: comparing year-first date fields . . .
Using other date formats . . . . . . . .
Example: isolating the year . . . . . . . .
Manipulating literals as dates . . . . . . . .
Assumed century window . . . . . . . .
Treatment of nondates . . . . . . . . .
Setting triggers and limits . . . . . . . . .
Example: using limits . . . . . . . . .
Using sign conditions . . . . . . . . .
Sorting and merging by date . . . . . . . .
Example: sorting by date and time . . . . .
Performing arithmetic on date fields. . . . . .
Allowing for overflow from windowed date
fields . . . . . . . . . . . . . . .
Specifying the order of evaluation . . . . .
Controlling date processing explicitly . . . . .
Using DATEVAL . . . . . . . . . . .
Using UNDATE . . . . . . . . . . .
510
510
511
512
513
514
516
517
518
518
518
519
520
521
521
522
523
523
524
525
525
526
527
527
527
Analyzing and avoiding date-related diagnostic
messages . . . . . . . . . . . . . . .
Avoiding problems in processing dates . . . . .
Avoiding problems with packed-decimal fields
Moving from expanded to windowed date fields
528
530
530
530
Part 6. Improving performance and
productivity . . . . . . . . . . . 533
Chapter 33. Tuning your program . . . 535
Using an optimal programming style . . .
Using structured programming . . . .
Factoring expressions. . . . . . . .
Using symbolic constants . . . . . .
Grouping constant computations . . . .
Grouping duplicate computations . . .
Choosing efficient data types . . . . . .
Computational data items . . . . . .
Consistent data types. . . . . . . .
Arithmetic expressions . . . . . . .
Exponentiations . . . . . . . . .
Handling tables efficiently . . . . . . .
Optimization of table references . . . .
Optimizing your code . . . . . . . .
Optimization . . . . . . . . . .
Example: PERFORM procedure integration
Choosing compiler features to enhance
performance . . . . . . . . . . . .
Performance-related compiler options . .
Evaluating performance . . . . . . .
Running efficiently with CICS, IMS, or VSAM
CICS . . . . . . . . . . . . .
IMS . . . . . . . . . . . . .
VSAM . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
535
536
536
536
536
537
537
537
538
538
538
539
540
542
542
544
.
.
.
.
.
.
.
.
.
.
.
.
.
.
544
545
548
548
548
549
549
Chapter 34. Simplifying coding . . . . 551
Eliminating repetitive coding . . . . . . .
Example: using the COPY statement. . . .
Using Language Environment callable services .
Sample list of Language Environment callable
services . . . . . . . . . . . . .
Calling Language Environment services . .
Example: Language Environment callable
services . . . . . . . . . . . . .
. 551
. 552
. 553
. 554
. 555
. 556
Part 7. Appendixes . . . . . . . . 557
Appendix A. Intermediate results and
arithmetic precision . . . . . . . . 559
Terminology used for intermediate results .
Example: calculation of intermediate results
Fixed-point data and intermediate results .
Addition, subtraction, multiplication, and
division . . . . . . . . . . .
Exponentiation . . . . . . . . .
Example: exponentiation in fixed-point
arithmetic . . . . . . . . . .
Truncated intermediate results. . . .
Binary data and intermediate results .
.
.
.
.
.
.
. 560
. 561
. 561
.
.
.
.
. 561
. 562
.
.
.
.
.
.
. 563
. 564
. 564
Contents
ix
Intrinsic functions evaluated in fixed-point
arithmetic . . . . . . . . . . . . . .
Integer functions . . . . . . . . . . .
Mixed functions . . . . . . . . . . .
Floating-point data and intermediate results . . .
Exponentiations evaluated in floating-point
arithmetic . . . . . . . . . . . . .
Intrinsic functions evaluated in floating-point
arithmetic . . . . . . . . . . . . .
ON SIZE ERROR and intermediate results. . . .
Arithmetic expressions in nonarithmetic statements
565
565
565
566
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
580
581
582
582
583
583
567
567
567
568
Appendix D. Sample programs . . . . 587
. 571
IGYTCARA: batch application . . . .
Input data for IGYTCARA . . . .
Report produced by IGYTCARA . .
Running IGYTCARA . . . . . .
IGYTCARB: interactive program . . .
Running IGYTCARB . . . . . .
IGYTSALE: nested program application
Input data for IGYTSALE . . . .
Reports produced by IGYTSALE . .
Running IGYTSALE . . . . . .
Language elements and concepts that are
illustrated . . . . . . . . . .
. 571
Notices . . . . . . . . . . . . . . 609
Appendix B. Complex OCCURS
DEPENDING ON . . . . . . . . . . 569
Example: complex ODO . . . . . . . . .
How length is calculated . . . . . . .
Setting values of ODO objects . . . . . .
Effects of change in ODO object value . . . .
Preventing index errors when changing ODO
object value . . . . . . . . . . . .
Preventing overlay when adding elements to a
variable table . . . . . . . . . . .
Processing of PRTEXIT . . .
Parameter list for PRTEXIT .
Processing of ADEXIT . . .
Parameter list for ADEXIT .
Error handling for exit modules
Example: SYSIN user exit . .
.
.
.
.
569
570
570
570
Trademarks .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 604
.
.
.
587
588
589
590
592
592
595
597
598
602
. 610
Appendix C. EXIT compiler option . . 575
Using the user-exit work area . . .
Calling from exit modules . . . .
Processing of INEXIT. . . . . .
Parameter list for INEXIT . . .
Processing of LIBEXIT . . . . .
Processing of LIBEXIT with nested
statements . . . . . . . .
Parameter list for LIBEXIT . . .
x
Programming Guide
. .
. .
. .
. .
. .
COPY
. .
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
576
576
577
577
578
.
.
.
.
. 578
. 579
Glossary . . . . . . . . . . . . . 611
List of resources . . . . . . . . . . 633
COBOL for OS/390 & VM .
Related publications . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 633
. 633
Index . . . . . . . . . . . . . . . 635
About this book
Welcome to IBM COBOL for OS/390 & VM, IBM’s latest host COBOL compiler!
This version of IBM COBOL for OS/390 & VM is fully source and object
compatible with COBOL for MVS & VM Version 1, with the exception of programs
containing object-oriented language constructs, which must be recompiled to
enable support for OS/390 SOMobjects.
IBM COBOL for OS/390 & VM is referred to as “COBOL for OS/390 & VM”
throughout this publication.
How this book will help you
This book will help you write and compile COBOL for OS/390 & VM programs. It
will also help you define object-oriented classes and methods, invoke methods, and
refer to objects in your programs. A companion volume, IBM Language Environment
Programming Guide, provides instructions on link-editing and running your
programs.
This book assumes experience in developing application programs and some
knowledge of COBOL. It focuses on using COBOL for OS/390 & VM to meet your
programming objectives and not on the definition of the COBOL language. For
complete information on COBOL syntax, refer to IBM COBOL Language Reference.
For information on migrating OS/VS COBOL and VS COBOL II programs to
COBOL for OS/390 & VM, see IBM COBOL for OS/390 & VM Compiler and
Run-Time Migration Guide.
IBM Language Environment for OS/390 & VM provides the run-time environment
and run-time services required to run your COBOL for OS/390 & VM programs.
You will find information on link-editing and running programs in the IBM
Language Environment Programming Guide and IBM Language Environment
Programming Reference.
For a comparison of commonly used COBOL for OS/390 & VM and IBM
Language Environment for OS/390 & VM terms, see “Comparison of
commonly-used terms” on page xiii.
Abbreviated terms
Certain terms are used in a shortened form in this book. Abbreviations for the
product names used most frequently in this book are listed alphabetically in the
following table. Abbreviations for other terms, if not commonly understood, are
shown in italics the first time they appear, and are listed in the glossary in the back
of this book.
Term used
Long form
CICS
CICS/ESA
COBOL for OS/390 & VM
IBM COBOL for OS/390 & VM
CMS
CMS component of VM/ESA
© Copyright IBM Corp. 1991, 2000
xi
Term used
Long form
IMS
IMS/VS or IMS/ESA
Language Environment
IBM Language Environment for OS/390 & VM
MVS
MVS/ESA
SOM
System Object Model
VM
VM/ESA
In addition to these abbreviated terms, the term “COBOL 85 Standard” is used in
this book to refer to the combination of the following standards:
v ISO 1989:1985, Programming languages - COBOL
v ISO 1989/Amendment 1, Programming Languages - COBOL - Amendment 1:
Intrinsic function module
v X3.23-1985, American National Standard for Information Systems - Programming
Language - COBOL
v X3.23a-1989, American National Standard for Information Systems Programming Language - Intrinsic Function Module for COBOL
The two ISO standards are identical to the American National standards.
How to read syntax diagrams
The following rules apply to syntax diagrams:
v Read the syntax diagrams from left to right, from top to bottom, following the
path of the line.
The
symbol indicates the beginning of a statement.
The
line.
symbol indicates that the statement syntax is continued on the next
The
symbol indicates that a statement is continued from the previous line.
The
symbol indicates the end of a statement.
Diagrams of syntactical units other than complete statements start with the
symbol and end with the
symbol.
v Required items appear on the horizontal line (the main path).
v Optional items appear below the main path.
If an optional item appears above the main path, that item has no effect on the
execution of the statement and is used only for readability.
If you can choose from two or more items, they appear vertically, in a stack.
If you must choose one of the items, one item of the stack appears on the main
path.
xii
Programming Guide
If choosing one of the items is optional, the entire stack appears below the main
path.
If one of the items is the default, it appears above the main path and the
remaining choices are shown below.
An arrow returning to the left, above the main line, indicates an item that can be
repeated.
If the repeat arrow contains a comma, you must separate repeated items with a
comma.
A repeat arrow above a stack indicates that you can repeat the items in the
stack.
v Keywords appear in uppercase (for example, FROM). They must be spelled exactly
as shown. Variables appear in all lowercase letters (for example, column-name).
They represent user-supplied names or values.
v If punctuation marks, parentheses, arithmetic operators, or other such symbols
are shown, you must enter them as part of the syntax.
How examples are shown
This book shows numerous examples of sample COBOL statements, program
fragments, and small programs to help illustrate the concepts being discussed. The
examples of program code are written in lowercase, uppercase, or mixed case to
demonstrate that you can write your programs in any of these ways.
Where it helps to more clearly separate the examples from the explanatory text,
they are presented in a different font style.
COBOL keywords and compiler options appearing in text are generally shown in
SMALL UPPER CASE. Other terms such as program variable names or method names
are sometimes shown in a different font style for clarity.
Comparison of commonly-used terms
In order to better understand the various terms used throughout the IBM
Language Environment for OS/390 & VM and IBM COBOL for OS/390 & VM
publications and what terms are meant to be equivalent, see the following table.
Language Environment term
COBOL for OS/390 & VM equivalent
Aggregate
Group item
Array
A table created using the OCCURS clause
Array element
Table element
About this book
xiii
Language Environment term
COBOL for OS/390 & VM equivalent
Enclave
Run unit
External data
WORKING-STORAGE data defined with EXTERNAL clause
Local data
Any non-EXTERNAL data item
Pass parameters directly, by value
BY VALUE
Pass parameters indirectly, by
reference
BY REFERENCE
Pass parameters indirectly, by value BY CONTENT
Routine
Program
Scalar
Elementary item
Summary of changes
This section lists the key changes that have been made to IBM COBOL for OS/390
& VM. Those documented in this publication have an associated page reference for
your convenience.
The latest technical changes are marked by a change bar in the left margin. Many
corrections have been made without comment.
Chapters have been extensively reorganized, and artwork improved.
Cross-references (except for those to examples) have been grouped together at the
ends of topics so as not to interrupt the flow of the text.
Major changes
v Enhanced support for decimal data, raising the maximum number of decimal
digits from 18 to 31 and providing an extended-precision mode for arithmetic
calculations (“ARITH” on page 262)
v Enhanced production debugging using overlay hooks rather than compiled-in
hooks, with symbolic debugging information optionally in a separate file
(“TEST” on page 295)
v Support for compiling, linking, and executing in the OS/390 UNIX System
Services environment, with COBOL files able to reside in the HFS (hierarchical
file system) (“Chapter 14. Compiling under OS/390 UNIX” on page 235)
v Toleration of fork(), exec(), and spawn(); and the ability to call UNIX/POSIX
functions (“Calling UNIX/POSIX APIs” on page 364)
v Enhanced input-output function, permitting dynamic file allocation by means of
an environment variable named in SELECT . . . ASSIGN, and the accessing of
sequentially organized HFS files including by means of ACCEPT and DISPLAY
(“Allocating files” on page 105)
v Support for line-sequential file organization for accessing HFS files that contain
text data, with records delimited by the new-line character (“Chapter 10.
Processing line-sequential files” on page 163)
v COMP-5 data type, new to host COBOL, allowing values of magnitude up to the
capacity of the native binary representation (“Formats for numeric data” on
page 36)
v Significant performance improvement in processing binary data with the
TRUNC(BIN) compiler option (“TRUNC” on page 297)
xiv
Programming Guide
v Support for linking of COBOL applications using the OS/390 DFSMS binder
alone, with the prelinker required only in exceptional cases under CICS
(“Compiling programs to create DLLs” on page 490)
v Diagnosis of moves (implicit or explicit) that result in numeric truncation
enabled via compiler option (“DIAGTRUNC” on page 269)
v System-determined block size for the listing data set available by specifying
BLKSIZE=0 (“Logical record length and block size” on page 219)
v Limit on block size of QSAM tape files raised to 2 GB (“Setting block sizes” on
page 115)
v Support under CICS for DISPLAY to the system logical output device and ACCEPT
for obtaining date and time (“Coding COBOL programs to run under CICS” on
page 347)
v Support for the DB2 coprocessor enabled through a new compiler option,
eliminating the need for a separate precompile step and permitting SQL
statements in nested programs and copy books (“SQL” on page 293)
v Support for the millennium language extensions now included in the base
COBOL product (“Millennium language extensions (MLE)” on page 510)
Changes in the fifth edition
v New compiler option ANALYZE to check the syntax of embedded SQL and CICS
statements (“ANALYZE” on page 261).
v Extension of the ACCEPT statement to cover the recommendation in the Working
Draft for Proposed Revision of ISO 1989:1985 Programming Language COBOL.
v New intrinsic date functions to convert to dates with a four-digit year.
v The millennium language extensions, enabling compiler-assisted date processing
for dates containing two-digit and four-digit years (“Millennium language
extensions (MLE)” on page 510).
Requires IBM VisualAge millennium language extensions for OS/390 & VM
(program number 5648-MLE) to be installed with your compiler.
Changes in the fourth edition
v Extensions to currency support for displaying financial data, including:
– Support for currency signs of more than one character
– Support for more than one type of currency sign in the same program
– Support for the euro currency sign, as defined by the Economic and Monetary
Union (EMU)
Changes from COBOL for MVS & VM
v Support has been added for dynamic link libraries (DLLs). A DLL is a load
module containing programs and data that can be accessed from other load
modules. The DLL mechanism is the primary means used for packaging SOM
class libraries. With this new support, object-oriented COBOL applications can
be packaged using separate DLL load modules for the client programs and class
definitions. Two new compiler options, DLL|NODLL and EXPORTALL|NOEXPORTALL,
are used to control the creation of DLLs. For details, see “Chapter 30. Creating a
DLL or a DLL application” on page 489.
v Due to changes in the SOMobjects product that is delivered with OS/390 Release
3, changes in the JCL for building object-oriented COBOL applications are
required:
– The SOMobjects kernel and the SOMobjects class libraries must be accessed
from the SOMobjects product DLLs, rather than being linked together with
the COBOL application load module as was required in the prior version.
About this book
xv
This requires changes to the JCL to specify appropriate COBOL compiler
options for DLL support; the prelink step must specify (at least) the DLL
definition side decks for the SOM kernel and class libraries, and the SOM
SGOSPLKD data set is no longer used in the SYSLIB concatenation of the
prelink step.
– The format of the SOM profile data set has changed, and the profile is now
specified via the SOMENV DD statement rather than the SOMPROF DD statement.
For further details, see the OS/390 SOMobjects Programmer’s Guide, and
“Chapter 25. System Object Model” on page 415.
v The INTDATE compiler option is no longer an installation option only—it can now
be specified as an option when invoking the compiler. See “INTDATE” on
page 278.
xvi
Programming Guide
Part 1. Coding your program
Chapter 1. Structuring your program . . . . . 5
Identifying a program . . . . . . . . . . . 5
Identifying a program as recursive . . . . . . 6
Marking a program as callable by containing
programs . . . . . . . . . . . . . . 6
Setting a program to an initial state. . . . . . 6
Changing the header of a source listing . . . . 6
Describing the computing environment . . . . . 7
Example: FILE-CONTROL entries . . . . . . 7
Specifying the collating sequence . . . . . . 8
Example: specifying the collating sequence . . 8
Defining symbolic characters . . . . . . . . 9
Defining a user-defined class . . . . . . . . 9
Defining files to the operating system . . . . 10
Varying the input or output file at run time . 11
Optimizing buffer and device space . . . . 12
Describing the data . . . . . . . . . . . . 12
Using data in input and output operations . . . 13
FILE SECTION entries. . . . . . . . . 14
Comparison of WORKING-STORAGE and
LOCAL-STORAGE . . . . . . . . . . . 15
Example: storage sections. . . . . . . . 15
Using data from another program . . . . . . 16
Sharing data in separately compiled programs 16
Sharing data in nested programs . . . . . 17
Processing the data . . . . . . . . . . . . 17
How logic is divided in the PROCEDURE
DIVISION . . . . . . . . . . . . . . 17
Imperative statements . . . . . . . . . 18
Conditional statements . . . . . . . . 19
Compiler-directing statements . . . . . . 20
Scope terminators . . . . . . . . . . 20
Declaratives . . . . . . . . . . . . . 21
Chapter 2. Using data . . . . . . . . . .
Using variables, structures, literals, and constants .
Variables . . . . . . . . . . . . . .
Data structure: data items and group items . . .
Literals . . . . . . . . . . . . . . .
Constants . . . . . . . . . . . . . .
Figurative constants . . . . . . . . . .
Assigning values to data items . . . . . . . .
Examples: initializing variables . . . . . . .
Initializing a structure (INITIALIZE) . . . . .
Assigning values to variables or structures
(MOVE) . . . . . . . . . . . . . .
Assigning arithmetic results (MOVE or
COMPUTE) . . . . . . . . . . . . .
Assigning input from a screen or file (ACCEPT)
Displaying values on a screen or in a file (DISPLAY)
Displaying data on the system logical output
device . . . . . . . . . . . . . . .
Using WITH NO ADVANCING . . . . . .
Using intrinsic functions (built-in functions) . . .
Types of intrinsic functions . . . . . . . .
Nesting functions . . . . . . . . . . .
© Copyright IBM Corp. 1991, 2000
23
23
23
23
24
24
24
25
25
26
27
27
28
29
29
30
31
31
32
Using tables (arrays) and pointers .
.
.
.
.
.
. 32
Chapter 3. Working with numbers and arithmetic
Defining numeric data. . . . . . . . . . .
Displaying numeric data . . . . . . . . . .
Controlling how numeric data is stored . . . . .
Formats for numeric data. . . . . . . . . .
External decimal (DISPLAY) items . . . . . .
External floating-point (DISPLAY) items . . . .
Binary (COMP) items . . . . . . . . . .
Native binary (COMP-5) items . . . . . . .
Packed-decimal (COMP-3) items . . . . . .
Floating-point (COMP-1 and COMP-2) items . .
Examples: numeric data and internal representation
Data format conversions . . . . . . . . . .
Conversions and precision . . . . . . . .
Conversions that preserve precision . . . .
Conversions that result in rounding . . . .
Sign representation and processing . . . . . .
NUMPROC(PFD) . . . . . . . . . . .
NUMPROC(NOPFD) . . . . . . . . . .
NUMPROC(MIG) . . . . . . . . . . .
Checking for incompatible data (numeric class test)
Performing arithmetic . . . . . . . . . . .
COMPUTE and other arithmetic statements . .
Arithmetic expressions . . . . . . . . .
Numeric intrinsic functions . . . . . . . .
Nesting functions and arithmetic expressions . .
ALL subscripting and special registers . . . .
Math and date Language Environment services
Math-oriented callable services . . . . . .
Date callable services . . . . . . . . .
Examples: numeric intrinsic functions . . . . .
General number handling . . . . . . . .
Date and time . . . . . . . . . . . .
Finance . . . . . . . . . . . . . . .
Mathematics . . . . . . . . . . . . .
Statistics . . . . . . . . . . . . . .
Fixed-point versus floating-point arithmetic . . .
Floating-point evaluations . . . . . . . .
Fixed-point evaluations . . . . . . . . .
Arithmetic comparisons (relation conditions) . .
Examples: fixed-point and floating-point
evaluations . . . . . . . . . . . . .
Using currency signs . . . . . . . . . . .
Example: multiple currency signs . . . . . .
Chapter 4. Handling tables.
Defining a table (OCCURS) .
Nesting tables . . . . .
Subscripting . . . . .
Indexing . . . . . .
Referring to an item in a table
Subscripting . . . . .
Indexing . . . . . .
Putting values into a table .
33
33
34
35
36
36
36
37
37
38
38
38
39
40
40
40
41
41
41
41
42
43
43
43
44
45
45
45
45
46
47
47
47
47
48
48
49
49
49
50
50
51
52
. . . . . . . . 53
. . . . . . . . 53
. . . . . . . . 54
. . . . . . . . 54
. . . . . . . . 55
. . . . . . . . 55
. . . . . . . . 56
. . . . . . . . 57
. . . . . . . . 58
1
Loading a table dynamically. . . . . . .
Initializing a table (INITIALIZE) . . . . .
Assigning values when you define a table
(VALUE) . . . . . . . . . . . . .
Initializing each table item individually . .
Initializing a table at the 01 level . . . .
Initializing all occurrences of a table element
Example: PERFORM and subscripting . . .
Example: PERFORM and indexing. . . . .
Creating variable-length tables (DEPENDING ON)
Loading a variable-length table . . . . . .
Assigning values to a variable-length table . .
Searching a table . . . . . . . . . . .
Doing a serial search (SEARCH) . . . . .
Example: serial search . . . . . . . .
Doing a binary search (SEARCH ALL) . . .
Example: binary search . . . . . . .
Processing table items using intrinsic functions .
Example: intrinsic functions . . . . . . .
. 58
. 58
. 58
. 59
. 59
59
. 60
. 61
62
. 63
. 64
. 65
. 65
. 66
. 66
. 67
. 67
. 68
Chapter 5. Selecting and repeating program
actions . . . . . . . . . . . . . . . 69
Selecting program actions . . . . . . . . . 69
Coding a choice of actions . . . . . . . . 69
Using nested IF statements . . . . . . . 70
Using the EVALUATE statement . . . . . 71
Coding conditional expressions . . . . . . . 73
Switches and flags . . . . . . . . . . 74
Defining switches and flags . . . . . . . 74
Example: switches . . . . . . . . . . 74
Example: flags . . . . . . . . . . . 75
Resetting switches and flags . . . . . . . 75
Example: set switch on . . . . . . . . 75
Example: set switch off . . . . . . . . 76
Repeating program actions . . . . . . . . . 76
Choosing inline or out-of-line PERFORM . . . 76
Example: inline PERFORM statement . . . . 77
Coding a loop . . . . . . . . . . . . 77
Coding a loop through a table . . . . . . . 78
Executing multiple paragraphs or sections . . . 79
Chapter 6. Handling strings . . . . . . . . 81
Joining data items (STRING) . . . . . . . . 81
Example: STRING statement. . . . . . . . 81
STRING program results . . . . . . . . 82
Splitting data items (UNSTRING) . . . . . . . 83
Example: UNSTRING statement . . . . . . 83
UNSTRING program results . . . . . . . 84
Manipulating null-terminated strings . . . . . . 85
Example: null-terminated strings . . . . . . 86
Referring to substrings of data items . . . . . . 86
Reference modifiers. . . . . . . . . . . 87
Example: arithmetic expressions as reference
modifiers . . . . . . . . . . . . . . 88
Example: intrinsic functions as reference
modifiers . . . . . . . . . . . . . . 88
Tallying and replacing data items (INSPECT) . . . 89
Examples: INSPECT statement . . . . . . . 89
Converting double-byte character set (DBCS) data
90
DBCS notation . . . . . . . . . . . . 90
2
Programming Guide
Nonnumeric to DBCS data conversion
(IGZCA2D) . . . . . . . . . . . . .
IGZCA2D syntax . . . . . . . . . .
IGZCA2D return codes . . . . . . . .
Example: IGZCA2D . . . . . . . . .
DBCS to nonnumeric data conversion
(IGZCD2A) . . . . . . . . . . . . .
IGZCD2A syntax . . . . . . . . . .
IGZCD2A return codes . . . . . . . .
Example: IGZCD2A . . . . . . . . .
Converting data items (intrinsic functions) . . . .
Converting to uppercase or lowercase
(UPPER-CASE, LOWER-CASE) . . . . . . .
Converting to reverse order (REVERSE) . . . .
Converting to numbers (NUMVAL, NUMVAL-C)
Evaluating data items (intrinsic functions) . . . .
Evaluating single characters for collating
sequence . . . . . . . . . . . . . .
Finding the largest or smallest data item . . .
MAX and MIN . . . . . . . . . . .
ORD-MAX and ORD-MIN . . . . . . .
Returning variable-length results with
alphanumeric functions . . . . . . . .
Finding the length of data items . . . . . .
Finding the date of compilation . . . . . .
Chapter 7. Processing files . . . . .
File organization and input-output devices
Choosing file organization and access mode
Format for coding input and output . .
Allocating files . . . . . . . . . .
Checking for input or output errors . . .
90
91
91
92
92
93
93
94
94
94
95
95
96
96
97
97
97
97
98
99
. . . 101
. . . 101
. . . 103
. . . 103
. . . 105
. . . 106
Chapter 8. Processing QSAM files . . . . . 107
Defining QSAM files and records in COBOL . . . 107
Establishing record formats. . . . . . . . 108
Logical records . . . . . . . . . . . 108
Requesting fixed-length format . . . . . 109
Requesting variable-length format . . . . 110
Requesting spanned format. . . . . . . 112
Requesting undefined format . . . . . . 114
Setting block sizes . . . . . . . . . . . 115
Letting OS/390 determine block size . . . 115
Setting block size explicitly . . . . . . . 115
Taking advantage of LBI. . . . . . . . 116
Block size and the DCB RECFM
subparameter . . . . . . . . . . . 116
Coding input and output statements for QSAM
files . . . . . . . . . . . . . . . . 117
Opening QSAM files . . . . . . . . . . 117
Dynamically creating QSAM files with CBLQDA 118
Adding records to QSAM files. . . . . . . 119
Updating QSAM files. . . . . . . . . . 119
Writing QSAM files to a printer or spooled data
set . . . . . . . . . . . . . . . . 119
Controlling the page size . . . . . . . 119
Controlling the vertical positioning of records 119
Closing QSAM files . . . . . . . . . . 120
Handling errors in QSAM files . . . . . . . 120
Working with QSAM files under OS/390 . . . . 121
Defining and allocating QSAM files . . . . . 121
Parameters for creating QSAM files . . .
Retrieving QSAM files . . . . . . . .
Parameters for retrieving QSAM files . .
Ensuring file attributes match your program
Processing existing files . . . . . . .
Defining variable-length (format-V) records
Defining format-U records . . . . . .
Defining fixed-length records . . . . .
Processing new files . . . . . . . .
Processing files dynamically created by
COBOL . . . . . . . . . . . .
Using striped extended-format QSAM data sets
Allocation of buffers for QSAM files. . .
Accessing HFS files using QSAM . . . . . .
Restrictions and usage . . . . . . . .
Identifying QSAM files to CMS . . . . . .
Using FILEDEF. . . . . . . . . . .
Using LABELDEF . . . . . . . . . .
Labels for QSAM files . . . . . . . . .
Using trailer and header labels . . . . .
Getting a user-label track . . . . . .
Handling user labels . . . . . . . .
Format of standard labels . . . . . . .
Standard user labels . . . . . . . .
Processing QSAM ASCII files on tape . . . .
Requesting the ASCII alphabet . . . . .
Defining the record formats . . . . . .
Defining the ddname . . . . . . . . .
Processing ASCII file labels . . . . . . . .
. 123
. 123
. 124
124
. 125
125
. 125
. 125
. 125
. 126
126
. 127
. 127
. 127
. 128
. 128
. 129
. 129
. 130
. 130
. 130
. 131
. 131
. 132
. 132
. 132
. 132
. 133
Chapter 9. Processing VSAM files. . . . . .
VSAM files . . . . . . . . . . . . . .
Defining VSAM file organization and records . .
Specifying sequential organization for VSAM
files . . . . . . . . . . . . . . .
Specifying indexed organization for VSAM files
Alternate keys . . . . . . . . . . .
Alternate index . . . . . . . . . . .
Specifying relative organization for VSAM files
Fixed-length and variable-length RRDS . . .
Simulating variable-length RRDS . . . . .
Specifying access modes for VSAM files . . .
Example: using dynamic access with VSAM
files . . . . . . . . . . . . . .
Defining record lengths for VSAM files. . . .
Defining fixed-length records . . . . . .
Defining variable-length records . . . . .
Coding input and output statements for VSAM
files . . . . . . . . . . . . . . . .
File position indicator . . . . . . . . .
Opening a file (ESDS, KSDS, or RRDS) . . . .
Opening an empty file . . . . . . . .
Statements to load records into a VSAM file
Opening a loaded file (a file with records)
Reading records from a VSAM file . . . . .
Updating records in a VSAM file . . . . . .
Adding records to a VSAM file . . . . . .
Adding records sequentially . . . . . .
Adding records randomly or dynamically
Replacing records in a VSAM file. . . . . .
Deleting records from a VSAM file . . . . .
135
136
137
138
138
139
139
139
140
140
141
141
141
142
142
143
144
145
145
147
147
147
148
149
149
149
149
150
Closing VSAM files . . . . . . . . . .
Handling errors in VSAM files . . . . . . .
Protecting VSAM files with a password . . . .
Example: password protection for a VSAM
indexed file . . . . . . . . . . . . .
Working with VSAM data sets under OS/390 and
OS/390 UNIX . . . . . . . . . . . . .
Defining VSAM files under OS/390 . . . . .
Creating alternate indexes . . . . . . . .
Example: entries for alternate indexes . . .
Allocating VSAM files . . . . . . . . .
Sharing VSAM files through RLS . . . . . .
Preventing update problems with VSAM files
in RLS mode . . . . . . . . . . .
Restrictions when using RLS . . . . . .
Handling errors in VSAM files in RLS mode
Defining VSAM data sets under CMS . . . . .
Improving VSAM performance . . . . . . .
150
151
151
Chapter 10. Processing line-sequential files . .
Defining line-sequential files and records in
COBOL . . . . . . . . . . . . . . .
Allowable control characters . . . . . . .
Describing the structure of a line-sequential file
Defining and allocating line-sequential files . . .
Coding input-output statements for line-sequential
files . . . . . . . . . . . . . . . .
Opening line-sequential files . . . . . . .
Reading records from line-sequential files . . .
Adding records to line-sequential files . . . .
Closing line-sequential files. . . . . . . .
Handling errors in line-sequential files . . . . .
163
Chapter 11. Sorting and merging files . . . .
Sort and merge process . . . . . . . . . .
Describing the sort or merge file . . . . . . .
Describing the input to sorting or merging . . .
Example: describing sort and input files for
SORT . . . . . . . . . . . . . . .
Coding the input procedure . . . . . . . .
Describing the output from sorting or merging . .
Coding the output procedure . . . . . . . .
Coding considerations when using DFSORT on
OS/390 . . . . . . . . . . . . . .
Example: coding the output procedure when
using DFSORT . . . . . . . . . . . .
Restrictions on input and output procedures . . .
Defining sort and merge data sets under OS/390
Defining sort and merge files under CMS . . . .
Sorting variable-length records . . . . . . .
Requesting the sort or merge . . . . . . . .
Setting sort or merge criteria . . . . . . .
Example: sorting with input and output
procedures . . . . . . . . . . . . .
Choosing alternate collating sequences . . . .
Sorting on windowed date fields . . . . . .
Preserving the original sequence of records with
equal keys . . . . . . . . . . . . .
Determining whether the sort or merge was
successful . . . . . . . . . . . . . .
Stopping a sort or merge operation prematurely
169
170
170
171
Part 1. Coding your program
3
152
152
153
154
155
156
157
157
158
158
158
159
163
164
164
165
165
166
166
167
167
168
171
172
173
173
174
174
175
175
176
176
177
177
178
179
179
180
180
181
Improving sort performance with FASTSRT . . .
FASTSRT requirements for JCL (OS/390 only)
FASTSRT requirements for sort input and
output files . . . . . . . . . . . . .
QSAM requirements . . . . . . . . .
VSAM requirements . . . . . . . . .
Checking for sort errors with NOFASTSRT . . .
Controlling sort behavior . . . . . . . . .
Sort special registers . . . . . . . . . .
Changing DFSORT defaults with control
statements . . . . . . . . . . . . .
Default characteristics of the IGZSRTCD data
set . . . . . . . . . . . . . . .
Allocating storage for sort or merge operations
Using checkpoint/restart with DFSORT under
OS/390 . . . . . . . . . . . . . . .
Sorting under CICS . . . . . . . . . . .
CICS SORT application restrictions . . . . .
181
181
181
182
183
183
184
184
185
185
186
186
187
187
Chapter 12. Handling errors . . . . . . . . 189
Requesting dumps . . . . . . . . . . . 189
Creating a formatted dump. . . . . . . . 189
Creating a system dump . . . . . . . . 190
Handling errors in joining and splitting strings . . 190
Handling errors in arithmetic operations . . . . 191
Example: checking for division by zero . . . . 191
Handling errors in input and output operations
191
Using the end-of-file condition (AT END) . . . 193
Coding ERROR declaratives . . . . . . . 194
Using file status keys . . . . . . . . . . 194
Example: file status key . . . . . . . . . 195
Using VSAM return codes (VSAM files only)
196
Example: checking VSAM status codes . . . . 196
Coding INVALID KEY phrases . . . . . . 198
INVALID KEY and ERROR declaratives . . 198
NOT INVALID KEY . . . . . . . . . 198
Example: FILE STATUS and INVALID KEY . . 198
Handling errors when calling programs . . . . 199
Writing routines for handling errors . . . . . . 199
4
Programming Guide
Chapter 1. Structuring your program
A COBOL program consists of four divisions, each with a specific logical function:
v IDENTIFICATION DIVISION
v ENVIRONMENT DIVISION
v DATA DIVISION
v PROCEDURE DIVISION
Only the IDENTIFICATION DIVISION is required.
To define a COBOL class or method, you need to define some divisions differently
than you would for a program.
RELATED TASKS
“Identifying a program”
“Describing the computing environment” on page 7
“Describing the data” on page 12
“Processing the data” on page 17
“Defining a class” on page 378
“Defining a class method” on page 381
Identifying a program
Use the IDENTIFICATION DIVISION to name your program and, if you want, give
other identifying information.
You can use the optional AUTHOR, INSTALLATION, DATE-WRITTEN, and DATE-COMPILED
paragraphs for descriptive information about your program. The data you enter on
the DATE-COMPILED paragraph is replaced with the latest compilation date.
IDENTIFICATION DIVISION.
Program-ID. Helloprog.
Author. A. Programmer.
Installation. Computing Laboratories.
Date-Written. 08/18/1997.
Date-Compiled. 03/30/2000.
Use the PROGRAM-ID paragraph to name your program. The program name that you
assign is used in these ways:
v Other programs use the name to call your program.
v The name appears in the header on each page, except the first page, of the
program listing generated when the program is compiled.
v If you use the NAME compiler option, the name is placed on the NAME linkage
editor control statement to identify the object module created by the
compilation.
Tip: Do not use program names that start with prefixes used by IBM products. If
you try to use programs whose names start with any of the following, your CALL
statements might resolve to IBM library or compiler routines rather than to your
intended program:
AFB
IBM
© Copyright IBM Corp. 1991, 2000
AFH
IFY
CBC
IGY
CEE
IGZ
EDC
ILB
5
Tip: When the program name is case sensitive, avoid mismatches with the name
the compiler is looking for. Verify that the appropriate setting of the PGMNAME
compiler option is used.
RELATED TASKS
“Changing the header of a source listing”
“Identifying a program as recursive”
“Marking a program as callable by containing programs”
“Setting a program to an initial state”
RELATED REFERENCES
Compiler limits (IBM COBOL Language Reference)
Conventions for program names (IBM COBOL Language Reference)
Identifying a program as recursive
Code the RECURSIVE attribute on the PROGRAM-ID clause to specify that your
program can be recursively reentered while a previous invocation is still active.
You can code RECURSIVE only on the outermost program of a compilation unit.
Neither nested subprograms nor programs containing nested subprograms can be
recursive.
RELATED TASKS
“Making recursive calls” on page 472
Marking a program as callable by containing programs
Use the COMMON attribute on the PROGRAM-ID clause to specify that your program can
be called by the containing program or by any program in the containing program.
The COMMON program cannot be called by any program contained in itself.
Only contained programs can have the COMMON attribute.
RELATED CONCEPTS
“Nested programs” on page 469
Setting a program to an initial state
Use the INITIAL attribute to specify that whenever a program is called, it is placed
in its initial state. If the program contains programs, these are also placed in their
initial states.
A program is in its initial state when the following has occurred:
v Data items having VALUE clauses are set to the specified value.
v Changed GO TO statements and PERFORM statements are set to their initial states.
v Non-EXTERNAL files are closed.
Changing the header of a source listing
The header on the first page of your source statement listing contains the
identification of the compiler and the current release level, plus the date and time
of compilation and the page number. For example:
PP 5648-A25 IBM COBOL for OS/390 & VM 2.2.0
6
Programming Guide
Date 03/30/2000
Time 15:05:19
Page
1
You can customize the header on succeeding pages of the listing with the
compiler-directing TITLE statement.
RELATED REFERENCES
TITLE statement (IBM COBOL Language Reference)
Describing the computing environment
In the ENVIRONMENT DIVISION you describe the aspects of your program that
depend on the computing environment.
Use the CONFIGURATION SECTION to specify the following items:
v Computer for compiling your program (in the SOURCE-COMPUTER paragraph)
v Computer for running your program (in the OBJECT-COMPUTER paragraph)
v Special items such as the currency sign and symbolic characters (in the
SPECIAL-NAMES paragraph)
v User-defined classes (in the REPOSITORY paragraph)
Use the FILE-CONTROL and I-O-CONTROL paragraphs of the INPUT-OUTPUT section to
do the following:
|
|
|
v Identify and describe the characteristics of your program files.
v Associate your files with the external QSAM, VSAM, or HFS (hierarchical file
system) data sets where they physically reside.
The terms file, in COBOL terminology, and data set or HFS file, in operating
system terminology, have essentially the same meaning and are used
interchangeably in this documentation.
For Customer Information Control System (CICS) and online Information
Management System (IMS) message processing programs (MPP), code only the
ENVIRONMENT DIVISION header and, optionally, the CONFIGURATION SECTION. CICS
does not allow COBOL definition of files. IMS allows COBOL definition of files
only for batch programs.
v Provide information to control efficient transmission of the data records between
your program and the external medium.
“Example: FILE-CONTROL entries”
RELATED TASKS
“Specifying the collating sequence” on page 8
“Defining symbolic characters” on page 9
“Defining a user-defined class” on page 9
“Defining files to the operating system” on page 10
RELATED REFERENCES
Sections and paragraphs (IBM COBOL Language Reference)
Example: FILE-CONTROL entries
|
The following table shows FILE-CONTROL entries for a QSAM sequential file, a
VSAM indexed file, and a line-sequential file.
Chapter 1. Structuring your program
7
|
QSAM file
|
|
|
|
SELECT PRINTFILE
ASSIGN TO UPDPRINT2
ORGANIZATION IS SEQUENTIAL3
ACCESS IS SEQUENTIAL.4
VSAM file
1
Line-sequential file
SELECT COMMUTER-FILE
ASSIGN TO COMMUTER2
ORGANIZATION IS INDEXED3
ACCESS IS RANDOM4
RECORD KEY IS COMMUTER-KEY5
FILE STATUS IS5
COMMUTER-FILE-STATUS
COMMUTER-VSAM-STATUS.
1
SELECT PRINTFILE1
ASSIGN TO UPDPRINT2
ORGANIZATION IS LINE SEQUENTIAL3
ACCESS IS SEQUENTIAL.4
1. The SELECT clause chooses a file in the COBOL program to be associated with an external data set.
|
|
2. The ASSIGN clause associates the program’s name for the file with the external name for the actual data file. You
can define the external name with a DD statement or an environment variable.
3. The ORGANIZATION clause describes the file’s organization. For QSAM files, the ORGANIZATION clause is optional.
|
4. The ACCESS MODE clause defines the manner in which the records are made available for processing—sequential,
random, or dynamic. For QSAM and line-sequential files, the ACCESS MODE clause is optional. These files always
have sequential organization.
5. For VSAM files, you might have additional statements in the FILE-CONTROL paragraph depending on the type of
VSAM file you use.
RELATED TASKS
“Chapter 8. Processing QSAM files” on page 107
“Chapter 9. Processing VSAM files” on page 135
“Chapter 10. Processing line-sequential files” on page 163
“Describing the computing environment” on page 7
Specifying the collating sequence
Use the PROGRAM COLLATING SEQUENCE clause and the ALPHABET clause of the
SPECIAL-NAMES paragraph to establish the collating sequence used in the following
operations:
v Nonnumeric comparisons explicitly specified in relation conditions and
condition-name conditions HIGH-VALUE and LOW-VALUE settings
v SEARCH ALL
v SORT and MERGE unless overridden by a COLLATINGSEQUENCE phrase on the SORT or
MERGE statement
“Example: specifying the collating sequence”
The sequence that you use can be based on one of these alphabets:
v EBCDIC (use NATIVE if the native character set is EBCDIC), the default if you
omit the ALPHABET clause
v ASCII (use STANDARD-1)
v ISO 7-bit code, International Reference Version (use STANDARD-2)
v An alteration of the EBCDIC sequence that you define in the SPECIAL-NAMES
paragraph
RELATED TASKS
“Choosing alternate collating sequences” on page 179
Example: specifying the collating sequence
The following example shows the ENVIRONMENT DIVISION coding used to specify a
collating sequence where uppercase and lowercase letters are similarly handled for
comparisons and for sorting or merging. When you change the EBCDIC sequence
8
Programming Guide
in the SPECIAL-NAMES paragraph, the overall collating sequence is affected, not just
the collating sequence of the characters included in the SPECIAL-NAMES paragraph.
IDENTIFICATION DIVISION.
. . .
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
Source-Computer. IBM-390.
Object-Computer. IBM-390.
Program Collating Sequence Special-Sequence.
Special-Names.
Alphabet Special-Sequence Is
“A” Also “a”
“B” Also “b”
“C” Also “c”
“D” Also “d”
“E” Also “e”
“F” Also “f”
“G” Also “g”
“H” Also “h”
“I” Also “i”
“J” Also “j”
“K” Also “k”
“L” Also “l”
“M” Also “m”
“N” Also “n”
“O” Also “o”
“P” Also “p”
“Q” Also “q”
“R” Also “r”
“S” Also “s”
“T” Also “t”
“U” Also “u”
“V” Also “v”
“W” Also “w”
“X” Also “x”
“Y” Also “y”
“Z” Also “z”.
RELATED TASKS
“Specifying the collating sequence” on page 8
Defining symbolic characters
Use the SYMBOLIC CHARACTER clause to give symbolic names to any character of the
specified alphabet. Use ordinal position to identify the character. Position 1
corresponds to character X’00’. Example: To give a name to the backspace character
(X’16’ in the EBCDIC alphabet), code:
SYMBOLIC CHARACTERS BACKSPACE IS 23
Defining a user-defined class
Use the CLASS clause to give a name to a set of characters listed in the clause. For
example, name the set of digits by using this code:
CLASS DIGIT IS “0” THROUGH “9”
The class name can be referenced only in a class condition. This user-defined class
is not the same as an object-oriented class.
Chapter 1. Structuring your program
9
Defining files to the operating system
For all files that you process in your COBOL program, you need to define the files
to the operating system with an appropriate system data definition:
v DD statement for OS/390 JCL
v ALLOCATE command under TSO
v FILEDEF command for CMS
v Environment variable for OS/390 or OS/390 UNIX. The contents can define
either an MVS data set or a file in the HFS (hierarchical file system).
|
|
|
The following shows the relationship of a FILE-CONTROL entry to the system data
definition and to the FD entry in the FILE SECTION.
v JCL DD statement:
|
|
(1)
//OUTFILE
//
/*
. . .
DD
DSNAME=MY.OUT171,UNIT=SYSDA,SPACE=(TRK,(50,5)),
DCB=(BLKSIZE=400)
v FILEDEF command:
FILEDEF
. . .
(1)
OUTFILE DISK MY OUTPUT A1 (BLKSIZE 400)
v Environment variable (export command):
|
|
|
|
(1)
export OUTFILE=DSNAME(MY.OUT171),UNIT(SYSDA),SPACE(TRK,(50,5))
. . .
v COBOL code:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT CARPOOL
ASSIGN TO OUTFILE (1)
ORGANIZATION IS SEQUENTIAL.
. . .
DATA DIVISION.
FILE SECTION.
FD CARPOOL
(2)
LABEL RECORD STANDARD
BLOCK CONTAINS 0 CHARACTERS
RECORD CONTAINS 80 CHARACTERS
|
The ddname in the DD statement or the FILEDEF command, or the
environment variable name in the export command, corresponds to the
assignment-name in the ASSIGN clause:
v //OUTFILE DD DSNAME=OUT171 . . ., or
v FILEDEF OUTFILE DISK . . ., or
v export OUTFILE= . . .
|
|
This assignment-name points to the ddname OUTFILE in the DD statement or
the FILEDEF command, or the environment variable name OUTFILE in the
export command:
(1)
|
|
ASSIGN TO OUTFILE
(2)
When you specify a file in a COBOL FILE-CONTROL entry, you must
describe the file in an FD entry for file-name.
SELECT CARPOOL
. . .
FD CARPOOL
10
Programming Guide
RELATED TASKS
“Optimizing buffer and device space” on page 12
Varying the input or output file at run time
|
The file-name you code in your SELECT clause is used as a constant throughout your
COBOL program, but you can associate the name of the file on the DD statement,
export command, or FILEDEF command with a different file at run time.
|
|
Changing a file-name in your COBOL program requires changing the input
statements and output statements and recompiling the program. Alternatively, you
can change the dsname in the DD statement, the dsname or path-name in your export
command, or fn, ft, and fm parameters in the FILEDEF command.
|
|
|
|
Rules for using different files: The name you use in the assignment-name of the
ASSIGN clause must be the same as the ddname in the DD statement, the environment
variable in the export command, or the ddname in the FILEDEF command. You can
change the actual file by using the DSNAME in the DD statement, the DSNAME or path
name in the environment variable, or the fn, ft, and fm in the FILEDEF.
The file-name that you use with the SELECT clause (such as SELECT MASTER) must be
the same as in the FD file-name entry.
|
|
|
Two files should not use the same ddname or environment variable name in their
SELECT clauses; otherwise, results could be unpredictable. For example, if DISPLAY
is directed to SYSOUT, do not use SYSOUT as the ddname or environment variable
name on the SELECT clause for a file.
“Example: using different input files on OS/390”
“Example: using different input files on VM/CMS” on page 12
Example: using different input files on OS/390: Consider a COBOL program that
is used in exactly the same way for several different master files. It contains this
SELECT clause:
SELECT MASTER
ASSIGN TO DA-3330-S-MASTERA
|
|
|
Under OS/390, assume the three possible input files are MASTER1, MASTER2, and
MASTER3. Then you must code one of the following DD statements in the job step
that calls for program execution, or issue one of the following export commands
from the same shell from which you run the program, prior to running the
program:
//MASTERA
DD DSNAME=MY.MASTER1, . . .
export MASTERA=DSN(MY.MASTER1),...
//MASTERA
DD DSNAME=MY.MASTER2, . . .
export MASTERA=DSN(MY.MASTER2),...
//MASTERA
DD DSNAME=MY.MASTER3, . . .
export MASTERA=DSN(MY.MASTER3),...
|
Any reference in the program to MASTERA will therefore be a reference to the file
currently assigned to ddname or environment variable name MASTERA.
|
|
|
Notice that in this example, you cannot use the PATH(path) form of the export
command to reference a line-sequential file in the HFS, because you cannot specify
an organization field (S- or AS-) with a line-sequential file.
Chapter 1. Structuring your program
11
Example: using different input files on VM/CMS: Consider a COBOL program
that is used in exactly the same way for several different master files. It contains
this SELECT clause:
SELECT MASTER
ASSIGN TO DA-3330-S-MASTERA
Under VM, assume the three possible input files on your A-disk are MASTER1
INPUT, MASTER2 INPUT, and MASTER3 INPUT. Then you need to issue one of the
following FILEDEF commands before running the program:
FILEDEF
MASTERA DISK MASTER1 INPUT A1 . . .
FILEDEF
MASTERA DISK MASTER2 INPUT A1 . . .
FILEDEF
MASTERA DISK MASTER3 INPUT A1 . . .
Any reference in the program to MASTERA will therefore be a reference to the file
named in the FILEDEF command.
Optimizing buffer and device space
Use the APPLY WRITE-ONLY clause to make optimum use of buffer and device space
when creating a sequential file with blocked variable-length records. With APPLY
WRITE-ONLY specified, a buffer is truncated only when the next record does not fit
in the unused portion of the buffer. Without APPLY WRITE-ONLY specified, a buffer is
truncated when it does not have enough space for a maximum-size record.
The APPLY WRITE-ONLY clause has meaning only for sequential files that have
variable-length records and are blocked.
The AWO compiler option applies an implicit APPLY WRITE-ONLY clause to all eligible
files. The NOAWO compiler option has no effect on files that have the APPLY
WRITE-ONLY clause specified. The APPLY WRITE-ONLY clause takes precedence over
the NOAWO compiler option.
The APPLY-WRITE ONLY clause can cause input files to use a record area rather than
process the data in the buffer. This use might affect the processing of both input
files and output files.
RELATED REFERENCES
“AWO” on page 263
Describing the data
Define the characteristics of your data and group your data definitions into one of
the sections in the DATA DIVISION:
v Define data used in input-output operations (FILE SECTION).
v Define data developed for internal processing:
– To have storage be statically allocated and exist for the life of the run unit
(WORKING-STORAGE SECTION).
– To have storage be allocated each time a program is called and deallocated
when the program ends (LOCAL-STORAGE SECTION).
v Describe data from another program (LINKAGE SECTION).
The IBM COBOL for OS/390 & VM compiler limits the maximum size of DATA
DIVISION elements.
12
Programming Guide
RELATED CONCEPTS
“Comparison of WORKING-STORAGE and LOCAL-STORAGE” on page 15
RELATED TASKS
“Using data in input and output operations”
“Using data from another program” on page 16
RELATED REFERENCES
Compiler limits (IBM COBOL Language Reference)
Using data in input and output operations
Define the data you use in input and output operations in the FILE SECTION:
v Name the input and output files your program will use. Use the FD entry to give
names to your files that the input-output statements in the PROCEDURE DIVISION
can refer to.
Data items defined in the FILE SECTION are not available to PROCEDURE DIVISION
statements until the file has been successfully opened.
v In the record description following the FD entry, describe the fields of the records
in the file:
|
|
|
|
|
|
– You can code a level-01 description of the entire record, and then in the
WORKING-STORAGE SECTION code a working copy that describes the fields of the
record in more detail. Use the READ INTO statement to bring the records into
WORKING-STORAGE. Processing occurs on the copy of data in WORKING-STORAGE.
A WRITE FROM statement then writes processed data into the record area
defined in the FILE SECTION.
– The record-name established is the object of WRITE and REWRITE statements.
– For QSAM files only, you can set the record format in the RECORDING MODE
clause. If you omit the RECORDING MODE clause, the compiler determines the
record format based on the RECORD clause and on the level-01 record
descriptions.
– For QSAM files, you can set a blocking factor for the file in the BLOCK
CONTAINS clause. If you omit the BLOCK CONTAINS clause, the file defaults to
unblocked. However, you can override this with OS/390 data management
facilities (including a DD file job control statement) or with CMS file services
under VM.
– For line-sequential files, you can set a blocking factor for the file in the BLOCK
CONTAINS clause. When you code BLOCK CONTAINS 1 RECORDS, or BLOCK
CONTAINS n CHARACTERS, where n is the length of one logical record, WRITE
statements result in the record being transferred immediately to the file,
rather than being buffered. This technique is useful when you want each
record written immediately, such as to an error log.
Programs in the same run unit can share, or have access to, common files. The
method for doing this depends on whether the programs are part of a nested
(contained) structure or are separately compiled (including programs compiled as
part of a batch sequence).
You can use the EXTERNAL clause for separately compiled programs. A file that is
defined as EXTERNAL can be referenced by any program in the run unit that
describes the file.
Chapter 1. Structuring your program
13
You can use the GLOBAL clause for programs in a nested, or contained, structure. If
a program contains another program (directly or indirectly), both programs can
access a common file by referencing a GLOBAL file name.
RELATED CONCEPTS
“Nested programs” on page 469
RELATED TASKS
“Sharing files between programs (external files)” on page 483
RELATED REFERENCES
“FILE SECTION entries”
FILE SECTION entries
Clause
To define
FD
The file-name to be referred to Must match file-name in the SELECT
in PROCEDURE DIVISION
clause. file-name is associated with a
input-output statements (OPEN, ddname through the assignment-name.
CLOSE, READ, also START and
DELETE for VSAM)
BLOCK CONTAINS
Size of physical record
|
|
Notes
QSAM: If provided, must match
information on JCL or data set label. If
not provided, the system determines
the optimal block size for you.
Line sequential: can be specified to
control buffering for WRITE statements.
VSAM: Handled as comments.
14
Programming Guide
RECORD CONTAINS
n
Size of logical records (fixed
length)
If provided, must match information on
JCL or data set label. If n is equal to 0,
LRECL must be coded on JCL or data set
label.
RECORD IS
VARYING
Size of logical records
(variable length)
If provided, must match information on
JCL or data set label; compiler checks
match with record descriptions.
RECORD CONTAINS
n TO m
Size of logical records
(variable length)
If provided, must match information on
JCL or data set label; compiler checks
match with record descriptions.
LABEL RECORDS
See reference below.
VSAM: Handled as comments.
STANDARD
Labels exist
QSAM: Handled as comments.
OMITTED
Labels do not exist
QSAM: Handled as comments.
data-name
Labels defined by the user
QSAM: Allowed for (optional) tape or
disk.
VALUE OF
An item in the label records
associated with file
Comments only.
DATA RECORDS
Names of records associated
with file
Comments only.
LINAGE
Depth of logical page
QSAM only.
Clause
To define
Notes
CODE-SET
ASCII or EBCDIC files
QSAM only.
When an ASCII file is identified with
the CODE-SET clause, the corresponding
DD statement might need to have
DCB=(OPTCD=Q. . .) or
DCB=(RECFM=D. . .) coded if the file
was not created using VS COBOL II or
COBOL for OS/390 & VM.
RECORDING MODE
Physical record description
QSAM only.
RELATED CONCEPTS
“Labels for QSAM files” on page 129
Comparison of WORKING-STORAGE and LOCAL-STORAGE
WORKING-STORAGE is allocated at the start of the run unit. Any data items with VALUE
clauses are initialized to the appropriate value at that time. For the duration of the
run unit, WORKING-STORAGE items persist in their last-used state. Exceptions are:
v A program with INITIAL specified on the PROGRAM-ID
In this case, WORKING-STORAGE data items are reinitialized each time the program
is entered.
v A subprogram that is dynamically called and then canceled
In this case, WORKING-STORAGE data items are reinitialized on the first reentry into
the program following the CANCEL.
WORKING-STORAGE is deallocated at the termination of the run unit.
LOCAL-STORAGE is allocated each time a program is called, and is deallocated when
the program returns by means of an EXIT PROGRAM, GOBACK, or STOP RUN. Note
however that for nested programs, LOCAL-STORAGE is allocated upon entry to, and
deallocated upon exit from, the containing outermost program. Any LOCAL-STORAGE
data items with VALUE clauses in a nested program are initialized to the appropriate
value each time the nested program is called.
RELATED CONCEPTS
“Example: storage sections”
RELATED TASKS
“Ending and reentering main programs or subprograms” on page 460
RELATED REFERENCES
Working-Storage section (IBM COBOL Language Reference)
Local-Storage section (IBM COBOL Language Reference)
Example: storage sections
The following is an example of a recursive program that uses both
WORKING-STORAGE and LOCAL-STORAGE.
CBL nocmpr2,pgmn(lu)
*********************************
* Recursive Program - Factorials
*********************************
IDENTIFICATION DIVISION.
Program-Id. factorial recursive.
ENVIRONMENT DIVISION.
Chapter 1. Structuring your program
15
DATA DIVISION.
Working-Storage Section.
01 numb pic 9(4) value 5.
01 fact pic 9(8) value 0.
Local-Storage Section.
01 num pic 9(4).
PROCEDURE DIVISION.
move numb to num.
if numb = 0
move 1 to fact
else
subtract 1 from numb
call 'factorial'
multiply num by fact
end-if.
display num '! = ' fact.
goback.
End Program factorial.
The following tables show the changing values of the data items in LOCAL-STORAGE
(L-S) and WORKING-STORAGE (W-S) in the successive recursive calls of the program,
and in the ensuing gobacks. During the gobacks, fact progressively accumulates
the value of 5! (five factorial).
Recursive
CALLs:
Main 1 2 3
4
5
___________________________________
L-S num 5 4 3
2
1
0
___________________________________
W-S numb 5 4 3 2
1
0
fact 0 0 0 0
0
0
___________________________________
Recursive
GOBACKs:
5 4 3 2
1 Main
____________________________________
L-S num 0 1 2
3
4
5
____________________________________
W-S numb 0 0 0 0
0
0
fact 1 1 2 6
24 120
____________________________________
RELATED CONCEPTS
“Comparison of WORKING-STORAGE and LOCAL-STORAGE” on page 15
Using data from another program
How you share data depends on whether the programs are separately compiled or
are nested, as discussed in the topics referenced below.
RELATED TASKS
“Sharing data in separately compiled programs”
“Sharing data in nested programs” on page 17
Sharing data in separately compiled programs
Many applications consist of separately compiled programs that call and pass data
to one another. Use the LINKAGE SECTION in the called program to describe the data
passed from another program. In the calling program, use a CALL . . . USING or
INVOKE . . . USING statement to pass the data.
RELATED TASKS
“Passing data” on page 475
16
Programming Guide
Sharing data in nested programs
Some applications consist of nested programs—programs that are contained in
other programs. Level-01 LINKAGE SECTION data items can include the GLOBAL
attribute. This attribute allows any nested program that includes the declarations
to access these LINKAGE SECTION data items.
A nested program can also access data items in a sibling program (one at the same
nesting level in the same containing program) that is declared with the COMMON
attribute.
RELATED CONCEPTS
“Nested programs” on page 469
Processing the data
In the PROCEDURE DIVISION of a program, you code the executable statements that
process the data you have defined in the other divisions. The PROCEDURE DIVISION
contains one or two headers and the logic of your program.
The PROCEDURE DIVISION begins with the division header and a procedure-name
header. The division header for a program can simply be:
PROCEDURE DIVISION.
You can code your division header to receive parameters with the USING phrase or
to return a value with the RETURNING phrase.
To receive an argument that was passed by reference (the default) or by content,
code the division header for a program in either of these ways:
PROCEDURE DIVISION USING dataname
PROCEDURE DIVISION USING BY REFERENCE dataname
Be sure to define the dataname in the LINKAGE SECTION of the DATA DIVISION.
To receive a parameter that was passed by value, code the division header for a
program as follows:
PROCEDURE DIVISION USING BY VALUE dataname
To return a value as a result, code the division header as follows:
PROCEDURE DIVISION RETURNING dataname2
You can also combine USING and RETURNING in a PROCEDURE DIVISION header:
PROCEDURE DIVISION USING dataname RETURNING dataname2
Be sure to define dataname and dataname2 in the LINKAGE SECTION of the DATA
DIVISION.
RELATED CONCEPTS
“How logic is divided in the PROCEDURE DIVISION”
RELATED TASKS
“Eliminating repetitive coding” on page 551
How logic is divided in the PROCEDURE DIVISION
The PROCEDURE DIVISION of a program is divided into sections and paragraphs,
which contain sentences and statements:
Chapter 1. Structuring your program
17
Section
Logical subdivision of your processing logic.
A section has a section header and is optionally followed by one or more
paragraphs.
A section can be the subject of a PERFORM statement. One type of section is
for declaratives.
Paragraph
Subdivision of a section, procedure, or program.
A paragraph has a name followed by a period and zero or more sentences.
A paragraph can be the subject of a statement.
Sentence
Series of one or more COBOL statements ending with a period.
Many structured programs do not have separate sentences. Each paragraph
can contain one sentence.
Statement
Performs a defined step of COBOL processing, such as adding two
numbers.
A statement is a valid combination of words, beginning with a COBOL
verb. Statements are imperative (indicating unconditional action),
conditional, or compiler-directing. Using explicit scope terminators instead
of periods to show the logical end of a statement is preferred.
Phrase
A subdivision of a statement.
RELATED CONCEPTS
“Compiler-directing statements” on page 20
“Scope terminators” on page 20
“Imperative statements”
“Conditional statements” on page 19
“Declaratives” on page 21
RELATED REFERENCES
PROCEDURE DIVISION structure (IBM COBOL Language Reference)
Imperative statements
An imperative statement indicates an unconditional action to be taken (such as
ADD, MOVE, INVOKE, or CLOSE).
An imperative statement can be ended with an implicit or explicit scope
terminator.
A conditional statement that ends with an explicit scope terminator becomes an
imperative statement called a delimited scope statement. Only imperative statements
(or delimited scope statements) can be nested.
RELATED CONCEPTS
“Conditional statements” on page 19
“Scope terminators” on page 20
18
Programming Guide
Conditional statements
A conditional statement is either a simple conditional statement (IF, EVALUATE,
SEARCH) or a conditional statement made up of an imperative statement that
includes a conditional phrase or option.
You can end a conditional statement with an implicit or explicit scope terminator.
If you end a conditional statement explicitly, it becomes a delimited scope
statement (which is an imperative statement).
You can use a delimited scope statement in these ways:
v To delimit the range of operation for a COBOL conditional statement and to
explicitly show the levels of nesting
For example, use an END-IF statement instead of a period to end the scope of an
IF statement within a nested IF.
v To code a conditional statement where the COBOL syntax calls for an imperative
statement
For example, code a conditional statement as the object of an inline PERFORM:
PERFORM UNTIL TRANSACTION-EOF
PERFORM 200-EDIT-UPDATE-TRANSACTION
IF NO-ERRORS
PERFORM 300-UPDATE-COMMUTER-RECORD
ELSE
PERFORM 400-PRINT-TRANSACTION-ERRORS
END-IF
READ UPDATE-TRANSACTION-FILE INTO WS-TRANSACTION-RECORD
AT END
SET TRANSACTION-EOF TO TRUE
END-READ
END-PERFORM
An explicit scope terminator is required for the inline PERFORM statement, but it is
not valid for the out-of-line PERFORM statement.
For additional program control, you can use the NOT phrase with conditional
statements. For example, you can provide instructions to be performed when a
particular exception does not occur, such as NOT ON SIZE ERROR. The NOT phrase
cannot be used with the ON OVERFLOW phrase of the CALL statement, but it can be
used with the ON EXCEPTION phrase.
Do not nest conditional statements. Nested statements must be imperative
statements (or delimited scope statements) and must follow the rules for
imperative statements.
The following statements are examples of conditional statements if they are coded
without scope terminators:
v
v
v
v
v
Arithmetic statement with ON SIZE ERROR
Data-manipulation statements with ON OVERFLOW
CALL statements with ON OVERFLOW
I/O statements with INVALID KEY, AT END, or AT END-OF-PAGE
RETURN with AT END
RELATED CONCEPTS
“Imperative statements” on page 18
“Scope terminators” on page 20
Chapter 1. Structuring your program
19
RELATED TASKS
“Selecting program actions” on page 69
RELATED REFERENCES
Conditional statements (IBM COBOL Language Reference)
Compiler-directing statements
A compiler-directing statement is not part of the program logic. A
compiler-directing statement causes the compiler to take specific action about the
program structure, COPY processing, listing control, or control flow.
RELATED REFERENCES
“Compiler-directing statements” on page 304
Compiler-directing statements (IBM COBOL Language Reference)
Scope terminators
Scope terminators can be explicit or implicit. Explicit scope terminators end a verb
without ending a sentence. They consist of END followed by a hyphen and the
name of the verb being terminated, such as END-IF. An implicit scope terminator is
a period (.) that ends the scope of all previous statements not yet ended.
Each of the two periods in the following program fragment ends an IF statement,
making the code equivalent to the code after it that instead uses explicit scope
terminators:
IF ITEM = “A”
DISPLAY “THE VALUE OF ITEM IS ” ITEM
ADD 1 TO TOTAL
MOVE “C” TO ITEM
DISPLAY “THE VALUE OF ITEM IS NOW ” ITEM.
IF ITEM = “B”
ADD 2 TO TOTAL.
IF ITEM = “A”
DISPLAY “THE VALUE OF ITEM IS ” ITEM
ADD 1 TO TOTAL
MOVE “C” TO ITEM
DISPLAY “THE VALUE OF ITEM IS NOW ” ITEM
END-IF
IF ITEM = “B”
ADD 2 TO TOTAL
END-IF
If you use implicit terminators, the end of statements can be unclear. As a result,
you might end statements unintentionally, changing your program’s logic. Explicit
scope terminators make a program easier to understand and prevent unintentional
ending of statements. For example, in the program fragment below, changing the
location of the first period in the first implicit scope example changes the meaning
of the code:
IF ITEM = “A”
DISPLAY “VALUE OF ITEM IS ” ITEM
ADD 1 TO TOTAL.
MOVE “C” TO ITEM
DISPLAY “ VALUE OF ITEM IS NOW ” ITEM
IF ITEM = “B”
ADD 2 TO TOTAL.
The MOVE statement and the DISPLAY statement after it are performed regardless of
the value of ITEM, despite what the indentation indicates, because the first period
terminates the IF statement.
20
Programming Guide
For improved program clarity and to avoid unintentional ending of statements, use
explicit scope terminators, especially within paragraphs. Use implicit scope
terminators only at the end of a paragraph or the end of a program.
Be careful when coding an explicit scope terminator for an imperative statement
that is nested within a conditional statement. Ensure that the scope terminator is
paired with the statement for which it was intended. In the following example, the
scope terminator will be paired with the second READ statement, though the
programmer intended it to be paired with the first.
READ FILE1
AT END
MOVE A TO B
READ FILE2
END-READ
To ensure that the explicit scope terminator is paired with the intended statement,
the preceding example can be recoded in this way:
READ FILE1
AT END
MOVE A TO B
READ FILE2
END-READ
END-READ
RELATED CONCEPTS
“Conditional statements” on page 19
“Imperative statements” on page 18
Declaratives
Declaratives provide one or more special-purpose sections that are executed when
an exception condition occurs.
Start each declarative section with a USE statement that identifies the function of
the section; in the procedures, specify the actions to be taken when the condition
occurs.
RELATED TASKS
“Finding and handling input-output errors” on page 311
RELATED REFERENCES
Declaratives (IBM COBOL Language Reference)
Chapter 1. Structuring your program
21
22
Programming Guide
Chapter 2. Using data
This section is intended to help the non-COBOL programmer relate terms used in
other programming languages to COBOL terms for data. It introduces COBOL
fundamentals for:
v
v
v
v
Variables, structures, literals, and constants
Assigning and displaying values
Intrinsic (built-in) functions
Tables (arrays) and pointers
RELATED TASKS
Using variables, structures, literals, and constants
“Assigning values to data items” on page 25
“Using intrinsic functions (built-in functions)” on page 31
“Using tables (arrays) and pointers” on page 32
Using variables, structures, literals, and constants
Most high-level programming languages share the concept of data being
represented as variables, structures, literals, and constants. You place all data
definitions in the DATA DIVISION of your program. The data in a COBOL program
can be alphabetic, alphanumeric, or numeric.
Variables
A variable is a data item whose value can change during a program. The values
are restricted, however, to the data type that you define when you give the
variable a name and a length. For example, if a customer name is a variable in
your program, you could code:
Data Division.
. . .
01 Customer-Name
Pic X(20).
01 Original-Customer-Name
Pic X(20).
. . .
Procedure Division.
. . .
Move Customer-Name to Original-Customer-Name
. . .
Data structure: data items and group items
Related data items can be parts of a hierarchical data structure. A data item that
does not have any subordinate items is called an elementary data item. A data item
that is composed of subordinated data items is called a group item. A record can be
either an elementary data item or a group of data items.
In this example, Customer-Record is a group item composed of two group items
(Customer-Name and Part-Order), each of which contains elementary data items.
You can refer to the entire group item or to parts of the group item as shown in
the MOVE statements in the PROCEDURE DIVISION.
Data Division.
File Section.
FD Customer-File
Record Contains 45 Characters.
01 Customer-Record.
© Copyright IBM Corp. 1991, 2000
23
05
Customer-Name.
10 Last-Name
Pic x(17).
10 Filler
Pic x.
10 Initials
Pic xx.
05 Part-Order.
10 Part-Name
Pic x(15).
10 Part-Color
Pic x(10).
Working-Storage Section.
01 Orig-Customer-Name.
05 Surname
Pic x(17).
05 Initials
Pic x(3).
01 Inventory-Part-Name
Pic x(15).
. . .
Procedure Division.
. . .
Move Customer-Name to Orig-Customer-Name
Move Part-Name to Inventory-Part-Name
. . .
Literals
A literal is a character string whose value is given by the characters themselves.
When you know the value you want to use for a data item, use a literal
representation of the data value in the PROCEDURE DIVISION. You do not need to
define it or refer to a data-name. For example, you can prepare an error message
for an output file this way:
Move “Name is not valid” To Customer-Name
You can compare a data item to a certain number this way:
01 Part-number
Pic 9(5).
. . .
If Part-number = 03519 then display “Part number was found”
In these examples, “Name is not valid” is a nonnumeric literal, and 03519 is a
numeric literal.
Constants
A constant is a data item that has only one value. COBOL does not define a
construct specifically for constants. However, most COBOL programmers define a
data item with an initial VALUE (as opposed to initializing a variable using the
INITIALIZE statement). For example:
Data Division.
. . .
01 Report-Header
. . .
01 Interest
pic x(50)
value “Company Sales Report”.
pic 9v9999 value 1.0265.
Figurative constants
A variable is a data item whose value can change during a program. Certain
commonly used constants and literals are provided as reserved words called
figurative constants: ZERO, SPACE, HIGH-VALUE, LOW-VALUE, QUOTE, NULL, and ALL.
Because they represent fixed values, figurative constants do not require a data
definition. For example:
Move Spaces To Report-Header
RELATED REFERENCES
PICTURE clause (IBM COBOL Language Reference)
Literals (IBM COBOL Language Reference)
Figurative constants (IBM COBOL Language Reference)
24
Programming Guide
Assigning values to data items
After you have defined a data item, you can assign a value to it at any time.
Assignment takes many forms in COBOL, depending on what you want to do.
What you want to do
How to do it
To establish a constant
Use the VALUE clause in the definition of the data
item.
Note: Not a language feature; for
optimized code only: the optimizer
recognizes an invariant VALUE item and
treats it as a constant.
Assign values to a data item or large
data area
Use one of these ways:
v INITIALIZE statement
v MOVE statement
v STRING or UNSTRING statement
v VALUE clause (to set data items to the values
you want them to have when the program is
in its initial state)
Assign the results of arithmetic
Use the COMPUTE statement.
Replace characters or groups of
characters in a data item
Use the INSPECT statement.
Receive values from a file
Use the READ (or READ INTO) statement.
Receive values from a screen or a file
Use the ACCEPT statement.
Display values on a screen or in a file
Use the DISPLAY statement.
“Examples: initializing variables”
RELATED TASKS
“Initializing a structure (INITIALIZE)” on page 26
“Assigning values to variables or structures (MOVE)” on page 27
“Assigning arithmetic results (MOVE or COMPUTE)” on page 27
“Assigning input from a screen or file (ACCEPT)” on page 28
“Displaying values on a screen or in a file (DISPLAY)” on page 29
Examples: initializing variables
Initializing a variable to blanks or zeros:
INITIALIZE identifier-1
IDENTIFIER-1 PICTURE
IDENTIFIER-1 before
IDENTIFIER-1 after
9(5)
12345
00000
X(5)
AB123
ººººº1
99XX9
12AB3
ººººº1
XXBX/XX
ABbC/DE
ºººº/ºº1
**99.9CR
1234.5CR
**00.0ºº1
A(5)
ABCDE
ººººº1
+99.99E+99
+12.34E+02
+00.00E+00
1. The symbol º represents a blank space.
Chapter 2. Using data
25
Initializing a right-justified field:
01 ANJUST
PIC X(8) JUSTIFIED RIGHT.
01 ALPHABETIC-1
PIC A(4) VALUE “ABCD”.
. . .
INITIALIZE ANJUST
REPLACING ALPHANUMERIC DATA BY ALPHABETIC-1
ALPHABETIC-1
ANJUST before
ANJUST after
ABCD
ºººººººº
ººººABCD1
1
1. The symbol º represents a blank space.
Initializing an alphanumeric variable:
01 ALPHANUMERIC-1
PIC X.
01 ALPHANUMERIC-3
PIC X(1) VALUE “A”.
. . .
INITIALIZE ALPHANUMERIC-1
REPLACING ALPHANUMERIC DATA BY ALPHANUMERIC-3
ALPHANUMERIC-3
ALPHANUMERIC-1 before
ALPHANUMERIC-1 after
A
y
A
Initializing a numeric variable:
01 NUMERIC-1
PIC 9(8).
01 NUM-INT-CMPT-3
PIC 9(7) COMP VALUE 1234567.
. . .
INITIALIZE NUMERIC-1
REPLACING NUMERIC DATA BY NUM-INT-CMPT-3
NUM-INT-CMPT-3
NUMERIC-1 before
NUMERIC-1 after
1234567
98765432
01234567
Initializing an edited alphanumeric variable:
01 ALPHANUM-EDIT-1
PIC XXBX/XXX.
01 ALPHANUM-EDIT-3
PIC X/BB VALUE “M/ººº”.
. . .
INITIALIZE ALPHANUM-EDIT-1
REPLACING ALPHANUMERIC-EDITED DATA BY ALPHANUM-EDIT-3
ALPHANUM-EDIT-3
ALPHANUM-EDIT-1 before
ALPHANUM-EDIT-1 after
M/ºº
ABºC/DEF
M/ºº/ººº1
1
1
1. The symbol º represents a blank space.
RELATED TASKS
“Initializing a structure (INITIALIZE)”
Initializing a structure (INITIALIZE)
You can reset the values of all subordinate items in a group by applying the
INITIALIZE statement to the group item. However, it is inefficient to initialize an
entire group unless you really need all the items in the group initialized.
26
Programming Guide
The following example shows how you can reset fields in a transaction record
produced by a program to spaces and zeros. The fields are not identical in each
record produced.
01
TRANSACTION-OUT.
05 TRANSACTION-CODE
05 PART-NUMBER
05 TRANSACTION-QUANTITY
05 PRICE-FIELDS.
10 UNIT-PRICE
10 DISCOUNT
10 SALES-PRICE
. . .
INITIALIZE TRANSACTION-OUT
PIC X.
PIC 9(6).
PIC 9(5).
PIC 9(5)V9(2).
PIC V9(2).
PIC 9(5)V9(2).
TRANSACTION-OUT before
TRANSACTION-OUT after
1
R001383000240000000000000000
º0000000000000000000000000001
2
R001390000480000000000000000
º0000000000000000000000000001
3
S001410000120000000000000000
º0000000000000000000000000001
4
C001383000000000425000000000
º0000000000000000000000000001
5
C002010000000000000100000000
º0000000000000000000000000001
Record
1. The symbol º represents a blank space.
Assigning values to variables or structures (MOVE)
Use the MOVE statement to assign values to variables or structures.
For example, the following statement assigns the contents of the variable
Customer-Name to the variable Orig-Customer-Name:
Move Customer-Name to Orig-Customer-Name
If Customer-Name were longer than Orig-Customer-Name, truncation would occur on
the right. If it were shorter, the extra character positions on the right would be
filled with spaces.
When you move a group item to another group item, be sure the subordinate data
descriptions are compatible. The compiler performs all MOVE statements regardless
of whether the items fit, even if a destructive overlap could occur at run time,
For variables containing numbers, moves can be more complicated because there
are several ways numbers are represented. In general, the algebraic values of
numbers are moved if possible (as opposed to the digit-by-digit move performed
with character data):
01 Item-x
Pic 999v9.
. . .
Move 3.06 to Item-x
This move would result in Item-x containing the value 3.0, represented by 0030.
Assigning arithmetic results (MOVE or COMPUTE)
When assigning a number to a variable, consider using the COMPUTE statement
instead of the MOVE statement. For example, the following two statements
accomplish the same thing in most cases:
Move w to z
Compute z = w
Chapter 2. Using data
27
The MOVE statement carries out the assignment with truncation. You can, however,
specify the DIAGTRUNC compiler option to request that the compiler issue a warning
diagnostic for MOVE statements that might truncate numeric receivers.
|
|
|
When significant left-order digits would be lost in execution, the COMPUTE statement
can detect the condition and allow you to handle it.
When you use the ON SIZE ERROR phrase of the COMPUTE statement, the compiler
generates code to detect a size-overflow condition. If the condition occurs, the code
in the ON SIZE ERROR phrase is performed, and the content of z remains
unchanged. If the ON SIZE ERROR phrase is not specified, the assignment is carried
out with truncation. There is no ON SIZE ERROR support for the MOVE statement.
You can also use the COMPUTE statement to assign the result of an arithmetic
expression (or intrinsic function) to a variable. For example:
Compute z = y + (x ** 3)
Compute x = Function Max(x y z)
Results of date, time, and mathematical calculations, as well as other operations,
can be assigned to data items using Language Environment callable services. These
Language Environment services are available via a standard COBOL CALL
statement, and the values they return are passed in the parameters in the CALL
statement. For example, you can call the Language Environment service CEESIABS
to find the absolute value of a variable with the statement:
Call 'CEESIABS' Using Arg, Feedback-code, Result.
As a result of this call, the variable Result is assigned to be the absolute value of
the value that is in the variable Arg; the variable Feedback-code contains the return
code indicating whether the service completed successfully. You have to define all
the variables in the Data Division using the correct descriptions, according to the
requirements of the particular callable service you are using. For the example
above, the variables could be defined like this:
77 Arg
77 Feedback-code
77 Result
Pic s9(9) Binary.
Pic x(12) Display.
Pic s9(9) Binary.
RELATED REFERENCES
“DIAGTRUNC” on page 269
Intrinsic functions (IBM COBOL Language Reference)
Callable services (Language Environment Programming Reference)
Assigning input from a screen or file (ACCEPT)
One way to assign a value to a variable is to read the value from a screen or a file.
To enter data from the screen, first associate the monitor with a mnemonic-name in
the SPECIAL-NAMES paragraph. Then use ACCEPT to assign the line of input entered
at the screen to a variable.
For example:
Environment Division.
Configuration Section.
Special-Names.
Console is Names-Input.
. . .
Accept Customer-Name From Names-Input
To read from a file instead of the screen, make the following change:
28
Programming Guide
v Change Console to device, where device is any valid system device (for example,
SYSIN). For example:
SYSIN is Names-Inpu
|
|
|
|
|
Note that device can be a ddname that references a hierarchical file system (HFS)
path. If this DD is not defined and your program is running in an OS/390 UNIX
environment, stdin is the input source. If this DD is not defined and your
program is not running in an OS/390 UNIX environment, the ACCEPT statement
fails.
RELATED REFERENCES
SPECIAL-NAMES paragraph (IBM COBOL Language Reference)
Displaying values on a screen or in a file (DISPLAY)
You can display the value of a variable on a screen or write it to a file using the
DISPLAY statement. For example:
Display “No entry for surname '” Customer-Name
“' found in the file.”.
If the content of the variable Customer-Name is JOHNSON, then the statement
above displays the following message on the system logical output device:
No entry for surname 'JOHNSON' found in the file.
To write data to a destination other than the system logical output device, use the
UPON clause with a destination other than SYSOUT. For example, the following
statement writes to the file specified in the SYSPUNCH DD statement:
Display “Hello” UPON SYSPUNCH.
|
|
|
|
|
|
Note that you can specify a file in the hierarchical file system (HFS) with this
ddname. For example, with the following definition, your DISPLAY output is
written to the HFS file /u/userid/cobol/demo.lst:
//SYSPUNCH DD PATH='/u/userid/cobol/demo.lst',
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU,
// FILEDATA=TEXT
The following statement writes to the job log or console:
Display “Hello” UPON CONSOLE.
Displaying data on the system logical output device
To write data to the system logical output device, either omit the UPON clause or
use the UPON clause with destination SYSOUT. For example:
Display “Hello” UPON SYSOUT.
|
|
The output is directed to the ddname that you specify in the OUTDD compiler
option. Note that you can specify a file in the hierarchical file system (HFS) with
this ddname.
|
|
If the OUTDD ddname is not allocated and you are not running in an OS/390 UNIX
environment, a default DD of SYSOUT=* is allocated.
|
|
If the OUTDD ddname is not allocated and you are running in an OS/390 UNIX
environment, the _IGZ_SYSOUT environment variable is used as follows:
|
|
Undefined or set to stdout
Output is routed to stdout (file descriptor 1).
Chapter 2. Using data
29
|
|
Set to stderr
Output is routed to stderr (file descriptor 2).
|
|
|
Otherwise (set to something other than stdout or stderr)
The DISPLAY statement fails; a severity-3 Language Environment condition
is raised.
|
|
|
When DISPLAY output is routed to stdout or stderr, the output is not subdivided
into records; rather the output is written as a single stream of characters without
line breaks.
If OUTDD and the Language Environment run-time option MSGFILE both specify the
same ddname, DISPLAY output and Language Environment run-time diagnostics
are both routed to the Language Environment message file.
Using WITH NO ADVANCING
|
If you specify the WITH NO ADVANCING phrase and the output is going to a ddname,
the printer control character + (plus) is placed into the first output position from
the next DISPLAY statement. + is the ANSI-defined printer control character that
suppresses line spacing before a record is printed.
|
|
|
If you specify the WITH NO ADVANCING phrase and the output is going to stdout or
stderr, a new-line character is not appended to the end of the stream. A subsequent
DISPLAY statement might add additional characters to the end of the stream.
|
If you do not specify WITH NO ADVANCING and the output is going to a ddname, the
printer control character ’ ’ (space) is placed into the first output position from the
next DISPLAY statement, indicating single-spaced output.
For example:
DISPLAY
DISPLAY
DISPLAY
DISPLAY
DISPLAY
“ABC”
“CDEF” WITH NO ADVANCING
“GHIJK” WITH NO ADVANCING
“LMNOPQ”
“RSTUVWX”
If you use the statements above, the result sent to the output device is:
ABC
CDEF
+GHIJK
+LMNOPQ
RSTUVMX
The output printed depends on how the output device interprets printer control
characters.
If you do not specify the WITH NO ADVANCING phrase and the output is going to
stdout or stderr, a new-line character is appended to the end of the stream.
|
|
RELATED TASKS
“Setting and accessing environment variables” on page 362
“Coding COBOL programs to run under CICS” on page 347
RELATED REFERENCES
DISPLAY statement (IBM COBOL Language Reference)
“OUTDD” on page 286
30
Programming Guide
Using intrinsic functions (built-in functions)
Some high-level programming languages have built-in functions that you can
reference in your program as if they were variables having defined attributes and a
predetermined value. In COBOL, these are called intrinsic functions. They provide
capabilities for manipulating strings and numbers.
Because the value of an intrinsic function is derived automatically at the time of
reference, you do not need to define functions in the DATA DIVISION. Define only
the nonliteral data items that you use as arguments. Figurative constants are not
allowed as arguments.
A function-identifier is the combination of the COBOL reserved word FUNCTION
followed by a function name (such as Max), followed by any arguments to be used
in the evaluation of the function (such as x, y, z).
The groups of highlighted words in the following examples are referred to as
function-identifiers.
Unstring Function Upper-case(Name) Delimited By Space Into Fname Lname
Compute A = 1 + Function Log10(x)
Compute M = Function Max(x y z)
A function-identifier represents both the invocation of the function and the data
value returned by the function. Because it actually represents a data item, you can
use a function-identifier in most places in the PROCEDURE DIVISION where a data
item having the attributes of the returned value can be used.
The COBOL word function is a reserved word, but the function names are not
reserved. You can use them in other contexts, such as for the name of a variable.
For example, you could use Sqrt to invoke an intrinsic function and to name a
variable in your program:
Working-Storage Section.
01 x
Pic 99
01 y
Pic 99
01 z
Pic 99
01 Sqrt
Pic 99
. . .
Compute Sqrt = 16 ** .5
Compute z = x + Function
. . .
value
value
value
value
2.
4.
0.
0.
Sqrt(y)
Types of intrinsic functions
A function-identifier represents a value that is either a character string
(alphanumeric data class) or a number (numeric data class) depending on the type
of function. You can include a substring specification (reference modifier) in a
function-identifier for alphanumeric functions. Numeric intrinsic functions are
further classified according to the type of numbers they return.
The functions MAX, MIN, DATEVAL, and UNDATE can return either type of value
depending on the type of arguments you supply.
The functions DATEVAL, UNDATE, and YEARWINDOW are provided with the millennium
language extensions to assist with manipulating and converting windowed date
fields.
Chapter 2. Using data
31
Nesting functions
Functions can reference other functions as arguments as long as the results of the
nested functions meet the requirements for the arguments of the outer function.
For example:
Compute x = Function Max((Function Sqrt(5)) 2.5 3.5)
In this case, Function Sqrt(5) returns a numeric value. Thus, the three arguments
to the MAX function are all numeric, which is an allowable argument type for this
function.
RELATED TASKS
“Processing table items using intrinsic functions” on page 67
“Converting data items (intrinsic functions)” on page 94
“Evaluating data items (intrinsic functions)” on page 96
Using tables (arrays) and pointers
In COBOL, arrays are called tables. A table is a set of logically consecutive data
items that you define in the DATA DIVISION by using the OCCURS clause.
Pointers are data items that contain virtual storage addresses. You define them
explicitly with the USAGE IS POINTER clause in the DATA DIVISION or implicitly as
ADDRESS OF special registers.
You can perform the following operations on pointer data items:
v Pass them between programs by using the CALL . . . BY REFERENCE statement
v Move them to other pointers by using the SET statement
v Compare them to other pointers for equality by using a relation condition
v Initialize them to contain an address that is not valid by using VALUE IS NULL
Use pointer data items to:
v Accomplish limited base addressing, particularly if you want to pass and receive
addresses of a record area, that is defined with OCCURS DEPENDING ON and is
therefore variably located.
v Handle a chained list.
A procedure pointer is a pointer to an entry point of a procedure. Define the entry
address for a procedure with the USAGE IS PROCEDURE-POINTER clause in the DATA
DIVISION.
RELATED TASKS
“Defining a table (OCCURS)” on page 53
32
Programming Guide
Chapter 3. Working with numbers and arithmetic
In general, you can view COBOL numeric data as a series of decimal digit
positions. However, numeric items can also have special properties such as an
arithmetic sign or a currency sign.
This section describes how to define, display, and store numeric data so that you
can perform arithmetic operations efficiently:
v Use the PICTURE clause and the characters 9, +, -, P, S, and V to define numeric
data.
v Use the PICTURE clause and editing characters (such as Z, comma, and period)
along with MOVE and DISPLAY statements to display numeric data.
v Use the USAGE clause with various formats to control how numeric data is stored.
v Use the numeric class test to validate that data values are appropriate.
v Use ADD, SUBTRACT, MULTIPLY, DIVIDE, and COMPUTE statements to perform
arithmetic.
v Use the CURRENCY SIGN clause and appropriate PICTURE characters to designate
the currency you want.
RELATED TASKS
“Defining numeric data”
“Displaying numeric data” on page 34
“Controlling how numeric data is stored” on page 35
“Checking for incompatible data (numeric class test)” on page 42
“Performing arithmetic” on page 43
“Using currency signs” on page 51
Defining numeric data
Define numeric items by using the PICTURE clause with the character 9 in the data
description to represent the decimal digits of the number. Do not use an X, which
is for alphanumeric items:
05
05
|
|
|
|
Count-y
Customer-name
Pic 9(4)
Value 25.
Pic X(20) Value “Johnson”.
When you compile using the default compiler option ARITH(COMPAT) (referred to as
compatibility mode), you can code up to 18 digits in the PICTURE clause. When you
compile using ARITH(EXTEND) (referred to as extended mode), you can code up to 31
digits in the PICTURE clause.
Other characters of special significance that you can code are:
P
Indicates leading or trailing zeroes
S
Indicates a sign, positive or negative
V
Implies a decimal point
The s in the following example means that the value is signed:
05
Price
Pic s99v99.
The field can therefore hold a positive or a negative value. The v indicates the
position of an implied decimal point, but does not contribute to the size of the
© Copyright IBM Corp. 1991, 2000
33
item because it does not require a storage position. An s usually does not
contribute to the size of a numeric item, because by default it does not require a
storage position.
However, if you plan to port your program or data to a different machine, you
might want to code the sign as a separate position in storage. In this case, the sign
takes 1 byte:
05
Price
Pic s99V99
Sign Is Leading, Separate.
This coding ensures that the convention your machine uses for storing a
nonseparate sign will not cause unexpected results on a machine that uses a
different convention.
Separate signs are also preferable for data items that will be printed or displayed.
You cannot use the PICTURE clause with internal floating-point data (COMP-1 or
COMP-2). However, you can use the VALUE clause to provide an initial value for a
floating-point literal:
05
Compute-result
Usage Comp-2
Value 06.23E-24.
“Examples: numeric data and internal representation” on page 38
RELATED CONCEPTS
“Appendix A. Intermediate results and arithmetic precision” on page 559
RELATED TASKS
“Displaying numeric data”
“Controlling how numeric data is stored” on page 35
“Performing arithmetic” on page 43
RELATED REFERENCES
“Sign representation and processing” on page 41
“ARITH” on page 262
“NUMPROC” on page 283
Displaying numeric data
You can define numeric items with certain editing symbols (such as decimal points,
commas, dollar signs, and debit or credit signs) to make the data easier to read
and understand when you display it or print it. For example, in the code below,
Edited-price is a numeric-edited item:
05 Price
Pic
9(5)v99.
05 Edited-price
Pic $zz,zz9.99.
. . .
Move Price To Edited-price
Display Edited-price
If the contents of Price are 0150099 (representing the value 1,500.99), then
$ 1,500.99 is displayed when you run the code. The z in the PICTURE clause of
Edited-price indicates the suppression of leading zeros.
You cannot use numeric-edited items as operands in arithmetic expressions or in
ADD, SUBTRACT, MULTIPLY, DIVIDE, or COMPUTE statements. You use numeric-edited
items primarily for displaying or printing numeric data. (You can specify the
clause USAGE IS DISPLAY for numeric-edited items; however, it is implied. It means
that the items are stored in character format.)
34
Programming Guide
You can move numeric-edited items to numeric or numeric-edited items. In the
following example, the value of the numeric-edited item is moved to the numeric
item:
Move Edited-price to Price
Display Price
If these two statements immediately followed the statements in the previous
example, then Price would be displayed as 0150099, representing the value
1,500.99.
“Examples: numeric data and internal representation” on page 38
RELATED TASKS
“Controlling how numeric data is stored”
“Defining numeric data” on page 33
“Performing arithmetic” on page 43
RELATED REFERENCES
MOVE statement (IBM COBOL Language Reference)
Controlling how numeric data is stored
You can control how the computer stores numeric data items by coding the USAGE
clause in your data description entries. You might want to control the format for
any of several reasons such as these:
v Arithmetic on computational data types is more efficient than on USAGE DISPLAY
data types.
v Packed-decimal format requires less storage per digit than USAGE DISPLAY data
types.
v Packed-decimal format converts to and from DISPLAY format more efficiently
than binary format does.
v Floating-point format is well suited for arithmetic operands and results with
widely varying scale, while maintaining the maximal number of significant
digits.
v You might need to preserve data formats when you move data from one
machine to another.
The numeric data you use in your program will have one of the following formats
available with COBOL:
v External decimal (USAGE DISPLAY)
|
v
v
v
v
v
External floating point (USAGE DISPLAY)
Internal decimal (USAGE PACKED-DECIMAL)
Binary (USAGE BINARY)
Native binary (USAGE COMP-5)
Internal floating point (USAGE COMP-1, USAGE COMP-2)
COMP and COMP-4 are synonymous with BINARY, and COMP-3 is synonymous with
PACKED-DECIMAL.
The compiler converts displayable numbers to the internal representation of their
numeric values before using them in arithmetic operations. Therefore it is often
more efficient if you define data items as BINARY or PACKED-DECIMAL rather than as
DISPLAY. For example:
Chapter 3. Working with numbers and arithmetic
35
05
Initial-count
Pic S9(4)
Usage Binary
Value 1000.
Regardless of which USAGE clause you use to control the internal representation of a
value, you use the same PICTURE clause conventions and decimal value in the
VALUE clause (except for floating-point data, for which you cannot use a PICTURE
clause).
“Examples: numeric data and internal representation” on page 38
RELATED CONCEPTS
“Formats for numeric data”
“Data format conversions” on page 39
“Appendix A. Intermediate results and arithmetic precision” on page 559
RELATED TASKS
“Defining numeric data” on page 33
“Displaying numeric data” on page 34
“Performing arithmetic” on page 43
RELATED REFERENCES
“Conversions and precision” on page 40
“Sign representation and processing” on page 41
Formats for numeric data
The following are the available formats for numeric data.
External decimal (DISPLAY) items
When USAGE DISPLAY is in effect for a data item (either because you have coded it,
or by default), each position (byte) of storage contains one decimal digit. This
means the items are stored in displayable form.
External decimal (also known as zoned decimal) items are primarily intended for
receiving and sending numbers between your program and files, terminals, or
printers. You can also use external decimal items as operands and receivers in
arithmetic processing. However, if your program performs a lot of intensive
arithmetic and efficiency is a high priority, COBOL’s computational numeric types
might be a better choice for the data items used in the arithmetic.
External floating-point (DISPLAY) items
Displayable numbers coded in a floating-point format are called external
floating-point items. As with external decimal items, you define external
floating-point items explicitly by coding USAGE DISPLAY or implicitly by omitting
the USAGE clause. You cannot use the VALUE clause for external floating-point items.
In the following example, Compute-Result is implicitly defined as an external
floating-point item. Each byte of storage contains one of the characters (except for
the v).
05
Compute-Result
Pic -9v9(9)E-99.
The minus signs (-) do not mean that the mantissa and exponent must necessarily
be negative numbers. Instead, they mean that when the number is displayed, the
sign appears as a blank for positive numbers or a minus sign for negative
numbers. If you instead code a plus sign (+), the sign appears as a plus sign for
positive numbers or a minus sign for negative numbers.
36
Programming Guide
|
|
|
|
As with external decimal numbers, external floating-point numbers have to be
converted (by the compiler) to an internal representation of their numeric value
before they can be used in arithmetic operations. If you compile with the default
option ARITH (COMPAT), external floating-point numbers are converted to long
(64-bit) floating-point format. If you compile with ARITH (EXTEND), they are instead
converted to extended-precision (128-bit) floating-point format.
Binary (COMP) items
BINARY, COMP, and COMP-4 are synonyms on all platforms.
Binary format numbers occupy 2, 4, or 8 bytes of storage. If the picture clause
specifies that the item is signed, the leftmost bit is used as the operational sign.
A binary number with a PICTURE description of four or fewer decimal digits
occupies 2 bytes; five to nine decimal digits, 4 bytes; and 10 to 18 decimal digits, 8
bytes. Binary items with nine or more digits require more handling by the
compiler. Testing them for the SIZE ERROR condition and rounding is more
cumbersome than with other types.
You can use binary items, for example, for indexes, subscripts, switches, and
arithmetic operands or results.
Use the TRUNC(STD|OPT|BIN) compiler option to indicate how binary data (BINARY,
COMP, or COMP-4) is to be truncated.
Native binary (COMP-5) items
|
COMP-5 is a USAGE type based on the X/OPEN COBOL specification.
|
|
|
|
|
|
|
Data items that you declare as USAGE COMP-5 are represented in storage as binary
data. However, unlike USAGE COMP items, they can contain values of magnitude up
to the capacity of the native binary representation (2, 4, or 8 bytes) rather than
being limited to the value implied by the number of 9s in the PICTURE clause.
When you move or store numeric data into a COMP-5 item, truncation occurs at the
binary field size rather than at the COBOL PICTURE size limit. When you reference
a COMP-5 item, the full binary field size is used in the operation.
|
|
COMP-5 is thus particularly useful for binary data items originating in non-COBOL
programs where the data might not conform to a COBOL PICTURE clause.
|
The table below shows the ranges of values possible for COMP-5 data items.
Picture
Storage representation
Numeric values
|
S9(1) through S9(4)
Binary halfword (2 bytes)
-32768 through +32767
|
S9(5) through S9(9)
Binary fullword (4 bytes)
-2,147,483,648 through +2,147,483,647
|
|
S9(10) through
S9(18)
Binary doubleword (8
bytes)
-9,223,372,036,854,775,808 through
+9,223,372,036,854,775,807
|
9(1) through 9(4)
Binary halfword (2 bytes)
0 through 65535
|
9(5) through 9(9)
Binary fullword (4 bytes)
0 through 4,294,967,295
|
9(10) through 9(18)
Binary doubleword (8
bytes)
0 through 18,446,744,073,709,551,615
Chapter 3. Working with numbers and arithmetic
37
|
|
|
|
|
You can specify scaling (that is, decimal positions or implied integer positions) in
the PICTURE clause of COMP-5 items. If you do so, you must appropriately scale the
maximal capacities listed above. For example, a data item you describe as PICTURE
S99V99 COMP-5 is represented in storage as a binary halfword, and supports a range
of values from -327.68 through +327.67.
|
|
Regardless of the setting of the TRUNC compiler option, COMP-5 data items behave
like binary data does in programs compiled with TRUNC(BIN).
Packed-decimal (COMP-3) items
PACKED-DECIMAL and COMP-3 are synonyms on all platforms.
Packed-decimal items occupy 1 byte of storage for every two decimal digits you
code in the PICTURE description, except that the rightmost byte contains only one
digit and the sign. This format is most efficient when you code an odd number of
digits in the PICTURE description, so that the leftmost byte is fully used.
Packed-decimal items are handled as fixed-point numbers for arithmetic purposes.
Floating-point (COMP-1 and COMP-2) items
COMP-1 refers to short floating-point format and COMP-2 refers to long floating-point
format, which occupy 4 and 8 bytes of storage, respectively. The leftmost bit
contains the sign and the next 7 bits contain the exponent; the remaining 3 or 7
bytes contain the mantissa.
On OS/390 & VM, COMP-1 and COMP-2 data items are stored in System/390
hexadecimal format.
RELATED CONCEPTS
“Appendix A. Intermediate results and arithmetic precision” on page 559
RELATED REFERENCE
“TRUNC” on page 297
Examples: numeric data and internal representation
This table shows the internal representation of numeric items.
Numeric type
External
decimal
PICTURE and USAGE and
optional SIGN clause
PIC S9999 DISPLAY
Value
+ 1234
- 1234
1234
F1 F2 F3 C4
F1 F2 F3 D4
F1 F2 F3 C4
1234
F1 F2 F3 F4
PIC S9999 DISPLAY
SIGN LEADING
+ 1234
- 1234
C1 F2 F3 F4
D1 F2 F3 F4
PIC S9999 DISPLAY
SIGN LEADING SEPARATE
PIC S9999 DISPLAY
SIGN TRAILING SEPARATE
+
+
-
PIC 9999 DISPLAY
38
Internal representation
Programming Guide
1234
1234
1234
1234
4E
60
F1
F1
F1
F1
F2
F2
F2
F2
F3
F3
F3
F3
F4
F4
F4
F4
4E
60
Numeric type
Binary
PICTURE and USAGE and
optional SIGN clause
PIC S9999 BINARY
COMP
COMP-4
|
|
PIC 9999
|
Internal representation
+ 1234
- 1234
04 D2
FB 2E
COMP-5
+ 123451
- 123451
30 39
CF C7
BINARY
COMP
COMP-4
1234
04 D2
COMP-5
600001
EA 60
PIC S9999 PACKED-DECIMAL
COMP-3
+ 1234
- 1234
01 23 4C
01 23 4D
PIC 9999
PACKED-DECIMAL
COMP-3
+ 1234
- 1234
01 23 4F
01 23 4F
Internal
floating
point
COMP-1
+ 1234
43 4D 20 00
Internal
floating
point
COMP-2
+ 1234
- 1234
43 4D 20 00 00 00 00 00
C3 4D 20 00 00 00 00 00
External
floating
point
PIC +9(2).9(2)E+99 DISPLAY
+ 1234
4E F1 F2 4B F3
F4 C5 4E F0 F2
- 1234
60 F1 F2 4B F3
F4 C5 4E F0 F2
Internal
decimal
|
|
|
Value
1. The example demonstrates that COMP-5 data items can contain values of magnitude up to the capacity of the
native binary representation (2, 4, or 8 bytes), rather than being limited to the value implied by the number of 9s
in the PICTURE clause.
Data format conversions
When the code in your program involves the interaction of items with different
data formats, the compiler converts these items as follows:
v Temporarily, for comparisons and arithmetic operations
v Permanently, for assignment to the receiver in a MOVE or COMPUTE statement
A conversion is actually a move of a value from one data item to another. The
compiler performs any conversions that are required during the execution of
arithmetic or comparisons with the same rules that are used for MOVE and COMPUTE
statements.
When possible, the compiler performs a move to preserve numeric value as
opposed to a direct digit-for-digit move.
Conversion generally requires additional storage and processing time because data
is moved to an internal work area and converted before the operation is
performed. The results might also have to be moved back into a work area and
converted again.
Conversions between fixed-point data formats (external decimal, packed decimal,
or binary) are without loss of precision as long as the target field can contain all
the digits of the source operand.
Chapter 3. Working with numbers and arithmetic
39
A loss of precision is possible in conversions between fixed-point data formats and
floating-point data formats (short floating point, long floating point, or external
floating point). These conversions happen during arithmetic evaluations that have
a mixture of both fixed-point and floating-point operands.
RELATED REFERENCES
“Conversions and precision”
“Sign representation and processing” on page 41
Conversions and precision
Because both fixed-point and external floating-point items have decimal
characteristics, references to fixed-point items in the following examples include
external floating-point items also unless stated otherwise.
When the compiler converts from fixed-point to internal floating-point format,
fixed-point numbers in base 10 are converted to the numbering system used
internally.
When the compiler converts short form to long form for comparisons, zeros are
used for padding the shorter number.
When a USAGE COMP-1 data item is moved to a fixed-point data item with more
than nine digits, the fixed-point data item will receive only nine significant digits,
and the remaining digits will be zero.
When a USAGE COMP-2 data item is moved to a fixed-point data item with more
than 18 digits, the fixed-point data item will receive only 18 significant digits, and
the remaining digits will be zero.
Conversions that preserve precision
If a fixed-point data item with six or fewer digits is moved to a USAGE COMP-1 data
item and then returned to the fixed-point data item, the original value is recovered.
If a USAGE COMP-1 data item is moved to a fixed-point data item of nine or more
digits and then returned to the USAGE COMP-1 data item, the original value is
recovered.
If a fixed-point data item with 15 or fewer digits is moved to a USAGE COMP-2 data
item and then returned to the fixed-point data item, the original value is recovered.
If a USAGE COMP-2 data item is moved to a fixed-point (not external floating-point)
data item of 18 or more digits and then returned to the USAGE COMP-2 data item,
the original value is recovered.
|
Conversions that result in rounding
If a USAGE COMP-1 data item, a USAGE COMP-2 data item, an external floating-point
data item, or a floating-point literal is moved to a fixed-point data item, rounding
occurs in the low-order position of the target data item.
If a USAGE COMP-2 data item is moved to a USAGE COMP-1 data item, rounding occurs
in the low-order position of the target data item.
If a fixed-point data item is moved to an external floating-point data item and the
PICTURE of the fixed-point data item contains more digit positions than the PICTURE
of the external floating-point data item, rounding occurs in the low-order position
of the target data item.
40
Programming Guide
RELATED CONCEPTS
“Appendix A. Intermediate results and arithmetic precision” on page 559
Sign representation and processing
Sign representation affects the processing and interaction of your numeric data.
Given X’sd’, where s is the sign representation and d represents the digit, the valid
sign representations for external decimal (USAGE DISPLAY without the SIGN IS
SEPARATE clause) are:
Positive:
C, A, E, and F
Negative:
D and B
The COBOL NUMPROC compiler option affects sign processing for external decimal
and internal decimal data. NUMPROC has no effect on binary data or floating-point
data.
NUMPROC(PFD)
Given X’sd’, where s is the sign representation and d represents the digit, when
you use NUMPROC(PFD), the compiler assumes that the sign in your data is one of
three preferred signs:
Signed positive or 0:
X’C’
Signed negative:
X’D’
Unsigned or alphanumeric:
X’F’
Based on this assumption, the compiler uses whatever sign it is given to process
data. The preferred sign is generated only where necessary (for example, when
unsigned data is moved to signed data). Using the NUMPROC(PFD) option can save
processing time, but you must use preferred signs with your data for correct
processing.
NUMPROC(NOPFD)
When the NUMPROC(NOPFD) compiler option is in effect, the compiler accepts any
valid sign configuration. The preferred sign is always generated in the receiver.
NUMPROC(NOPFD) is less efficient than NUMPROC(PFD), but you should use it whenever
data that does not use preferred signs might exist.
If an unsigned, external-decimal sender is moved to an alphanumeric receiver, the
sign is unchanged (even with NUMPROC(NOPFD)).
NUMPROC(MIG)
When NUMPROC(MIG) is in effect, the compiler generates code that is similar to that
produced by OS/VS COBOL. This option can be especially useful if you migrate
OS/VS COBOL programs to COBOL for OS/390 & VM.
RELATED REFERENCES
“NUMPROC” on page 283
Chapter 3. Working with numbers and arithmetic
41
Checking for incompatible data (numeric class test)
The compiler assumes that the values you supply for a data item are valid for the
item’s PICTURE and USAGE clauses, and assigns the values without checking for
validity. When you give an item a value that is incompatible with its data
description, references to that item in the PROCEDURE DIVISION are undefined and
your results will be unpredictable.
It can happen that values are passed into your program and assigned to items that
have incompatible data descriptions for those values. For example, nonnumeric
data might be moved or passed into a field that is defined as numeric. Or a signed
number might be passed into a field that is defined as unsigned. In both cases, the
receiving fields contain invalid data. Ensure that the contents of a data item
conform to its PICTURE and USAGE clauses before using the data item in any further
processing steps.
You can use the numeric class test to perform data validation. For example:
Linkage Section.
01 Count-x
Pic 999.
. . .
Procedure Division Using Count-x.
If Count-x is numeric then display “Data is good”
The numeric class test checks the contents of a data item against a set of values
that are valid for the particular PICTURE and USAGE of the data item. For example, a
packed-decimal item is checked for hexadecimal values X’0’ through X’9’ in the
digit positions, and for a valid sign value in the sign position (whether separate or
nonseparate).
For external decimal, external floating-point, and packed-decimal items, the
numeric class test is affected by the NUMPROC compiler option and the NUMCLS option
(which is set at installation time). To determine the NUMCLS setting used at your
installation, consult your system programmer.
If NUMCLS(PRIM) is in effect at your installation, use the following table to find the
values that the compiler considers valid for the sign.
NUMPROC(NOPFD)
NUMPROC(PFD)
NUMPROC(MIG)
Signed
C, D, F
C, D, +0 (positive zero)
C, D, F
Unsigned
F
F
F
Separate sign
+, -
+, -, +0 (positive zero)
+, -
If NUMCLS(ALT) is in effect at your installation, use the following table to find the
values that the compiler considers valid for the sign.
NUMPROC(NOPFD)
NUMPROC(PFD)
NUMPROC(MIG)
Signed
A to F
C, D, +0 (positive zero)
A to F
Unsigned
F
F
F
Separate sign
+, -
+, -, +0 (positive zero)
+, -
RELATED REFERENCES
“NUMPROC” on page 283
42
Programming Guide
Performing arithmetic
You can use any of several COBOL language features to perform arithmetic:
v COMPUTE, ADD, SUBTRACT, MULTIPLY, and DIVIDE statements
v Arithmetic expressions
v Intrinsic functions
v Language Environment callable services
COMPUTE and other arithmetic statements
Use the COMPUTE statement for most arithmetic evaluations rather than ADD,
SUBTRACT, MULTIPLY, and DIVIDE statements. Often you can code one COMPUTE
statement instead of several individual statements.
The COMPUTE statement assigns the result of an arithmetic expression to one or
more data items:
Compute z
= a + b / c ** d - e
Compute x y z = a + b / c ** d - e
Some arithmetic might be more intuitive using arithmetic statements other than
COMPUTE. For example:
COMPUTE
Equivalent arithmetic statements
Compute Increment =
Increment + 1
Add 1 to Increment
Compute Balance =
Balance - Overdraft
Subtract Overdraft
from Balance
Compute IncrementOne =
IncrementOne + 1
Compute IncrementTwo =
IncrementTwo + 1
Compute IncrementThree =
IncrementThree + 1
Add 1 to IncrementOne,
IncrementTwo,
IncrementThree
You might also prefer to use the DIVIDE statement (with its REMAINDER phrase) for
division in which you want to process a remainder. The REM intrinsic function also
provides the ability to process a remainder.
Arithmetic expressions
|
You can use arithmetic expressions in many (but not all) places in statements
where numeric data items are allowed. For example, you can use arithmetic
expressions as comparands in relation conditions:
If (a + b) > (c - d + 5) Then. . .
Arithmetic expressions can consist of a single numeric literal, a single numeric data
item, or a single intrinsic function reference. They can also consist of several of
these items connected by arithmetic operators. Arithmetic operators are evaluated
in the following order of precedence:
Operator
Meaning
Order of evaluation
Unary + or -
Algebraic sign
First
**
Exponentiation
Second
Chapter 3. Working with numbers and arithmetic
43
Operator
Meaning
Order of evaluation
/ or *
Division or multiplication
Third
Binary + or -
Addition or subtraction
Last
Operators at the same level of precedence are evaluated from left to right;
however, you can use parentheses to change the order of evaluation. Expressions
in parentheses are evaluated before the individual operators are evaluated.
Parentheses, necessary or not, make your program easier to read.
Numeric intrinsic functions
You can use numeric intrinsic functions only in places where numeric expressions
are allowed. These functions can save you time because you don’t have to code the
many common types of calculations that they provide.
Numeric intrinsic functions return a signed numeric value. They are treated as
temporary numeric data items.
Many of the capabilities of numeric intrinsic functions are also provided by
Language Environment callable services.
Numeric functions are classified into these categories:
Integer
Those that return an integer
Floating point
Those that return a long (64-bit) or extended-precision (128-bit)
floating-point value (depending on whether you compile using the default
option ARITH(COMPAT) or using ARITH(EXTEND))
|
|
|
Mixed Those that return an integer, a floating-point value, or a fixed-point
number with decimal places, depending on the arguments
You can use intrinsic functions to perform several different arithmetic operations,
as outlined in the following table.
|
Number handling
Date and time
Finance
Mathematics
Statistics
LENGTH
MAX
MIN
NUMVAL
NUMVAL-C
ORD-MAX
ORD-MIN
CURRENT-DATE
DATE-OF-INTEGER
DATE-TO-YYYYMMDD
DATEVAL
DAY-OF-INTEGER
DAY-TO-YYYYDDD
INTEGER-OF-DATE
INTEGER-OF-DAY
UNDATE
WHEN-COMPILED
YEAR-TO-YYYY
YEARWINDOW
ANNUITY
PRESENT-VALUE
ACOS
ASIN
ATAN
COS
FACTORIAL
INTEGER
INTEGER-PART
LOG
LOG10
MOD
REM
SIN
SQRT
SUM
TAN
MEAN
MEDIAN
MIDRANGE
RANDOM
RANGE
STANDARD-DEVIATION
VARIANCE
|
|
“Examples: numeric intrinsic functions” on page 47
44
Programming Guide
Nesting functions and arithmetic expressions
You can reference one function as the argument of another. A nested function is
evaluated independently of the outer function, except when determining whether a
mixed function should be evaluated using fixed-point or floating-point
instructions.
You can also nest an arithmetic expression as an argument to a numeric function:
Compute x = Function Sum(a b (c / d))
In this example, there are only three function arguments: a, b, and the arithmetic
expression (c / d).
ALL subscripting and special registers
You can reference all the elements of a table (or array) as function arguments by
using the ALL subscript.
You can use the integer special registers as arguments wherever integer arguments
are allowed.
Math and date Language Environment services
Many of the capabilities of COBOL intrinsic functions are also provided by
Language Environment callable services. Language Environment callable services
provide a means of assigning arithmetic results to data items. They include
mathematical functions, and date and time operations.
Math-oriented callable services
|
|
|
|
For most COBOL intrinsic functions there are corresponding math-oriented callable
services you can use that produce the same results, as shown in the following
table. When you compile with the default option ARITH(COMPAT), COBOL
floating-point intrinsic functions return long (64-bit) results. When you compile
with option ARITH(EXTEND), COBOL floating-point intrinsic functions (with the
exception of RANDOM) return extended-precision (128-bit) results.
|
|
|
So for example (considering the first row of the table), if you compile using
ARITH(COMPAT), CEESDACS returns the same result as ACOS. If you compile using
ARITH(EXTEND), CEESQACS returns the same result as ACOS.
COBOL intrinsic
function
Corresponding Language Environment
callable services
Long precision
Extended precision
Results same for
intrinsic function
and callable service?
|
ACOS
CEESDACS
CEESQACS
Yes
|
ASIN
CEESDASN
CEESQASN
Yes
|
ATAN
CEESDATN
CEESQATN
Yes
|
COS
CEESDCOS
CEESQCOS
Yes
|
LOG
CEESDLOG
CEESQLOG
Yes
|
LOG10
CEESDLG1
CEESQLG1
Yes
|
RANDOM
CEERAN0
none
No
|
REM
CEESDMOD
CEESQMOD
Yes
|
SIN
CEESDSIN
CEESQSIN
Yes
|
SQRT
CEESDSQT
CEESQSQT
Yes
1
Chapter 3. Working with numbers and arithmetic
45
|
TAN
|
|
1. RANDOM returns a long (64-bit) floating-point result even if you pass it a 31-digit
argument and compile using option ARITH(EXTEND).
CEESDTAN
CEESQTAN
Yes
Both the RANDOM intrinsic function and CEERAN0 service generate random
numbers between zero and one. However, because each uses its own algorithm,
RANDOM and CEERAN0 produce different random numbers from the same seed.
Even for functions that produce the same results, how you use intrinsic functions
and Language Environment callable services differs. The rules for the data types
required for intrinsic function arguments are less restrictive. For numeric intrinsic
functions, you can use arguments that are of any numeric data type. When you
invoke a Language Environment callable service with a CALL statement, however,
you must ensure that the parameters match the numeric data types required by
that service (generally COMP-1 or COMP-2).
The error handling of intrinsic functions and Language Environment callable
services sometimes differs. If you pass an explicit feedback token when calling the
Language Environment math services, you must check the feedback code after
each call and take explicit action to deal with errors. However, if you call with the
feedback token explicitly OMITTED, you do not need to check the token; Language
Environment automatically signals any errors.
Date callable services
Both the COBOL date intrinsic functions and the Language Environment date
callable services are based on the Gregorian calendar. However, the starting dates
can differ depending on the setting of the INTDATE compiler option. When the
default setting of INTDATE(ANSI) is in effect, COBOL uses January 1, 1601 as day 1.
When INTDATE(LILIAN) is in effect, COBOL uses October 15, 1582 as day 1.
Language Environment always uses October 15, 1582 as day 1.
This means that if you use INTDATE(LILIAN), you get equivalent results from
COBOL intrinsic functions and Language Environment callable date services.
The following table shows the results when INTDATE(ANSI) is in effect.
COBOL intrinsic
function
Language Environment callable
service
Results
INTEGER-OF-DATE
CEECBLDY
Compatible
DATE-OF-INTEGER
CEEDATE with picture string YYYYMMDD
Incompatible
DAY-OF-INTEGER
CEEDATE with picture string YYYYDDD
Incompatible
INTEGER-OF-DATE
CEEDAYS
Incompatible
The following table shows the results when INTDATE(LILIAN) is in effect.
46
Programming Guide
COBOL intrinsic
function
Language Environment callable
service
Results
DATE-OF-INTEGER
CEEDATE with picture string YYYYMMDD
Compatible
DAY-OF-INTEGER
CEEDATE with picture string YYYYDDD
Compatible
INTEGER-OF-DATE
CEEDAYS
Compatible
INTEGER-OF-DATE
CEECBLDY
Incompatible
RELATED CONCEPTS
“Fixed-point versus floating-point arithmetic” on page 49
“Appendix A. Intermediate results and arithmetic precision” on page 559
RELATED TASKS
“Using Language Environment callable services” on page 553
RELATED REFERENCES
“ARITH” on page 262
Examples: numeric intrinsic functions
The following examples and accompanying explanations show intrinsic functions
in each of several categories.
General number handling
Suppose you want to find the maximum value of two prices (represented as
alphanumeric items with dollar signs), put this value into a numeric field in an
output record, and determine the length of the output record. You can use
NUMVAL-C (a function that returns the numeric value of an alphanumeric string) and
the MAX and LENGTH functions to do this:
01
01
01
01
X
Pic 9(2).
Price1
Pic x(8)
Value “$8000”.
Price2
Pic x(8)
Value “$2000”.
Output-Record.
05 Product-Name
Pic x(20).
05 Product-Number Pic 9(9).
05 Product-Price
Pic 9(6).
. . .
Procedure Division.
Compute Product-Price =
Function Max (Function Numval-C(Price1) Function Numval-C(Price2))
Compute X = Function Length(Output-Record)
Additionally, to ensure that the contents in Product-Name are in uppercase letters,
you can use the following statement:
Move Function Upper-case (Product-Name) to Product-Name
Date and time
The following example shows how to calculate a due date that is 90 days from
today. The first eight characters returned by the CURRENT-DATE function represent
the date in a four-digit year, two-digit month, and two-digit day format (YYYYMMDD).
The date is converted to its integer value; then 90 is added to this value and the
integer is converted back to the YYYYMMDD format.
01 YYYYMMDD
Pic 9(8).
01 Integer-Form
Pic S9(9).
. . .
Move Function Current-Date(1:8) to YYYYMMDD
Compute Integer-Form = Function Integer-of-Date(YYYYMMDD)
Add 90 to Integer-Form
Compute YYYYMMDD = Function Date-of-Integer(Integer-Form)
Display 'Due Date: ' YYYYMMDD
Finance
Business investment decisions frequently require computing the present value of
expected future cash inflows to evaluate the profitability of a planned investment.
Chapter 3. Working with numbers and arithmetic
47
The present value of an amount that you expect to receive at a given time in the
future is that amount, which, if invested today at a given interest rate, would
accumulate to that future amount.
For example, assume that a proposed investment of $1,000 produces a payment
stream of $100, $200, and $300 over the next three years, one payment per year
respectively. The following COBOL statements calculate the present value of those
cash inflows at a 10% interest rate:
01
01
01
01
01
. .
Series-Amt1
Pic 9(9)V99
Value 100.
Series-Amt2
Pic 9(9)V99
Value 200.
Series-Amt3
Pic 9(9)V99
Value 300.
Discount-Rate
Pic S9(2)V9(6)
Value .10.
Todays-Value
Pic 9(9)V99.
.
Compute Todays-Value =
Function
Present-Value(Discount-Rate Series-Amt1 Series-Amt2 Series-Amt3)
You can use the ANNUITY function in business problems that require you to
determine the amount of an installment payment (annuity) necessary to repay the
principal and interest of a loan. The series of payments is characterized by an
equal amount each period, periods of equal length, and an equal interest rate each
period. The following example shows how you can calculate the monthly payment
required to repay a $15,000 loan in three years at a 12% annual interest rate (36
monthly payments, interest per month = .12/12):
01
01
01
01
. .
Loan
Pic 9(9)V99.
Payment
Pic 9(9)V99.
Interest
Pic 9(9)V99.
Number-Periods
Pic 99.
.
Compute Loan = 15000
Compute Interest = .12
Compute Number-Periods = 36
Compute Payment =
Loan * Function Annuity((Interest / 12) Number-Periods)
Mathematics
The following COBOL statement demonstrates that you can nest intrinsic
functions, use arithmetic expressions as arguments, and perform previously
complex calculations simply:
Compute Z = Function Log(Function Sqrt (2 * X + 1)) + Function Rem(X 2)
Here in the addend the intrinsic function REM (instead of a DIVIDE statement with a
REMAINDER clause) returns the remainder of dividing X by 2.
Statistics
Intrinsic functions make calculating statistical information easier. Assume you are
analyzing various city taxes and want to calculate the mean, median, and range
(the difference between the maximum and minimum taxes):
01
01
01
01
01
01
01
. .
48
Programming Guide
Tax-S
Tax-T
Tax-W
Tax-B
Ave-Tax
Median-Tax
Tax-Range
.
Pic
Pic
Pic
Pic
Pic
Pic
Pic
99v999 value
99v999 value
99v999 value
99v999 value
99v999.
99v999.
99v999.
.045.
.02.
.035.
.03.
Compute Ave-Tax
= Function Mean
(Tax-S Tax-T Tax-W Tax-B)
Compute Median-Tax = Function Median (Tax-S Tax-T Tax-W Tax-B)
Compute Tax-Range = Function Range (Tax-S Tax-T Tax-W Tax-B)
Fixed-point versus floating-point arithmetic
Many statements in your program could involve arithmetic. For example, each of
the following types of COBOL statements requires some arithmetic evaluation:
v General arithmetic
compute report-matrix-col = (emp-count ** .5) + 1
add report-matrix-min to report-matrix-max giving report-matrix-tot
v Expressions and functions
compute report-matrix-col = function sqrt(emp-count) + 1
compute whole-hours
= function integer-part((average-hours) + 1)
v Arithmetic comparisons
if report-matrix-col <
function sqrt(emp-count) + 1
if whole-hours
not = function integer-part((average-hours) + 1)
How you code arithmetic in your program (whether an arithmetic statement, an
intrinsic function, an expression, or some combination of these nested within each
other) determines whether the evaluation is in floating-point or fixed-point
arithmetic.
Floating-point evaluations
In general, if your arithmetic coding has either of the characteristics listed below, it
is evaluated in floating-point arithmetic:
v An operand or result field is floating point.
A data item is floating point if you code it as a floating-point literal or if you
define it as USAGE COMP-1, USAGE COMP-2, or external floating point (USAGE
DISPLAY with a floating-point PICTURE).
An operand that is a nested arithmetic expression or a reference to a numeric
intrinsic function results in floating-point arithmetic when any of the following
is true:
– An argument in an arithmetic expression results in floating point.
– The function is a floating-point function.
– The function is a mixed function with one or more floating-point arguments.
v An exponent contains decimal places.
An exponent contains decimal places if you use a literal that contains decimal
places, give the item a PICTURE containing decimal places, or use an arithmetic
expression or function whose result has decimal places.
An arithmetic expression or numeric function yields a result with decimal places if
any operand or argument (excluding divisors and exponents) has decimal places.
Fixed-point evaluations
In general, if an arithmetic operation contains neither of the characteristics listed
above for floating point, the compiler will cause it to be evaluated in fixed-point
arithmetic. In other words, arithmetic evaluations are handled as fixed point only if
all the operands are fixed point, the result field is defined to be fixed point, and
none of the exponents represent values with decimal places. Nested arithmetic
expressions and function references must also represent fixed-point values.
Chapter 3. Working with numbers and arithmetic
49
Arithmetic comparisons (relation conditions)
When you compare numeric expressions using a relational operator, the numeric
expressions (whether they are data items, arithmetic expressions, function
references, or some combination of these) are comparands in the context of the
entire evaluation. That is, the attributes of each can influence the evaluation of the
other: both expressions are evaluated in fixed point, or both are evaluated in
floating point. This is also true of abbreviated comparisons even though one
comparand does not explicitly appear in the comparison. For example:
if (a + d) = (b + e) and c
This statement has two comparisons: (a + d) = (b + e), and (a + d) = c.
Although (a + d) does not explicitly appear in the second comparison, it is a
comparand in that comparison. Therefore, the attributes of c can influence the
evaluation of (a + d).
The compiler handles comparisons (and the evaluation of any arithmetic
expressions nested in comparisons) in floating-point arithmetic if either comparand
is a floating-point value or resolves to a floating-point value.
The compiler handles comparisons (and the evaluation of any arithmetic
expressions nested in comparisons) in fixed-point arithmetic if both comparands
are fixed-point values or resolve to fixed-point values.
Implicit comparisons (no relational operator used) are not handled as a unit,
however; the two comparands are treated separately as to their evaluation in
floating-point or fixed-point arithmetic. In the following example, five arithmetic
expressions are evaluated independently of one another’s attributes, and then are
compared to each other.
evaluate (a + d)
when (b + e) thru c
when (f / g) thru (h * i)
. . .
end-evaluate
“Examples: fixed-point and floating-point evaluations”
RELATED REFERENCES
“Arithmetic expressions in nonarithmetic statements” on page 568
Examples: fixed-point and floating-point evaluations
Assume you define the data items for an employee table in the following manner:
01
. .
01
01
01
01
01
01
employee-table.
05 emp-count
pic 9(4).
05 employee-record occurs 1 to 1000 times
depending on emp-count.
10 hours
pic +9(5)e+99.
.
report-matrix-col
pic 9(3).
report-matrix-min
pic 9(3).
report-matrix-max
pic 9(3).
report-matrix-tot
pic 9(3).
average-hours
pic 9(3)v9.
whole-hours
pic 9(4).
These statements are evaluated using floating-point arithmetic:
50
Programming Guide
compute report-matrix-col = (emp-count ** .5) + 1
compute report-matrix-col = function sqrt(emp-count) + 1
if report-matrix-tot < function sqrt(emp-count) + 1
These statements are evaluated using fixed-point arithmetic:
add report-matrix-min to report-matrix-max giving report-matrix-tot
compute report-matrix-max =
function max(report-matrix-max report-matrix-tot)
if whole-hours not = function integer-part((average-hours) + 1)
Using currency signs
Many programs need to process financial information and present that information
using the appropriate currency signs. With COBOL currency support (and the
appropriate code page for your printer or display unit), you can use one or more
of the following signs in a program:
v Symbols such as the dollar sign ($)
v Currency signs of more than one character (such as USD, DEM, EUR)
v Euro sign, established by the Economic and Monetary Union (EMU)
To specify the symbols for displaying financial information, use the CURRENCY SIGN
clause (in the SPECIAL-NAMES paragraph in the CONFIGURATION SECTION) with the
PICTURE characters that relate to the symbols. In the following example, the
PICTURE character $ indicates that the currency sign $US is to be used:
Currency Sign is “$US” with Picture Symbol “$”.
. . .
77 Invoice-Amount
Pic $$,$$9.99.
. . .
Display “Invoice amount is ” Invoice-Amount.
In this example, if Invoice-Amount contained 1500.00, the display output would be:
Invoice amount is
$US1,500.00
By using more than one CURRENCY SIGN clause in your program, you can allow for
multiple currency signs to be displayed.
You can use a hexadecimal literal to indicate the currency sign value. This could be
useful if the data-entry method for the source program does not allow the entry of
the intended characters easily. The following example shows the hex value X’9F’
used as the currency sign:
Currency Sign X'9F' with Picture Symbol 'U'.
. . .
01 Deposit-Amount
Pic UUUUU9.99.
If there is no corresponding character for the euro sign on your keyboard, you
need to specify it as a hexadecimal value in the CURRENCY SIGN clause. The
hexadecimal value for the euro sign is either X’9F’ or X’5A’ depending on the code
page in use, as shown in the following table.
Modified
from
Euro sign
USA, Canada, Netherlands, Portugal,
Australia, New Zealand
IBM-037
X’9F’
IBM-1141
Austria, Germany
IBM-273
X’9F’
IBM-1142
Denmark, Norway
IBM-277
X’5A’
Code page
Applicable countries
IBM-1140
Chapter 3. Working with numbers and arithmetic
51
Code page
Applicable countries
Modified
from
Euro sign
IBM-1143
Finland, Sweden
IBM-278
X’5A’
IBM-1144
Italy
IBM-280
X’9F’
IBM-1145
Spain, Latin America - Spanish
IBM-284
X’9F’
IBM-1146
UK
IBM-285
X’9F’
IBM-1147
France
IBM-297
X’9F’
IBM-1148
Belgium, Canada, Switzerland
IBM-500
X’9F’
IBM-1149
Iceland
IBM-871
X’9F’
“Example: multiple currency signs”
Example: multiple currency signs
The following example shows how you can display values in both euro currency
(as EUR) and French francs (as FRF):
IDENTIFICATION DIVISION.
PROGRAM-ID. EuroExample.
Environment Division.
Configuration Section.
Special-Names.
Currency Sign is “FRF ” with Picture Symbol “F”
Currency Sign is “EUR ” with Picture Symbol “U”.
Data Division.
WORKING-STORAGE Section.
01 Deposit-in-Euro
Pic S9999V99 Value 8000.00.
01 Deposit-in-FRF
Pic S99999V99.
01 Deposit-Report.
02 Report-in-Franc
Pic -FFFFF9.99.
02 Report-in-Euro
Pic -UUUUU9.99.
. . .
01 EUR-to-FRF-Conv-Rate
Pic 9V99999 Value 6.78901.
. . .
PROCEDURE DIVISION.
Report-Deposit-in-FRF-and-EUR.
Move Deposit-in-Euro to Report-in-Euro
. . .
Compute Deposit-in-FRF Rounded
= Deposit-in-Euro * EUR-to-FRF-Conv-Rate
On Size Error
Perform Conversion-Error
Not On Size Error
Move Deposit-in-FRF to Report-in-Franc
Display “Deposit in Euro = ” Report-in-Euro
Display “Deposit in Franc = ” Report-in-Franc
End-Compute
. . .
Goback.
Conversion-Error.
Display “Conversion error from EUR to FRF”
Display “Euro value: ” Report-in-Euro.
The above example produces the following display output:
Deposit in Euro = EUR 8000.00
Deposit in Franc = FRF 54312.08
The exchange rate used in this example is for illustrative purposes only.
52
Programming Guide
Chapter 4. Handling tables
A table is a collection of data items that have the same description, such as account
totals or monthly averages. A table is the COBOL equivalent of an array of
elements. It consists of a table name and subordinate items called table elements.
In the example above, SAMPLE-TABLE-ONE is the group item that contains the table.
TABLE-COLUMN names the table element of a one-dimensional table that occurs three
times.
Rather than define repetitious items as separate, consecutive entries in the DATA
DIVISION, you can use the OCCURS clause in the DATA DIVISION entry to define a
table. This practice has these advantages:
v The code clearly shows the unity of the items (the table elements).
v You can use subscripts and indexes to refer to the table elements.
v You can easily repeat data items.
Tables are important for increasing the speed of a program, especially one that
looks up records.
RELATED TASKS
“Defining a table (OCCURS)”
“Referring to an item in a table” on page 55
“Putting values into a table” on page 58
“Nesting tables” on page 54
“Creating variable-length tables (DEPENDING ON)” on page 62
“Searching a table” on page 65
“Processing table items using intrinsic functions” on page 67
“Handling tables efficiently” on page 539
Defining a table (OCCURS)
To code a table, give the table a group name and define a subordinate item (the
table element) that is to be repeated n times. table-name is the group name in the
following example:
01
table-name.
05 element-name OCCURS n TIMES.
. . . (subordinate items of the table element might follow)
The table element definition (which includes the OCCURS clause) is subordinate to
the group item that contains the table. The OCCURS clause cannot appear in a
level-01 description.
To create tables of two to seven dimensions, use nested OCCURS clauses.
© Copyright IBM Corp. 1991, 2000
53
RELATED TASKS
“Creating variable-length tables (DEPENDING ON)” on page 62
“Nesting tables”
“Putting values into a table” on page 58
“Referring to an item in a table” on page 55
“Searching a table” on page 65
RELATED REFERENCES
OCCURS clause (IBM COBOL Language Reference)
Nesting tables
To create a two-dimensional table, define a one-dimensional table in each
occurrence of another one-dimensional table. For example:
In SAMPLE-TABLE-TWO, TABLE-ROW is an element of a one-dimensional table that
occurs two times. TABLE-COLUMN is an element of a two-dimensional table that
occurs three times in each occurrence of TABLE-ROW.
To create a three-dimensional table, define a one-dimensional table in each
occurrence of another one-dimensional table, which is itself contained in each
occurrence of another one-dimensional table. For example:
In SAMPLE-TABLE-THREE, TABLE-DEPTH is an element of a one-dimensional table that
occurs two times. TABLE-ROW is an element of a two-dimensional table that occurs
two times within each occurrence of TABLE-DEPTH. TABLE-COLUMN is an element of a
three-dimensional table that occurs three times within each occurrence of
TABLE-ROW.
Subscripting
In a two-dimensional table, the two subscripts correspond to the row and column
numbers. In a three-dimensional table, the three subscripts correspond to the
depth, row, and column numbers.
The following valid references to SAMPLE-TABLE-THREE use literal subscripts. The
spaces are required in the second example.
54
Programming Guide
TABLE-COLUMN (2, 2, 1)
TABLE-COLUMN (2 2 1)
In either table reference, the first value (2) refers to the second occurrence within
TABLE-DEPTH, the second value (2) refers to the second occurrence within TABLE-ROW,
and the third value (1) refers to the first occurrence within TABLE-COLUMN.
The following reference to SAMPLE-TABLE-TWO uses variable subscripts. The reference
is valid if SUB1 and SUB2 are data names that contain positive integer values within
the range of the table.
TABLE-COLUMN (SUB1 SUB2)
Indexing
Consider the following three-dimensional table, SAMPLE-TABLE-FOUR:
01
SAMPLE-TABLE-FOUR
05 TABLE-DEPTH OCCURS 3 TIMES INDEXED BY INX-A.
10 TABLE-ROW OCCURS 4 TIMES INDEXED BY INX-B.
15 TABLE-COLUMN OCCURS 8 TIMES INDEXED BY INX-C
PIC X(8).
Suppose you code the following relative indexing reference to SAMPLE-TABLE-FOUR:
TABLE-COLUMN (INX-A + 1, INX-B + 2, INX-C - 1)
This reference causes the following computation of the displacement to the
TABLE-COLUMN element:
(contents of INX-A) + (256 * 1)
+ (contents of INX-B) + (64 * 2)
+ (contents of INX-C) - (8 * 1)
This calculation is based on the following element lengths:
v Each occurrence of TABLE-DEPTH is 256 bytes in length (4 * 8 * 8).
v Each occurrence of TABLE-ROW is 64 bytes in length (8 * 8).
v Each occurrence of TABLE-COLUMN is 8 bytes in length.
RELATED TASKS
“Defining a table (OCCURS)” on page 53
“Referring to an item in a table”
“Putting values into a table” on page 58
“Creating variable-length tables (DEPENDING ON)” on page 62
“Searching a table” on page 65
“Processing table items using intrinsic functions” on page 67
“Handling tables efficiently” on page 539
RELATED REFERENCES
OCCURS clause (IBM COBOL Language Reference)
Referring to an item in a table
A table element has a collective name, but the individual items within it do not
have unique data names.
To refer to an item, you have a choice of three techniques:
v Use the data name of the table element, along with its occurrence number
(called a subscript) in parentheses. This technique is called subscripting.
Chapter 4. Handling tables
55
v Use the data name of the table element, along with a value (called an index) that
is added to the address of the table to locate an item (the displacement from the
beginning of the table). This technique is called indexing, or subscripting using
indenames.
v Use both subscripts and indexes together.
RELATED TASKS
“Indexing” on page 57
“Subscripting”
Subscripting
The lowest possible subscript value is 1, which points to the first occurrence of the
table element. In a one-dimensional table, the subscript corresponds to the row
number.
You can use a data name or a literal for a subscript.
If a data item with a literal subscript is of fixed length, the compiler resolves the
location of the data item.
When you use a data name as a variable subscript, you must describe the data
name as an elementary numeric integer. The most efficient format is COMPUTATIONAL
(COMP) with a PICTURE size smaller than five digits. You cannot use a subscript with
a data name that is used as a subscript.
The code generated for the application resolves the location of a variable subscript
at run time.
You can increment or decrement a literal or variable subscript by a specified
integer amount. For example:
TABLE-COLUMN (SUB1 - 1, SUB2 + 3)
You can change part of a table element rather than the whole element. Simply refer
to the character position and length of the substring to be changed within the
subscripted element. For example:
01
ANY-TABLE.
05 TABLE-ELEMENT
PIC X(10)
OCCURS 3 TIMES
VALUE “ABCDEFGHIJ”.
. . .
MOVE “??” TO TABLE-ELEMENT (1) (3 : 2).
The MOVE statement moves the value ?? into table element number 1, beginning at
character position 3, for a length of 2:
RELATED TASKS
“Indexing” on page 57
56
Programming Guide
“Putting values into a table” on page 58
“Searching a table” on page 65
“Handling tables efficiently” on page 539
Indexing
You can create an index either with a particular table (using OCCURS INDEXED BY) or
separately (using USAGE IS INDEX).
For example:
05 TABLE-ITEM PIC X(8)
OCCURS 10 INDEXED BY INX-A.
The compiler calculates the value contained in the index as the occurrence number
(subscript) minus 1, multiplied by the length of the table element. Therefore, for
the fifth occurrence of TABLE-ITEM, the binary value contained in INX-A is (5 - 1) * 8,
or 32.
You can use this index to index another table only if both table descriptions have
the same number of table elements, and the table elements are the same length.
If you use USAGE IS INDEX to create an index, you can use the index data item with
any table. For example:
77 INX-B USAGE IS INDEX.
. . .
PERFORM VARYING INX-B FROM 1 BY 1 UNTIL INX-B > 10
DISPLAY TABLE-ITEM (INX-B)
. . .
END-PERFORM.
INX-B is used to traverse table TABLE-ITEM above, but could be used to traverse
other tables also.
You can increment or decrement an index name by an unsigned numeric literal.
The literal is considered to be an occurrence number. It is converted to an index
value before being added to or subtracted from the index name.
Initialize the index name with a SET, PERFORM VARYING, or SEARCH ALL statement.
You can then also use it in SEARCH or relational condition statements. To change the
value, use a PERFORM, SEARCH, or SET statement.
Use the SET statement to assign to an index the value that you stored in the index
data item defined by USAGE IS INDEX. For example, when you load records into a
variable-length table, you can store the index value of the last record read in a data
item defined as USAGE IS INDEX. Then you can test for the end of the table by
comparing the current index value with the index value of the last record. This
technique is useful when you look through or process the table.
Because you are comparing a physical displacement, you can use index data items
only in SEARCH and SET statements or for comparisons with indexes or other index
data items. You cannot use index data items as subscripts or indexes.
RELATED TASKS
“Subscripting” on page 56
“Putting values into a table” on page 58
Chapter 4. Handling tables
57
“Searching a table” on page 65
“Processing table items using intrinsic functions” on page 67
“Handling tables efficiently” on page 539
RELATED REFERENCES
INDEXED BY phrase (IBM COBOL Language Reference)
INDEX phrase (IBM COBOL Language Reference)
Putting values into a table
Use one of these methods to put values into a table:
v Load the table dynamically.
v Initialize the table (INITIALIZE statement).
v Assign values when you define the table (VALUE clause).
RELATED TASKS
“Loading a table dynamically”
“Loading a variable-length table” on page 63
“Initializing a table (INITIALIZE)”
“Assigning values when you define a table (VALUE)”
“Assigning values to a variable-length table” on page 64
Loading a table dynamically
If the initial values of your table are different with each execution of your
program, you can define the table without initial values. You can then read the
changed values into the table before your program refers to the table.
To load a table, use the PERFORM statement and either subscripting or indexing.
When reading data to load your table, test to make sure that the data does not
exceed the space allocated for the table. Use a named value (rather than a literal)
for the item count. Then, if you make the table bigger, you need to change only
one value, instead of all references to a literal.
“Example: PERFORM and subscripting” on page 60
“Example: PERFORM and indexing” on page 61
RELATED REFERENCES
PERFORM with VARYING phrase (IBM COBOL Language Reference)
Initializing a table (INITIALIZE)
You can load your table with a value during execution with the INITIALIZE
statement. For example, to fill a table with 3s, you can use this code:
INITIALIZE TABLE-ONE REPLACING NUMERIC DATA BY 3.
The INITIALIZE statement cannot load a variable-length table (one that was defined
using OCCURS DEPENDING ON).
RELATED REFERENCES
INITIALIZE statement (IBM COBOL Language Reference)
Assigning values when you define a table (VALUE)
If your table contains stable values (such as days and months), set the specific
values your table holds when you define it.
58
Programming Guide
Define static values in WORKING-STORAGE in one of these ways:
v Initialize each table item individually.
v Initialize an entire table at the 01 level.
v Initialize all occurrences of a given table element to the same value.
Initializing each table item individually
If your table is small, you can use this technique:
1. Declare a record that contains the same items as are in your table.
2. Set the initial value of each item in a VALUE clause.
3. Code a REDEFINES entry to make the record into a table.
For example:
***********************************************************
***
E R R O R
F L A G
T A B L E
***
***********************************************************
01 Error-Flag-Table
Value Spaces.
88 No-Errors
Value Spaces.
05 Type-Error
Pic X.
05 Shift-Error
Pic X.
05 Home-Code-Error
Pic X.
05 Work-Code-Error
Pic X.
05 Name-Error
Pic X.
05 Initials-Error
Pic X.
05 Duplicate-Error
Pic X.
05 Not-Found-Error
Pic X.
01 Filler Redefines Error-Flag-Table.
05 Error-Flag Occurs 8 Times
Indexed By Flag-Index
Pic X.
(In this example, the items could all be initialized with one VALUE clause at the 01
level, because each item was being initialized to the same value.)
To initialize larger tables, use MOVE, PERFORM, or INITIALIZE statements.
Initializing a table at the 01 level
Code a level-01 record and assign to it, through the VALUE clause, the contents of
the whole table. Then, in a subordinate level data item, use an OCCURS clause to
define the individual table items.
For example:
01
TABLE-ONE
05 TABLE-TWO OCCURS 4 TIMES
VALUE “1234”.
PIC X.
Initializing all occurrences of a table element
You can use the VALUE clause on a table element to initialize the element to the
indicated value. For example:
01
T2.
05 T-OBJ
05 T OCCURS 5 TIMES
DEPENDING ON T-OBJ.
10 X
10 Y
10 Z
PIC 9
VALUE 3.
PIC XX VALUE “AA”.
PIC 99 VALUE 19.
PIC XX VALUE “BB”.
The above code causes all the X elements (1 through 5) to be initialized to AA, all
the Y elements (1 through 5) to be initialized to 19, and all the Z elements (1
through 5) to be initialized to BB. T-OBJ is then set to 3.
Chapter 4. Handling tables
59
RELATED REFERENCES
REDEFINES clause (IBM COBOL Language Reference)
PERFORM statement (IBM COBOL Language Reference)
INITIALIZE statement (IBM COBOL Language Reference)
OCCURS clause (IBM COBOL Language Reference)
Example: PERFORM and subscripting
This example traverses an error flag table using subscripting until an error code
that has been set is found. If an error code is found, the corresponding error
message is moved to a print report field.
. . .
***********************************************************
***
E R R O R
F L A G
T A B L E
***
***********************************************************
01 Error-Flag-Table
Value Spaces.
88 No-Errors
Value Spaces.
05 Type-Error
Pic X.
05 Shift-Error
Pic X.
05 Home-Code-Error
Pic X.
05 Work-Code-Error
Pic X.
05 Name-Error
Pic X.
05 Initials-Error
Pic X.
05 Duplicate-Error
Pic X.
05 Not-Found-Error
Pic X.
01 Filler Redefines Error-Flag-Table.
05 Error-Flag Occurs 8 Times
77 ERROR-ON
Pic X Value “E”.
Indexed By Flag-Index
Pic X.
***********************************************************
***
E R R O R
M E S S A G E
T A B L E
***
***********************************************************
01 Error-Message-Table.
05 Filler
Pic X(25) Value
“Transaction Type Invalid”.
05 Filler
Pic X(25) Value
“Shift Code Invalid”.
05 Filler
Pic X(25) Value
“Home Location Code Inval.”.
05 Filler
Pic X(25) Value
“Work Location Code Inval.”.
05 Filler
Pic X(25) Value
“Last Name - Blanks”.
05 Filler
Pic X(25) Value
“Initials - Blanks”.
05 Filler
Pic X(25) Value
“Duplicate Record Found”.
05 Filler
Pic X(25) Value
“Commuter Record Not Found”.
01 Filler Redefines Error-Message-Table.
05 Error-Message Occurs 8 Times
Indexed By Message-Index
Pic X(25).
. . .
PROCEDURE DIVISION.
. . .
Perform
Varying Sub From 1 By 1
Until No-Errors
If Error-Flag (Sub) = Error-On
Move Space To Error-Flag (Sub)
Move Error-Message (Sub) To Print-Message
Perform 260-Print-Report
End-If
End-Perform
. . .
60
Programming Guide
Example: PERFORM and indexing
This example traverses an error flag table using indexing until an error code that
has been set is found. If an error code is found, the corresponding error message is
moved to a print report field.
. . .
***********************************************************
***
E R R O R
F L A G
T A B L E
***
***********************************************************
01 Error-Flag-Table
Value Spaces.
88 No-Errors
Value Spaces.
05 Type-Error
Pic X.
05 Shift-Error
Pic X.
05 Home-Code-Error
Pic X.
05 Work-Code-Error
Pic X.
05 Name-Error
Pic X.
05 Initials-Error
Pic X.
05 Duplicate-Error
Pic X.
05 Not-Found-Error
Pic X.
01 Filler Redefines Error-Flag-Table.
05 Error-Flag Occurs 8 Times
Indexed By Flag-Index
Pic X.
***********************************************************
***
E R R O R
M E S S A G E
T A B L E
***
***********************************************************
01 Error-Message-Table.
05 Filler
Pic X(25) Value
“Transaction Type Invalid”.
05 Filler
Pic X(25) Value
“Shift Code Invalid”.
05 Filler
Pic X(25) Value
“Home Location Code Inval.”.
05 Filler
Pic X(25) Value
“Work Location Code Inval.”.
05 Filler
Pic X(25) Value
“Last Name - Blanks”.
05 Filler
Pic X(25) Value
“Initials - Blanks”.
05 Filler
Pic X(25) Value
“Duplicate Record Found”.
05 Filler
Pic X(25) Value
“Commuter Record Not Found”.
01 Filler Redefines Error-Message-Table.
05 Error-Message Occurs 8 Times
Indexed By Message-Index
Pic X(25).
. . .
PROCEDURE DIVISION.
. . .
Set Flag-Index To 1
Perform Until No-Errors
Search Error-Flag
When Error-Flag (Flag-Index) = Error-On
Move Space To Error-Flag (Flag-Index)
Set Message-Index To Flag-Index
Move Error-Message (Message-Index) To
Print-Message
Perform 260-Print-Report
End-Search
End-Perform
. . .
Chapter 4. Handling tables
61
Creating variable-length tables (DEPENDING ON)
If you do not know before run time how many times a table element occurs, you
need to set up a variable-length table definition. To do this, use the OCCURS
DEPENDING ON (ODO) clause. For example:
X OCCURS 1 TO 10 TIMES DEPENDING ON Y
In this example, X is called the ODO subject, and Y is the ODO object.
Two factors affect the successful manipulation of variable-length records:
v Correct calculation of records lengths.
The length of the variable portions of a group item is the product of the object
of the DEPENDING ON option and the length of the subject of the OCCURS clause.
v Conformance of the data in the object of the OCCURS DEPENDING ON clause to its
PICTURE clause.
If the content of the ODO object does not match its PICTURE clause, the program
could abnormally terminate. You must ensure that the ODO object correctly
specifies the current number of occurrences of table elements.
The following example shows a group item (REC-1) that contains both the subject
and object of the OCCURS DEPENDING ON clause. The way the length of the group
item is determined depends on whether it is sending or receiving data.
WORKING-STORAGE SECTION.
01 MAIN-AREA.
03 REC-1.
05 FIELD-1
05 FIELD-2 OCCURS 1 TO 5 TIMES
DEPENDING ON FIELD-1
01 REC-2.
03 REC-2-DATA
PIC 9.
PIC X(05).
PIC X(50).
If you want to move REC-1 (the sending item in this case) to REC-2, the length of
REC-1 is determined immediately before the move, using the current value in
FIELD-1. If the content of FIELD-1 conforms to its PICTURE (that is, if FIELD-1
contains an external decimal item), the move can proceed based on the actual
length of REC-1. Otherwise, the result is unpredictable. You must ensure that the
ODO object has the correct value before you initiate the move.
When you do a move to REC-1 (the receiving item in this case), the length of REC-1
is determined using the maximum number of occurrences. In this example, that
would be five occurrences of FIELD-2, plus FIELD-1, for a length of 26 bytes.
In this case, you need not set the ODO object (FIELD-1) before referencing REC-1 as
a receiving item. However, the sending field’s ODO object (not shown) must be set
to a valid numeric value between 1 and 5 for the ODO object of the receiving field
to be validly set by the move.
This behavior is different if the CMPR2 compiler option is in effect.
However, if you do a move to REC-1 (again the receiving item) where REC-1 is
followed by a variably located group (a type of complex ODO), the actual length of
REC-1 is calculated immediately before the move. In the following example, REC-1
and REC-2 are in the same record, but REC-2 is not subordinate to REC-1 and is
therefore variably located:
62
Programming Guide
01
MAIN-AREA
03 REC-1.
05 FIELD-1
05 FIELD-3
05 FIELD-2 OCCURS
DEPENDING ON
03 REC-2.
05 FIELD-4 OCCURS
DEPENDING ON
PIC 9.
PIC 9.
1 TO 5 TIMES
FIELD-1
PIC X(05).
1 TO 5 TIMES
FIELD-3
PIC X(05).
When you do a MOVE to REC-1 in this case, the actual length of REC-1 is calculated
immediately before the move using the current value of the ODO object (FIELD-1).
The compiler issues a message letting you know that the actual length was used.
This case requires that you set the value of the ODO object before using the group
item as a receiving field.
The following example shows how to define a variable-length table when the ODO
object (here LOCATION-TABLE-LENGTH) is outside the group.
DATA DIVISION.
FILE SECTION.
FD LOCATION-FILE
RECORDING MODE F
BLOCK 0 RECORDS
RECORD 80 CHARACTERS
LABEL RECORD STANDARD.
01 LOCATION-RECORD.
05 LOC-CODE
PIC XX.
05 LOC-DESCRIPTION
PIC X(20).
05 FILLER
PIC X(58).
. . .
WORKING-STORAGE SECTION.
01 FLAGS.
05 LOCATION-EOF-FLAG
PIC X(5) VALUE SPACE.
88 LOCATION-EOF
VALUE “FALSE”.
01 MISC-VALUES.
05 LOCATION-TABLE-LENGTH
PIC 9(3) VALUE ZERO.
05 LOCATION-TABLE-MAX
PIC 9(3) VALUE 100.
*****************************************************************
***
L O C A T I O N
T A B L E
***
***
FILE CONTAINS LOCATION CODES.
***
*****************************************************************
01 LOCATION-TABLE.
05 LOCATION-CODE OCCURS 1 TO 100 TIMES
DEPENDING ON LOCATION-TABLE-LENGTH
PIC X(80).
RELATED CONCEPTS
“Appendix B. Complex OCCURS DEPENDING ON” on page 569
RELATED TASKS
“Assigning values to a variable-length table” on page 64
“Loading a variable-length table”
COBOL for OS/390 & VM Compiler and Run-Time Migration Guide
RELATED REFERENCES
OCCURS DEPENDING ON clause (IBM COBOL Language Reference)
“CMPR2” on page 264
Loading a variable-length table
You can use a do-until structure (a TEST AFTER loop) to control the loading of a
variable-length table. For example, after the following code runs,
LOCATION-TABLE-LENGTH contains the subscript of the last item in the table.
Chapter 4. Handling tables
63
DATA DIVISION.
FILE SECTION.
FD LOCATION-FILE
RECORDING MODE F
BLOCK 0 RECORDS
RECORD 80 CHARACTERS
LABEL RECORD STANDARD.
01 LOCATION-RECORD.
05 LOC-CODE
PIC XX.
05 LOC-DESCRIPTION
PIC X(20).
05 FILLER
PIC X(58).
. . .
WORKING-STORAGE SECTION.
01 FLAGS.
05 LOCATION-EOF-FLAG
PIC X(5) VALUE SPACE.
88 LOCATION-EOF
VALUE “YES”.
01 MISC-VALUES.
05 LOCATION-TABLE-LENGTH
PIC 9(3) VALUE ZERO.
05 LOCATION-TABLE-MAX
PIC 9(3) VALUE 100.
*****************************************************************
***
L O C A T I O N
T A B L E
***
***
FILE CONTAINS LOCATION CODES.
***
*****************************************************************
01 LOCATION-TABLE.
05 LOCATION-CODE OCCURS 1 TO 100 TIMES
DEPENDING ON LOCATION-TABLE-LENGTH
PIC X(80).
. . .
PROCEDURE DIVISION.
. . .
Perform Test After
Varying Location-Table-Length From 1 By 1
Until Location-EOF
Or Location-Table-Length = Location-Table-Max
Move Location-Record To
Location-Code (Location-Table-Length)
Read Location-File
At End Set Location-EOF To True
End-Read
End-Perform
Assigning values to a variable-length table
You can use a VALUE clause on a group item that contains an OCCURS clause with the
DEPENDING ON option. Each subordinate structure that contains the DEPENDING ON
option is initialized using the maximum number of occurrences. If you define the
entire table with the DEPENDING ON option, all the elements are initialized using the
maximum defined value of the DEPENDING ON object.
If the ODO object has a VALUE clause, it is logically initialized after the ODO subject
has been initialized. For example, in the following code
01
TABLE-THREE
05 X
05 Y OCCURS 5 TIMES
DEPENDING ON X
VALUE “3ABCDE”.
PIC 9.
PIC X.
the ODO subject Y(1) is initialized to A, Y(2) to B, . . ., Y(5) to E, and finally the
ODO object X is initialized to 3. Any subsequent reference to TABLE-THREE (such as
in a DISPLAY statement) refers to the first three elements, Y(1) through Y(3).
This behavior is different if the CMPR2 compiler option is in effect.
RELATED TASKS
COBOL for OS/390 & VM Compiler and Run-Time Migration Guide
64
Programming Guide
RELATED REFERENCES
OCCURS DEPENDING ON clause (IBM COBOL Language Reference)
“CMPR2” on page 264
Searching a table
COBOL provides two search techniques for tables: serial and binary.
To do serial searches, use SEARCH and indexing. For variable-length tables, you can
use PERFORM with subscripting or indexing.
To do binary searches, use SEARCH ALL and indexing.
A binary search can be considerably more efficient than a serial search. For a serial
search, the number of comparisons is of the order of n, the number of entries in
the table. For a binary search, the number of comparisons is only of the order of
the logarithm (base 2) of n. A binary search, however, requires that the table items
already be sorted.
RELATED TASKS
“Doing a serial search (SEARCH)”
“Doing a binary search (SEARCH ALL)” on page 66
Doing a serial search (SEARCH)
Use the SEARCH statement to do a serial search beginning at the current index
setting. To modify the index setting, use the SET statement.
The conditions in the WHEN option are evaluated in the order in which they appear:
v If none of the conditions is satisfied, the index is increased to correspond to the
next table element, and the WHEN conditions are evaluated again.
v If one of the WHEN conditions is satisfied, the search ends. The index remains
pointing to the table element that satisfied the condition.
v If the entire table has been searched and no conditions were met, the AT END
imperative statement is executed if there is one. If you do not use AT END,
control passes to the next statement in your program.
You can reference only one level of a table (a table element) with each SEARCH
statement. To search multiple levels of a table, use nested SEARCH statements.
Delimit each nested SEARCH statement with END-SEARCH.
If the found condition comes after some intermediate point in the table, you can
speed up the search. Use the SET statement to set the index to begin the search
after that point.
Arranging the table so that the data used most often is at the beginning also
enables more efficient serial searching. If the table is large and is presorted, a
binary search is more efficient.
“Example: serial search” on page 66
RELATED REFERENCES
SEARCH statement (IBM COBOL Language Reference)
Chapter 4. Handling tables
65
Example: serial search
Suppose you define a three-dimensional table, each with its own index (set to 1, 4,
and 1, respectively). The innermost table (TABLE-ENTRY3) has an ascending key. The
object of the search is to find a particular string in the innermost table.
01
TABLE-ONE.
05 TABLE-ENTRY1 OCCURS 10 TIMES
INDEXED BY TE1-INDEX.
10 TABLE-ENTRY2 OCCURS 10 TIMES
INDEXED BY TE2-INDEX.
15 TABLE-ENTRY3 OCCURS 5 TIMES
ASCENDING KEY IS KEY1
INDEXED BY TE3-INDEX.
20 KEY1
PIC X(5).
20 KEY2
PIC X(10).
. . .
PROCEDURE DIVISION.
. . .
SET TE1-INDEX TO 1
SET TE2-INDEX TO 4
SET TE3-INDEX TO 1
MOVE “A1234” TO KEY1 (TE1-INDEX, TE2-INDEX, TE3-INDEX + 2)
MOVE “AAAAAAAA00” TO KEY2 (TE1-INDEX, TE2-INDEX, TE3-INDEX + 2)
. . .
SEARCH TABLE-ENTRY3
AT END
MOVE 4 TO RETURN-CODE
WHEN TABLE-ENTRY3(TE1-INDEX, TE2-INDEX, TE3-INDEX)
= “A1234AAAAAAAA00”
MOVE 0 TO RETURN-CODE
END-SEARCH
Values after execution:
TE1-INDEX = 1
TE2-INDEX = 4
TE3-INDEX points to the TABLE-ENTRY3 item
that equals “A1234AAAAAAAA00”
RETURN-CODE = 0
Doing a binary search (SEARCH ALL)
When you use SEARCH ALL to do a binary search, you do not need to set the index
before you begin. The index used is always the one associated with the first index
name in the OCCURS clause. The index varies during execution to maximize the
search efficiency.
To use the SEARCH ALL statement, your table must already be ordered on the key or
keys coded in the OCCURS clause. You can use any key in the WHEN condition, but
you must test all preceding data names in the KEY option, if any. The test must be
an equal-to condition, and the KEY data-name must be either the subject of the
condition or the name of a conditional variable with which the tested
condition-name is associated. The WHEN condition can also be a compound
condition, formed from simple conditions with AND as the only logical connective.
The key and its object of comparison must be compatible.
“Example: binary search” on page 67
RELATED REFERENCES
SEARCH statement (IBM COBOL Language Reference)
66
Programming Guide
Example: binary search
Suppose you define a table that contains 90 elements of 40 bytes each, with three
keys. The primary and secondary keys (KEY-1 and KEY-2) are in ascending order,
but the least significant key (KEY-3) is in descending order:
01
TABLE-A.
05 TABLE-ENTRY OCCURS 90 TIMES
ASCENDING KEY-1, KEY-2
DESCENDING KEY-3
INDEXED BY INDX-1.
10 PART-1
PIC 99.
10 KEY-1
PIC 9(5).
10 PART-2
PIC 9(6).
10 KEY-2
PIC 9(4).
10 PART-3
PIC 9(18).
10 KEY-3
PIC 9(5).
You can search this table using the following instructions:
SEARCH ALL TABLE-ENTRY
AT END
PERFORM NOENTRY
WHEN KEY-1 (INDX-1) = VALUE-1 AND
KEY-2 (INDX-1) = VALUE-2 AND
KEY-3 (INDX-1) = VALUE-3
MOVE PART-1 (INDX-1) TO OUTPUT-AREA
END-SEARCH
If an entry is found in which the three keys are equal to the given values (VALUE-1,
VALUE-2, and VALUE-3), PART-1 of that entry will be moved to OUTPUT-AREA. If
matching keys are not found in any of the entries in TABLE-A, the NOENTRY routine
is performed.
Processing table items using intrinsic functions
You can use an intrinsic function to process an alphanumeric or numeric table
item. However, the data description of the table item must be compatible with the
argument requirements for the function.
Use a subscript or index to reference an individual data item as a function
argument. For example, assuming Table-One is a 3x3 array of numeric items, you
can find the square root of the middle element with this statement:
Compute X = Function Sqrt(Table-One(2,2))
You might often need to process the data in tables iteratively. For intrinsic
functions that accept multiple arguments, you can use the ALL subscript to
reference all the items in the table or a single dimension of the table. The iteration
is handled automatically, making your code shorter and simpler.
You can mix scalars and array arguments for functions that accept multiple
arguments:
Compute Table-Median = Function Median(Arg1 Table-One(ALL))
“Example: intrinsic functions” on page 68
RELATED TASKS
“Using intrinsic functions (built-in functions)” on page 31
RELATED REFERENCES
Intrinsic functions (IBM COBOL Language Reference)
Chapter 4. Handling tables
67
Example: intrinsic functions
This example sums a cross-section of Table-Two:
Compute Table-Sum = FUNCTION SUM (Table-Two(ALL, 3, ALL))
Assuming that Table-Two is a 2x3x2 array, the statement above causes the
following elements to be summed:
Table-Two(1,3,1)
Table-Two(1,3,2)
Table-Two(2,3,1)
Table-Two(2,3,2)
This example computes values for all employees.
01
Employee-Table.
05 Emp-Count
05 Emp-Record
Pic s9(4) usage binary.
Occurs 1 to 500 times
depending on Emp-Count.
10 Emp-Name
Pic x(20).
10 Emp-Idme
Pic 9(9).
10 Emp-Salary Pic 9(7)v99.
. . .
Procedure Division.
Compute Max-Salary = Function Max(Emp-Salary(ALL))
Compute I = Function Ord-Max(Emp-Salary(ALL))
Compute Avg-Salary = Function Mean(Emp-Salary(ALL))
Compute Salary-Range = Function Range(Emp-Salary(ALL))
Compute Total-Payroll = Function Sum(Emp-Salary(ALL))
68
Programming Guide
Chapter 5. Selecting and repeating program actions
Use COBOL control language to choose program actions based on the outcome of
logical tests, to iterate over selected parts of your program and data, and to
identify statements to be performed as a group. These controls include:
v
v
v
v
IF statement
EVALUATE statement
Switches and flags
PERFORM statement
RELATED TASKS
“Selecting program actions”
“Repeating program actions” on page 76
Selecting program actions
You can provide for different program actions depending on the tested value of
one or more data items.
The IF and EVALUATE statements in COBOL test one or more data items by means
of a conditional expression.
RELATED TASKS
“Coding a choice of actions”
“Coding conditional expressions” on page 73
RELATED REFERENCES
IF statement (IBM COBOL Language Reference)
EVALUATE statement (IBM COBOL Language Reference)
Coding a choice of actions
Use IF . . . ELSE to code a choice between two processing actions. (The word
THEN is optional in a COBOL program.)
IF condition-p
statement-1
ELSE
statement-2
END-IF
When one of the processing choices is no action, code the IF statement with or
without ELSE. Because the ELSE clause is optional, you can code the following:
IF condition-q
statement-1
END-IF
This coding is suitable for simple programming cases. For complex logic, you
probably need to use the ELSE clause. For example, suppose you have nested IF
statements with an action for only one of the processing choices; you could use the
ELSE clause and code the null branch of the IF statement with the CONTINUE
statement:
© Copyright IBM Corp. 1991, 2000
69
IF condition-q
statement-1
ELSE
CONTINUE
END-IF
Use the EVALUATE statement to code a choice among three or more possible
conditions instead of just two. The EVALUATE statement is an expanded form of the
IF statement that allows you to avoid nesting IF statements for such coding, a
common source of logic errors and debugging problems.
With the EVALUATE statement, you can test any number of conditions in a single
statement and have separate actions for each. In structured programming terms,
this is a case structure. It can also be thought of as a decision table.
“Example: EVALUATE using THRU phrase” on page 72
“Example: EVALUATE using multiple WHEN statements” on page 72
“Example: EVALUATE testing several conditions” on page 72
RELATED TASKS
“Coding conditional expressions” on page 73
“Using the EVALUATE statement” on page 71
“Using nested IF statements”
Using nested IF statements
When an IF statement has another IF statement as one of its possible processing
branches, these IF statements are said to be nested. Theoretically, there is no limit
to the depth of nested IF statements. However, when the program has to test a
variable for more than two values, EVALUATE is the better choice.
Use nested IF statements sparingly. The logic can be difficult to follow, although
explicit scope terminators and proper indentation help.
The following pseudocode depicts a nested IF statement:
IF condition-p
IF condition-q
statement-1
ELSE
statement-2
END-IF
statement-3
ELSE
statement-4
END-IF
Here an IF is nested, along with a sequential structure, in one branch of another
IF. In a structure like this, the END-IF closing the inner nested IF is very important.
Use END-IF instead of a period, because a period would end the outer IF structure
as well.
The following figure shows the logic structure for nested IF statements.
70
Programming Guide
RELATED TASKS
“Coding a choice of actions” on page 69
RELATED REFERENCES
Explicit scope terminators (IBM COBOL Language Reference)
Using the EVALUATE statement
Use the EVALUATE statement to test several conditions and design a different action
for each, a construct often known as a case structure. The expressions to be tested
are called selection subjects; the answer selected is called a selection object. You can
code multiple subjects and multiple objects in the same structure.
You can code the EVALUATE statement to handle the case where multiple conditions
lead to the same processing by using the THRU phrase and by using multiple WHEN
statements.
When evaluated, each pair of selection subjects and selection objects must belong
to the same class (numeric, character, CONDITION TRUE or FALSE).
The execution of the EVALUATE statement ends when:
v The statements associated with the selected WHEN phrase are performed.
v The statements associated with the WHEN OTHER phrase are performed.
v No WHEN conditions are satisfied.
WHEN phrases are tested in the order they are coded. Therefore, you should order
these phrases for the best performance: code first the WHEN phrase containing
selection objects most likely to be satisfied, then the next most likely, and so on. An
exception is the WHEN OTHER phrase, which must come last.
RELATED TASKS
“Coding a choice of actions” on page 69
Chapter 5. Selecting and repeating program actions
71
Example: EVALUATE using THRU phrase: This example shows how you can use
the THRU phrase to easily code several conditions in a range of values that lead to
the same processing action. In this example, CARPOOL-SIZE is the selection subject;
1, 2, and 3 THRU 6 are the selection objects.
EVALUATE CARPOOL-SIZE
WHEN 1
MOVE “SINGLE” TO PRINT-CARPOOL-STATUS
WHEN 2
MOVE “COUPLE” TO PRINT-CARPOOL-STATUS
WHEN 3 THRU 6
MOVE “SMALL GROUP” TO PRINT-CARPOOL STATUS
WHEN OTHER
MOVE “BIG GROUP” TO PRINT-CARPOOL STATUS
END-EVALUATE
The following nested IF statements represent the same logic:
IF CARPOOL-SIZE = 1 THEN
MOVE “SINGLE” TO PRINT-CARPOOL-STATUS
ELSE
IF CARPOOL-SIZE = 2 THEN
MOVE “COUPLE” TO PRINT-CARPOOL-STATUS
ELSE
IF CARPOOL-SIZE >= 3 and CARPOOL-SIZE <= 6 THEN
MOVE “SMALL GROUP” TO PRINT-CARPOOL-STATUS
ELSE
MOVE “BIG GROUP” TO PRINT-CARPOOL-STATUS
END-IF
END-IF
END-IF
Example: EVALUATE using multiple WHEN statements: You can use multiple
WHEN statements when several conditions lead to the same processing action. This
gives you more flexibility than using the THRU phrase, because the conditions do
not have to evaluate to values that fall in a range or evaluate to alphanumeric
values.
EVALUATE MARITAL-CODE
WHEN “M”
ADD 2 TO PEOPLE-COUNT
WHEN “S”
WHEN “D”
WHEN “W”
ADD 1 TO PEOPLE-COUNT
END-EVALUATE
The following nested IF statements represent the same logic:
IF MARITAL-CODE = “M” THEN
ADD 2 TO PEOPLE-COUNT
ELSE
IF MARITAL-CODE = “S” OR
MARITAL-CODE = “D” OR
MARITAL-CODE = “W” THEN
ADD 1 TO PEOPLE-COUNT
END-IF
END-IF
Example: EVALUATE testing several conditions: In this example both selection
subjects in a WHEN phrase must satisfy the TRUE, TRUE condition before the phrase is
performed. If both subjects do not evaluate to TRUE, the next WHEN phrase is
processed.
Identification Division.
Program-ID. MiniEval.
Environment Division.
72
Programming Guide
Configuration Section.
Source-Computer. IBM-390.
Data Division.
Working-Storage Section.
01
Age
Pic 999.
01
Sex
Pic X.
01
Description
Pic X(15).
01
A
Pic 999.
01
B
Pic 9999.
01
C
Pic 9999.
01
D
Pic 9999.
01
E
Pic 99999.
01
F
Pic 999999.
Procedure Division.
PN01.
Evaluate True Also True
When Age < 13 Also Sex = “M”
Move “Young Boy” To Description
When Age < 13 Also Sex = “F”
Move “Young Girl” To Description
When Age > 12 And Age < 20 Also Sex = “M”
Move “Teenage Boy” To Description
When Age > 12 And Age < 20 Also Sex = “F”
Move “Teenage Girl” To Description
When Age > 19 Also Sex = “M”
Move “Adult Man” To Description
When Age > 19 Also Sex = “F”
Move “Adult Woman” To Description
When Other
Move “Invalid Data” To Description
End-Evaluate
Evaluate True Also True
When A + B < 10 Also C = 10
Move “Case 1” To Description
When A + B > 50 Also C = ( D + E ) / F
Move “Case 2” To Description
When Other
Move “Case Other” To Description
End-Evaluate
Stop Run.
Coding conditional expressions
Using the IF and EVALUATE statements, you can code program actions that will be
performed depending on the truth value of a conditional expression. COBOL lets
you specify any of these conditions:
v Numeric condition
v Nonnumeric condition
v Class of a field
v Switches and flags that you define
v Sign condition
v Status of UPSI switch
RELATED CONCEPTS
“Switches and flags” on page 74
RELATED TASKS
“Defining switches and flags” on page 74
“Resetting switches and flags” on page 75
“Checking for incompatible data (numeric class test)” on page 42
Chapter 5. Selecting and repeating program actions
73
RELATED REFERENCES
Rules for condition-name values (IBM COBOL Language Reference)
Switch-status condition (IBM COBOL Language Reference)
Sign condition (IBM COBOL Language Reference)
Comparing numeric and nonnumeric operands (IBM COBOL Language Reference)
Combined conditions (IBM COBOL Language Reference)
Class condition (IBM COBOL Language Reference)
Switches and flags
Some program decisions are based on whether the value of a data item is true or
false, on or off, yes or no. Control these two-way decisions with level-88 items
with meaningful names (condition-names) to act as switches.
Other program decisions depend on the particular value or range of values of a
data item. When you use condition-names to give more than just on or off values
to a field, the field is generally referred to as a flag.
Flags and switches make your code easier to change. If you need to change the
values for a condition, you have to change only the value of that level-88
condition-name.
For example, suppose a program uses a condition-name to test a field for a given
salary range. If the program must be changed to check for a different salary range,
you need to change only the value of the condition-name in the DATA DIVISION.
You do not need to make changes in the PROCEDURE DIVISION.
RELATED TASKS
“Defining switches and flags”
“Resetting switches and flags” on page 75
Defining switches and flags
In the DATA DIVISION, define level-88 items to give meaningful names (condition
names) to values that will act as switches or flags.
To test for more than two values, as flags, assign more than one condition name to
a field by using multiple level-88 items.
The reader can easily follow your code if you choose meaningful condition names
and if the values assigned have some association with logical values.
“Example: switches”
“Example: flags” on page 75
Example: switches
To test for an end-of-file condition for an input file named Transaction-File, you
could use the following data definitions:
WORKING-STORAGE Section.
01 Switches.
05 Transaction-EOF-Switch Pic X value space.
88 Transaction-EOF value “y”.
The level-88 description says a condition named Transaction-EOF is turned on
when Transaction-EOF-Switch has value “y”. Referencing Transaction-EOF in your
PROCEDURE DIVISION expresses the same condition as testing for
Transaction-EOF-Switch = “y”. For example, the following statement causes the
report to be printed only if your program has read to the end of the
Transaction-File and if the Transaction-EOF-Switch has been set to “y”:
74
Programming Guide
If Transaction-EOF Then
Perform Print-Report-Summary-Lines
Example: flags
Consider a program that updates a master file. The updates are read from a
transaction file. The transaction file’s records contain a field for the function to be
performed: add, change, or delete. In the record description of the input file code a
field for the function code using level-88 items:
01
Transaction-Input Record
05 Transaction-Type
88 Add-Transaction
88 Change-Transaction
88 Delete-Transaction
Pic X.
Value “A”.
Value “C”.
Value “D”.
The code in the PROCEDURE DIVISION for testing these condition-names might look
like this:
Evaluate True
When Add-Transaction
Perform Add-Master-Record-Paragraph
When Change-Transaction
Perform Update-Exisitng-Record-Paragraph
When Delete-Transaction
Perform Delete-Master-Record-Paragraph
End-Evaluate
Resetting switches and flags
Throughout your program, you might need to reset switches or change flags back
to the original values they have in their data descriptions. To do so, use either a
SET statement or define your own data item to use.
When you use the SET condition-name TO TRUE statement, the switch or flag is set
back to the original value that was assigned in its data description.
For a level-88 item with multiple values, SET condition-name TO TRUE assigns the
first value (here, A):
88 Record-is-Active Value “A” “O” “S”
Using the SET statement and meaningful condition-names makes it easy for the
reader to follow your code.
“Example: set switch on”
“Example: set switch off” on page 76
Example: set switch on
The SET statement in the following example does the same thing as Move “y” to
Transaction-EOF-Switch:
01
Switches
05 Transaction-EOF-Switch
Pic X
88 Transaction-EOF
. . .
Procedure Division.
000-Do-Main-Logic.
Perform 100-Initialize-Paragraph
Read Update-Transaction-File
At End Set Transaction-EOF to True
End-Read
Value space.
Value “y”.
The following example shows how to assign a value for a field in an output record
based on the transaction code of an input record.
Chapter 5. Selecting and repeating program actions
75
01
Input-Record.
05 Transaction-Type
. . .
01 Data-Record-Out.
05 Data-Record-Type
88 Record-Is-Active
88 Record-Is-Suspended
88 Record-Is-Deleted
05 Key-Field
. . .
Pic X(9).
Pic X.
Value “A”.
Value “S”.
Value “D”.
Pic X(5).
Procedure Division.
. . .
Evaluate Transaction-Type of Input-Record
When “ACTIVE”
Set Record-Is-Active to TRUE
When “SUSPENDED”
Set Record-Is-Suspended to TRUE
When “DELETED”
Set Record-Is-Deleted to TRUE
End-Evaluate
Example: set switch off
You could use a data item called SWITCH-OFF throughout your program to set
on/off switches to off, as in the following code:
01
Switches
05 Transaction-EOF-Switch
Pic X Value space.
88 Transaction-EOF
Value “y”.
01 SWITCH-OFF
Pic X Value “n”.
. . .
Procedure Division.
. . .
Move SWITCH-OFF to Transaction-EOF-Switch
This code resets the switch to indicate that the end of the file has not been reached.
Repeating program actions
Use the PERFORM statement to run a paragraph and then implicitly return control to
the next executable statement. In effect, the PERFORM statement is a way of coding a
closed subroutine that you can enter from many different parts of the program.
Use the PERFORM statement to loop (repeat the same code) a set number of times or
to loop based on the outcome of a decision.
PERFORM statements can be inline or out-of-line.
RELATED TASKS
“Choosing inline or out-of-line PERFORM”
“Coding a loop” on page 77
“Coding a loop through a table” on page 78
“Executing multiple paragraphs or sections” on page 79
RELATED REFERENCES
PERFORM statement (IBM COBOL Language Reference)
Choosing inline or out-of-line PERFORM
The inline PERFORM statement has the same general rules as the out-of-line PERFORM
statement except for one area: statements within the inline PERFORM statement are
executed rather than those within the range of the procedure named in the
out-of-line PERFORM statement.
76
Programming Guide
To determine whether to code an inline or out-of-line PERFORM statement, consider
the following questions:
v Is the PERFORM statement used from several places?
Use out-of-line PERFORM when you use the same piece of code from several
places in your program.
v Which placement of the statement will be easier to read?
Use an out-of-line PERFORM if the logical flow of the program will be less clear
because the PERFORM extends over several screens. If, however, the PERFORM
paragraph is short, an inline PERFORM can save the trouble of skipping around in
the code.
v What are the efficiency tradeoffs?
Avoid the overhead of branching around an out-of-line PERFORM if performance is
an issue. But remember, even out-of-line PERFORM coding can improve code
optimization, so efficiency gains should not be overemphasized.
In the 1974 COBOL standard, the PERFORM statement is out-of-line and thus requires
an explicit branch to a separate paragraph and has an implicit return. If the
performed paragraph is in the subsequent sequential flow of your program, it is
also executed in that flow of the logic. To avoid this additional execution, you
must place the paragraph outside the normal sequential flow (for example, after
the GOBACK) or code a branch around it.
The subject of an inline PERFORM is an imperative statement. Therefore, you must
code statements (other than imperative statements within an inline PERFORM) with
explicit scope terminators. Each paragraph performs one logical function.
“Example: inline PERFORM statement”
Example: inline PERFORM statement
This example shows the structure of an inline PERFORM statement with the required
scope terminators and the required END-PERFORM statement.
Perform 100-Initialize-Paragraph
* The following is an inline PERFORM
Perform Until Transaction-EOF
Read Update-Transaction-File Into WS-Transaction-Record
At End
Set Transaction-EOF To True
Not At End
Perform 200-Edit-Update-Transaction
If No-Errors
Perform 300-Update-Commuter-Record
Else
Perform 400-Print-Transaction-Errors
* End-If is a required scope terminator
End-If
Perform 410-Re-Initialize-Fields
* End-Read is a required scope terminator
End-Read
End-Perform
Coding a loop
Use the PERFORM . . . TIMES statement to execute a paragraph a certain number of
times:
PERFORM 010-PROCESS-ONE-MONTH 12 TIMES
INSPECT . . .
Chapter 5. Selecting and repeating program actions
77
When control reaches the PERFORM statement, the code for the paragraph
010-PROCESS-ONE-MONTH is executed 12 times before control is transferred to the
INSPECT statement.
Use the PERFORM . . . UNTIL statement to execute a paragraph until a condition
you choose is satisfied. You can use either of the following forms:
PERFORM . . . WITH TEST AFTER . . . UNTIL . . .
PERFORM . . . [WITH TEST BEFORE] . . . UNTIL . . .
Use the PERFORM . . . WITH TEST AFTER . . . UNTIL if you want to execute the
paragraph at least once and then test before any subsequent execution. This
statement is equivalent to the do-until structure:
In the following example, the implicit WITH TEST BEFORE phrase provides a
do-while structure:
PERFORM 010-PROCESS-ONE-MONTH
UNTIL MONTH GREATER THAN 12
INSPECT . . .
When control reaches the PERFORM statement, the condition (MONTH EQUAL DECEMBER)
is tested. If the condition is satisfied, control is transferred to the INSPECT
statement. If the condition is not satisfied, 010-PROCESS-ONE-MONTH is executed, and
the condition is tested again. This cycle continues until the condition tests as true.
(To make your program easier to read, you might want to code the WITH TEST
BEFORE clause.)
Coding a loop through a table
You can use PERFORM . . . VARYING to initialize a table. In this form of the PERFORM
statement, a variable is increased or decreased and tested until a condition is
satisfied.
Thus you use the PERFORM statement to control a loop through a table. You can use
either of the following forms:
PERFORM . . . WITH TEST AFTER . . . VARYING . . . UNTIL . . .
PERFORM . . . [WITH TEST BEFORE] . . . VARYING . . . UNTIL .
The following code shows an example of looping through a table to check for
invalid data:
78
Programming Guide
PERFORM TEST AFTER VARYING WS-DATA-IX
FROM 1 BY 1
UNTIL WS-DATA-IX = 12
IF WS-DATA (WS-DATA-IX) EQUALS SPACES
SET SERIOUS-ERROR TO TRUE
DISPLAY ELEMENT-NUM-MSG5
END-IF
END-PERFORM
INSPECT . . .
In the code above, when control reaches the PERFORM statement, WS-DATA-IX is set
equal to 1 and the PERFORM statement is executed. Then the condition
(WS-DATA-IX = 12) is tested. If the condition is true, control drops through to the
INSPECT statement. If it is false, WS-DATA-IX is increased by 1, the PERFORM statement
is executed, and the condition is tested again. This cycle of execution and testing
continues until WS-DATA-IX is equal to 12.
In terms of the application, this loop controls input-checking for the 12 fields of
item WS-DATA. Empty fields are not allowed, and this section of code loops through
and issues error messages as appropriate.
Executing multiple paragraphs or sections
In structured programming, the paragraph you execute is usually a single
paragraph. However, you can execute a group of paragraphs, a single section, or a
group of sections using the PERFORM . . . THRU statement.
When you use PERFORM . . . THRU use a paragraph-EXIT statement to clearly
indicate the end point for the series of paragraphs.
Intrinsic functions can make the coding of the iterative processing of tables simpler
and easier.
RELATED TASKS
“Processing table items using intrinsic functions” on page 67
Chapter 5. Selecting and repeating program actions
79
80
Programming Guide
Chapter 6. Handling strings
COBOL provides language constructs for performing the following operations
associated with string data items:
v Joining and splitting data items
v Manipulating null-terminated strings, such as counting or moving characters
v Referring to substrings by their ordinal position and, if needed, length
v Tallying and replacing data items, such as counting the number of times a
specific character occurs in a data item
v Converting data items, such as changing to uppercase or lowercase
v Evaluating data items, such as determining the length of a data item
RELATED TASKS
“Joining data items (STRING)”
“Splitting data items (UNSTRING)” on page 83
“Manipulating null-terminated strings” on page 85
“Referring to substrings of data items” on page 86
“Tallying and replacing data items (INSPECT)” on page 89
“Converting double-byte character set (DBCS) data” on page 90
“Converting data items (intrinsic functions)” on page 94
“Evaluating data items (intrinsic functions)” on page 96
Joining data items (STRING)
Use the STRING statement to join all or parts of several data items into one data
item. One STRING statement can save you several MOVE statements.
The STRING statement transfers data items into the receiving item in the order you
indicate. In the STRING statement you can also specify the following:
v Delimiters that cause a sending field to be ended and another to be started
v Actions to be taken when the single receiving field is filled before all of the
sending characters have been processed (ON OVERFLOW condition)
“Example: STRING statement”
RELATED TASKS
“Handling errors in joining and splitting strings” on page 190
RELATED REFERENCES
STRING statement (IBM COBOL Language Reference)
Example: STRING statement
In the following example, the STRING statement selects and formats information
from record RCD-01 as an output line: line number, customer name and address,
invoice number, next billing date, and balance due. The balance is truncated to the
dollar figure shown.
In the FILE SECTION, the following record is defined:
01
RCD-01.
05 CUST-INFO.
10 CUST-NAME
10 CUST-ADDR
© Copyright IBM Corp. 1991, 2000
PIC X(15).
PIC X(35).
81
05
BILL-INFO.
10 INV-NO
10 INV-AMT
10 AMT-PAID
10 DATE-PAID
10 BAL-DUE
10 DATE-DUE
PIC
PIC
PIC
PIC
PIC
PIC
X(6).
$$,$$$.99.
$$,$$$.99.
X(8).
$$,$$$.99.
X(8).
In the WORKING-STORAGE SECTION, the following fields are defined:
77
77
77
77
RPT-LINE
LINE-POS
LINE-NO
DEC-POINT
PIC
PIC
PIC
PIC
X(120).
S9(3).
9(5) VALUE 1.
X VALUE “.”.
The record RCD-01 contains the following information (the symbol º indicates a
blank space):
J.B.ºSMITHººººº
444ºSPRINGºST.,ºCHICAGO,ºILL.ºººººº
A14275
$4,736.85
$2,400.00
09/22/76
$2,336.85
10/22/76
In the PROCEDURE DIVISION, the programmer initializes RPT-LINE to SPACES and sets
LINE-POS, the data item to be used as the POINTER field, to 4. (By coding the
POINTER phrase of the STRING statement, you can use the explicit pointer field to
control placement of data in the receiving field.) Then, the programmer codes this
STRING statement:
STRING
LINE-NO SPACE CUST-INFO INV-NO SPACE DATE-DUE SPACE
DELIMITED BY SIZE
BAL-DUE
DELIMITED BY DEC-POINT
INTO RPT-LINE
WITH POINTER LINE-POS.
STRING program results
When the STRING statement is performed, items are moved into RPT-LINE as shown
in the table below.
Item
Positions
LINE-NO
4-8
Space
9
CUST-INFO
10 - 59
INV-NO
60 - 65
Space
66
DATE-DUE
67 - 74
Space
75
Portion of BAL-DUE that precedes the decimal point
76 - 81
After the STRING statement is performed, the value of LINE-POS is 82, and RPT-LINE
appears as shown below.
82
Programming Guide
Splitting data items (UNSTRING)
Use the UNSTRING statement to split one sending field into several receiving fields.
One UNSTRING statement can save you several MOVE statements.
In the UNSTRING statement you can specify the following:
v Delimiters that, when encountered in the sending field, cause the current
receiving field to stop receiving and the next to begin receiving
v Fields that store the number of characters placed in receiving fields
v A field that stores a count of the total number of characters transferred
v Special actions to take if all the receiving fields are filled before the end of the
sending item is reached
CMPR2 consideration: The UNSTRING statement works differently when the CMPR2
compiler option is in effect. For VS COBOL II Release 2 compatibility and
migration details, see the references indicated below.
“Example: UNSTRING statement”
RELATED TASKS
“Handling errors in joining and splitting strings” on page 190
COBOL for OS/390 & VM Compiler and Run-Time Migration Guide
RELATED REFERENCES
“CMPR2” on page 264
UNSTRING statement (IBM COBOL Language Reference)
Example: UNSTRING statement
In the following example, selected information is taken from the input record.
Some is organized for printing and some for further processing.
In the FILE SECTION, the following records are defined:
*
Record to be acted on by the UNSTRING statement:
01 INV-RCD.
05 CONTROL-CHARS
PIC XX.
05 ITEM-INDENT
PIC X(20).
05 FILLER
PIC X.
05 INV-CODE
PIC X(10).
05 FILLER
PIC X.
05 NO-UNITS
PIC 9(6).
05 FILLER
PIC X.
05 PRICE-PER-M
PIC 99999.
05 FILLER
PIC X.
05 RTL-AMT
PIC 9(6).99.
*
*
UNSTRING receiving field for printed output:
01 DISPLAY-REC.
05 INV-NO
PIC X(6).
05 FILLER
PIC X VALUE SPACE.
05 ITEM-NAME
PIC X(20).
Chapter 6. Handling strings
83
*
*
05
05
FILLER
DISPLAY-DOLS
PIC X VALUE SPACE.
PIC 9(6).
UNSTRING receiving field for further processing:
01 WORK-REC.
05 M-UNITS
PIC 9(6).
05 FIELD-A
PIC 9(6).
05 WK-PRICE REDEFINES FIELD-A
PIC 9999V99.
05 INV-CLASS
PIC X(3).
*
*
UNSTRING statement control fields
77 DBY-1
77 CTR-1
77 CTR-2
77 CTR-3
77 CTR-4
77 DLTR-1
77 DLTR-2
77 CHAR-CT
77 FLDS-FILLED
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
X.
S9(3).
S9(3).
S9(3).
S9(3).
X.
X.
S9(3).
S9(3).
In the PROCEDURE DIVISION, the programmer writes the following UNSTRING
statement:
* Move subfields of INV-RCD to the subfields of DISPLAY-REC
* and WORK-REC:
UNSTRING INV-RCD
DELIMITED BY ALL SPACES OR “/” OR DBY-1
INTO ITEM-NAME COUNT IN CTR-1
INV-NO DELIMITER IN DLTR-1 COUNT IN CTR-2
INV-CLASS
M-UNITS COUNT IN CTR-3
FIELD-A
DISPLAY-DOLS DELIMITER IN DLTR-2 COUNT IN CTR-4
WITH POINTER CHAR-CT
TALLYING IN FLDS-FILLED
ON OVERFLOW GO TO UNSTRING-COMPLETE.
Before issuing the UNSTRING statement, the programmer places the value 3 in
CHAR-CT (the POINTER field) to avoid working with the two control characters in
INV-RCD. A period (.) is placed in DBY-1 for use as a delimiter, and the value 0
(zero) is placed in FLDS-FILLED (the TALLYING field). The data is then read into
INV-RCD, as shown below.
UNSTRING program results
When the UNSTRING statement is performed, the following steps take place:
1. Positions 3 through 18 (FOUR-PENNY-NAILS) of INV-RCD are placed in ITEM-NAME,
left-justified in the area, and the four unused character positions are padded
with spaces. The value 16 is placed in CTR-1.
2. Because ALL SPACES is coded as a delimiter, the five contiguous SPACE characters
in positions 19 through 23 are considered to be one occurrence of the delimiter.
3. Positions 24 through 29 (707890) are placed in INV-NO. The delimiter character,
/, is placed in DLTR-1, and the value 6 is placed in CTR-2.
84
Programming Guide
4. Positions 31 through 33 are placed in INV-CLASS. The delimiter is a SPACE, but
because no field has been defined as a receiving area for delimiters, the SPACE
in position 34 is bypassed.
5. Positions 35 through 40 (475120) are examined and placed in M-UNITS. The
value 6 is placed in CTR-3. The delimiter is a SPACE, but because no field has
been defined as a receiving area for delimiters, the SPACE in position 41 is
bypassed.
6. Positions 42 through 46 (00122) are placed in FIELD-A and right-justified in the
area. The high-order digit position is filled with a 0 (zero). The delimiter is a
SPACE, but because no field has been defined as a receiving area for delimiters,
the SPACE in position 47 is bypassed.
7. Positions 48 through 53 (000379) are placed in DISPLAY-DOLS. The period (.)
delimiter character in DBY-1 is placed in DLTR-2, and the value 6 is placed in
CTR-4.
8. Because all receiving fields have been acted on and two characters of data in
INV-RCD have not been examined, the ON OVERFLOW exit is taken, and execution
of the UNSTRING statement is completed.
After the UNSTRING statement is performed, the fields contain the values shown
below.
Field
Value
DISPLAY-REC
707890 FOUR-PENNY-NAILS
WORK-REC
475120000122BBA
CHAR-CT (the POINTER field)
55
FLDS-FILLED (the TALLYING field)
6
000379
Manipulating null-terminated strings
You can construct and manipulate null-terminated strings (passed to or from a C
program, for example), by various mechanisms:
v Use null-terminated literal constants (Z“. . . ”).
v Use an INSPECT statement to count the number of characters in a null-terminated
string:
MOVE 0 TO char-count
INSPECT source-field TALLYING char-count
FOR CHARACTERS
BEFORE X“00”
v Use an UNSTRING statement to move characters in a null-terminated string to a
target field, and get the character count:
WORKING-STORAGE SECTION.
01 source-field
PIC X(1001).
01 char-count
COMP-5 PIC 9(4).
01 target-area.
02 individual-char OCCURS 1 TO 1000 TIMES DEPENDING ON char-count
PIC X.
. . .
PROCEDURE DIVISION.
. . .
UNSTRING source-field DELIMITED BY X“00”
INTO target-area
COUNT IN char-count
Chapter 6. Handling strings
85
ON OVERFLOW
DISPLAY “source not null terminated or target too short”
. . .
END-UNSTRING
v Use a SEARCH statement to locate trailing null or space characters. Define the
string being examined as a table of single characters.
v Check each character in a field in a loop (PERFORM). You can examine each
character in the field by using a reference modifier such as source-field (I:1).
“Example: null-terminated strings”
RELATED REFERENCES
Nonnumeric literals (IBM COBOL Language Reference)
Example: null-terminated strings
The following example shows several ways you can manipulate null-terminated
strings:
01 L pic X(20) value z'ab'.
01 M pic X(20) value z'cd'.
01 N pic X(20).
01 N-Length pic 99 value zero.
01 Y pic X(13) value 'Hello, World!'.
. . .
* Display null-terminated string
Inspect N tallying N-length
for characters before initial x'00'
Display 'N: ' N(1:N-Length) ' Length: ' N-Length
. . .
* Move null-terminated string to alphanumeric, strip null
Unstring N delimited by X'00' into X
. . .
* Create null-terminated string
String Y
delimited by size
X'00' delimited by size
into N.
. . .
* Concatenate two null-terminated strings to produce another
String L
delimited by x'00'
M
delimited by x'00'
X'00' delimited by size
into N.
Referring to substrings of data items
Refer to a substring of a character-string data item (including EBCDIC data items)
with reference modifiers. Intrinsic functions that return character-string values are
also considered alphanumeric data items, and can include a reference modifier.
The following example shows how to use a reference modifier to refer to a
substring of a data item:
Move Customer-Record(1:20) to Orig-Customer-Name
As this example shows, in parentheses immediately following the data item you
code two values separated by a colon:
v Ordinal position (from the left) of the character you want the substring to start
with
v Length of the desired substring
86
Programming Guide
The length is optional. If you omit the length, the substring extends to the end of
the item. Omit the length when possible as a simpler and less error-prone coding
technique.
You can code either of the two values as a variable or as an arithmetic expression.
Because numeric function identifiers can be used anywhere arithmetic expressions
are allowed, you can use them in the reference modifier as the leftmost character
position or as the length.
You can also refer to substrings of table entries, including variable-length entries.
Both numbers in the reference modifier must have a value of at least 1. Their sum
should not exceed the total length of the data item by more than 1 so that you do
not reference beyond the end of the desired substring.
If the leftmost character position or the length value is a fixed-point noninteger,
truncation occurs to create an integer. If either is a floating-point noninteger,
rounding occurs to create an integer.
The following options detect out-of-range reference modifiers, and flag violations
with a run-time message:
v SSRANGE compiler option
v CHECK run-time option
RELATED CONCEPTS
“Reference modifiers”
RELATED TASKS
“Referring to an item in a table” on page 55
RELATED REFERENCES
“SSRANGE” on page 294
Reference modification (IBM COBOL Language Reference)
Function definitions (IBM COBOL Language Reference)
Reference modifiers
Assume that you want to retrieve the current time from the system and display its
value in an expanded format. You can retrieve the current time with the ACCEPT
statement, which returns the hours, minutes, seconds, and hundredths of seconds
in this format:
HHMMSSss
However, you might prefer to view the current time in this format:
HH:MM:SS
Without reference modifiers, you would have to define data items for both formats.
You would also have to write code to convert from one format to the other.
With reference modifiers, you do not need to provide names for the subfields that
describe the TIME elements. The only data definition you need is for the time as
returned by the system. For example:
01
REFMOD-TIME-ITEM
PIC X(8).
The following code retrieves and expands the time value:
Chapter 6. Handling strings
87
*
*
*
*
*
*
ACCEPT REFMOD-TIME-ITEM FROM TIME.
DISPLAY “CURRENT TIME IS: ”
Retrieve the portion of the time value that corresponds to
the number of hours:
REFMOD-TIME-ITEM (1:2)
“:”
Retrieve the portion of the time value that corresponds to
the number of minutes:
REFMOD-TIME-ITEM (3:2)
“:”
Retrieve the portion of the time value that corresponds to
the number of seconds:
REFMOD-TIME-ITEM (5:2)
“Example: arithmetic expressions as reference modifiers”
“Example: intrinsic functions as reference modifiers”
RELATED TASKS
“Referring to substrings of data items” on page 86
Example: arithmetic expressions as reference modifiers
Suppose that a field contains some right-justified characters, and you want to
move the characters to another field where they will be left-justified. You can do
that using reference modifiers and an INSPECT statement.
Suppose the program has the following data:
01
01
01
LEFTY
RIGHTY
I
PIC X(30).
PIC X(30) JUSTIFIED RIGHT.
PIC 9(9) USAGE BINARY.
The program counts the number of leading spaces and, using arithmetic
expressions in a reference modifier, moves the right-justified characters into
another field, justified to the left:
MOVE SPACES TO LEFTY
MOVE ZERO TO I
INSPECT RIGHTY
TALLYING I FOR LEADING SPACE.
IF I IS LESS THAN LENGTH OF RIGHTY THEN
MOVE RIGHTY ( I + 1 : LENGTH OF RIGHTY - I ) TO LEFTY
END-IF
The MOVE statement transfers characters from RIGHTY, beginning at the position
computed as I + 1 for a length that is computed as LENGTH OF RIGHTY - I, into the
field LEFTY.
Example: intrinsic functions as reference modifiers
The following code fragment causes a substring of Customer-Record to be moved
into the variable WS-name. The substring is determined at run time.
05 WS-name
Pic x(20).
05 Left-posn
Pic 99.
05 I
Pic 99.
. . .
Move Customer-Record(Function Min(Left-posn I):Function Length(WS-name)) to WS-name
If you want to use a noninteger function in a position requiring an integer
function, you can use the INTEGER or INTEGER-PART function to convert the result to
an integer. For example:
Move Customer-Record(Function Integer(Function Sqrt(I)): ) to WS-name
88
Programming Guide
RELATED REFERENCES
INTEGER-PART (IBM COBOL Language Reference)
INTEGER (IBM COBOL Language Reference)
Tallying and replacing data items (INSPECT)
Use the INSPECT statement to do the following:
v Fill selective portions of a data item with a value
v Replace portions of a data item with a corresponding portion of another data
item
v Count the number of times a specific character (zero, space, or asterisk, for
example) occurs in a data item
“Examples: INSPECT statement”
RELATED REFERENCES
INSPECT statement (IBM COBOL Language Reference)
Examples: INSPECT statement
The following examples show some uses of the INSPECT statement.
In the following example, the INSPECT statement is used to examine and replace
characters in data item DATA-2. The number of times a leading 0 occurs in the data
item is accumulated in COUNTR. Every instance of the character A following the first
instance of the character C is replaced by the character 2.
77 COUNTR
PIC 9
VALUE ZERO.
01 DATA-2
PIC X(11).
. . .
INSPECT DATA-2
TALLYING COUNTR FOR LEADING “0”
REPLACING FIRST “A” BY “2” AFTER INITIAL “C”
DATA-2 before
COUNTR after
DATA-2 after
00ACADEMY00
2
00AC2DEMY00
0000ALABAMA
4
0000ALABAMA
CHATHAM0000
0
CH2THAM0000
In the following example, the INSPECT statement is used to examine and replace
characters in data item DATA-3. Every character in the data item preceding the first
instance of a quote (“) is replaced by the character 0.
77 COUNTR
PIC 9
VALUE ZERO.
01 DATA-3
PIC X(8).
. . .
INSPECT DATA-3
REPLACING CHARACTERS BY ZEROS BEFORE INITIAL QUOTE
DATA-3 before
COUNTR after
DATA-3 after
456”ABEL
0
000“ABEL
ANDES”12
0
00000“12
”TWAS BR
0
“TWAS BR
The following example shows the use of INSPECT CONVERTING with AFTER and
BEFORE phrases to examine and replace characters in data item DATA-4. All
Chapter 6. Handling strings
89
characters in the data item following the first instance of the character / but
preceding the first instance of the character ? (if any) are translated from lowercase
to uppercase.
01 DATA-4
PIC X(11).
. . .
INSPECT DATA-4
CONVERTING
”abcdefghijklmnopqrstuvwxyz“ TO
”ABCDEFGHIJKLMNOPQRSTUVWXYZ“
AFTER INITIAL ”/“
BEFORE INITIAL”?“
DATA-4 before
DATA-4 after
a/five/?six
a/FIVE/?six
r/Rexx/RRRr
r/REXX/RRRR
zfour?inspe
zfour?inspe
Converting double-byte character set (DBCS) data
If you use byte-oriented nonnumeric operations (for example, STRING and
UNSTRING) on nonnumeric data items containing double-byte characters, results are
unpredictable. You should instead convert such items to pure DBCS data using the
Language Environment IGZCA2D service routine.
After you have processed the DBCS data, use the Language Environment
IGZCD2A service routine to convert the DBCS data items back to nonnumeric data
items containing double-byte characters.
The DBCS compiler option does not affect the operation of these service routines.
RELATED REFERENCES
“DBCS notation”
“Nonnumeric to DBCS data conversion (IGZCA2D)”
“DBCS to nonnumeric data conversion (IGZCD2A)” on page 92
“DBCS” on page 269
DBCS notation
These symbols describe DBCS items:
Symbols
Meaning
< and >
Shift-out (SO) and Shift-in (SI), respectively
D0, D1, D2, . . ., Dn
Any DBCS character except for double-byte EBCDIC
characters
.A, .B, .C, . . .
Any double-byte EBCDIC character; the period (.)
represents the value X’42’
A single letter, such as A, B, or s
Any single-byte EBCDIC character
Nonnumeric to DBCS data conversion (IGZCA2D)
The Language Environment IGZCA2D service routine converts nonnumeric data
that contains double-byte characters to pure DBCS data.
90
Programming Guide
IGZCA2D syntax
To use the IGZCA2D service routine, pass the following four parameters to the
routine using the CALL statement:
parameter-1
The sending field for the conversion, handled as a nonnumeric data item.
parameter-2
The receiving field for the conversion, handled as a DBCS data item.
You cannot use reference modification with parameter-2.
parameter-3
The number of bytes in parameter-1 to be converted.
It can be the LENGTH OF special register of parameter-1, or a 4-byte USAGE IS
BINARY data item containing the number of bytes of parameter-1 to be
converted. Shift codes count as 1 byte each.
parameter-4
The number of bytes in parameter-2 that will receive the converted data.
It can be the LENGTH OF special register of parameter-2, or a 4-byte USAGE IS
BINARY data item containing the number of bytes of parameter-2 to receive
the converted data.
Usage notes
v You can pass parameter-1, parameter-3, and parameter-4 to the routine BY
REFERENCE or BY CONTENT, but you must pass parameter-2 BY REFERENCE.
v The compiler does not perform syntax checking on these parameters. Ensure that
the parameters are correctly set and passed to the conversion routine using the
CALL statement. Otherwise, results are unpredictable.
v When creating parameter-2 from parameter-1, IGZCA2D makes these changes:
– Removes the shift codes, leaving the DBCS data unchanged
|
– Converts the single-byte EBCDIC data to double-byte EBCDIC characters
– Converts EBCDIC space (X’40’) to DBCS space (X’4040’), instead of X’4240’
v IGZCA2D does not change the contents of parameter-1, parameter-3, or
parameter-4.
v The valid range for the contents of parameter-3 and parameter-4 is 1 to 16,777,215.
“Example: IGZCA2D” on page 92
RELATED REFERENCES
“IGZCA2D return codes”
IGZCA2D return codes
IGZCA2D sets the RETURN-CODE special register to reflect the status of the conversion,
as shown in the table below.
Return code
Explanation
0
Parameter-1 was converted and the results were placed in parameter-2.
2
Parameter-1 was converted and the results were placed in parameter-2.
Parameter-2 was padded on the right with DBCS spaces.
4
Parameter-1 was converted and the results were placed in parameter-2.
The DBCS data placed in parameter-2 was truncated on the right.
Chapter 6. Handling strings
91
Return code
Explanation
6
Parameter-1 was converted and the results were placed in parameter-2.
An EBCDIC character in the range X’00’ to X’3F’ or X’FF’ was
encountered. The valid EBCDIC character has been converted into an
out-of-range DBCS character.
8
Parameter-1 was converted and the results were placed in parameter-2.
An EBCDIC character in the range X’00’ to X’3F’ or X’FF’ was
encountered. The valid EBCDIC character has been converted into an
out-of-range DBCS character.
Parameter-2 was padded on the right with DBCS spaces.
10
Parameter-1 was converted and the results were placed in parameter-2.
An EBCDIC character in the range X’00’ to X’3F’ or X’FF’ was
encountered. The valid EBCDIC character has been converted into an
out-of-range DBCS character.
The DBCS data in parameter-2 was truncated on the right.
12
An odd number of bytes was found between paired shift codes in
parameter-1. No conversion occurred.
13
Unpaired or nested shift codes were found in parameter-1. No conversion
occurred.
14
Parameter-1 and parameter-2 were overlapping. No conversion occurred.
15
The value provided for parameter-3 or parameter-4 was out of range. No
conversion occurred.
16
An odd number of bytes was coded in parameter-4. No conversion
occurred.
Example: IGZCA2D
The following CALL statement converts the nonnumeric data in alpha-item to DBCS
data. The results of the conversion are placed in dbcs-item.
CALL “IGZCA2D” USING BY REFERENCE alpha-item dbcs-item
BY CONTENT LENGTH OF alpha-item LENGTH OF dbcs-item
Suppose the contents of alpha-item and dbcs-item and the lengths before the
conversion are:
alpha-item = AB<D1D2D3>CD
dbcs-item = D4D5D6D7D8D9D0
LENGTH OF alpha-item = 12
LENGTH OF dbcs-item = 14
Then after the conversion, alpha-item and dbcs-item will contain:
alpha-item = AB<D1D2D3>CD
dbcs-item = .A.BD1D2D3.C.D
The content of the RETURN-CODE register is 0.
RELATED REFERENCES
“DBCS notation” on page 90
DBCS to nonnumeric data conversion (IGZCD2A)
The Language Environment IGZCD2A routine converts pure DBCS data to
nonnumeric data that can contain double-byte characters.
92
Programming Guide
IGZCD2A syntax
To use the IGZCD2A service routine, pass the following four parameters to the
routine using the CALL statement:
parameter-1
The sending field for the conversion, handled as a DBCS data item.
parameter-2
The receiving field for the conversion, handled as a nonnumeric data item.
parameter-3
The number of bytes in parameter-1 to be converted.
It can be the LENGTH OF special register of parameter-1, or a 4-byte USAGE IS
BINARY data item containing the number of bytes of parameter-1 to be
converted.
parameter-4
The number of bytes in parameter-2 that will receive the converted data.
It can be the LENGTH OF special register of parameter-2, or a 4-byte USAGE IS
BINARY data item containing the number of bytes of parameter-2 to receive
the converted data. Shift codes count as 1 byte each.
Usage notes
v You can pass parameter-1, parameter-3, and parameter-4 to the routine BY
REFERENCE or BY CONTENT, but you must pass parameter-2 BY REFERENCE.
v The compiler does not perform syntax checking on these parameters. Ensure that
the parameters are correctly set and passed to the conversion routine. Otherwise,
results are unpredictable.
v When creating parameter-2 from parameter-1, IGZCD2A makes these changes:
– Inserts shift codes around DBCS characters that are not double-byte EBCDIC
characters
|
– Converts double-byte EBCDIC characters to single-byte EBCDIC characters
– Converts the DBCS space (X’4040’) to an EBCDIC space (X’40’)
v IGZCD2A does not change the contents of parameter-1, parameter-3, or
parameter-4.
v If the converted data contains double-byte characters, shift codes are counted in
the length of parameter-2.
v The valid range for the contents of parameter-3 and parameter-4 is 1 to 16,777,215.
“Example: IGZCD2A” on page 94
RELATED REFERENCES
“IGZCD2A return codes”
IGZCD2A return codes
IGZCD2A sets the RETURN-CODE special register to reflect the status of the conversion,
as shown in the table below.
Return code
Explanation
0
Parameter-1 was converted and the results were placed in parameter-2.
2
Parameter-1 was converted and the results were placed in parameter-2.
Parameter-2 was padded on the right with EBCDIC spaces.
4
Parameter-1 was converted and the results were placed in parameter-2.
Parameter-2 was truncated on the right.1
Chapter 6. Handling strings
93
Return code
Explanation
14
Parameter-1 and parameter-2 were overlapping. No conversion occurred.
15
The value of parameter-3 or parameter-4 was out of range. No
conversion occurred.
16
An odd number of bytes was coded in parameter-3. No conversion
occurred.
1. If a truncation occurs within the DBCS characters, the truncation is on an even-byte
boundary and a shift-in (SI) is inserted. If necessary, the nonnumeric data is padded
with an EBCDIC space after the shift-in.
Example: IGZCD2A
The following CALL statement converts the DBCS data in dbcs-item to nonnumeric
data with double-byte characters. The results of the conversion are placed in
alpha-item.
CALL “IGZCD2A” USING BY REFERENCE dbcs-item alpha-item
BY CONTENT LENGTH OF dbcs-item LENGTH OF alpha-item
Suppose the contents of dbcs-item and alpha-item and the lengths before the
conversion are:
dbcs-item = .A.BD1D2D3.C.D
alpha-item = ssssssssssss
LENGTH OF dbcs-item = 14
LENGTH OF alpha-item = 12
Then after the conversion, dbcs-item and alpha-item will contain:
dbcs-item = .A.BD1D2D3.C.D
alpha-item = AB<D1D2D3>CD
The content of the RETURN-CODE register is 0.
RELATED REFERENCES
“DBCS notation” on page 90
Converting data items (intrinsic functions)
Intrinsic functions are available to convert character-string data items to:
v Uppercase or lowercase
v Reverse order
v Numbers
You can also use the INSPECT statement to convert characters.
“Examples: INSPECT statement” on page 89
Converting to uppercase or lowercase (UPPER-CASE,
LOWER-CASE)
01 Item-1
Pic x(30) Value “Hello World!”.
01 Item-2
Pic x(30).
. . .
Display Item-1
Display Function Upper-case(Item-1)
Display Function Lower-case(Item-1)
Move Function Upper-case(Item-1) to Item-2
Display Item-2
94
Programming Guide
|
|
The code above displays the following messages on the system logical output
device:
Hello
HELLO
hello
HELLO
World!
WORLD!
world!
WORLD!
The DISPLAY statements do not change the actual contents of Item-1, but affect only
how the letters are displayed. However, the MOVE statement causes uppercase
letters to be moved to the actual contents of Item-2.
Converting to reverse order (REVERSE)
The following code reverses the order of the characters in Orig-cust-name.
Move Function Reverse(Orig-cust-name) To Orig-cust-name
For example, if the starting value is JOHNSONººº, the value after the statement is
performed is ºººNOSNHOJ, where º represents a blank space.
Converting to numbers (NUMVAL, NUMVAL-C)
The NUMVAL and NUMVAL-C functions convert character strings to numbers. Use these
functions to convert alphanumeric data items that contain free-format
character-representation numbers to numeric form, and process them numerically.
For example:
01
01
01
. .
|
|
|
|
|
R
Pic x(20) Value “- 1234.5678”.
S
Pic x(20) Value “ $12,345.67CR”.
Total
Usage is Comp-1.
.
Compute Total = Function Numval(R) + Function Numval-C(S)
Use NUMVAL-C when the argument includes a currency symbol or comma, or both,
as shown in the example. You can also place an algebraic sign before or after the
character string, and the sign will be processed. The arguments must not exceed 18
digits when you compile with the default option ARITH(COMPAT) (compatibility mode)
nor 31 digits when you compile with ARITH(EXTEND) (extended mode), not including
the editing symbols.
NUMVAL and NUMVAL-C return long (64-bit) floating-point values in compatibility
mode, and return extended-precision (128-bit) floating-point values in extended
mode. A reference to either of these functions, therefore, represents a reference to a
numeric data item.
When you use NUMVAL or NUMVAL-C, you do not need to statically declare numeric
data in a fixed format, nor input data in a precise manner. For example, suppose
you define numbers to be entered as follows:
01 X
Pic S999V99
. . .
Accept X from Console
leading sign is separate.
The user of the application must enter the numbers exactly as defined by the
PICTURE clause. For example:
+001.23
-300.00
However, using the NUMVAL function, you could code:
Chapter 6. Handling strings
95
01 A
Pic x(10).
01 B
Pic S999V99.
. . .
Accept A from Console
Compute B = Function Numval(A)
The input could then be:
1.23
-300
RELATED CONCEPTS
“Formats for numeric data” on page 36
RELATED TASKS
“Assigning input from a screen or file (ACCEPT)” on page 28
“Displaying values on a screen or in a file (DISPLAY)” on page 29
RELATED REFERENCES
NUMVAL (IBM COBOL Language Reference)
NUMVAL-C (IBM COBOL Language Reference)
“ARITH” on page 262
Evaluating data items (intrinsic functions)
You can use several intrinsic functions in evaluating data items:
v CHAR and ORD for evaluating integers and single alphanumeric characters with
respect to the collating sequence used in your program
v MAX, MIN, ORD-MAX, and ORD-MIN for finding the largest and smallest items in a
series of data items
v LENGTH for finding the length of data items
v WHEN-COMPILED for finding the date and time the program was compiled
RELATED TASKS
“Evaluating single characters for collating sequence”
“Finding the largest or smallest data item” on page 97
“Finding the length of data items” on page 98
“Finding the date of compilation” on page 99
Evaluating single characters for collating sequence
To find out the ordinal position of a given character in the collating sequence, use
the ORD function with the character as the argument. ORD returns an integer
representing that ordinal position. One convenient way to find a character’s ordinal
position is to use a one-character substring of a data item as the argument to ORD:
IF Function Ord(Customer-record(1:1)) IS > 194 THEN . . .
If you know the ordinal position in the collating sequence of a character, and want
to know the character that it corresponds to, use the CHAR function with the integer
ordinal position as the argument. CHAR returns the desired character:
INITIALIZE Customer-Name REPLACING ALPHABETIC BY Function Char(65)
RELATED REFERENCES
CHAR (IBM COBOL Language Reference)
ORD (IBM COBOL Language Reference)
96
Programming Guide
Finding the largest or smallest data item
If you want to know which of two or more alphanumeric data items has the
largest value, use the MAX or ORD-MAX function. Supply the data items in question as
arguments. If you want to know which item contains the smallest value, use the
MIN or ORD-MIN function. These functions evaluate the values according to the
collating sequence. You can also use MAX, ORD-MAX, MIN, or ORD-MIN for numbers. In
that case, the algebraic values of the arguments are compared.
MAX and MIN
The MAX and MIN functions return the contents of one of the variables you supply.
For example, suppose you have these data definitions:
05
05
05
Arg1
Arg2
Arg3
Pic x(10)
Pic x(10)
Pic x(10)
Value “THOMASSON ”.
Value “THOMAS
”.
Value “VALLEJO
”.
The following statement assigns VALLEJOººº to the first 10 character positions of
Customer-record, where º represents a blank space:
Move Function Max(Arg1 Arg2 Arg3) To Customer-record(1:10)
If you use MIN instead, then THOMASºººº is assigned.
ORD-MAX and ORD-MIN
The functions ORD-MAX and ORD-MIN return an integer that represents the ordinal
position of the argument with the largest or smallest value in the list of arguments
you supply (counting from the left).
If you used the ORD-MAX function in the example above, you would receive a syntax
error message at compile time; the reference to a numeric function is in an invalid
place. The following is a valid use of the ORD-MAX function:
Compute x = Function Ord-max(Arg1 Arg2 Arg3)
This code assigns the integer 3 to x if the same arguments are used as in the
previous example. If you use ORD-MIN instead, the integer 2 is returned.
The above examples would probably be more realistic if Arg1, Arg2, and Arg3 were
instead successive elements of an array (table).
Returning variable-length results with alphanumeric functions
The results of alphanumeric functions could be of varying lengths and values
depending on the function arguments.
In the following example, the amount of data moved to R3 and the results of the
COMPUTE statement depend on the values and sizes of R1 and R2:
01
01
01
01
. .
R1
Pic x(10) value “e”.
R2
Pic x(05) value “f”.
R3
Pic x(20) value spaces.
L
Pic 99.
.
Move Function Max(R1 R2) to R3
Compute L = Function Length(Function Max(R1 R2))
Here, R2 is evaluated to be larger than R1. Therefore:
v The string fºººº is moved to R3, where º represents a blank space. (The unfilled
character positions in R3 are padded with spaces.)
v L evaluates to the value 5.
Chapter 6. Handling strings
97
If R1 contained “g” instead of “e” then R1 would evaluate as larger than R2, and:
v The string gººººººººº would be moved to R3. (The unfilled character positions
in R3 would be padded with spaces.)
v The value 10 would be assigned to L.
You might be dealing with variable-length output from alphanumeric functions.
Plan your program accordingly. For example, you might need to think about using
variable-length files when the records you are writing could be of different lengths:
File Section.
FD Output-File Recording Mode V.
01 Short-Customer-Record
Pic X(50).
01 Long-Customer-Record
Pic X(70).
. . .
Working-Storage Section.
01 R1
Pic x(50).
01 R2
Pic x(70).
. . .
If R1 > R2
Write Short-Customer-Record from R1
Else
Write Long-Customer-Record from R2
End-if
RELATED TASKS
“Performing arithmetic” on page 43
“Processing table items using intrinsic functions” on page 67
RELATED REFERENCES
ORD-MAX (IBM COBOL Language Reference)
ORD-MIN (IBM COBOL Language Reference)
Finding the length of data items
You can use the LENGTH function in many contexts (including numeric data and
tables) to determine the length of string items.
The following COBOL statement demonstrates moving a data item into that field
in a record that holds customer names:
Move Customer-name To Customer-record(1:Function Length(Customer-name))
You could also use the LENGTH OF special register. Coding either Function
Length(Customer-Name) or LENGTH OF Customer-Name returns the same result: the
length of Customer-Name in bytes.
You can use the LENGTH function only where arithmetic expressions are allowed.
However, you can use the LENGTH OF special register in a greater variety of
contexts. For example, you can use the LENGTH OF special register as an argument
to an intrinsic function that allows integer arguments. (You cannot use an intrinsic
function as an operand to the LENGTH OF special register.) You can also use the
LENGTH OF special register as a parameter in a CALL statement.
RELATED TASKS
“Performing arithmetic” on page 43
“Processing table items using intrinsic functions” on page 67
RELATED REFERENCES
LENGTH (IBM COBOL Language Reference)
98
Programming Guide
Finding the date of compilation
If you want to know the date and time when a program was compiled, you can
use the WHEN-COMPILED function. The result returned has 21 character positions,
with the first 16 positions in the following format:
YYYYMMDDhhmmsshh
These characters show the four-digit year, month, day, and time (in hours, minutes,
seconds, and hundredths of seconds) of compilation.
The WHEN-COMPILED special register is another means you can use to find the date
and time of compilation. It has the following format:
MM/DD/YYhh.mm.ss
The WHEN-COMPILED special register supports only a two-digit year, and carries the
time out only to seconds. This special register be used only as the sending field in
a MOVE statement.
RELATED REFERENCES
WHEN-COMPILED (IBM COBOL Language Reference)
Chapter 6. Handling strings
99
100
Programming Guide
Chapter 7. Processing files
Reading and writing data is an essential part of every program. Your program
retrieves information, processes it as you request, and then produces the results.
The source of the information and the target for the results can be one or more of
the following:
v Another program
v Direct-access storage device
v Magnetic tape
v Printer
v Terminal
v Card reader or punch
The information as it exists on an external device is in a physical record or block, a
collection of information that is handled as a unit by the system during input or
output operations.
Your COBOL program does not directly handle physical records. It processes
logical records. A logical record can correspond to a complete physical record, part
of a physical record, or to parts or all of one or more physical records. Your
COBOL program handles logical records exactly as you have defined them.
In COBOL, a collection of logical records is a file, a sequence of pieces of
information that your program can process.
RELATED CONCEPTS
“File organization and input-output devices”
RELATED TASKS
“Choosing file organization and access mode” on page 103
“Allocating files” on page 105
“Checking for input or output errors” on page 106
File organization and input-output devices
|
Depending on the input-output devices, your file organization can be sequential,
line sequential, indexed, or relative. Decide on the file types and devices to be used
when you design your program.
You have the following choices of file organization:
Sequential file organization
The chronological order in which records are entered when a file is created
establishes the arrangement of the records. Each record except the first has
a unique predecessor record, and each record except the last has a unique
successor record. Once established, these relationships do not change.
The access (record transmission) mode allowed for sequential files is
sequential only.
© Copyright IBM Corp. 1991, 2000
101
Line-sequential file organization
Line-sequential files are sequential files that reside on the hierarchical file
system (HFS) and that contain only characters as data. Each record ends
with a new-line character.
|
|
|
The only access (record transmission) mode allowed for line-sequential files
is sequential.
|
|
Indexed file organization
Each record in the file contains a special field whose contents form the
record key. The position of the key is the same in each record. The index
component of the file establishes the logical arrangement of the file, an
ordering by record key. The actual physical arrangement of the records in
the file is not significant to your COBOL program.
An indexed file can also use alternate indexes in addition to the record key.
These keys let you access the file using a different logical ordering of the
records.
The access (record transmission) modes allowed for indexed files are
sequential, random, or dynamic. When you read or write indexed files
sequentially, the sequence is that of the key values.
Relative file organization
Records in the file are identified by their location relative to the beginning
of the file. The first record in the file has a relative record number of 1, the
tenth record has a relative record number of 10, and so on.
The access (record transmission) modes allowed for relative files are
sequential, random, or dynamic. When relative files are read or written
sequentially, the sequence is that of the relative record number.
With COBOL for OS/390 & VM, requests to the operating system for the storage
and retrieval of records from input-output devices are handled by the two access
methods QSAM and VSAM, and the OS/390 UNIX file system.
|
|
|
The device type upon which you elect to store your data could affect the choices of
file organization available to you. Direct-access storage devices provide greater
flexibility in the file organization options. Sequential-only devices limit
organization options but have other characteristics, such as the portability of tapes,
that might be useful.
Sequential-only devices
Terminals, printers, card readers, and punches are called unit-record devices
because they process one line at a time. Therefore, you must also process
records one at a time sequentially in your program when it reads from or
writes to unit-record devices.
On tape, records are ordered sequentially, so your program must process
them sequentially. Use QSAM physical sequential files when processing
tape files. The records on tape can be fixed length or variable length. The
rate of data transfer is faster than it is for cards.
Direct-access storage devices
Direct-access storage devices hold many records. The record arrangement
of files stored on these devices determines the ways that your program can
process the data. When using direct-access devices, you have greater
flexibility within your program, because your can use several types of file
organization:
v Sequential (VSAM or QSAM)
102
Programming Guide
|
v Line sequential (OS/390 UNIX)
v Indexed (VSAM)
v Relative (VSAM)
RELATED TASKS
“Allocating files” on page 105
“Chapter 8. Processing QSAM files” on page 107
“Chapter 9. Processing VSAM files” on page 135
“Chapter 10. Processing line-sequential files” on page 163
“Choosing file organization and access mode”
Choosing file organization and access mode
|
|
|
Consider the following guidelines when determining which file organization and
access mode to use in your application:
v If your application accesses records (fixed-length or variable-length records) only
sequentially and does not insert records between existing ones, a QSAM or
VSAM sequential file is the simplest type.
v If you are developing an application for OS/390 UNIX that sequentially accesses
records that contain only printable characters and certain control characters,
line-sequential files work the best.
v If your application requires both sequential and random access (fixed-length or
variable-length records), a VSAM indexed file is the most flexible type.
v If your application randomly inserts and deletes records, a relative file works
well.
If a large percentage of a file is referenced or updated in your application,
sequential processing is faster than random or dynamic access. If a small
percentage of records is processed during each run of your application, use
random or dynamic access.
The following table shows the possible file organizations, access modes, and record
formats for COBOL files.
File organization
|
|
|
Sequential
access
Random
access
Dynamic
access
Fixedlength
Variablelength
QSAM (physical
sequential)
X
X
X
Line sequential
X
X1
X
VSAM sequential (ESDS)
X
X
X
VSAM indexed (KSDS)
X
X
X
X
X
VSAM relative (RRDS)
X
X
X
X
X
1. The data itself is in variable format but can be read into and written from COBOL
fixed-length records.
RELATED REFERENCES
“Format for coding input and output”
“Allowable control characters” on page 164
Format for coding input and output
The following code shows the general format of input-output coding. Explanations
of the user-supplied information follow the code.
Chapter 7. Processing files
103
IDENTIFICATION DIVISION.
. . .
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO assignment-name (1) (2)
ORGANIZATION IS org ACCESS MODE IS access (3) (4)
FILE STATUS IS file-status
(5)
. . .
DATA DIVISION.
FILE SECTION.
FD filename
01 recordname
(6)
nn . . . fieldlength & type
(7) (8)
nn . . . fieldlength & type
. . .
WORKING-STORAGE SECTION
01 file-status PICTURE 99.
. . .
PROCEDURE DIVISION.
. . .
OPEN iomode filename
(9)
. . .
READ filename
. . .
WRITE recordname
. . .
CLOSE filename
. . .
STOP RUN.
The user-supplied information in the code above is as follows:
(1) filename
Any legal COBOL name. You must use the same file name on the SELECT
and the FD statements, and on the READ, OPEN, and CLOSE statements. In
addition, the file name is required if you use the START or DELETE
statements. This name is not necessarily the actual name of the data set as
known to the system. Each file requires its own SELECT, FD, and
input-output statements.
(2) assignment-name
Any name you choose, provided that it follows COBOL and system
naming rules. The name can be 1-30 characters long if it is a user-defined
word, or 1-160 characters long if it is a literal. You code the name part of
the assignment-name on a DD statement, in an ALLOCATE command (TSO), in
a FILEDEF command (CMS), or as an environment variable (for example, in
an export command) (OS/390 UNIX).
|
|
|
(3) org The organization can be SEQUENTIAL, LINE SEQUENTIAL, INDEXED, or
RELATIVE. This clause is optional for QSAM files.
|
(4) access
The access mode can be SEQUENTIAL, RANDOM, or DYNAMIC. For sequential file
processing, including line-sequential, you can omit this clause.
|
(5) file-status
The two-character COBOL FILE STATUS key.
(6) recordname
The name of the record used in the WRITE and REWRITE statements.
(7) fieldlength
The logical length of the field.
104
Programming Guide
(8) type
The record format of the file. If you break the record entry beyond the
level-01 description, each element should map accurately against the fields
in the record.
(9) iomode
The INPUT or OUTPUT mode. If you are only reading from a file, code INPUT.
If you are only writing to it, code OUTPUT or EXTEND. If you are both reading
and writing, code I-O, except for organization LINE SEQUENTIAL.
|
RELATED TASKS
“Chapter 8. Processing QSAM files” on page 107
“Chapter 9. Processing VSAM files” on page 135
“Chapter 10. Processing line-sequential files” on page 163
Allocating files
|
|
|
|
For any type of file (sequential, line sequential, indexed, or relative) in your
OS/390 or OS/390 UNIX applications, you can define the external name with
either a ddname or an environment variable name. The external name is the name
in the assignment-name of the ASSIGN clause.
|
|
If the file is in the HFS, you can use either a DD definition or an environment
variable to define the file by specifying its path name with the PATH keyword.
|
|
The environment variable name must be uppercase. The allowable attributes for its
value depend on the organization of the file being defined.
|
|
|
|
|
|
|
|
|
|
|
|
|
Because you can define the external name in either of two ways, the COBOL run
time goes through the following steps to find the definition of the file:
|
|
|
|
v The contents (including a value of null or all blanks) of the environment
variable are not valid.
v The dynamic allocation of the file fails.
|
|
|
|
|
|
|
The COBOL run time checks the contents of the environment variable at each
OPEN statement. If a file with the same external name was dynamically allocated
by a previous OPEN statement and the contents of the environment variable
have changed since that OPEN, the run time dynamically deallocates the
previous allocation and reallocates the file using the options currently set in the
environment variable. If the contents of the environment variable have not
changed, the run time uses the current allocation.
1. If the ddname is explicitly allocated, it is used. The definition can be from a DD
statement in JCL, an ALLOCATE command from TSO/E, or a user-initiated
dynamic allocation.
2. If the ddname is not explicitly allocated and an environment variable of the
same name is set, the value of the environment variable is used.
The file is dynamically allocated using the attributes specified by the
environment variable. At a minimum, you must specify either the PATH() or
DSN() option. All options and attributes must be in uppercase, except for the
path-name suboption of the PATH option, which is case sensitive. You cannot
specify a temporary data set name in the DSN() option.
File status code 98 results from any of the following:
v The dynamic deallocation of the file fails.
Chapter 7. Processing files
105
|
|
|
|
|
|
|
3. If neither a ddname nor an environment variable is defined, the following
occurs:
v If the allocation is for a QSAM file and the CBLQDA run-time option is in
effect, CBLQDA dynamic allocation processing takes place for those eligible
files. This type of “implicit” dynamic allocation persists for the life of the run
unit and cannot be reallocated.
v Otherwise the allocation fails.
|
|
|
|
The COBOL run time follows these steps for both OS/390 and OS/390 UNIX
applications that were compiled with the NOCMPR2 compiler option. Dynamic
allocation of files using an environment variable is not available to programs
compiled with the CMPR2 compiler option or programs run under CMS.
|
|
The COBOL run time deallocates all dynamic allocations at run-unit termination,
except “implicit” CBLQDA allocations.
RELATED TASKS
“Setting and accessing environment variables” on page 362
“Defining and allocating QSAM files” on page 121
“Dynamically creating QSAM files with CBLQDA” on page 118
“Allocating VSAM files” on page 156
RELATED REFERENCES
“CMPR2” on page 264
Checking for input or output errors
After each input or output statement is performed, the FILE STATUS key is updated
with a value that indicates the success or failure of the operation. Using a FILE
STATUS clause, test the FILE STATUS key after each input or output statement, and
call an error-handling procedure if a nonzero file status code is returned.
With VSAM files, you can use a second data-name in the FILE STATUS clause to get
additional VSAM return code information.
Another way of handling errors in input and output operations is to code ERROR
(synonymous with EXCEPTION) declaratives, as explained in the references below.
RELATED TASKS
“Handling errors in input and output operations” on page 191
“Coding ERROR declaratives” on page 194
“Using file status keys” on page 194
106
Programming Guide
Chapter 8. Processing QSAM files
Queued sequential access method (QSAM) files are unkeyed files in which the
records are placed one after another, according to entry order. Your program can
process these files only sequentially, retrieving (with the READ statement) records in
the same order as they are in the file. Each record is placed after the preceding
record.
To process QSAM files in your program, use COBOL language statements that:
v Identify and describe the QSAM files in the ENVIRONMENT DIVISION and the DATA
DIVISION.
v Process the records in these files in the PROCEDURE DIVISION.
|
After you have created a record, you cannot change its length or its position in the
file, and you cannot delete it. You can, however, update QSAM files on
direct-access storage devices (using REWRITE), though not in the HFS.
QSAM files can be on tape, direct-access storage devices (DASDs), unit-record
devices, and terminals. QSAM processing is best for tables and intermediate
storage.
|
|
|
|
You can also access byte-stream files in the HFS using QSAM. These files are
binary byte-oriented sequential files with no record structure. The record
definitions that you code in your COBOL program and the length of the variables
that you read into and write from determine the amount of data transferred.
RELATED CONCEPTS
“Labels for QSAM files” on page 129
OS/390 DFSMS: Using Data Sets (how QSAM files are organized, and how the
system processes them)
RELATED TASKS
“Defining QSAM files and records in COBOL”
“Coding input and output statements for QSAM files” on page 117
“Handling errors in QSAM files” on page 120
“Working with QSAM files under OS/390” on page 121
“Identifying QSAM files to CMS” on page 128
“Processing QSAM ASCII files on tape” on page 132
“Processing ASCII file labels” on page 133
Defining QSAM files and records in COBOL
Use the FILE-CONTROL entry to:
|
|
v Define the files in your COBOL program as QSAM files.
v Associate the files with the external file names (ddnames or environment
variable names). (An external file name is the name by which a file is known to
the operating system.)
|
|
In the following example, COMMUTER-FILE-MST is your program’s name for the file;
COMMUTR is the external name.
© Copyright IBM Corp. 1991, 2000
107
FILE-CONTROL.
SELECT COMMUTER-FILE-MST
ASSIGN TO S-COMMUTR
ORGANIZATION IS SEQUENTIAL
ACCESS MODE IS SEQUENTIAL.
Your ASSIGN clause name can include an S- before the external name (ddname or
environment variable name) to document that the file is a QSAM file.
|
|
Both the ORGANIZATION and ACCESS MODE clauses are optional.
RELATED TASKS
“Establishing record formats”
“Setting block sizes” on page 115
Establishing record formats
In the FD entry in the DATA DIVISION, code the record format and whether the
records are blocked. In the associated record description entry or entries, define the
record-name and record length.
You can code a record format of F, V, S, or U in the RECORDING MODE clause. COBOL
determines the record format from the RECORD clause or from the record
descriptions associated with your FD entry for the file. If you want the records to
be blocked, code the BLOCK CONTAINS clause in your FD entry.
The following example shows how the FD entry might look for a file with
fixed-length records:
FILE SECTION.
FD COMMUTER-FILE-MST
RECORDING MODE IS F
BLOCK CONTAINS 0 RECORDS
RECORD CONTAINS 80 CHARACTERS.
01 COMMUTER-RECORD-MST.
05 COMMUTER-NUMBER
PIC X(16).
05 COMMUTER-DESCRIPTION
PIC X(64).
A recording mode of S is not supported for files in the HFS. The above example is
appropriate for such a file.
|
|
RELATED CONCEPTS
“Logical records”
RELATED TASKS
“Requesting fixed-length format” on page 109
“Requesting variable-length format” on page 110
“Requesting spanned format” on page 112
“Requesting undefined format” on page 114
“Defining QSAM files and records in COBOL” on page 107
Logical records
The term logical record is used in a slightly different way in the COBOL language
and in OS/390 QSAM. For format-V and format-S files, the QSAM logical record
includes a 4-byte prefix in front of the user data portion of the record that is not
included in the definition of a COBOL logical record. For format-F and format-U
files, and for HFS byte-stream files, the definitions of QSAM logical record and
COBOL logical record are identical.
|
108
Programming Guide
In this information, QSAM logical record refers to the QSAM definition, and logical
record refers to the COBOL definition.
RELATED REFERENCES
“Layout
“Layout
“Layout
“Layout
of
of
of
of
format-F records”
format-V records” on page 111
format-S records” on page 113
format-U records” on page 114
Requesting fixed-length format
Fixed-length records are in format F. Use RECORDING MODE F to explicitly request
this format.
You can omit the RECORDING MODE clause. The compiler determines the recording
mode to be F if the length of the largest level-01 record associated with the file is
not greater than the block size coded in the BLOCK CONTAINS clause, and you take
one of the following actions:
v Use the RECORD CONTAINS integer clause (RECORD clause format 1).
When you use this clause, the file is always fixed format with record length
integer, even if there are multiple level-01 record description entries with
different lengths associated with the file.
v Omit the RECORD CONTAINS integer clause, but code the same fixed size and no
OCCURS DEPENDING ON clause for all level-01 record description entries associated
with the file. This fixed size is the record length.
In an unblocked format-F file, the logical record is the same as the block.
|
In a blocked format-F file, the number of logical records in a block (the blocking
factor) is constant for every block in the file, except the last block, which might be
shorter. Files in the HFS are never blocked.
RELATED CONCEPTS
“Logical records” on page 108
RELATED TASKS
“Requesting variable-length format” on page 110
“Requesting spanned format” on page 112
“Requesting undefined format” on page 114
“Establishing record formats” on page 108
RELATED REFERENCES
“Layout of format-F records”
|
Layout of format-F records: The layout of format-F QSAM records is shown
below.
Chapter 8. Processing QSAM files
109
RELATED CONCEPTS
“Logical records” on page 108
RELATED TASKS
“Requesting fixed-length format” on page 109
Fixed-length record formats (OS/390 DFSMS: Using Data Sets)
RELATED REFERENCES
“Layout of format-V records” on page 111
“Layout of format-S records” on page 113
“Layout of format-U records” on page 114
Requesting variable-length format
Variable-length records can be in format V or format D. Format-D records are
variable-length records on ASCII tape files. Format-D records are processed in the
same way as format-V records. Use RECORDING MODE V for both.
You can omit the RECORDING MODE clause. The compiler determines the recording
mode to be V if the largest level-01 record associated with the file is not greater
than the block size set in the BLOCK CONTAINS clause, and you take one of the
following actions:
v Use the RECORD IS VARYING clause (RECORD clause format 3).
If you provide values for integer-1 and integer-2 (RECORD IS VARYING FROM
integer-1 TO integer-2), the maximum record length is the value coded for
integer-2, regardless of the lengths coded in the level-01 record description
entries associated with the file.
If you omit integer-1 and integer-2, the maximum record length is determined to
be the size of the largest level-01 record description entry associated with the
file.
v Use the RECORD CONTAINS integer-1 TO integer-2 clause (RECORD clause format 2).
Make integer-1 and integer-2 match the minimum length and the maximum
length of the level-01 record description entries associated with the file. The
maximum record length is the integer-2 value.
v Omit the RECORD clause, but code multiple level-01 records (associated with the
file) that are of different sizes or contain an OCCURS DEPENDING ON clause.
The maximum record length is determined to be the size of the largest level-01
record description entry associated with the file.
When you specify a READ INTO statement for a format-V file, the record size read
for that file is used in the MOVE statement generated by the compiler. Consequently,
you might not get the result you expect if the record just read does not correspond
to the level-01 record description. All other rules of the MOVE statement apply. For
example, when you specify a MOVE statement for a format-V record read in by the
READ statement, the size of the record moved corresponds to its level-01 record
description.
When you specify a READ statement for a format-V file followed by a MOVE of the
level-01 record, the actual record length is not used. The program will attempt to
move the number of bytes described by the level-01 record description. If this
number exceeds the actual record length and extends outside the area addressable
by the program, results are unpredictable. If the number of bytes described by the
level-01 record description is shorter than the physical record read, truncation of
bytes beyond the 01-level description occurs. To find the actual length of a
variable-length record, specify data-name-1 in format 3 of the RECORD clause of the
File Definition (FD).
110
Programming Guide
The RECORD clause is sensitive to the CMPR2 compiler option.
RELATED TASKS
“Requesting fixed-length format” on page 109
“Requesting spanned format” on page 112
“Requesting undefined format” on page 114
“Establishing record formats” on page 108
RELATED REFERENCES
“Layout of format-V records”
“CMPR2” on page 264
COBOL for OS/390 & VM Compiler and Run-Time Migration Guide (VS COBOL II
Release 2 compatibility and migration)
|
Layout of format-V records: Format-V QSAM records have control fields (shown
below) preceding the data. The QSAM logical record length is determined by
adding 4 bytes (for the control fields) to the record length defined in your
program, but you must not include these 4 bytes in the description of the record
and record length.
CC
The first 4 bytes of each block contain control information.
LL Represents 2 bytes designating the length of the block (including the
’CC’ field).
BB Represents 2 bytes reserved for system use.
cc
The first 4 bytes of each logical record contain control information.
ll Represents 2 bytes designating the logical record length (including the
’cc’ field).
bb Represents 2 bytes reserved for system use.
The block length is determined as follows:
v Unblocked format-V records: CC + cc + the data portion
v Blocked format-V records: CC + the cc of each record + the data portion of each
record
The operating system provides the control bytes when the file is written; the
control byte fields do not appear in your description of the logical record in the
DATA DIVISION of your program. COBOL allocates input and output buffers large
enough to accommodate the control bytes. These control fields in the buffer are not
available for you to use in your program. When variable-length records are written
on unit record devices, control bytes are neither printed nor punched. They appear,
however, on other external storage devices, as well as in buffer areas of storage. If
you move V-mode records from an input buffer to a WORKING-STORAGE area, they’ll
be moved without the control bytes.
Chapter 8. Processing QSAM files
111
Files in the HFS are never blocked.
|
RELATED CONCEPTS
“Logical records” on page 108
RELATED TASKS
“Requesting variable-length format” on page 110
RELATED REFERENCES
“Layout of format-F records” on page 109
“Layout of format-S records” on page 113
“Layout of format-U records” on page 114
Requesting spanned format
Spanned records are in format S. A spanned record is a QSAM logical record that
can be contained in one or more physical blocks. You can code RECORDING MODE S
for spanned records in QSAM files assigned to magnetic tape or to direct access
devices. Do not request spanned records for files in the HFS.
|
You can omit the RECORDING MODE clause. The compiler determines the recording
mode to be S if the maximum record length plus 4 is greater than the block size set
in the BLOCK CONTAINS clause.
For files with format S in your program, the compiler determines the maximum
record length with the same rules used for format V. The length is based on your
usage of the RECORD clause.
When creating files containing format-S records, and a record is larger than the
remaining space in a block, COBOL writes a segment of the record to fill the block.
The rest of the record is stored in the next block or blocks, depending on its length.
COBOL supports QSAM Spanned records up to 32760 bytes long.
When retrieving files with format-S records, your program can retrieve only
complete records.
Benefits of format-S files: You can efficiently use external storage and still
organize your files with logical record lengths by defining files with format-S
records:
v You can set block lengths to efficiently use track capacities on direct access
devices.
v You are not required to adjust the logical record lengths to device-dependent
physical block lengths. One logical record can span two or more physical blocks.
v You have greater flexibility when you want to transfer logical records between
direct access storage types.
You will, however, have additional overhead in processing format-S files.
Format-S files and READ INTO: By specifying a READ INTO statement for a
format-S file, the record size just read for that file is used in the MOVE statement
generated by the compiler. Consequently, you might not get the result you expect
if the record just read does not correspond to the level-01 record description. All
other rules of the MOVE statement apply.
RELATED CONCEPTS
“Logical records” on page 108
“Spanned blocked and unblocked files” on page 113
112
Programming Guide
RELATED TASKS
“Requesting fixed-length format” on page 109
“Requesting variable-length format” on page 110
“Requesting undefined format” on page 114
“Establishing record formats” on page 108
RELATED REFERENCES
“Layout of format-S records”
|
Spanned blocked and unblocked files: A spanned blocked QSAM file is made
up of blocks, each containing one or more logical records or segments of logical
records. The logical records can be either fixed or variable in length and their size
can be smaller than, equal to, or larger than the physical block size. There are no
required relationships between logical records and physical block sizes.
A spanned unblocked file is made up of physical blocks, each containing one
logical record or one segment of a logical record. The logical records can be either
fixed or variable in length. When the physical block contains one logical record,
the block length is determined by the logical record size. When a logical record has
to be segmented, the system always writes the largest physical block possible. The
system segments the logical record when the entire logical record cannot fit on a
track.
RELATED CONCEPTS
“Logical records” on page 108
RELATED TASKS
“Requesting spanned format” on page 112
Layout of format-S records: Spanned records are preceded by control fields, as
shown below.
Each block is preceded by a block descriptor field. There is only one block
descriptor field at the beginning of each physical block.
Each segment of a record in a block, even if the segment is the entire record, is
preceded by a segment descriptor field. There is one segment descriptor field for
each record segment in the block. The segment descriptor field also indicates
whether the segment is the first, the last, or an intermediate segment.
You do not describe these fields in the DATA DIVISION of your COBOL program,
and the fields are not available for you to use in your program.
RELATED TASKS
“Requesting spanned format” on page 112
RELATED REFERENCES
“Layout of format-F records” on page 109
“Layout of format-V records” on page 111
“Layout of format-U records” on page 114
Chapter 8. Processing QSAM files
113
Requesting undefined format
Format-U records have undefined or unspecified characteristics. With format U,
you can process blocks that do not meet format-F or format-V specifications.
The compiler determines the recording mode to be U only if you code RECORDING
MODE U.
The record length is determined in your program based on how you use the
RECORD clause:
v If you use the RECORD CONTAINS integer clause (RECORD clause format 1), the record
length is the integer value, regardless of the lengths of the level-01 record
description entries associated with the file.
v If you use the RECORD IS VARYING clause (RECORD clause format 3), the record
length is determined based on whether you code integer-1 and integer-2.
If you code integer-1 and integer-2 (RECORD IS VARYING FROM integer-1 TO
integer-2), the maximum record length is the integer-2 value, regardless of the
lengths of the level-01 record description entries associated with the file.
If you omit integer-1 and integer-2, the maximum record length is determined to
be the size of the largest level-01 record description entry associated with the
file.
v If you use the RECORD CONTAINS integer-1 TO integer-2 clause (RECORD clause
format 2), with integer-1 and integer-2 matching the minimum length and the
maximum length of the level-01 record description entries associated with the
file, the maximum record length is the integer-2 value.
v If you omit the RECORD clause, the maximum record length is determined to be
the size of the largest level-01 record description entry associated with the file.
Format-U files and READ INTO: When you specify a READ INTO statement for a
format-U file, the size of the record just read for that file is used in the MOVE
statement generated by the compiler. Consequently, you might not get the result
you expect if the record just read does not correspond to the level-01 record
description. All other rules of the MOVE statement apply.
RELATED TASKS
“Requesting fixed-length format” on page 109
“Requesting variable-length format” on page 110
“Requesting spanned format” on page 112
“Establishing record formats” on page 108
RELATED REFERENCES
“Layout of format-U records”
Layout of format-U records: Each block of external storage is handled as a logical
record. There are no record-length or block-length fields.
RELATED CONCEPTS
“Logical records” on page 108
RELATED TASKS
“Requesting undefined format”
114
Programming Guide
RELATED REFERENCES
“Layout of format-F records” on page 109
“Layout of format-V records” on page 111
“Layout of format-S records” on page 113
Setting block sizes
|
|
|
In COBOL, you establish the size of a physical record with the BLOCK CONTAINS
clause. If you omit this clause, the compiler assumes that the records are not
blocked. Blocking QSAM files on tape and disk can enhance processing speed and
minimize storage requirements. You can block UNIX system services files
(including those in the HFS), PDSE members, and spooled data sets, but doing so
has no effect on how the system stores the data.
If you set the block size explicitly in the BLOCK CONTAINS clause, it must not be
greater than the maximum block size for the device. The block size set for a
format-F file must be an integral multiple of the record length.
If your program uses QSAM files on tape, use a physical block size of at least 12 to
18 bytes. Otherwise, the block will be skipped over when a parity check occurs
while doing one of the following:
v Reading a block of records of fewer than 12 bytes
v Writing a block of records of fewer than 18 bytes
Letting OS/390 determine block size
We recommend that to maximize performance, you not explicitly set the block size
for a blocked file in your COBOL source program. For new blocked data sets on
OS/390, it is simpler to allow OS/390 to supply a system-determined block size.
To use this feature:
v Code BLOCK CONTAINS 0 in your source program.
v Do not code RECORD CONTAINS 0 in your source program.
v Do not code a BLKSIZE value in the JCL DD statement.
Setting block size explicitly
If you prefer to set a block size explicitly (in either an OS/390 or CMS
environment), your program will be most flexible if you:
v Code BLOCK CONTAINS 0 in your source program.
v Code a BLKSIZE value in the ddname definition (the JCL DD statement or the
FILEDEF command).
For extended-format QSAM data sets on OS/390, DFSMS adds a 32-byte block
suffix to the physical record. If you specify a block size explicitly (using JCL or
ISPF), do not include the size of this block suffix in the block size. This block suffix
is not available for you to use in your program. DFSMS allocates the space used to
read in the block suffix. However, when you calculate how many blocks of a
QSAM striped data set will fit on a track of a direct access device, you need to
include the size of the block suffix in the block size.
|
|
|
|
|
|
If you specify a block size larger than 32760 directly on your BLOCK CONTAINS
clause or indirectly with the use of BLOCK CONTAINS n RECORDS, and you do not
meet both the following conditions, the OPEN of the data set fails with file status
code 90:
v You use OS/390 V2R10.0 DFSMS or later.
v You define the data set to be tape.
For existing blocked data sets, it is simplest to:
Chapter 8. Processing QSAM files
115
v Code BLOCK CONTAINS 0 in your source program.
v Code no BLKSIZE value in the ddname definition.
When you omit the BLKSIZE from the ddname definition, the block size is
automatically obtained by the system from the data set label.
Taking advantage of LBI
|
|
|
|
|
|
You can improve the performance of tape data sets by using OS/390 V2R10.0
DFSMS, which provides the large block interface (LBI) for large block sizes. When
it is available, the COBOL run time automatically uses this facility for those tape
files for which you use system-determined block size. LBI is also used for those
files for which you explicitly define a block size in JCL or a BLOCK CONTAINS clause.
Use of the LBI allows block sizes to exceed 32760 if the tape device supports it.
|
|
|
|
The LBI is not used in all cases. An attempt to use a block size greater than 32760
in the following cases is diagnosed at compile time or results in a failure at OPEN:
v Spanned records
v OPEN I-O
|
|
|
|
|
|
Using a block size that exceeds 32760 might result in your not being able to read
the tape on another system. A tape that you create with a block size greater than
32760 can be read only on an MVS system that uses OS/390 V2R10.0 DFSMS or
later and has a tape device that supports block sizes greater than 32760. If you
specify a block size that is too large for the file, the device, or the operating system
level, a run-time message is issued.
|
|
|
|
|
To limit a system-determined block size to 32760, do not specify BLKSIZE anywhere,
and do one of the following:
v Specify the BLKSZLIM keyword on your DD statement for the data set.
v Have your systems programmer set BLKSZLIM for the data class using the
BLKSZLIM keyword.
|
|
v Have your systems programmer set a block-size limit for the system in the
DEVSUPxx member of SYS1.PARMLIB using the keyword TAPEBLKSZLIM.
|
|
|
If no BLKSIZE or BLKSZLIM value is available from any source, the system limits
BLKSIZE to 32760. You can then enable LBI selectively one of two ways:
v Specify a BLKSZLIM value greater than 32760 in the DD statement for the file.
|
|
v Specify a value greater than 32760 for the BLKSIZE in the DD statement or in the
BLOCK CONTAINS clause in your COBOL source.
|
BLKSZLIM is device-independent.
Block size and the DCB RECFM subparameter
Under OS/390, you can code the S or T option in the DCB RECFM subparameter:
v Use the S (standard) option in the DCB RECFM subparameter for a format-F record
with only standard blocks (ones that have no truncated blocks or unfilled tracks
in the file, except for the last block of the file). S is also supported for records on
tape. It is ignored if the records are not on DASD or tape.
Using this standard block option might improve input-output performance,
especially for direct access devices.
v The T (track overflow) option for QSAM files is no longer useful.
RELATED TASKS
“Defining QSAM files and records in COBOL” on page 107
OS/390 DFSMS: Using Data Sets
116
Programming Guide
RELATED REFERENCE
BLOCK CONTAINS clause (IBM COBOL Language Reference)
Coding input and output statements for QSAM files
|
|
Code the following input and output statements to process a QSAM file or a
byte-stream file in the HFS using QSAM:
OPEN
Makes the file available to your program.
You can open all QSAM files as INPUT, OUTPUT, or EXTEND (depending on
device capabilities).
You can also open QSAM files on direct access storage devices as I-O. You
cannot open HFS files as I-O; you will receive a file status of 37 if you
attempt to do so.
|
|
|
READ
Reads a record from the file.
With sequential processing, your program reads one record after another in
the same order in which they were entered when the file was created.
WRITE
Creates a record in the file.
Your program writes new records to the end of the file.
REWRITE
Updates a record. You cannot update a file in the HFS using REWRITE.
|
CLOSE
Releases the connection between the file and your program.
RELATED TASKS
“Opening QSAM files”
“Adding records to QSAM files” on page 119
“Updating QSAM files” on page 119
“Writing QSAM files to a printer or spooled data set” on page 119
“Closing QSAM files” on page 120
RELATED REFERENCES
OPEN statement (IBM COBOL Language Reference)
READ statement (IBM COBOL Language Reference)
WRITE statement (IBM COBOL Language Reference)
REWRITE statement (IBM COBOL Language Reference)
CLOSE statement (IBM COBOL Language Reference)
Opening QSAM files
Before your program can use any READ, WRITE, or REWRITE statements to process
records in a file, it must first open the file with an OPEN statement.
An OPEN statement works if both of the following are true:
|
|
v The file is available or has been dynamically allocated.
v The fixed file attributes coded in the ddname definition or the data set label for a
file match the attributes coded for that file in the SELECT and FD statements of
your COBOL program.
Mismatches in the file organization attributes, code set, maximum record size, or
record type (fixed or variable) result in a file status code 39, and the OPEN
statement fails. Mismatches in maximum record size and record type are not
considered errors when opening files in the HFS.
Chapter 8. Processing QSAM files
117
For fixed-length QSAM files under OS/390, when you code RECORD CONTAINS 0
in the FD, the record size attributes are not in conflict. The record size is taken
from the DD statement or the data set label, and the OPEN statement is successful.
Code CLOSE WITH LOCK so that the file cannot be opened again while the program
is running.
Use the REVERSED option of the OPEN statement to process tape files in reverse order.
Execution of the OPEN statement will then position the file at its end. Subsequent
READ statements read the data records in reverse order, starting with the last record.
The REVERSED option is supported only for files with fixed-length records.
RELATED TASKS
“Dynamically creating QSAM files with CBLQDA”
RELATED REFERENCES
OPEN statement (IBM COBOL Language Reference)
Dynamically creating QSAM files with CBLQDA
A file is considered to be available on OS/390 when it has been identified to the
operating system using a DD statement, an export command (an environment
variable), or a TSO ALLOCATE command. (For availability, a DD statement with a
misspelled ddname is equivalent to a missing DD statement; an environment
variable with a value that is not valid is equivalent to an unset variable.)
|
|
|
|
A file is available on CMS when it has been identified using a CMS FILEDEF
command or if the file FILE ddname exists on your minidisk.
Sometimes a QSAM file is unavailable on OS/390 or CMS, but the COBOL
language defines that the file be created. The file is implicitly created for you if
you use the run-time option CBLQDA and one of the following circumstances exists:
v The file is being opened for OUTPUT, regardless of the OPTIONAL phrase. An
OPTIONAL file is being opened as EXTEND or I-O.
Optional files are files that are not necessarily present each time the program is
run. You can define files opened in INPUT, I-O, or EXTEND mode as optional by
using the SELECT OPTIONAL phrase in the FILE-CONTROL paragraph.
The file is allocated with the system default attributes established at your
installation and the attributes coded in the SELECT and FD statements in your
program.
Do not confuse this implicit allocation mechanism with the dynamic allocation of
files through the use of environment variables. That explicit dynamic allocation
requires a valid environment variable to be set. This CBLQDA support is used only
when the QSAM file is unavailable as defined above, which includes no valid
environment variable being set.
|
|
|
|
|
Under OS/390, files created using the CBLQDA option are temporary data sets and
do not exist after the program has run. Under CMS, they are named FILE ddname
A4 and do exist after the program has run.
RELATED TASKS
“Opening QSAM files” on page 117
118
Programming Guide
Adding records to QSAM files
To add to a QSAM file, open the file as EXTEND and use the WRITE statement to add
records immediately after the last record in the file.
To add records to a file opened as I-O, you must first close the file and open it as
EXTEND.
RELATED REFERENCES
READ statement (IBM COBOL Language Reference)
WRITE statement (IBM COBOL Language Reference)
Updating QSAM files
|
|
You can update QSAM files that reside on direct access storage devices only. You
cannot update files in the HFS.
Replace an existing record with another record of the same length by doing the
following:
1. Open the file as I-O.
2. Use REWRITE to update an existing record in the file. (The last file processing
statement before REWRITE must have been a successful READ statement.)
RELATED REFERENCES
REWRITE statement (IBM COBOL Language Reference)
Writing QSAM files to a printer or spooled data set
COBOL provides language statements to control the size of a printed page and
control the vertical positioning of records.
Controlling the page size
Use the LINAGE clause of the FD entry to control the size of your printed page: the
number of lines in the top and bottom margins and in the footing area of the page.
When you use the LINAGE clause, COBOL handles the file as if you had also
requested the ADV compiler option.
If you use the LINAGE clause in combination with WRITE BEFORE/AFTER ADVANCING
nn LINES, be careful about the values you set. With the ADVANCING nn LINES clause,
COBOL first calculates the sum of LINAGE-COUNTER plus nn. Subsequent actions
depend on the size of nn. The END-OF-PAGE imperative statement is performed after
the LINAGE-COUNTER is increased. Consequently, the LINAGE-COUNTER could be
pointing to the next logical page instead of to the current footing area when the
END-OF-PAGE statement is performed.
AT END-OF-PAGE or NOT AT END-OF-PAGE imperative statements are performed only
if the write operation completes successfully. If the write operation is unsuccessful,
control is passed to the end of the WRITE statement, omitting all conditional
phrases.
Controlling the vertical positioning of records
Use the WRITE ADVANCING statement to control the vertical positioning of each
record you write on a printed page.
. . . BEFORE ADVANCING prints the record before the page is advanced.
. . . AFTER ADVANCING prints the record after the page is advanced.
Chapter 8. Processing QSAM files
119
Specify the number of lines the page is advanced with an integer (or an identifier
with a mnemonic-name) following ADVANCING. If you omit the ADVANCING option from
your WRITE statement, you get the equivalent of:
AFTER ADVANCING 1 LINE
RELATED REFERENCES
WRITE statement (IBM COBOL Language Reference)
Closing QSAM files
Use the CLOSE statement to disconnect your program from the QSAM file. If you
try to close a file that is already closed, you will get a logic error.
If you do not close a QSAM file, the file is automatically closed for you under the
following conditions:
v When the run unit ends normally, the run time closes all open files that are
defined in any of the following types of programs in the run unit: COBOL for
OS/390 & VM, COBOL for MVS & VM, and VS COBOL II.
v If the run unit ends abnormally and you have set the TRAP(ON) run-time option,
the run time closes all open files that are defined in any of the following types
of programs in the run unit: COBOL for OS/390 & VM, COBOL for MVS & VM,
and VS COBOL II.
v When Language Environment condition handling is completed and the
application resumes in a routine other than where the condition occurred, the
run time closes all open files that are defined in any of the following types of
programs in the run unit that might be called again and reentered: COBOL for
OS/390 & VM, COBOL for MVS & VM, and VS COBOL II.
You can change the location of where the program resumes running (after a
condition is handled) by moving the resume cursor with the Language
Environment CEEMRCR callable service or by using HLL language constructs
such as a C longjmp.
v When you use CANCEL for a COBOL for OS/390 & VM, COBOL for MVS & VM,
or VS COBOL II subprogram, the run time closes any open nonexternal files that
are defined in that program.
v When a COBOL for OS/390 & VM, COBOL for MVS & VM, or VS COBOL II
subprogram with the INITIAL attribute returns control, the run time closes any
open nonexternal files that are defined in that program.
File status codes are set when these implicit CLOSE operations are performed, but
EXCEPTION/ERROR and LABEL declaratives are not invoked.
RELATED REFERENCES
CLOSE statement (IBM COBOL Language Reference)
Handling errors in QSAM files
When an input-statement or output-statement operation fails, COBOL does not
take corrective action for you. You choose whether or not your program will
continue running after a less-than-severe input or output error occurs.
COBOL provides these ways for you to intercept and handle certain QSAM input
and output errors:
v End of file phrase (AT END)
v EXCEPTION/ERROR declarative
120
Programming Guide
v FILE STATUS clause
v INVALID KEY phrase
If you do not code a FILE STATUS key or a declarative, serious QSAM processing
errors will cause a message to be issued and a Language Environment condition to
be signaled, which will cause an abend if you specify the run-time option
ABTERMENC(ABEND).
If you use the FILE STATUS clause or the EXCEPTION/ERROR declarative, code
EROPT=ACC in the DCB of the DD statement for that file. Otherwise, your COBOL
program will not be able to continue processing after some error conditions.
If you use the FILE STATUS clause, be sure to check the key and take appropriate
action based on its value. If you do not check the key, your program might
continue, but the results will probably not be what you expected.
RELATED TASKS
“Handling errors in input and output operations” on page 191
Working with QSAM files under OS/390
This section describes:
v “Defining and allocating QSAM files”
v “Retrieving QSAM files” on page 123
v “Ensuring file attributes match your program” on page 124
v “Using striped extended-format QSAM data sets” on page 126
RELATED REFERENCES
“Allocation of buffers for QSAM files” on page 127
Defining and allocating QSAM files
|
|
|
|
|
You can define a QSAM file or a byte-stream file in the HFS using either a DD
statement or an environment variable. When you use an environment variable, the
name must be in uppercase. Allocation of these files follows the general rules for
the allocation of COBOL files. When you use an environment variable to define a
QSAM file, specify the MVS data set as follows:
|
|
DSN(dataset-name) or DSN(dataset-name(member-name)). dataset-name must be fully
qualified and cannot be a temporary data set (must not start with &).
|
|
You can optionally specify the following attributes in any order following the DSN:
v A disposition value, one of: NEW, OLD, SHR, or MOD
|
|
|
|
|
|
|
|
v
v
v
v
v
v
v
v
TRACKS or CYL
SPACE(nnn,mmm)
VOL(volume-serial)
UNIT(type)
KEEP, DELETE, CATALOG, or UNCATALOG
STORCLAS(storage-class)
MGMTCLAS(management-class)
DATACLAS(data-class)
Chapter 8. Processing QSAM files
121
|
|
|
You can use either an environment variable or a DD definition to define a file in the
HFS. To do this, define one of the following with a name that matches the external
name on your ASSIGN clause:
|
|
|
v A DD allocation that uses PATH=’absolute-path-name’ and FILEDATA=BINARY
v An environment variable with a value PATH(pathname), where pathname is an
absolute path name (starting with /).
|
|
|
|
|
For compatibility with earlier releases of COBOL, you can also specify
FILEDATA=TEXT when using a DD allocation for HFS files, but this use is not
recommended. To process text files in the HFS, use LINE SEQUENTIAL organization.
If you do use QSAM to process text files in the HFS, you cannot use environment
variables to define the files.
|
When you define a QSAM file, use the specified parameters to do the following:
|
What you want to do
DD parameter to use
EV keyword to use
|
Name the file
DSNAME (data set name)
DSN
|
Select the type and quantity of
input-output devices to be
allocated for the file.
UNIT
UNIT for type only
|
Give instructions for the volume in VOLUME, or let the system
VOL
which the file will reside and for
choose an output volume.
volume mounting.
|
|
|
|
|
Allocate the type and amount of
space the file needs. (For direct
access storage devices only.)
SPACE
SPACE for the amount of
space (primary and
secondary only); TRACKS
or CYL for the type of
space
|
Specify the type (and some of the
contents of) the label associated
with the file.
LABEL
N/A
|
|
|
Indicate whether you want to
catalog, pass, or keep the file after
the job step is completed.
DISP
NEW, OLD, SHR, MOD plus
KEEP, DELETE, CATALOG, or
UNCATALOG
|
Complete any data control block
information you want to add.
DCB subparameters
N/A
Some of the information about the QSAM file must always be coded in the
FILE-CONTROL entry, the FD entry, and other COBOL clauses. Other information
must be coded in the DD statement or environment variable for output files. For
input files, the system can obtain information from the file label (for standard label
files). If DCB information is provided in the DD statement for input files, it overrides
information on the data set label. For example, the amount of space allocated for a
new direct-access device file can be set in the DD statement by the SPACE parameter.
|
You cannot express certain characteristics of QSAM files in the COBOL language,
but you can code them in the DD statement for the file using the DCB parameter. Use
the subparameters of the DCB parameter to provide information that the system
needs for completing the data set definition, including the following:
v Block size (BLKSIZE=), if BLOCK CONTAINS 0 RECORDS was coded at compile time
(which is recommended)
v Options to be executed if an error occurs in reading or writing a record
v TRACK OVERFLOW or standard blocks
122
Programming Guide
v Mode of operation for a card reader or punch
DCB attributes coded for a DD DUMMY do not override those coded in the FD entry of
your COBOL program.
RELATED TASKS
“Setting block sizes” on page 115
“Defining QSAM files and records in COBOL” on page 107
“Allocating files” on page 105
RELATED REFERENCES
“Parameters for creating QSAM files”
OS/390 MVS JCL Reference
Parameters for creating QSAM files
The following DD statement parameters are frequently used to create QSAM files.
RELATED TASKS
“Defining and allocating QSAM files” on page 121
Retrieving QSAM files
|
|
You retrieve QSAM files, cataloged or not, by using job control statements or
environment variables.
Cataloged files
All data set information, such as volume and space, is stored in the catalog
and file label. All you have to code are the data set name and a
disposition. When you use a DD statement, this is the DSNAME parameter and
Chapter 8. Processing QSAM files
123
the DISP parameter. When you use an environment variable, this is the DSN
parameter and one of the parameters OLD, SHR, or MOD.
|
|
Noncataloged files
Some information is stored in the file label, but you must code the unit
and volume information as well as the dsname and disposition.
If you are using JCL, and you created the file in the current job step or in a
previous job step in the current job, you can refer to the previous DD statement for
most of the data set information. You do, however, need to code DSNAME and DISP.
|
RELATED REFERENCES
“Parameters for retrieving QSAM files”
Parameters for retrieving QSAM files
The following DD statement parameters are used to retrieve previously created files.
RELATED TASKS
“Retrieving QSAM files” on page 123
Ensuring file attributes match your program
When the fixed file attributes coded in the DD statement or the data set label for a
file and the attributes coded for that file in the SELECT and FD statements of your
COBOL program are not consistent, an OPEN statement in your program might not
work. Mismatches in the attributes for file organization, record format (fixed or
variable), record length, or the code set result in a file status code 39, and the OPEN
statement fails. An exception exists for files in the HFS: mismatches in record
format and record length do not cause an error.
|
|
To prevent common file status 39 problems, follow the guidelines listed below for
processing files that are existing, new, or dynamically created by COBOL.
124
Programming Guide
|
Remember that information in the JCL or environment variable overrides
information in the data set label.
Processing existing files
When your program processes an existing file, code the description of the file in
your COBOL program to be consistent with the file attributes of the data set. Use
these guidelines to define the maximum record length.
For this format
Specify this
V or S
Exactly 4 bytes smaller than the length attribute of the data set
F
Same as the length attribute of the data set
U
Same as the length attribute of the data set
Defining variable-length (format-V) records
The easiest way to define variable-length records in your program is to use RECORD
IS VARYING FROM integer-1 TO integer-2 in the FD entry and set an appropriate value
for integer-2. For example, assume that you have determined the length attribute of
the data set to be 104 (LRECL=104). Remembering that the maximum record length
is determined from the RECORD IS VARYING clause (in which values are set) and not
from the level-01 record descriptions, you could define a format-V file in your
program with this code:
FILE SECTION.
FD COMMUTER-FILE-MST
RECORDING MODE IS V
RECORD IS VARYING FROM 4 TO 100 CHARACTERS.
01 COMMUTER-RECORD-A
PIC X(4).
01 COMMUTER-RECORD-B
PIC X(75).
Defining format-U records
Assume that the existing file in the previous example was format-U instead of
format-V. If the 104 bytes are all user data, you could define the file in your
program with this code:
FILE SECTION.
FD COMMUTER-FILE-MST
RECORDING MODE IS U
RECORD IS VARYING FROM 4 TO 104 CHARACTERS.
01 COMMUTER-RECORD-A
PIC X(4).
01 COMMUTER-RECORD-B
PIC X(75).
Defining fixed-length records
To define fixed-length records in your program, use either the RECORD CONTAINS
integer clause, or omit this clause and code all level-01 record descriptions to be the
same fixed size. In either case, use a value that equals the value of the length
attribute of the data set. When you intend to use the same program to process
different files at run time and the files have differing fixed-length record lengths,
the recommended way to avoid record-length conflicts is to code RECORD CONTAINS
0.
If the existing file is an ASCII data set (DCB=(OPTCD=Q)), you must use the CODE-SET
clause in the program’s FD entry for the file.
Processing new files
|
When your COBOL program will write records to a new file that is made available
before the program is run, ensure that the file attributes you code in the DD
statement, the environment variable, or the allocation do not conflict with the
attributes you have coded in your program. Usually, you need to code only a
minimum of parameters when predefining your files.
Chapter 8. Processing QSAM files
125
When you do need to explicitly set a length attribute for the data set, (for example,
you are using an ISPF allocation panel or if your DD statement is for a batch job in
which the program uses RECORD CONTAINS 0):
v For format-V and format-S files, set a length attribute that is 4 bytes larger than
that defined in the program.
v For format-F and format-U files, set a length attribute that is the same as that
defined in the program.
v If you open your file as OUTPUT and write it to a printer, the compiler might add
1 byte to the record length to account for the carriage control character,
depending on the ADV compiler option and the COBOL language used in your
program. In such a case, take the added byte into account when coding the
LRECL.
For example, suppose your program contains the following code for a file with
variable-length records:
FILE SECTION.
FD COMMUTER-FILE-MST
RECORDING MODE IS V
RECORD CONTAINS 10 TO 50 CHARACTERS.
01 COMMUTER-RECORD-A
PIC X(10).
01 COMMUTER-RECORD-B
PIC X(50).
The LRECL in your DD statement or allocation should be 54.
Processing files dynamically created by COBOL
When you have not made a file available with a DD statement or a TSO ALLOCATE
command and your COBOL program defines that the file be created, COBOL for
OS/390 & VM dynamically allocates the file. When the file is opened, the file
attributes coded in your program are used. You do not have to worry about file
attribute conflicts.
RELATED TASKS
“Requesting fixed-length format” on page 109
“Requesting variable-length format” on page 110
“Requesting undefined format” on page 114
“Dynamically creating QSAM files with CBLQDA” on page 118
Using striped extended-format QSAM data sets
A striped extended-format QSAM data set is an extended-format QSAM data set
that is spread over multiple volumes, allowing parallel data access.
Striped extended-format QSAM data sets can benefit an application with these
characteristics:
v The application processes files that contain large volumes of data.
v The time for the input and output operations to the files significantly affects
overall performance.
For you to gain the maximum benefit from using QSAM striped data sets, DFSMS
needs to be able to allocate the required number of buffers above the 16-MB line.
When you develop applications that contain files allocated to QSAM striped data
sets, follow these guidelines:
v Avoid using a QSAM striped data set for a file that cannot have buffers
allocated above the 16-MB line.
126
Programming Guide
v Omit the RESERVE clause in the FILE-CONTROL paragraph entry for the file.
Omitting the RESERVE clause allows DFSMS to determine the optimum number
of buffers for the data set.
v Compile your program with the DATA(31) and RENT compiler options, and make
the load module AMODE 31.
v Specify the ALL31(ON) run-time option if the file is an EXTERNAL file with
format-F, format-V, or format-U records.
RELATED TASKS
OS/390 DFSMS: Using Data Sets (performance considerations)
RELATED REFERENCES
“Allocation of buffers for QSAM files”
Allocation of buffers for QSAM files
DFSMS automatically allocates buffers for storing input and output for QSAM files
above or below the 16-MB line as appropriate for the file being used. Most QSAM
files have buffers allocated above the 16-MB line. Exceptions are:
v Programs running in AMODE 24.
v Programs compiled with the DATA(24) and RENT options.
v Programs compiled with the NORENT and RMODE(24) options.
v Programs compiled with the NORENT and RMODE(AUTO) options.
v EXTERNAL files, when the ALL31(OFF) run-time option is being specified. To
specify the ALL31(ON) run-time option, all programs in the run unit must be
capable of running in 31-bit addressing mode.
v Files allocated to the TSO terminal.
v A file with format-S (spanned) records, if the file is any of the following:
– An EXTERNAL file (even if the ALL31(ON) option is specified).
– A file specified in a SAME RECORD AREA clause of the I-O-CONTROL paragraph.
– A blocked file that is opened I-O and updated using the REWRITE statement.
RELATED TASKS
“Using striped extended-format QSAM data sets” on page 126
Accessing HFS files using QSAM
|
|
|
You can process byte-stream files in the hierarchical file system (HFS) as COBOL
ORGANIZATION SEQUENTIAL files using QSAM. To do this, specify as the
assignment-name on the ASSIGN clause one of the following:
|
|
|
ddname
A DD allocation that identifies the file with the keywords PATH= and
FILEDATA=BINARY
|
|
|
Environment variable name
An environment variable with the run-time value of the HFS path for the
file
Restrictions and usage
|
|
|
|
Note the following restrictions:
v File status 39 (fixed file attribute conflict) is not enforced for either of the
following:
– Record-length conflict
– Record-type conflict (fixed vs. variable)
Chapter 8. Processing QSAM files
127
|
|
|
|
|
|
|
|
|
|
|
|
v Spanned record format is not supported.
v A READ returns the number of bytes equal to that of the maximum logical record
size for the file except for the last record, which might be shorter.
For example, suppose your file definition has 01 record descriptions of 3, 5, and
10 bytes long, and you write the following three records: ’abc’, ’defgh’, and
’ijklmnopqr’, in that order. Your first READ of this file returns ’abcdefghij’, your
second READ returns ’klmnopqr ’, and your third READ results in the AT END
condition.
v OPEN I-O and REWRITE are not supported. If you attempt one of these operations,
you will get the following file status conditions:
– 37 from OPEN I-O
– 47 from REWRITE (because you could not have opened the file I-O successfully)
|
|
|
|
|
For compatibility with earlier releases of COBOL, you can also specify
FILEDATA=TEXT when using a DD allocation for HFS files, but this use is not
recommended. To process text files in the HFS, use the LINE SEQUENTIAL
organization. If you do use QSAM to process text files in the HFS, you cannot use
environment variables to define the files.
RELATED TASKS
“Allocating files” on page 105
“Defining and allocating QSAM files” on page 121
Accessing HFS files via BSAM and QSAM (OS/390 DFSMS: Using Data Sets)
Identifying QSAM files to CMS
Under CMS, when you run a COBOL for OS/390 & VM program that has input or
output files or both, or you need to read an OS data set onto a CMS disk, you
must first identify the files to CMS with the FILEDEF command. The FILEDEF
command in CMS performs the same functions as the data definition (DD)
statement in OS/390 job control language (JCL): it describes the input and output
files.
For certain files, you also need to use the LABELDEF command.
Using FILEDEF
The FILEDEF command relates a ddname (file name) in your program with an
input or output device. If the FILEDEF command is issued for a program input or
output file, the ddname must be the same as the ddname or file name coded for
the file in the source program. Code the ddname in the ASSIGN clause of the SELECT
statement in the FILE CONTROL paragraph.
For example, suppose your program contains this code:
FILE-CONTROL.
SELECT INFILE
ASSIGN TO UR-2540R-S-CARDIN
SELECT OUTFILE
ASSIGN TO DA-3330-S-OUTDD.
. . .
FD INFILE
. . .
FD OUTFILE
. . .
128
Programming Guide
The ddname for INFILE is CARDIN, and the ddname for OUTFILE is OUTDD. These are
the names you use in the ddname portion of the FILEDEF command. If the input
file is to be read from your virtual card reader, your FILEDEF command might be:
FILEDEF CARDIN READER
Although you can read data sets from operating system (OS) disks when you run
COBOL programs in CMS, you cannot write files on the disks unless they are
VSAM files. You can, however, write OS simulated data sets on CMS disks, which
retain file characteristics of OS sequential data sets. To do this, use file-mode 4
when creating the files. You should use OS simulated data sets for files defined in
the COBOL program as blocked and with variable-length records.
When a program abends, or an HX Immediate command is issued during
execution, CMS automatically clears all FILEDEFs even if PERM has been specified.
Using LABELDEF
The LABELDEF command is required in addition to FILEDEF for certain files.
CMS multivolume tape files must be standard labeled tape files (SL or AL). Also,
the LABELDEF command must be used to sequentially identify the tape volumes that
compose the logical file.
If you are using OPEN EXTEND and standard labeled tapes, issue the LABELDEF
command with the FID option. For example:
FILEDEF OUTFILE TAP3 SL
LABELDEF OUTFILE FID EXTR4C
RELATED REFERENCES
The FILEDEF command (VM/ESA CMS Command Reference)
Labels for QSAM files
You can use labels to identify magnetic tape and direct access volumes and data
sets. The operating system uses label processing routines to identify and verify
labels and locate volumes and data sets.
There are two kinds of labels: standard and nonstandard. COBOL for OS/390 &
VM does not support nonstandard user labels. In addition, standard user labels
contain user-specified information about the associated data set.
Standard labels consist of volume labels and groups of data set labels. Volume
labels precede or follow data on the volume, and identify and describe the volume.
The data set labels precede or follow each data set on the volume, and identify and
describe the data set.
v The data set labels that precede the data set are called header labels.
v The data set labels that follow the data set are called trailer labels.
They are similar to the header labels, except that they also contain a count of
blocks in the data set.
v The data set label groups can optionally include standard user labels.
v The volume label groups can optionally include standard user labels.
RELATED TASKS
“Using trailer and header labels” on page 130
Chapter 8. Processing QSAM files
129
RELATED REFERENCES
“Format of standard labels” on page 131
Using trailer and header labels
You can create, examine, or update user labels when the beginning or end of a
data set or volume (reel) is reached. End-of-volume or beginning-of-volume exits
are allowed. You can also create or examine intermediate trailers and headers.
You can create, examine, or update up to eight header labels and eight trailer
labels on each volume of the data set. (QSAM EXTEND works in a manner identical
to OUTPUT except that the beginning-of-file label is not processed.) Labels reside on
the initial volume of a multivolume data set. This volume must be mounted as
CLOSE if trailer labels are to be created, examined, or updated. Trailer labels for files
opened as INPUT or I-O are processed when a CLOSE statement is performed for the
file that has reached an AT END condition.
If you code a header or trailer with the wrong position number, the result is
unpredictable. (Data management might force the label to the correct relative
position.)
When you use standard label processing, code the label type of the standard and
user labels (SUL) on the DD statement that describes the data set.
Getting a user-label track
If you use a LABEL subparameter of SUL for direct access volumes, a separate
user-label track will be allocated when the data set is created. This additional track
is allocated at initial allocation and for sequential data sets at end-of-volume
(volume switch). The user-label track (one per volume of a sequential data set) will
contain both user header and user trailer labels. If a LABEL name is referenced
outside the user LABEL declarative, results are unpredictable.
Handling user labels
The USE AFTER LABEL declarative provides procedures for handling user labels on
supported files. The AFTER option indicates processing of standard user labels.
List the labels as data-names in the LABEL RECORDS clause in the FD entry for the file.
When the file is
opened as:
And:
Result:
INPUT
USE . . . LABEL declarative is
coded for the OPEN option or for
the file.
The label is read and control is
passed to the LABEL declarative.
OUTPUT
USE . . . LABEL declarative is
coded for the OPEN option or for
the file.
A buffer area for the label is
provided and control is passed to
the LABEL declarative.
INPUT or I-O
CLOSE statement is performed
for the file that has reached the
AT END condition.
Control is passed to the LABEL
declarative for processing trailer
labels.
You can specify a special exit by using the statement GO TO MORE-LABELS. When
this statement results in an exit from a label DECLARATIVE SECTION, the system does
one of the following:
v Writes the current beginning or ending label and then reenters the USE section at
its beginning to create more labels. After creating the last label, the system exits
by performing the last statement of the section.
130
Programming Guide
v Reads an additional beginning or ending label, and then reenters the USE section
at its beginning to check more labels. When processing user labels, the system
reenters the section only if there is another user label to check. Hence, a program
path that flows through the last statement in the section is not needed.
If a GO TO MORE-LABELS statement is not performed for a user label, the
DECLARATIVE SECTION is not reentered to check or create any immediately
succeeding user labels.
RELATED CONCEPTS
“Labels for QSAM files” on page 129
Format of standard labels
Standard labels are 80-character records that are recorded in EBCDIC or ASCII. The
first four characters are always used to identify the labels. The figure below shows
these identifiers for tape.
Identifier
Description
VOL1
Volume label
HDR1 or HDR2
Data set header labels
EOV1 or EOV2
Data set trailer labels (end-of-volume)
EOF1 or EOF2
Data set trailer labels (end-of-data-set)
UHL1 to UHL8
User header labels
UTL1 to UTL8
User trailer labels
The format of the label for a direct-access volume is the almost the same as the
format of the label group for a tape volume label group. The difference is that a
data set label of the initial DASTO volume label consists of the data set control
block (DSCB). The DSCB appears in the volume table of contents (VTOC) and
contains the equivalent of the tape data set header and trailer, in addition to
control information such as space allocation.
Standard user labels
User labels are optional within the standard label groups.
The format used for user header labels (UHL1-8) and user trailer labels (UTL1-8)
consists of a label 80 characters in length recorded in either:
v EBCDIC on DASD or on IBM standard labeled tapes, or
v ASCII on ANSI/ISO/FIPS labeled tapes
The first 3 bytes consist of the characters that identify the label as either:
v UHL for a user header label (at the beginning of a data set), or
v UTL for a user trailer label (at the end-of-volume or end-of-data set)
The next byte contains the relative position of this label within a set of labels of the
same type. One through eight labels are permitted.
The remaining 76 bytes consist of user-specified information.
Standard user labels are not supported for QSAM striped data sets.
RELATED CONCEPTS
“Labels for QSAM files” on page 129
Chapter 8. Processing QSAM files
131
Processing QSAM ASCII files on tape
If your program processes an QSAM ASCII file, do the following:
1. Request the ASCII alphabet.
2. Define the record formats.
3. Define the ddname (JCL for OS/390 or FILEDEF for CMS).
In addition, if your program processes numeric data items from ASCII files, use the
separately signed numeric data type (SIGN IS LEADING SEPARATE).
Requesting the ASCII alphabet
In the SPECIAL-NAMES paragraph, code STANDARD-1 for ASCII:
ALPHABET-NAME IS STANDARD-1
In the FD statement for the file, code:
CODE-SET IS ALPHABET-NAME
Defining the record formats
Process QSAM ASCII tape files with any of these record formats:
v Fixed length (format F)
v Undefined (format U)
v Variable length (format V)
If you are using variable-length records, you cannot explicitly code format D;
instead, code RECORDING MODE V. The format information is internally converted to
D mode. D-mode records have a 4-byte record descriptor for each record.
Defining the ddname
Under OS/390, processing ASCII files requires special JCL coding. Code these
subparameters of the DCB parameter in the DD statement:
BUFOFF=[L|n]
L
A 4-byte block prefix that contains the block length (including the
block prefix).
n
The length of the block prefix:
v For input, from 0 through 99
v For output, either 0 or 4
Use this value if you coded BLOCK CONTAINS 0.
BLKSIZE=n
n
The size of the block, including the length of the block prefix.
LABEL=[AL|AUL|NL]
132
Programming Guide
AL
American National Standard (ANS) labels.
AUL
ANS and user labels.
NL
No labels.
OPTCD=Q
Q
This value is required for ASCII files, and is the default if the file
was created using COBOL for OS/390 & VM.
RELATED TASKS
“Processing ASCII file labels”
Processing ASCII file labels
Standard label processing for ASCII files is the same as standard label processing
for EBCDIC files. The system translates ASCII code into EBCDIC before processing.
All ANS user labels are optional. ASCII files can have user header labels (UHLn)
and user trailer labels (UTLn). There is no limit to the number of user labels at the
beginning and the end of a file; you can write as many labels as you need. All user
labels must be 80 bytes in length.
To create or verify user labels (user label exit), code a USE AFTER STANDARD LABEL
procedure. You cannot use USE BEFORE STANDARD LABEL procedures. Under CMS,
code the OPTCD=Q option on the FILEDEF command for ASCII files.
ASCII files on tape can have:
v ANS labels
v ANS and user labels
v No labels
Any labels on an ASCII tape must be in ASCII code only. Tapes containing a
combination of ASCII and EBCDIC cannot be read.
RELATED TASKS
“Processing QSAM ASCII files on tape” on page 132
Chapter 8. Processing QSAM files
133
134
Programming Guide
Chapter 9. Processing VSAM files
Virtual storage access method (VSAM) is an access method for files on
direct-access storage devices. With VSAM you can:
v Load a file
v Retrieve records from a file
v Update a file
v Add, replace, and delete records in a file
VSAM processing has these advantages over QSAM:
v Protection of data against unauthorized access
v Compatibility across systems
v Independence of devices (no need to be concerned with block size and other
control information)
v Simpler JCL (information needed by the system is provided in integrated
catalogs)
v Ability to use indexed file organization or relative file organization
The lists below show how VSAM terms differ from COBOL terms and other terms
that you might be familiar with.
VSAM term
Data set
Entry-sequenced data set (ESDS)
Key-sequenced data set (KSDS)
Relative-record data set (RRDS)
Control interval size (CISZ)
Buffers (BUFNI/BUFND)
Access method control block (ACB)
Cluster (CL)
Cluster definition
AMP parameter of JCL DD statement
Record size
COBOL term
File
Sequential file
Indexed file
Relative file
Similar non-VSAM term
Data set
QSAM data set
ISAM data set
BDAM data set
Block size
BUFNO
Data control block (DCB)
Data set
Data set allocation
DCB parameter of JCL DD statement
Record length
The term file in this VSAM information refers to either a COBOL file or a VSAM
data set.
If you have complex requirements or frequently use VSAM, review the VSAM
publications for your operating system.
RELATED TASKS
“Defining VSAM file organization and records” on page 137
“Coding input and output statements for VSAM files” on page 143
“Protecting VSAM files with a password” on page 151
“Handling errors in VSAM files” on page 151
“Working with VSAM data sets under OS/390 and OS/390 UNIX” on page 152
“Defining VSAM data sets under CMS” on page 158
“Improving VSAM performance” on page 159
© Copyright IBM Corp. 1991, 2000
135
RELATED REFERENCES
OS/390 DFSMS: Using Data Sets
OS/390 DFSMS: Macro Instructions for Data Sets
OS/390 DFSMS: Access Method Services for Catalogs
VSAM Administration: Macro Instruction Reference
VSAM files
The physical organization of VSAM data sets differs considerably from those used
by other access methods. VSAM data sets are held in control intervals and control
areas (CA). The size of these is normally determined by the access method, and the
way in which they are used is not visible to you.
You can use three types of file organization with VSAM.
VSAM sequential file organization
(Also referred to as VSAM ESDS (entry-sequenced data set) organization.)
In VSAM sequential file organization, the records are stored in the order in
which they were entered. VSAM entry-sequenced data sets are equivalent
to QSAM sequential files. The order of the records is fixed.
VSAM indexed file organization
(Also referred to as VSAM KSDS (key-sequenced data set) organization.) In
a VSAM indexed file (KSDS), the records are ordered according to the
collating sequence of an embedded prime key field, which you define. The
prime key consists of one or more consecutive characters in the records.
The prime key uniquely identifies the record and determines the sequence
in which it is accessed with respect to other records. A prime key for a
record might be, for example, an employee number or an invoice number.
VSAM relative file organization
(Also referred to as VSAM fixed-length or variable-length RRDS
(relative-record data set) organization.) A VSAM relative record data set
(RRDS) contains records ordered by their relative key. The relative key is
the relative record number that represents the location of the record
relative to where the file begins. The relative record number identifies the
fixed- or variable-length record.
In a VSAM fixed-length RRDS, records are placed in a series of
fixed-length slots in storage. Each slot is associated with a relative record
number. For example, in a fixed-length RRDS containing 10 slots, the first
slot has a relative record number of 1, and the tenth slot has a relative
record number of 10.
In a VSAM variable-length RRDS, the records are ordered according to
their relative record number. Records are stored and retrieved according to
the relative record number that you set.
Throughout this documentation, the term VSAM relative-record data set (or
RRDS) is used to mean both relative-record data sets with fixed-length
records and with variable-length records, unless they need to be
differentiated.
The following table compares the different types of VSAM data sets in terms of
several characteristics.
136
Programming Guide
Entry-sequenced data set
(ESDS)
Key-sequenced data set
(KSDS)
Relative-record data set
(RRDS)
Order of records
Order in which they are
written
Collating sequence by key
field
Order of relative record
number
Access
Sequential
By key through an index
By relative record number,
which is handled like a key
Alternate indexes
Can have one or more
alternate indexes, although
not supported in COBOL
Can have one or more
alternate indexes
Cannot have alternate indexes
Relative byte
address (RBA) and
relative record
number (RRN) of a
record
RBA cannot change.
RBA can change.
RRN cannot change.
Space for adding
records
Uses space at the end of the
data set
Uses distributed free space
for inserting records and
changing their lengths in
place
For fixed-length RRDS, uses
empty slots in the data set
Space from deleting You cannot delete a record,
records
but you can reuse its space
for a record of the same
length.
Space from a deleted or
shortened record is
automatically reclaimed in a
control interval.
Space from a deleted record
can be reused.
Spanned records
Can have spanned records
Can have spanned records
Cannot have spanned records
Reuse as work file
Can be reused unless it has
an alternate index, is
associated with key ranges, or
exceeds 123 extents per
volume
Can be reused
Can be reused unless it has
an alternate index, is
associated with key ranges, or
exceeds 123 extents per
volume
Characteristic
For variable-length RRDS, uses
distributed free space and
changes the lengths of added
records in place
RELATED TASKS
“Specifying sequential organization for VSAM files” on page 138
“Specifying indexed organization for VSAM files” on page 138
“Specifying relative organization for VSAM files” on page 139
“Defining VSAM files under OS/390” on page 153
“Defining VSAM data sets under CMS” on page 158
Defining VSAM file organization and records
Use the FILE-CONTROL entry in the ENVIRONMENT DIVISION to define the VSAM file
organization and access modes for the files in your COBOL program.
In the FILE SECTION of the DATA DIVISION, code a file description (FD) entry for the
file. In the associated record description entry or entries, define the record-name and
record length. Code the logical size of the records with the RECORD clause.
Important: You can process VSAM data sets in COBOL for OS/390 & VM
programs only after you define them with access method services.
The following table summarizes VSAM file organization, access modes, and record
formats (fixed or variable length).
Chapter 9. Processing VSAM files
137
Sequential
access
Random
access
Dynamic
access
Fixed
length
Variable
length
VSAM sequential
(ESDS)
Yes
No
No
Yes
Yes
VSAM indexed
(KSDS)
Yes
Yes
Yes
Yes
Yes
VSAM relative
(RRDS)
Yes
Yes
Yes
Yes
Yes
File organization
RELATED TASKS
“Specifying sequential organization for VSAM files”
“Specifying indexed organization for VSAM files”
“Specifying relative organization for VSAM files” on page 139
“Using file status keys” on page 194
“Using VSAM return codes (VSAM files only)” on page 196
“Defining VSAM files under OS/390” on page 153
“Defining VSAM data sets under CMS” on page 158
“Specifying access modes for VSAM files” on page 141
Specifying sequential organization for VSAM files
Identify VSAM ESDS files in your COBOL program with the ORGANIZATION IS
SEQUENTIAL clause.
You can access (read or write) records in sequential files only sequentially.
After you place a record in the file, you cannot shorten, lengthen, or delete it.
However, you can update (REWRITE) a record if the length does not change. New
records are added at the end of the file.
The following example shows typical FILE-CONTROL entries for a VSAM sequential
file (ESDS):
SELECT S-FILE
ASSIGN TO SEQUENTIAL-AS-FILE
ORGANIZATION IS SEQUENTIAL
ACCESS IS SEQUENTIAL
FILE STATUS IS FSTAT-CODE VSAM-CODE.
RELATED CONCEPTS
“VSAM files” on page 136
Specifying indexed organization for VSAM files
Identify VSAM KSDS in your COBOL program with the ORGANIZATION IS INDEXED
clause.
Code a prime key for the record by using the clause:
RECORD KEY IS data-name
where data-name is the name of the key field as you defined it in the record
description entry in the DATA DIVISION.
The following example shows the statements for a VSAM indexed file (KSDS) that
is accessed dynamically. In addition to the primary key, COMMUTER-NO, there is an
alternate key, LOCATION-NO:
138
Programming Guide
SELECT I-FILE
ASSIGN TO INDEXED-FILE
ORGANIZATION IS INDEXED
ACCESS IS DYNAMIC
RECORD KEY IS IFILE-RECORD-KEY
ALTERNATE RECORD KEY IS IFILE-ALTREC-KEY
FILE STATUS IS FSTAT-CODE VSAM-CODE.
Alternate keys
In addition to the primary key, you can also code one or more alternate keys to use
for retrieving records. Using alternate keys, you can access the indexed file to read
records in some sequence other than the prime key sequence. For example, you
could access the file through employee department rather than through employee
number. Alternate keys need not be unique. More than one record will be accessed,
given a department number as a key. This is permitted if alternate keys are coded
to allow duplicates.
You define the alternate key in your COBOL program with the ALTERNATE RECORD
KEY clause:
ALTERNATE RECORD KEY IS data-name
Here data-name is the name of the key field as you defined it in the record
description entry in the DATA DIVISION.
Alternate index
To use an alternate index, you need to define a data set (using access method
services) called the alternate index (AIX). The AIX contains one record for each
value of a given alternate key; the records are in sequential order by alternate key
value. Each record contains the corresponding primary keys of all records in the
associated indexed files that contain the alternate key value.
RELATED CONCEPTS
“VSAM files” on page 136
RELATED TASKS
“Creating alternate indexes” on page 154
Specifying relative organization for VSAM files
Identify VSAM RRDS files in your COBOL program with the ORGANIZATION IS
RELATIVE clause.
Use the RELATIVE KEY IS clause to associate each logical record with its relative
record number.
The following example shows a relative-record data set (RRDS) that is accessed
randomly by the value in the relative key ITEM-NO:
SELECT R-FILE
ASSIGN TO RELATIVE-FILE
ORGANIZATION IS RELATIVE
ACCESS IS RANDOM
RELATIVE KEY IS RFILE-RELATIVE-KEY
FILE STATUS IS FSTAT-CODE VSAM-CODE.
You can use a randomizing routine to associate a key value in each record with the
relative record number for that record. Although there are many techniques to
convert a record key to a relative record number, the most commonly used
randomizing algorithm is the division/remainder technique. With this technique,
Chapter 9. Processing VSAM files
139
you divide the key by a value equal to the number of slots in the data set to
produce a quotient and remainder. When you add one to the remainder, the result
will be a valid relative record number.
Alternate indexes are not supported for VSAM RRDS.
Fixed-length and variable-length RRDS
In an RRDS with fixed-length records, each record occupies one slot, and you store
and retrieve records according to the relative record number of that slot. When you
load the file, you have the option of skipping over slots and leaving them empty.
When you load an RRDS with variable-length records, you can skip over relative
record numbers. Unlike fixed-length RRDS, a variable-length RRDS does not have
slots. Instead, the free space that you define allows for more efficient record
insertions.
VSAM variable-length RRDS is supported on OS/390 and VM/ESA.
Simulating variable-length RRDS
If you cannot use VSAM variable-length RRDS or prefer not to, COBOL for
OS/390 & VM provides another way for you to have relative-record data sets with
variable-length records. This support, called COBOL simulated variable-length RRDS,
is provided by the SIMVRD|NOSIMVRD run-time option. When you use the SIMVRD
option, COBOL for OS/390 & VM simulates variable-length RRDS using a VSAM
KSDS.
The coding you use in your COBOL program to identify and describe VSAM
variable-length RRDS and COBOL simulated variable-length RRDS is similar. How
you use the SIMVRD run-time option and whether you define the VSAM file as a
RRDS or KSDS differs, however.
To use a variable-length RRDS, do the following steps, depending on the whether
you want to simulate an RRDS:
COBOL simulated variable-length
RRDS
Step
VSAM variable-length RRDS
1
Define the file in your COBOL program Same
with the ORGANIZATION IS RELATIVE
clause.
2
Use FD statements in your COBOL
program to describe the records with
variable-length sizes.
Same
3
Use the NOSIMVRD run-time option.
Use the SIMVRD run-time option.
4
Define the VSAM file through access
method services as an RRDS.
Define the VSAM file through access
method services as a KSDS with a
4-byte key.
RELATED CONCEPTS
“VSAM files” on page 136
RELATED TASKS
“Defining VSAM files under OS/390” on page 153
140
Programming Guide
Specifying access modes for VSAM files
You can access records in VSAM sequential files only sequentially. You can access
records in VSAM indexed and relative files in three ways: sequentially, randomly,
or dynamically.
For sequential access, code ACCESS IS SEQUENTIAL in the FILE-CONTROL entry.
Records in indexed files are then accessed in the order of the key field selected
(either primary or alternate). Records in relative files are accessed in the order of
the relative record numbers.
For random access, code ACCESS IS RANDOM in the FILE-CONTROL entry. Records in
indexed files are then accessed according to the value you place in a key field.
Records in relative files are accessed according to the value you place in the
relative key.
For dynamic access, code ACCESS IS DYNAMIC in the FILE-CONTROL entry. Dynamic
access is a mixed sequential-random access in the same program. Using dynamic
access, you can write one program to perform both sequential and random
processing, accessing some records in sequential order and others by their keys.
“Example: using dynamic access with VSAM files”
RELATED TASKS
“Reading records from a VSAM file” on page 147
Example: using dynamic access with VSAM files
Suppose that you have an indexed file of employee records and the employee’s
hourly wage forms the record key. Your program is processing those employees
who earn between $10.00 and $12.00 per hour and those who earn $20.00 per hour
and above.
Using dynamic access of VSAM files, the program would do as follows:
1. Retrieve the first record randomly (with a random-retrieval READ) based on the
key of 1000.
2. Read sequentially (using READ NEXT) until the salary field exceeds 1200.
3. Retrieve the next record randomly, this time based on a key of 2000.
4. Read sequentially until the end of the file.
RELATED TASKS
“Reading records from a VSAM file” on page 147
Defining record lengths for VSAM files
VSAM records can be fixed or variable in length. COBOL determines the record
format from the RECORD clause and the record descriptions associated with your FD
entry for the file.
Because the concept of blocking has no meaning for VSAM files, you can omit the
BLOCK CONTAINS clause. The clause is syntax-checked, but it has no effect on how
the program runs.
Chapter 9. Processing VSAM files
141
Defining fixed-length records
To define the records to be fixed length, use one of the following coding options:
RECORD clause
Code RECORD CONTAINS
integer
Clause
format
1
Omit the RECORD clause,
but code all level-01
records (associated with
the file) as the same size
and none with an OCCURS
DEPENDING ON clause.
Record length
Comments
Fixed in size with a
length of integer-2
The lengths of the
level-01 record
description entries
associated with the file
do not matter.
The fixed size that you
coded
Defining variable-length records
To define the records to be variable-length, use one of the following coding
options:
Clause
format
Maximum record length
Comments
Code RECORD IS VARYING
FROM integer-1 TO
integer-2
3
integer-2 value
The lengths of the
level-01 record
description entries
associated with the file
do not matter.
Code RECORD IS VARYING
3
Size of the largest level-01 The compiler determines
record description entry
the maximum record
associated with the file
length.
Code RECORD CONTAINS
integer-1 TO integer-2
2
integer-2 value
RECORD clause
Omit the RECORD clause,
but code multiple level-01
records (associated with
the file) that are of
different sizes or that
contain an OCCURS
DEPENDING ON clause.
The minimum record
length is the integer-2
value.
Size of the largest level-01 The compiler determines
record description entry
the maximum record
associated with the file
length.
The RECORD clause is sensitive to the CMPR2 compiler option.
When you specify a READ INTO statement for a format-V file, the record size read
for that file is used in the MOVE statement generated by the compiler. Consequently,
you might not get the result you expect if the record read in does not correspond
to the level-01 record description. All other rules of the MOVE statement apply. For
example, when you specify a MOVE statement for a format-V record read in by the
READ statement, the size of the record corresponds to its level-01 record description.
RELATED TASKS
COBOL for OS/390 & VM Compiler and Run-Time Migration Guide
142
Programming Guide
Coding input and output statements for VSAM files
Use these COBOL statements for processing VSAM files:
OPEN
To connect the VSAM data set to your COBOL program for processing.
WRITE
To add records to a file or load a file.
START
To establish the current location in the cluster for a READ NEXT statement.
START does not retrieve a record; it only sets the current record pointer.
READ and READ NEXT
To retrieve records from a file.
REWRITE
To update records.
DELETE To logically remove records from indexed and relative files only.
CLOSE
To disconnect the VSAM data set from your program.
All of the following factors determine which input and output statements you can
use for a given VSAM data set:
v Access mode (sequential, random, or dynamic)
v File organization (ESDS, KSDS, or RRDS)
v Mode of OPEN statement (INPUT, OUTPUT, I-O, or EXTEND)
The following table shows the possible combinations with sequential files (ESDS).
The X indicates that you can use the statement with the open mode at the top of
the column.
Access mode
COBOL
statement
Sequential
OPEN
OPEN
INPUT
OPEN
OUTPUT
OPEN
I-O
OPEN
EXTEND
X
X
X
X
WRITE
X
X
START
READ
X
X
REWRITE
X
DELETE
CLOSE
X
X
X
X
The following table shows the possible combinations you can use with indexed
(KSDS) files and relative (RRDS) files. The X indicates that you can use the
statement with the open mode at the top of the column.
Chapter 9. Processing VSAM files
143
Access mode
COBOL
statement
Sequential
OPEN
OPEN
INPUT
OPEN
OUTPUT
OPEN
I-O
OPEN
EXTEND
X
X
X
X
WRITE
Random
X
X
START
X
X
READ
X
X
REWRITE
X
DELETE
X
CLOSE
X
X
X
OPEN
X
X
X
X
X
WRITE
X
START
READ
Dynamic
X
X
REWRITE
X
DELETE
X
CLOSE
X
X
X
OPEN
X
X
X
X
X
WRITE
START
X
X
READ
X
X
REWRITE
X
DELETE
X
CLOSE
X
X
X
The fields you code in the FILE STATUS clause are updated by VSAM after each
input-output statement to indicate the success or failure of the operation.
RELATED CONCEPTS
“File position indicator”
RELATED TASKS
“Opening a file (ESDS, KSDS, or RRDS)” on page 145
“Reading records from a VSAM file” on page 147
“Updating records in a VSAM file” on page 148
“Adding records to a VSAM file” on page 149
“Replacing records in a VSAM file” on page 149
“Deleting records from a VSAM file” on page 150
“Closing VSAM files” on page 150
File position indicator
The file position indicator marks the next record to be accessed for sequential
COBOL requests. You do not set the file position indicator anywhere in your
program; it is set by successful OPEN, START, READ, and READ NEXT statements.
Subsequent READ or READ NEXT requests use the established file position indicator
location and update it.
144
Programming Guide
The file position indicator is not used or affected by the output statements WRITE,
REWRITE, or DELETE. The file position indicator has no meaning for random
processing.
RELATED TASKS
“Reading records from a VSAM file” on page 147
Opening a file (ESDS, KSDS, or RRDS)
Before you can use any WRITE, START, READ, REWRITE, or DELETE statements to
process records in a file, you must first open the file with an OPEN statement. File
availability and creation affect OPEN processing, optional files, and file status codes
05 and 35.
For example, if you OPEN EXTEND, OPEN I-O, or OPEN INPUT a file that is neither
optional nor available, you get file status 35 and the OPEN statement fails. If the file
is OPTIONAL, the OPEN EXTEND, OPEN I-O, or OPEN INPUT creates the file and returns
file status 05.
An OPEN operation works successfully only when you set fixed file attributes in the
DD statement or data set label for a file and specify consistent attributes for that file
in the SELECT and FD statements of your COBOL program. Mismatches in the
following items result in a file status code 39, and the OPEN statement fails:
v Attributes for file organization (sequential, relative, or indexed)
v Prime record key
v Alternate record keys
v Maximum record size
v Record type (fixed or variable)
How you code the OPEN statement in your COBOL program for a VSAM file
depends on whether the file is empty (a file that has never contained records) or
loaded. For either type of file, your program should check the file status key after
each OPEN statement.
RELATED TASKS
“Opening an empty file”
“Opening a loaded file (a file with records)” on page 147
RELATED REFERENCES
“Statements to load records into a VSAM file” on page 147
Opening an empty file
To open a file that has never contained records (an empty file), use the following
statements depending on the type of file:
v OPEN OUTPUT for ESDS files.
v OPEN OUTPUT or OPEN EXTEND for KSDS and RRDS files. (Either coding has the
same effect.) If you have coded the file for random or dynamic access and the
file is optional, you can use OPEN I-O.
Optional files are files that are not necessarily present each time the program is
run. You can define files opened in INPUT, I-O, or OUTPUT mode as optional by
defining them with the SELECT OPTIONAL phrase in the FILE-CONTROL section of
your program.
Chapter 9. Processing VSAM files
145
Initially loading records sequentially into a file: Initially loading a file means
writing records into the file for the first time. This is not the same as writing
records into a file from which all previous records have been deleted.
To
1.
2.
3.
initially load a VSAM file:
Open the file.
Use sequential processing (ACCESS IS SEQUENTIAL) because it is faster.
Use WRITE to add a record to the file.
Using OPEN OUTPUT to load a VSAM file significantly improves the performance of
your program. Using OPEN I-O or OPEN EXTEND has a negative impact on the
performance of your program.
When you load VSAM indexed files sequentially, you optimize both loading
performance and subsequent processing performance, because sequential
processing maintains user-defined free space. Future insertions will be more
efficient.
With ACCESS IS SEQUENTIAL, you must write the records in ascending RECORD KEY
order.
When you load VSAM relative files sequentially, the records are placed in the file
in the ascending order of relative record numbers.
Initially loading a file randomly or dynamically: You can use random or
dynamic processing to load a file, but they are not as efficient as sequential
processing. Because VSAM does not support random or dynamic processing,
COBOL has to perform some extra processing to enable you to use ACCESS IS
RANDOM or ACCESS IS DYNAMIC with OPEN OUTPUT or OPEN I-O. These steps prepare
the file for use and give it the status of a loaded file, having been used at least
once.
In addition to extra overhead for preparing files for use, random processing does
not consider any user-defined free space. As a result, any future insertions might
be inefficient. Sequential processing maintains user-defined free space.
Loading a VSAM data set with access method services: You can load or update
a VSAM data set with the access method services REPRO command. Use REPRO
whenever possible.
RELATED TASKS
“Opening a loaded file (a file with records)” on page 147
RELATED REFERENCES
“Statements to load records into a VSAM file” on page 147
REPRO (OS/390 DFSMS: Access Method Services for Catalogs)
146
Programming Guide
Statements to load records into a VSAM file
Division
ESDS
KSDS
RRDS
ENVIRONMENT
DIVISION
SELECT
ASSIGN
FILE STATUS
PASSWORD
ACCESS MODE
SELECT
ASSIGN
ORGANIZATION IS INDEXED
RECORD KEY
ALTERNATE RECORD KEY
FILE STATUS
PASSWORD
ACCESS MODE
SELECT
ASSIGN
ORGANIZATION IS
RELATIVE
RELATIVE KEY
FILE STATUS
PASSWORD
ACCESS MODE
DATA
DIVISION
FD entry
FD entry
FD entry
PROCEDURE
DIVISION
OPEN OUTPUT
OPEN EXTEND
WRITE
CLOSE
OPEN OUTPUT
OPEN EXTEND
WRITE
CLOSE
OPEN OUTPUT
OPEN EXTEND
WRITE
CLOSE
RELATED TASKS
“Opening an empty file” on page 145
“Updating records in a VSAM file” on page 148
Opening a loaded file (a file with records)
To open a file that already contains records, use OPEN INPUT, OPEN I-O, or OPEN
EXTEND.
If you open a VSAM entry-sequenced or relative-record file as EXTEND, the added
records are placed after the last existing records in the file.
If you open a VSAM key-sequenced file as EXTEND, each record you add must have
a record key higher than the highest record in the file.
RELATED TASKS
“Opening an empty file” on page 145
“Working with VSAM data sets under OS/390 and OS/390 UNIX” on page 152
“Defining VSAM data sets under CMS” on page 158
RELATED REFERENCES
“Statements to load records into a VSAM file”
Access Method Services Reference
Reading records from a VSAM file
Use the READ statement to retrieve (READ) records from a file. To read a record, you
must have opened the file INPUT or I-O. Your program should check the file status
key after each READ.
You can retrieve records in VSAM sequential files only in the sequence in which
they were written.
You can retrieve records in VSAM indexed and relative record files in any of the
following ways:
Sequentially
According to the ascending order of the key you are using, the RECORD KEY
Chapter 9. Processing VSAM files
147
or the ALTERNATE RECORD KEY, beginning at the current position of the file
position indicator for indexed files, or according to ascending relative
record locations for relative files.
Randomly
In any order, depending on how you set the RECORD KEY or ALTERNATE
RECORD KEY or the RELATIVE KEY before your READ request.
Dynamically
Mixed sequential and random.
With dynamic access, you can switch between reading a specific record directly
and reading records sequentially, by using READ NEXT for sequential retrieval and
READ for random retrieval (by key).
When you want to read sequentially, beginning at a specific record, use START
before the READ NEXT statement to set the file position indicator to point to a
particular record. When you code START followed by READ NEXT, the next record is
read and the file position indicator is reset to the next record. You can move the
file position indicator randomly by using START, but all reading is done
sequentially from that point.
START file-name KEY IS EQUAL TO ALTERNATE-RECORD-KEY
When a direct READ is performed for a VSAM indexed file, based on an alternate
index for which duplicates exist, only the first record in the data set (base cluster)
with that alternate key value is retrieved. You need a series of READ NEXT
statements to retrieve each of the data set records with the same alternate key. A
file status code of 02 is returned if there are more records with the same alternate
key value to be read; a code of 00 is returned when the last record with that key
value has been read.
RELATED CONCEPTS
“File position indicator” on page 144
RELATED TASKS
“Specifying access modes for VSAM files” on page 141
Updating records in a VSAM file
To update a VSAM file, use the ENVIRONMENT DIVISION and DATA DIVISION
statements to load records into a VSAM file and the following PROCEDURE DIVISION
statements to update VSAM files.
Access
method
ACCESS IS
SEQUENTIAL
148
Programming Guide
ESDS
KSDS
RRDS
OPEN EXTEND
WRITE
CLOSE
or
OPEN I-O
READ
REWRITE
CLOSE
OPEN EXTEND
WRITE
CLOSE
or
OPEN I-O
READ
REWRITE
DELETE
CLOSE
OPEN EXTEND
WRITE
CLOSE
or
OPEN I-O
READ
REWRITE
DELETE
CLOSE
Access
method
ESDS
KSDS
RRDS
ACCESS IS
RANDOM
Not applicable
OPEN I-O
READ
WRITE
REWRITE
DELETE
CLOSE
OPEN I-O
READ
WRITE
REWRITE
DELETE
CLOSE
ACCESS IS
DYNAMIC
(sequential
processing)
Not applicable
OPEN I-O
READ NEXT
WRITE
REWRITE
START
DELETE
CLOSE
OPEN I-O
READ NEXT
WRITE
REWRITE
START
DELETE
CLOSE
ACCESS IS
DYNAMIC
(random
processing)
Not applicable
OPEN I-O
READ
WRITE
REWRITE
DELETE
CLOSE
OPEN I-O
READ
WRITE
REWRITE
DELETE
CLOSE
RELATED REFERENCES
“Statements to load records into a VSAM file” on page 147
Adding records to a VSAM file
Use the COBOL WRITE statement to add a record to a file without replacing any
existing records. The record to be added must not be larger than the maximum
record size that you set when you defined the file. Your program should check the
file status key after each WRITE statement.
Adding records sequentially
Use ACCESS IS SEQUENTIAL and code the WRITE statement to add records
sequentially to the end of a VSAM file that has been opened with either OUTPUT or
EXTEND.
Sequential files are always written sequentially.
For indexed files, you must write new records in ascending key sequence. If you
open the file EXTEND, the record keys of the records to be added must be higher
than the highest primary record key on the file when you opened the file.
For relative files, the records must be in sequence. If you include a RELATIVE KEY
data-item in the SELECT clause, the relative record number of the record to be
written is placed in that data item.
Adding records randomly or dynamically
When you write records to an indexed data set and ACCESS IS RANDOM or ACCESS IS
DYNAMIC, you can write the records in any order.
Replacing records in a VSAM file
To replace records in a VSAM file, use REWRITE on a file that you have opened for
I-O. If you try to use REWRITE on a file that is not opened I-O, the record is not
rewritten and the status key is set to 49. Your program should check the file status
key after each REWRITE statement.
Chapter 9. Processing VSAM files
149
v For sequential files, the length of the record you rewrite must be the same as the
length of the original record.
v For indexed files, you can change the length of the record you rewrite.
v For variable-length relative files, you can change the length of the record you
rewrite.
To replace records randomly or dynamically, your program need not read the
record to be rewritten. Instead, to position the record that you want to update, do
as follows:
v For indexed files, move the record key to the RECORD KEY data item and then
issue the REWRITE.
v For relative files, move the relative record number to the RELATIVE KEY data item
and then issue the REWRITE.
Deleting records from a VSAM file
Open the file I-O and use the DELETE statement to remove an existing record from
an indexed or relative file. You cannot use DELETE on a sequential file.
When you use ACCESS IS SEQUENTIAL or the file contains spanned records, your
program must first read the record to be deleted. The DELETE then removes the
record that was read. If the DELETE is not preceded by a successful READ, the
deletion is not done and the status key value is set to 92.
When you use ACCESS IS RANDOM or ACCESS IS DYNAMIC, your program need not
first read the record to be deleted. To delete a record, move the key of the record to
be deleted to the RECORD KEY data item and then issue the DELETE. Your program
should check the file status key after each DELETE statement.
Closing VSAM files
Use the CLOSE statement to disconnect your program from the VSAM file. If you
try to close a file that is already closed, you will get a logic error. Check the file
status key after each CLOSE statement.
If you do not close a VSAM file, the file is automatically closed for you under the
following conditions:
v When the run unit ends normally, all open files defined in any COBOL for
OS/390 & VM, COBOL for MVS & VM, or VS COBOL II programs in the run
unit are closed.
v When the run unit ends abnormally, if the TRAP(ON) run-time option has been
set, all open files defined in any COBOL for OS/390 & VM, COBOL for MVS &
VM, or VS COBOL II programs in the run unit are closed.
v When Language Environment condition handling is completed and the
application resumes in a routine other than where the condition occurred, open
files defined in any COBOL for OS/390 & VM, COBOL for MVS & VM, or VS
COBOL II programs in the run unit that might be called again and reentered are
closed.
You can change the location where a program resumes after a condition is
handled. To make this change, you can, for example, move the resume cursor
with the CEEMRCR callable service or use HLL language constructs such as a C
longjmp statement.
v When you issue CANCEL for a COBOL for OS/390 & VM, COBOL for MVS &
VM, or VS COBOL II subprogram, any open nonexternal files defined in that
program are closed.
150
Programming Guide
v When a COBOL for OS/390 & VM, COBOL for MVS & VM, or VS COBOL II
subprogram with the INITIAL attribute returns control, any open nonexternal
files defined in that program are closed.
File status codes are set when these implicit CLOSE operations are performed, but
EXCEPTION/ERROR declaratives are not invoked.
Handling errors in VSAM files
When an input statement or output statement operation fails, COBOL does not
perform corrective action for you.
All OPEN and CLOSE errors with a VSAM file, whether logical errors in your
program or input/output errors on the external storage media, return control to
your COBOL program, even when you have coded no DECLARATIVE and no FILE
STATUS clause.
If any other input or output statement operation fails, you choose whether your
program will continue running after a less-than-severe input/output error occurs.
COBOL provides these ways for you to intercept and handle certain VSAM input
and output errors:
v End-of-file phrase (AT END)
v EXCEPTION/ERROR declarative
v FILE STATUS clause (file status key and VSAM return code)
v INVALID KEY phrase
You should define a status key for each VSAM file that you define in your
program. Check the status key value after every input or output request, especially
OPEN and CLOSE.
If you do not code a FILE STATUS key or a declarative, serious VSAM processing
errors will cause a message to be issued and a Language Environment condition to
be signaled, which will cause an abend if you specify the run-time option
ABTERMENC(ABEND).
RELATED TASKS
“Handling errors in input and output operations” on page 191
“Using VSAM return codes (VSAM files only)” on page 196
RELATED REFERENCES
OS/390 DFSMS: Macro Instructions for Data Sets
Protecting VSAM files with a password
Although the preferred security mechanism on an OS/390 system is RACF,
COBOL for OS/390 & VM also supports using explicit passwords on VSAM files
to prevent unauthorized access and update.
To use explicit passwords, code the PASSWORD clause in the SELECT statement of
your program. Use this clause only if the catalog entry for the files includes a read
or an update password.
v If the catalog entry includes a read password, you cannot open and access the
file in a COBOL program unless you use the password clause in the
FILE-CONTROL paragraph and describe it in the DATA DIVISION. The data-name
referred to must contain a valid password when the file is opened.
Chapter 9. Processing VSAM files
151
v If the catalog entry includes an update password, you can open and access it,
but not update it, unless you code the password clause in the FILE-CONTROL
paragraph and describe it in the DATA DIVISION.
v If the catalog entry includes both a read password and an update password,
specify the update password to both read and update the file in your program.
If your program only retrieves records and does not update them, you need only
the read password. If your program loads files or updates them, you need to
specify the update password that was cataloged.
For indexed files, the PASSWORD data item for the RECORD KEY must contain the valid
password before the file can be successfully opened.
If you password-protect a VSAM indexed file, you must also password-protect
every alternate index in order to be fully password-protected. Where you place the
PASSWORD clause becomes important because each alternate index has its own
password. The PASSWORD clause must directly follow the key clause to which it
applies.
“Example: password protection for a VSAM indexed file”
Example: password protection for a VSAM indexed file
The following example shows the COBOL code used for a VSAM indexed file with
password protection.
. . .
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT LIBFILE
ASSIGN TO PAYMAST
ORGANIZATION IS INDEXED
RECORD KEY IS EMPL-NUM
PASSWORD IS BASE-PASS
ALTERNATE RECORD KEY IS EMPL-PHONE
PASSWORD IS PATH1-PASS
. . .
WORKING-STORAGE SECTION.
01 BASE-PASS
PIC X(8) VALUE “25BSREAD”.
01 PATH1-PASS
PIC X(8) VALUE “25ATREAD”.
Working with VSAM data sets under OS/390 and OS/390 UNIX
There are some special considerations for VSAM files under OS/390 and OS/390
UNIX in terms of coding access method services (IDCAMS) commands,
environment variables, and JCL.
|
|
|
A VSAM file is available if all of the following are true:
v You define it using access method services.
v You define it for your program by providing a DD statement, an environment
variable, or an ALLOCATE command for it.
v It has previously contained a record.
|
|
A VSAM file is unavailable if it has never contained a record, even if you have
defined it.
You always get a return code of zero on completion of the OPEN statement for a
VSAM sequential file.
152
Programming Guide
Use the access method services REPRO command to empty a file. Deleting records in
this manner resets the high-use relative byte address (RBA) of the file to zero. The
file is effectively empty and appears to COBOL as if it never contained a record.
RELATED TASKS
“Defining files to the operating system” on page 10
“Defining VSAM files under OS/390”
“Creating alternate indexes” on page 154
“Allocating VSAM files” on page 156
“Sharing VSAM files through RLS” on page 157
Defining VSAM files under OS/390
You can process VSAM entry-sequenced, key-sequenced, and relative-record data
sets in COBOL for OS/390 & VM only after you define them through access
method services (IDCAMS).
A VSAM cluster is a logical definition for a VSAM data set and has one or two
components:
v The data component of a VSAM cluster contains the data records.
v The index component of a VSAM key-sequenced cluster consists of the index
records.
Use the access method services DEFINE CLUSTER command to define your VSAM
data sets (clusters). This process includes creating an entry in an integrated catalog
without any data transfer.
Define the following information about the cluster:
v Name of the entry
v Name of the catalog to contain this definition and its password (can use default
name.
v
v
v
v
v
Organization (sequential, indexed, or relative)
Device and volumes that the data set will occupy
Space required for the data set
Record size and control interval sizes (CISIZE)
Passwords (if any) required for future access
Depending on what kind of data set is in the cluster, also define the following
information for each cluster:
v For VSAM indexed data sets (KSDS), specify length and position of the prime
key in the records.
v For VSAM fixed-length relative-record data sets (RRDS), specify the record size
as greater than or equal to the maximum size COBOL record:
DEFINE CLUSTER NUMBERED
RECORDSIZE(n,n)
When you define a data set in this way, all records will be padded to the fixed
slot size n. If you use the RECORD IS VARYING ON data-name form of the RECORD
clause, a WRITE or REWRITE will use the length specified in the DEPENDING ON
data-name as the length of the record to be transferred by VSAM. This data is
then padded to the fixed slot size. READ statements always return the fixed slot
size in the DEPENDING ON data-name.
v For VSAM variable-length relative-record data sets (RRDS), specify the average
size COBOL record expected and the maximum size COBOL record expected:
Chapter 9. Processing VSAM files
153
DEFINE CLUSTER NUMBERED
RECORDSIZE(avg,m)
The average size COBOL record expected must be less than the maximum size
COBOL record expected.
v For COBOL simulated variable-length relative-record data sets, specify the
average size of the COBOL records and a size that is greater than or equal to the
maximum size COBOL record plus 4:
DEFINE CLUSTER INDEXED
KEYS(4,0)
RECORDSIZE(avg,m)
The average size COBOL record expected must be less than the maximum size
COBOL record expected.
RELATED TASKS
“Creating alternate indexes”
“Allocating VSAM files” on page 156
“Specifying relative organization for VSAM files” on page 139
RELATED REFERENCES
OS/390 DFSMS: Access Method Services for Catalogs
Access Method Services Reference
Creating alternate indexes
An alternate index provides access to the records in a data set using more than one
key. It accesses records in the same way as the prime index key of an indexed data
set (KSDS).
When planning to use an alternate index, you must know:
v The type of data set (base cluster) with which the index will be associated
v Whether the keys will be unique or not unique
v Whether the index is to be password protected
v Some of the performance aspects of using alternate indexes
Because an alternate index is, in practice, a VSAM data set that contains pointers to
the keys of a VSAM data set, you must define the alternate index and the alternate
index path (the entity that establishes the relationship between the alternate index
and the prime index). After you define an alternate index, make a catalog entry to
establish the relationship (or path) between the alternate index and its base cluster.
This path allows you to access the records of the base cluster through the alternate
keys.
To use an alternate index, you need to follow these steps:
1. Define the alternate index by using the DEFINE ALTERNATEINDEX command. In it,
define the following:
v Name of the alternate index
v Name of its related VSAM indexed data set
v Location in the record of any alternate indexes and whether they are unique
or not
v Whether or not alternate indexes are to be updated when the data set is
changed
v Name of the catalog to contain this definition and its password (can use
default name)
154
Programming Guide
In your COBOL program the alternate index is identified solely by the
ALTERNATE RECORD KEY clause of the FILE CONTROL paragraph. The ALTERNATE
RECORD KEY definitions must match the definitions that you have made in the
catalog entry. Any password entries that you have cataloged should be coded
directly after the ALTERNATE RECORD KEY phrase.
2. Relate the alternate index to the base cluster (the data set to which the alternate
index gives you access) by using the DEFINE PATH command. In it, define the
following:
v Name of the path
v Alternate index to which the path is related
v Name of the catalog that contains the alternate index
The base cluster and alternate index are described by entries in the same
catalog.
3. Load the VSAM indexed data set.
4. Build the alternate index by using (typically) the BLDINDEX command. Identify
the input file as the indexed data set (base cluster) and the output file as the
alternate index or its path. This command BLDINDEX reads all the records in
your VSAM indexed data set (or base cluster) and extracts the data needed to
build the alternate index.
Alternatively, you can use the run-time option AIXBLD to build the alternate
index at run time. However, this option might adversely affect run-time
performance.
“Example: entries for alternate indexes”
RELATED REFERENCES
AIXBLD (Language Environment Programming Reference)
Example: entries for alternate indexes
|
The following example maps the relationships between the COBOL FILE-CONTROL
entry and the DD statements or environment variables for a VSAM indexed file
with two alternate indexes.
Using JCL:
//MASTERA
//MASTERA1
//MASTERA2
DD
DD
DD
DSNAME=clustername,DISP=OLD
DSNAME=path1,DISP=OLD
DSNAME=path2,DISP=OLD
(1)
(2)
(3)
Using environment variables:
|
|
|
export MASTERA=DSN(clustername),OLD
export MASTERA=DSN(path1),OLD
export MASTERA=DSN(path2),OLD
. . .
FILE-CONTROL.
SELECT MASTER-FILE ASSIGN TO MASTERA
RECORD KEY IS EM-NAME
PASSWORD IS PW-BASE
ALTERNATE RECORD KEY IS EM-PHONE
PASSWORD IS PW-PATH1
ALTERNATE RECORD KEY IS EM-CITY
PASSWORD IS PW-PATH2.
(1)
(2)
(3)
(4)
(5)
(6)
(7)
(1)
The base cluster name is clustername.
(2)
The name of the first alternate index path is path1.
(3)
The name of the second alternate index path is path2.
Chapter 9. Processing VSAM files
155
|
(4)
The ddname or environment variable name for the base cluster is specified
with the ASSIGN clause.
(5)
Passwords immediately follow their indexes.
(6)
The key EM-PHONE relates to the first alternate index.
(7)
The key EM-CITY relates to the second alternate index.
RELATED TASKS
“Creating alternate indexes” on page 154
Allocating VSAM files
You must predefine and catalog all VSAM data sets through the access method
services DEFINE command. Most of the information about a VSAM data set is in the
catalog. You need to specify only minimal DD or environment variable information
for a VSAM file. When you use an environment variable, the name must be in
uppercase. Usually the input and data buffers are the only variables that you are
concerned about.
|
|
|
Allocation of VSAM files (indexed, relative, and sequential) follows the general
rules for the allocation of COBOL files. If you use an environment variable to
allocate a VSAM file, you must specify these options in the order shown, but no
others:
v DSN(dsname), where dsname is the name of the base cluster
v OLD or SHR
|
|
|
|
|
|
The basic DD statement that you need for your VSAM files is:
//ddname
DD
DSN=dsname,DISP=SHR,AMP=AMORG
The corresponding export command is:
|
|
export evname=“DSN(dsname),SHR”
In either case, dsname must be the same as the name used in the access method
services DEFINE CLUSTER or DEFINE PATH command. DISP must be OLD or SHR
because the data set is already cataloged. If you specify MOD when using JCL, the
data set is treated as OLD.
AMP is a VSAM JCL parameter used to supplement the information that the
program supplies about the data set. AMP takes effect when your program opens
the VSAM file. Any information that you set through the AMP parameter takes
precedence over the information that is in the catalog or that the program supplies.
The AMP parameter is not required except under the following circumstances:
v You use a dummy VSAM data set. For example,
//ddname DD
DUMMY,AMP=AMORG
v You request additional index or data buffers. For example,
//ddname
//
DD
DSN=VSAM.dsname,DISP=SHR,
AMP=('BUFNI=4,BUFND=8')
|
|
You cannot specify AMP if you allocate your VSAM data set with an environment
variable.
|
|
For a VSAM base cluster, specify the same system name (ddname or or
environment variable name) that you specify in the ASSIGN clause of the SELECT
statement in your COBOL program.
156
Programming Guide
|
|
|
|
When you use alternate indexes in your COBOL program, you must specify not
only a system name (using a DD statement or environment variable) for the base
cluster, but also one for each alternate index path. No language mechanism exists
to explicitly declare system names for alternate index paths within the program.
Therefore, you must adhere to the following guidelines for forming the system
name (ddname or environment variable name) for each alternate index path:
v Concatenate the base cluster name with an integer.
v Begin with 1 for the path associated with the first alternate record defined for
the file in your program (ALTERNATE RECORD KEY clause of the SELECT statement).
v Increment by 1 for the path associated with each successive alternate record
definition for that file.
|
|
|
For example, if the system name of a base cluster is ABCD, the system name for the
first alternate index path defined for the file in your program is ABCD1, the system
name for the second alternate index path is ABCD2, and so on.
|
|
|
|
If the length of the base cluster system name and sequence number exceeds eight
characters, the base cluster portion of the system name is truncated on the right to
reduce the concatenated result to eight characters. For example, if the system name
of a base cluster is ABCDEFGH, the system name of the first alternate index path is
ABCDEFG1, the tenth is ABCDEF10, and so on.
RELATED TASKS
“Allocating files” on page 105
RELATED REFERENCES
OS/390 MVS JCL Reference
Sharing VSAM files through RLS
By using the VSAM JCL parameter RLS, you can specify the use of record level
sharing with VSAM. Use RLS=CR when consistent read protocols are required, and
RLS=NRI when no read integrity protocols are required. Specifying the RLS
parameter is the only way to request the RLS mode when running COBOL
programs.
|
|
You cannot specify RLS if you allocate your VSAM data set with an environment
variable.
Preventing update problems with VSAM files in RLS mode
When a VSAM data set is opened in RLS mode for I-O (updates), the first READ
causes an exclusive lock of the control interval that contains the record, regardless
of RLS=CR or RLS=NRI that you specify. The exclusive lock is released after a WRITE
or REWRITE statement is issued or another READ statement is issued for another
record.
Specifying RLS=CR locks a record and prevents an update to it until another READ is
requested for another record. While a lock on the record being read is in effect,
other users can request a READ for the same record, but they cannot update the
record until the read lock is released. When you specify RLS=NRI, no lock will be in
effect when a READ for input is issued and another user might update the record.
The locking rules for RLS=CR can cause the application to wait for availability of a
record lock, and this wait might slow down the READ for input.
Chapter 9. Processing VSAM files
157
You might need to modify your application logic to use the RLS=CR capability. Do
not use the RLS JCL parameter for batch jobs that update nonrecoverable spheres
until you are sure that the application functions correctly in a multiple updater
environment.
When you open a VSAM data set in RLS mode for INPUT or I-O processing, it is a
good idea to issue an OPEN or START immediately before a READ. If there is a delay
between the OPEN or START and the actual READ, another user might add records
before the record on which the application is positioned after the OPEN or START.
The COBOL run time points explicitly to the beginning of the VSAM data set at
the time when OPEN was requested, but another user might add records that would
alter the true beginning of the VSAM data set if the READ is delayed.
Restrictions when using RLS
The following restrictions apply to RLS mode:
v The VSAM cluster attributes KEYRANGE and IMBED are not supported when you
open a VSAM file in RLS mode.
v The VSAM cluster attribute REPLICATE is not recommended with RLS mode
because the benefits are negated by the system-wide buffer pool and potentially
large CF cache structure in the storage hierarchy.
v The AIXBLD run-time option is not supported when you open a VSAM file in RLS
mode, because VSAM does not allow an empty path to be opened. If you need
the AIXBLD run-time option to build the alternate index data set, open the VSAM
data set in non-RLS mode.
v Temporary data sets are not allowed in RLS mode.
v The SIMVRD run-time option is not supported for VSAM files opened in RLS
mode.
Handling errors in VSAM files in RLS mode
If your application accesses a VSAM data set in RLS mode, be sure to check the file
status and VSAM feedback codes after each request.
If your application encounters “SMSVSAM server not available” while processing
input or output, explicitly close the VSAM file before you try to open it again.
VSAM generates return code 16 for failures like “SMSVSAM server not available,”
and there is no feedback code. You can have your COBOL programs check the first
two bytes of the second file status area for a VSAM return code 16.
The COBOL run time generates message IGZ0205W and automatically closes the
file if the error occurs during OPEN processing.
All other RLS mode errors return a VSAM return code of 4, 8, or 12.
Defining VSAM data sets under CMS
You can run COBOL programs that read and write VSAM files in CMS. The VSAM
used is VSE VSAM (not OS/390 VSAM). Nevertheless, the VSAM files written in
CMS have the same format as those created under OS/390 and are fully
compatible with OS/390 VSAM data sets. VSAM files created in CMS can be read
by an OS/390 system, and vice versa.
COBOL coding requirements are the same whether OS/390 or VSE VSAM is used.
However, instead of using the FILEDEF command to identify the VSAM files, you
must use the DLBL command. It has the same basic format as the FILEDEF
command. For example:
158
Programming Guide
DLBL INPUT C DSN COBTEST DATA (VSAM
This file might be identified in your program as follows:
FILE-CONTROL.
SELECT INVSAM
ASSIGN TO INPUT
ORGANIZATION IS INDEXED. . .
FD INVSAM
. . .
If you are running a program that uses a VSAM file and a non-VSAM file, use the
DLBL command to identify the VSAM file and the FILEDEF command to identify
your non-VSAM file. You can set additional options if the VSAM data set is a
multivolume file or if it is cataloged in a user catalog. If you use any of these
special options, you do not need to use the VSAM option.
A special ddname is provided for you to identify the catalog that you use during a
terminal session:
DLBL IJSYSCT F DSN MASTCAT (PERM
Entering this command makes the catalog available to you for the remainder of
your terminal session.
When a program abends or an HX Immediate command is issued while the
program is running, CMS automatically clears all DLBL and FILEDEF definitions,
even if PERM has been issued.
You must use access method services (CMS command AMSERV) to define catalogs,
data spaces, and clusters, and to perform functions such as REPRO, EXPORT, IMPORT,
and LISTCAT. Notice that the commands for these functions under CMS are
VSE/VSAM commands.
If a file with alternate indexes is open for input or output, you must define it with
SHAREOPTIONS(4).
RELATED REFERENCES
DLBL command (VM/ESA CMS User’s Guide)
AMSERV command (CMS Command Reference)
VSE/VSAM Commands and Macros
Improving VSAM performance
Most likely, your system programmer is responsible for tuning the performance of
COBOL and VSAM. As an application programmer, you can control the aspects of
VSAM listed in this table.
Aspect of VSAM What you can do
Invoking access
methods service
Rationale and comments
Build your alternate indexes in
advance, using IDCAMS (for
OS/390) or AMSERV (for CMS).
Chapter 9. Processing VSAM files
159
Aspect of VSAM What you can do
Buffering
Rationale and comments
For sequential access, request more The default is one index (BUFNI)
and two data buffers (BUFND).
data buffers; for random access,
request more index buffers. Specify
both BUFND and BUFNI when ACCESS
IS DYNAMIC.
Avoid coding additional buffers
unless your application will run
interactively; and then code buffers
only when response-time problems
arise that might be caused by
delays in input and output.
Loading records, Use the access methods service
using access
REPRO command when:
methods services v The target indexed data set
already contains records.
The REPRO command can update an
indexed data set as fast or faster
than any COBOL program under
these conditions.
v The input sequential data set
contains records to be updated
or inserted into the indexed data
set.
If you use a COBOL program to
load the file, use OPEN OUTPUT and
ACCESS SEQUENTIAL.
160
Programming Guide
File access modes For best performance, access
records sequentially.
Dynamic access is less efficient
than sequential access, but more
efficient than random access.
Random access results in increased
EXCPs because VSAM must access
the index for each request.
Key design
Design the key in the records so
that the high-order portion is
relatively constant and the
low-order portion changes often.
This method compresses the key
best.
Multiple
alternate indexes
Avoid using multiple alternate
indexes.
Updates must be applied through
the primary paths and are reflected
through multiple alternate paths,
perhaps slowing performance,
Relative file
organization
Use VSAM fixed-length relative
data sets rather than VSAM
variable-length relative data sets.
Although not as space efficient,
VSAM fixed-length relative data
sets are more run-time efficient
than VSAM variable-length relative
data sets, which have performance
characteristics comparable to
COBOL simulated relative data
sets.
Aspect of VSAM What you can do
Rationale and comments
Control interval
sizes (CISZ)
VSAM calculates CISZ to best fit
the direct-access storage device
(DASD) usage algorithm, which
might not, however, be efficient for
your application.
Provide your system programmer
with information about the data
access and future growth of your
VSAM data sets. From this
information, your system
programmer can determine the
best control interval size (CISZ) and
FREESPACE size (FSPC).
An average CISZ of 4K is suitable
for most applications. A smaller
CISZ means faster retrieval for
Choose proper values for CISZ and random processing at the expense
FSPC to minimize control area (CA) of inserts (that is, more CISZ splits
and therefore more space in the
splits. You can diagnose the
data set). A larger CISZ results in
current number of CA splits by
issuing the LISTCAT ALL command the transfer of more data across the
channel for each READ. This is more
on the cluster, and then compress
efficient for sequential processing,
(using EXPORT or IMPORT or REPRO)
similar to a large OS BLKSIZE.
the cluster to omit all CA splits
periodically.
Many control area (CA) splits are
unfavorable for VSAM
performance. The FREESPACE
value can affect CA splits,
depending on how the file is used.
RELATED TASKS
“Specifying access modes for VSAM files” on page 141
Deciding how big a virtual resource pool to provide (OS/390 DFSMS: Using Data
Sets)
Selecting the optimal percentage of free space (OS/390 DFSMS: Using Data Sets)
RELATED REFERENCES
AMSERV command (CMS Command Reference)
Access Method Services Reference
Chapter 9. Processing VSAM files
161
162
Programming Guide
Chapter 10. Processing line-sequential files
|
|
|
|
|
|
|
Line-sequential files are files that reside in the hierarchical file system (HFS) and
that contain only printable characters and certain control characters as data. Each
record ends with an EBCDIC new-line character (X’15’), which is not included in
the length of the record. Because these are sequential files, records are placed one
after another, according to entry order. Your program can process these files only
sequentially, retrieving (with the READ statement) records in the same order as they
are in the file. A new record is placed after the preceding record.
|
|
|
|
|
To process line-sequential files in your program, use COBOL language statements
that:
v Identify and describe the files in the ENVIRONMENT DIVISION and the DATA
DIVISION.
v Process the records in the files in the PROCEDURE DIVISION.
|
|
After you have created a record, you cannot change its length or its position in the
file, and you cannot delete it.
RELATED CONCEPTS
OS/390 UNIX System Services User’s Guide
RELATED TASKS
“Defining line-sequential files and records in COBOL”
“Describing the structure of a line-sequential file” on page 164
“Coding input-output statements for line-sequential files” on page 165
“Handling errors in line-sequential files” on page 168
“Defining and allocating line-sequential files” on page 165
RELATED REFERENCES
“Allowable control characters” on page 164
Defining line-sequential files and records in COBOL
|
|
|
|
|
Use the FILE-CONTROL entry in the ENVIRONMENT DIVISION to:
v Define the files in your COBOL program as line-sequential files.
v Associate them with the external file names (ddnames or environment variable
names). An external file name is the name by which a file is known to the
operating system.
In the following example, COMMUTER-FILE is the name that your program uses for
the file; COMMUTR is the external name.
|
|
|
|
|
|
|
|
FILE-CONTROL.
SELECT COMMUTER-FILE
ASSIGN TO COMMUTR
ORGANIZATION IS LINE SEQUENTIAL
ACCESS MODE IS SEQUENTIAL
FILE STATUS IS ECODE.
|
|
|
Your ASSIGN assignment-name clause must not include an organization field (S- or
AS-) before the external name. The ACCESS phrase and the FILE STATUS phrase are
optional.
© Copyright IBM Corp. 1991, 2000
163
RELATED TASKS
“Describing the structure of a line-sequential file”
“Coding input-output statements for line-sequential files” on page 165
“Defining and allocating line-sequential files” on page 165
RELATED REFERENCES
“Allowable control characters”
Allowable control characters
|
|
|
The control characters shown in the table below are the only characters other than
printable characters that line-sequential files can contain. The hex values are in
EBCDIC.
|
|
|
|
|
|
|
|
|
Hex value
X’05’
X’0B’
X’0C’
X’0D’
X’0E’
X’0F’
X’15’
X’16’
X’2F’
|
|
The new-line character is treated as a record delimiter. The other control characters
are treated as data and are part of the record.
Control character
Horizontal tab
Vertical tab
Form feed
Carriage return
DBCS shift-out
DBCS shift-in
New-line
Backspace
Alarm
RELATED TASKS
“Defining line-sequential files and records in COBOL” on page 163
Describing the structure of a line-sequential file
|
|
|
In the FILE SECTION of the DATA DIVISION, code a file description (FD) entry for the
file. In the associated record description entry or entries, define the record-name and
record length.
|
|
|
Code the logical size of the records with the RECORD clause. Line-sequential files are
stream files. Because of their character-oriented nature, the physical records are of
variable length.
|
|
The following examples show how the FD entry might look for a line-sequential
file:
|
|
|
|
|
|
FILE SECTION.
FD COMMUTER-FILE
RECORD CONTAINS 80 CHARACTERS.
01 COMMUTER-RECORD.
05 COMMUTER-NUMBER
PIC X(16).
05 COMMUTER-DESCRIPTION
PIC X(64).
With fixed-length records:
With variable-length records:
FILE SECTION.
FD COMMUTER-FILE
RECORD VARYING FROM 16 TO 80 CHARACTERS.
|
|
|
164
Programming Guide
|
|
|
01
COMMUTER-RECORD.
05 COMMUTER-NUMBER
05 COMMUTER-DESCRIPTION
|
|
|
|
If you code the same fixed size and no OCCURS DEPENDING ON clause for any level-01
record description entries associated with the file, that fixed size is the logical
record length. However, because blanks at the end of a record are not written to
the file, the physical records might be of varying lengths.
PIC X(16).
PIC X(64).
RELATED TASKS
“Defining line-sequential files and records in COBOL” on page 163
“Coding input-output statements for line-sequential files”
“Defining and allocating line-sequential files”
RELATED REFERENCES
Data Division—file description entries (IBM COBOL Language Reference)
Defining and allocating line-sequential files
|
|
|
You can define a line-sequential file in the HFS using either a DD statement or an
environment variable. Allocation of these files follows the general rules for
allocating COBOL files.
|
|
To define a line-sequential file, define one of the following with a name that
matches the external name on your ASSIGN clause:
v A DD allocation:
– A DD statement that specifies PATH=’absolute-path-name’
|
|
|
|
|
|
|
|
|
|
|
– A TSO allocation that specifies PATH(’absolute-path-name’)
You can optionally also specify these options:
– PATHOPTS
– PATHMODE
– PATHDISP
v An environment variable with a value of PATH(absolute-path-name). No other
values can be specified.
For example, to have your COBOL program use HFS file /u/myfiles/comtfile
for a COBOL file with an assignment-name of COMMUTR, you would use the
following command:
export COMMUTR=“PATH(/u/myfiles/commuterfile)”
RELATED TASKS
“Allocating files” on page 105
“Defining line-sequential files and records in COBOL” on page 163
RELATED REFERENCES
OS/390 MVS JCL Reference
Coding input-output statements for line-sequential files
|
Code the following input and output statements to process a line-sequential file:
|
OPEN
|
|
To make the file available to your program.
You can open a line-sequential file as INPUT, OUTPUT, or EXTEND. You cannot
open a line-sequential file as I-O.
Chapter 10. Processing line-sequential files
165
READ
|
To read a record from the file.
With sequential processing, your program reads one record after another in
the same order in which they were entered when the file was created.
|
|
WRITE
|
To create a record in the file.
Your program writes new records to the end of the file.
|
CLOSE
|
To release the connection between the file and your program.
RELATED TASKS
“Defining line-sequential files and records in COBOL” on page 163
“Describing the structure of a line-sequential file” on page 164
“Opening line-sequential files”
“Reading records from line-sequential files”
“Adding records to line-sequential files” on page 167
“Closing line-sequential files” on page 167
“Handling errors in line-sequential files” on page 168
RELATED REFERENCES
OPEN statement (IBM COBOL Language Reference)
READ statement (IBM COBOL Language Reference)
WRITE statement (IBM COBOL Language Reference)
CLOSE statement (IBM COBOL Language Reference)
Opening line-sequential files
|
|
Before your program can use any READ or WRITE statements to process records in a
file, it must first open the file with an OPEN statement.
|
An OPEN statement works if the file is available or has been dynamically allocated.
|
|
Code CLOSE WITH LOCK so that the file cannot be opened again while the program
is running.
RELATED TASKS
“Reading records from line-sequential files”
“Adding records to line-sequential files” on page 167
“Closing line-sequential files” on page 167
“Defining and allocating line-sequential files” on page 165
RELATED REFERENCES
OPEN statement (IBM COBOL Language Reference)
CLOSE statement (IBM COBOL Language Reference)
Reading records from line-sequential files
|
To read from a line-sequential file, open the file and use the READ statement.
|
|
With sequential processing, your program reads one record after another in the
same order in which the records were entered when the file was created.
|
|
|
Characters in the file record are read one at a time into the record area until one of
the following conditions occurs:
v The record delimiter (the EBCDIC new-line character) is encountered.
|
|
The delimiter is discarded and the remainder of the record area is filled with
spaces. (Record area is longer than the file record.)
166
Programming Guide
|
|
|
|
|
|
v The entire record area is filled with characters.
If the next unread character is the record delimiter, it is discarded. The next READ
reads from the first character of the next record. (Record area is the same length
as the file record.)
Otherwise the next unread character is the first character to be read by the next
READ. (Record area is shorter than the file record.)
RELATED TASKS
“Opening line-sequential files” on page 166
“Adding records to line-sequential files”
“Closing line-sequential files”
“Defining and allocating line-sequential files” on page 165
RELATED REFERENCES
OPEN statement (IBM COBOL Language Reference)
WRITE statement (IBM COBOL Language Reference)
Adding records to line-sequential files
|
|
To add to a line-sequential file, open the file as EXTEND and use the WRITE statement
to add records immediately after the last record in the file.
|
|
|
Blanks at the end of the record area are removed and the record delimiter is
added. The characters in the record area from the first character up to and
including the added record delimiter are written to the file as one record.
|
|
|
Records written to line-sequential files must contain only USAGE DISPLAY and
DISPLAY-1 items. External decimal data items must be unsigned or declared with
the SEPARATE CHARACTER phrase if signed.
RELATED TASKS
“Opening line-sequential files” on page 166
“Reading records from line-sequential files” on page 166
“Closing line-sequential files”
“Defining and allocating line-sequential files” on page 165
RELATED REFERENCES
OPEN statement (IBM COBOL Language Reference)
WRITE statement (IBM COBOL Language Reference)
Closing line-sequential files
|
|
Use the CLOSE statement to disconnect your program from a line-sequential file. If
you try to close a file that is already closed, you will get a logic error.
|
|
|
|
If you do not close a line-sequential file, the file is automatically closed for you
under the following conditions:
v When the run unit ends normally.
v When the run unit ends abnormally, if the TRAP(ON) run-time option is set.
v When Language Environment condition handling is completed and the
application resumes in a routine other than where the condition occurred, open
files defined in any COBOL programs in the run unit that might be called again
and reentered are closed.
|
|
|
|
Chapter 10. Processing line-sequential files
167
|
|
|
|
You can change the location where the program resumes (after a condition is
handled) by moving the resume cursor with the Language Environment
CEEMRCR callable service or using HLL language constructs such as a C
longjmp call.
|
|
File status codes are set when these implicit CLOSE operations are performed, but
EXCEPTION/ERROR declaratives are not invoked.
RELATED TASKS
“Opening line-sequential files” on page 166
“Reading records from line-sequential files” on page 166
“Adding records to line-sequential files” on page 167
“Defining and allocating line-sequential files” on page 165
RELATED REFERENCES
CLOSE statement (IBM COBOL Language Reference)
Handling errors in line-sequential files
|
|
|
When an input or output statement operation fails, COBOL does not take
corrective action for you. You choose whether or not your program will continue
running after an input or output error occurs.
|
|
|
|
COBOL provides these techniques for intercepting and handling certain
line-sequential input and output errors:
v End of file phrase (AT END)
v EXCEPTION/ERROR declarative
|
v FILE STATUS clause
|
|
If you do not use one of these techniques, an error in processing input or output
raises a Language Environment condition.
|
|
|
If you use the FILE STATUS clause, be sure to check the key and take appropriate
action based on its value. If you do not check the key, it is possible that your
program could continue; but the results will probably not be what you expected.
RELATED TASKS
“Coding input-output statements for line-sequential files” on page 165
“Handling errors in input and output operations” on page 191
168
Programming Guide
Chapter 11. Sorting and merging files
You can arrange records in a particular sequence by using the SORT or MERGE
statements:
SORT statement
Accepts input (from a file or an internal procedure) that is not in sequence,
and produces output (to a file or an internal procedure) in a requested
sequence. You can add, delete, or change records before or after they are
sorted.
MERGE statement
Compares records from two or more sequenced files and combines them in
order. You can add, delete, or change records after they are merged.
You can mix SORT and MERGE statements in the same COBOL program. A program
can contain any number of sort and merge operations. They can be the same
operation performed many times or different operations. However, one operation
must finish before another begins.
With COBOL for OS/390 & VM, your IBM licensed program for sorting and
merging must be DFSORT or an equivalent. Where DFSORT is mentioned, you can
use any equivalent sort or merge product.
COBOL programs containing SORT or MERGE statements can reside above or below
the 16M line.
The general procedure for sorting or merging is as follows:
1. Describe the sort or merge file to be used for sorting or merging.
2. Describe the input to be sorted or merged. If you want to process the records
before you sort them, code an input procedure.
3. Describe the output from sorting or merging. If you want to process the records
after you sort or merge them, code an output procedure.
4. Request the sort or merge.
5. Determine whether the sort or merge operation was successful.
|
|
|
|
OS/390 UNIX: You cannot run a COBOL program containing SORT or MERGE
statements under OS/390 UNIX. This restriction includes BPXBATCH. The USING
or GIVING files on a SORT or MERGE statement can be sequential files residing in the
HFS.
RELATED CONCEPTS
Sort and merge process
RELATED TASKS
“Describing the sort or merge file” on page 170
“Describing the input to sorting or merging” on page 171
“Describing the output from sorting or merging” on page 173
“Requesting the sort or merge” on page 177
“Determining whether the sort or merge was successful” on page 180
“Improving sort performance with FASTSRT” on page 181
“Controlling sort behavior” on page 184
DFSORT Application Programming Guide
© Copyright IBM Corp. 1991, 2000
169
RELATED REFERENCES
SORT statement (IBM COBOL Language Reference)
MERGE statement (IBM COBOL Language Reference)
Sort and merge process
During the sorting of a file, all of its records are ordered according to the contents
of one or more fields (keys) in each record. If there are multiple keys, the records
are first sorted according to the content of the first (or primary) key, then according
to the content of the second key, and so on. You can sort the records in either
ascending or descending order of each key.
To sort a file, use the COBOL SORT statement.
During the merging of two or more files (which must already be sorted), the
records are combined and ordered according to the contents of one or more keys in
each record. As with sorting, the records are first ordered according to the content
of the primary key, then according to the content of the second key, and so on. You
can order the records in either ascending or descending order of each key.
Use MERGE . . . USING to name the files that you want to combine into one
sequenced file. . The merge operation compares keys in the records of the input
files, and passes the sequenced records one by one to the RETURN statement of an
output procedure or to the file that you name in the GIVING phrase.
RELATED REFERENCES
SORT statement (IBM COBOL Language Reference)
MERGE statement (IBM COBOL Language Reference)
Describing the sort or merge file
Describe the sort file to be used for sorting or merging:
1. Write one or more SELECT statements in the FILE-CONTROL paragraph of the
ENVIRONMENT DIVISION to name a sort file. For example:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT Sort-Work-1 ASSIGN TO SortFile.
Sort-Work-1 is the name of the file in your program. Use this name to refer to
the file.
2. Describe the sort file in an SD entry in the FILE SECTION of the DATA DIVISION.
Every SD entry must contain a record description. For example:
DATA DIVISION.
FILE SECTION.
SD Sort-Work-1
RECORD CONTAINS 100 CHARACTERS.
01 SORT-WORK-1-AREA.
05 SORT-KEY-1
PIC X(10).
05 SORT-KEY-2
PIC X(10).
05 FILLER
PIC X(80).
You need SELECT statements and SD entries for sorting or merging, even if you are
sorting or merging data items from WORKING-STORAGE only.
170
Programming Guide
The file described in an SD entry is the working file used for a sort or merge
operation. You cannot perform any input or output operations on this file. You do
not need to provide a ddname definition for the file.
RELATED REFERENCES
“FILE SECTION entries” on page 14
Describing the input to sorting or merging
Describe the input file or files for sorting or merging by following this procedure:
1. Write one or more SELECT statements in the FILE-CONTROL paragraph of the
ENVIRONMENT DIVISION to name the input files. For example:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT Input-File ASSIGN TO InFile.
Input-File is the name of the file in your program. Use this name to refer to
the file.
2. Describe the input file (or files when merging) in an FD entry in the FILE
SECTION of the DATA DIVISION. For example:
DATA DIVISION.
FILE SECTION.
FD Input-File
LABEL RECORDS ARE STANDARD
BLOCK CONTAINS 0 CHARACTERS
RECORDING MODE IS F
RECORD CONTAINS 100 CHARACTERS.
01 Input-Record
PIC X(100).
RELATED TASKS
“Coding the input procedure” on page 172
“Requesting the sort or merge” on page 177
RELATED REFERENCES
“FILE SECTION entries” on page 14
Example: describing sort and input files for SORT
The following example shows the ENVIRONMENT DIVISION and DATA DIVISION entries
needed to describe sort files and an input file.
ID Division.
Program-ID. SmplSort.
Environment Division.
Input-Output Section.
File-Control.
*
* Assign name for a working file is
* treated as documentation.
*
Select Sort-Work-1 Assign To SortFile.
Select Sort-Work-2 Assign To SortFile.
Select Input-File Assign To InFile.
. . .
Data Division.
File Section.
SD Sort-Work-1
Record Contains 100 Characters.
01 Sort-Work-1-Area.
05 Sort-Key-1
Pic X(10).
05 Sort-Key-2
Pic X(10).
Chapter 11. Sorting and merging files
171
05 Filler
Pic X(80).
Sort-Work-2
Record Contains 30 Characters.
01 Sort-Work-2-Area.
05 Sort-Key
Pic X(5).
05 Filler
Pic X(25).
FD Input-File
Label Records Are Standard
Block Contains 0 Characters
Recording Mode is F
Record Contains 100 Characters.
01 Input-Record
Pic X(100).
. . .
Working-Storage Section.
01 EOS-Sw
Pic X.
01 Filler.
05 Table-Entry Occurs 100 Times
Indexed By X1
Pic X(30).
. . .
SD
RELATED TASKS
“Requesting the sort or merge” on page 177
Coding the input procedure
If you want to process the records in an input file before they are released to the
sort program, use the INPUT PROCEDURE phrase of the SORT statement. You can use
an input procedure to do the following:
v Release data items to the sort file from WORKING-STORAGE.
v Release records that have already been read in elsewhere in the program.
v Read records from an input file, select or process them, and release them to the
sort file.
Each input procedure must be contained in either paragraphs or sections. For
example, to release records from a table in WORKING-STORAGE to the sort file
SORT-WORK-2, you could code as follows:
SORT SORT-WORK-2
ON ASCENDING KEY SORT-KEY
INPUT PROCEDURE 600-SORT3-INPUT-PROC
. . .
600-SORT3-INPUT-PROC SECTION.
PERFORM WITH TEST AFTER
VARYING X1 FROM 1 BY 1 UNTIL X1 = 100
RELEASE SORT-WORK-2-AREA FROM TABLE-ENTRY (X1)
END-PERFORM.
To transfer records to the sort program, all input procedures must contain at least
one RELEASE or RELEASE FROM statement. To release A from X, for example, you can
code:
MOVE X TO A.
RELEASE A.
Alternatively, you can code:
RELEASE A FROM X.
172
Programming Guide
The following table compares the RELEASE and RELEASE FROM statements.
RELEASE
RELEASE FROM
MOVE EXT-RECORD
TO SORT-EXT-RECORD
PERFORM RELEASE-SORT-RECORD
. . .
RELEASE-SORT-RECORD.
RELEASE SORT-RECORD
PERFORM RELEASE-SORT-RECORD
. . .
RELEASE-SORT-RECORD.
RELEASE SORT-RECORD
FROM SORT-EXT-RECORD
RELATED REFERENCES
“Restrictions on input and output procedures” on page 175
RELEASE statement (IBM COBOL Language Reference)
Describing the output from sorting or merging
If the output from sorting or merging is a file, describe the file by following this
procedure:
1. Write a SELECT statement in the FILE-CONTROL paragraph of the ENVIRONMENT
DIVISION to name the output file. For example:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT Output-File ASSIGN TO OutFile.
Output-File is the name of the file in your program. Use this name to refer to
the file.
2. Describe the output file (or files when merging) in an FD entry in the FILE
SECTION of the DATA DIVISION. For example:
DATA DIVISION.
FILE SECTION.
FD Output-File
LABEL RECORDS ARE STANDARD
BLOCK CONTAINS 0 CHARACTERS
RECORDING MODE IS F
RECORD CONTAINS 100 CHARACTERS.
01 Output-Record
PIC X(100).
RELATED TASKS
“Coding the output procedure”
“Requesting the sort or merge” on page 177
RELATED REFERENCES
“FILE SECTION entries” on page 14
Coding the output procedure
If you want to select, edit, or otherwise change sorted records before writing them
from the sort work file into another file, use the OUTPUT PROCEDURE phrase of the
SORT statement.
Each output procedure must be contained in either a section or a paragraph. An
output procedure must include both of the following elements:
v At least one RETURN or RETURN INTO statement
v Any statements necessary to process the records that are made available, one at
a time, by the RETURN statement
Chapter 11. Sorting and merging files
173
The RETURN statement makes each sorted record available to your output
procedure. (The RETURN statement for a sort file is similar to a READ statement for an
input file.)
You can use the AT END and END-RETURN phrases with the RETURN statement. The
imperative statements on the AT END phrase are performed after all the records
have been returned from the sort file. The END-RETURN explicit scope terminator
delimits the scope of the RETURN statement.
If you use the RETURN INTO statement instead of RETURN, your records will be
returned to WORKING-STORAGE or to an output area.
Coding considerations when using DFSORT on OS/390
When a RETURN statement does not encounter an AT END condition before your
COBOL program finishes running, the SORT statement could end abnormally with
DFSORT message IEC025A. To avoid this situation, take these steps:
1. Code the RETURN statement with the AT END phrase.
2. Ensure that the RETURN statement is executed until the AT END condition is
encountered.
The AT END condition occurs after the last record is returned to the program from
the sort work file and a subsequent RETURN statement is executed.
“Example: coding the output procedure when using DFSORT”
RELATED REFERENCES
“Restrictions on input and output procedures” on page 175
RETURN statement (IBM COBOL Language Reference)
Example: coding the output procedure when using DFSORT
The following example shows a coding technique that ensures that the RETURN
statement encounters the AT END condition before the program finishes running.
The RETURN statement, coded with the AT END phrase, is executed until the AT END
condition occurs.
IDENTIFICATION DIVISION.
DATA DIVISION.
FILE SECTION.
SD OUR-FILE.
01 OUR-SORT-REC.
03 SORT-KEY
PIC X(10).
03 FILLER
PIC X(70).
. . .
WORKING-STORAGE SECTION.
01 WS-SORT-REC
PIC X(80).
01 END-OF-SORT-FILE-INDICATOR PIC X VALUE 'N'.
88 NO-MORE-SORT-RECORDS
VALUE 'Y'.
. . .
PROCEDURE DIVISION.
A-CONTROL SECTION.
SORT OUR-FILE ON ASCENDING KEY SORT-KEY
INPUT PROCEDURE IS B-INPUT
OUTPUT PROCEDURE IS C-OUTPUT.
. . .
B-INPUT SECTION.
MOVE . . .. . .. TO WS-SORT-REC.
RELEASE OUR-SORT-REC FROM WS-SORT-REC.
. . .
C-OUTPUT SECTION.
DISPLAY 'STARTING READS OF SORTED RECORDS: '.
174
Programming Guide
RETURN OUR-FILE
AT END
SET NO-MORE-SORT-RECORDS TO TRUE.
PERFORM WITH TEST BEFORE UNTIL NO-MORE-SORT-RECORDS
IF SORT-RETURN = 0 THEN
DISPLAY 'OUR-SORT-REC = ' OUR-SORT-REC
RETURN OUR-FILE
AT END
SET NO-MORE-SORT-RECORDS TO TRUE
END-IF
END-PERFORM.
Restrictions on input and output procedures
The following restrictions apply to each input or output procedure called by SORT
and to each output procedure called by MERGE:
v The procedure must not contain any SORT or MERGE statements.
v The procedure must not contain any STOP RUN, EXIT PROGRAM, or GOBACK
statements.
v You can use ALTER, GO TO, and PERFORM statements in the procedure to refer to
procedure names outside the input or output procedure. However, control must
return to the input or output procedure after a GO TO or PERFORM statement.
v The remainder of the PROCEDURE DIVISION must not contain any transfers of
control to points inside the input or output procedure (with the exception of the
return of control from a declarative section).
v In an input or output procedure, you can call a program that follows standard
linkage conventions. However, the called program cannot issue a SORT or MERGE
statement. For information on linkage convention considerations with Language
Environment callable services, see the reference below.
v During a SORT or MERGE operation, the SD data item is used. You must not use it
in the output procedure before the first RETURN executes. If you move data into
this record area before the first RETURN statement, the first record to be returned
will be overwritten.
v Language Environment condition handling does not allow user-written
condition handlers to be established in an input or output procedure.
RELATED TASKS
“Coding the input procedure” on page 172
“Coding the output procedure” on page 173
Language Environment Programming Guide
Defining sort and merge data sets under OS/390
To use DFSORT under OS/390, code DD statements in the run-time JCL to describe
the necessary data sets:
|
Sort or merge work
Define a minimum of three data sets: SORTWK01, SORTWK02, SORTWK03, . . .,
SORTWKnn (where nn is 99 or less). These data sets cannot be in the HFS.
SYSOUT Define for sort diagnostic messages, unless you change the data set name.
(Change the name using either the MSGDDN keyword of the OPTION control
statement in the SORT-CONTROL data set, or using the SORT-MESSAGE special
register.)
SORTCKPT
Define if the sort or merge is to take checkpoints.
Chapter 11. Sorting and merging files
175
Input and output
Define input and output data sets, if any.
SORTLIB (DFSORT library)
Define the library containing the sort modules, for example, SYS1.SORTLIB.
RELATED TASKS
“Controlling sort behavior” on page 184
“Using checkpoint/restart with DFSORT under OS/390” on page 186
Defining sort and merge files under CMS
You can run programs containing SORT and MERGE statements under CMS using
DFSORT/CMS or equivalent. To use DFSORT/CMS, identify the following files
and TXTLIB:
Sort or merge work
Sort and merge work files are allocated by DFSORT/CMS.
You can tailor the sort or merge work files in these ways:
v Create your own OPTION CONTROL statement in a SORT-CONTROL data set.
Issue the FILEDEF command for the SORT-CONTROL data set.
v Use the DFSORT/CMS parameters WRKADR, WRKDEV, and WRKSIZ.
Input and output
Identify by issuing the FILEDEF command.
SORT-CONTROL
Identify by issuing the FILEDEF command. The file must correspond to the
default (IGZSRTCD) or to the name you code in the SORT-CONTROL special
register.
DFSORT/CMS library
Before running a program that uses DFSORT/CMS, you must also define
the TXTLIB that contains the DFSORT/CMS library. Use the GLOBAL TXTLIB
command (discussed further in the reference below) to add the name of
the DFSORT/CMS library.
RELATED TASKS
“Controlling sort behavior” on page 184
“Identifying QSAM files to CMS” on page 128 (FILEDEF command)
Using DFSORT/CMS (DFSORT/CMS User’s Guide)
Using the GLOBAL command (Language Environment Programming Guide)
Sorting variable-length records
Your sort work file will be variable length only if you define it to be variable
length, even if the input file to the sort contains variable-length records.
The compiler will determine that the sort work file is variable length if you code
one of the following in its SD entry:
v A RECORD IS VARYING clause
v Two or more record descriptions that define records with different sizes, or
records that contain an OCCURS DEPENDING ON clause
You cannot code RECORDING MODE V for the sort work file because the SD entry does
not allow the RECORDING MODE clause.
176
Programming Guide
To improve sort performance on variable-length files, specify the most frequently
occurring record length of the input file (the modal length) on the SMS= control
card or in the SORT-MODE-SIZE special register.
RELATED TASKS
“Changing DFSORT defaults with control statements” on page 185
“Controlling sort behavior” on page 184
Requesting the sort or merge
To read records directly from an input file (files for MERGE) without any preliminary
processing, use SORT . . . USING or MERGE . . . USING and the name of the input
file (files) that you have declared in a SELECT statement. The compiler generates an
input procedure to open the input file (files), read the records, release the records
to the sort or merge program, and close the input file (files). The input file or files
must not be open when the SORT or MERGE statement begins execution.
To transfer sorted or merged records from the sort or merge program directly to
another file without any further processing, use SORT . . . GIVING or MERGE . . .
GIVING and the name of the output file that you have declared in a SELECT
statement. The compiler generates an output procedure to open the output file,
return the records, write the records, and close the file. The output file must not be
open when the SORT or MERGE statement begins execution. For example:
SORT Sort-Work-1
ON ASCENDING KEY Sort-Key-1
USING Input-File
GIVING Output-File.
“Example: describing sort and input files for SORT” on page 171
If you want an input procedure to be performed on the sort records before they are
sorted, use SORT . . . INPUT PROCEDURE. If you want an output procedure to be
performed on the sorted records, use SORT . . . OUTPUT PROCEDURE. For example:
SORT Sort-Work-1
ON ASCENDING KEY Sort-Key-1
INPUT PROCEDURE EditInputRecords
OUTPUT PROCEDURE FormatData.
“Example: sorting with input and output procedures” on page 178
Restriction: You cannot use an input procedure with the MERGE statement. The
source of input to the merge operation must be a collection of already sorted files.
However, if you want an output procedure to be performed on the merged
records, use MERGE . . . OUTPUT PROCEDURE. For example:
MERGE Merge-Work
ON ASCENDING KEY Merge-Key
USING Input-File-1 Input-File-2 Input-File-3
OUTPUT PROCEDURE ProcessOutput.
You must define Merge-Work in an SD statement in the FILE SECTION of the DATA
DIVISION, and the input files in FD statements in the FILE SECTION.
Setting sort or merge criteria
To set sort or merge criteria, follow these steps:
1. In the record description of the files to be sorted or merged, define the key or
keys on which the operation is to be performed.
Chapter 11. Sorting and merging files
177
There is no maximum number of keys, but the keys must be located in the first
4092 bytes of the record description.
The total length of the keys cannot exceed 4092 bytes unless the EQUALS
keyword is coded in the DFSORT OPTION control statement, in which case the
total length of the keys must not exceed 4088 bytes.
Restriction: A key cannot be variably located.
|
|
2. In the SORT or MERGE statement, specify the key fields to be used for sequencing.
You can code keys as ascending or descending. When you code more than one
key, some can be ascending, and some descending.
The leftmost key is the primary key. The next key is the secondary key, and so
on.
You can mix SORT and MERGE statements in the same COBOL program. A program
can perform any number of sort or merge operations. However, one operation
must end before another can begin.
RELATED CONCEPTS
“Appendix B. Complex OCCURS DEPENDING ON” on page 569 (variably located
items)
RELATED TASKS
“Defining sort and merge data sets under OS/390” on page 175
“Defining sort and merge files under CMS” on page 176
RELATED REFERENCES
SORT control statement (DFSORT Application Programming Guide)
SORT statement (IBM COBOL Language Reference)
MERGE statement (IBM COBOL Language Reference)
Example: sorting with input and output procedures
The following example shows the use of an input and an output procedure in a
SORT statement. The example also shows how you can define primary key
SORT-GRID-LOCATION and secondary key SORT-SHIFT in the DATA DIVISION before
using them in the SORT statement.
DATA DIVISION.
. . .
SD SORT-FILE
RECORD CONTAINS 115 CHARACTERS
DATA RECORD SORT-RECORD.
01 SORT-RECORD.
05 SORT-KEY.
10 SORT-SHIFT
PIC X(1).
10 SORT-GRID-LOCATION
PIC X(2).
10 SORT-REPORT
PIC X(3).
05 SORT-EXT-RECORD.
10 SORT-EXT-EMPLOYEE-NUM
PIC X(6).
10 SORT-EXT-NAME
PIC X(30).
10 FILLER
PIC X(73).
. . .
WORKING-STORAGE SECTION.
01 TAB1.
05 TAB-ENTRY OCCURS 10 TIMES
INDEXED BY TAB-INDX.
10 WS-SHIFT
PIC X(1).
10 WS-GRID-LOCATION
PIC X(2).
10 WS-REPORT
PIC X(3).
10 WS-EXT-EMPLOYEE-NUM
PIC X(6).
10 WS-EXT-NAME
PIC X(30).
10 FILLER
PIC X(73).
|
|
|
|
|
|
|
|
|
|
178
Programming Guide
|
|
|
|
|
|
|
|
. . .
PROCEDURE DIVISION.
. . .
SORT SORT-FILE
ON ASCENDING KEY SORT-GRID-LOCATION SORT-SHIFT
INPUT PROCEDURE 600-SORT3-INPUT
OUTPUT PROCEDURE 700-SORT3-OUTPUT.
. . .
600-SORT3-INPUT.
PERFORM VARYING TAB-INDX FROM 1 BY 1 UNTIL TAB-INDX > 10
RELEASE SORT-RECORD FROM TAB-ENTRY(TAB-INDX)
END-PERFORM.
. . .
700-SORT3-OUTPUT.
PERFORM VARYING TAB-INDX FROM 1 BY 1 UNTIL TAB-INDX > 10
RETURN SORT-FILE INTO TAB-ENTRY(TAB-INDX)
AT END DISPLAY 'Out Of Records In SORT File'
END-RETURN
END-PERFORM.
RELATED TASKS
“Requesting the sort or merge” on page 177
Choosing alternate collating sequences
You can sort or merge records on the EBCDIC or ASCII collating sequence, or on
another collating sequence. The default collating sequence is EBCDIC unless you
code the PROGRAM COLLATING SEQUENCE clause in the OBJECT-COMPUTER paragraph. To
override the sequence named in the PROGRAM COLLATING SEQUENCE clause, use the
COLLATING SEQUENCE phrase of the SORT or MERGE statement. You can use different
collating sequences for each SORT or MERGE statement in your program.
When you sort or merge an ASCII file, you have to request the ASCII collating
sequence. To do so, code the COLLATING SEQUENCE phrase of the SORT or MERGE
statement, where you define the alphabet-name as STANDARD-1 in the SPECIAL-NAMES
paragraph.
RELATED TASKS
“Specifying the collating sequence” on page 8
RELATED REFERENCES
SORT statement (IBM COBOL Language Reference)
Sorting on windowed date fields
You can specify windowed date fields as sort keys if your version of DFSORT
supports the Y2PAST option. If so, DFSORT can sort or merge on the windowed
date sequence.
To sort on a windowed date field, use the DATE FORMAT clause to define a
windowed date field; then use the field as the sort key. DFSORT will use the same
century window as that used by the compilation unit. Specify the century window
with the YEARWINDOW compiler option.
DFSORT supports year-last windowed date fields, although the compiler itself
does not provide automatic windowing for year-last windowed date fields in
statements other than MERGE or SORT.
RELATED REFERENCES
“YEARWINDOW” on page 303
Chapter 11. Sorting and merging files
179
DATE FORMAT clause (IBM COBOL Language Reference)
Y2PAST option (DFSORT Application Programming Guide)
Preserving the original sequence of records with equal keys
You can preserve the order of identical collating records from input to output in
one of these ways:
v Install DFSORT with the EQUALS option as the default.
v Provide, at run time, an OPTION card with the EQUALS keyword in the IGZSRTCD
data set.
v Use the WITH DUPLICATES IN ORDER phrase in the SORT statement. Doing so adds
the EQUALS keyword to the OPTION card in the IGZSRTCD data set.
Do not use the NOEQUALS keyword on the OPTION card and use the DUPLICATES
phrase, or the run unit will be ended.
RELATED REFERENCES
OPTION control statement (DFSORT Application Programming Guide)
Determining whether the sort or merge was successful
The DFSORT program returns one of the following completion codes after a sort or
merge has finished:
0
Successful completion of the sort or merge
16
Unsuccessful completion of the sort or merge
The completion code is stored in the SORT-RETURN special register. The contents of
this register change after each SORT or MERGE statement is performed.
You should test for successful completion after each SORT or MERGE statement. For
example:
SORT SORT-WORK-2
ON ASCENDING KEY SORT-KEY
INPUT PROCEDURE IS 600-SORT3-INPUT-PROC
OUTPUT PROCEDURE IS 700-SORT3-OUTPUT-PROC.
IF SORT-RETURN NOT=0
DISPLAY “SORT ENDED ABNORMALLY. SORT-RETURN = ” SORT-RETURN.
. . .
600-SORT3-INPUT-PROC SECTION.
. . .
700-SORT3-OUTPUT-PROC SECTION.
. . .
If you do not reference SORT-RETURN anywhere in your program, the COBOL run
time tests the return code. If the return code is 16, COBOL issues a run-time
diagnostic message.
If you test SORT-RETURN for one or more (but not necessarily all) SORT or MERGE
statements, the COBOL run time does not check the return code.
By default, DFSORT diagnostic messages are sent to the SYSOUT data set. If you
want to change this default, use the MSGDDN parameter of the DFSORT OPTION
control card or use the SORT-MESSAGE special register.
RELATED TASKS
“Checking for sort errors with NOFASTSRT” on page 183
“Controlling sort behavior” on page 184
180
Programming Guide
RELATED REFERENCES
DFSORT messages and return codes (DFSORT Application Programming Guide)
Stopping a sort or merge operation prematurely
To stop a sort or merge operation, use the SORT-RETURN special register. Move the
integer 16 into the register in either of the following ways:
v Use MOVE in an input or output procedure.
Sort or merge processing will be stopped immediately after the next RELEASE or
RETURN statement is performed.
v Reset the register in a declarative section entered during processing of a USING or
GIVING file.
Sort or merge processing will be stopped immediately after the next implicit
RELEASE or RETURN is performed, which will occur after a record has been read
from or written to the USING or GIVING file.
Control then returns to the statement following the SORT or MERGE statement.
Improving sort performance with FASTSRT
Using the FASTSRT compiler option improves the performance of most sort
operations. With FASTSRT, the DFSORT product (instead of COBOL for OS/390 &
VM) performs the I/O on the input and output files you name in the following
statements:
SORT . . . USING
SORT . . . GIVING
The compiler issues informational messages to point out statements in which
FASTSRT can improve performance.
|
|
Restrictions: You cannot use the DFSORT options SORTIN or SORTOUT if you use
FASTSRT. The FASTSRT compiler option does not apply to line-sequential files you
use as USING or GIVING files.
If you specify file status and use FASTSRT, file status is ignored during the sort.
RELATED REFERENCES
“FASTSRT” on page 273
“FASTSRT requirements for JCL (OS/390 only)”
“FASTSRT requirements for sort input and output files”
FASTSRT requirements for JCL (OS/390 only)
In the run-time JCL, you must assign the sort work files (SORTWKnn) to a
direct-access device, not to tape data sets.
For the input and output files, the DCB parameter of the DD statement in the JCL
must match the FD description.
FASTSRT requirements for sort input and output files
If you specify FASTSRT but your code does not meet FASTSRT requirements, the
compiler issues a message and the COBOL run time performs the I/O instead.
Your program will not experience the performance improvements otherwise
possible.
Chapter 11. Sorting and merging files
181
To use FASTSRT, you must describe and process the input files to the sort, and the
output files from the sort, in these ways:
v You can mention only one input file in the USING phrase. You can mention only
one output file in the GIVING phrase.
v You cannot use an input procedure on an input file, nor an output procedure on
an output file.
Instead of using input or output procedures, you might be able to use DFSORT
control statements:
– INREC
– OUTREC
–
–
–
–
–
INCLUDE
OMIT
STOPAFT
SKIPREC
SUM
Many DFSORT functions perform the same operations that are common in input
or output procedures. Code the appropriate DFSORT control statements instead,
and place them either in the IGZSRTCD data set or the SORTCNTL data set.
v Do not code the LINAGE clause for the output FD entry.
v Do not code any INPUT declarative (for input files), OUTPUT declarative (for
output files), or file-specific declaratives (for either input or output files) to
apply to any FDs used in the sort.
v Do not use a variable relative file as the input or output file.
v Do not use a line-sequential file as the input or output file.
v For either an input or an output file, the record descriptions of the SD and FD
entry must define the same format (fixed or variable), and the largest records of
the SD and FD entry must define the same record length.
|
Note that if you code a RELATIVE KEY clause for an output file, it will not be set by
the sort.
Tip: If you block your input and output records, the sort performance could be
significantly improved.
QSAM requirements
v QSAM files must have a record format of fixed, variable, or spanned.
v A QSAM input file can be empty.
v To use the same QSAM file for both input and output, you must describe the file
using two different DD statements. For example, in the FILE-CONTROL SECTION
you might code the following:
SELECT FILE-IN ASSIGN INPUTF.
SELECT FILE-OUT ASSIGN OUTPUTF.
In the DATA DIVISION, you would have an FD entry for both FILE-IN and
FILE-OUT, where FILE-IN and FILE-OUT are identical except for their names.
In the PROCEDURE DIVISION, your SORT statement could look like this:
SORT file-name
ASCENDING KEY data-name-1
USING FILE-IN GIVING FILE-OUT
182
Programming Guide
Then in your JCL, you would code:
//INPUTF DD DSN=INOUT,DISP=SHR
//OUTPUTF DD DSN=INOUT,DISP=SHR
where data set INOUT has been cataloged.
On the other hand, if you code the same file name in the USING and GIVING
phrases, or assign the input and output files the same ddname, then the file can
be accepted for FASTSRT either for input or output, but not both. If no other
conditions disqualify the file from being eligible for FASTSRT on input, then the
file will be accepted for FASTSRT on input, but not on output. If the file was
found to be ineligible for FASTSRT on input, it might be eligible for FASTSRT on
output.
A QSAM file that qualifies for FASTSRT can be accessed by the COBOL program
while the SORT statement is being performed. For example, if the file is used for
FASTSRT on input, you can access it in an output procedure; if it is used for FASTSRT
on output, you can access it in an input procedure.
VSAM requirements
v A VSAM input file must not be empty.
v VSAM files cannot be password protected.
v You cannot name the same VSAM file in both the USING and GIVING phrases.
v A VSAM file that qualifies for FASTSRT cannot be accessed by the COBOL
program until the SORT statement processing is completed. For example, if the
file qualifies for FASTSRT on input, you cannot access it in an output procedure
and vice versa. (If you do so, OPEN will fail.)
RELATED TASKS
DFSORT Application Programming Guide
Checking for sort errors with NOFASTSRT
When you compile with the NOFASTSRT option, the sort process does not check for
errors on open, close, or input or output operations for files you reference in the
USING or GIVING phrase of the SORT statement. Therefore, you might need to check
whether the SORT statement completed successfully.
The code required depends on whether you code a FILE STATUS clause or an ERROR
declarative for the files referenced in the USING and GIVING phrases, as shown in
the table below.
FILE STATUS
clause?
ERROR
declarative?
No
No
No special coding. Any failure during the sort process
causes the program to end abnormally.
Yes
No
Test the SORT-RETURN special register after the SORT
statement, and test the file status key. (Not recommended
if you want complete file status checking, because the file
status code is set but COBOL cannot check it.)
Maybe
Yes
In the ERROR declarative, set the SORT-RETURN special
register to 16 to stop the sort process and indicate that it
was not successful. Test the SORT-RETURN special register
after the SORT statement.
Then do:
Chapter 11. Sorting and merging files
183
RELATED TASKS
“Determining whether the sort or merge was successful” on page 180
“Using file status keys” on page 194
“Coding ERROR declaratives” on page 194
“Stopping a sort or merge operation prematurely” on page 181
Controlling sort behavior
You can control several aspects of sort behavior by the following means:
v Inserting values in special registers before the sort
v Using compiler options
v Using control statement keywords
You can also verify sort behavior by examining the contents of special registers
after the sort.
The table below lists those aspects of sort behavior that you can affect using
special registers or compiler options, and the equivalent sort control statement
keywords if any. For a full list of sort keywords, see the reference below.
To set or test
Use this special register or
compiler option
Or this control statement
(and keyword if
applicable)
Amount of main storage to be
reserved
SORT-CORE-SIZE special register OPTION (keyword RESINV)
Amount of main storage to be
used
SORT-CORE-SIZE special register OPTION (keywords
MAINSIZE or MAINSIZE=MAX)
Modal length of records in a
file with variable-length
records
SORT-MODE-SIZE special register SMS=nnnnn
Name of sort control statement SORT-CONTROL special register
data set(default IGZSRTCD)
None
Name of sort message file
(default SYSOUT)
SORT-MESSAGE special register
Number of sort records
SORT-FILE-SIZE special register OPTION (keyword FILSZ)
Sort completion code
SORT-RETURN special register
Century window for sorting or YEARWINDOW compiler option
merging on date fields
Format of windowed date
fields used as sort or merge
keys
(Derived from PICTURE, USAGE,
and DATE FORMAT clauses)
OPTION (keyword MSGDDN)
None
OPTION (keyword Y2PAST)
SORT (keyword
FORMAT=Y2x)
Sort special registers
SORT-CONTROL is an eight-character COBOL special register that contains the
ddname of the sort control statement file. If you do not want to use the default
ddname IGZSRTCD, assign to SORT-CONTROL the ddname of the data set that contains
your sort control statements.
The SORT-CORE-SIZE, SORT-FILE-SIZE, SORT-MESSAGE, and SORT-MODE-SIZE special
registers are used in the SORT interface if you assign them nondefault values. At
184
Programming Guide
run time, however, any parameters on control statements in the sort control
statement data set override corresponding settings in the special registers, and a
message to that effect is issued.
|
|
|
You can use the SORT-RETURN special register to determine whether the sort or
merge was successful and to stop a sort or merge operation prematurely, as
discussed in the cross-references below.
A compiler warning message (W-level) is issued for each sort special register that
you set in a program.
RELATED TASKS
“Determining whether the sort or merge was successful” on page 180
“Stopping a sort or merge operation prematurely” on page 181
“Changing DFSORT defaults with control statements”
Using DFSORT program control statements (DFSORT Application Programming
Guide)
RELATED REFERENCES
“Default characteristics of the IGZSRTCD data set”
Changing DFSORT defaults with control statements
If you want to change DFSORT system defaults to improve sort performance, pass
information to DFSORT through control statements in the run-time data set
IGZSRTCD.
The control statements you can include in the IGZSRTCD data set (in the order
listed) are:
1. SMS=nnnnn, where nnnnn is the length in bytes of the most frequently occurring
record size. (Use only if the SD file is variable length.)
2. OPTION (except keywords SORTIN or SORTOUT).
3. Other DFSORT control statements (except SORT, MERGE, RECORD, or END).
Code control statements between columns 2 and 71. You can continue a control
statement record by ending the line with a comma and starting the next line with a
new keyword. No labels or comments are allowed on a record, and a record itself
cannot be a DFSORT comment statement.
RELATED TASKS
“Controlling sort behavior” on page 184
Using DFSORT program control statements (DFSORT Application Programming
Guide)
RELATED REFERENCES
“Default characteristics of the IGZSRTCD data set”
Default characteristics of the IGZSRTCD data set
v LRECL=80
v BLKSIZE=400
v ddname is IGZSRTCD. (You can use a different ddname by coding it in the
SORT-CONTROL special register.)
The IGZSRTCD data set is optional. If you defined a ddname for the SORT-CONTROL
data set and you receive the message IGZ0027W, an OPEN failure occurred that you
should investigate.
Chapter 11. Sorting and merging files
185
RELATED TASKS
“Controlling sort behavior” on page 184
Allocating storage for sort or merge operations
Certain parameters set during the installation of DFSORT determine the amount of
storage it uses. In general, the more storage DFSORT has available, the faster the
sort or merge operations in your program will be.
DFSORT installation should not allocate all the free space in the region for its
COBOL operation, however. When your program is running, storage must be
available for the following:
v COBOL programs that are dynamically called from an input or output procedure
v Language Environment run-time library modules
v Data management modules that can be loaded into the region for use by an
input or output procedure
v Any storage obtained by these modules
For a specific sort or merge operation, you can override the DFSORT storage
values set at installation. To do so, code the MAINSIZE and RESINV keywords on the
OPTION control statement in the sort control statement data set, or use the
SORT-CORE-SIZE special register.
Be careful not to override the storage allocation to the extent that all the free space
in the region is used for sort operations in your COBOL program.
RELATED TASKS
“Controlling sort behavior” on page 184
DFSORT Installation and Customization
RELATED REFERENCES
OPTION control statement (DFSORT Application Programming Guide)
Using checkpoint/restart with DFSORT under OS/390
You cannot use checkpoints taken while DFSORT is running under OS/390 to
restart, unless the checkpoints are taken by DFSORT. Checkpoints taken by your
COBOL program while SORT or MERGE statements execute are invalid; the restarts
are detected and canceled.
To take a checkpoint during a sort or merge operation, follow these steps:
1. Add a DD statement for SORTCKPT in the JCL.
2. Code the RERUN clause in the I-O-CONTROL paragraph:
RERUN ON assignment-name
3. Code the CKPT (or CHKPT) keyword on an OPTION control statement in the sort
control statement data set (default ddname IGZSRTCD).
RELATED CONCEPTS
“Chapter 31. Interrupts and checkpoint/restart” on page 501
RELATED TASKS
“Changing DFSORT defaults with control statements” on page 185
“Setting checkpoints” on page 501
186
Programming Guide
Sorting under CICS
There is no IBM sort product that is supported under CICS. However, you can use
the SORT statement with a sort program you write that runs under CICS to sort
small amounts of data.
You must have both an input and an output procedure for the SORT statement. In
the input procedure, use the RELEASE statement to transfer records from the
COBOL program to the sort program before the sort is performed. In the output
procedure, use the RETURN statement to transfer records from the sort program to
the COBOL program after the sort is performed.
RELATED TASKS
“Coding the input procedure” on page 172
“Coding the output procedure” on page 173
RELATED REFERENCES
“CICS SORT application restrictions”
CICS SORT application restrictions
The following restrictions apply to COBOL applications that run under CICS and
use the SORT statement:
v SORT statements that include the USING or GIVING phrase are not supported.
v Sort control data sets are not supported. Data in the SORT-CONTROL special
register is ignored.
v Using the following CICS commands in the input or output procedures can
cause unpredictable results:
– CICS LINK
– CICS XCTL
– CICS RETURN
– CICS HANDLE
– CICS IGNORE
– CICS PUSH
– CICS POP
v You can use CICS commands other than those in the preceding list provided you
use the NOHANDLE or RESP option. Unpredictable results can occur if you do not
use NOHANDLE or RESP.
Chapter 11. Sorting and merging files
187
188
Programming Guide
Chapter 12. Handling errors
Anticipate possible coding or system problems by putting code into your program
to handle them. Such code is like built-in distress flares or lifeboats. With this code,
output data and files should not be corrupted, and the user will know when there
is a problem.
Your error-handling code can take actions such as handling the situation, issuing a
message, or halting the program. In any event, coding a warning message is a
good idea.
You might create error-detection routines for data-entry errors or for errors as your
installation defines them.
COBOL contains special elements to help you anticipate and correct error
conditions:
v User-requested dumps
v ON OVERFLOW in STRING and UNSTRING operations
v
v
v
v
ON SIZE ERROR in arithmetic operations
Technique handling for input or output errors
ON EXCEPTION or ON OVERFLOW in CALL statements
User-written routines for handling errors
RELATED TASKS
“Handling errors in joining and splitting strings” on page 190
“Handling errors in arithmetic operations” on page 191
“Handling errors in input and output operations” on page 191
“Handling errors when calling programs” on page 199
“Writing routines for handling errors” on page 199
Requesting dumps
You can obtain a formatted dump of the run-time environment by calling the
Language Environment service CEE3DMP. To obtain a system dump, you can
request an abend without cleanup by calling the Language Environment service
CEE3ABD with a cleanup value of zero.
Creating a formatted dump
You can cause a dump of the Language Environment run-time environment and
the member language libraries at any prespecified point in your program. Simply
code a call to the Language Environment callable service CEE3DMP. For example:
77
77
01
. .
Title-1
Pic
Options
Pic
Feedback-code
Pic
.
Call “CEE3DMP” Using
x(80)
x(255)
x(12)
Display.
Display.
Display.
Title-1, Options, Feedback-code
To have symbolic variables included in the formatted dump produced by
Language Environment, you must compile with the SYM suboption of the TEST
compiler option and use the VARIABLES subparameter of CEE3DMP.
© Copyright IBM Corp. 1991, 2000
189
You can also request, through run-time options, that a dump be produced for error
conditions of your choosing.
Creating a system dump
You can cause a system dump at any prespecified point in your program. Simply
request an abend without cleanup by calling the Language Environment service
CEE3ABD with a cleanup value of zero.
This callable service stops the run unit immediately, and a system dump is
requested when the abend is issued.
RELATED REFERENCES
Language Environment Debugging Guide and Run-Time Messages
Language Environment Programming Reference
Handling errors in joining and splitting strings
During the joining string or splitting of strings, the pointer, used by STRING or
UNSTRING, might fall outside the range of the receiving field. Here a potential
overflow condition exists, COBOL does not let the overflow happen, instead, the
STRING or UNSTRING operation is not completed, the receiving field remains
unchanged, and control passes to the next sequential statement. However, you do
not have an ON OVERFLOW clause on the STRING or UNSTRING statement, and you are
not notified of the incomplete operation.
Consider the following statement:
String Item-1 space Item-2 delimited by Item-3
into Item-4
with pointer String-ptr
on overflow
Display “A string overflow occurred”
End-String
These are the data values before and after the statement is performed:
Data item
PICTURE
Value before
Value after
Item-1
X(5)
AAAAA
AAAAA
Item-2
X(5)
EEEAA
EEEAA
Item-3
X(2)
EA
Item-4
X(8)
ºººººººº
ºººººººº1
String-ptr
9(2)
0
0
EA
1
1. The symbol º represents a blank space.
Because String-ptr has a value of zero that falls short of the receiving field, an
overflow condition occurs and the STRING operation is not completed. (A
String-ptr greater than nine would have the same result.) If ON OVERFLOW had not
been specified, you would not be notified that the contents of Item-4 remain
unchanged.
190
Programming Guide
Handling errors in arithmetic operations
The results of arithmetic operations might be larger than the fixed-point field that
is to hold them, or you might have tried dividing by zero. In either case, the ON
SIZE ERROR clause after the ADD, SUBTRACT, MULTIPLY, DIVIDE, or COMPUTE statement
can handle the situation.
For ON SIZE ERROR to work correctly for fixed-point overflow and decimal
overflow, you must specify the TRAP(ON) run-time option.
The imperative statement of the ON SIZE ERROR clause will be performed and the
result field will not change in these cases:
v Fixed-point overflow
v Division by zero
v Zero raised to the zero power
v Zero raised to a negative number
v Negative number raised to a fractional power
Floating-point exponent overflow occurs when the value of a floating-point
computation cannot be represented in the System/390 floating-point operand
format. This type of overflow does not cause SIZE ERROR; an abend occurs instead.
You could code a user-written condition handler to intercept the abend and
provide your own error recovery logic.
“Example: checking for division by zero”
RELATED REFERENCES
“ON SIZE ERROR and intermediate results” on page 567
Example: checking for division by zero
Code your ON SIZE ERROR imperative statement so that it issues an informative
message. For example:
DIVIDE-TOTAL-COST.
DIVIDE TOTAL-COST BY NUMBER-PURCHASED
GIVING ANSWER
ON SIZE ERROR
DISPLAY “ERROR IN DIVIDE-TOTAL-COST PARAGRAPH”
DISPLAY “SPENT ” TOTAL-COST, “ FOR ” NUMBER-PURCHASED
PERFORM FINISH
END-DIVIDE
. . .
FINISH.
STOP RUN.
In this example, if division by zero occurs, the program writes a message
identifying the trouble and halts program execution.
Handling errors in input and output operations
When an input or output operation fails, COBOL does not automatically take
corrective action. You choose whether your program will continue running after a
less-than-severe input or output error occurs.
|
|
|
You can use any of the following techniques for intercepting and handling certain
input or output errors:
v Imperative-statement phrases on your READ or WRITE statement
Chapter 12. Handling errors
191
|
|
v ERROR declaratives
v FILE STATUS clauses
|
|
For VSAM files, if you specify a FILE STATUS clause, you can also test the VSAM
return code to direct your program to error-handling logic.
If you choose to have your program continue (by incorporating error-handling
code into your design), you must code the appropriate error-recovery procedure.
You might code, for example, a procedure to check the value of the file status key.
If you do not handle an input or output error in any of these ways, a severity-3
Language Environment condition is signaled, which causes the run unit to end if
the condition is not handled.
|
The following figures show the flow of logic after the indicated errors:
v VSAM input or output error
v QSAM and line-sequential input or output error
|
The following figure shows the flow of logic after a VSAM input or output error:
192
Programming Guide
|
|
|
The following figure shows the flow of logic after an input or output error with
QSAM or line-sequential files. The error can be from a READ statement, a WRITE
statement, or a CLOSE statement with a REEL/UNIT clause (QSAM only).
Set status key
(if present)
Applicable*
imperative
phrase?
Yes
Execute
imperative
statement
Yes
Execute
ERROR
declarative
Yes
Test file**
status key
No
Associated
ERROR
declarative?
No
File-status
clause
specified ?
No
Terminate the run
unit with a message
Return to COBOL***
at the end of I/O
statement
|
|
*Possible phrases for QSAM are AT END, AT END-OF-PAGE, and INVALID KEY; for line
sequential, AT END.
|
**You need to write the code to test the file status key.
***Execution of your COBOL program continues after the input or output
statement that caused the error.
RELATED TASKS
“Using the end-of-file condition (AT END)”
“Coding ERROR declaratives” on page 194
“Using file status keys” on page 194
“Handling errors in QSAM files” on page 120
“Using VSAM return codes (VSAM files only)” on page 196
“Coding INVALID KEY phrases” on page 198
Using the end-of-file condition (AT END)
You code the AT END phrase of the READ statement to handle errors or normal
conditions, according to your program design. If you code an AT END phrase, on
end-of-file the phrase is performed. If you do not code an AT END phrase, the
associated ERROR declarative is performed.
Chapter 12. Handling errors
193
In many designs, reading sequentially to the end of a file is done intentionally, and
the AT END condition is expected. For example, suppose you are processing a file
containing transactions in order to update a master file:
PERFORM UNTIL TRANSACTION-EOF = “TRUE”
READ UPDATE-TRANSACTION-FILE INTO WS-TRANSACTION-RECORD
AT END
DISPLAY “END OF TRANSACTION UPDATE FILE REACHED”
MOVE “TRUE” TO TRANSACTION-EOF
END READ
. . .
END-PERFORM
Any NOT AT END phrase you code is performed only if the READ statement
completes successfully. If the READ operation fails because of a condition other than
end-of-file, neither the AT END nor the NOT AT END phrase is performed. Instead,
control passes to the end of the READ statement after performing any associated
declarative procedure.
You might choose to code neither an AT END phrase nor an EXCEPTION declarative
procedure, but a status key clause for the file. In that case, control passes to the
next sequential instruction after the input or output statement that detected the
end-of-file conditions. Here presumably you have some code to take appropriate
action.
RELATED REFERENCES
AT END phrases (IBM COBOL Language Reference)
Coding ERROR declaratives
You can code one or more ERROR declarative procedures in your COBOL program
that will be given control if an input or output error occurs. You can have:
v A single, common procedure for the entire program
v Procedures for each file open mode (whether INPUT, OUTPUT, I-O, or EXTEND)
v Individual procedures for each particular file
Place each such procedure in the declaratives section of your PROCEDURE DIVISION.
In your procedure, you can choose to try corrective action, retry the operation,
continue, or end execution. You can use the ERROR declaratives procedure in
combination with the file status key if you want a further analysis of the error.
If you continue processing a blocked file, you might lose the remaining records in
a block after the record that caused the error.
Write an ERROR declarative procedure if you want the system to return control to
your program after an error occurs. If you do not write an ERROR declarative
procedure, your job could be canceled or abnormally terminated after an error
occurs.
RELATED REFERENCES
EXCEPTION/ERROR declarative (IBM COBOL Language Reference)
Using file status keys
After each input or output statement is performed on a file, the system updates
values in the two digits of the file status key. In general, a zero in the first digit
indicates a successful operation, and a zero in both digits means there is nothing
194
Programming Guide
abnormal. Establish a file status key by using the FILE STATUS clause in the
FILE-CONTROL paragraph and data definitions in the DATA DIVISION.
FILE STATUS IS data-name-1
The variable data-name-1 specifies the two-character COBOL file status key that
should be defined in the WORKING-STORAGE SECTION. This data-name cannot be
variably located.
Your program can check the COBOL file status key to discover whether an error
has been made and, if so, what type of error it is. For example, suppose a FILE
STATUS clause is coded like this:
FILE STATUS IS FS-CODE
FS-CODE is used by COBOL to hold status information like this:
Follow these rules for each file:
v Define a different file status key for each file.
You can then determine the cause of a file input or output exception, such as an
application logic error or a disk error.
v Check the file status key after every input or output request.
If it contains a value other than 0, your program can issue an error message or
can act based on the value.
You do not have to reset the status key code, because it is set after each input or
output attempt.
For VSAM files, in addition to the file status key, you can code a second identifier
in the FILE STATUS clause to get more detailed information on VSAM input or
output requests.
You can use the status key alone, or in conjunction with the INVALID KEY option, or
to supplement the EXCEPTION or ERROR declarative. Using the status key in this way
gives you precise information about the results of each input or output operation.
“Example: file status key”
Example: file status key
This COBOL code performs a simple check on the status key after opening a file.
IDENTIFICATION DIVISION.
PROGRAM-ID. SIMCHK.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT MASTERFILE ASSIGN TO AS-MASTERA
FILE STATUS IS MASTER-CHECK-KEY
. . .
DATA DIVISION.
. . .
Chapter 12. Handling errors
195
WORKING-STORAGE SECTION.
01 MASTER-CHECK-KEY
PIC X(2).
. . .
PROCEDURE DIVISION.
. . .
OPEN INPUT MASTERFILE
IF MASTER-CHECK-KEY NOT = “00”
DISPLAY “Nonzero file status returned from OPEN ” MASTER-CHECK-KEY
. . .
Using VSAM return codes (VSAM files only)
Often the two-character FILE STATUS code is too general to pinpoint the disposition
of a request. You can get more detailed information about VSAM input or output
requests by coding a second status area:
FILE STATUS IS data-name-1 data-name-8
The variable data-name-1 specifies the two-character COBOL file status key. The
variable data-name-8 specifies a 6-byte data item that contains the VSAM return
code when the COBOL file status key is not 0.
You can define the second status area, data-name-8, in the WORKING-STORAGE SECTION
as in VSAM-CODE here:
01 RETURN-STATUS.
05 FS-CODE
05 VSAM-CODE.
10 VSAM-R15-RETURN
10 VSAM-FUNCTION
10 VSAM-FEEDBACK
PIC X(2).
PIC S9(4) Usage Binary.
PIC S9(4) Usage Binary.
PIC S9(4) Usage Binary.
COBOL for OS/390 & VM uses data-name-8 to pass information supplied by
VSAM. In the following example, FS-CODE corresponds to data-name-1 and
VSAM-CODE corresponds to data-name-8:
“Example: checking VSAM status codes”
Example: checking VSAM status codes
This COBOL code does the following actions:
v Reads an indexed file (starting at the fifth record)
v Checks the file status key after each input or output request
v Displays the VSAM codes when the file status key is not zero
196
Programming Guide
This example also illustrates how output from this program might look if the file
being processed contains six records.
IDENTIFICATION DIVISION
PROGRAM-ID. EXAMPLE.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT VSAMFILE ASSIGN TO VSAMFILE
ORGANIZATION IS INDEXED
ACCESS DYNAMIC
RECORD KEY IS VSAMFILE-KEY
FILE STATUS IS FS-CODE VSAM-CODE.
DATA DIVISION.
FILE SECTION.
FD VSAMFILE
RECORD 30.
01 VSAMFILE-REC.
10 VSAMFILE-KEY
PIC X(6).
10 FILLER
PIC X(24).
WORKING-STORAGE SECTION.
01 RETURN-STATUS.
05 FS-CODE
PIC XX.
05 VSAM-CODE.
10 VSAM-RETURN-CODE
PIC S9(2) Usage Binary.
10 VSAM-COMPONENT-CODE
PIC S9(1) Usage Binary.
10 VSAM-REASON-CODE
PIC S9(3) Usage Binary.
PROCEDURE DIVISION.
OPEN INPUT VSAMFILE.
DISPLAY “OPEN INPUT VSAMFILE FS-CODE: ” FS-CODE.
IF FS-CODE NOT = “00”
PERFORM VSAM-CODE-DISPLAY
STOP RUN
END-IF.
MOVE “000005” TO VSAMFILE-KEY.
START VSAMFILE KEY IS EQUAL TO VSAMFILE-KEY.
DISPLAY “START VSAMFILE KEY=” VSAMFILE-KEY
“ FS-CODE: ” FS-CODE.
IF FS-CODE NOT = “00”
PERFORM VSAM-CODE-DISPLAY
END-IF.
IF FS-CODE = “00”
PERFORM READ-NEXT UNTIL FS-CODE NOT = “00”
END-IF.
CLOSE VSAMFILE.
STOP RUN.
READ-NEXT.
READ VSAMFILE NEXT.
DISPLAY “READ NEXT VSAMFILE FS-CODE: ” FS-CODE.
IF FS-CODE NOT = “00”
PERFORM VSAM-CODE-DISPLAY
END-IF.
DISPLAY VSAMFILE-REC.
VSAM-CODE-DISPLAY.
DISPLAY “VSAM-CODE ==>”
“ RETURN: ” VSAM-RETURN-CODE,
“ COMPONENT: ” VSAM-COMPONENT-CODE,
“ REASON: ” VSAM-REASON-CODE.
Below is a sample of the output from the example program that checks VSAM
code information:
Chapter 12. Handling errors
197
OPEN INPUT VSAMFILE FS-CODE: 00
START VSAMFILE KEY=000005 FS-CODE: 00
READ NEXT VSAMFILE FS-CODE: 00
000005 THIS IS RECORD NUMBER 5
READ NEXT VSAMFILE FS-CODE: 00
000006 THIS IS RECORD NUMBER 6
READ NEXT VSAMFILE FS-CODE: 10
VSAM-CODE ==> RETURN: 08 COMPONENT: 2 REASON: 004
Coding INVALID KEY phrases
You can include INVALID KEY phrases on READ, START, WRITE, REWRITE, and DELETE
requests for VSAM indexed and relative files. The INVALID KEY phrase is given
control if an input or output error occurs because of a faulty index key.
Use the FILE STATUS clause with INVALID KEY to evaluate the status key and
determine the specific INVALID KEY condition.
You can also include INVALID KEY on WRITE requests for QSAM files, but the
INVALID KEY phrase has limited meaning here. It is used only if you try to write to
a disk that is full.
INVALID KEY and ERROR declaratives
INVALID KEY phrases differ from ERROR declaratives in these ways:
v INVALID KEY phrases operate for only limited types of errors, whereas the ERROR
declarative encompasses all forms.
v INVALID KEY phrases are coded directly onto the input or output verb, whereas
ERROR declaratives are coded separately.
v INVALID KEY phrases are specific for a single input or output operation, whereas
ERROR declaratives are more general.
If you code INVALID KEY in a statement that causes an INVALID KEY condition,
control is transferred to the INVALID KEY imperative statement. Here, any ERROR
declaratives you have coded are not performed.
NOT INVALID KEY
A NOT INVALID KEY phrase that you code is performed only if the statement
completes successfully. If the operation fails because of a condition other than
INVALID KEY, neither the INVALID KEY nor the NOT INVALID KEY phrase is
performed. Instead control passes to the end of the statement after the program
performs any associated ERROR declaratives.
“Example: FILE STATUS and INVALID KEY”
Example: FILE STATUS and INVALID KEY
Assume you have a file containing master customer records and need to update
some of these records with information in a transaction update file. The program
reads each transaction record, finds the corresponding record in the master file,
and makes the necessary updates. The records in both files contain a field for a
customer number, and each record in the master file has a unique customer
number.
The FILE-CONTROL entry for the master file of customer records includes statements
defining indexed organization, random access, MASTER-CUSTOMER-NUMBER as the
prime record key, and CUSTOMER-FILE-STATUS as the file status key. The following
example shows how you can use FILE STATUS with the INVALID KEY to more
specifically determine why an input or output statement failed.
198
Programming Guide
.
. (read the update transaction record)
.
MOVE “TRUE” TO TRANSACTION-MATCH
MOVE UPDATE-CUSTOMER-NUMBER TO MASTER-CUSTOMER-NUMBER
READ MASTER-CUSTOMER-FILE INTO WS-CUSTOMER-RECORD
INVALID KEY
DISPLAY “MASTER CUSTOMER RECORD NOT FOUND”
DISPLAY “FILE STATUS CODE IS: ” CUSTOMER-FILE-STATUS
MOVE “FALSE” TO TRANSACTION-MATCH
END-READ
Handling errors when calling programs
When a program dynamically calls a separately compiled program, the called
program might be unavailable to the system. For example, the system could run
out of storage or it could be unable to locate the load module. If you do not have
an ON EXCEPTION or ON OVERFLOW clause on the CALL statement, your application
might abend.
Use the ON EXCEPTION clause to perform a series of statements and to perform your
own error handling. For example:
MOVE “REPORTA” TO REPORT-PROG
CALL REPORT-PROG
ON EXCEPTION
DISPLAY “Program REPORTA not available, using REPORTB.'
MOVE ”REPORTB“ TO REPORT-PROG
CALL REPORT-PROG
END-CALL
END-CALL
If program REPORTA is unavailable, control will continue with the ON EXCEPTION
clause.
The behavior of the ON EXCEPTION/OVERFLOW clause is sensitive to the CMPR2
compiler option.
The ON EXCEPTION clause applies only to the availability of the called program. If
an error occurs while the called program is running, the ON EXCEPTION clause will
not be performed.
RELATED TASKS
COBOL for OS/390 & VM Compiler and Run-Time Migration Guide
RELATED REFERENCES
“CMPR2” on page 264
Writing routines for handling errors
You can handle most error conditions that might occur while your program is
running by using the ON EXCEPTION phrase, the ON SIZE ERROR phrase, and other
language constructs. But if an extraordinary condition like a machine check occurs,
normally your application will not regain control—it will be abnormally
terminated.
However, COBOL for OS/390 & VM and Language Environment provide a way
for a user-written program to gain control when such conditions occur. Using
Chapter 12. Handling errors
199
Language Environment condition handling you can write your own error-handling
programs in COBOL. They can report, analyze, or even fix up and allow your
program to resume running.
To have Language Environment pass control to your user-written error program,
you must first identify and register its entry point to Language Environment.
PROCEDURE-POINTER data items allow you to pass the entry address of procedure
entry points to Language Environment services.
RELATED TASKS
“Using procedure pointers” on page 472
200
Programming Guide
Part 2. Compiling and debugging your program
Chapter 13. Compiling under OS/390. . . . .
Compiling with JCL . . . . . . . . . . .
Using a cataloged procedure . . . . . . .
Compile procedure (IGYWC) . . . . . .
Compile and link-edit procedure (IGYWCL)
Compile, link-edit, and run procedure
(IGYWCLG) . . . . . . . . . . . .
Compile, load, and run procedure (IGYWCG)
Compile, prelink, and link-edit procedure
(IGYWCPL) . . . . . . . . . . . .
Compile, prelink, link-edit, and run
procedure (IGYWCPLG) . . . . . . . .
Prelink and link-edit procedure (IGYWPL)
Compile, prelink, load, and run procedure
(IGYWCPG) . . . . . . . . . . . .
Writing JCL to compile programs. . . . . .
Example: user-written JCL for compiling . .
Compiling under TSO . . . . . . . . . .
Example: ALLOCATE and CALL for compiling
under TSO . . . . . . . . . . . . .
Example: CLIST for compiling under TSO . . .
Starting the compiler from an assembler program
Defining compiler input and output . . . . . .
Data sets used by the compiler under OS/390
Logical record length and block size. . . .
Defining the source code data set (SYSIN) . . .
Specifying source libraries (SYSLIB) . . . . .
Defining the output data set (SYSPRINT) . . .
Directing compiler messages to your terminal
(SYSTERM) . . . . . . . . . . . . .
Creating object code (SYSLIN or SYSPUNCH)
Creating an associated data file (SYSADATA)
Defining the output IDL data set (SYSIDL) . .
Defining the debug data set (SYSDEBUG) . . .
Specifying compiler options under OS/390 . . .
Specifying compiler options with the PROCESS
(CBL) statement . . . . . . . . . . .
Example: specifying compiler options using JCL
Example: specifying compiler options under
TSO . . . . . . . . . . . . . . .
Compiler options and compiler output under
OS/390 . . . . . . . . . . . . . .
Compiling multiple programs (batch compilation)
Example: batch compilation . . . . . . .
Specifying compiler options in a batch
compilation . . . . . . . . . . . . .
Example: precedence of options in a batch
compilation . . . . . . . . . . . . .
Example: LANGUAGE option in a batch
compilation . . . . . . . . . . . . .
Correcting errors in your source program . . . .
Generating a list of compiler error messages . .
Messages and listings for compiler-detected
errors . . . . . . . . . . . . . . .
Format of compiler error messages . . . . .
Severity codes for compiler error messages . .
© Copyright IBM Corp. 1991, 2000
203
203
204
205
206
207
208
209
210
211
212
213
214
215
215
216
216
218
218
219
220
220
221
221
221
222
222
222
223
223
224
224
224
226
226
227
228
229
230
230
231
231
232
Chapter 14. Compiling under OS/390 UNIX . .
Setting environment variables under OS/390 UNIX
Specifying compiler options under OS/390 UNIX
Compiling and linking with the cob2 command
Defining input and output . . . . . . . .
Creating a DLL . . . . . . . . . . . .
Example: using cob2 to compile under OS/390
UNIX . . . . . . . . . . . . . . .
cob2 . . . . . . . . . . . . . . .
cob2 input and output files . . . . . . . .
Compiling using scripts . . . . . . . . . .
235
235
236
237
237
238
Chapter 15. Compiling under CMS . . . . .
Accessing the compiler (CP LINK and ACCESS)
Specifying a source program to compile . . . .
COBOL2 . . . . . . . . . . . . . .
Using compiler-directing statements . . . . . .
Specifying compiler options under CMS . . . .
Using parentheses in COBOL2 . . . . . .
Abbreviating compiler options . . . . . .
Using logical line-editing characters . . . . .
Additional compiler options under CMS . . .
Differences in compiler options under CMS . .
Precedence of compiler options under CMS . .
Files used by the compiler under CMS . . . .
Compiler options and compiler output under
CMS . . . . . . . . . . . . . .
Naming generated files under CMS . . . . . .
Overriding FILEDEF . . . . . . . . . .
Using system-generated names . . . . . .
Correcting errors . . . . . . . . . . . .
Error messages from COBOL2 . . . . . . .
243
243
244
244
245
246
246
246
247
247
248
248
248
238
239
240
241
249
251
251
251
252
252
Chapter 16. Compiler options . . . . . . . 257
Option settings for COBOL 85 Standard
conformance. . . . . . . . . . . . . . 259
Conflicting compiler options . . . . . . . . 259
ADATA . . . . . . . . . . . . . . . 261
ANALYZE . . . . . . . . . . . . . . 261
ADV . . . . . . . . . . . . . . . . 262
ARITH . . . . . . . . . . . . . . . 262
AWO . . . . . . . . . . . . . . . . 263
BUFSIZE . . . . . . . . . . . . . . . 263
CMPR2 . . . . . . . . . . . . . . . 264
COMPILE . . . . . . . . . . . . . . 265
CURRENCY . . . . . . . . . . . . . . 265
DATA . . . . . . . . . . . . . . . . 266
External data . . . . . . . . . . . . 267
QSAM input/output buffers . . . . . . . 267
DATEPROC . . . . . . . . . . . . . . 267
DBCS . . . . . . . . . . . . . . . . 269
DECK . . . . . . . . . . . . . . . . 269
DIAGTRUNC . . . . . . . . . . . . . 269
DISK/PRINT . . . . . . . . . . . . . 270
DLL . . . . . . . . . . . . . . . . 270
DUMP . . . . . . . . . . . . . . . 271
201
DYNAM . . . . . . . .
EXIT . . . . . . . . .
EXPORTALL . . . . . .
FASTSRT . . . . . . . .
FLAG . . . . . . . . .
FLAGMIG . . . . . . .
FLAGSTD . . . . . . .
IDLGEN . . . . . . . .
INTDATE . . . . . . .
LANGUAGE . . . . . .
LIB . . . . . . . . . .
LINECOUNT . . . . . .
LIST . . . . . . . . .
MAP . . . . . . . . .
NAME . . . . . . . .
NUMBER . . . . . . .
NUMPROC . . . . . . .
OBJECT . . . . . . . .
OFFSET . . . . . . . .
OPTIMIZE . . . . . . .
Unused data items: . . .
OUTDD . . . . . . . .
PGMNAME . . . . . . .
PGMNAME(COMPAT) . .
PGMNAME(LONGUPPER).
PGMNAME(LONGMIXED)
PGMNAME usage notes. .
QUOTE/APOST . . . . .
RENT . . . . . . . . .
RMODE . . . . . . . .
SEQUENCE . . . . . . .
SIZE . . . . . . . . .
SOURCE . . . . . . . .
SPACE . . . . . . . .
SQL . . . . . . . . .
SSRANGE . . . . . . .
TERMINAL . . . . . . .
TEST . . . . . . . . .
TRUNC . . . . . . . .
TRUNC example 1 . . .
TRUNC example 2 . . .
TYPECHK . . . . . . .
VBREF . . . . . . . .
WORD . . . . . . . .
XREF . . . . . . . . .
YEARWINDOW . . . . .
ZWB . . . . . . . . .
Compiler-directing statements .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
272
272
272
273
274
275
275
277
278
279
280
280
281
281
282
283
283
284
285
285
286
286
287
287
288
288
288
289
289
290
291
291
292
293
293
294
295
295
297
298
299
300
301
301
302
303
304
304
Chapter 17. Debugging . . . . . . . . . 309
Debugging with source language . . . . . . . 310
Tracing program logic . . . . . . . . . 310
Finding and handling input-output errors . . . 311
Validating data . . . . . . . . . . . . 311
Finding uninitialized data . . . . . . . . 311
Generating information about procedures . . . 312
Debugging lines . . . . . . . . . . 312
Debugging statements . . . . . . . . 312
Example: USE FOR DEBUGGING . . . . 312
Debugging using compiler options . . . . . . 313
Finding coding errors . . . . . . . . . 314
202
Programming Guide
Checking syntax only. . . . . . . .
Compiling conditionally . . . . . . .
Finding line sequence problems . . . . .
Checking for valid ranges . . . . . . .
Selecting the level of error to be diagnosed .
Example: embedded messages. . . . .
Finding program entity definitions and
references . . . . . . . . . . . .
Listing data items . . . . . . . . . .
Getting listings . . . . . . . . . . . .
Example: short listing . . . . . . . .
Example: SOURCE and NUMBER output . .
Example: MAP output . . . . . . .
Example: embedded map summary . . . .
Terms used in MAP output. . . . . . .
Symbols used in LIST and MAP output . .
Example: nested program map . . . . .
Reading LIST output . . . . . . . . .
Example: program initialization code . .
Signature information bytes: compiler
options . . . . . . . . . . . .
Signature information bytes: DATA
DIVISION . . . . . . . . . . .
Signature information bytes:
ENVIRONMENT DIVISION . . . . .
Signature information bytes: PROCEDURE
DIVISION verbs . . . . . . . . .
Signature information bytes: more
PROCEDURE DIVISION items . . . .
Example: assembler code generated from
source code . . . . . . . . . . .
Example: TGT memory map . . . . .
Example: location and size of
WORKING-STORAGE . . . . . . .
Example: DSA memory map . . . . .
Example: XREF output - data-name
cross-references. . . . . . . . . . .
Example: XREF output - program-name
cross-references. . . . . . . . . . .
Example: embedded cross-reference . . . .
Example: OFFSET compiler output . . . .
Example: VBREF compiler output . . . .
Preparing to use the debugger. . . . . . .
.
.
.
.
.
.
314
314
315
315
316
316
.
.
.
.
.
.
.
.
.
.
.
.
317
318
319
320
323
324
325
326
326
328
328
329
. 331
. 333
. 333
. 333
. 335
. 336
. 338
. 339
. 339
. 340
.
.
.
.
.
341
341
342
343
343
Chapter 13. Compiling under OS/390
You can compile COBOL for OS/390 & VM programs under OS/390 using job
control language (JCL), TSO commands, CLISTs, or ISPF panels:
v For compiling with JCL, IBM provides a set of cataloged procedures, which can
reduce the amount of JCL coding that you need to write. If the cataloged
procedures do not meet your needs, you can write your own JCL. Using JCL,
you can compile a single program or compile several programs as part of a
batch job.
v When compiling under TSO, you can use TSO commands, CLISTs, or ISPF
panels.
You might also want to start the COBOL for OS/390 & VM compiler from an
assembler program, such as when your shop has developed a tool or interface that
calls the COBOL for OS/390 & VM compiler.
Whether you are compiling using JCL or under TSO, as part of the compilation
step, you need to define the data sets needed for the compilation and specify any
compiler options necessary for your program and the desired output.
The compiler translates your COBOL program into language that the computer can
process (object code). The compiler also lists errors in your source statements and
provides supplementary information to help you debug and tune your program.
Use compiler-directing statements and compiler options to control your
compilation.
After compiling your program, you need to review the results of the compilation
and correct any compiler-detected errors.
RELATED TASKS
“Compiling with JCL”
“Compiling under TSO” on page 215
“Starting the compiler from an assembler program” on page 216
“Defining compiler input and output” on page 218
“Specifying compiler options under OS/390” on page 223
“Compiling multiple programs (batch compilation)” on page 226
“Correcting errors in your source program” on page 230
RELATED REFERENCES
“Compiler-directing statements” on page 304
“Data sets used by the compiler under OS/390” on page 218
“Compiler options and compiler output under OS/390” on page 224
Compiling with JCL
|
|
You need to include the following information in the JCL for compilation:
v Job description
v Statement to run the compiler
v Definitions for the data sets needed (including the directory paths if using HFS
files)
© Copyright IBM Corp. 1991, 2000
203
The simplest way to compile your program under OS/390 is to code JCL that uses
a cataloged procedure. A cataloged procedure is a set of job control statements placed
in a partitioned data set called the procedure library (SYS1.PROCLIB).
The following JCL shows the general format for a cataloged procedure.
//jobname JOB parameters
//stepname EXEC [PROC=]procname[,{PARM=│PARM.stepname=}'options']
//SYSIN
DD data set parameters
. . .
(source program to be compiled)
/*
//
Additional considerations apply when you use cataloged procedures to compile
object-oriented programs.
“Example: sample JCL for an object-oriented application” on page 418
“Example: sample JCL for a procedural DLL application” on page 492
RELATED TASKS
“Using a cataloged procedure”
“Writing JCL to compile programs” on page 213
“Specifying compiler options under OS/390” on page 223
“Specifying compiler options in a batch compilation” on page 227
“Compiling programs to create DLLs” on page 490
RELATED REFERENCES
“Data sets used by the compiler under OS/390” on page 218
Using a cataloged procedure
Specify a cataloged procedure in an EXEC statement in your JCL.
The following JCL calls the IBM-supplied cataloged procedure (IGYWC) for
compiling a COBOL for OS/390 & VM program and defining the required data
sets:
You can use these procedures with any of the job schedulers that are part of
OS/390. When a scheduler encounters parameters that it does not require, the
scheduler either ignores them or substitutes alternative parameters.
If the compiler options are not explicitly supplied with the procedure, default
options established at the installation apply. You can override these default options
by using an EXEC statement that includes the desired options.
You can specify data sets to be in the hierarchical file system by overriding the
corresponding DD statement. However, the compiler utility files (SYSUTx) and copy
libraries (SYSLIB) you specify must be MVS data sets.
|
|
|
204
Programming Guide
Additional details on invoking cataloged procedures, overriding and adding to
EXEC statements, and overriding and adding to DD statements are in the Language
Environment information.
RELATED TASKS
Language Environment Programming Guide
RELATED REFERENCES
“Compile procedure (IGYWC)”
“Compile and link-edit procedure (IGYWCL)” on page 206
“Compile, link-edit, and run procedure (IGYWCLG)” on page 207
“Compile, load, and run procedure (IGYWCG)” on page 208
“Compile, prelink, and link-edit procedure (IGYWCPL)” on page 209
“Compile, prelink, link-edit, and run procedure (IGYWCPLG)” on page 210
“Prelink and link-edit procedure (IGYWPL)” on page 211
“Compile, prelink, load, and run procedure (IGYWCPG)” on page 212
Compile procedure (IGYWC)
The IGYWC procedure is a single-step procedure for compiling a program. It
produces an object module. The compile steps in all other cataloged procedures
that invoke the compiler are similar.
You must supply the following DD statement, indicating the location of the source
program, in the input stream.
//COBOL.SYSIN DD
*
(or appropriate parameters)
The following statements make up the IGYWC cataloged procedure.
//IGYWC PROC LNGPRFX='IGY.V2R2M0',SYSLBLK=3200
//*
//* COMPILE A COBOL PROGRAM
//*
//* PARAMETER DEFAULT VALUE
USAGE
//*
SYSLBLK
3200
BLKSIZE FOR OBJECT DATA SET
//*
LNGPRFX IGY.V2R2M0
PREFIX FOR LANGUAGE DATA SET NAMES
//*
//* CALLER MUST SUPPLY //COBOL.SYSIN DD . . .
//*
//COBOL EXEC PGM=IGYCRCTL,REGION=2048K
//STEPLIB DD DSNAME=&LNGPRFX..SIGYCOMP,
(1)
//
DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN
DD DSNAME=&&LOADSET,UNIT=SYSDA,
//
DISP=(MOD,PASS),SPACE=(TRK,(3,3)),
//
DCB=(BLKSIZE=&SYSLBLK)
//SYSUT1
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT2
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT3
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT4
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT5
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
(2)
//SYSUT6
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT7
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
(1) STEPLIB can be installation-dependent.
(2) SYSUT5 is needed only if the LIB option is used.
“Example: JCL for compiling using HFS”
|
|
Example: JCL for compiling using HFS: The following job uses procedure
IGYWC to compile a COBOL program demo.cbl that is located in the hierarchical
Chapter 13. Compiling under OS/390
205
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
file system (HFS). It writes the generated compiler listing demo.lst, object file
demo.o, Interface Definition Language file demo.idl, and SYSADATA file demo.adt
to the HFS.
|
(1)
PATH specifies the path name for an HFS file.
|
|
(2)
PATHOPTS indicates the access for the file (such as read or read-write) and
sets the status for the file (such as append, create, or truncate).
|
|
(3)
PATHMODE indicates the permissions, or file access attributes, to be set when
a file is created.
|
(4)
FILEDATA specifies whether the data is to be treated as text or binary.
|
|
|
|
You can use a mixture of HFS (PATH=’hfs-directory-path’) and MVS data sets
(DSN=traditional-data-set-name) on the compilation DD statements shown in this
example as overrides. However, the compiler utility files (DD statements SYSUTx)
and COPY libraries (DD statements SYSLIB) must be MVS data sets.
//HFSDEMO JOB ,
// TIME=(1),MSGLEVEL=(1,1),MSGCLASS=H,CLASS=A,REGION=50M,
// NOTIFY=&SYSUID,USER=&SYSUID
//COMPILE EXEC IGYWC,
// PARM.COBOL='LIST,MAP,RENT,FLAG(I,I),XREF,ADATA,IDLGEN'
//SYSPRINT DD PATH='/u/userid/cobol/demo.lst',
(1)
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
(2)
// PATHMODE=SIRWXU,
(3)
// FILEDATA=TEXT
(4)
//SYSLIN DD PATH='/u/userid/cobol/demo.o',
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU
//SYSIDL DD PATH='/u/userid/cobol/demo.idl',
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU,
// FILEDATA=TEXT
//SYSADATA DD PATH='/u/userid/cobol/demo.adt',
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU
//SYSIN DD PATH='/u/userid/cobol/demo.cbl',
// PATHOPTS=ORDONLY,
// FILEDATA=TEXT,
// RECFM=F
RELATED REFERENCES
OS/390 UNIX System Services Command Reference
OS/390 MVS JCL Reference
“Data sets used by the compiler under OS/390” on page 218
Compile and link-edit procedure (IGYWCL)
The IGYWCL procedure is a two-step procedure to compile and link-edit a
program. The COBOL job step produces an object module that is input to the
linkage editor. Other object modules can be added.
You must supply the following DD statement, indicating the location of the source
program, in the input stream.
//COBOL.SYSIN DD
*
(or appropriate parameters)
The following statements make up the IGYWCL cataloged procedure.
//IGYWCL PROC LNGPRFX='IGY.V2R2M0',SYSLBLK=3200,
//
LIBPRFX='CEE',
//
PGMLIB='&&GOSET',GOPGM=GO
//*
//* COMPILE AND LINK EDIT A COBOL PROGRAM
206
Programming Guide
//*
//* PARAMETER DEFAULT VALUE
USAGE
//*
LNGPRFX IGY.V2R2M0
PREFIX FOR LANGUAGE DATA SET NAMES
//*
SYSLBLK
3200
BLOCK SIZE FOR OBJECT DATA SET
//*
LIBPRFX CEE
PREFIX FOR LIBRARY DATA SET NAMES
//*
PGMLIB
&&GOSET
DATA SET NAME FOR LOAD MODULE
//*
GOPGM
GO
MEMBER NAME FOR LOAD MODULE
//*
//* CALLER MUST SUPPLY //COBOL.SYSIN DD . . .
//*
//COBOL EXEC PGM=IGYCRCTL,REGION=2048K
//STEPLIB DD DSNAME=&LNGPRFX..SIGYCOMP,
(1)
//
DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN
DD DSNAME=&&LOADSET,UNIT=SYSDA,
//
DISP=(MOD,PASS),SPACE=(TRK,(3,3)),
//
DCB=(BLKSIZE=&SYSLBLK)
//SYSUT1
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT2
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT3
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT4
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT5
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
(2)
//SYSUT6
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT7
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//LKED
EXEC PGM=HEWL,COND=(8,LT,COBOL),REGION=1024K
//SYSLIB
DD DSNAME=&LIBPRFX..SCEELKED,
(3)
//
DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN
DD DSNAME=&&LOADSET,DISP=(OLD,DELETE)
//
DD DDNAME=SYSIN
//SYSLMOD DD DSNAME=&PGMLIB(&GOPGM),
//
SPACE=(TRK,(10,10,1)),
//
UNIT=SYSDA,DISP=(MOD,PASS)
//SYSUT1
DD UNIT=SYSDA,SPACE=(TRK,(10,10))
(1) STEPLIB can be installation-dependent.
(2) SYSUT5 is needed only if the LIB option is used.
(3) SYSLIB can be installation-dependent.
Compile, link-edit, and run procedure (IGYWCLG)
The IGYWCLG procedure is a three-step procedure to compile, link-edit, and run a
program.
The COBOL job step produces an object module that is input to the linkage editor.
Other object modules can be added. If the COBOL program refers to any data sets,
DD statements that define these data sets must also be supplied.
You must supply the following DD statement, indicating the location of the source
program, in the input stream.
//COBOL.SYSIN DD
*
(or appropriate parameters)
The following shows the statements that make up the IGYWCLG cataloged
procedure.
//IGYWCLG PROC LNGPRFX='IGY.V2R2M0',SYSLBLK=3200,
//
LIBPRFX='CEE',GOPGM=GO
//*
//* COMPILE, LINK EDIT AND RUN A COBOL PROGRAM
//*
//* PARAMETER DEFAULT VALUE
USAGE
//*
LNGPRFX IGY.V2R2M0
PREFIX FOR LANGUAGE DATA SET NAMES
//*
SYSLBLK
3200
BLKSIZE FOR OBJECT DATA SET
//*
LIBPRFX CEE
PREFIX FOR LIBRARY DATA SET NAMES
//*
GOPGM
GO
MEMBER NAME FOR LOAD MODULE
Chapter 13. Compiling under OS/390
207
//*
//* CALLER MUST SUPPLY //COBOL.SYSIN DD . . .
//*
//COBOL EXEC PGM=IGYCRCTL,REGION=2048K
//STEPLIB DD DSNAME=&LNGPRFX..SIGYCOMP,
(1)
//
DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN
DD DSNAME=&&LOADSET,UNIT=SYSDA,
//
DISP=(MOD,PASS),SPACE=(TRK,(3,3)),
//
DCB=(BLKSIZE=&SYSLBLK)
//SYSUT1
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT2
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT3
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT4
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT5
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
(2)
//SYSUT6
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT7
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//LKED
EXEC PGM=HEWL,COND=(8,LT,COBOL),REGION=1024K
//SYSLIB
DD DSNAME=&LIBPRFX..SCEELKED,
(3)
//
DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN
DD DSNAME=&&LOADSET,DISP=(OLD,DELETE)
//
DD DDNAME=SYSIN
//SYSLMOD DD DSNAME=&&GOSET(&GOPGM),SPACE=(TRK,(10,10,1)),
//
UNIT=SYSDA,DISP=(MOD,PASS)
//SYSUT1
DD UNIT=SYSDA,SPACE=(TRK,(10,10))
//GO
EXEC PGM=*.LKED.SYSLMOD,COND=((8,LT,COBOL),(4,LT,LKED)),
//
REGION=2048K
//STEPLIB DD DSNAME=&LIBPRFX..SCEERUN,
(1)
//
DISP=SHR
//SYSPRINT DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
(1) STEPLIB can be installation-dependent.
(2) SYSUT5 is needed only if the LIB option is used.
(3) SYSLIB can be installation-dependent.
Compile, load, and run procedure (IGYWCG)
The IGYWCG procedure is a two-step procedure to compile, load, and run a
program. The COBOL job step produces an object module that is input to the
loader. If the COBOL program refers to any data sets, the DD statements that define
these data sets must also be supplied.
You must supply the following DD statement, indicating the location of the source
program, in the input stream.
//COBOL.SYSIN DD
*
(or appropriate parameters)
The following shows the statements that make up the IGYWCG cataloged
procedure.
//IGYWCG PROC LNGPRFX='IGY.V2R2M0',SYSLBLK=3200,
//
LIBPRFX='CEE'
//*
//* COMPILE, LOAD AND RUN A COBOL PROGRAM
//*
//* PARAMETER DEFAULT VALUE
USAGE
//*
LNGPRFX IGY.V2R2M0
PREFIX FOR LANGUAGE DATA SET NAMES
//*
SYSLBLK
3200
BLKSIZE FOR OBJECT DATA SET
//*
LIBPRFX CEE
PREFIX FOR LIBRARY DATA SET NAMES
//*
//* CALLER MUST SUPPLY //COBOL.SYSIN DD . . .
//*
//COBOL EXEC PGM=IGYCRCTL,REGION=2048K
208
Programming Guide
//STEPLIB DD
//
//SYSPRINT DD
//SYSLIN
DD
//
//
//SYSUT1
DD
//SYSUT2
DD
//SYSUT3
DD
//SYSUT4
DD
//SYSUT5
DD
//SYSUT6
DD
//SYSUT7
DD
//GO
EXEC
//SYSLIB
DD
//
//SYSLOUT DD
//SYSLIN
DD
//STEPLIB DD
//
//SYSPRINT DD
//CEEDUMP DD
//SYSUDUMP DD
|
(1)
(2)
(3)
(4)
DSNAME=&LNGPRFX..SIGYCOMP,
DISP=SHR
SYSOUT=*
DSNAME=&&LOADSET,UNIT=SYSDA,
DISP=(MOD,PASS),SPACE=(TRK,(3,3)),
DCB=(BLKSIZE=&SYSLBLK)
UNIT=SYSDA,SPACE=(CYL,(1,1))
UNIT=SYSDA,SPACE=(CYL,(1,1))
UNIT=SYSDA,SPACE=(CYL,(1,1))
UNIT=SYSDA,SPACE=(CYL,(1,1))
UNIT=SYSDA,SPACE=(CYL,(1,1))
UNIT=SYSDA,SPACE=(CYL,(1,1))
UNIT=SYSDA,SPACE=(CYL,(1,1))
PGM=LOADER,COND=(8,LT,COBOL),REGION=2048K
DSNAME=&LIBPRFX..SCEELKED,
DISP=SHR
SYSOUT=*
DSNAME=&&LOADSET,DISP=(OLD,DELETE)
DSNAME=&LIBPRFX..SCEERUN,
DISP=SHR
SYSOUT=*
SYSOUT=*
SYSOUT=*
(1)
(2)
(3)
(4)
(1)
STEPLIB can be installation-dependent.
SYSLIN can reside in the HFS.
SYSUT5 is needed only if the LIB option is used.
SYSLIB can be installation-dependent.
Compile, prelink, and link-edit procedure (IGYWCPL)
The IGYWCPL procedure is a three-step procedure for compiling, prelinking, and
link-editing a program.
You must supply the following DD statement, indicating the location of the source
program, in the input stream.
SYSIN DD
*
(or appropriate parameters)
The following shows the statements that make up the IGYWCPL cataloged
procedure.
//IGYWCPL PROC LNGPRFX='IGY.V2R2M0',SYSLBLK=3200,
//
LIBPRFX='CEE',PLANG=EDCPMSGE,
//
PGMLIB='&&GOSET',GOPGM=GO
//*
//* COMPILE, PRELINK AND LINK EDIT A COBOL PROGRAM
//*
//* PARAMETER DEFAULT VALUE
USAGE
//*
LNGPRFX IGY.V2R2M0
PREFIX FOR LANGUAGE DATA SET NAMES
//*
SYSLBLK
3200
BLOCK SIZE FOR OBJECT DATA SET
//*
LIBPRFX CEE
PREFIX FOR LIBRARY DATA SET NAMES
//*
PLANG
EDCPMSGE
PRELINKER MESSAGES MODULE
//*
PGMLIB
&&GOSET
DATA SET NAME FOR LOAD MODULE
//*
GOPGM
GO
MEMBER NAME FOR LOAD MODULE
//*
//* CALLER MUST SUPPLY //COBOL.SYSIN DD . . .
//*
//COBOL EXEC PGM=IGYCRCTL,REGION=2048K
//STEPLIB DD DSNAME=&LNGPRFX..SIGYCOMP,
(1)
//
DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN
DD DSNAME=&&LOADSET,UNIT=SYSDA,
//
DISP=(MOD,PASS),SPACE=(TRK,(3,3)),
//
DCB=(BLKSIZE=&SYSLBLK)
//SYSUT1
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT2
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
Chapter 13. Compiling under OS/390
209
//SYSUT3
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT4
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT5
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
(2)
//SYSUT6
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT7
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//PLKED
EXEC PGM=EDCPRLK,PARM='',COND=(8,LT,COBOL),
//
REGION=2048K
//STEPLIB DD DSNAME=&LIBPRFX..SCEERUN,
//
DISP=SHR
//SYSMSGS DD DSNAME=&LIBPRFX..SCEEMSGP(&PLANG),
//
DISP=SHR
//SYSLIB
DD DUMMY
//SYSIN
DD DSN=&&LOADSET,DISP=(OLD,DELETE)
//SYSMOD
DD DSNAME=&&PLKSET,UNIT=SYSDA,DISP=(NEW,PASS),
//
SPACE=(32000,(100,50)),
//
DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)
//SYSDEFSD DD DUMMY
//SYSOUT
DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//*
//LKED
EXEC PGM=HEWL,COND=(8,LT,COBOL),REGION=1024K
//SYSLIB
DD DSNAME=&LIBPRFX..SCEELKED,
(3)
//
DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN
DD DSNAME=&&PLKSET,DISP=(OLD,DELETE)
//
DD DDNAME=SYSIN
//SYSLMOD DD DSNAME=&PGMLIB(&GOPGM),
//
SPACE=(TRK,(10,10,1)),
//
UNIT=SYSDA,DISP=(MOD,PASS)
//SYSUT1
DD UNIT=SYSDA,SPACE=(TRK,(10,10))
(1) STEPLIB can be installation-dependent.
(2) SYSUT5 is needed only if the LIB option is used.
(3) SYSLIB can be installation-dependent.
Compile, prelink, link-edit, and run procedure (IGYWCPLG)
The IGYWCPLG procedure is a four-step procedure for compiling, prelinking,
link-editing, and running a program.
You must supply the following DD statement, indicating the location of the source
program, in the input stream.
SYSIN DD
*
(or appropriate parameters)
The following shows the statements that make up the IGYWCPLG cataloged
procedure.
//IGYWCPLG PROC LNGPRFX='IGY.V2R2M0',SYSLBLK=3200,
//
PLANG=EDCPMSGE,
//
LIBPRFX='CEE',GOPGM=GO
//*
//* COMPILE, PRELINK, LINK EDIT, AND RUN A COBOL PROGRAM
//*
//* PARAMETER DEFAULT VALUE
USAGE
//*
LNGPRFX IGY.V2R2M0
PREFIX FOR LANGUAGE DATA SET NAMES
//*
SYSLBLK
3200
BLKSIZE FOR OBJECT DATA SET
//*
PLANG
EDCPMSGE
PRELINKER MESSAGES MODULE
//*
LIBPRFX CEE
PREFIX FOR LIBRARY DATA SET NAMES
//*
GOPGM
GO
MEMBER NAME FOR LOAD MODULE
//*
//* CALLER MUST SUPPLY //COBOL.SYSIN DD . . .
//*
//COBOL EXEC PGM=IGYCRCTL,REGION=2048K
//STEPLIB DD DSNAME=&LNGPRFX..SIGYCOMP,
(1)
//
DISP=SHR
//SYSPRINT DD SYSOUT=*
210
Programming Guide
//SYSLIN
DD DSNAME=&&LOADSET,UNIT=SYSDA,
//
DISP=(MOD,PASS),SPACE=(TRK,(3,3)),
//
DCB=(BLKSIZE=&SYSLBLK)
//SYSUT1
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT2
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT3
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT4
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT5
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
(2)
//SYSUT6
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT7
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//PLKED
EXEC PGM=EDCPRLK,PARM='',COND=(8,LT,COBOL),
//
REGION=2048K
//STEPLIB DD DSNAME=&LIBPRFX..SCEERUN,
//
DISP=SHR
//SYSMSGS DD DSNAME=&LIBPRFX..SCEEMSGP(&PLANG),
//
DISP=SHR
//SYSLIB
DD DUMMY
//SYSIN
DD DSN=&&LOADSET,DISP=(OLD,DELETE)
//SYSMOD
DD DSNAME=&&PLKSET,UNIT=SYSDA,DISP=(NEW,PASS),
//
SPACE=(32000,(100,50)),
//
DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)
//SYSDEFSD DD DUMMY
//SYSOUT
DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//*
//LKED
EXEC PGM=HEWL,COND=(8,LT,COBOL),REGION=1024K
//SYSLIB
DD DSNAME=&LIBPRFX..SCEELKED,
(3)
//
DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN
DD DSNAME=&&PLKSET,DISP=(OLD,DELETE)
//
DD DDNAME=SYSIN
//SYSLMOD DD DSNAME=&&GOSET(&GOPGM),SPACE=(TRK,(10,10,1)),
//
UNIT=SYSDA,DISP=(MOD,PASS)
//SYSUT1
DD UNIT=SYSDA,SPACE=(TRK,(10,10))
//GO
EXEC PGM=*.LKED.SYSLMOD,COND=((8,LT,COBOL),(4,LT,LKED)),
//
REGION=2048K
//STEPLIB DD DSNAME=&LIBPRFX..SCEERUN,
//
DISP=SHR
//SYSPRINT DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
(1) STEPLIB can be installation-dependent.
(2) SYSUT5 is needed only if the LIB option is used.
(3) SYSLIB can be installation-dependent.
Prelink and link-edit procedure (IGYWPL)
The IGYWPL procedure is a two-step procedure for prelinking and link-editing a
program.
The following statements make up the IGYWPL cataloged procedure.
//IGYWPL PROC PLANG=EDCPMSGE,SYSLBLK=3200,
//
LIBPRFX='CEE',
//
PGMLIB='&&GOSET',GOPGM=GO
//*
//* PRELINK AND LINK EDIT A COBOL PROGRAM
//*
//* PARAMETER DEFAULT VALUE
USAGE
//*
PLANG
EDCPMSGE
PRELINK MESSAGES MEMBER NAME
//*
SYSLBLK
3200
BLKSIZE FOR OBJECT DATA SET
//*
LIBPRFX CEE
PREFIX FOR LIBRARY DATA SET NAMES
//*
PGMLIB
&&GOSET
DATA SET NAME FOR LOAD MODULE
//*
GOPGM
GO
MEMBER NAME FOR LOAD MODULE
//*
//* CALLER MUST SUPPLY //PLKED.SYSIN DD . . .
Chapter 13. Compiling under OS/390
211
//*
//PLKED
EXEC PGM=EDCPRLK,PARM='',
//
REGION=2048K
//STEPLIB DD DSNAME=&LIBPRFX..SCEERUN,
(1)
//
DISP=SHR
//SYSMSGS DD DSNAME=&LIBPRFX..SCEEMSGP(&PLANG),
//
DISP=SHR
//SYSLIB
DD DUMMY
//SYSMOD
DD DSNAME=&&PLKSET,UNIT=SYSDA,DISP=(NEW,PASS),
//
SPACE=(32000,(100,50)),
//
DCB=(RECFM=FB,LRECL=80,BLKSIZE=&SYSLBLK)
//SYSDEFSD DD DUMMY
//SYSOUT
DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//*
//LKED
EXEC PGM=HEWL,COND=(4,LT,PLKED),REGION=1024K
//SYSLIB
DD DSNAME=&LIBPRFX..SCEELKED,
(2)
//
DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN
DD DSNAME=*.PLKED.SYSMOD,DISP=(OLD,DELETE)
//
DD DDNAME=SYSIN
//SYSLMOD DD DSNAME=&PGMLIB(&GOPGM),SPACE=(TRK,(10,10,1)),
//
UNIT=SYSDA,DISP=(MOD,PASS)
//SYSUT1
DD UNIT=SYSDA,SPACE=(TRK,(10,10))
//SYSIN
DD DUMMY
(1) STEPLIB can be installation-dependent.
(2) SYSLIB can be installation-dependent.
Compile, prelink, load, and run procedure (IGYWCPG)
The IGYWCPG procedure is a four-step procedure for compiling, prelinking,
loading, and running a program.
You must supply the following DD statement, indicating the location of the source
program, in the input stream.
//COBOL.SYSIN DD
*
(or appropriate parameters)
The following statements make up the IGYWCPG cataloged procedure.
//IGYWCPG PROC LNGPRFX='IGY.V2R2M0',SYSLBLK=3200,
//
PLANG=EDCPMSGE,
//
LIBPRFX='CEE'
//*
//* COMPILE, PRELINK, LOAD, AND RUN A COBOL PROGRAM
//*
//* PARAMETER DEFAULT VALUE
USAGE
//*
LNGPRFX IGY.V2R2M0
PREFIX FOR LANGUAGE DATA SET NAMES
//*
SYSLBLK
3200
BLKSIZE FOR OBJECT DATA SET
//*
PLANG
EDCPMSGE
PRELINKER MESSAGES MODULE
//*
LIBPRFX CEE
PREFIX FOR LIBRARY DATA SET NAMES
//*
//* CALLER MUST SUPPLY //COBOL.SYSIN DD . . .
//*
//COBOL
EXEC PGM=IGYCRCTL,REGION=2048K
//STEPLIB DD DSNAME=&LNGPRFX..SIGYCOMP,
(1)
//
DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN
DD DSNAME=&&LOADSET,UNIT=SYSDA,
//
DISP=(MOD,PASS),SPACE=(TRK,(3,3)),
//
DCB=(BLKSIZE=&SYSLBLK)
//SYSUT1
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT2
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT3
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT4
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT5
DD UNIT=SYSDA,SPACE=(CYL,(1,1))
(2)
212
Programming Guide
//SYSUT6
DD
//SYSUT7
DD
//PLKED
EXEC
//
//STEPLIB DD
//
//SYSMSGS DD
//
//SYSLIB
DD
//SYSIN
DD
//SYSMOD
DD
//
//
//SYSDEFSD DD
//SYSOUT
DD
//SYSPRINT DD
//*
//GO
EXEC
//SYSLIB
DD
//
//SYSLOUT DD
//SYSLIN
DD
//STEPLIB DD
//
//SYSPRINT DD
//CEEDUMP DD
//SYSUDUMP DD
|
(1)
(2)
(3)
(4)
UNIT=SYSDA,SPACE=(CYL,(1,1))
UNIT=SYSDA,SPACE=(CYL,(1,1))
PGM=EDCPRLK,PARM='',COND=(8,LT,COBOL),
REGION=2048K
DSNAME=&LIBPRFX..SCEERUN,
DISP=SHR
DSNAME=&LIBPRFX..SCEEMSGP(&PLANG),
DISP=SHR
DUMMY
DSN=&&LOADSET,DISP=(OLD,DELETE)
DSNAME=&&PLKSET,UNIT=SYSDA,DISP=(NEW,PASS), (3)
SPACE=(32000,(100,50)),
DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)
DUMMY
SYSOUT=*
SYSOUT=*
PGM=LOADER,COND=(8,LT,COBOL),REGION=2048K
DSNAME=&LIBPRFX..SCEELKED,
DISP=SHR
SYSOUT=*
DSNAME=&&PLKSET,DISP=(OLD,DELETE)
DSNAME=&LIBPRFX..SCEERUN,
DISP=SHR
SYSOUT=*
SYSOUT=*
SYSOUT=*
(4)
STEPLIB can be installation-dependent.
SYSUT5 is needed only if the LIB option is used.
SYSMOD can reside in the HFS.
SYSLIB can be installation-dependent.
Writing JCL to compile programs
If the cataloged procedures do not give you the OS/390 programming flexibility
you need for more complex programs, write your own job control statements. The
following JCL shows the general format used to compile a program:
//jobname
//stepname
//STEPLIB
//SYSUT1
//SYSUT2
//SYSUT3
//SYSUT4
//SYSUT5
//SYSUT6
//SYSUT7
//SYSPRINT
//SYSLIN
//
//SYSIN
JOB
EXEC
DD
DD
DD
DD
DD
DD
DD
DD
DD
DD
DD
acctno,name,MSGCLASS=1
PGM=IGYCRCTL,PARM=(options)
DSNAME=IGY.V2R2M0.SIGYCOMP,DISP=SHR
UNIT=SYSDA,SPACE=(subparms)
UNIT=SYSDA,SPACE=(subparms)
UNIT=SYSDA,SPACE=(subparms)
UNIT=SYSDA,SPACE=(subparms)
UNIT=SYSDA,SPACE=(subparms)
UNIT=SYSDA,SPACE=(subparms)
UNIT=SYSDA,SPACE=(subparms)
SYSOUT=A
DSNAME=MYPROG,UNIT=SYSDA,
DISP=(MOD,PASS),SPACE=(subparms)
DSNAME=dsname,UNIT=device,
VOLUME=(subparms),DISP=SHR
(1)
(2)
(3)
(4)
(5)
(6)
(7)
(1)
The JOB statement indicates the beginning of a job.
(2)
The EXEC statement specifies that the COBOL for OS/390 & VM compiler
(IGYCRCTL) is to be invoked.
(3)
This DD statement defines the data set where the COBOL for OS/390 & VM
compiler resides.
(4)
The SYSUT DD statements define the utility data sets that the compiler will
use to process the source program. All SYSUT files must be on
direct-access storage devices.
Chapter 13. Compiling under OS/390
213
(5)
The SYSPRINT DD statement defines the data set that receives output from
options such as LIST and MAP. SYSOUT=A is the standard designation for data
sets whose destination is the system output device.
(6)
The SYSLIN DD statement defines the data set that receives output from the
OBJECT option (the object module).
(7)
The SYSIN DD statement defines the data set to be used as input to the job
step (source code).
You can use a mixture of HFS (PATH=’hfs-directory-path’) and MVS data sets
(DSN=traditional-data-set-name) on the compilation DD statements for the
following data sets:
v Sources files
v Object files
v Listings
v Interface Definition Language files
v ADATA files
|
|
|
|
|
|
|
|
|
|
v Debug files
v Executable modules
However, the compiler utility files (DD statements SYSUTx) and COPY files (DD
statement SYSLIB) must be MVS data sets.
|
|
“Example: user-written JCL for compiling”
“Example: sample JCL for a procedural DLL application” on page 492
“Example: sample JCL for an object-oriented application” on page 418
RELATED REFERENCES
OS/390 MVS JCL Reference
Example: user-written JCL for compiling
This example shows a few possibilities for adapting the basic JCL.
//JOB1
JOB
(1)
//STEP1
EXEC PGM=IGYCRCTL,PARM='OBJECT'
(2)
//STEPLIB DD
DSNAME=IGY.V2R2M0.SIGYCOMP,DISP=SHR
//SYSUT1
DD
UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT2
DD
UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT3
DD
UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT4
DD
UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT5
DD
UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT6
DD
UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT7
DD
UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSPRINT DD
SYSOUT=A
//SYSLIN
DD
DSNAME=MYPROG,UNIT=SYSDA,
//
DISP=(MOD,PASS),SPACE=(TRK,(3,3))
//SYSIN
DD
*
(3)
000100 IDENTIFICATION DIVISION.
. . .
/*
(4)
(1)
JOB1 is the name of the job.
(2)
STEP1 is the name of the single job step in the job. The EXEC statement also
specifies that the generated object code be placed on disk or tape to be
used later as input to the link step.
(3)
The asterisk indicates that the input data set follows in the input stream.
|
214
Programming Guide
(4)
The delimiter statement /* separates data from subsequent control
statements in the input stream.
Compiling under TSO
|
|
|
|
|
|
Under TSO, you can use TSO commands, command lists (CLISTs), REXX execs, or
ISPF to compile your program using traditional MVS data sets. You can use TSO
commands or REXX execs to compile your program using HFS files. With each
method, you need to allocate the data sets and request the compilation.
1. Use the ALLOCATE command to allocate data sets.
For any compilation, allocate the work data sets (SYSUTn), and the SYSIN and
SYSPRINT data sets. If you specify certain compiler options, allocate the
following data sets:
v If you specified the OBJECT compiler option, allocate the SYSLIN data set to
produce an object module.
v If you specified the TERMINAL option, allocate the SYSTERM data set to get
compiler messages at your terminal.
v If you specified the LIB option and if you have used COPY or REPLACE
statements in your COBOL for OS/390 & VM program, allocate the SYSLIB
data set. This must be a traditional MVS data set, not an HFS path.
v If you specified the LIB option in your program, allocate SYSUT5. This utility
data set must be a traditional MVS data set, not an HFS path.
You can allocate data sets in any order. However, you must allocate all needed
data sets before you start to compile.
2. Use the CALL command to request compilation:
READY
CALL 'IGY.V2R2M0.SIGYCOMP(IGYCRCTL)'
|
|
You can specify the ALLOCATE and CALL commands on the TSO command line, or, if
you are not using HFS files, include them in a CLIST.
|
|
|
|
|
You can allocate HFS files for all the compiler data sets except the SYSUTx utility
data sets and the SYSLIB libraries. Your ALLOCATE statements have the following
form:
Allocate File(SYSIN) Path('/u/myu/myap/std/prog2.cbl')
Pathopts(ORDONLY) Filedata(TEXT)
“Example: ALLOCATE and CALL for compiling under TSO”
“Example: CLIST for compiling under TSO” on page 216
Example: ALLOCATE and CALL for compiling under TSO
The following example shows how to specify ALLOCATE and CALL commands when
you are compiling under TSO.
READY
ALLOCATE
READY
ALLOCATE
READY
ALLOCATE
READY
ALLOCATE
READY
ALLOCATE
READY
ALLOCATE
FILE(SYSUT1) CYLINDERS SPACE(1 1)
FILE(SYSUT2) CYLINDERS SPACE(1 1)
FILE(SYSUT3) CYLINDERS SPACE(1 1)
FILE(SYSUT4) CYLINDERS SPACE(1 1)
FILE(SYSUT5) CYLINDERS SPACE(1 1)
FILE(SYSUT6) CYLINDERS SPACE(1 1)
Chapter 13. Compiling under OS/390
215
READY
ALLOCATE FILE(SYSUT7) CYLINDERS SPACE(1 1)
READY
ALLOCATE FILE(SYSPRINT) SYSOUT
READY
ALLOCATE FILE(SYSTERM) DATASET(*)
READY
ALLOCATE FILE(SYSLIN) DATASET(PROG2.OBJ) NEW TRACKS SPACE(3,3)
READY
ALLOCATE FILE(SYSIN) DATASET(PROG2.COBOL) SHR
READY
CALL 'IGY.V2R2M0.SIGYCOMP(IGYCRCTL)' 'LIST,NOCOMPILE(S),OBJECT,FLAG(E,E),TERMINAL'
.
(COBOL listings and messages)
.
READY
FREE FILE(SYSUT1,SYSUT2,SYSUT3,SYSUT4,SYSUT5,SYSUT6,SYSUT7,SYSPRINT,SYSTERM,SYSIN,SYSLIN)
READY
Example: CLIST for compiling under TSO
In the following sample CLIST for compiling under TSO, the FREE commands are
not required. However, good programming practice dictates that you free your files
before you allocate them.
PROC 1 MEM
CONTROL LIST
FREE (SYSUT1)
FREE (SYSUT2)
FREE (SYSUT3)
FREE (SYSUT4)
FREE (SYSUT5)
FREE (SYSUT6)
FREE (SYSUT7)
FREE (SYSPRINT)
FREE (SYSIN)
FREE (SYSLIN)
ALLOC F(SYSPRINT) SYSOUT
ALLOC F(SYSIN) DA(COBOL.SOURCE(&MEM)) SHR REUSE
ALLOC F(SYSLIN) DA(COBOL.OBJECT(&MEM)) OLD REUSE
ALLOC F(SYSUT1) NEW SPACE(5,5) TRACKS UNIT(SYSDA)
ALLOC F(SYSUT2) NEW SPACE(5,5) TRACKS UNIT(SYSDA)
ALLOC F(SYSUT3) NEW SPACE(5,5) TRACKS UNIT(SYSDA)
ALLOC F(SYSUT4) NEW SPACE(5,5) TRACKS UNIT(SYSDA)
ALLOC F(SYSUT5) NEW SPACE(5,5) TRACKS UNIT(SYSDA)
ALLOC F(SYSUT6) NEW SPACE(5,5) TRACKS UNIT(SYSDA)
ALLOC F(SYSUT7) NEW SPACE(5,5) TRACKS UNIT(SYSDA)
CALL 'IGY.V2R2M0.SIGYCOMP(IGYCRCTL)'
Starting the compiler from an assembler program
An assembler program can start the COBOL for OS/390 & VM compiler by using
the ATTACH or the LINK macro instruction, by dynamic invocation. Using dynamic
invocation, you must supply the following information to the COBOL for OS/390
& VM compiler:
v Options to be specified for the compilation
v ddnames of the data sets to be used during processing by the COBOL for
OS/390 & VM compiler
Format
symbol
216
Programming Guide
{LINK|ATTACH} EP=IGYCRCTL,
PARAM=(optionlist[,ddnamelist]),VL=1
EP
Specifies the symbolic name of the COBOL for OS/390 & VM compiler.
The control program (from the library directory entry) determines the entry
point at which the program should begin running.
PARAM
Specifies, as a sublist, address parameters to be passed from the assembler
program to the COBOL for OS/390 & VM compiler. The first fullword in
the address parameter list contains the address of the COBOL optionlist.
The second fullword contains the address of the ddnamelist.
The third and fourth fullwords contain the addresses of null parameters, or
zero.
optionlist
Specifies the address of a variable-length list containing the COBOL
options specified for compilation. This address must be written although
no list is provided.
The optionlist 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 optionlist is free form,
with each field separated from the next by a comma. No blanks or zeros
should appear in the list. The compiler recognizes only the first 100
characters in the list.
ddnamelist
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, the ddnamelist can be omitted.
The ddnamelist 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 fewer than 8 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. You can omit names from the end by shortening
the list.
|
|
All SYSUTn data sets specified must be on direct-access storage devices
and have physical sequential organization. They must not reside in the
HFS.
The following table shows the sequence of the 8-byte entries in the
ddnamelist.
ddname 8-byte entry
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Name for which substituted
SYSLIN
Not applicable
Not applicable
SYSLIB
SYSIN
SYSPRINT
SYSPUNCH
SYSUT1
SYSUT2
SYSUT3
SYSUT4
SYSTERM
SYSUT5
SYSUT6
SYSUT7
Chapter 13. Compiling under OS/390
217
ddname 8-byte entry
16
17
18
VL
Name for which substituted
SYSADATA
SYSIDL
SYSDEBUG
Specifies that the sign bit is to be set to 1 in the last fullword of the
address parameter list.
When the COBOL for OS/390 & VM compiler completes processing, it puts a
return code in register 15.
Defining compiler input and output
You need to define several kinds of data sets that the compiler uses to do its work.
The compiler takes input data sets and libraries and produces various types of
output, including object code, listings, and messages. The compiler also uses utility
data sets during compilation.
RELATED TASKS
“Defining the source code data set (SYSIN)” on page 220
“Specifying source libraries (SYSLIB)” on page 220
“Defining the output data set (SYSPRINT)” on page 221
“Directing compiler messages to your terminal (SYSTERM)” on page 221
“Creating object code (SYSLIN or SYSPUNCH)” on page 221
“Creating an associated data file (SYSADATA)” on page 222
“Defining the output IDL data set (SYSIDL)” on page 222
“Defining the debug data set (SYSDEBUG)” on page 222
RELATED REFERENCES
“Data sets used by the compiler under OS/390”
Data sets used by the compiler under OS/390
The following table lists the function, device requirements, and allowable device
classes for each data set that the compiler uses.
|
|
|
|
Allowable
Device
device
requirements classes
Reside
on
HFS?
Card reader;
intermediate
storage
Any
Yes
SYSDA
No
Type
ddname
Function
Required?
Input
SYSIN
Reads source
program
Yes
SYSLIB or
other copy
libraries1
Reads user source
libraries (PDSs)
If program has COPY or BASIS Direct access
statements (LIB is required)
SOMENV
Reads SOM profile
when OO COBOL
programs are
compiled
If TYPECHK or IDLGEN is in
effect
|
218
1
Programming Guide
|
|
|
Type
ddname
Function
Required?
Allowable
Device
device
requirements classes
|
Utility
SYSUT1,
SYSUT2,
SYSUT3,
SYSUT4,
SYSUT62
Work data set used
by compiler during
compilation
Yes
Direct access
SYSDA
No
|
SYSUT52
Work data set used
by compiler during
compilation
If program has COPY,
Direct access
REPLACE, or BASIS statements
(LIB is required )
SYSDA
No
|
SYSUT72
Work data set used
Yes
by compiler to create
listing
Direct access
SYSDA
No
SYSPRINT1
Writes storage map,
listings, and
messages
Yes
Printer;
intermediate
storage
SYSSQ, SYSDA, Yes
standard
output class
A
|
SYSTERM
Writes progress and
diagnostic messages
If TERM is in effect
Output
device; TSO
terminal
Yes
|
SYSPUNCH
Creates object code
If DECK is in effect
Card punch;
direct access
SYSSQ, SYSDA Yes
|
SYSLIN
Creates object
If OBJECT is in effect
module data set as
output from compiler
and input to linkage
editor
Direct access
SYSSQ, SYSDA Yes
|
SYSADATA
Writes associated
data file records
|
SYSIDL
Creates SOM IDL for If IDLGEN is in effect
class definitions
|
SYSUDUMP,
Writes dump
SYSABEND, or
SYSMDUMP
If DUMP is in effect (should be Direct access
rarely used)
SYSDA
Yes
|
|
|
|
|
SYSDEBUG
If TEST(...,SYM,SEPARATE) is Direct access
in effect
SYSDA
Yes
|
Output
Writes symbolic
debug information
tables to a data set
separate from the
object module
If ADATA or EVENTS is in effect Output
device
Reside
on
HFS?
Yes
Direct access
Yes
1. You can use the EXIT option to provide user exits from these data sets.
2. These data sets must be single volume.
RELATED REFERENCES
“Logical record length and block size”
“EXIT” on page 272
Logical record length and block size
|
For compiler data sets other than the work data sets (SYSUTn) and HFS files, you
can set the block size using the BLKSIZE subparameter of the DCB parameter. The
value must be permissible for the device on which the data set resides. The values
you set depend on whether the data sets are fixed length or variable length.
Chapter 13. Compiling under OS/390
219
For fixed-length records (RECFM=F or RECFM=FB), LRECL is the logical record length,
and BLKSIZE equals LRECL multiplied by n, where n is equal to the blocking factor.
The following table shows the defined values for the fixed-length data sets. In
general, you should not change these values, but you can change the value for:
v SYSIDL, SYSDEBUG: You can specify any LRECL in the listed range, with 255
recommended.
v SYSPRINT, SYSDEBUG: You can specify BLKSIZE=0, which results in a
system-determined block size.
|
|
Data set
RECFM
LRECL (bytes)
BLKSIZE1
SYSIN
F or FB
80
80 x n
SYSLIN
F or FB
80
80 x n
SYSPUNCH
F or FB
80
80 x n
SYSLIB or other copy libraries
F or FB
80
80 x n
SYSPRINT
F or FB
133
133 x n
SYSTERM
F or FB
80
80 x n
F or FB
80 to 255
LRECL x n
F or FB
80 to 1024
LRECL x n
2
SYSIDL
2
|
SYSDEBUG
1. n = blocking factor
2. If you specify BLKSIZE=0, the system will determine the block size.
|
For variable-length records (RECFM=V), LRECL is the logical record length, and
BLKSIZE equals LRECL plus 4.
Data set
RECFM
LRECL
(bytes)
BLKSIZE (bytes)
minimum acceptable value
SYSADATA
VB
1020
1024
Defining the source code data set (SYSIN)
Define the data set that contains your source code with the SYSIN DD statement, as
in:
//SYSIN
//
DD
DSNAME=dsname,UNIT=SYSSQ,
VOLUME=(subparms),DISP=SHR
You can place your source code or BASIS statement directly in the input stream. If
you do, use this SYSIN DD statement:
//SYSIN
DD
*
When you use the DD * convention, the source code or BASIS statement must
follow the statement. If another job step follows the compilation, the EXEC
statement for that step follows the /* statement or the last source statement.
Specifying source libraries (SYSLIB)
Add the SYSLIB DD statements if your program contains COPY or BASIS statements.
These DD statements define the libraries (partitioned data sets) that contain the data
requested by COPY statements (in the source code) or by a BASIS statement in the
input stream.
//SYSLIB
220
Programming Guide
DD
DSNAME=copylibname,DISP=SHR
Concatenate multiple DD statements if you have multiple copy or basis libraries.
//SYSLIB
//
|
|
DD DSNAME=PROJECT.USERLIB,DISP=SHR
DD DSNAME=SYSTEM.COPYX,DISP=SHR
Libraries are on direct-access storage devices. They cannot be in the hierarchical
file system when you compile using JCL or under TSO.
You do not need the SYSLIB DD statement if the NOLIB option is in effect.
Defining the output data set (SYSPRINT)
You can use SYSPRINT to produce a listing, as in:
//SYSPRINT DD
SYSOUT=A
You can direct the output to a SYSOUT data set, a printer, a direct-access storage
device, or a magnetic-tape device. The listing includes the results of the default or
requested options of the PARM parameter (that is, diagnostic messages, the object
code listing).
|
|
|
Specify the following for the data set that you define:
v The name of a sequential data set, the name of a PDS or PDSE member, or an
HFS path.
|
|
|
|
v A data set LRECL of 133.
v A data set RECFM of F or B.
v A block size, using the BLKSIZE subparameter of the DCB parameter, or let the
system set the system-determined default block size.
Directing compiler messages to your terminal (SYSTERM)
If you are compiling under TSO, you can define the SYSTERM data set to send
compiler messages to your terminal, as in:
ALLOC F(SYSTERM) DA(*)
|
You can define SYSTERM in various ways, including as a SYSOUT data set, a data
set on disk, a file in the HFS, or to another print class.
Creating object code (SYSLIN or SYSPUNCH)
|
|
When using the OBJECT compiler option, you can store the object code on disk as a
traditional MVS data set or an HFS file or on tape. The compiler uses the file that
you define in the SYSLIN or SYSPUNCH DD statement to store the object code.
//SYSLIN
//
DD
DSNAME=dsname,UNIT=SYSDA,
SPACE=(subparms),DISP=(MOD,PASS)
Use the DISP parameter of the SYSLIN DD statement to indicate whether the object
code data set is to be:
v Passed to the linkage editor
v Cataloged
v Kept
v Added to an existing cataloged library
In the example above, the data is created and passed to another job step, the
linkage editor job step.
Your installation might use the DECK option and the SYSPUNCH DD statement.
Chapter 13. Compiling under OS/390
221
//SYSPUNCH DD
SYSOUT=B
B is the standard output class for punch data sets.
You do not need the SYSLIN DD statement if the NOOBJECT option is in effect. You do
not need the SYSPUNCH DD statement if the NODECK option is in effect.
RELATED REFERENCES
“OBJECT” on page 284
“DECK” on page 269
Creating an associated data file (SYSADATA)
Define a SYSADATA data set if you use either the ADATA compiler option or the
EVENTS compiler option.
//SYSADATA DD
DSNAME=dsname,UNIT=SYSDA
The file defined in the SYSADATA DD statement will be a sequential file containing
specific record types that have information about the program collected during
compilation. The file can be a traditional MVS data set or an HFS file.
|
RELATED REFERENCES
“ADATA” on page 261
Defining the output IDL data set (SYSIDL)
Add the SYSIDL DD statement if you are using the IDLGEN compiler option to
request a SOM Interface Definition Language (IDL) file for object-oriented COBOL
class definitions.
//SYSIDL
DD
DSNAME=pdsname(member),DISP=(MOD,PASS)
The file can be a traditional MVS data set as shown, or an HFS file.
|
Defining the debug data set (SYSDEBUG)
|
|
|
|
When you compile from JCL or from TSO and specify the
TEST(. . .,SYM,SEPARATE) compiler option, the symbolic debug information tables
are written to the data set that you specify on the SYSDEBUG DD statement, as in:
|
|
|
|
|
Specify the following for the data set that you define:
|
|
|
v A data set RECFM of F or FB.
v A block size, using the BLKSIZE subparameter of the DCB parameter, or let the
system set the system-determined default block size.
//SYSDEBUG DD
DSNAME=dsname,UNIT=SYSDA
v The name of a sequential data set, the name of a PDS or PDSE member, or an
HFS path.
v A data set LRECL greater than or equal to 80, and less than or equal to 1024. The
default LRECL for SYSDEBUG is 1024.
RELATED REFERENCES
“TEST” on page 295
222
Programming Guide
Specifying compiler options under OS/390
The compiler is installed and set up with default compiler options. While installing
the compiler, the system programmers for a site can fix compiler option settings to,
for example, ensure better performance or maintain certain standards. You cannot
override any compiler options that your site has set as fixed. For options that are
not fixed, you can override the default settings by specifying compiler options in
either of these ways:
v Code them on the PROCESS or CBL statement in your COBOL source.
v Include them when you start the compiler, either on the PARM parameter on the
EXEC statement in your JCL or on the command line under TSO.
The compiler recognizes the options in the following order of precedence from
highest to lowest:
|
1. Installation defaults that are fixed by your site
2. Values of the BUFSIZE, LIB, OUTDD, SIZE, and SQL compiler options in effect for
the first program in a batch
3. Options specified on PROCESS (or CBL) statements, preceding the Identification
Division
4. Options specified on the compiler invocation (JCL PARM parameter or the TSO
CALL command)
5. Installation defaults that are not fixed
This order of precedence also determines which options are in effect when
conflicting or mutually exclusive options are specified.
Most of the options come in pairs; you select one or the other. For example, the
option pair for a cross-reference listing is XREF|NOXREF. If you want a
cross-reference listing, specify XREF. If you do not want one, specify NOXREF.
Some options have subparameters. For example, if you want 44 lines per page on
your listings, specify LINECOUNT(44).
“Example: specifying compiler options using JCL” on page 224
“Example: specifying compiler options under TSO” on page 224
RELATED TASKS
“Specifying compiler options with the PROCESS (CBL) statement”
“Specifying compiler options in a batch compilation” on page 227
RELATED REFERENCES
“Conflicting compiler options” on page 259
“Chapter 16. Compiler options” on page 257
Specifying compiler options with the PROCESS (CBL)
statement
You can code compiler options on the PROCESS statement in your COBOL source
.CBL programs.
Chapter 13. Compiling under OS/390
223
Place the PROCESS statement before the IDENTIFICATION DIVISION header and before
any comment lines or compiler-directing statements.
You can start PROCESS in columns 1 through 66. A sequence field is allowed in
columns 1 through 6. When used with a sequence field, PROCESS can start in
columns 8 through 66. If used, the sequence field must contain six characters, and
the first character must be numeric.
You can use CBL as a synonym for PROCESS. CBL can start in columns 1 through 70.
When used with a sequence field, CBL can start in columns 8 through 70.
Use one or more blanks to separate PROCESS from the first option in options-list.
Separate options with a comma or a blank. Do not insert spaces between
individual options and their suboptions.
You can use more than one PROCESS statement. If multiple PROCESS statements are
used, they must follow one another with no intervening statement of any other
type. You cannot continue options across multiple PROCESS statements.
Your programming organization can inhibit the use of PROCESS statements with the
default options module of the COBOL compiler. When PROCESS statements are
found in a COBOL program where not allowed by the organization, the COBOL
compiler generates error diagnostics.
Example: specifying compiler options using JCL
The following example shows how to specify compiler options under OS/390
using JCL:
. . .
//STEP1
//
EXEC PGM=IGYCRCTL,
PARM='LIST,NOCOMPILE(S),OBJECT,FLAG(E,E)'
Example: specifying compiler options under TSO
The following example shows how to specify compiler options under TSO:
. . .
READY
CALL 'SYS1.LINKLIB(IGYCRCTL)' 'LIST,NOCOMPILE(S),OBJECT,FLAG(E,E)'
Compiler options and compiler output under OS/390
When the compiler finishes processing your source program, it will have produced
one or more of the following, depending on the compiler options you selected:
Compiler option
Compiler output
Type of output
ADATA or EVENTS
Information about the program being compiled
Associated data file
DLL
Object module that is enabled for DLL support
Object
DUMP
System dump, if compilation ended with abnormal
termination (requires SYSUDUMP, SYSABEND, or SYSMDUMP
DD statement); should be rarely used
Listing
EXPORTALL
Exported symbols for a DLL
Object
FLAG
List of errors that the compiler found in your program
Listing
IDLGEN
Interface Definition Language (IDL) file for your
object-oriented COBOL class definition
Object
224
Programming Guide
|
|
Compiler option
Compiler output
Type of output
LIST
Listing of object code in machine and assembler
language
Listing
MAP
Map of the data items in your program
Listing
NUMBER
User-supplied line numbers shown in listing
Listing
OBJECT or DECK with COMPILE Your object code
Object
OFFSET
Map of the relative addresses in your object code
Listing
OPTIMIZE
Optimized object code if OBJECT in effect
Object
RENT
Reentrant object code if OBJECT in effect
Object
SOURCE
Listing of your source program
Listing
SQL
SQL statements and host variable information for DB2
bind process
Database request module
SSRANGE
Extra code for checking references within tables
In object
TERMINAL
Progress and diagnostic messages sent to terminal
Terminal
TEST(hook location
suboption)
Compiled-in hooks for Debug Tool
Extra code in object
TEST(SYM,NOSEP)
Information tables for Debug Tool and for formatted
dumps
Object
TEST(SYM,SEP)
Information tables for Debug Tool and for formatted
dumps
Debug information side file
VBREF
Cross-reference listing of verbs in your source program
Listing
XREF
Sorted cross-reference listing of names of procedures,
programs, and data
Listing
Listing output from compilation will be in the data set defined by SYSPRINT; object
output will be in SYSLIN or SYSPUNCH. Progress and diagnostic messages can be
directed to the SYSTERM data set as well as included in the SYSPRINT data set.
Associated data file records will be in the data set defined by SYSADATA. The
database request module (DBRM) will be the data set defined in DBRMLIB. The
debug information side file will be the data set defined in SYSDEBUG.
Save the listings you produced during compilation. You can use them during the
testing of your work if you need to debug or tune.
After compilation, your next step will be to fix any errors that the compiler found
in your program.
If no errors are detected, you can go to the next step in the process: link-editing, or
binding, your program. (If you used compiler options to suppress object code
generation, you must recompile to obtain it.)
RELATED REFERENCES
“Messages and listings for compiler-detected errors” on page 231
“Chapter 16. Compiler options” on page 257
Chapter 13. Compiling under OS/390
225
Compiling multiple programs (batch compilation)
You can compile a sequence of separate COBOL programs with a single invocation
of the compiler. You can link the object program produced from this compilation
into one load module or separate load modules, controlled by the NAME compiler
option.
You can also use a single invocation of the compiler to compile a sequence of class
definitions or a sequence that mixes class definitions and program definitions.
When you compile several programs as part of a batch job, you need to:
v Determine whether you want to create one or more load modules.
v Terminate each program in the sequence.
v Specify compiler options, with an awareness of the effect of compiler options
specified in programs within the batch job.
To create separate load modules, precede each set of modules with the NAME option.
When the compiler encounters a NAME compiler option, the first program in the
sequence and all subsequent programs are link-edited into a single load module,
until the next NAME compiler option is encountered. Then, each successive program
that is compiled with the NAME option is included in a separate load module.
Use the END PROGRAM header to terminate each program in the sequence (except the
last program in the batch for which the END PROGRAM header is optional).
Alternatively, you can precede each program in the sequence with a CBL or PROCESS
statement. (If the CMPR2 compiler option is in effect, separate each program with
the CBL form of the PROCESS or CBL statement.)
If you omit the END PROGRAM header from a program (other than the last program
in a sequence of separate programs), the next program in the sequence will be
nested in the preceding program. An error can occur in either of the following
situations:
v A PROCESS statement is in a program that is now nested.
v A CBL statement is not coded entirely in the sequence number area (columns 1
through 6).
If a CBL statement is coded entirely in the sequence number area (columns 1
through 6), no error message is issued for the CBL statement because it is
considered a label for the source statement line.
“Example: batch compilation”
RELATED TASKS
“Specifying compiler options in a batch compilation” on page 227
RELATED REFERENCES
“NAME” on page 282
“CMPR2” on page 264
Example: batch compilation
The following example shows a batch compilation for three programs (PROG1,
PROG2, and PROG3) creating two load modules, using one invocation of the
IGYWCL cataloged procedure:
v PROG1 and PROG2 are link-edited together to form one load module with a
name of PROG2. The entry point of this load module defaults to the first
program in the load module, PROG1.
226
Programming Guide
v PROG3 is link-edited by itself into a load module with the name PROG3.
Because it is the only program in the load module, the entry point is also
PROG3.
//jobname JOB acctno,name,MSGLEVEL=1
//stepname EXEC IGYWCL
//COBOL.SYSIN DD *
010100 IDENTIFICATION DIVISION.
010200 PROGRAM-ID PROG1.
. . .
019000 END PROGRAM PROG1.
020100 IDENTIFICATION DIVISION.
020200 PROGRAM-ID PROG2.
. . .
029000 END PROGRAM PROG2.
CBL NAME
030100 IDENTIFICATION DIVISION.
030200 PROGRAM-ID PROG3.
. . .
039000 END PROGRAM PROG3.
/*
//LKED.SYSLMOD DD DSN=&&GOSET
/*
//P2
EXEC PGM=PROG2
//STEPLIB DD
DSN=&&GOSET,DISP=(SHR,PASS)
. . .
/*
//P3
EXEC PGM=PROG3
//STEPLIB DD
DSN=&&GOSET,DISP=(SHR,PASS)
. . .
/*
//
(1)
(2)
(3)
(2)
(3)
(1)
The data set name for the LKED step SYSLMOD is changed to the temporary
name &&GOSET, without any member name.
(2)
The temporary data set &&GOSET is used as the STEPLIB for steps P2 and P3
to run the compiled programs. If the library does not reside in shared
storage, the library data set CEE.V2R2M0.SCEERUN must be added as a DD
statement for STEPLIB.
(3)
Other DD statements and input that are required to run PROG1 and PROG2
must be added.
(4)
Other DD statements and input that are required to run PROG3 must be
added.
RELATED REFERENCES
Cataloged procedures for link-editing COBOL programs (Language Environment
Programming Guide)
Specifying compiler options in a batch compilation
You can specify compiler options for each program in the batch sequence in either
of the usual ways:
v CBL or PROCESS statements preceding a program
v Invocation of the compiler
If a CBL or PROCESS statement is specified in the current program, the compiler
resolves the CBL or PROCESS statements together with the options in effect before
the first program. If the current program does not contain CBL or PROCESS
statements, the compiler uses the settings of options in effect for the previous
program.
Chapter 13. Compiling under OS/390
227
You should be aware of the effect of certain compiler options on the precedence of
compiler option settings for each program in the sequence:
1. Installation defaults that are fixed at your site
2. Values of the BUFSIZE, LIB, OUTDD, SIZE, and SQL compiler options in effect for
the first program in the batch
3. Options on CBL or PROCESS statements, if any, for the current program
4. Options specified on the compiler invocation (JCL PARM or TSO CALL)
5. Installation defaults that are not fixed
|
If any program in the sequence requires the BUF, LIB, OUTDD, SIZE, or SQL option,
that option must be in effect for the first program in the batch sequence. (When
processing BASIS, COPY, or REPLACE statements, the compiler handles all programs
in the batch as a single input file.)
|
If you specify the LIB option for the batch, you cannot change the NUMBER and
SEQUENCE options during the batch compilation. The compiler treats all programs in
the batch as a single input file during NUMBER and SEQUENCE processing under the
LIB option; therefore, the sequence numbers of the entire input file must be in
ascending order.
If the compiler diagnoses the LANGUAGE option on the CBL or PROCESS statement as
an error, the language selection reverts to what was in effect before the compiler
encountered the first CBL or PROCESS statement. The language in effect during a
batch compilation conforms to the rules of processing CBL or PROCESS statements in
that environment.
“Example: precedence of options in a batch compilation”
“Example: LANGUAGE option in a batch compilation” on page 229
Example: precedence of options in a batch compilation
The following listing shows the compiler options hierarchy for a batch compile.
PP 5648-A25 IBM COBOL for OS/390 & VM 2.2.0
Date 03/30/2000 Time 10:34:14 Page
1
INVOCATION PARAMETERS:
NOTERM
PROCESS(CBL) statements:
CBL CMPR2,FLAG(I,I)
Options in effect:
All options are installation defaults unless otherwise noted:
NOADATA
ADV
QUOTE
NOAWO
BUFSIZE(4096)
CMPR2
Process option PROGRAM 1
.
.
FLAG(I,I)
Process option PROGRAM 1
.
.
NOTERM
INVOCATION option
.
.
End of compilation for program 1
.
.
PP 5648-A25 IBM COBOL for OS/390 & VM 2.2.0
Date 03/30/2000 Time 10:34:14 Page
PROCESS(CBL) statements:
228
Programming Guide
4
CBL APOST
Options in effect:
NOADATA
ADV
APOST
NOAWO
BUFSIZE(4096)
NOCMPR2
.
.
FLAG(I)
.
.
NOTERM
.
.
End of compilation for
Process option in effect for PROGRAM 2
Returns to installation option for PROGRAM 2, and subsequent prog
Returns to installation option
INVOCATION option remains in effect
program 2
Example: LANGUAGE option in a batch compilation
The following example shows the behavior of the LANGUAGE compiler option in a
batch environment. The default installation option is ENGLISH (abbreviated to EN),
and the invocation option is XX (a nonexistent language).
Source
Language in
effect
-----------------------------------------------------------------------CBL
LANG(JP),FLAG(I,I),APOST,SIZE(MAX)
|EN| Installation default -- EN
IDENTIFICATION DIVISION.
|JP| Invocation
-- XX
PROGRAM-ID. COMPILE1.
|: |
. . .
|: |
END PROGRAM COMPILE1.
|: |
CBL
LANGUAGE(YY)
|EN| CBL resets language
CBL
SIZE(2048K),LANGUAGE(JP),LANG(!!)
|: | to EN. LANGUAGE(YY)
IDENTIFICATION DIVISION.
|JP| is ignored because it
PROGRAM-ID. COMPILE2.
|: | is superseded by (JP).
. . .
|: | (!!) is not alphaEND PROGRAM COMPILE2.
|: | numeric and is
IDENTIFICATION DIVISION.
|: | discarded.
PROGRAM-ID. COMPILE3.
|: |
. . .
|: |
END PROGRAM COMPILE3.
|: |
CBL
LANGUAGE(JP),LANGUAGE(YY)
|EN| CBL resets language
. . .
|: | to EN. LANGUAGE(YY)
. . .
|: | supersedes (JP) but
. . .
|: | is nonexistent.
For the program COMPILE1, the default language English (EN) is in effect when
the compiler scans the invocation options. A diagnostic message is issued in
mixed-case English because XX is a nonexistent language identifier. The default EN
remains in effect when the compiler scans the CBL statement. The unrecognized
option APOST in the CBL statement is diagnosed in mixed-case English because the
CBL statement has not completed processing and EN was the last valid language
option. After the compiler processes the CBL options, the language in effect
becomes Japanese (JP).
In the program COMPILE2, the compiler diagnoses CBL statement errors in
mixed-case English because English is the language in effect before the first
program is used. If more than one LANGUAGE option is specified, only the last valid
language specified is used. In this example, the last valid language is Japanese (JP),
and therefore Japanese becomes the language in effect when the compiler finishes
Chapter 13. Compiling under OS/390
229
processing the CBL options. If you want diagnostics in Japanese for the options in
the CBL or PROCESS statements, the language in effect before COMPILE1 must be
Japanese.
The program COMPILE3 has no CBL statement, and so it inherits the language in
effect, Japanese (JP), from the previous compilation.
After compiling COMPILE3, the compiler resets the language in effect to English
(EN) because of the CBL statement. The language option in the CBL statement
resolves the last-specified two-character alphanumeric language identifier, which is
YY. Because YY is nonexistent, the language in effect remains English.
Correcting errors in your source program
Messages about source code errors indicate where the error happened (LINEID),
and the text of the message tells you what the problem is. With this information,
you can correct the source program and recompile.
Although you should try to correct errors, it is not necessary to fix all of them. A
warning-level or informational-level message can be left in a program without
much risk, and you might decide that the recoding and compilation needed to
remove the error are not worth the effort. Severe-level and error-level errors,
however, indicate probable program failure and should be corrected.
Unrecoverable-level errors are in a class by themselves. In contrast with the four
lower levels of errors, a U-level error might not result from a mistake in your
source program. It could come from a flaw in the compiler itself or in the
operating system. In any case, the problem must be resolved, because the compiler
is forced to end early and does not produce complete object code and listing. If the
message is received for a program with many S-level syntax errors, correct those
errors and compile the program again. You can also resolve job set-up cases
yourself (problems such as missing data set definitions or insufficient storage for
compiler processing) by making changes to the compile job. If your compile job
set-up is correct and you have corrected the S-level syntax errors, you need to call
IBM to investigate other U-level errors.
After correcting the errors in your source program, recompile the program. If this
second compilation is successful, go on to the link-editing step. If the compiler still
finds problems, repeat the above procedure until only informational messages are
returned.
RELATED TASKS
“Generating a list of compiler error messages”
RELATED REFERENCES
“Messages and listings for compiler-detected errors” on page 231
Generating a list of compiler error messages
You can generate a complete listing of compiler diagnostic messages, with their
explanations, by compiling a program with a program name of ERRMSG specified in
the PROGRAM-ID paragraph, like this:
Identification Division.
Program-ID. ErrMsg.
You can omit the rest of the program.
230
Programming Guide
Messages and listings for compiler-detected errors
As the compiler processes your source program, it checks for COBOL language
errors that you might have made. For each error found, the compiler issues a
message. These messages are collated in the compiler listing (subject to the FLAG
option).
Each message in the listing gives the following information:
v Nature of the error
v Compiler phase that detected the error
v Severity level of the error
Wherever possible, the message provides specific instructions for correcting the
error.
The messages for errors found during processing of compiler options, CBL and
PROCESS statements, or BASIS, COPY, and REPLACE statements are displayed near the
top of your listing.
The messages for compilation errors found in your program (ordered by line
number) are displayed near the end of the listing for each program.
A summary of all errors found during compilation is displayed near the bottom of
your listing.
RELATED TASKS
“Correcting errors in your source program” on page 230
“Generating a list of compiler error messages” on page 230
RELATED REFERENCES
“Format of compiler error messages”
“Severity codes for compiler error messages” on page 232
“FLAG” on page 274
Format of compiler error messages
Each message issued by the compiler has the following form:
nnnnnn IGYppxxxx-l message-text
nnnnnn
The number of the source statement of the last line the compiler was
processing. Source statement numbers are listed on the source printout of
your program. If you specified the NUMBER option at compile time, these are
your original source program numbers. If you specified NONUMBER, the
numbers are those generated by the compiler.
IGY
The prefix that identifies this message as coming from the COBOL
compiler.
pp
Two characters that identify which phase of the compiler discovered the
error. As an application programmer, you can ignore this information. If
you are diagnosing a suspected compiler error, contact IBM for support.
xxxx
A four-digit number that identifies the error message.
l
A character that indicates the severity level of the error: I, W, E, S, or U.
message-text
The message text itself which, in the case of an error message, is a short
explanation of the condition that caused the error.
Chapter 13. Compiling under OS/390
231
Tip: If you used the FLAG option to suppress messages, there might be additional
errors in your program.
RELATED REFERENCES
“Severity codes for compiler error messages”
“FLAG” on page 274
Severity codes for compiler error messages
Errors the compiler can detect fall into the following five categories of severity:
Level of message
Purpose
Informational (I)
(return code=0)
To inform you. No action is required and the program
executes correctly.
Warning (W)
(return code=4)
To indicate a possible error. The program probably executes
correctly as written.
Error (E)
(return code=8)
To indicate a condition that is definitely an error. The
compiler attempted to correct the error, but the results of
program execution might not be what you expect. You should
correct the error.
Severe (S)
(return code=12)
To indicate a condition that is a serious error. The compiler
was unable to correct the error. The program does not execute
correctly, and execution should not be attempted. Object code
might not be created.
Unrecoverable (U)
(return code=16)
To indicate an error condition of such magnitude that the
compilation was terminated.
In the following example, the part of the statement that caused the message to be
issued is enclosed in quotes.
232
Programming Guide
Line
ID
Message code
Message text
2
IGYDS0009-E
“PROGRAM” should not begin in area “A.” It was processed as if
found in area “B.”
2
IGYDS1089-S
“PROGRAM” was invalid. Scanning was resumed at the next area
“A” item, level-number, or the start of the next clause.
2
IGYDS0017-E
“ID” should begin in area “A.” It was processed as if found in
area “A.”
2
IGYDS1003-E
A “PROGRAM-ID” paragraph was not found. Program name
“CBLPGM01” was assumed.
2
IGYSC1082-E
A period was required. A period was assumed before “ID.”
2
IGYDS1102-E
Expected “DIVISION,” but found “ALONGPRO.” “DIVISION”
was assumed before “ALONGPRO.”
2
IGYDS1082-E
A period was required. A period was assumed before
“ALONGPRO.”
2
IGYDS1089-S
“ALONGPRO” was not valid. Scanning was resumed at the next
area “A” item, level-number, or the start of the next clause.
2
IGYDS1003-E
A “PROGRAM-ID” paragraph was not found. Program name
“CBLPGM02” was assumed.
3
IGYPS0017-E
“PROCEDURE” should begin in area “A.” It was processed as if
found in area “A.”
Line
ID
Message code
Message text
34
IGYSC0137-E
Program-name “ALONGPRO” did not match the name of any
open program. The “END PROGRAM” statement was assumed to
have ended program “CBLPGM02.”
34
IGYSC0136-E
Program “CBLPGM01” required an “END PROGRAM” statement
at this point in the program. An “END PROGRAM” statement
was assumed.
Chapter 13. Compiling under OS/390
233
234
Programming Guide
Chapter 14. Compiling under OS/390 UNIX
|
|
|
|
|
You can compile COBOL for OS/390 & VM programs under OS/390 UNIX using
the cob2 command. Under OS/390 UNIX, you can compile any COBOL source
program that you compile under OS/390. The object code generated under OS/390
UNIX by the COBOL compiler can run under OS/390 or CMS, with certain
run-time restrictions.
|
|
|
As part of the compilation step, you need to define the files needed for the
compilation and specify any compiler options necessary for your program and for
the output that you want.
|
|
|
|
|
The main job of the compiler is to translate your COBOL program into language
that the computer can process (object code). The compiler also lists errors in your
source statements and provides supplementary information to help you debug and
tune your program. Use compiler-directing statements and compiler options to
control your compilation.
RELATED TASKS
“Setting environment variables under OS/390 UNIX”
“Specifying compiler options under OS/390 UNIX” on page 236
“Compiling and linking with the cob2 command” on page 237
“Compiling using scripts” on page 241
RELATED REFERENCES
“Run-time restrictions under CMS” on page 369
“Data sets used by the compiler under OS/390” on page 218
“Compiler options and compiler output under OS/390” on page 224
Setting environment variables under OS/390 UNIX
|
|
|
|
|
|
An environment variable is a name associated with a string of characters. You use
environment variables to set values that programs need, including the compiler. Set
the environment variables for the compiler by using the export shell command.
For example, to set the SYSLIB variable, issue the export command from the shell
or from a script file:
|
|
|
|
|
The value that you assign to an environment variable can include other
environment variables or the variable itself. The values of these variables apply
only when you compile from the shell where you issue the export command. If
you do not set an environment variable, either a default value is applied or the
variable is not defined. The environment variable names must be uppercase.
|
The environment variables that you can set for use by the compiler are as follows:
|
|
|
|
|
|
|
COBOPT
Specify compiler options separated by blanks or commas. Separate
suboptions with commas. Blanks at the beginning or the end of the
variable value are ignored. Delimit the list of options with quotation marks
if it contains blanks or characters significant to the OS/390 UNIX shell. For
example:
export SYSLIB=/u/mystuff/copybooks
export COBOPT=“TRUNC(OPT) XREF”
© Copyright IBM Corp. 1991, 2000
235
SYSLIB
|
|
|
|
|
|
|
Specify paths to directories to be used in searching for COBOL copy books
when you do not specify an explicit library name on the COPY statement.
Separate multiple paths with a colon. The paths are evaluated in order,
from the first path to the last in the export command. If you set the
variable with multiple files of the same name, the first located copy of the
file is used.
|
|
For COPY statements where you have not coded an explicit library name,
the compiler searches for your copy book in this order:
|
|
|
1. In the current directory
2. In the paths you specify with the -I cob2 option
3. In the paths you specify in the SYSLIB environment variable
|
|
|
|
|
|
library-name
Specify the directory path from which to copy when you specify an explicit
library-name on the COPY statement. The environment variable name is
identical to the library-name in your program. You must set an environment
variable for each library; an error will occur otherwise. The environment
variable name library-name must be uppercase.
|
|
|
|
text-name
Specify the name of the file from which to copy text. The environment
variable name is identical to the text-name in your program. The
environment variable name text-name must be uppercase.
RELATED TASKS
“Specifying compiler options under OS/390 UNIX”
“Compiling and linking with the cob2 command” on page 237
RELATED REFERENCES
“Compiler-directing statements” on page 304
“Chapter 16. Compiler options” on page 257
COPY statement (IBM COBOL Language Reference)
Specifying compiler options under OS/390 UNIX
The compiler is installed and set up with default compiler options. While installing
the compiler, the system programmers for a site can fix compiler option settings to,
for example, ensure better performance or maintain certain standards. You cannot
override any compiler options that your site has set as fixed. For options that are
not fixed, you can override the default settings by specifying compiler options in
any of three ways:
1. Code them on the PROCESS or CBL statement in your COBOL source.
2. Specify the -q option of the cob2 command.
|
|
|
|
|
|
|
|
|
3. Set the COBOPT environment variable.
|
The compiler recognizes the options in the above order of precedence.
|
|
|
|
|
|
|
The order of precedence also determines which options are in effect when
conflicting or mutually exclusive options are specified. When you compile using
the cob2 command, compiler options are recognized in the following order of
precedence from highest to lowest:
1. Installation defaults fixed as nonoverridable
2. The values of BUFSIZE, LIB, SQL, OUTDD, and SIZE options in effect for the first
program in a batch compilation
236
Programming Guide
|
|
|
|
|
3. The values that you specify on PROCESS or CBL statements within your COBOL
source programs
4. The values that you specify in the cob2 command’s -q option string
5. The values that you specify in the COBOPT environment variable
6. Installation defaults that are not fixed
RELATED TASKS
“Specifying compiler options with the PROCESS (CBL) statement” on page 223
“Setting environment variables under OS/390 UNIX” on page 235
“Compiling and linking with the cob2 command”
RELATED REFERENCES
“Conflicting compiler options” on page 259
“Chapter 16. Compiler options” on page 257
Compiling and linking with the cob2 command
|
|
|
|
Use the cob2 command to compile and link your COBOL programs from the
OS/390 UNIX shell. You can specify the options and input file names in any order,
using spaces to separate options and names. Any options that you specify apply to
all files on the command line.
|
To compile multiple files (batch compilation), specify multiple source file names.
|
|
|
When you compile COBOL programs for OS/390 UNIX, the RENT option is
required. The cob2 command automatically includes the COBOL compiler options
RENT and TERM.
|
|
|
|
|
|
The cob2 command invokes the COBOL compiler that is found through the
standard MVS search order. If the COBOL compiler is not installed in the linklist
or if more than one level of IBM COBOL compiler is installed on your system, you
can specify the compiler PDS that you want to use in the STEPLIB environment
variable. For example:
|
|
|
The cob2 command implicitly uses the OS/390 UNIX shell command c89 for the
link step. c89 is the shell interface to the linkage editor (the DFSMS program
management binder).
export STEPLIB=IGY.V2R2M0.SIGYCOMP
Defining input and output
|
The default location for compiler input and output is the current directory.
|
|
Only files with the .cbl extension are passed to the compiler; cob2 passes all other
files to the linker.
|
The linker causes execution to begin at the first main program.
|
|
|
Listing output that you request from the compilation of a COBOL source program
file.cbl is written to file.lst. Listing output that you request from the linker is
written to stdout.
Chapter 14. Compiling under OS/390 UNIX
237
Creating a DLL
|
|
|
|
To create a DLL, you must specify the cob2 option -bdll. The COBOL compiler
options DLL, EXPORTALL, and RENT are required when you create a DLL and are
included for you when you specify the -bdll cob2 option. For example:
|
|
|
|
|
|
When you specify cob2 -bdll, the link step produces a DLL definition side file.
This file contains IMPORT control statements for each of the names exported by the
DLL. The name of the DLL definition side file is based on the output file name. If
the output name has an extension, that extension is replaced with “x” to form the
side file name. For example, if the output file name is foo.dll, the side file name is
foo.x.
|
|
|
|
To use the DLL definition side files later when you create a module that calls the
DLL, specify the side files with any other object files (file.o) that you specify for the
linking. For example:
cob2 -o mydll -bdll mysub.cbl
cob2 -o myappl -qdll myappl.cbl mydll.x
“Example: using cob2 to compile under OS/390 UNIX”
RELATED TASKS
“Compiling programs to create DLLs” on page 490
Language Environment Programming Guide
OS/390 UNIX System Services User’s Guide
RELATED REFERENCES
“cob2” on page 239
“cob2 input and output files” on page 240
“Data sets used by the compiler under OS/390” on page 218
“Compiler options and compiler output under OS/390” on page 224
OS/390 UNIX System Services Command Reference
Example: using cob2 to compile under OS/390 UNIX
The following examples illustrate the use of cob2:
v To compile one file (called alpha.cbl here), enter:
|
|
|
cob2 -c alpha.cbl
The compiled file is named alpha.o.
|
|
|
v To compile two files (called alpha.cbl and beta.cbl here), enter:
|
|
|
|
The compiled files are named alpha.o and beta.o.
v To link two files, compile them without the -c option. For example, to compile
and link alpha.cbl and beta.cbl and generate gamma, enter:
|
|
|
|
|
This command creates alpha.o and beta.o, then links alpha.o, beta.o, and the
COBOL libraries. If the link step is successful, it produces an executable program
named gamma.
v To compile alpha.cbl with the LIST and NODATA options, enter:
cob2 -c alpha.cbl beta.cbl
cob2 alpha.cbl beta.cbl -o gamma
cob2 -qlist,noadata alpha.cbl
238
Programming Guide
cob2
|
Do not capitalize cob2.
|
The options for cob2 are as follows:
|
|
|
|
-bxxx
Passes the string xxx to the linker as parameters. xxx is a list of linker
options in name=value format, separated by commas. You must spell out
both the name and the value in full. They are case insensitive. Do not use
any spaces between -b and xxx.
|
|
If you do not specify a value for an option, a default value of YES is used,
except for the following options, which have the indicated default values:
|
|
|
|
v
v
v
v
|
|
One special value is when xxx is dll, which specifies that the executable
module is to be a DLL. It is not passed to the linker.
LIST=NOIMPORT
ALIASES=ALL
COMPAT=CURRENT
DYNAM=DLL
|
-c
|
|
|
|
|
|
|
|
-comprc_ok=n
Controls cob2 behavior on the return code from the compiler. If the return
code is less than or equal to n, cob2 continues to the link step or, in the
compile-only case, exits with a zero return code. If the return code
returned by the compiler is greater than n, cob2 exits with the same return
code. When the c89 command is implicitly invoked by cob2 for the link
step, the exit value from the c89 command is used as the return code from
the cob2 command.
Compiles programs but does not link them.
The default is -comprc_ok=4.
|
|
|
|
|
-e xxx Specifies the name of a program to be used as the entry point of the
module. If you do not specify -e, the default entry point is the first
program (file.cbl) or object file (file.o) that you specify as a file name on the
cob2 command invocation.
|
|
-g
Prepares the program for debugging. Equivalent to specifying the TEST
option with no suboptions.
|
|
-Ixxx
Adds a path xxx to the directories to be searched for COPY files for which
you do not specify a library-name.
|
|
To specify multiple paths, either use multiple -I options, or use a colon to
separate multiple path names within a single -I option value.
|
|
For COPY statements where you have not coded an explicit library name,
the compiler searches for your COPY book in this order:
|
|
|
1. In the current directory
2. In the paths you specify with the -I cob2 option
3. In the paths you specify in the SYSLIB environment variable
Chapter 14. Compiling under OS/390 UNIX
239
|
|
If you use the COPY statement, you must ensure that the LIB compiler
option is in effect.
|
|
-L xxx Specifies the directory paths to be used to search for archive libraries
specified by the -l operand.
|
|
|
|
-l xxx
|
|
-o xxx Names the object module xxx. If the -o option is not used, the name of the
object module is a.out.
|
|
-qxxx
Specifies the name of an archive library for the linker. The cob2 command
searches for the name libxxx.a in the directories specified on the -L option,
then in the usual search order. (This is lowercase “el,” not uppercase
“eye.”)
Passes xxx to the compiler, where xxx is a list of compiler options
separated by blanks or commas.
Enclose xxx in quotes if a parenthesis is part of the option or suboption, or
if you use blanks to separate options. Do not insert spaces between -q and
xxx.
|
|
|
|
|
|
|
|
|
|
|
-v
|
-#
Displays the generated commands that are issued by cob2 for the compile
and link steps, including the options being passed, and executes them. This
is sample output:
cob2 -v -o mini -qssrange mini.cbl
compiler: ATTCRCTL PARM=RENT,TERM,SSRANGE /u/userid/cobol/mini.cbl
PP 5648-A25 IBM COBOL for OS/390 & VM 2.2.0 in progress ...
End of compilation 1, program mini, no statements flagged.
linker: /bin/c89 -o mini -e // mini.o
Displays compile and link steps, but does not execute them.
RELATED TASKS
“Compiling and linking with the cob2 command” on page 237
“Setting environment variables under OS/390 UNIX” on page 235
cob2 input and output files
|
|
You can specify the following files as input file names when you use the cob2
command:
|
|
File
name
|
|
Description
Comments
file.cbl
COBOL source file to be compiled and
linked
Will not be linked if you specify the
cob2 option -c
|
|
file.a
Archive file
Produced by the ar command, to be
used during the link-edit phase
|
|
|
file.o
Object file to be link-edited
Can be produced by the COBOL
compiler, the C/C++ compiler, or the
assembler
|
|
|
file.x
DLL definition side file
Used during the link-edit phase of an
application that references the dynamic
link library (DLL)
|
|
When you use the cob2 command, the following files are created in the current
directory:
240
Programming Guide
|
|
File
name
Description
Comments
|
|
file
Executable module or DLL
Created by the linker if you specify the
cob2 option -o file
|
|
a.out
Executable module or DLL
Created by the linker if you do not
specify the cob2 option -o
|
|
|
file.adt
Associated data (ADATA) file
corresponding to input COBOL source
program file.cbl
Created by the compiler if you specify
the compiler option ADATA
|
|
|
file.dbg
Symbolic information tables for Debug
Tool corresponding to input COBOL
source program file.cbl
Created by the compiler if you specify
the compiler option
TEST(hook,SYM,SEPARATE)
|
|
|
file.idl
Interface Definition Language (IDL) file Created by the compiler if you specify
for OO COBOL class definitions
the compiler option IDLGEN
defined in input source program file.cbl
|
|
file.lst
Listing file corresponding to input
COBOL source program file.cbl
Created by the compiler
|
|
file.o
Object file corresponding to input
COBOL source program file.cbl
Created by the compiler
|
|
file.x
DLL definition side file
Created during the cob2 linking phase
when creating a DLL named file.dll
RELATED TASKS
“Compiling and linking with the cob2 command” on page 237
RELATED REFERENCES
“ADATA” on page 261
“TEST” on page 295
“IDLGEN” on page 277
OS/390 UNIX System Services Command Reference
Compiling using scripts
|
|
|
|
|
|
|
|
To use a shell script to automate your cob2 tasks, use the following syntax to
prevent the shell from passing syntax to cob2 that is not valid:
v Use an equal sign and colon rather than left and right parentheses, respectively,
to specify compiler suboptions. For example, use -qOPT=FULL:,XREF instead of
-qOPT(FULL),XREF.
v Use an underscore rather than apostrophe where a compiler option requires
apostrophes for delimiting a suboption.
v Do not use blanks in the option string.
Chapter 14. Compiling under OS/390 UNIX
241
242
Programming Guide
Chapter 15. Compiling under CMS
Under CMS, the COBOL compiler can compile any COBOL source program it can
compile under OS/390 except programs that contain embedded SQL. The object
code generated under CMS by the COBOL compiler can be run under OS/390 or
CMS, with certain run-time restrictions.
To compile under CMS:
1. Make the compiler available to you on a minidisk through using the CP LINK
and ACCESS commands. If IBM COBOL for OS/390 & VM is stored on your
A-disk or another disk to which you already have access, you can omit this
step.
2. Start the compiler by using the COBOL2 command. You can start the compiler by
using ISPF/PDF menus if you have ISPF/PDF Version 3 installed at your site.
The compiler translates your COBOL program into language that the computer can
process (object code). The compiler also lists errors in your source statements and
provides supplementary information to help you debug and tune your program.
Use compiler-directing statements and compiler options to control your
compilation.
RELATED TASKS
“Accessing the compiler (CP LINK and ACCESS)”
“Specifying a source program to compile” on page 244
“Using compiler-directing statements” on page 245
“Specifying compiler options under CMS” on page 246
“Naming generated files under CMS” on page 251
“Correcting errors” on page 252
“Chapter 22. Running COBOL programs under CMS” on page 369
RELATED REFERENCES
“Run-time restrictions under CMS” on page 369
“COBOL2” on page 244
“Differences in compiler options under CMS” on page 248
“Files used by the compiler under CMS” on page 248
Accessing the compiler (CP LINK and ACCESS)
To access the compiler under CMS:
1. Link to the mini disk containing the compiler by issuing the CP LINK
command.
2. Issue the ACCESS command to identify the mini disk to CMS.
For example:
CP LINK PRODUCT 194 198 RR PASSWORD
ACCESS 198 B
This example links to disk 194 of the virtual machine that contains the IBM
COBOL for OS/390 & VM product and for which the user ID is PRODUCT. It defines
disk 194 as 198 to the VM session. It asks for read access to the disk (RR) and
enters the read-share password for the 194 disk (PASSWORD). After linking to the 194
disk as 198, this code accesses the 198 disk as disk B.
© Copyright IBM Corp. 1991, 2000
243
If you can avoid having to access the compiler explicitly each time you need it,
simply put the CP LINK and ACCESS commands into your PROFILE EXEC, which
issues them for you each time you log on.
Specifying a source program to compile
Use one of the following methods to indicate which COBOL source program to
compile:
v Enter the file name of the COBOL source program with the COBOL2 command.
For example:
COBOL2 PROG1 (SOURCE,VBREF,XREF,MAP)
This command compiles the COBOL source program named PROG1 using the
compiler options SOURCE, VBREF, XREF, and MAP. The source program must have a
file type of COBOL.
v Issue a FILEDEF for SYSIN before compiling. For example:
FILEDEF SYSIN DISK PROG2 COBOL A
COBOL2 (SOURCE,VBREF,XREF,MAP)
This code compiles the COBOL program named PROG2 using the options
entered with the COBOL2 command.
The compiler uses the source program that you enter with the FILEDEF, even if
you provided an optional file name on the command line. The compiler uses the
optional file name for the name of listing, text, SYSADATA, and work files. With
FILEDEF, the file type need not be COBOL.
v Supply source statements from a user-supplied module by using the EXIT
compiler option.
Neither a FILEDEF for SYSIN nor a file name in the COBOL2 command is required.
For example:
COBOL2 (EXIT(INEXIT('ABCD',INMOD1)),VBREF,XREF)
This command compiles the source statements provided by the input user
module named INMOD1 using the character string ABCD and the options VBREF
and XREF.
The compiler ignores FILEDEF for SYSIN when the INEXIT suboption of the EXIT
option is specified. However, you can provide an optional file name with the
COBOL2 command that will be used as the name for listing, text, and work files.
RELATED REFERENCES
“COBOL2”
COBOL2
You can compile programs under CMS by using the COBOL2 command.
244
Programming Guide
filename
The name of your COBOL source program. Use one of three methods for
specifying your source COBOL program.
options
Represents one or more compiler options, separated by a blank or comma,
that you want in effect during compilation. These compiler options are
equivalent to the options you would provide on the PARM parameter of an
EXEC job-control statement, if you were invoking the compiler under
OS/390.
The compiler options in effect at compile time are determined by the
default options that were set when IBM COBOL for OS/390 & VM was
installed and by the options you enter with the COBOL2 command. Three
compiler options can be used only when running under CMS: DISK, PRINT,
and NOPRINT.
Your installation might have created a synonym for COBOL2 when the compiler was
installed. See your system programmer for the command name.
RELATED TASKS
“Specifying a source program to compile” on page 244
“Specifying compiler options under CMS” on page 246
“Naming generated files under CMS” on page 251
RELATED REFERENCES
“Additional compiler options under CMS” on page 247
Using compiler-directing statements
You can put compiler-directing statements in your source program to help direct
compilation.
If you have files that contain frequently used COBOL code, you can place them in
a CMS file called a MACLIB. You can then use the compiler-directing COPY
statement in your COBOL program and identify the MACLIB to be searched
during compilation.
If you are using the compiler-directing BASIS statement, you also place the BASIS
program in a CMS MACLIB file.
To make the MACLIB available, you must issue the CMS GLOBAL command:
GLOBAL MACLIB mylib
where mylib is the name of your MACLIB file (library).
If the GLOBAL command is issued, the FILEDEF command for SYSLIB will be issued
by IBM COBOL for OS/390 & VM.
To use the COPY statement to copy from libraries other than SYSLIB, you must issue
a FILEDEF command for each library. The ddname field of the FILEDEF command is
identical to the library-name in your program. For these additional libraries, do not
issue a GLOBAL command.
RELATED REFERENCES
“Compiler-directing statements” on page 304
Chapter 15. Compiling under CMS
245
Specifying compiler options under CMS
The compiler is installed and set up with default compiler options. The default
options will be used unless you override them in either the PROCESS (synonym:
CBL) statement or the COBOL2 command.
Compiler options under CMS have these differences:
v Three additional compiler options are available: DISK, PRINT, and NOPRINT.
v Certain compiler options behave differently: DUMP, TERMINAL, and LANGUAGE.
v Compiler options are recognized in a specific order of precedence. You can
specify any compiler options on the PROCESS statement except DISK, PRINT,
NOPRINT, EVENTS, ADATA, and EXIT. Specifying any of these options on a PROCESS
statement is not allowed and causes a diagnostic message to be issued.
You can enter more than one compiler option on the COBOL2 command line, using a
blank character or a comma as a separator. Do not mix commas and blanks within
the command. If you choose blanks, use all blanks; if you choose commas, use all
commas.
The COBOL2 command can diagnose some errors in compiler options from the
command line by issuing a message to the terminal and then stopping the
compilation. If the compilation is not ended, you should check the compiler listing
for other compiler-detected errors. The listing shows subparameter values that are
not valid. If a subparameter is optional, you can omit it and the separator
character.
Using parentheses in COBOL2
You must use parentheses with options that normally require them. For example,
you can enter the same command in either of these different ways:
COBOL2 FILENAME (SZ(MAX),BUF(10K),LC(55),OPT)
COBOL2 FILENAME (SZ(MAX) BUF(10K) LC(55) OPT)
The format for specifying options in the COBOL2 command is the same as for
specifying options on the PROCESS statement.
Option lists for existing applications that use only spaces and no parentheses will
continue to work, and the compiler will issue a warning indicating that
parentheses were added to the option list. If you change an existing options list by
adding an option that requires parentheses, by adding commas, or by adding an
option greater than eight characters, then parentheses must also be added to all the
existing options that require them.
If you do not place commas between options or parenthesize subparameters, the
compiler might place parentheses around any subparameters following an option.
For example, NOC is an option that can be coded with or without the subparameter
S, and SOURCE is an option that can be abbreviated as S. The option string NOC S
might be interpreted as NOC(S) if the compiler assumes you are entering
subparameters without parentheses. To ensure correct interpretation of the NOC
option followed by the S option, you could code NOC,S.
Abbreviating compiler options
When you enter the options in the command, you can use either the full option
name or the allowed abbreviations. Options can be more than eight characters.
246
Programming Guide
If you receive an error message that too many characters were specified for options
in the COBOL2 command, you must reissue the command with fewer option
characters. You can use more abbreviations for the options or enter some options
on the PROCESS statement. However, moving options to the PROCESS statement
could change their precedence.
Using logical line-editing characters
When entering options with the COBOL2 command, be aware of the VM/ESA logical
line-editing characters that are established for your terminal or virtual console.
VM/ESA does not consider the logical line-editing characters as part of the input
stream that is passed to the invoked program.
For example, the VM/ESA default setting for the logical escape character is the
quotation mark (“). Suppose the compiler option CURRENCY(”$“) was entered with
the COBOL2 command:
COBOL2 progname (CURRENCY(”$“)
VM/ESA removes the character ” from the input stream and passes the following
code:
CURRENCY($)
The COBOL for OS/390 & VM compiler then diagnoses the option CURRENCY($) as
not valid because of the missing delimiters in the value.
RELATED REFERENCES
“Additional compiler options under CMS”
“Files used by the compiler under CMS” on page 248
“Error messages from COBOL2” on page 252
Additional compiler options under CMS
Three compiler options are unique to COBOL under CMS: DISK, PRINT, and
NOPRINT. They are valid only when used with the COBOL2 command.
Default is: DISK
Abbreviations are: DI, PRI, and NOPRI, respectively
Use DISK to request that a program listing be produced containing any of the
following information:
v Page headings
v Line numbers of the statements in error
v Message identification numbers
v Severity levels
v Message texts
v Any other output requested by OFFSET, MAP, LIST, XREF, SOURCE, or VBREF
This listing will be written to the appropriate read/write disk with a file type of
LISTING.
Chapter 15. Compiling under CMS
247
Use PRINT to request that the program listing be printed on your virtual printer.
Use NOPRINT if you want no LISTING file to be produced.
If you have issued a FILEDEF for SYSPRINT to redirect the listing file produced by
the compiler, the DISK, PRINT, and NOPRINT options are ignored.
DISK, PRINT, and NOPRINT are opposing options. If you enter more than one of these
options with the COBOL2 command, the last one takes precedence.
Differences in compiler options under CMS
The following differences apply to using the compiler options under CMS:
v The DUMP option specifies that there is to be an abend at the point of failure, but
no output is produced.
v The default for the TERMINAL option is TERMINAL, whereas under OS/390 it is
NOTERMINAL.
v The LANGUAGE option does not control the language of messages issued by the
COBOL2 command processor. The language of these messages is determined by
the installation default LANGUAGE selection and cannot be changed.
RELATED REFERENCES
“Error messages from COBOL2” on page 252
Precedence of compiler options under CMS
Compiler options under CMS are recognized in the following order of precedence
from highest to lowest:
1.
2.
3.
4.
Installation defaults fixed by your site
Options specified on PROCESS (or CBL) statements
Options specified on the COBOL2 command
Installation defaults that are not fixed
This order of precedence also determines which options are in effect when
conflicting or mutually exclusive options are specified.
RELATED REFERENCES
“Conflicting compiler options” on page 259
“Chapter 16. Compiler options” on page 257
Files used by the compiler under CMS
When you compile a COBOL program, the compiler generates work files and
possibly output such as listings and error messages.
When the compiler is running, it uses and creates both work and default files, as
shown below.
FILEDEF
File type
Function
Required?
Default
device
SYSIN
COBOL
Reads the source file
Yes
Disk
SYSLIB
MACLIB
Reads user source libraries If program has COPY or
BASIS statements (LIB
option is required)
248
Programming Guide
Disk
Comments
FILEDEF
File type
Function
Required?
Default
device
SYSUT1 to
SYSUT4,
SYSUT6,
and
SYSUT71
SYSUT1 to
SYSUT4,
SYSUT6,
and
SYSUT7
Work files used by the
compiler during
compilation
Yes
Disk
SYSUT51
SYSUT5
Work file used by the
compiler during
compilation
If LIB is in effect
Disk
SYSPRINT
LISTING
Writes listings and
messages
If DISK is in effect
Disk
Written to the
appropriate disk2
If PRINT is in effect
Printer
Printed on virtual
printer
Creates machine-language
code; no error messages
are produced with a
severity level higher than
the severity indicated in
the COMPILE option.
Yes
Disk
Written to the
appropriate disk2
SYSLIN
TEXT
Comments
If you need to stop a
compilation before it
finishes, these files
might still reside on
one of your disks,
and you should erase
them.
You can relocate this
TEXT file and run it
after loading it into
virtual storage.
SYSDEBUG
SYSDEBUG
Writes symbolic debug
information tables to a
data set separate from the
object module
If TEST(...,SYM,SEPARATE)
is in effect
Disk
SYSTERM
None
Writes progress and
diagnostic messages and
compiler statistics
If TERM is in effect
Terminal
SYSPUNCH
None
Writes object module on
spooled punch
If DECK is in effect
Punch
SYSADATA
SYSADATA
Writes record types that
have machine-readable
information about the
compilation
If ADATA or EVENTS is in
effect
Disk
Written to the
appropriate disk2
1. These files are written to the minidisk with the most available read-write space; they are erased at the end of
compilation.
2. LISTING, TEXT, and SYSADATA files are written to the minidisk where the source COBOL program resides, if
that disk is accessed as read-write. If that disk is not accessed in read-write mode, the LISTING, TEXT, and
SYSADATA files are written to the first read-write disk found using the search order.
Compiler options and compiler output under CMS
If you use certain compiler options, the compiler will also create files with the file
types of TEXT, LISTING, or SYSADATA. Their file names are the same as the name
of the source file. If any TEXT, LISTING, or SYSADATA file with the same name
already exists, it is erased, even when you use NOOBJECT or NOPRINT or both.
The following table lists the types of output you will get if you use various
compiler options.
Chapter 15. Compiling under CMS
249
Compiler option
LISTING file
DECK
TEXT file
Terminal (with TERM
option)
File is created; object code
DISK
Writes the LISTING file to disk
EXIT(PRTEXIT)
Writes the LISTING file to a
user-specified module
FLAG(x[,y])
Warning messages and error
messages to LISTING file
Warning messages and
error messages are
displayed
FLAGMIG
Warning messages and error
messages to LISTING file
Warning messages and
error messages are
displayed
FLAGSTD(x[yy][,z])
Information messages to
LISTING file
Information messages are
displayed
LIST
Assembler language expansion,
global tables, literal pools,
WORKING-STORAGE location, length
MAP
Glossary, global tables, literal
pools
NUMBER
User-supplied line numbers
shown in listing
OBJECT
OFFSET
Object code
Condensed object listing in
LISTING file
OPTIMIZE
Optimized object code if
OBJECT option in effect
PGMNAME(LU),(LM)
Where appropriate, you will see
long names in your listing
PRINT
Prints LISTING file on virtual
printer
RENT
Reentrant object code if
OBJECT option in effect
SOURCE
Source module to LISTING file
SPACE(1)
LISTING file is single-spaced
SPACE(2)
LISTING file is double-spaced
SPACE(3)
LISTING file is triple-spaced
SSRANGE
Extra code generated for
checking references within
tables
TERMINAL
Progress and diagnostic
messages to terminal
TEST
Extra code generated
VBREF
Verb cross-reference list to
LISTING file
XREF, XREF(FULL),
XREF(SHORT)
Sorted procedure and data-names
to LISTING file
250
Programming Guide
RELATED TASKS
“Naming generated files under CMS”
“Correcting errors” on page 252
Naming generated files under CMS
The names for the files the compiler generates depend on how you code the
COBOL2 command and whether you issue any FILEDEFs.
If you start the compiler using COBOL2 and the file name of the source program, the
compiler will assign file names that are the same as the source program file name:
COBOL2 filename (SOURCE,VBREF,XREF,MAP)
You can override the name of a compiler-created file (such as listing, text, or work
files) by issuing a CMS FILEDEF command. When you issue a FILEDEF with a
different file name or file type, the file is not erased when the compilation ends.
Indicate the file name to be assigned by the compiler for these files with any of the
following methods when you start the compiler:
FILEDEF SYSIN DISK PROG2 COBOL A
COBOL2 PROG1 (SOURCE,VBREF,XREF,MAP)
or
COBOL2 PROG1 (EXIT(INEXIT('ABCD',INMOD1)),VBREF,XREF)
or
FILEDEF SYSIN DISK PROG2 COBOL A
COBOL2 PROG1 (EXIT(INEXIT('ABCD',INMOD1)),VBREF,XREF)
In all the above cases, the compiler assigns the file name PROG1.
Overriding FILEDEF
By using the PRTEXIT suboption of the EXIT option, you can override two
specifications for file names:
v The listing output from the FILEDEF command for SYSPRINT
v Any optional file name that you specify in the COBOL2 command
For example:
FILEDEF SYSPRINT DISK PROG4 COBOL A
COBOL2 PROG2 (EXIT(PRTEXIT('WXYZ',OUTMOD)),VBREF,XREF)
This code causes the SYSPRINT output to be transmitted to the user-supplied exit
module named OUTMOD.
Using system-generated names
CMS defines the listing, text, work, associated data (ADATA), and debugging
information files for you if you do not provide a file name in the COBOL2 command
and either of the following conditions exists:
v A FILEDEF for SYSIN is not supplied (for example, when an input user exit
provides the source statements for the compiler).
v The FILEDEF for SYSIN does not include a file name (such as FILEDEF SYSIN
READER).
The default file name provided by CMS is FILE. The table below shows the file
types of the files.
Chapter 15. Compiling under CMS
251
File
CMS file type
Listing
SYSPRINT
Text
SYSLIN
Work files
SYSUTn
Associated data files
SYSADATA
Symbolic debugging information
SYSDEBUG
RELATED REFERENCES
“Files used by the compiler under CMS” on page 248
Correcting errors
You can usually identify a problem from the diagnostic message you see displayed
at the terminal, so that you do not have to examine a printed listing file. When
you have an error, you can correct the source file immediately and recompile it.
Under CMS, the TERM option is in effect unless the default value for your site has
been changed to TERM=NO or you have specified the NOTERM option. TERM specifies
that all diagnostic messages issued by the compiler are displayed at your terminal,
in addition to being written to a LISTING file.
RELATED REFERENCES
“Error messages from COBOL2”
Error messages from COBOL2
The COBOL2 command can generate error messages. These have the identification
DMSIGY, followed by a message number, severity indicator, and message text.
Whether the message identification or text, or both, is displayed depends on the
setting in your virtual machine of EMSG, which is a CP SET command function.
Many of the DMSIGY messages issued by CMS are self-explanatory. For example:
COBOL2 myprog
DMSIGY002E Source file “MYPROG COBOL” was not found.
DMSIGY000E The COBOL2 command was terminated.
Ready(00040);
The error was issued because the specified input file was not found on any of the
accessed disks. You should reissue the command using the correct file name.
The messages issued by the COBOL2 command will be in the language specified by
your installation’s default setting for the LANGUAGE compiler option.
The error messages issued by the COBOL2 command are listed below.
Be sure to check your listing for any errors not detected by the COBOL2 command.
252
Programming Guide
Message number
Message text
DMSIGY000E (page 253)
THE COBOL2 COMMAND WAS TERMINATED.
DMSIGY002E (page 253)
SOURCE FILE “filename filetype” WAS NOT FOUND.
DMSIGY003E (page 253)
AN ASTERISK “*” WAS USED AS A FILE NAME IN THE
COBOL2 COMMAND.
DMSIGY004E (page 254)
AN ERROR OCCURRED WHILE ATTEMPTING TO LOAD
MODULE “modname”.
DMSIGY005W (page 254)
THE OPTIONS PARAMETER LIST WAS PARENTHESIZED
BY THE COMPILER. THE OPTIONS IN EFFECT MAY NOT
BE AS INTENDED.
DMSIGY011E (page 254)
A CMS DISK WAS NOT ACCESSED IN READ/WRITE
MODE.
DMSIGY012E (page 254)
DEVICE “device” WAS INVALID IN A USER FILEDEF FOR
SYSIN.
DMSIGY021E (page 254)
SOURCE FILE “filename filetype” DID NOT HAVE “FIXED”
RECORD FORMAT.
DMSIGY030E (page 255)
THE FOLLOWING OPTIONS SPECIFIED WERE INVALID:
DMSIGY031I (page 255)
“option-1 option-2...option-n”.
DMSIGY032E (page 255)
OPTION “option” DID NOT HAVE A VALUE SPECIFIED.
DMSIGY033E (page 255)
TOO MANY CHARACTERS WERE SPECIFIED FOR
OPTIONS IN THE COBOL2 COMMAND.
DMSIGY034E (page 256)
A LEFT PARENTHESIS “(” DID NOT PRECEDE THE
OPTION LIST IN THE COBOL2 COMMAND.
DMSIGY036W (page 256)
THE OPTION LIST WAS TERMINATED BY A RIGHT
PARENTHESIS “)”. THE REMAINDER OF THE OPTION LIST
WAS IGNORED.
DMSIGY037E (page 256)
THE OPTION “GRAPHIC” IS NOT SUPPORTED.
DMSIGY000E
THE COBOL2 COMMAND WAS TERMINATED.
Explanation: An error was detected that will terminate the COBOL2 command. This
message will be issued only once for invalid COBOL2 commands.
Programmer response: Reissue the command, correcting the errors indicated by
previous messages.
System action: Execution of the COBOL2 command ends. The system status is the
same as before the command executed, except that all user FILEDEFs issued
without the PERM option will be cleared.
DMSIGY002E
SOURCE FILE “filename filetype” WAS NOT FOUND.
Explanation: The specified input file was not found on any of the accessed disks.
Programmer response: Reissue the command, specifying the correct input file.
System action: RC=40. Execution of the COBOL2 command ends. The system has the
same status as before the command executed.
DMSIGY003E
AN ASTERISK “*” WAS USED AS A FILE NAME IN THE COBOL2 COMMAND.
Chapter 15. Compiling under CMS
253
Explanation: ’*’ is not a valid file name for the COBOL2 command.
Programmer response: Reissue the command with a valid file name.
System action: RC=40. Execution of the COBOL2 command ends. The system has the
same status as before the command executed.
DMSIGY004E
AN ERROR OCCURRED WHILE ATTEMPTING TO LOAD MODULE “modname”.
Explanation: An error was detected by the command processor while attempting
to load module modname.
Programmer response: Reissue the command.
System action: Compilation ends, and a user abend is initiated.
DMSIGY005W
THE OPTIONS PARAMETER LIST WAS PARENTHESIZED BY THE COMPILER. THE
OPTIONS IN EFFECT MAY NOT BE AS INTENDED.
Explanation: An options parameter list was used that contained no suboption
parentheses.
Programmer response: Verify the options as shown in the listing.
System action: The compiler adds any required parentheses to the list.
DMSIGY011E
A CMS DISK WAS NOT ACCESSED IN READ/WRITE MODE.
Explanation: No read/write disk is available for compiler output and work files.
Programmer response: Access a CMS disk in read/write mode.
System action: RC=40. Execution of the COBOL2 command ends. The system has the
same status as before the command executed.
DMSIGY012E
DEVICE “device” WAS INVALID IN A USER FILEDEF FOR SYSIN.
Explanation: A user FILEDEF specifying a device invalid for SYSIN has been issued.
Programmer response: Reissue the COBOL2 command specifying a valid device for
SYSIN, or clear the SYSIN FILEDEF.
System action: RC=40. Execution of the COBOL2 command ends. The user-issued
FILEDEF is cleared unless the PERM option was specified. Otherwise, the system has
the same status as before the command executed.
254
Programming Guide
DMSIGY021E
SOURCE FILE “filename filetype” DID NOT HAVE “FIXED” RECORD FORMAT.
Explanation: COBOL source file must have FIXED record format.
Programmer response: Change the record format of the source file to FIXED and
reissue the command.
System action: RC=40. Execution of the COBOL2 command ends. The system has the
same status as before the command executed.
DMSIGY030E
THE FOLLOWING OPTIONS SPECIFIED WERE INVALID:
Explanation: At least one invalid option is specified in the command line. The
invalid options are listed under message DMSIGY031I that follows.
Programmer response: Reissue the COBOL2 command with valid options.
System action: RC=40. Execution of the COBOL2 command ends. The system has the
same status as before the command executed.
DMSIGY031I
“option-1 option-2...option-n”.
Explanation: This is the list of invalid options indicated by message DMSIGY030E.
Programmer response: Same as message DMSIGY030E
System action: Same as message DMSIGY030E
DMSIGY032E
OPTION “option” DID NOT HAVE A VALUE SPECIFIED.
Explanation: The option stated must have a value specified.
Programmer response: Reissue the COBOL2 command, specifying a value for the
option.
System action: RC=40. Execution of the COBOL2 command ends. The system has the
same status as before the command executed.
DMSIGY033E
TOO MANY CHARACTERS WERE SPECIFIED FOR OPTIONS IN THE COBOL2
COMMAND.
Explanation: User specified too many characters for options in the COBOL2
command line.
Chapter 15. Compiling under CMS
255
Programmer response: Reissue the COBOL2 command with fewer options or use
abbreviations
System action: RC=40. Execution of the COBOL2 command ends. The system has the
same status as before the command executed. for the options.
DMSIGY034E
A LEFT PARENTHESIS “(” DID NOT PRECEDE THE OPTION LIST IN THE COBOL2
COMMAND.
Explanation: Options following the file name in the COBOL2 command must be
preceded by a left parenthesis.
Programmer response: Reissue the COBOL2 command with the correct syntax.
System action: RC=40. Execution of the COBOL2 command ends. The system has the
same status as before the command executed.
DMSIGY036W
THE OPTION LIST WAS TERMINATED BY A RIGHT PARENTHESIS “)”. THE
REMAINDER OF THE OPTION LIST WAS IGNORED.
Explanation: A right parenthesis has prematurely ended the option list in the
COBOL2 command.
System action: RC=0. Any options following a right parenthesis are ignored. The
COBOL2 command will be executed unless other terminating errors are detected.
Programmer response: Reissue the command deleting the right parenthesis.
DMSIGY037E
THE OPTION “GRAPHIC” IS NOT SUPPORTED.
Explanation: The user specified GRAPHIC as an option of the COBOL2 command. This
option is not supported in Release 2.0 or later.
Programmer response: Reissue the COBOL2 command without the GRAPHIC option.
System action: RC=40. Execution of the COBOL2 command ends. The system has the
same status as before the command executed.
RELATED TASKS
“Correcting errors” on page 252
256
Programming Guide
Chapter 16. Compiler options
You can direct and control your compilation in two ways:
v By using compiler options
v By using compiler-directing statements (compile directives)
Compiler options affect the aspects of your program that are listed in the table
below. The linked-to information for each option provides the syntax for specifying
the option and describes the option, its parameters, and its interaction with other
parameters.
|
Aspect of your
program
Compiler option
Default
Abbreviations
Source language
“ARITH” on page 262
ARITH(COMPAT)
AR(C), AR(E)
“QUOTE/APOST” on page 289
QUOTE
Q|APOST
“CMPR2” on page 264
NOCMPR2
None
“CURRENCY” on page 265
NOCURRENCY
CURR|NOCURR
“DBCS” on page 269
NODBCS
None
“LIB” on page 280
LIB
None
“NUMBER” on page 283
NONUMBER
NUM|NONUM
“SEQUENCE” on page 291
SEQUENCE
SEQ|NOSEQ
“SQL” on page 293
NOSQL
None
“WORD” on page 301
NOWORD
WD|NOWD
“DATEPROC” on page 267
NODATEPROC, or
DATEPROC(FLAG,NOTRIG) if only
DATEPROC is specified
DP|NODP
“INTDATE” on page 278
INTDATE(ANSI)
None
“YEARWINDOW” on page 303
YEARWINDOW(1900)
YW
“LANGUAGE” on page 279
LANGUAGE(ENGLISH)
LANG(EN|UE|JA|JP)
“LINECOUNT” on page 280
LINECOUNT(60)
LC
“LIST” on page 281
NOLIST
None
“MAP” on page 281
NOMAP
None
“OFFSET” on page 285
NOOFFSET
OFF|NOOFF
“SOURCE” on page 292
SOURCE
S|NOS
“SPACE” on page 293
SPACE(1)
None
“TERMINAL” on page 295
NOTERMINAL
TERM|NOTERM
“VBREF” on page 301
NOVBREF
None
“XREF” on page 302
NOXREF
X|NOX
|
Date processing
Maps and listings
© Copyright IBM Corp. 1991, 2000
257
Aspect of your
program
Object deck
generation
Object code control
Virtual storage usage
Debugging and
diagnostics
Other
Compiler option
Default
Abbreviations
“COMPILE” on page 265
NOCOMPILE(S)
C|NOC
“DECK” on page 269
NODECK
D|NOD
“NAME” on page 282
NONAME, or NAME(NOALIAS) if only
NAME is specified
None
“OBJECT” on page 284
OBJECT
OBJ|NOOBJ
“PGMNAME” on page 287
PGMNAME(COMPAT)
PGMN(CO|LU|LM)
“ADV” on page 262
ADV
None
“AWO” on page 263
NOAWO
None
“DLL” on page 270
NODLL
None
“EXPORTALL” on page 272
NOEXPORTALL
EXP|NOEXP
“FASTSRT” on page 273
NOFASTSRT
FSRT|NOFSRT
“NUMPROC” on page 283
NUMPROC(NOPFD)
None
“OPTIMIZE” on page 285
NOOPTIMIZE
OPT|NOOPT
“OUTDD” on page 286
OUTDD(SYSOUT)
OUT
“TRUNC” on page 297
TRUNC(STD)
None
“ZWB” on page 304
ZWB
None
“BUFSIZE” on page 263
4096
BUF
“SIZE” on page 291
SIZE(MAX)
SZ
“DATA” on page 266
DATA(31)
None
“DYNAM” on page 272
NODYNAM
DYN|NODYN
“RENT” on page 289
NORENT
None
“RMODE” on page 290
AUTO
None
“DIAGTRUNC” on page 269
NODIAGTRUNC
DTR, NODTR
“DUMP” on page 271
NODUMP
DU|NODU
“FLAG” on page 274
FLAG(I)
F|NOF
“FLAGMIG” on page 275
NOFLAGMIG
None
“FLAGSTD” on page 275
NOFLAGSTD
None
“TEST” on page 295
NOTEST
None
“SSRANGE” on page 294
NOSSRANGE
SSR|NOSSR
“TYPECHK” on page 300
NOTYPECHK
TC|NOTC
“ADATA” on page 261
NOADATA
None
“ANALYZE” on page 261
NOANALYZE
None
“EXIT” on page 272
NOEXIT
EX(INX,LIBX,PRTX,ADX)
“IDLGEN” on page 277
NOIDLGEN
IDL
Installation defaults: The default options that were set up when your compiler
was installed are in effect for your program unless you override them with other
options. (In some installations, certain compiler options are set up as fixed so that
you cannot override them. If you have problems, see your system administrator.)
To find out the default compiler options in effect, run a test compilation without
specifying any options; the output listing lists the default options specified by your
installation.
258
Programming Guide
Nonoverridable options: In some installations, certain compiler options are set up
so that you cannot override them. If you have problems, see your system
administrator.
CMS only: The compiler options DISK, PRINT, and NOPRINT, which are not listed in
the following table, are unique to COBOL under CMS. For a description, see the
related information below.
Performance considerations: The DYNAM, FASTSRT, NUMPROC, OPTIMIZE, RENT, SSRANGE,
TEST, and TRUNC compiler options can all affect run-time performance.
RELATED REFERENCES
“Conflicting compiler options”
“Compiler-directing statements” on page 304
“Option settings for COBOL 85 Standard conformance”
RELATED TASKS
“Chapter 13. Compiling under OS/390” on page 203
“Compiling under TSO” on page 215
“Chapter 15. Compiling under CMS” on page 243
“Chapter 14. Compiling under OS/390 UNIX” on page 235
“Chapter 33. Tuning your program” on page 535
Option settings for COBOL 85 Standard conformance
The following compiler options are required to conform to the COBOL 85 Standard
specification:
ADV
NOCMPR2
NODATEPROC
NODBCS
DYNAM
NOFASTSRT
NOFLAGMIG
LIB
NAME(ALIAS) or NAME(NOALIAS)
NONUMBER
NUMPROC(NOPFD) or NUMPROC(MIG)
QUOTE
NOSEQUENCE
TRUNC(STD)
NOWORD
ZWB
The following run-time options are required to conform to the COBOL 85
Standard:
v AIXBLD
v CBLQDA(ON)
v TRAP(ON)
RELATED REFERENCES
Language Environment Programming Reference
Conflicting compiler options
The COBOL for OS/390 & VM compiler can encounter conflicting compiler options
in two ways:
v Both the positive and negative form of a compiler option are specified on the
same level in the hierarchy of precedence (such as specifying both DECK and
NODECK in a PROCESS (or CBL) statement).
Chapter 16. Compiler options
259
When conflicting options are specified at the same level in the hierarchy, the
option specified last takes effect.
v Mutually exclusive options are specified at the same level in the hierarchy,
regardless of order.
When you specify a mutually exclusive option, any conflicting options that you
specify are ignored. For example, if you specify both OFFSET and LIST in your
PROCESS statement, in any order, OFFSET takes effect and LIST is ignored.
However, options coded at a higher level of precedence override any options
specified at a lower level of precedence. For example, if you code OFFSET in your
JCL statement but LIST in your PROCESS statement, LIST will take effect because
the options coded in the PROCESS statement and any options forced on by an
option coded in the PROCESS statement have higher precedence.
The following table lists mutually exclusive compiler options.
Specified
Ignored1
Forced on1
|
|
|
ANALYZE
SQL
NOADATA
NOLIB
NOSQL
ADATA
LIB
|
|
|
|
|
CMPR2
ADATA
ANALYZE
ARITH(EXTEND)
CURRENCY
DATEPROC
DBCS
DIAGTRUNC
DLL
EXPORTALL
FLAGSTD
IDLGEN
INTDATE(LILIAN)
OPT(FULL)
PGMNAME(LU) and PGMNAME(LM)
RMODE(24) and RMODE(ANY)
SQL
TYPECHK
YEARWINDOW
NOADATA
NOANALYZE
ARITH(COMPAT)
NOCURRENCY
NODATEPROC
NODBCS
NODIAGTRUNC
NODLL
NOEXPORTALL
NOFLAGSTD
NOIDLGEN
INTDATE(ANSI)
OPT(STD)
PGMNAME(COMPAT)
RMODE(AUTO)
NOSQL
NOTYPECHK
YEARWINDOW(1900)
DBCS
FLAGMIG
NOFLAGMIG
DLL
DYNAM
NORENT
NODYNAM
RENT
EXIT
DUMP
NODUMP
EXPORTALL
NODLL
DYNAM
NORENT
DLL
NODYNAM
RENT
FLAGSTD
FLAGMIG
DBCS
NOFLAGMIG
NODBCS
NOCMPR2
FLAGMIG
NOFLAGMIG
|
|
|
|
|
|
|
|
260
Programming Guide
OFFSET
LIST
NOLIST
SQL
NOLIB
LIB
TEST
TEST(ALL)
TEST(STMT)
TEST(PATH)
TEST(BLOCK)
NOOBJECT
OPT(STD) or OPT(FULL)
OBJECT
NOOPTIMIZE
Specified
Ignored1
Forced on1
WORD
FLAGSTD
NOFLAGSTD
1. Unless in conflict with a fixed installation default option.
RELATED TASKS
“Specifying
“Specifying
“Specifying
“Specifying
compiler
compiler
compiler
compiler
options
options
options
options
under OS/390” on page 223
in a batch compilation” on page 227
under OS/390 UNIX” on page 236
under CMS” on page 246
ADATA
Default is: NOADATA
Abbreviations are: None
Use ADATA when you want the compiler to create a SYSADATA file, which contains
records of additional compilation information. It is required for remote compile
using IBM VisualAge COBOL. On OS/390, this file is written to DDNAME SYSADATA.
On CMS, a file with file type SYSADATA is created. The size of this file generally
grows with the size of the associated program.
You cannot specify ADATA in a PROCESS (CBL) statement; it can be specified only in
one of the following ways:
v On invocation of the compiler using an option list
v On the PARM field of JCL
v As a command option
v As an installation default
RELATED REFERENCES
“Appendix C. EXIT compiler option” on page 575
“Conflicting compiler options” on page 259
ANALYZE
Default is: NOANALYZE
Abbreviations are: None
Use ANALYZE when you want the compiler to check the syntax of embedded SQL
and CICS statements in addition to native COBOL statements.
No executable code is generated when this compiler option is specified, regardless
of the COMPILE|NOCOMPILE setting.
Chapter 16. Compiler options
261
When you specify the ADATA option with this option, you can create a SYSADATA file
for later analysis by program understanding tools.
This option can be set as the installation default option or as a compiler invocation
option, but cannot be set on a CBL or PROCESS statement.
The specification of the ANALYZE option forces the handling of the following
character strings as reserved words:
v CICS
v EXEC
v END-EXEC
v SQL
RELATED REFERENCES
“Conflicting compiler options” on page 259
ADV
Default is: ADV
Abbreviations are: None
ADV has meaning only if you use WRITE . . . ADVANCING in your source code.
With ADV in effect, the compiler adds 1 byte to the record length to account for the
printer control character.
ADV conforms to the COBOL 85 Standard.
Use NOADV if you have already adjusted your record length to include 1 byte for the
printer control character.
ARITH
|
Default is: ARITH(COMPAT)
|
Abbreviations are: AR(C), AR(E)
|
|
|
|
|
|
|
When you specify ARITH(EXTEND):
v The maximum number of digit positions that you can specify in the PICTURE
clause for packed-decimal, zoned-decimal, and numeric-edited data items is
raised from 18 to 31.
v The maximum number of digits that you can specify in a fixed-point numeric
literal is raised from 18 to 31. You can use numeric literals with large precision
anywhere that numeric literals are currently allowed, including:
262
Programming Guide
|
|
|
|
|
|
|
– Operands of PROCEDURE DIVISION statements
– VALUE clauses (on numeric data items with large precision pictures)
– Condition-name values (on numeric data items with large precision pictures)
v The maximum number of digits that you can specify in the arguments to NUMVAL
and NUMVAL-C is raised from 18 to 31.
v The maximum value of the integer argument to the FACTORIAL function is 29.
v Intermediate results in arithmetic statements use extended mode.
|
|
|
|
|
|
|
When you specify ARITH(COMPAT):
v The maximum number of digit positions in the PICTURE clause for
packed-decimal, zoned-decimal, and numeric-edited data items is 18.
v The maximum number of digits in a fixed-point numeric literal is 18.
v The maximum number of digits in the arguments to NUMVAL and NUMVAL-C is 18.
v The maximum value of the integer argument to the FACTORIAL function is 28.
v Intermediate results in arithmetic statements use compatibility mode.
RELATED CONCEPTS
“Appendix A. Intermediate results and arithmetic precision” on page 559
RELATED REFERENCES
“Conflicting compiler options” on page 259
AWO
Default is: NOAWO
Abbreviations are: None
With AWO specified, an implicit APPLY WRITE-ONLY clause is activated for all files in
the program that are eligible for this clause. To be eligible, a file must have
physical sequential organization and blocked variable-length records.
RELATED TASKS
“Optimizing buffer and device space” on page 12
BUFSIZE
Default is: 4096
Abbreviations are: BUF
nnnnn specifies a decimal number that must be at least 256.
nnnK specifies a decimal number in 1K increments.
Chapter 16. Compiler options
263
Use BUFSIZE to allocate an amount of main storage to the buffer for each compiler
work data set (where 1K = 1024 bytes decimal). Usually, a large buffer size
improves the performance of the compiler.
If you use both BUFSIZE and SIZE, the amount allocated to buffers is included in
the amount of main storage available for compilation via the SIZE option.
BUFSIZE cannot exceed the track capacity for the device used, nor can it exceed the
maximum allowed by data management services.
CMPR2
Default is: NOCMPR2
Abbreviations are: None
Use CMPR2 when you want the compiler to generate code that is compatible with
code generated by VS COBOL II Release 2. Valid COBOL source programs that
compiled successfully under VS COBOL II Release 2 also compile successfully
under COBOL for OS/390 & VM with CMPR2 in effect and will provide compatible
results.
The only valid VS COBOL II Release 2 programs that do not compile successfully
under CMPR2 are programs comparing an internal decimal item, a binary item, or
an arithmetic expression to a group item.
Implementation of the COBOL 85 Standard created some instances where
incompatibilities with VS COBOL II Release 2 can occur. Use the CMPR2 and
FLAGMIG options to aid in the migration of programs written for VS COBOL II
Release 2 to COBOL for OS/390 & VM.
NOCMPR2 conforms to the COBOL 85 Standard.
Limited support: In general, new language elements added to IBM COBOL since
VS COBOL II Release 2 are not supported under CMPR2. CMPR2 is intended only as a
migration aid to enable continued use of programs that are written at the VS
COBOL II Release 2 language level.
|
|
|
|
RELATED REFERENCES
“FLAGMIG” on page 275
“Conflicting compiler options” on page 259
Differences between CMPR2 and NOCMPR2 (COBOL for OS/390 & VM Compiler
and Run-Time Migration Guide)
264
Programming Guide
COMPILE
Default is: NOCOMPILE(S)
Abbreviations are: C|NOC
Use the COMPILE option only if you want to force full compilation even in the
presence of serious errors. All diagnostics and object code will be generated. Do
not try to run the object code generated if the compilation resulted in serious
errors—the results could be unpredictable or an abnormal termination could occur.
Use NOCOMPILE without any suboption to request a syntax check (only diagnostics
produced, no object code).
Use NOCOMPILE with W, E, or S for conditional full compilation. Full compilation
(diagnosis and object code) will stop when the compiler finds an error of the level
you specify (or higher), and only syntax checking will continue.
If you request an unconditional NOCOMPILE, the following options have no effect
because no object code will be produced:
v LIST
v SSRANGE
v OPTIMIZE
v OBJECT
v TEST
RELATED REFERENCES
“Messages and listings for compiler-detected errors” on page 231
CURRENCY
Default is: NOCURRENCY
The default currency symbol is the dollar sign ($). You can use the CURRENCY option
to provide an alternate default currency symbol to be used for the COBOL
program.
NOCURRENCY specifies that no alternate default currency symbol will be used.
To change the default currency symbol, use the CURRENCY(literal) option where
literal is a valid COBOL nonnumeric literal (including a hex literal) representing a
single character that must not be any of the following:
v Digits zero (0) through nine (9)
Chapter 16. Compiler options
265
v Uppercase alphabetic characters A B C D E G N P R S V X Z, or their lowercase
equivalents
v The space
v Special characters * + - / , . ; ( ) “ = ’
v A figurative constant
v A null-terminated literal
v A DBCS literal
If your program processes only one currency type, you can use the CURRENCY
option as an alternative to the CURRENCY SIGN clause for selecting the currency
symbol you will use in the PICTURE clause of your program. If your program
processes more than one currency type, you should use the CURRENCY SIGN clause
with the WITH PICTURE SYMBOL phrase to specify the different currency sign types.
If you use both the CURRENCY option and the CURRENCY SIGN clause in a program,
the CURRENCY option is ignored. Currency symbols specified in the CURRENCY SIGN
clause or clauses can be used in PICTURE clauses.
When the NOCURRENCY option is in effect and you omit the CURRENCY SIGN clause,
the dollar sign ($) is used as the PICTURE symbol for the currency sign.
Delimiter note: The CURRENCY option literal can be delimited by either the quote or
the apostrophe, regardless of the QUOTE|APOST compiler option setting.
If you plan to specify the CURRENCY compiler option in the COBOL2 command under
CMS, see the special usage notes under Specifying compiler options using the
COBOL2 command in the related information below.
RELATED TASKS
“Specifying compiler options under CMS” on page 246
“Conflicting compiler options” on page 259
DATA
Default is: DATA(31)
Abbreviations are: None
Language Environment provides services that control the storage used at run time.
IBM COBOL for OS/390 & VM uses these services for all storage requests
For reentrant programs, the DATA(24|31) compiler option and the HEAP run-time
option control whether storage for dynamic data areas (such as WORKING-STORAGE
section and FD record areas) is obtained from below the 16-MB line or from
unrestricted storage. (The DATA option does not affect the location of LOCAL-STORAGE
section variables; the STACK run-time option controls that location instead.)
When you specify the run-time option HEAP(BELOW), the DATA(24|31) compiler
option has no effect; the storage for all dynamic data areas is allocated from below
the 16-MB line. However, with HEAP(ANYWHERE) as the run-time option, storage for
266
Programming Guide
dynamic data areas is allocated from below the line if you compiled the program
with the DATA(24) compiler option or from unrestricted storage if you compiled
with the DATA(31) compiler option.
Specify the DATA(24) compiler option for programs running in 31-bit addressing
mode that are passing data parameters to programs in 24-bit addressing mode.
This ensures that the data will be addressable by the called program.
External data
In addition to affecting how storage is obtained for dynamic data areas, the
DATA(24|31) compiler option can also influence where storage for external data is
obtained. Storage required for external data will be obtained from unrestricted
storage if the following conditions are met:
v The program is compiled with the DATA(31) compiler option.
v The HEAP(ANYWHERE) run-time option is in effect.
v The ALL31(ON) run-time option is in effect.
In all other cases, the storage for external data will be obtained from below the
16-MB line. To specify the ALL31(ON) run-time option, all the programs in the run
unit must be capable of running in 31-bit addressing mode.
QSAM input/output buffers
On an OS/390 system, the DATA(24|31) compiler option can also influence where
input/output buffers for QSAM files are obtained for reentrant programs. Storage
required for a QSAM file’s buffers will be acquired from unrestricted storage if the
following conditions are met:
v The program is compiled with the DATA(31) and RENT compiler options or the
program is compiled with the RMODE(ANY) and NORENT compiler options.
v The program is running in AMODE 31.
v The file is eligible for buffer allocation above the 16-MB line.
v If the file is an EXTERNAL file, the ALL31(ON) run-time option is in effect.
In all other cases, the storage for the QSAM file’s buffers will be obtained from
below the 16-MB line. To specify the ALL31(ON) run-time option, all the programs
in the run unit must be capable of running in 31-bit addressing mode.
RELATED TASKS
Using run-time options (Language Environment Programming Guide)
RELATED REFERENCES
“Allocation of buffers for QSAM files” on page 127
DATEPROC
Default is: NODATEPROC, or DATEPROC(FLAG,NOTRIG) if only DATEPROC is specified
Abbreviations are: DP|NODP
Chapter 16. Compiler options
267
Use the DATEPROC option to enable the millennium language extensions of the
COBOL compiler.
DATEPROC(FLAG)
With DATEPROC(FLAG), the millennium language extensions are enabled, and
the compiler produces a diagnostic message wherever a language element
uses or is affected by the extensions. The message is usually an
information-level or warning-level message that identifies statements that
involve date-sensitive processing. Additional messages that identify errors
or possible inconsistencies in the date constructs might be generated.
Production of diagnostic messages, and their appearance in or after the
source listing, is subject to the setting of the FLAG compiler option.
DATEPROC(NOFLAG)
With DATEPROC(NOFLAG), the millennium language extensions are in effect,
but the compiler does not produce any related messages unless there are
errors or inconsistencies in the COBOL source.
DATEPROC(TRIG)
With DATEPROC(TRIG), the millennium language extensions are enabled, and
the automatic windowing that the compiler applies to operations on
windowed date fields is sensitive to specific trigger or limit values in the
date fields and in other nondate fields that are stored into or compared
with the windowed date fields. These special values represent invalid dates
that can be tested for or used as upper or lower limits.
Performance: The DATEPROC(TRIG) option results in slower-performing code
for windowed date comparisons.
DATEPROC(NOTRIG)
With DATEPROC(NOTRIG), the millennium language extensions are enabled,
and the automatic windowing that the compiler applies to operations on
windowed dates does not recognize any special trigger values in the
operands. Only the value of the year part of dates is relevant to automatic
windowing.
Performance: The DATEPROC(NOTRIG) option is a performance option that
assumes valid date values in windowed date fields.
NODATEPROC
NODATEPROC indicates that the extensions are not enabled for this
compilation unit. This affects date-related program constructs as follows:
v The DATE FORMAT clause is syntax-checked, but has no effect on the
execution of the program.
v The DATEVAL and UNDATE intrinsic functions have no effect. That is, the
value returned by the intrinsic function is exactly the same as the value
of the argument.
v The YEARWINDOW intrinsic function returns a value of zero.
Notes:
1. NODATEPROC conforms to the COBOL 85 Standard.
2. You can specify the FLAG|NOFLAG and TRIG|NOTRIG suboptions in any order. If
you omit either suboption, it defaults to the current setting.
RELATED REFERENCES
“FLAG” on page 274
“Conflicting compiler options” on page 259
268
Programming Guide
DBCS
Default is: NODBCS
Abbreviations are: None
Using DBCS causes the compiler to recognize X’0E’ (SO) and X’0F’ (SI) as shift
codes for the double-byte portion of a nonnumeric literal.
With DBCS selected, the double-byte portion of the literal is syntax-checked and the
literal remains category alphanumeric.
NODBCS conforms to the COBOL 85 Standard.
RELATED REFERENCES
“Conflicting compiler options” on page 259
DECK
Default is: NODECK
Abbreviations are: D|NOD
Use DECK to produce object code in the form of 80-column card images. If you use
the DECK option, be certain that SYSPUNCH is defined in your JCL for compilation.
DIAGTRUNC
|
Default is: NODIAGTRUNC
|
Abbreviations are: DTR, NODTR
|
|
|
|
|
DIAGTRUNC causes the compiler to issue a severity-4 (Warning) diagnostic message
for MOVE statements with numeric receivers when the receiving data item has fewer
integer positions than the sending data item or literal. In statements with multiple
receivers, the message is issued separately for each receiver that could be
truncated.
|
|
|
The diagnostic message is also issued for implicit moves associated with
statements such as these:
v INITIALIZE
Chapter 16. Compiler options
269
|
|
|
|
|
v
v
v
v
v
READ . . . INTO
RELEASE . . . FROM
RETURN . . . INTO
REWRITE . . . FROM
WRITE . . . FROM
|
|
The diagnostic is also issued for moves to numeric receivers from alphanumeric
data-names or literal senders, except when the sending field is reference-modified.
|
|
There is no diagnostic for COMP-5 receivers, nor for binary receivers when you
specify the TRUNC(BIN) option.
RELATED CONCEPTS
“Formats for numeric data” on page 36
“Reference modifiers” on page 87
RELATED REFERENCES
“TRUNC” on page 297
“Conflicting compiler options” on page 259
DISK/PRINT
The DISK and PRINT|NOPRINT compiler options are unique to COBOL under CMS.
RELATED REFERENCES
“Additional compiler options under CMS” on page 247
DLL
Default is: NODLL
Abbreviations are: None
Execution of programs compiled with the DLL option is allowed only under
OS/390. You can specify the DLL option when compiling under VM/CMS, but the
resulting application object modules must be moved to OS/390 for linking and for
execution.
|
|
|
|
Use DLL to instruct the compiler to generate an object module that is enabled for
dynamic link library (DLL) support. DLL enablement is required if the program
will be part of a DLL, will reference DLLs, or if the program contains
object-oriented COBOL syntax such as INVOKE statements, class definitions, or calls
to SOMobjects API functions.
Specification of the DLL option requires that the RENT linkage editor option also be
used.
NODLL instructs the compiler to generate an object module that is not enabled for
DLL usage.
270
Programming Guide
RELATED REFERENCES
“Conflicting compiler options” on page 259
DUMP
Default is: NODUMP
Abbreviations are: DU|NODU
Not general: This option is not intended for general use.
Use DUMP to produce a system dump at compile time for an internal compiler error.
Under CMS, this option specifies that there is to be an abend at the point of
failure, but no output is produced. The DUMP option should only be used at the
request of an IBM representative.
The dump, which consists of a listing of the compiler’s registers and a storage
dump, is intended primarily for diagnostic personnel for determining errors in the
compiler.
If you use the DUMP option, include a DD statement at compile time to define
SYSABEND, SYSUDUMP, or SYSMDUMP.
With DUMP, the compiler will not issue a diagnostic message before abnormal
termination processing. Instead, a user abend will be issued with an IGYppnnnn
message. In general, a message IGYppnnnn corresponds to a compile-time user
abend nnnn. However, both IGYpp5nnn and IGYpp1nnn messages produce a user
abend of 1nnn. You can usually distinguish whether the message is really a 5nnn or
a 1nnn by recompiling with the NODUMP option.
Use NODUMP if you want normal termination processing, including:
v
v
v
v
Diagnostic messages produced so far in compilation
A description of the error
The name of the compiler phase currently executing
The line number of the COBOL statement being processed when the error was
found (if you have compiled with OPTIMIZE, the line number might not always
be correct; for some errors, it will be the last line in the program)
v The contents of the general purpose registers
Using the DUMP and OPTIMIZE compiler options together could cause the compiler to
produce a system dump instead of the following optimizer message:
“IGYOP3124-W
This statement may cause a program exception at
execution time.”
This situation is not a compiler error. Using the NODUMP option will allow the
compiler to issue message IGYOP3124-W and continue processing.
RELATED TASKS
Understanding abend codes (Language Environment Debugging Guide and Run-Time
Messages)
Chapter 16. Compiler options
271
RELATED REFERENCES
“Conflicting compiler options” on page 259
DYNAM
Default is: NODYNAM
Abbreviations are: DYN|NODYN
Use DYNAM to cause nonnested, separately compiled programs invoked through the
CALL literal statement to be loaded (for CALL) and deleted (for CANCEL) dynamically
at run time. Any CALL identifier statements that cannot be resolved in your program
are also handled as dynamic calls. The DYNAM compiler option must not be used by
programs that are translated by the CICS translator.
If your COBOL program calls programs that have been linked as dynamic link
libraries (DLLs), then you must not use the DYNAM option. You must instead
compile the program with the NODYNAM and DLL options. In particular, if your
program calls SOMobjects API functions, then you must compile it with NODYNAM
and DLL.
DYNAM conforms to the COBOL 85 Standard.
RELATED REFERENCES
“Making both static and dynamic calls” on page 465
“Conflicting compiler options” on page 259
EXIT
For information on the EXIT compiler option, see the first reference below.
RELATED REFERENCES
“Appendix C. EXIT compiler option” on page 575
“Conflicting compiler options” on page 259
EXPORTALL
Default is: NOEXPORTALL
Abbreviations are: EXP|NOEXP
Execution of programs compiled with the EXPORTALL option is only allowed under
OS/390. You can specify the EXPORTALL option when compiling under VM/CMS,
but you must move the resulting application object modules to OS/390 for linking
and for execution.
|
|
|
|
272
Programming Guide
Use EXPORTALL to instruct the compiler to automatically export the following
symbols when the object deck is link-edited to form a DLL:
v From each program definition, export the PROGRAM-ID name and each alternate
entry point name.
v From each class definition, export the external SOM symbols needed to bind to
the class when it is a DLL, namely:
– <classname>NewClass
– <classname>ClassData
– <classname>CClassData
With these symbols exported from the DLL:
v The exported program and entry point names can be called from programs in
the root load module or in other DLL load modules in the application, as well as
from programs that are linked into the same DLL.
v The methods in the classes can be invoked from programs in the root load
module or in other DLL load modules in the application, as well as from
programs that are linked into the same DLL.
Specification of the EXPORTALL option requires that the RENT linkage editor option is
also used.
NOEXPORTALL instructs the compiler to not export any symbols. In this case the
programs and class definitions are only accessible from other routines that are
link-edited into the same load module together with this COBOL class or program
definition.
RELATED REFERENCES
“Conflicting compiler options” on page 259
FASTSRT
Default is: NOFASTSRT
Abbreviations are: FSRT|NOFSRT
FASTSRT allows IBM DFSORT, or its equivalent, to perform the input and output
instead of COBOL.
NOFASTSRT conforms to the COBOL 85 Standard
RELATED TASKS
“Improving sort performance with FASTSRT” on page 181
Chapter 16. Compiler options
273
FLAG
Default is: FLAG(I)
Abbreviations are: F|NOF
x and y can be either I, W, E, S, or U.
Use FLAG(x) to produce diagnostic messages for errors of a severity level x or above
at the end of the source listing.
Use FLAG(x,y) to produce diagnostic messages for errors of severity level x or above
at the end of the source listing, with error messages of severity y and above to be
embedded directly in the source listing. The severity coded for y must not be
lower than the severity coded for x. To use FLAG(x,y), you must also specify the
SOURCE compiler option.
Error messages in the source listing are set off by embedding the statement
number in an arrow that points to the message code. The message code is then
followed by the message text. For example:
000413
==000413==>
MOVE CORR WS-DATE TO HEADER-DATE
IGYPS2121-S
“ WS-DATE ” was not defined as a data-name.
. . .
With FLAG(x,y) selected, messages of severity y and above will be embedded in the
listing following the line that caused the message. (Refer to the notes below for
exceptions.)
Use NOFLAG to suppress error flagging. NOFLAG will not suppress error messages for
compiler options.
Embedded messages:
1. Specifying embedded level-U messages is accepted, but will not produce any
messages in the source. Embedding a level-U message is not recommended.
2. The FLAG option does not affect diagnostic messages produced before the
compiler options are processed.
3. Diagnostic messages produced during processing of compiler options, CBL and
PROCESS statements, or BASIS, COPY, and REPLACE statements, are never
embedded in the source listing. All such messages appear at the beginning of
the compiler output.
4. Messages produced during processing of the *CONTROL (*CBL) statement are not
embedded in the source listing.
RELATED REFERENCES
“Messages and listings for compiler-detected errors” on page 231
274
Programming Guide
FLAGMIG
Default is: NOFLAGMIG
Abbreviations are: None
Use FLAGMIG to identify language elements that might be implemented differently
in VS COBOL II Release 2 than in COBOL for OS/390 & VM.
NOFLAGMIG conforms to the COBOL 85 Standard.
Implementation of the COBOL 85 Standard created some instances where
incompatibilities with VS COBOL II Release 2 can occur. Using the CMPR2 and
FLAGMIG options aids in the migration of programs written for VS COBOL II
Release 2 to COBOL for OS/390 & VM.
RELATED REFERENCES
“Conflicting compiler options” on page 259
CMPR2, FLAGMIG, and NOCOMPILE compiler options (COBOL for OS/390 & VM
Compiler and Run-Time Migration Guide)
FLAGSTD
Default is: NOFLAGSTD
x specifies the level or subset of COBOL 85 Standard to be regarded as conforming:
M
Language elements that are not from the minimum subset are to be flagged
as “nonconforming standard.”
I
Language elements that are not from the minimum or the intermediate
subset are to be flagged as “nonconforming standard.”
H
The high subset is being used and elements will not be flagged by subset.
And, elements in the IBM extension category will be flagged as
“nonconforming Standard, IBM extension.”
yy specifies, by a single character or combination of any two, the optional modules
to be included in the subset:
D
Elements from Debug module level 1 are not flagged as “nonconforming
standard.”
N
Elements from Segmentation module level 1 are not flagged as
“nonconforming standard.”
S
Elements from Segmentation module level 2 are not flagged as
“nonconforming standard.”
Chapter 16. Compiler options
275
If S is specified, N is included (N is a subset of S).
O specifies that obsolete language elements are flagged as “obsolete.”
Use FLAGSTD to get informational messages about the COBOL 85 Standard elements
included in your program. You can specify any of the following items for flagging:
v
v
v
v
v
v
A selected Federal Information Processing Standard (FIPS) COBOL subset
Any of the optional modules
Obsolete language elements
Any combination of subset and optional modules
Any combination of subset and obsolete elements
IBM extensions (these are flagged any time FLAGSTD is specified and are
identified as “nonconforming nonstandard”)
The informational messages appear in the source program listing and contain the
following information:
v Identify the element as “obsolete,” “nonconforming standard,” or
“nonconforming nonstandard” (a language element that is both obsolete and
nonconforming is flagged as obsolete only).
v Identify the clause, statement, or header that contains the element.
v Identify the source program line and beginning location of the clause, statement,
or header that contains the element.
v Identify the subset or optional module to which the element belongs.
FLAGSTD requires the standard set of reserved words.
In the following example, the line number and column where a flagged clause,
statement, or header occurred are shown, as well as the message code and text. At
the bottom is a summary of the total of the flagged items and their type.
LINE.COL CODE
FIPS MESSAGE TEXT
IGYDS8211
Comment lines before “IDENTIFICATION DIVISION”:
nonconforming nonstandard, IBM extension to
ANS/ISO 1985.
11.14
IGYDS8111
“GLOBAL clause”: nonconforming standard, ANS/ISO
1985 high subset.
59.12
IGYPS8169
“USE FOR DEBUGGING statement”:
in ANS/ISO 1985.
FIPS MESSAGES TOTAL
3
STANDARD
1
RELATED REFERENCES
“Conflicting compiler options” on page 259
276
Programming Guide
obsolete element
NONSTANDARD
1
OBSOLETE
1
IDLGEN
Default is: NOIDLGEN
Abbreviations are: IDL|NOIDL
OS/390 only: This option is not supported under VM/CMS.
Use the IDLGEN option to indicate whether SOM Interface Definition Language
(IDL) should be generated for COBOL class definitions contained in the COBOL
source file.
Use IDLGEN to request that in addition to the compile of the COBOL source file,
IDL definitions for classes defined in the file be generated.
Use NOIDLGEN to request that no IDL definitions be generated.
The IDL is written to the data set specified on the SYSIDL DD statement, which
must be included in the JCL for the compilation. The data set name on the SYSIDL
DD statement must specify a member of a partitioned data set (PDS) that has fixed
or fixed-blocked records (RECFM=F or RECFM=FB) and a record length (LRECL) of
between 80 and 255 characters. The default record length is 255 characters. IDL
does not support continuation characters, so if a line output by the compiler is
longer than the LRECL of the IDL output data set, the line is truncated. This could
occur if the class uses very long names for methods or the external class-name, and
the LRECL of the IDL output data set is too short. A record length of 255 is
recommended, since IDL created by COBOL compiler will always fit in
255-character lines.
When a class definition includes references to other classes (such as on the
INHERITS or METACLASS IS phrases, or typed object references as method
parameters) defined in separate source files, the generated IDL contains include
statements for the IDL files of the referenced classes. The COBOL compiler
attempts to obtain the file name (referred to as the filestem in the SOM
documentation) for a referenced class from the SOM interface repository (IR). If the
referenced class does not have an IR entry, the external class-name of the
referenced class is assumed as the filestem. An include is then generated of the
form: #include <filestem..idl>. This might be adequate for classes with external
class-names formed with eight or fewer characters, but if long external class-names
are used, the IR entry is essential to enable the COBOL compiler to obtain the
eight-character (or less) PDS member name to include.
When a COBOL source file contains more than one class definition (batch compile)
and you use the IDLGEN option, the COBOL class definitions must be sequenced in
an appropriate order within the source file. The generated IDL for such a batch
compile contains multiple class interfaces with the IDL interfaces in the same order
as the COBOL classes were defined in the COBOL source file. The SOM IDL
compiler requires that interfaces be defined before they are referenced. So if there
are references between the classes in the COBOL batch compile, the referenced
classes must precede the referencing classes in the COBOL source file.
Chapter 16. Compiler options
277
The mapping of COBOL to IDL is designed to balance two conflicting objectives,
namely enablement of object-oriented COBOL type checking and enabling COBOL
classes to operate with other SOM-based programming languages. At a high level:
v COBOL classes map to IDL interfaces.
v COBOL methods map to IDL operation declarations.
v Where possible, the data types of COBOL method parameters are mapped to
corresponding native IDL types. These cases include binary integer, floating
point, pointer, object reference, and character types.
All elementary USAGE DISPLAY types and fixed-length COBOL groups are
mapped to IDL as array of character.
Remaining COBOL types that do not naturally map to any native IDL data type
are mapped to COBOL-specific “foreign” IDL types. These cases include
packed-decimal, scaled binary, DBCS, and variable-length groups.
v Method formal parameters that specify BY REFERENCE on the method PROCEDURE
DIVISION header are given the IDL parameter attribute inout and parameters that
specify BY VALUE are given the IDL parameter attribute in.
The IDL generated for the same class by the IBM COBOL compiler on OS/390,
Windows, and AIX might differ; therefore you should regenerate the IDL for the
target platform rather than port it between platforms. For example, the
procedure-pointer data type in COBOL for OS/390 & VM is an 8-byte data item
that does not map to any native IDL type, hence a COBOL-specific mapping is
used. On Windows and AIX, procedure-pointers are 4-byte data items that map to
IDL pointers. Another example is that on OS/390 or AIX, a PIC S9(8) BINARY data
item maps naturally to an IDL long type, whereas on Windows, the same data
item could map either to an IDL long or to a COBOL-specific data type that
emulates System/390 binary format, depending on the compilation options used.
Do not use SIZE(MAX) when you are compiling large object-oriented applications
with the IDLGEN option. You must leave storage space in the user region for
Interface Repository data.
RELATED TASKS
“Chapter 24. Writing object-oriented programs” on page 375
“Chapter 26. Using SOM IDL-based class libraries” on page 425
OS/390 SOMobjects Programmer’s Guide
RELATED REFERENCES
“Conflicting compiler options” on page 259
INTDATE
Default is: INTDATE(ANSI)
INTDATE(ANSI) instructs the compiler to use the ANSI COBOL Standard starting
date for integer dates used with date intrinsic functions. Day 1 is Jan 1, 1601.
With INTDATE(ANSI), the date intrinsic functions return the same results as in
COBOL/370 Release 1.
278
Programming Guide
INTDATE(LILIAN) instructs the compiler to use the Language Environment Lilian
starting date for integer dates used with date intrinsic functions. Day 1 is Oct 15,
1582.
With INTDATE(LILIAN), the date intrinsic functions return results compatible with
the Language Environment date callable services. These results will be different
than in COBOL/370 Release 1.
Usage notes:
1. When INTDATE(LILIAN) is in effect, CEECBLDY is not usable since you have no
way to turn an ANSI integer into a meaningful date using either intrinsic
functions or callable services. If you code a CALL literal statement with
CEECBLDY as the target of the call with INTDATE(LILIAN) in effect, the
compiler diagnoses this and converts the call target to CEEDAYS.
2. If your installation default is INTDATE(LILIAN), you should recompile all of your
COBOL/370 Release 1 programs that use intrinsic functions to ensure that all of
your code uses the Lilian integer date standard. This method is the safest,
because you can store integer dates and pass them between programs, even
between PL/I, COBOL, and C programs, and know that the date processing
will be consistent.
RELATED REFERENCES
“Conflicting compiler options” on page 259
LANGUAGE
Default is: LANGUAGE(ENGLISH)
Abbreviations are: LANG(EN|UE|JA|JP)
Use the LANGUAGE option to select the language in which compiler output will be
printed. The information that will be printed in the selected language includes
diagnostic messages, source listing page and scale headers, FIPS message headers,
message summary headers, compilation summary, and headers and notations that
result from the selection of certain compiler options (MAP, XREF, VBREF, and
FLAGSTD).
name specifies the language for compiler output messages. Possible values for the
LANGUAGE option are shown in the table.
Name
Abbreviation1
Output language
ENGLISH
EN
Mixed-case English (the default)
JAPANESE
JA, JP
Japanese, using the Japanese character set
UENGLISH
UE
Uppercase English
2
1. If your installation’s system programmer has provided a language other than those
described, you must specify at least the first two characters of this other language’s
name.
2. To specify a language other than UENGLISH, the appropriate language feature must be
installed.
Chapter 16. Compiler options
279
If the LANGUAGE option is changed at compile time (using CBL or PROCESS
statements), some initial text will be printed using the language that was in effect
at the time the compiler was started.
NATLANG: The NATLANG run-time option allows you to control the national language
to be used for the run-time environment, including error messages, month names,
and day-of-the-week names. The LANGUAGE compiler option and the NATLANG
run-time option act independently of each other. You can use them together with
neither taking precedence over the other.
LIB
Default is: LIB
Abbreviations are: None
If your program uses COPY, BASIS, or REPLACE statements, you need to specify the
LIB compiler option. In addition, for COPY and BASIS statements, you need to define
the library or libraries from which the compiler can take the copied code. Define
the libraries with DD statements, ALLOCATE commands, environment variables, or
FILEDEF commands as appropriate for your environment. When using JCL, also
include a DD statement to allocate SYSUT5.
|
|
|
|
LIB conforms to the COBOL 85 Standard.
RELATED REFERENCES
“Compiler-directing statements” on page 304
“Conflicting compiler options” on page 259
LINECOUNT
Default is: LINECOUNT(60)
Abbreviations are: LC
nnn must be an integer between 10 and 255, or 0.
Use LINECOUNT(nnn) to specify the number of lines to be printed on each page of
the compilation listing, or use LINECOUNT(0) to suppress pagination.
If you specify LINECOUNT(0), no page ejects are generated in the compilation listing.
The compiler uses three lines of nnn for titles. For example, if you specify
LINECOUNT(60), 57 lines of source code are printed on each page of the output
listing.
280
Programming Guide
LIST
Default is: NOLIST
Abbreviations are: None
Use the LIST compiler option to produce a listing of the assembler-language
expansion of your source code.
You will also get these in your output listing:
v Global tables
v Literal pools
v Information about WORKING-STORAGE
v Size of the program’s WORKING-STORAGE and its location in the object code if the
program is compiled with the NORENT option
The output is generated if:
v You specify the COMPILE option (or the NOCOMPILE(x) option is in effect and an
error level x or higher does not occur).
v You do not specify the OFFSET option.
If you want to limit the assembler listing output, use *CONTROL LIST or NOLIST
statements in your PROCEDURE DIVISION. Your source statements following a
*CONTROL NOLIST are not included in the listing until a *CONTROL LIST statement
switches the output back to normal LIST format.
RELATED TASKS
“Getting listings” on page 319
RELATED REFERENCES
“Conflicting compiler options” on page 259
*CONTROL (*CBL) statement (IBM COBOL Language Reference)
MAP
Default is: NOMAP
Abbreviations are: None
Use the MAP compiler option to produce a listing of the items you defined in the
DATA DIVISION. The output includes the following:
v DATA DIVISION map
v Global tables
v Literal pools
v Nested program structure map, and program attributes
Chapter 16. Compiler options
281
v Size of the program’s WORKING-STORAGE and its location in the object code if the
program is compiled with the NORENT option
If you want to limit the MAP output, use *CONTROL MAP or NOMAP statements in the
DATA DIVISION. Source statements following a *CONTROL NOMAP are not included in
the listing until a *CONTROL MAP statement switches the output back to normal MAP
format. For example:
*CONTROL NOMAP
01 A
02 B
*CONTROL MAP
*CBL NOMAP
01 A
02 B
*CBL MAP
By selecting the MAP option, you can also print an embedded MAP report in the
source code listing. The condensed MAP information is printed to the right of
data-name definitions in the FILE SECTION, WORKING-STORAGE SECTION, and LINKAGE
SECTION of the DATA DIVISION. When both XREF data and an embedded MAP
summary are on the same line, the embedded summary is printed first.
“Example: MAP output” on page 324
RELATED CONCEPTS
“Chapter 17. Debugging” on page 309
RELATED TASKS
“Getting listings” on page 319
RELATED REFERENCES
*CONTROL (*CBL) statement (IBM COBOL Language Reference)
NAME
Default is: NONAME, or NAME(NOALIAS) if only NAME is specified
Abbreviations are: None
Use NAME to generate a link-edit NAME card for each object module. NAME is also used
to generate names for each load module when doing batch compilations. When
NAME is specified, a NAME card is appended to each object module that is created.
Load module names are formed using the rules for forming module names from
PROGRAM-ID statements.
If you specify NAME(ALIAS) and if your program contains ENTRY statements, a
link-edit ALIAS card is generated for each ENTRY statement.
The NAME or NAME(ALIAS) options cannot be used when compiling programs that
will be prelinked with the Language Environment prelinker.
RELATED REFERENCES
PROGRAM-ID paragraph (IBM COBOL Language Reference)
282
Programming Guide
NUMBER
Default is: NONUMBER
Abbreviations are: NUM|NONUM
Use the NUMBER compiler option if you have line numbers in your source code and
want those numbers to be used in error messages and SOURCE, MAP, LIST, and XREF
listings.
If you request NUMBER, the compiler checks columns 1 through 6 to make sure that
they contain only numbers and that the numbers are in numeric collating
sequence. (In contrast, SEQUENCE checks the characters in these columns according
to EBCDIC collating sequence.) When a line number is found to be out of
sequence, the compiler assigns to it a line number with a value one higher than the
line number of the preceding statement. The compiler flags the new value with
two asterisks and includes in the listing a message indicating an out-of-sequence
error. Sequence-checking continues with the next statement, based on the newly
assigned value of the previous line.
If you use COPY statements and NUMBER is in effect, be sure that your source
program line numbers and the COPY member line numbers are coordinated.
If you are doing a batch compilation and LIB and NUMBER are in effect, all programs
in the batch compile will be treated as a single input file. The sequence numbers of
the entire input file must be in ascending order.
Use NONUMBER if you do not have line numbers in your source code, or if you want
the compiler to ignore the line numbers you do have in your source code. With
NONUMBER in effect, the compiler generates line numbers for your source statements
and uses those numbers as references in listings.
NONUMBER conforms to the COBOL 85 Standard.
NUMPROC
Default is: NUMPROC(NOPFD)
Abbreviations are: None
Use NUMPROC(NOPFD) if you want the compiler to perform invalid sign processing.
This option is not as efficient as NUMPROC(PFD); object code size will be increased,
and there could be an increase in run-time overhead to validate all signed data.
NUMPROC(NOPFD) and NUMPROC(MIG) conform to the COBOL 85 Standard.
Chapter 16. Compiler options
283
NUMPROC(PFD) is a performance option that can be used to bypass invalid sign
processing. Use this option only if your program data agrees exactly with the
following IBM system standards:
External decimal, unsigned: High-order 4 bits of the sign byte contain X’F’.
External decimal, signed overpunch: High-order 4 bits of the sign byte contain
X’C’ if the number is positive or 0, X’D’ if it is not.
External decimal, separate sign: Separate sign contains the character ’+’ if the
number is positive or 0, ’-’ if it is not.
Internal decimal, unsigned: Low-order 4 bits of the low-order byte contain X’F’.
Internal decimal, signed: Low-order 4 bits of the low-order byte contain X’C’ if the
number is positive or 0, X’D’ if it is not.
Data produced by COBOL arithmetic statements conforms to the above IBM
system standards. However, using REDEFINES and group moves could change data
so that it no longer conforms. If you use NUMPROC(PFD), use the INITIALIZE
statement to initialize data fields, rather than using group moves.
Using NUMPROC(PFD) can affect class tests for numeric data. You should use
NUMPROC(NOPFD) or NUMPROC(MIG) if a COBOL program calls programs written in
PL/I or FORTRAN.
Sign representation is not only affected by the NUMPROC option, but also by the
installation time option NUMCLS.
Use NUMPROC(MIG) to aid in migrating OS/VS COBOL programs to IBM COBOL for
OS/390 & VM. When NUMPROC(MIG) is in effect, the following processing occurs:
v Preferred signs are created only on the output of MOVE statements and arithmetic
operations.
v No explicit sign repair is done on input.
v Some implicit sign repair might occur during conversion.
v Numeric comparisons are performed by a decimal compare, not a logical
compare.
RELATED TASKS
“Checking for incompatible data (numeric class test)” on page 42
RELATED REFERENCES
“Sign representation and processing” on page 41
OBJECT
Default is: OBJECT
Abbreviations are: OBJ|NOOBJ
284
Programming Guide
Use OBJECT to place the generated object code on disk or tape to be later used as
input for the linkage editor.
If you specify OBJECT, include a SYSLIN DD statement in your JCL for compilation.
The only difference between DECK and OBJECT is in the routing of the data sets:
v DECK output goes to the data set associated with ddname SYSPUNCH.
v OBJECT output goes to the data set associated with ddname SYSLIN.
Use the option your installation guidelines recommend.
RELATED REFERENCES
“Conflicting compiler options” on page 259
OFFSET
Default is: NOOFFSET
Abbreviations are: OFF|NOOFF
Use OFFSET to produce a condensed PROCEDURE DIVISION listing. With OFFSET, the
condensed PROCEDURE DIVISION listing will contain line numbers, statement
references, and the location of the first instruction generated for each statement. In
addition, the following are produced:
v Global tables.
v Literal pools.
v Size of the program’s WORKING-STORAGE, and its location in the object code if the
program is compiled with the NORENT option.
RELATED REFERENCES
“Conflicting compiler options” on page 259
OPTIMIZE
Default is: NOOPTIMIZE
Abbreviations are: OPT|NOOPT
Use OPTIMIZE to reduce the run time of your object program; optimization might
also reduce the amount of storage your object program uses. Because OPTIMIZE
increases compile time, and can change the order of statements in your program, it
should not be used when debugging.
If OPTIMIZE is specified without any suboptions, OPTIMIZE(STD) will be in effect.
Chapter 16. Compiler options
285
The FULL suboption requests that, in addition to the optimizations performed
under OPT(STD), the compiler discard unreferenced data items from the DATA
DIVISION and suppress generation of code to initialize these data items to their
VALUE clauses. When OPT(FULL)is in effect, all unreferenced 77-level items and
elementary 01-level items will be discarded. In addition, 01-level group items will
be discarded, if none of the subordinate items are referenced. The deleted items are
shown in the listing. If the MAP option is in effect, a BL number of XXXX in the data
map information indicates that the data item was discarded.
Unused data items:
Do not use OPT(FULL) if your programs depend on making use of unused data
items. Two common ways this has been done in the past are:
1. A technique sometimes used in OS/VS COBOL programs is to place an
unreferenced table after a referenced table and use out-of-range subscripts on
the first table to access the second table. To see if your programs have this
problem, use the SSRANGE compiler option with the CHECK(ON) run-time option.
To work around this problem, use the ability of COBOL to code large tables
and use just one table.
2. The second technique utilizing unused data items is to place eyecatcher data
items in the WORKING-STORAGE section to identify the beginning and end of the
program data, or to mark a copy of a program for a library tool that uses the
data to identify a version of a program. To solve this problem, initialize these
items with PROCEDURE DIVISION statements rather than VALUE clauses. With this
method, the compiler will consider these items as used, and will not delete
them.
The OPTIMIZE option is turned off in the case of a severe-level error or higher.
RELATED CONCEPTS
“Optimization” on page 542
RELATED REFERENCES
“Conflicting compiler options” on page 259
OUTDD
Default is: OUTDD(SYSOUT)
Abbreviations are: OUT
Use OUTDD to specify that you want DISPLAY output that is directed to the system
logical output device to go to a specific ddname. Note that you can specify a file in
the hierarchical file system (HFS) with the ddname named in OUTDD. See the
discussion of the DISPLAY statement for defaults and for behavior when this
ddname is not allocated.
|
|
|
|
The MSGFILE run-time option allows you to specify the ddname of the file to which
all run-time diagnostics and reports generated by the RPTOPTS and RPTSTG run-time
options are written. The IBM-supplied default is MSGFILE(SYSOUT). If the OUTDD
compiler option and the MSGFILE run-time option both specify the same ddname,
286
Programming Guide
the error message information and DISPLAY output directed to the system logical
output device are routed to the same destination.
RELATED TASKS
“Displaying values on a screen or in a file (DISPLAY)” on page 29
RELATED REFERENCES
MSGFILE (Language Environment Programming Reference)
PGMNAME
Default is: PGMNAME(COMPAT)
Abbreviations are: PGMN(LM|LU|CO)
LONGUPPER can be abbreviated as UPPER, LU, or U. LONGMIXED can be abbreviated as
MIXED, LM, or M.
The PGMNAME option controls the handling of names used in the following contexts:
v Program names defined in the PROGRAM-ID paragraph
v Program entry point names on the ENTRY statement
v Program name references in:
– Calls to nested programs
– Static calls to separately compiled programs
– Static SET procedure-pointer TO ENTRY literal statement
– CANCEL of a nested program
PGMNAME(COMPAT)
With PGMNAME(COMPAT), program names are handled in a manner compatible with
COBOL/370 Release 1, namely:
v The program name can be up to 30 characters in length.
v All the characters used in the name must be alphabetic, digits, or the hyphen,
except that if the program name is entered in the literal format and is in the
outermost program, then the literal can also contain the extension characters @,
#, and $.
v At least one character must be alphabetic.
v The hyphen cannot be used as the first or last character.
External program names are processed by the compiler as follows:
v They are folded to uppercase.
v They are truncated to eight characters.
v Hyphens are translated to zero (0).
v If the first character is not alphabetic, it is converted as follows:
– 1-9 are translated to A-J.
– Anything else is translated to J.
Chapter 16. Compiler options
287
PGMNAME(LONGUPPER)
With PGMNAME(LONGUPPER), program names that are specified in the PROGRAM-ID
paragraph as COBOL user-defined words must follow the normal COBOL rules for
forming a user-defined word:
v
v
v
v
The program name can be up to 30 characters in length.
All the characters used in the name must be alphabetic, digits, or the hyphen.
At least one character must be alphabetic.
The hyphen cannot be used as the first or last character.
When a program or method name is specified as a literal, in either a definition or a
reference, then:
v The program name can be up to 160 characters in length.
v All the characters used in the name must be alphabetic, digits, or the hyphen.
v At least one character must be alphabetic.
v The hyphen cannot be used as the first or last character.
External program names are processed by the compiler as follows:
v They are folded to uppercase.
v Hyphens are translated to zero (0).
v If the first character is not alphabetic, it is converted as follows:
– 1-9 are translated to A-J.
– Anything else is translated to J.
Nested-program names are folded to uppercase by the compiler but otherwise are
processed as is, without truncation or translation.
PGMNAME(LONGMIXED)
With PGMNAME(LONGMIXED), program names are processed as is, without truncation,
translation, or folding to uppercase.
With PGMNAME(LONGMIXED), all program name definitions must be specified using
the literal format of the program name in the PROGRAM-ID paragraph or ENTRY
statement.
The literal used for a program name (in any of the contexts listed above as affected
by the PGMNAME option) can contain any character in the range X’41’-X’FE’.
PGMNAME usage notes
v The following are not affected by the PGMNAME option:
– Class names and method names.
– System names (assignment-names in SELECT . . . ASSIGN, and text-names or
library-names on COPY statements).
– Dynamic calls. Dynamic calls are resolved with the target program name
truncated to eight characters, folded to uppercase, and translation of
embedded hyphens or a leading digit.
– CANCELs of nonnested programs. Name resolution uses the same mechanism
as for a dynamic call.
v The PGMNAME option does affect nested-program calls and static calls to programs
that are linked together with the caller.
288
Programming Guide
v COBOL source files containing calls to SOM API interfaces must be compiled
with PGMNAME(LONGMIXED) because SOM API names are case sensitive and many
are longer than eight characters.
v Dynamic calls are not permitted to COBOL programs compiled with the
PGMNAME(LONGMIXED) or PGMNAME(LONGUPPER) options unless the program name is
less than or equal to 8 bytes and all uppercase. In addition, the name of the
program must be identical to the name of the module that contains it.
v PGMNAME(LONGUPPER) and PGMNAME(LONGMIXED) are supported only when NOCMPR2
is specified. When CMPR2 is specified, PGMNAME(COMPAT) is forced on.
v When using the extended character set supported by PGMNAME(LONGMIXED), be
sure to use names that conform to the linker, prelinker, or system conventions
that apply, depending on the mechanism used to resolve the names.
Using characters such as commas or parentheses is not recommended, as these
characters are used in the syntax of linker control statements.
RELATED REFERENCES
“Conflicting compiler options” on page 259
QUOTE/APOST
Default is: QUOTE
Abbreviations are: Q|APOST
Use QUOTE if you want the figurative constant [ALL] QUOTE or [ALL] QUOTES to
represent one or more quotation mark (“) characters. QUOTE conforms to the
COBOL 85 Standard.
Use APOST if you want the figurative constant [ALL] QUOTE or [ALL] QUOTES to
represent one or more apostrophe (’) characters.
Delimiters: Either quotes or apostrophes can be used as literal delimiters,
regardless of whether the APOST or QUOTE option is in effect. The delimiter character
used as the opening delimiter for a literal must be used as the closing delimiter for
that literal.
RENT
Default is: NORENT
Abbreviations are: None
A program compiled as RENT is generated as a reentrant object module; a program
compiled as NORENT is generated as a nonreentrant object module. Either can be
invoked as a main program or subprogram.
Chapter 16. Compiler options
289
CICS: You must use RENT for programs to be run under CICS.
OS/390 UNIX: You must use RENT for programs to be run in the OS/390 UNIX
environment.
|
|
When a reentrant program is to be run with extended addressing, you can use the
DATA(24|31) option to control whether dynamic data areas are allocated in
unrestricted storage or in storage obtained from below 16 MB. Compile programs
with RENT or RMODE(ANY) if they will be run with extended addressing in virtual
storage addresses above 16 MB.
DATA(24|31): DATA(24|31) does not affect programs compiled with NORENT.
RENT|NORENT also affects the RMODE (residency mode) that your program will run
under. All IBM COBOL for OS/390 & VM programs are AMODE(ANY).
Link-edit considerations: If all programs in a load module are compiled with RENT,
then it is recommended that the load module be link-edited with the RENT link-edit
attribute. (Use the REUS link-edit attribute instead if the load module will also
contain any non-COBOL programs that are serially reusable.)
If any program in a load module is compiled with NORENT, the load module must
not be link-edited with the RENT or REUS link-edit attributes. The NOREUS
linkage-editor option is needed to ensure that the CANCEL statement will guarantee
a fresh copy of the program on a subsequent CALL.
RELATED REFERENCES
“Conflicting compiler options” on page 259
RMODE
Default is: AUTO
Abbreviations are: None
A program compiled with the RMODE(AUTO) option will have RMODE(24) if NORENT is
specified, and RMODE(ANY) if RENT is specified. This is the same behavior as
COBOL/370 Release 1 and VS COBOL II.
A program compiled with the RMODE(24) option will have RMODE(24) whether
NORENT or RENT is specified.
A program compiled with the RMODE(ANY) option will have RMODE(ANY) whether
NORENT or RENT is specified.
Passing data: IBM COBOL for OS/390 & VM NORENT programs compiled with
RMODE(ANY) that are required to pass data to programs running in AMODE(24) must
be link-edited with RMODE(24). The data areas for NORENT programs will be above
the line or below the line depending on the RMODE of the program, even if DATA(24)
has been specified.
290
Programming Guide
IBM COBOL for OS/390 & VM RENT programs that are required to pass data to
programs running in AMODE(24) must be compiled with DATA(24).
RELATED REFERENCES
“QSAM input/output buffers” on page 267
“Conflicting compiler options” on page 259
SEQUENCE
Default is: SEQUENCE
Abbreviations are: SEQ|NOSEQ
When you use SEQUENCE, the compiler examines columns 1 through 6 of your
source statements to check that the statements are arranged in ascending order
according to their EBCDIC collating sequence. The compiler issues a diagnostic
message if any statements are not in ascending sequence (source statements with
blanks in columns 1 through 6 do not participate in this sequence check and do
not result in messages).
If you use COPY statements and SEQUENCE is in effect, be sure that your source
program sequence fields and the copy member sequence fields are coordinated.
If you use NUMBER and SEQUENCE, the sequence is checked according to numeric,
rather than EBCDIC, collating sequence.
If you are doing a batch compilation and LIB and SEQUENCE are in effect, all
programs in the batch compile will be treated as a single input file. The sequence
numbers of the entire input file must be in ascending order.
Use NOSEQUENCE to suppress this checking and the diagnostic messages.
NOSEQUENCE conforms to the COBOL 85 Standard.
SIZE
Default is: SIZE(MAX)
Abbreviations are: SZ
nnnnn specifies a decimal number that must be at least 851968.
nnnK specifies a decimal number in 1K increments. The minimum acceptable value
is 832K.
Chapter 16. Compiler options
291
MAX requests the largest available block of storage in the user region for use during
compilation.
Use SIZE to indicate the amount of main storage available for compilation (where
1K = 1024 bytes decimal).
Do not use SIZE(MAX) if, when you invoke the compiler, you require it to leave a
specific amount of unused storage available in the user region. If you specify
SIZE(MAX) in an extended addressing environment, the compiler uses:
v Above the 16-MB line—all the storage in the user region
v Below the 16-MB line—storage for:
– Work file buffers
– Compiler modules that must be loaded below the line
Do not use SIZE(MAX) when you are compiling large object-oriented applications
with either the IDLGEN or TYPECHK options. Storage space must be left in the user
region for Interface Repository data.
SOURCE
Default is: SOURCE
Abbreviations are: S|NOS
Use SOURCE to get a listing of your source program. This listing will include any
statements embedded by PROCESS or COPY statements.
You must specify SOURCE if you want embedded messages in the source listing.
Use NOSOURCE to suppress the source code from the compiler output listing.
If you want to limit the SOURCE output, use *CONTROL SOURCE or NOSOURCE
statements in your PROCEDURE DIVISION. Your source statements following a
*CONTROL NOSOURCE are not included in the listing at all, unless a *CONTROL SOURCE
statement switches the output back to normal SOURCE format.
“Example: MAP output” on page 324
RELATED REFERENCES
*CONTROL (*CBL) statement (IBM COBOL Language Reference)
292
Programming Guide
SPACE
Default is: SPACE(1)
Abbreviations are: None
Use SPACE to select single-, double-, or triple-spacing in your source code listing.
SPACE has meaning only when the SOURCE compiler option is in effect.
RELATED REFERENCES
“SOURCE” on page 292
SQL
|
Default is: NOSQL
|
Abbreviations are: None
|
OS/390 only: This option is not supported under VM/CMS.
|
|
|
|
Use the SQL compiler option to enable the DB2 coprocessor capability and to
specify DB2 suboptions. You must specify the SQL option if your COBOL source
program contains SQL statements and it has not been processed by the DB2
precompiler.
|
|
|
When you use the SQL option, the compiler writes the database request module
(DBRM) to ddname DBRMLIB. Note that the compiler needs access to DB2 Version 7
or later.
|
|
If you specify the NOSQL option, any SQL statements found in the source program
are diagnosed and discarded.
|
Use either quotes or apostrophes to delimit the string of DB2 suboptions.
|
|
|
|
|
|
|
|
|
|
|
You can partition a long suboption string into multiple suboption strings on
multiple CBL statements. The DB2 suboptions are concatenated in the order of their
appearance. For example:
//STEP1 EXEC IGYWC, . . .
// PARM.COBOL='SQL(“string1”)'
//COBOL.SYSIN DD *
CBL SQL(“string2”)
CBL SQL(“string3”)
IDENTIFICATION DIVISION.
PROGRAM-ID. DRIVER1.
. . .
Chapter 16. Compiler options
293
|
|
The compiler passes the following suboption string to the DB2 coprocessor:
|
|
|
|
The concatenated strings are delimited with single spaces as shown. If multiple
instances of the same DB2 option are found, the last specification of each option
prevails. The compiler limits the length of the concatenated DB2 suboptions string
to 4K bytes.
“string1 string2 string3”
RELATED TASKS
“Compiling with the SQL option” on page 356
RELATED REFERENCES
“Conflicting compiler options” on page 259
SSRANGE
Default is: NOSSRANGE
Abbreviations are: SSR|NOSSR
Use SSRANGE to generate code that checks if subscripts (including ALL subscripts) or
indexes try to reference an area outside the region of the table. Each subscript or
index is not individually checked for validity; rather, the effective address is
checked to ensure that it does not cause a reference outside the region of the table.
Variable-length items will also be checked to ensure that the reference is within
their maximum defined length.
Reference modification expressions will be checked to ensure that:
v The reference modification starting position is greater than or equal to 1.
v The reference modification starting position is not greater than the current length
of the subject data item.
v The reference modification length value (if specified) is greater than or equal to
1.
v The reference modification starting position and length value (if specified) do
not reference an area beyond the end of the subject data item.
If SSRANGE is in effect at compile time, the range-checking code is generated. You
can inhibit range checking by specifying CHECK(OFF) as a run-time option. This
leaves range-checking code dormant in the object code. The range-checking code
can then be optionally used to aid in resolving any unexpected errors without
recompilation.
If an out-of-range condition is detected, an error message is displayed and the
program is terminated.
Remember: You will get range checking only if you compile your program with
the SSRANGE option and run it with the CHECK(ON) run-time option.
RELATED CONCEPTS
“Reference modifiers” on page 87
294
Programming Guide
TERMINAL
Default is: NOTERMINAL
Abbreviations are: TERM|NOTERM
Use TERMINAL to send progress and diagnostic messages to the SYSTERM data set.
Use NOTERMINAL if this additional output is not desired.
TEST
Default is: NOTEST
|
Abbreviations are: SEP for SEPARATE and NOSEP for NOSEPARATE.
Use TEST to produce object code that enables Debug Tool to perform batch and
interactive debugging. The amount of debugging support available depends on
which TEST suboptions you use. The TEST option also allows you to request that
symbolic variables be included in the formatted dump produced by Language
Environment.
Use NOTEST if you do not want to generate object code with debugging information
and do not want the formatted dump to include symbolic variables.
|
|
|
TEST has three suboptions:
|
|
1. The first specifies whether compiled-in hooks will be generated by the
compiler.
2. The second specifies whether symbolic information will be generated.
3. The third specifies whether that symbolic information will be part of the object
program or in a separate file.
You can specify any combination of suboptions (one, two, or all) but you can
specify SEPARATE only when SYM is in effect.
|
You can choose one of the following hook-location suboptions:
|
NONE
No hooks will be generated.
|
BLOCK
Hooks will be generated at all program entry and exit points.
|
PATH
Hooks will be generated at all program entry and exit points and at all
|
|
|
Chapter 16. Compiler options
295
path points. A path point is anywhere in a program where the logic flow is
not necessarily sequential or can change. Some examples of path points are
IF-THEN-ELSE constructs, PERFORM loops, ON SIZE ERROR phrases, and CALL
statements.
|
|
|
|
|
|
|
STMT
Hooks will be generated at every statement and label, and at all program
entry and exit points. In addition, if the DATEPROC option is in effect, hooks
will be generated at all date-processing statements.
|
|
|
|
ALL
Hooks will be generated at all statements, all path points, and at all
program entry and exit points (both outermost and contained programs.)
In addition, if the DATEPROC option is in effect, hooks will be generated at
all date-processing statements.
|
|
|
|
When you set the SYM suboption, you can specify the optional suboption SEPARATE,
indicating that the symbolic information tables for the Debug Tool are generated in
a data set separate from the object module. When you do not specify the SEPARATE
suboption, the symbolic information is included in the object module.
|
|
|
|
|
|
|
|
|
When you invoke the COBOL compiler from JCL or from TSO and you specify the
TEST(. . .,SYM,SEPARATE) option, the symbolic debug information tables are
written to the data set specified in the SYSDEBUG DD statement. The SYSDEBUG DD
statement must specify the name of a sequential data set, the name of a PDS or
PDSE member, or an HFS path. The data set LRECL must be greater than or equal
to 80, and less than or equal 1024. The default LRECL for SYSDEBUG is 1024. The
data set RECFM can be F or FB. You can set the block size by either using the
BLKSIZE subparameter of the DCB parameter, or leave it to the system to set it to the
system-determined default block size.
|
|
|
|
When you invoke the COBOL compiler from the OS/390 UNIX shell and you
specify the TEST(. . .,SYM,SEPARATE) option, the symbolic debug information
tables are written to file file.dbg in the current directory, where file is the name of
the COBOL source file.
|
|
|
|
|
|
|
|
|
Production debugging: With the latest levels of Debug Tool you can step through
your program, even if there are no compiled-in hooks, using new Debug Tool
function called overlay hooks. To take advantage of this function, compile with
NOOPTIMIZE and TEST(NONE). This is sometimes referred to as production debugging
or production-level debugging, because you avoid the performance overhead of
compiled-in hooks yet most Debug Tool function is still available. Production
debugging also refers to using the SEPARATE suboption to keep the load module
size smaller and yet maintain Debug Tool and Language Environment formatted
dump functionality.
|
|
|
When you use production debugging with overlay hooks, there are some
restrictions on debugging function, such as:
v The GO TO Debug Tool command is not supported.
There are two ways that the TEST option can improve your formatted dumps from
Language Environment:
v Use the NOSYM suboption of TEST to have line numbers in the dump that indicate
the failing statement, rather than just an offset.
v Use the SYM suboption of TEST to have the values of the program variables listed
in the dump.
With NOTEST, the dump will not have program variables and will not have a line
number for the failing statement.
296
Programming Guide
IBM COBOL for OS/390 & VM uses the Language Environment-provided dump
services to produce dumps that are consistent in content and format to those
produced by other Language Environment-conforming member languages.
Whether Language Environment produces a dump for unhandled conditions
depends on the setting of the run-time option TERMTHDACT. If you specify
TERMTHDACT(DUMP), a dump is generated if a condition of severity 2 or greater goes
unhandled.
RELATED CONCEPTS
Considerations for setting TERMTHDACT options (Language Environment
Debugging Guide and Run-Time Messages)
RELATED TASKS
“Defining the debug data set (SYSDEBUG)” on page 222
Generating a dump (Language Environment Debugging Guide and Run-Time Messages)
Invoking Debug Tool using the run-time TEST option (Debug Tool User’s Guide and
Reference)
RELATED REFERENCES
“Conflicting compiler options” on page 259
TEST | NOTEST (Language Environment Programming Reference)
TRUNC
Default is: TRUNC(STD)
Abbreviations are: None
TRUNC(STD) conforms to the COBOL 85 Standard, whereas TRUNC(OPT) and
TRUNC(BIN) are IBM extensions.
|
|
TRUNC has no effect on COMP-5 data items; COMP-5 items are handled as if
TRUNC(BIN) were in effect regardless of the TRUNC suboption specified.
TRUNC(STD)
Use TRUNC(STD) to control the way arithmetic fields are truncated during
MOVE and arithmetic operations. TRUNC(STD) applies only to USAGE BINARY
receiving fields in MOVE statements and arithmetic expressions. When
TRUNC(STD) is in effect, the final result of an arithmetic expression, or the
sending field in the MOVE statement, is truncated to the number of digits in
the PICTURE clause of the BINARY receiving field.
TRUNC(OPT)
TRUNC(OPT) is a performance option. When TRUNC(OPT) is in effect, the
compiler assumes that data conforms to PICTURE specifications in USAGE
BINARY receiving fields in MOVE statements and arithmetic expressions. The
results are manipulated in the most optimal way, either truncating to the
number of digits in the PICTURE clause, or to the size of the binary field in
storage (halfword, fullword, or doubleword).
Tips:
Chapter 16. Compiler options
297
1. Use the TRUNC(OPT) option only if you are sure that the data being
moved into the binary areas will not have a value with larger precision
than that defined by the PICTURE clause for the binary item. Otherwise,
unpredictable results could occur. This truncation is performed in the
most efficient manner possible; therefore, the results will be dependent
on the particular code sequence generated. It is not possible to predict
the truncation without seeing the code sequence generated for a
particular statement.
2. There are some cases when programs compiled with the TRUNC(OPT)
option under COBOL for OS/390 & VM could give different results
than the same programs compiled under OS/VS COBOL with NOTRUNC.
You must actually lose nonzero high-order digits for this difference to
appear. For statements where loss of high-order digits might cause a
difference in results between COBOL for OS/390 & VM and OS/VS
COBOL, COBOL for OS/390 & VM will issue a diagnostic message. If
you receive this message, make sure that either the sending items will
not contain large numbers or that the receivers are defined with
enough digits in the PICTURE clause to handle the largest sending data
items.
TRUNC(BIN)
The TRUNC(BIN) option applies to all COBOL language that processes USAGE
BINARY data. When TRUNC(BIN) is in effect, all binary items (USAGE COMP,
COMP-4, or BINARY) are handled as native hardware binary items, that is, as
if they were each individually declared USAGE COMP-5:
v BINARY receiving fields are truncated only at halfword, fullword, or
doubleword boundaries.
v BINARY sending fields are handled as halfwords, fullwords, or
doublewords when the receiver is numeric; TRUNC(BIN) has no effect
when the receiver is not numeric.
v The full binary content of fields is significant.
v DISPLAY will convert the entire content of binary fields with no
truncation.
|
|
|
Recommendation: TRUNC(BIN) is the recommended option for programs
that use binary values set by other products. Other products, such as IMS,
DB2, C/C++, FORTRAN, and PL/I, might place values in COBOL binary
data items that do not conform to the PICTURE clause of the data items.
You can avoid the performance overhead of using TRUNC(BIN) as your
installation default by using COMP-5 for individual binary data items passed
to non-COBOL programs or other products and subsystems. The use of
COMP-5 is not affected by the TRUNC suboption in effect.
|
|
|
|
TRUNC example 1
01 BIN-VAR
PIC 99 USAGE BINARY.
. . .
MOVE 123451 to BIN-VAR
The following table shows values of the data items after the MOVE:
298
Programming Guide
Data item
Decimal
Hex
Display
Sender
123451
00|01|E2|3B
123451
Receiver TRUNC(STD)
51
00|33
51
Data item
Decimal
Hex
Display
Receiver TRUNC(OPT)
-7621
E2|3B
2J
Receiver TRUNC(BIN)
-7621
E2|3B
762J
A halfword of storage is allocated for BIN-VAR. The result of this MOVE statement if
the program is compiled with the TRUNC(STD) option is 51; the field is truncated to
conform to the PICTURE clause.
If you compile the program with the TRUNC(BIN), the result of the MOVE statement is
-7621. The reason for the unusual result is that nonzero high-order digits are
truncated. Here, the generated code sequence would merely move the lower
halfword quantity X’E23B’ to the receiver. Because the new truncated value
overflows into the sign bit of the binary halfword, the value becomes a negative
number.
It is better not to compile this MOVE statement with TRUNC(OPT), because 123451 has
greater precision than the PICTURE clause for BIN-VAR. With TRUNC(OPT), the results
are again -7621. This is because the best performance was gained by not doing a
decimal truncation.
TRUNC example 2
01 BIN-VAR
PIC 9(6) USAGE BINARY
. . .
MOVE 1234567891 to BIN-VAR
The following table shows values of the data items after the MOVE:
Data item
Decimal
Hex
Display
Sender
1234567891
49|96|02|D3
1234567891
Receiver TRUNC(STD)
567891
00|08|AA|53
567891
Receiver TRUNC(OPT)
567891
53|AA|08|00
567891
Receiver TRUNC(BIN)
1234567891
49|96|02|D3
1234567891
When you specify TRUNC(STD), the sending data is truncated to six integer digits to
conform to the PICTURE clause of the BINARY receiver.
When you specify TRUNC(OPT), the compiler assumes the sending data is not larger
than the PICTURE clause precision of the BINARY receiver. The most efficient code
sequence in this case is ttruncation as if TRUNC(STD) were in effect.
When you specify TRUNC(BIN), no truncation occurs because all of the sending data
fits into the binary fullword allocated for BIN-VAR.
RELATED CONCEPTS
“Formats for numeric data” on page 36
RELATED TASKS
“Preparing COBOL programs to run under CICS” on page 350
Chapter 16. Compiler options
299
TYPECHK
Default is: NOTYPECHK
Abbreviations are: TC|NOTC
OS/390 only: This option is not supported under VM/CMS.
Use TYPECHK to have the compiler enforce the rules for object-oriented type
checking, and generate diagnostics for any violations.
Use NOTYPECHK to turn off the checking for typing violations.
The type conformance requirements are covered in the IBM COBOL Language
Reference under the appropriate language elements. Type-checking requirements
include:
v The method being invoked on an INVOKE statement must be supported by the
class of the referenced object.
v Method parameters on an INVOKE and the corresponding method PROCEDURE
DIVISION USING must conform.
v The SET object-reference-1 TO object-reference-2 statement requires that the classes of
the objects be of appropriate derivation relationships.
v A method override must have a conforming interface to the corresponding
method in the parent class.
When you specify TYPECHK, there must be entries in the SOM Interface Repository
(IR) for each class that is referenced in the COBOL source being compiled.
For COBOL classes, you can create the IR entries by using the COBOL IDLGEN
option when compiling the class definitions. Doing so creates an IDL file that
describes the interface of the COBOL class. Compile the IDL using the SOM
Compiler with its “ir” emitter.
Note that if the COBOL program references classes that are provided by the SOM
product itself (such as the SOMObject class), then you can use the pregenerated IR
for these classes (provided as part of the OS/390 SOMobjects product) to verify
that the COBOL usage conforms to the class interfaces.
Do not use SIZE(MAX) when you are compiling large object-oriented applications
with the TYPECHK option. Storage space must be left in the user region for Interface
Repository data.
RELATED CONCEPTS
“Chapter 25. System Object Model” on page 415
RELATED REFERENCES
“IDLGEN” on page 277
“Conflicting compiler options” on page 259
300
Programming Guide
VBREF
Default is: NOVBREF
Abbreviations are: None
Use VBREF to get a cross-reference among all verb types used in the source program
and the line numbers in which they are used. VBREF also produces a summary of
how many times each verb was used in the program.
Use NOVBREF for more efficient compilation.
WORD
Default is: NOWORD
Abbreviations are: WD|NOWD
xxxx specifies the ending characters of the name of the reserved-word table
(IGYCxxxx) to be used in your compilation. IGYC are the first four standard
characters of the name, and xxxx can be one to four characters in length.
Use WORD(xxxx) to specify that an alternate reserved-word table is to be used during
compilation.
Alternate reserved-word tables provide changes to the IBM-supplied default
reserved-word table. Your systems programmer might have created one or more
alternate reserved-word tables for your site. See your systems programmer for the
names of alternate reserved-word tables.
IBM COBOL provides an alternate reserved-word table (IGYCCICS) specifically for
CICS applications. It is set up to flag COBOL words not supported under CICS
with an error message. If you want to use this CICS reserved-word table during
your compilation, specify the compiler option WORD(CICS).
|
|
|
|
IBM COBOL provides an alternate reserved-word table (IGYCNOOO) specifically
for your existing applications that use object-oriented reserved words (OBJECT,
METHOD, FACTORY, and others) as user-defined words.IGYCNOOO does not reserve
the words used for object-orientation, so your applications will still work if you
refer to these words:
CLASS-ID
END-INVOKE
FACTORY
INHERITS
INVOKE
LOCAL-STORAGE
METACLASS
METHOD
METHOD-ID
OBJECT
OVERRIDE
RECURSIVE
RETURNING
REPOSITORY
SELF
SUPER
Chapter 16. Compiler options
301
If you want to use this NOOO reserved-word table during your compilation, specify
the compiler option WORD(NOOO).
NOWORD conforms to the COBOL 85 Standard.
RELATED TASKS
“Preparing COBOL programs to run under CICS” on page 350
RELATED REFERENCES
“Conflicting compiler options” on page 259
XREF
Default is: NOXREF
Abbreviations are: X|NOX
You can choose XREF, XREF(FULL), or XREF(SHORT).
Use XREF to get a sorted cross-reference listing. EBCDIC data names and procedure
names are listed in alphanumeric order. DBCS data names and procedure names
are listed based on their physical order in the program, and appear before the
EBCDIC data names and procedure names, unless the DBCSXREF installation option
is selected with a DBCS ordering program. In this case, DBCS data names and
procedure names are ordered as specified by the DBCS ordering program.
Also included is a section listing all the program names that are referenced in your
program, and the line number where they are defined. External program names are
identified as such.
If you use XREF and SOURCE, cross-reference information will also be printed on the
same line as the original source in the listing. Line number references or other
information, will appear on the right-hand side of the listing page. On the right of
source lines that reference intrinsic functions, the letters ’IFN’ appear with the line
numbers of the location where the function’s arguments are defined. Information
included in the embedded references lets you know if an identifier is undefined or
defined more than once (UND or DUP will be printed); if an item is implicitly defined
(IMP), such as special registers or figurative constants; and if a program name is
external (EXT).
If you use XREF and NOSOURCE, you’ll get only the sorted cross-reference listing.
XREF(SHORT) will print only the explicitly referenced variables in the cross-reference
listing. XREF(SHORT) applies to DBCS data names and procedure-names as well as
EBCDIC names.
NOXREF suppresses this listing.
Observe:
302
Programming Guide
1. Group names used in a MOVE CORRESPONDING statement are in the XREF listing. In
addition, the elementary names in those groups are also listed.
2. In the data name XREF listing, line numbers preceded by the letter “M” indicate
that the data item is explicitly modified by a statement on that line.
3. XREF listings take additional storage.
RELATED CONCEPTS
“Chapter 17. Debugging” on page 309
RELATED TASKS
“Getting listings” on page 319
RELATED REFERENCES
COBOL compiler options (Language Environment Debugging Guide and Run-Time
Messages)
YEARWINDOW
Default is: YEARWINDOW(1900)
Abbreviation is: YW
Use the YEARWINDOW option to specify the first year of the 100-year window (the
century window) to be applied to windowed date field processing by the COBOL
compiler.
base-year represents the first year of the 100-year window, and must be specified as
one of the following:
v An unsigned decimal number between 1900 and 1999.
This specifies the starting year of a fixed window. For example,
YEARWINDOW(1930) indicates a century window of 1930-2029.
v A negative integer from -1 through -99.
This indicates a sliding window, where the first year of the window is calculated
from the current run-time date. The number is subtracted from the current year
to give the starting year of the century window. For example, YEARWINDOW(-80)
indicates that the first year of the century window is 80 years before the current
year at the time the program is run.
Notes:
1. The YEARWINDOW option has no effect unless the DATEPROC option is also in effect.
2. At run time, two conditions must be true:
v The century window must have its beginning year in the 1900s.
v The current year must lie within the century window for the compilation
unit.
For example, if the current year is 2001, the DATEPROC option is in effect, and
you use the YEARWINDOW(1900) option, the program will terminate with an error
message.
RELATED REFERENCES
“Conflicting compiler options” on page 259
Chapter 16. Compiler options
303
ZWB
Default is: ZWB
Abbreviations are: None
With ZWB, the compiler removes the sign from a signed external decimal (DISPLAY)
field when comparing this field to an alphanumeric elementary field during
execution.
If the external decimal item is a scaled item (contains the symbol P in its PICTURE
character string), its use in comparisons is not affected by ZWB. Such items always
have their sign removed before the comparison is made to the alphanumeric field.
ZWB affects how the program runs; the same COBOL source program can give
different results, depending on the option setting.
ZWB conforms to the COBOL 85 Standard.
Use NOZWB if you want to test input numeric fields for SPACES.
Compiler-directing statements
Several statements help you to direct the compilation of your program.
BASIS statement
This extended source program library statement provides a complete
COBOL program as the source for a compilation. For rules of formation
and processing, see the description under text-name of the COPY statement.
|
|
*CONTROL (*CBL) statement
This compiler-directing statement selectively suppresses or allows output
to be produced. The names *CONTROL and *CBL are synonymous.
COPY statement
|
|
This library statement places prewritten text into a COBOL program. A
user-defined word can be the same as a text-name or a library-name. The
uniqueness of text-name and library-name is determined after the formation
and conversion rules for a system-dependent name have been applied. If
library-name is omitted, SYSLIB is assumed.
|
When compiling with JCL:
Text-name, library-name, and literal are processed as follows:
v The name (which can be one to 30 characters long) is truncated to eight
characters. Only the first eight characters of text-name and library-name
are used as the identifying name. These eight characters must be unique
within one COBOL library.
v The name is folded to uppercase.
304
Programming Guide
v Hyphens that are not the first or last character are translated to zero (0),
and a warning message is given.
v If the first character is numeric, then the characters (1-9) are translated to
A-I, and a warning message is given. An error message is given if the
first or last character is a hyphen (or if it is a hyphen, @, #, or $ for a
literal).
For example:
COPY INVOICES1Q
COPY “Company-#Employees” IN Personellib
|
|
|
|
|
In the IN/OF phrase, library-name is the ddname that identifies the
partitioned data set to be copied from. Use a DD statement such as in the
following example to define library-name:
|
|
|
|
To specify more than one copy library, use either JCL or a combination of
JCL and the IN/OF phrase. Using just JCL, concatenate data sets on your DD
statement for SYSLIB. Alternatively, define multiple DD statements and
include the IN/OF phrase on your COPY statements.
//COPYLIB
//
DD
DSNAME=ABC.COB,VOLUME=SER=111111,
DISP=SHR,UNIT=3380
The maximum block size for the copy library depends on the device on
which your data set resides.
|
When compiling in the OS/390 UNIX System Services shell:
|
|
When you compile with the cob2 command, COPY text is included from the
HFS. Text-name, library-name, and literal are processed as follows:
v User-defined words are folded to uppercase. Literals are not. Because
OS/390 UNIX is case sensitive, if your file name is lowercase or mixed
case, you must specify it as a literal.
v When text-name is a literal and library-name is omitted, text-name is used
directly: as a file name, a relative path name, or an absolute path name
(if the first character is /). For example:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
COPY “MyInc”
COPY “x/MyInc”
COPY “/u/user1/MyInc”
v When text-name is a user-defined word and an environment variable of
that name is defined, the value of the environment variable is used as
the name of the file containing the copy text.
If an environment variable of that name is not defined, the copy text is
searched for as the following names, in the order given:
1. text-name.cpy
2. text-name.CPY
3. text-name.cbl
4. text-name.CBL
5. text-name.cob
6. text-name.COB
7. text-name
v When library-name is a literal, it is treated as the actual path, relative or
absolute, from which to copy file text-name.
Chapter 16. Compiler options
305
|
|
|
v When library-name is a user-defined word, it is treated as an environment
variable. The value of the environment variable is used as the path. If
the environment variable is not set, an error occurs.
|
|
|
|
|
|
v If both library-name and text-name are specified, the compiler forms the
path name for the copy text by concatenating library-name and text-name
with a path separator (/) inserted between the two values. For example,
suppose you have the following setting for COPY MYCOPY OF MYLIB:
export MYCOPY=mystuff/today.cpy
export MYLIB=/u/user1
These settings result in:
|
|
/u/user1/mystuff/today.cpy
|
|
|
|
When library-name is an environment variable that identifies the path from
which copy text is to be copied, use an export command such as the
following example to define library-name:
|
|
|
The name of the environment variable must be uppercase. To specify more
than one copy library, set the environment variable to multiple path names
delimited by : (colon).
|
|
|
When library-name is omitted and text-name is not an absolute path name,
the copy text is searched for in this order:
1. In the current directory
2. In the paths specified on the -I cob2 option
export COPYLIB=/u/mystuff/copybooks
|
|
3. In the paths specified in the SYSLIB environment variable
DELETE statement
This extended source library statement removes COBOL statements from
the BASIS source program.
EJECT statement
This compiler-directing statement specifies that the next source statement is
to be printed at the top of the next page.
ENTER statement
The compiler handles this statement as a comment.
INSERT statement
This library statement adds COBOL statements to the BASIS source
program.
PROCESS (CBL) statement
This statement, which is placed before the IDENTIFICATION DIVISION
header of an outermost program, indicates which compiler options are to
be used during compilation of the program.
REPLACE statement
This statement is used to replace source program text.
SERVICE LABEL statement
This statement is generated by the CICS translator to indicate control flow.
It is not intended for general use.
SKIP1/2/3 statement
These statements indicate lines to be skipped in the source listing.
306
Programming Guide
TITLE statement
This statement specifies that a title (header) be printed at the top of each
page of the source listing.
USE statement
The USE statement provides declaratives to specify the following:
v Error-handling procedures—EXCEPTION/ERROR
v User label-handling procedures—LABEL
v Debugging lines and sections—DEBUGGING
RELATED TASKS
“Changing the header of a source listing” on page 6
“Eliminating repetitive coding” on page 551
“Using compiler-directing statements” on page 245
“Specifying compiler options under OS/390” on page 223
“Specifying compiler options under OS/390 UNIX” on page 236
“Setting environment variables under OS/390 UNIX” on page 235
“Specifying compiler options under CMS” on page 246
RELATED REFERENCES
“cob2” on page 239
IBM COBOL Language Reference
Chapter 16. Compiler options
307
308
Programming Guide
Chapter 17. Debugging
You can choose from two approaches to determine the cause of problems in
program behavior of your application: source-language debugging or the
interactive debugger.
For source-language debugging COBOL provides several language elements,
compiler options, and listing outputs that make debugging easier.
If the problem with your program is not easily detected and you do not have a
debugger available, you might need to analyze a storage dump of your program.
Besides using the features inherent in COBOL, you can also use the Debug Tool,
which is available in the Full Function offering of this compiler.
The Debug Tool offers these productivity enhancements:
v Interactive debugging (in full-screen or line mode) or in batch mode
During an interactive full-screen mode session, you can use the Debug Tool’s
full-screen services and session panel windows on a 3270 device to debug your
program as it is running.
v COBOL-like commands
For each high-level language supported, commands for coding actions to be
taken at breakpoints are provided in a syntax similar to that programming
language. (This feature is not available to workstation users.)
v Mixed-language debugging
You can debug an application that contains programs written in different
language. Debug Tool automatically determines the language of the program or
subprogram being run.
v COBOL-CICS debugging
Debug Tool supports the debugging of CICS applications in both interactive and
batch mode.
v Support for remote debugging
Workstation users can use the IBM VisualAge COBOL product for debugging
programs residing on OS/390. VisualAge COBOL is available as a separate
product or as the Enterprise Workstation feature of this compiler.
RELATED TASKS
“Debugging with source language” on page 310
“Debugging using compiler options” on page 313
“Getting listings” on page 319
“Preparing to use the debugger” on page 343
RELATED REFERENCE
Debug Tool User’s Guide and Reference
Formatting and analyzing system dumps on OS/390 (Language Environment
Debugging Guide and Run-Time Messages)
Debugging example COBOL programs (Language Environment Debugging Guide and
Run-Time Messages)
© Copyright IBM Corp. 1991, 2000
309
Debugging with source language
You can use several COBOL language features to pinpoint the cause of a failure in
your program. If the program is part of a large application already in production
(precluding source updates), write a small test case to simulate the failing part of
the program. Code certain debugging features in the test case to help detect these
problems:
v Errors in program logic
v Input-output errors
v Mismatches of data types
v Uninitialized data
v Problems with procedures
RELATED TASKS
“Tracing program logic”
“Finding and handling input-output errors” on page 311
“Validating data” on page 311
“Finding uninitialized data” on page 311
“Generating information about procedures” on page 312
RELATED REFERENCES
Source language debugging (IBM COBOL Language Reference)
Tracing program logic
Trace the logic of your program by adding DISPLAY statements. For example, if you
determine that the problem is in an EVALUATE statement or in a set of nested IF
statements, use DISPLAY statements in each path to see the logic flow. If you
determine that the calculation of a numeric value is causing the problem, use
DISPLAY statements to check the value of some interim results.
If you have used explicit scope terminators to end statements in your program, the
logic of your program is more apparent and therefore easier to trace.
To determine whether a particular routine started and finished, you might insert
code like this into your program:
DISPLAY “ENTER CHECK PROCEDURE”
.
. (checking procedure routine)
.
DISPLAY “FINISHED CHECK PROCEDURE”
After you are sure that the routine works correctly, disable the DISPLAY statements
one of two ways:
v Put an asterisk in column 7 of each DISPLAY statement line to convert it to a
comment line.
v Put a D in column 7 of each DISPLAY statement to convert it to a comment line.
When you want to reactivate these statements, include a WITH DEBUGGING MODE
clause in the ENVIRONMENT DIVISION; the D in column 7 is ignored and the
DISPLAY statements are implemented.
Before you put the program into production, delete or disable the debugging aids
you used and recompile the program. The program will run more efficiently and
use less storage.
310
Programming Guide
RELATED CONCEPTS
“Scope terminators” on page 20
RELATED REFERENCES
DISPLAY statement (IBM COBOL Language Reference)
Finding and handling input-output errors
File status keys can help you determine whether your program errors are due to
input-output errors occurring on the storage media.
To use file status keys in debugging, include a test after each input-output
statement to check for a nonzero value in the status key. If the value is nonzero (as
reported in an error message), you should look at the coding of the input-output
procedures in the program. You can also include procedures to correct the error
based on the value of the status key.
If you have determined that a problem lies in an input-output procedure, include
the USE EXCEPTION/ERROR declarative to help debug the problem. Then, when a file
fails to open, the appropriate EXCEPTION/ERROR declarative is performed. The
appropriate declarative might be a specific one for the file or one provided for the
open attributes: INPUT, OUTPUT, I-O, or EXTEND.
Code each USE AFTER STANDARD ERROR statement in a section immediately after the
DECLARATIVE SECTION keyword of the PROCEDURE DIVISION.
RELATED REFERENCES
Status key values and meanings (IBM COBOL Language Reference)
Status key (IBM COBOL Language Reference)
Validating data
If you suspect that your program is trying to perform arithmetic on nonnumeric
data or is somehow receiving the wrong type of data on an input record, use the
class test to validate the type of data. The class test checks whether data is
alphabetic, alphabetic-lower, alphabetic-upper, DBCS, KANJI, or numeric.
RELATED REFERENCES
Class condition (IBM COBOL Language Reference)
Finding uninitialized data
Use INITIALIZE or SET statements to initialize a table or variable when you suspect
that the problem might be caused by residual data left in those fields.
If the problem you are having happens intermittently and not always with the
same data, the problem could be that a switch is not initialized but generally is set
to the right value (0 or 1) by accident. By including a SET statement to ensure that
the switch is initialized, you can either determine that the uninitialized switch is
the problem or remove that as a possible cause.
RELATED REFERENCES
INITIALIZE statement (IBM COBOL Language Reference)
SET statement (IBM COBOL Language Reference)
Chapter 17. Debugging
311
Generating information about procedures
Generate information about your program or test case and how it is running with
the USE FOR DEBUGGING declarative. This declarative lets you include statements in
the program and indicate when they should be performed when you run your
program.
For example, to check how many times a procedure is run, you could include a
debugging procedure in the USE FOR DEBUGGING declarative and use a counter to
keep track of the number of times control passes to that procedure. You can use
the counter technique to check items such as these:
v How many times a PERFORM runs and thus whether a particular routine is being
used and whether the control structure is correct
v How many times a loop routine runs and thus whether the loop is executing
and whether the number for the loop is accurate
You can have debugging lines or debugging statements or both in your program.
Debugging lines
Debugging lines are statements that are identified by a D in column 7. To make
debugging lines in your program active, include the WITH DEBUGGING MODE clause
on the SOURCE-COMPUTER line in the ENVIRONMENT DIVISION. Otherwise debugging
lines are treated as comments.
Debugging statements
Debugging statements are the statements coded in the DECLARATIVES SECTION of the
PROCEDURE DIVISION. Code each USE FOR DEBUGGING declarative in a separate
section. Code the debugging statements as follows:
v Only in a DECLARATIVES SECTION.
v Following the header USE FOR DEBUGGING.
v Only in the outermost program; they are not valid in nested programs.
Debugging statements are also never triggered by procedures contained in
nested programs.
To use debugging statements in your program, you must include both the WITH
DEBUGGING MODE clause and the DEBUG run-time option.
The WITH DEBUGGING MODE clause and the TEST compiler option (with any suboption
value other than NONE) are mutually exclusive. If both are present, the WITH
DEBUGGING MODE clause takes precedence.
“Example: USE FOR DEBUGGING”
RELATED REFERENCES
Debugging line (IBM COBOL Language Reference)
Coding debugging sections (IBM COBOL Language Reference)
DEBUGGING declarative (IBM COBOL Language Reference)
Example: USE FOR DEBUGGING
These program segments show what kind of statements are needed to use a
DISPLAY statement and a USE FOR DEBUGGING declarative to test a program. The
DISPLAY statement generates information on the terminal or in the output data set.
The USE FOR DEBUGGING declarative is used with a counter to show how many
times a routine runs.
312
Programming Guide
In this example the DISPLAY statement in the DECLARATIVES SECTION issues this
message every time the procedure Some-Routine runs:
Trace For Procedure-Name : Some-Routine 22
The number at the end of the message, 22, is the value accumulated in the
data-item Total; it shows the number of times Some-Routine has run. The
statements in the debugging declarative are performed before the named
procedure runs.
You can also use the DISPLAY statement to trace program execution and show the
flow through the program. You do this by dropping Total from the DISPLAY
statement and changing the USE FOR DEBUGGING declarative in the DECLARATIVES
SECTION to:
USE FOR DEBUGGING ON ALL PROCEDURES.
Now a message is displayed before every nondebugging procedure in the
outermost program is run.
Debugging using compiler options
Use certain compiler options to generate information to help you find errors in
your program such as these:
v Syntax errors such as duplicate data names (NOCOMPILE)
v Missing sections (SEQUENCE)
v Invalid subscript values (SSRANGE)
In addition, you can use certain compiler options to help you find these elements
in your program:
v Error messages and where the errors occurred (FLAG)
Chapter 17. Debugging
313
v
v
v
v
Program entity definitions and references (XREF)
Items you defined in the DATA DIVISION (MAP)
Verb references (VBREF)
Assembler-language expansion (LIST)
You can get a copy of your source (by using the SOURCE compiler option) or a
listing of generated code (by using the LIST compiler option).
There is also a compiler option (TEST) that you need to use to prepare your
program for debugging.
RELATED TASKS
“Selecting the level of error to be diagnosed” on page 316
“Finding coding errors”
“Finding line sequence problems” on page 315
“Checking for valid ranges” on page 315
“Finding program entity definitions and references” on page 317
“Listing data items” on page 318
“Getting listings” on page 319
“Preparing to use the debugger” on page 343
RELATED REFERENCES
“COMPILE” on page 265
“SEQUENCE” on page 291
“SSRANGE” on page 294
“FLAG” on page 274
“XREF” on page 302
“MAP” on page 281
“VBREF” on page 301
“LIST” on page 281
“TEST” on page 295
Finding coding errors
Use the NOCOMPILE compiler option for compiling conditionally or for checking
syntax only. When used with the SOURCE option, this option produces a listing that
will help you find your COBOL coding mistakes, such as missing definitions,
improperly defined data names, and duplicate data names.
If you are compiling in the TSO foreground, you can send the messages to your
screen by defining your data set as the SYSTERM data set and using the TERM option
when you compile your program.
Checking syntax only
Use NOCOMPILE without parameters to have the compiler only syntax-check the
source program and produce no object code. If you also specify the SOURCE option,
the compiler produces a listing after completing the syntax check.
The following compiler options are suppressed when you use NOCOMPILE without
parameters: DECK, OFFSET, LIST, OBJECT, OPTIMIZE, SSRANGE, and TEST.
Compiling conditionally
When you use NOCOMPILE(x), where x is one of the severity levels for errors, your
program is compiled if all the errors are of a lower severity than the x level. The
severity levels (from highest to lowest) that you can use are S (severe), E (error),
and W (warning).
314
Programming Guide
If an error of x level or higher occurs, the compilation stops and your program is
syntax-checked only. You receive a source listing if you have specified the SOURCE
option.
RELATED REFERENCES
“COMPILE” on page 265
Finding line sequence problems
Use the SEQUENCE compiler option to find statements that are out of sequence.
These breaks in sequence indicate that a section of your source program was
moved or deleted.
When you use SEQUENCE, the compiler checks the source statement numbers you
have supplied to see whether they are in ascending sequence. Two asterisks are
placed beside statement numbers that are out of sequence. Also, the total number
of these statements is printed as the first line of the diagnostics after the source
listing.
RELATED REFERENCES
“SEQUENCE” on page 291
Checking for valid ranges
Use the SSRANGE compiler option to check the following ranges:
v Subscripted or indexed data references
Is the effective address of the desired element within the maximum boundary of
the specified table?
v Variable-length data references (a reference to a data item that contains an
OCCURS DEPENDING ON clause)
Is the actual length positive and within the maximum defined length for the
group data item?
v Reference-modified data references
Are the offset and length positive? Is the sum of the offset and length within the
maximum length for the data item?
When the SSRANGE option is specified, checking is performed at run time when
both of the following are true:
v The COBOL statement containing the indexed, subscripted, variable-length, or
reference-modified data item is actually performed.
v The CHECK run-time option is ON.
If a check finds that an address is generated outside the address range of the data
item containing the referenced data, an error message is generated and the
program stops. The error message identifies the table or identifier that was
referenced and the line number where the error occurred. Additional information is
provided depending on the type of reference that caused the error.
If all subscripts, indices, or reference modifiers are literals in a given data reference
and they result in a reference outside the data item, the error is diagnosed at
compile time, regardless of the setting of the SSRANGE compiler option.
Performance consideration: SSRANGE can degrade the performance of your
program somewhat because of the extra overhead to check each subscripted or
indexed item.
Chapter 17. Debugging
315
RELATED REFERENCES
“SSRANGE” on page 294
“Performance-related compiler options” on page 545
Selecting the level of error to be diagnosed
Use the FLAG compiler option to select the level of error to be diagnosed during
compilation and to indicate whether syntax-error messages are embedded in the
listing. Use FLAG(I) or FLAG(I,I) to be notified of all errors in your program.
Specify as the first parameter the lowest severity level of the syntax-error messages
to be issued. Optionally, specify the second parameter as the lowest level of the
syntax-error messages to be embedded in the source listing. This severity level
must be the same or higher than the level for the first parameter. If you specify
both parameters, you must also specify the SOURCE compiler option.
Severity level
What you get when you specify the corresponding level
U (unrecoverable)
U messages only
S (severe)
All S and U messages
E (error)
All E, S, and U messages
W (warning)
All W, E, S, and U messages
I (informational)
All messages
When you specify the second parameter, each syntax-error message (except a
U-level message) is embedded in the source listing at the point where the compiler
had enough information to detect the error. All embedded messages (except those
issued by the library compiler phase) directly follow the statement to which they
refer. The number of the statement containing the error is also included with the
message. Embedded messages are repeated with the rest of the diagnostic
messages at the end of the source listing.
When you specify the NOSOURCE compiler option, the syntax-error messages are
included only at the end of the listing. Messages for unrecoverable errors are not
embedded in the source listing, because an error of this severity terminates the
compilation.
“Example: embedded messages”
RELATED CONCEPTS
“Severity codes for compiler error messages” on page 232
RELATED TASKS
“Generating a list of compiler error messages” on page 230
RELATED REFERENCES
“FLAG” on page 274
“Messages and listings for compiler-detected errors” on page 231
Example: embedded messages
The following example shows the embedded messages generated by specifying a
second parameter on the FLAG option. Some messages in the summary apply to
more than one COBOL statement.
316
Programming Guide
Finding program entity definitions and references
Use the XREF(FULL) compiler option to find out where a data name, procedure
name, or program name is defined and referenced. The sorted cross-reference
includes the line number where the entity was defined and the line numbers of all
references to it.
To include only the explicitly referenced variables, use the XREF(SHORT) option.
Chapter 17. Debugging
317
Use both the XREF (with FULL or SHORT) and the SOURCE options to get a modified
cross-reference printed to the right of the source listing. This embedded
cross-reference gives the line number where the data name or procedure name was
defined.
If your program contains DBCS user-defined words, these user-defined words are
listed before the alphabetic list of EBCDIC user-defined words.
In the OS/390 environment, if a DBCS ordering program is specified in the
DBCSXREF installation option, the DBCS user-defined words are listed in order
according to the specified DBCS collating sequence. Otherwise, the DBCS
user-defined words are listed in physical order according to their appearance in the
source program.
In the CMS environment, the DBCS user-defined words are listed in physical order
according to their appearance in the source program.
Group names in a MOVE CORRESPONDING statement are listed in the XREF listing. The
cross-reference listing includes the group names and all the elementary names
involved in the move.
“Example: XREF output - data-name cross-references” on page 340
“Example: XREF output - program-name cross-references” on page 341
“Example: embedded cross-reference” on page 341
RELATED TASKS
“Getting listings” on page 319
RELATED REFERENCES
“XREF” on page 302
Listing data items
Use the MAP compiler option to produce a listing of the items you defined in the
DATA DIVISION, plus all items implicitly declared. Use the MAP output to locate the
contents of a data item in a system dump.
In addition, when you use the MAP option, an embedded MAP summary (which
contains condensed data MAP information) is generated to the right of the COBOL
source data declaration. When both XREF data and an embedded MAP summary are
on the same line, the embedded summary is printed first.
You can select or inhibit parts of the MAP listing and embedded MAP summary by
using *CONTROL MAP or *CONTROL NOMAP statements (*CBL MAP or *CBL NOMAP
statements) throughout the source. For example:
*CONTROL NOMAP
01 A
02 B
*CONTROL MAP
*CBL NOMAP
01 A
02 B
*CBL MAP
“Example: MAP output” on page 324
RELATED TASKS
“Getting listings” on page 319
RELATED REFERENCES
“MAP” on page 281
318
Programming Guide
Getting listings
Get the information that you need for debugging by requesting the appropriate
compiler listing with the use of compiler options.
Attention: The listings produced by the compiler are not a programming interface
and are subject to change.
Use
Listing
Contents
To check diagnostic
messages about the
compilation, a list of the
options in effect for the
program, and statistics
about the content of the
program
Short listing
Diagnostic messages about NOSOURCE, NOXREF, NOVBREF,
the compile1; list of options NOMAP, NOOFFSET, NOLIST
in effect for the program;
statistics about the content
of the program
To aid in testing and
debugging your program;
to have a record after the
program has been
debugged
Source listing
Copy of your source
“SOURCE” on page 292
All DATA DIVISION items
and all implicitly declared
variables
“MAP” on page 2812
Map of DATA DIVISION
To find certain data items
items
in a storage dump; to see
the final storage allocation
after reentrancy or
optimization has been
accounted for; to see where
programs are defined and
check their attributes
Compiler option
Embedded map summary
(in the right margin of the
listing for lines in the DATA
DIVISION that contain data
declarations)
Nested program map (if the
program contains nested
programs)
Sorted cross-reference
To find where a name is
listing of names
defined, referenced, or
modified; to determine the
context (such as whether a
verb was used in a PERFORM
block) in which a procedure
is referenced
To find the failing verb in a PROCEDURE DIVISION code
program or the address in
and assembler code
storage of a data item that produced by the compiler3
was moved during the
program
Data names, procedure
names, and program
names; references to these
names
“XREF” on page 3022
3
Embedded modified
cross-reference: provides
the line number where the
data name or procedure
name was defined
Generated code
“LIST” on page 2812
4
To verify you still have a
valid logic path after you
move or add PROCEDURE
DIVISION sections
Condensed PROCEDURE
DIVISION listing
Condensed verb listing,
global tables,
WORKING-STORAGE
information, and literals
“OFFSET” on page 285
To find an instance of a
certain verb
Alphabetic listing of verbs
Each verb used, number of
times each verb was used,
line numbers where each
verb was used
“VBREF” on page 301
Chapter 17. Debugging
319
Use
Listing
Contents
Compiler option
1. To eliminate messages, turn off the options (such as FLAG) that govern the level of compile diagnostic
information. To use your line numbers in the compiled program, use the NUMBER compiler option. The compiler
checks the sequence of your source statement line numbers in columns 1 through 6 as the statements are read in.
When it finds a line number out of sequence, the compiler assigns to it a number with a value one higher than
the line number of the preceding statement. The new value is flagged with two asterisks. A diagnostic message
indicating an out-of-sequence error is included in the compilation listing.
2. The context of the procedure reference is indicated by the characters preceding the line number.
3. You can control the selective listing of generated object code by placing *CONTROL LIST and *CONTROL NOLIST
statements (*CBL LIST and *CBL NOLIST) in your source. Note that the *CONTROL statement is different from the
PROCESS (or CBL) statement.
The output is generated if:
v You specify the COMPILE option (or the NOCOMPILE(x) option is in effect and an error level x or higher does not
occur).
v You do not specify the OFFSET option. OFFSET and LIST are mutually exclusive options with OFFSET taking
precedence.
“Example:
“Example:
“Example:
“Example:
“Example:
“Example:
“Example:
“Example:
“Example:
“Example:
short listing”
SOURCE and NUMBER output” on page 323
MAP output” on page 324
embedded map summary” on page 325
nested program map” on page 328
XREF output - data-name cross-references” on page 340
XREF output - program-name cross-references” on page 341
embedded cross-reference” on page 341
OFFSET compiler output” on page 342
VBREF compiler output” on page 343
RELATED TASKS
“Generating a list of compiler error messages” on page 230
“Reading LIST output” on page 328
Determining the source of error (Language Environment Debugging Guide and
Run-Time Messages)
RELATED REFERENCES
“Messages and listings for compiler-detected errors” on page 231
Example: short listing
The numbers used in the explanation after the listing correspond to those
annotating the listing. For illustrative purposes, some errors that cause diagnostic
messages to be issued were deliberately introduced.
320
Programming Guide
Chapter 17. Debugging
321
(1)
COBOL default page header, including compiler-level information from the
LVLINFO installation-time compiler option.
(2)
Message about options passed to the compiler at compiler invocation. This
message does not appear if no options were passed.
(3)
Options coded in the PROCESS (or CBL) statement.
RENT
The program was compiled to be reentrant to copy code from a
library.
NOSOURCE
Turning SOURCE off removes the COBOL source code from the
COBOL listing.
TEST(ALL)
The program was compiled for use with Debug Tool.
322
(4)
Deliberate option conflicts were forced by specifying the OPTIMIZE option
on the compiler input parameter list. OPTIMIZE and the TEST(ALL) option
specified on the CBL statement are mutually exclusive. As a result, the
OPTIMIZE option is ignored.
(5)
Status of options at the start of this compilation.
(6)
Customized page header resulting from the COBOL program TITLE
statement.
(7)
Program diagnostics. The first message refers you to any library phase
diagnostics. Diagnostics for the library phase are presented at the
beginning of the listing.
(8)
Count of diagnostic messages in this program, grouped by severity level.
(9)
Program statistics for the program IGYTCARA.
(10)
Program statistics for the compilation unit. When you perform a batch
compilation, the return code is the highest message severity level for the
entire compilation.
Programming Guide
Example: SOURCE and NUMBER output
In the portion of the listing shown below, the programmer numbered two of the
statements out of sequence.
(1)
Customized page header resulting from the COBOL program TITLE
statement
(2)
Scale line labels Area A, Area B, and source code column numbers
(3)
Source code line number assigned by the compiler
(4)
Program (PL) and statement (SL) nesting level
(5)
Columns 1 through 6 of program (the sequence number area)
Chapter 17. Debugging
323
Example: MAP output
The following example shows output from the MAP option. The numbers used in
the explanation below correspond to the numbers annotating the output.
324
(1)
Explanations of the data definition attribute codes.
(2)
Source line number where the data item was defined.
(3)
Level definition or number. The compiler generates this number in the
following way:
v First level of any hierarchy is always 01. Increase 1 for each level; any
item you coded as 02 through 49.
v Level numbers 66, 77, and 88, and the indicators FD and SD, are not
changed.
(4)
Data name that is used in the source module in source order.
(5)
Base locator used for this data item.
(6)
Hexadecimal displacement from the beginning of the base locator value.
(7)
Hexadecimal displacement from the beginning of the containing structure.
(8)
Pseudoassembler code showing how the data is defined. When a structure
contains variable-length fields, the maximum length of the structure is
shown.
(9)
Data type and usage.
Programming Guide
(10)
Data definition attribute codes. The definitions are explained at the top of
the DATA DIVISION map.
(11)
UNUSED-DATA-ITEM was not referenced in the PROCEDURE DIVISION. Because
OPTIMIZE(FULL) was specified, UNUSED-DATA-ITEM was deleted, resulting in
the base locator being set to XXXX.
RELATED REFERENCES
“Terms used in MAP output” on page 326
“Symbols used in LIST and MAP output” on page 326
Example: embedded map summary
The following example shows an embedded map summary from specifying the MAP
option. The summary appears in the right margin of the listing for lines in the DATA
DIVISION that contain data declarations.
(1)
Base locator used for this data item
(2)
Hexadecimal displacement from the beginning of the base locator value
(3)
Hexadecimal displacement from the beginning of the containing structure
Chapter 17. Debugging
325
Pseudoassembler code showing how the data is defined
(4)
Terms used in MAP output
This table describes the terms used in the listings produced by the MAP option.
Term
|
Definition
Description
1
Fixed-length group data item
GROUP
DS 0CLn
ALPHABETIC
DS nC
Alphabetic data item (PICTURE A)
ALPHA-EDIT
DS nC
Alphabetic-edited data item
DISPLAY
DS nC
Alphanumeric data item (PICTURE X)
AN-EDIT
DS nC
Alphanumeric-edited data item
1
GRP-VARLEN
DS 0LCn
Variable-length group data item
NUM-EDIT
DS nC
Numeric-edited data item
DISP-NUM
DS nC
External decimal data item (USAGE DISPLAY)
BINARY
DS 1H , 1F , 2F , 2C, 4C, or
8C
Binary data item (USAGE BINARY or USAGE COMPUTATIONAL or
USAGE COMPUTATIONAL-5)
COMP-1
DS 4C
Single-precision floating-point data item (USAGE
COMPUTATIONAL-1)
COMP-2
DS 8C
Double-precision floating-point data item (USAGE
COMPUTATIONAL-2)
PACKED-DEC
DS nP
Internal decimal data item (USAGE PACKED-DECIMAL or USAGE
COMPUTATIONAL-3)
DBCS
DS nC
DBCS data item (USAGE DISPLAY-1)
DBCS-EDIT
DS nC
DBCS edited data item (USAGE DISPLAY-1)
2
2
2
INDX-NAME
Index name
INDEX
Index data item (USAGE INDEX)
OBJECT-REF
Object-reference data item (USAGE OBJECT-REFERENCE)
POINTER
Pointer data item (USAGE POINTER)
FD
File definition
VSAM, QSAM,
LINESEQ
File processing method
1-49, 77
Level numbers for data descriptions
66
Level number for RENAMES
88
Level number for condition-names
SD
Sort file definition
1. n is the size in bytes for fixed-length groups and the maximum size in bytes for variable-length groups.
2. If the SYNCHRONIZED clause appears, these fields are used.
Symbols used in LIST and MAP output
This table describes the symbols used in the listings produced by the LIST or MAP
option.
Symbol
Definition
APBdisp=n1
ALL subscript parameter block displacement
AVN=n1
Variable name cell for ALTER statement
326
Programming Guide
Symbol
Definition
1
Base locator for special registers
BL=n
1
BLA=n
Base locator for alphanumeric temporaries4
BLF=n1
Base locator for files
1
Base locator for LOCAL-STORAGE
1
Base locator for linkage section
1
Base locator for object instance data
BLK=n
BLL=n
BLO=n
1
Base locator for sort items
BLS=n
1
Base locator for variably located data
BLV=n
1
Base locator for WORKING-STORAGE
BLW=n
1
Base locator for external data
1
Base locator for constant global table (CGT)
BLX=n
CBL=n
Load list entry address in TGT
CLLE=@
CLO=n
1
DOV=n
Class object cell
DSA overflow cell
1
1
Evaluate boolean cell
EVALUATE=n
1
File control block (FCB) address
FCB=n
2.
Generated procedure name and its offset in hexadecimal
GN=n(hhhhh)
1
Base locator for index names
1
Index cell number
IDX=n
IDX=n
1
Index cell for LOCAL-STORAGE table or instance variable
ILS=n
ODO save cell number
1
ODOSAVE=n
3
Optimizer temporary storage cell
OPT=nnnn
1
Base locator for procedure code
PBL=n
PERFORM n times cells
1
PFM=n
3
PGMLIT AT + nnnn
1
Perform save cell number
PSV=n
PVN=n
Displacement for program literal from beginning of literal pool
Variable name cell for PERFORM statement
1
1
Register backstore cell
RBKST=n
1
Secondary file control block for external file
SFCB=n
3
SYSLIT AT + nnnn
Displacement for system literal from beginning of system literal pool
TGT FDMP TEST INFO. AREA +
nnnn3
FDUMP/TEST information area
TGTFIXD + nnnn3
Offset from beginning of fixed portion of task global table (TGT)
TOV=n
1
TGT overflow cell number
TS1=aaaa
Temporary storage cell number in subpool 1
TS2=aaaa
Temporary storage cell number in subpool 2
TS3=aaaa
Temporary storage cell number in subpool 3
TS4=aaaa
Temporary storage cell number in subpool 4
V(routine name)
Assembler VCON for external routine
1
Variable length name cell number (ODO)
1
Variable name initialization
VLC=n
VNI=n
Chapter 17. Debugging
327
Symbol
WHEN=n
Definition
1
Evaluate WHEN cell number
1. n is the number of the entry.
2. (hhhhh) is the program offset in hexadecimal.
3. nnnn is the offset in decimal from the beginning of the entry.
4. Alphanumeric temporaries are temporary data values used in processing alphanumeric intrinsic function and
alphanumeric EVALUATE statement subjects.
Example: nested program map
This example shows a map of nested procedures produced by specifying the MAP
compiler option.
(1)
Explanations of the program attribute codes
(2)
Source line number where the program was defined
(3)
Depth of program nesting
(4)
Program name
(5)
Program attribute codes
Reading LIST output
Parts of the LIST compiler output might be useful to you for debugging your
program. You do not need to be able to program in assembler language to
understand the output produced by LIST. The comments that accompany most of
the assembler code provide you with a conceptual understanding of the functions
performed by the code.
The LIST compiler option produces seven pieces of output:
v An assembler listing of the initialization code for the program (program
signature information bytes) from which you can verify program characteristics
such as these:
– Compiler options in effect
– Types of data items present
– Verbs used in the PROCEDURE DIVISION
v An assembler listing of the source code for the program
From the address in storage of the instruction that was executing when an abend
occurred, you can find the COBOL verb corresponding to that instruction. After
you have found the address of the failing instruction, go to the assembler listing
and find the verb for which that instruction was generated.
v Location of compiler-generated tables in the object module
328
Programming Guide
v Map of the task global table (TGT), including information on the program global
table (PGT) and constant global table (CGT)
Use the TGT to find information about the environment in which your program
is running.
v Information on the location and size of WORKING-STORAGE and control blocks
You can use the WORKING-STORAGE piece of LIST output to find the location of
data items defined in WORKING-STORAGE. (The beginning location of
WORKING-STORAGE is not shown for programs compiled with the RENT option.)
v Map of the dynamic save area (DSA)
The map of the DSA (also known as the stack frame) contains information about
the contents of the storage acquired every time a separately compiled procedure
is entered.
v Information on the location of literals and code for dynamic storage usage
“Example:
“Example:
“Example:
“Example:
“Example:
program initialization code”
assembler code generated from source code” on page 336
TGT memory map” on page 338
location and size of WORKING-STORAGE” on page 339
DSA memory map” on page 339
RELATED TASKS
Interpret a particular instruction (System/390 Reference Summary)
RELATED REFERENCE
The stack frame section (Language Environment Debugging Guide and Run-Time
Messages)
Example: program initialization code
A listing of the program initialization code gives you information about the
characteristics of the COBOL source program. Interpret the program signature
information bytes to verify characteristics of your program.
Chapter 17. Debugging
329
330
(1)
Offset from the start of the COBOL program.
(2)
Hexadecimal representation of assembler instructions.
Programming Guide
(3)
Pseudoassembler code generated for the COBOL program.
(4)
Comments explaining the assembler code.
(5)
“Eye catcher” indicating the COBOL compiler used to compile this
program.
(6)
Address of the task global table (TGT), or the address of the dynamic
access block (DAB), if the program is reentrant.
(7)
Program name as used in the IDENTIFICATION DIVISION of the program.
(8)
Four-digit year when the program was compiled.
(9)
Month and the day when the program was compiled.
(10)
Time when the program was compiled.
(11)
Version, release, and modification level of the COBOL compiler used to
compile this program (each represented in two digits).
(12)
Program signature information bytes. These provide information about the
following for this program:
v Compiler options
v DATA DIVISION
v ENVIRONMENT DIVISION
v PROCEDURE DIVISION
(13)
Number of statements in the DATA DIVISION.
(14)
Number of statements in the PROCEDURE DIVISION.
(15)
4-byte user-controlled level information field. The value of this field is
controlled by the LVLINFO.
RELATED REFERENCES
“Signature
“Signature
“Signature
“Signature
“Signature
information
information
information
information
information
bytes:
bytes:
bytes:
bytes:
bytes:
compiler options”
DATA DIVISION” on page 333
ENVIRONMENT DIVISION” on page 333
PROCEDURE DIVISION verbs” on page 333
more PROCEDURE DIVISION items” on page 335
Signature information bytes: compiler options
This table shows program signature information that is part of the listing of
program initialization code provided when you use the LIST compiler option.
Byte
Bit
On
Off
1
0
ADV
NOADV
1
APOST
QUOTE
2
DATA(31)
DATA(24)
3
DECK
NODECK
4
DUMP
NODUMP
5
DYNAM
NODYNAM
6
FASTSRT
NOFASTSRT
7
reserved
Chapter 17. Debugging
331
Byte
Bit
On
Off
2
0
LIB
NOLIB
1
LIST
NOLIST
2
MAP
NOMAP
3
NUM
NONUM
4
OBJ
NOOBJ
5
OFFSET
NOOFFSET
6
OPTIMIZE
NOOPTIMIZE
7
DDNAME supplied in OUTDD option
will be used
Default DDNAME for OUTDD will be
used
0
NUMPROC(PFD)
NUMPROC(NOPFD)
1
RENT
NORENT
2
reserved
3
SEQUENCE
NOSEQUENCE
4
SIZE(MAX)
SIZE(value)
5
SOURCE
NOSOURCE
6
SSRANGE
NOSSRANGE
7
TERM
NOTERM
0
TEST
NOTEST
1
TRUNC(STD)
TRUNC(OPT)
2
User-Supplied Reserved Word List Installation Default Reserved
Word List
3
VBREF
NOVBREF
4
XREF
NOXREF
5
ZWB
NOZWB
6
NAME
NONAME
7
CMPR2
NOCMPR2
0
NUMPROC(MIG)
1
NUMCLS(ALT)
NUMCLS(PRIM)
2
DBCS
NODBCS
3
AWO
NOAWO
4
TRUNC(BIN)
not TRUNC(BIN)
6
CURRENCY
NOCURRENCY
7
Compilation unit is a CLASS
Compilation unit is a program
0
RMODE(ANY)
RMODE(24)
1
TEST(STMT)
not TEST(STMT)
2
TEST(PATH)
not TEST(PATH)
3
TEST(BLOCK)
not TEST(BLOCK)
4
OPT(FULL)
OPT(STD) or NOOPT
5
INTDATE(LILIAN)
INTDATE(ANSI)
6
TEST(SEPARATE)
not TEST(SEPARATE)
3
4
5
26
|
332
Programming Guide
Byte
Bit
On
Off
27
0
PGMNAME(LONGUPPER)
not PGMNAME(LONGUPPER)
1
PGMNAME(LONGMIXED)
not PGMNAME(LONGMIXED)
2
DLL
NODLL
3
EXPORTALL
NOEXPORTALL
4
DATEPROC
NODATEPROC
5
ARITH(EXTEND)
ARITH(COMPAT)
|
Signature information bytes: DATA DIVISION
This table shows program signature information that is part of the listing of
program initialization code provided when you use the LIST compiler option.
Byte
Bit
Item
6
0
QSAM file descriptor
1
VSAM sequential file descriptor
2
VSAM indexed file descriptor
3
VSAM relative file descriptor
4
CODE-SET clause (ASCII files) in file descriptor
5
Spanned records
6
PIC G or PIC N (DBCS data item)
7
OCCURS DEPENDING ON clause in data description entry
0
SYNCHRONIZED clause in data description entry
1
JUSTIFIED clause in data description entry
2
USAGE IS POINTER item
3
Complex OCCURS DEPENDING ON clause
4
External floating-point items in the DATA DIVISION
5
Internal floating-point items in the DATA DIVISION
6
Line-sequential file
7
USAGE IS PROCEDURE-POINTER item
7
|
RELATED REFERENCES
“LIST” on page 281
Signature information bytes: ENVIRONMENT DIVISION
This table shows program signature information that is part of the listing of
program initialization code provided when you use the LIST compiler option.
Byte
Bit
Item
8
0
FILE STATUS clause in FILE-CONTROL paragraph
1
RERUN clause in I-O-CONTROL paragraph of INPUT-OUTPUT
SECTION
2
UPSI switch defined in SPECIAL-NAMES paragraph
Signature information bytes: PROCEDURE DIVISION verbs
This table shows program signature information that is part of the listing of
program initialization code provided when you use the LIST compiler option.
Chapter 17. Debugging
333
Byte
Bit
Item
9
0
ACCEPT
1
ADD
2
ALTER
3
CALL
4
CANCEL
6
CLOSE
0
COMPUTE
2
DELETE
4
DISPLAY
5
DIVIDE
1
END-PERFORM
2
ENTER
3
ENTRY
4
EXIT
6
GO TO
7
IF
0
INITIALIZE
1
INVOKE
2
INSPECT
3
MERGE
4
MOVE
5
MULTIPLY
6
OPEN
7
PERFORM
0
READ
2
RELEASE
3
RETURN
4
REWRITE
5
SEARCH
7
SET
0
SORT
1
START
2
STOP
3
STRING
4
SUBTRACT
7
UNSTRING
10
11
12
13
14
334
Programming Guide
Byte
Bit
Item
15
0
USE
1
WRITE
2
CONTINUE
3
END-ADD
4
END-CALL
5
END-COMPUTE
6
END-DELETE
7
END-DIVIDE
0
END-EVALUATE
1
END-IF
2
END-MULTIPLY
3
END-READ
4
END-RETURN
5
END-REWRITE
6
END-SEARCH
7
END-START
0
END-STRING
1
END-SUBTRACT
2
END-UNSTRING
3
END-WRITE
4
GOBACK
5
EVALUATE
7
SERVICE statement
0
END-INVOKE
16
17
18
Check return code: A return code greater than 4 from the compiler could mean
that some of the verbs shown as being in the program in information bytes might
have been discarded because of an error.
Signature information bytes: more PROCEDURE DIVISION items
This table shows program signature information that is part of the listing of
program initialization code provided when you use the LIST compiler option.
Byte
Bit
Item
21
0
Hexadecimal literal
1
Altered GO TO
2
I-O ERROR declarative
3
LABEL declarative
4
DEBUGGING declarative
5
Program segmentation
6
OPEN. . .EXTEND
7
EXIT PROGRAM
Chapter 17. Debugging
335
Byte
Bit
Item
22
0
CALL literal
1
CALL identifier
2
CALL. . .ON OVERFLOW
3
CALL. . .LENGTH OF
4
CALL. . .ADDRESS OF
5
CLOSE. . .REEL/UNIT
6
Exponentiation used
7
Floating-point items used
0
COPY
1
BASIS
2
DBCS name in program
3
SHIFT-OUT and SHIFT-IN in program
4-7
Highest error severity at entry to ASM2 module IGYBINIT
0
DBCS literal
1
REPLACE
2
Reference modification was used
3
Nested program
4
INITIAL
5
COMMON
6
SELECT . . . OPTIONAL
7
EXTERNAL
0
GLOBAL
1
RECORD IS VARYING
2
ACCEPT FROM SYSIPT used in LABEL declarative
3
DISPLAY UPON SYSLST used in LABEL declarative
4
DISPLAY UPON SYSPCH used in LABEL declarative
5
Intrinsic function was used
23
24
25
RELATED REFERENCES
“LIST” on page 281
Example: assembler code generated from source code
The following example shows a listing of the assembler code that is generated
from source code when you use the LIST compiler option. You can use this listing
to find the COBOL verb corresponding to the instruction that failed.
336
Programming Guide
DATA VALIDATION AND UPDATE PROGRAM
000433 MOVE
000435 READ
000436 SET (1)
(2)
000F26 92E8
000F2A
000F2A 47F0
000F2E
000439 IF
000F2E 95E8
000F32 4780
000440 DISPLAY
000F36 5820
000F3A 58F0
000F3E 4110
000F42 05EF
000443 CALL
000F44 4130
000F48 5030
000F4C 9680
000F50 4110
000F54 58F0
000F58 05EF
000F5A 50F0
000F5E BF38
000F62 0430
000F64
000F64 5820
000F68 07F2
(1)
(3)
A00A
B426
GN=13
GN=74
IGYTCARA
Date 03/30/2000 Time 12:26:53 Page
(5)
MVI 10(10),X'E8'
EQU *
BC
15,1062(0,11)
EQU *
(6)
LOCATION-EOF-FLAG
GN=75(000EFA)
A00A
B490
CLI
BC
10(10),X'E8'
8,1168(0,11)
LOCATION-EOF-FLAG
GN=14(000F64)
D05C
202C
97FF
L
L
LA
BALR
2,92(0,13)
15,44(0,2)
1,2047(0,9)
14,15
TGTFIXD+92
V(IGZCDSP )
PGMLIT AT +1999
A012
D21C
D21C
D21C
9000
D078
D089
(4)
D154
GN=14
52
LA
3,18(0,10)
ST
3,540(0,13)
OI
540(13),X'80'
LA
1,540(0,13)
L
15,0(0,9)
BALR 14,15
ST
15,120(0,13)
ICM 3,8,137(13)
SPM 3,0
EQU *
L
2,340(0,13)
BCR 15,2
COMP-CODE
TS2=4
TS2=4
TS2=4
V(ILBOABN0)
TGTFIXD+120
TGTFIXD+137
VN=3
Source line number and COBOL verb, paragraph name, or section name
In line 000436, SET is the COBOL verb. An asterisk (*) before a name
indicates that the name is a paragraph name or a section name.
(2)
Relative location of the object code instruction in the module, in
hexadecimal notation
(3)
Object code instruction, in hexadecimal notation
The first two or four hexadecimal digits are the instruction, and the
remaining digits are the instruction operands. Some instructions have two
operands.
(4)
Compiler-generated names (GN) for code sequences
(5)
Object code instruction in a form that closely resembles assembler
language
(6)
Comments about the object code instruction:
v One or two operands participating in the machine instructions are
displayed on the right. An asterisk immediately follows the data names
that are defined in more than one structure (in that way made unique by
qualification in the source program).
v The relative location of any generated label appearing as an operand is
displayed in parentheses.
RELATED REFERENCES
“Symbols used in LIST and MAP output” on page 326
Chapter 17. Debugging
337
Example: TGT memory map
The following example shows LIST output for the task global table (TGT) with
information about the environment in which your program runs.
DATA VALIDATION AND UPDATE PROGRAM
IGYTCARA
*** TGT MEMORY MAP ***
(1)
(2)
(3)
PGMLOC TGTLOC
005160
0051A8
0051AC
0051B0
0051B1
0051B4
0051B8
0051BC
0051C0
0051C4
0051C8
0051CC
0051D0
0051D4
0051D8
0051DA
0051DC
0051DE
0051E0
0051E4
0051E8
0051E9
0051EA
0051EC
0051F0
0051F4
0051F8
005200
005208
00520C
005240
005244
005248
00524C
005250
005254
005258
00525C
005260
005264
005268
00526C
005270
005274
005278
00527C
000000
000048
00004C
000050
000051
000054
000058
00005C
000060
000064
000068
00006C
000070
000074
000078
00007A
00007C
00007E
000080
000084
000088
000089
00008A
00008C
000090
000094
000098
0000A0
0000A8
0000AC
0000E0
0000E4
0000E8
0000EC
0000F0
0000F4
0000F8
0000FC
000100
000104
000108
00010C
000110
000114
000118
00011C
Date 03/30/2000 Time 12:26:53 Page
RESERVED - 72 BYTES
TGT IDENTIFIER
RESERVED - 4 BYTES
TGT LEVEL INDICATOR
RESERVED - 3 SINGLE BYTE FIELDS
32 BIT SWITCH
POINTER TO RUNCOM
POINTER TO COBVEC
POINTER TO PROGRAM DYNAMIC BLOCK TABLE
NUMBER OF FCB'S
WORKING-STORAGE LENGTH
RESERVED - 4 BYTES
ADDRESS OF IGZESMG WORK AREA
ADDRESS OF 1ST GETMAIN BLOCK (SPACE MGR)
RESERVED - 2 BYTES
RESERVED - 2 BYTES
RESERVED - 2 BYTES
MERGE FILE NUMBER
ADDRESS OF CEL COMMON ANCHOR AREA
LENGTH OF TGT
RESERVED - 1 SINGLE BYTE FIELD
PROGRAM MASK USED BY THIS PROGRAM
RESERVED - 2 SINGLE BYTE FIELDS
NUMBER OF SECONDARY FCB CELLS
LENGTH OF THE ALTER VN(VNI) VECTOR
COUNT OF NESTED PROGRAMS IN COMPILE UNIT
DDNAME FOR DISPLAY OUTPUT
RESERVED - 8 BYTES
POINTER TO COM-REG SPECIAL REGISTER
CALC ROUTINE REGISTER SAVE AREA
ALTERNATE COLLATING SEQUENCE TABLE PTR.
ADDRESS OF SORT G.N. ADDRESS BLOCK
ADDRESS OF PGT
CURRENT INTERNAL PROGRAM NUMBER
POINTER TO 1ST IPCB
ADDRESS OF THE CLLE FOR THIS PROGRAM
POINTER TO ABEND INFORMATION TABLE
POINTER TO TEST INFO FIELDS IN THE TGT
ADDRESS OF START OF COBOL PROGRAM
POINTER TO ALTER VNI'S IN CGT
POINTER TO ALTER VN'S IN TGT
POINTER TO FIRST PBL IN THE PGT
POINTER TO FIRST FCB CELL
WORKING-STORAGE ADDRESS
POINTER TO FIRST SECONDARY FCB CELL
POINTER TO STATIC CLASS INFO BLOCK
*** VARIABLE PORTION OF TGT ***
005280
005288
005290
005294
0052A8
0052AC
0052C8
338
Programming Guide
000120
000128
000130
000134
000148
00014C
000168
BASE LOCATORS FOR SPECIAL REGISTERS
BASE LOCATORS FOR WORKING-STORAGE (4)
BASE LOCATORS FOR LINKAGE-SECTION
BASE LOCATORS FOR FILES
BASE LOCATORS FOR ALPHANUMERIC TEMPS
CLLE ADDR. CELLS FOR CALL LIT. SUB-PGMS.
INDEX CELLS
132
0052EC
005300
005364
00018C
0001A0
000204
FCB CELLS
ALL PARAMETER BLOCK
INTERNAL PROGRAM CONTROL BLOCKS
(1)
Hexadecimal offset of the TGT field from the start of the COBOL program
(not shown for programs compiled with the RENT option)
(2)
Hexadecimal offset of the TGT field from the start of the TGT
(3)
Explanation of the contents of the TGT field
(4)
TGT fields for the base locators of COBOL data areas
Example: location and size of WORKING-STORAGE
The following example shows LIST output about the WORKING-STORAGE for a NORENT
program.
(1)
(2)
(3)
WRK-STOR LOCATED AT 0066D8 FOR 00001598 BYTES
(1)
WORKING-STORAGE identification
(2)
Hexadecimal offset of WORKING-STORAGE from the start of the COBOL
program
(3)
Length of WORKING-STORAGE in hexadecimal
Example: DSA memory map
The following example shows LIST output for the dynamic save area (DSA), which
contains information about the contents of the storage acquired when a separately
compiled procedure is entered.
DATA VALIDATION AND UPDATE PROGRAM
*** DSA MEMORY MAP ***
(1)
(2)
DSALOC
000000
00004C
00005C
000058
000080
IGYTCARA
Date 03/30/2000 Time 12:26:53 Page
139
REGISTER SAVE AREA
STACK NAB (NEXT AVAILABLE BYTE)
ADDRESS OF TGT
ADDRESS OF INLINE-CODE PRIMARY DSA
PROCEDURE DIVISION RETURNING VALUE
*** VARIABLE PORTION OF DSA ***
000084 BACKSTORE CELLS FOR SYMBOLIC REGISTERS
00009C VARIABLE-LENGTH CELLS
0000A8 ODO SAVE CELLS
0000B4 VARIABLE NAME (VN) CELLS FOR PERFORM
000124 PERFORM SAVE CELLS
000250 TEMPORARY STORAGE-1
000260 TEMPORARY STORAGE-2
000430 OPTIMIZER TEMPORARY STORAGE
(1)
Hexadecimal offset of the dynamic save area (DSA) field from the start of
the DSA
(2)
Explanation of the contents of the DSA field
Chapter 17. Debugging
339
Example: XREF output - data-name cross-references
The following example shows a sorted cross-reference of data names, produced by
the XREF compiler option.
Cross-reference of data names:
(1)
Line number where the name was defined.
(2)
Data name.
(3)
Line numbers where the name was used. If M precedes the line number, the
data item was explicitly modified at the location.
Cross-reference of procedure references:
340
(4)
Explanations of the context usage codes for procedure references
(5)
Line number where the procedure name is defined
(6)
Procedure name
(7)
Line numbers where the procedure is referenced and the context usage
code for the procedure
Programming Guide
Example: XREF output - program-name cross-references
The following example shows a sorted cross-reference of program names,
produced by the XREF compiler option.
(1)
Line number where the program name was defined. If the program is
external, the word EXTERNAL is displayed instead of a definition line
number.
(2)
Program name.
(3)
Line numbers where the program is referenced.
Example: embedded cross-reference
The following example shows a modified cross-reference embedded in the source
listing, produced by the XREF compiler option.
(1)
Line number of the definition of the data name or procedure name in the
program
(2)
Special definition symbols:
UND
The user name is undefined.
Chapter 17. Debugging
341
DUP
The user name is defined more than once.
IMP
Implicitly defined name, such as special registers and figurative
constants
IFN
Intrinsic function reference
EXT
External reference
*
The program name is unresolved because the NOCOMPILE option is
in effect.
Example: OFFSET compiler output
The following example shows a listing that has a condensed verb listing, global
tables, WORKING-STORAGE information, and literals. It is output from the OFFSET
compiler option.
DATA VALIDATION AND UPDATE PROGRAM
IGYTCARA Date 03/30/2000 Time 12:26:53 Page
. . .
(1)
(2)
(3)
LINE # HEXLOC VERB
LINE # HEXLOC VERB
LINE # HEXLOC VERB
000880 0026F0 DISPLAY
000881 002702 PERFORM
000933 002702 OPEN
000934 002722 IF
000935 00272C DISPLAY
000936 002736 PERFORM
001389 002736 DISPLAY
001390 002740 DISPLAY
001391 00274A DISPLAY
001392 002754 DISPLAY
001393 00275E DISPLAY
001394 002768 DISPLAY
001395 002772 DISPLAY
000937 00277C PERFORM
001434 00277C DISPLAY
001435 002786 STOP
000939 0027A2 MOVE
000940 0027AC WRITE
000941 0027D6 IF
000942 0027E0 DISPLAY
000943 0027EA PERFORM
001389 0027EA DISPLAY
001390 0027F4 DISPLAY
001391 0027FE DISPLAY
001392 002808 DISPLAY
001393 002812 DISPLAY
001394 00281C DISPLAY
001395 002826 DISPLAY
000944 002830 DISPLAY
000945 00283A PERFORM
001403 00283A DISPLAY
001404 002844 DISPLAY
001405 00284E DISPLAY
001406 002858 DISPLAY
001407 002862 CALL
000947 002888 CLOSE
(1)
Line number. Your line numbers or compiler-generated line numbers are
listed.
(2)
Offset, from the start of the program, of the code generated for this verb
(in hexadecimal notation).
The verbs are listed in the order in which they occur and once for each
time they are used.
(3)
Verb used.
RELATED REFERENCES
“OFFSET” on page 285
342
Programming Guide
54
Example: VBREF compiler output
The following example shows an alphabetic listing of all the verbs in your
program and where each is referenced. The listing is produced by the VBREF
compiler option.
(1) Number of times the verb is used in the program
(2) Verb
(3) Line numbers where the verb is used
Preparing to use the debugger
Use the TEST option to prepare your executable COBOL program for use with the
debugger.
|
|
The Debug Tool debugger is provided with the Full Function feature of the
COBOL for OS/390 & VM compiler. To use Debug Tool to step through a run of
your program, specify the TEST compiler option. For remote debugging, the
Distributed Debugger provides the client graphical user interface to the debug
information provided by the Debug Tool engine running on OS/390 or OS/390
UNIX.
|
|
|
|
|
You can specify the TEST suboption SEPARATE to have the symbolic information
tables for the Debug Tool generated in a data set separate from your object
module. And you can enable your COBOL program for debugging using overlay
hooks (production debugging), rather than compiled-in hooks, which have some
performance degradation even when the run-time TEST option is off.
RELATED TASKS
Debug Tool User’s Guide and Reference
Chapter 17. Debugging
343
RELATED REFERENCES
“TEST” on page 295
344
Programming Guide
Part 3. Targeting COBOL programs for certain environments
Chapter 18. Developing COBOL programs for
CICS . . . . . . . . . . . . . . . . 347
Coding COBOL programs to run under CICS . . 347
Coding file input and output . . . . . . . 348
Retrieving the system date and time. . . . . 348
Displaying the contents of data items . . . . 348
Calling to or from COBOL programs . . . . 348
Coding a COBOL program to run above the
16-MB line . . . . . . . . . . . . . 349
Determining the success of ECI calls. . . . . 349
Preparing COBOL programs to run under CICS
350
Using the CICS translator . . . . . . . . 350
Compiling your CICS program . . . . . . 350
CICS reserved-word table . . . . . . . . 351
Handling errors by using CICS HANDLE . . . . 352
Example: handling errors by using CICS
HANDLE . . . . . . . . . . . . . 352
Chapter 19. Programming for a DB2
environment . . . . . . . . . . .
Coding SQL statements . . . . . . . .
Using SQL INCLUDE . . . . . . .
Using binary items . . . . . . . .
Determining the success of SQL statements
Compiling with the SQL option . . . . .
Compiling in batch . . . . . . . .
Separating DB2 suboptions . . . . . .
DB2 coprocessor . . . . . . . . .
Run-time message IGZ0002S .
.
.
.
.
.
.
. 370
Chapter 23. Accessing COBOL programs
interactively with ISPF . . . . . . . .
.
. 371
. . 355
. . 355
. . 355
. . 355
. . 356
. . 356
. . 357
. . 357
. . 358
Chapter 20. Running COBOL programs under
IMS . . . . . . . . . . . . . . . . 359
Compiling and linking COBOL programs for
running under IMS . . . . . . . . . . . 359
Chapter 21. Running COBOL programs under
OS/390 UNIX . . . . . . . . . . . . .
Running in OS/390 UNIX environments . . . .
Setting and accessing environment variables . . .
Setting environment variables that affect
execution . . . . . . . . . . . . . .
Environment variables of interest for COBOL
programs . . . . . . . . . . . . .
Resetting environment variables . . . . . .
Accessing environment variables . . . . . .
Example: accessing environment variables . . .
Calling UNIX/POSIX APIs . . . . . . . . .
fork, exec, and spawn . . . . . . . . .
Samples . . . . . . . . . . . . . .
Accessing main program parameters . . . . .
Example: accessing main program parameters
361
361
362
362
363
363
363
363
364
364
365
365
366
Chapter 22. Running COBOL programs under
CMS . . . . . . . . . . . . . . . . 369
Run-time restrictions under CMS . . . . . . . 369
Handling QSAM files under CMS . . . . . . 369
© Copyright IBM Corp. 1991, 2000
345
346
Programming Guide
Chapter 18. Developing COBOL programs for CICS
COBOL for OS/390 & VM programs written for CICS can run under CICS/ESA
and CICS Transaction Server. You must use the CICS command level interface to
write CICS COBOL application programs. COBOL programs cannot use the CICS
macro level interface.
The CICS translator converts the EXEC CICS commands in your source program to
COBOL code. The translator replaces each EXEC CICS command with one or more
COBOL statements, one of which is a CALL statement.
After compiling and link-editing your program, you need to do some other steps
such as updating CICS tables before you can run the COBOL program under CICS.
However, these CICS topics are beyond the focus of this COBOL information.
RELATED TASKS
“Coding COBOL programs to run under CICS”
“Preparing COBOL programs to run under CICS” on page 350
“Handling errors by using CICS HANDLE” on page 352
Coding COBOL programs to run under CICS
To code your program, you need to know how to code CICS commands in the
PROCEDURE DIVISION. They have the following basic format:
EXEC CICS command name and command options
END-EXEC
Observe these guidelines when coding your COBOL programs to run under CICS:
v Do not use EXEC, CICS, or END-EXEC for variable names.
v Do not use the FILE-CONTROL entry in the ENVIRONMENT DIVISION, unless the
FILE-CONTROL entry is being used for a SORT statement.
v Do not use the FILE SECTION of the DATA DIVISION, unless the FILE SECTION is
being used for a SORT statement.
v Do not use user-specified parameters to the main program.
v Do not use USE declaratives (except USE FOR DEBUGGING).
v Do not use these COBOL language statements:
ACCEPT format 1: data transfer (you can use format-2 ACCEPT to retrieve the
system date and time)
CLOSE
DELETE
DISPLAY UPON SYSPUNCH
DISPLAY UPON CONSOLE
MERGE
OPEN
READ
RERUN
REWRITE
START
STOP literal
WRITE
|
|
|
|
© Copyright IBM Corp. 1991, 2000
347
v REPLACE statements that contain EXEC commands must occur after the PROCEDURE
DIVISION statement of the program for the EXEC commands to be translated.
v When coding nested (contained) programs, pass DFHEIBLK and DFHCOMMAREA as
parameters to any nested programs that contain EXEC commands or references to
the EIB (EXEC interface block). The same parameters must also be passed to any
program that forms part of the control hierarchy between such a program and
its top level program.
v The space character is not interchangeable with a comma or semicolon within
EXEC commands. In such commands, use the space as a word separator.
v You cannot use EXEC CICS statements within object-oriented COBOL class
definitions. However, COBOL methods can make calls to COBOL subprograms
that contain EXEC CICS statements. Also, COBOL programs containing EXEC CICS
statements can use COBOL INVOKE statements to invoke methods.
Coding file input and output
You must use CICS commands for most input and output processing. Therefore,
do not describe files or code any OPEN, CLOSE, READ, START, REWRITE, WRITE, or
DELETE statements. Instead, use CICS commands to retrieve, update, insert, and
delete data.
Retrieving the system date and time
You cannot not use a format-1 ACCEPT statement in a CICS program.
You can use these format-2 ACCEPT statements in the CICS environment to get the
system date:
v ACCEPT identifier-2 FROM DATE
|
|
|
|
|
|
|
v ACCEPT identifier-2 FROM DATE YYYYMMDD
v ACCEPT identifier-2 FROM DAY
v ACCEPT identifier-2 FROM DAY YYYYDDD
v ACCEPT identifier-2 FROM DAY-OF-WEEK
You can use this format-2 ACCEPT statement in the CICS environment to get the
system time:
v ACCEPT identifier-2 FROM TIME
|
|
|
The recommended way of retrieving system date and time information is using the
ACCEPT statement, because it works in all environments (CICS and non-CICS).
Displaying the contents of data items
|
|
|
DISPLAY to the system logical output device (SYSOUT, SYSLIST, SYSLST) is
supported under CICS. The DISPLAY output is written to the Language
Environment message file (transient data queue CESE).
|
|
DISPLAY . . . UPON CONSOLE and DISPLAY . . . UPON SYSPUNCH, however, are
disallowed.
Calling to or from COBOL programs
You can make calls to or from VS COBOL II, COBOL for MVS & VM, and COBOL
for OS/390 & VM programs using the CALL statement. However, COBOL for
OS/390 & VM, COBOL for MVS & VM, and VS COBOL II programs cannot call or
be called by OS/VS COBOL programs with the CALL statement. You must use EXEC
348
Programming Guide
CICS LINK instead. If you are calling a COBOL program that has been translated,
you must pass DFHEIBLK and DFHCOMMAREA as the first two parameters in the CALL
statement.
You can use CALL identifier with the NODYNAM compiler option to dynamically call a
program. Called programs can contain any function supported by CICS for the
language. You must define dynamically called programs in the CICS program
processing table (PPT), if you are not using CICS autoinstall.
The ON OVERFLOW phrase and ON EXCEPTION phrase of the CALL statement are
supported under CICS unless the program has been compiled with the CMPR2
compiler option. In that case, no conditions under CICS will cause the statement
specified by the ON OVERFLOW to be performed.
Support for interlanguage communication (ILC) with other HLL languages is
available. Where ILC is not supported, you can use CICS LINK, XCTL, and RETURN
instead.
Assembler-language programs that conform to the interface described in the
Language Environment Programming Guide are called Language Environmentconforming assembler programs. Those that do not conform to the interface are
non-Language Environment-conforming assembler programs. The following table
shows the calling relationship between COBOL and assembler-language programs.
Language
Environment-conforming
assembler program
Non-Language
Environment-conforming
assembler program
Yes
Yes
From the assembler program Yes
to a COBOL for OS/390 &
VM program?
No
Calls between COBOL and
assembler programs
From a COBOL for OS/390
& VM program to the
assembler program?
Coding a COBOL program to run above the 16-MB line
Under OS/390, these restrictions apply when you code a COBOL program to run
above the 16-MB line:
v If you are using IMS/ESA Version 3 (or later) without DBCTL, DL/I CALL
statements are supported only if all the data passed on the call resides below the
16-MB line. Therefore, you must specify the DATA(24) compiler option. However,
if you are using IMS/ESA Version 3 (or later) with DBCTL, you can use the
DATA(31) compiler option instead and pass data that resides above the 16-MB
line.
If you use EXEC DLI instead of DL/I CALL statements, you can specify DATA(31),
regardless of the IMS product level.
v If the receiving program is link-edited with AMODE=31, addresses passed must be
31 bits long, or 24 bits long with the leftmost byte set to zeros.
v If the receiving program is link-edited with AMODE=24, addresses passed must be
24 bits long.
Determining the success of ECI calls
The external CICS interface (ECI) does not clear register 15 at termination,
regardless of whether your COBOL program executes normally or not. Therefore,
Chapter 18. Developing COBOL programs for CICS
349
even if your COBOL program terminates normally after successfully using the
external CICS interface, the job step could end with an undefined return code.
To ensure that a meaningful return code is given at termination, set the job step
return code before terminating your program. Keep the COBOL convention of
storing its RETURN-CODE special register into register 15 by saving the response code
from the last call to the external CICS interface and moving it to special register
RETURN-CODE before terminating.
RELATED TASKS
Writing ILC applications (Language Environment Writing ILC Applications)
RELATED REFERENCES
CICS/ESA V4R1 External CICS Interface, SC33-1390
Preparing COBOL programs to run under CICS
To prepare you COBOL program to run under CICS you must use the CICS
translator to convert the CICS commands to COBOL statement and compile and
link the program to create the executable module.
Using the CICS translator
To run a COBOL program that includes CICS commands, you must use the CICS
translator to convert the EXEC CICS commands into COBOL code. When you
translate COBOL for OS/390 & VM programs, use the COBOL3 translator option.
When you use the COBOL3 translator option, it causes the following line to be
inserted:
CBL RENT,NODYNAM,LIB
You can suppress the insertion of a CBL statement by using the CICS translator
option NOCBLCARD.
CICS features the translator option ANSI85, which supports these language features
(introduced by the COBOL 85 Standard):
v Blank lines intervening in literals
v Sequence numbers containing any character
v Lowercase characters supported in all COBOL words
v REPLACE statement
v Batch compilation
v
v
v
v
v
Nested programs
Reference modification
GLOBAL variables
Interchangeability of comma, semicolon, and space
Symbolic character definition
Compiling your CICS program
To run a COBOL program under CICS, you must use the following compiler
options when you compile the program:
Required compiler option
RENT
350
Programming Guide
Condition
Required compiler option
Condition
NODYNAM
The program is translated by the CICS translator.
LIB
The program contains a COPY or BASIS statement.
In addition, you might want to use the following recommended options under
certain circumstances:
Recommended compiler option
Condition
TRUNC(OPT)
All binary data items conform to the PICTURE and
USAGE clause for those data items.
TRUNC(BIN)
Not all binary data items conform to the PICTURE and
USAGE clause for those data items.
WORD(CICS)
You want the COBOL language elements not
supported under CICS to be flagged at compile time.
For example, if you have a data item defined as PIC S9(8) BINARY that might
receive a value greater than eight digits, use TRUNC(BIN) or change the PICTURE
clause.
You might also want to avoid using an option that has no effect:
ADV
FASTSRT
OUTDD
The input data set for the compiler is the data set that you received as result of
translation, which is SYSPUNCH by default.
CICS reserved-word table
COBOL provides an alternate reserved-word table (IGYCCICS) for CICS
application programs. If you use the compiler option WORD(CICS), COBOL words
not supported under CICS are flagged by the compiler with an error message.
In addition to the COBOL words restricted by the IBM-supplied default
reserved-word table, the IBM-supplied CICS reserved-word table restricts the
following COBOL words:
CLOSE
DELETE
FD
FILE
FILE-CONTROL
INPUT-OUTPUT
I-O-CONTROL
MERGE
OPEN
READ
RERUN
REWRITE
SD
SORT
START
WRITE
If you intend to use the SORT statement under CICS (COBOL supports an interface
for the SORT statement under CICS), you must change the CICS reserved-word
table before using it. You must remove the words italicized above from the list of
words marked as restricted, because they are required for the SORT function.
RELATED TASKS
“Preparing COBOL programs to run under CICS” on page 350
Chapter 18. Developing COBOL programs for CICS
351
RELATED REFERENCES
“WORD” on page 301
Handling errors by using CICS HANDLE
The setting of the CBLPSHPOP run-time option affects the state of the HANDLE
specifications when a program calls a COBOL subprogram.
When CBLPSHPOP is ON and a COBOL subprogram (not a nested program) is called,
the following happens:
v As part of program initialization, the run time suspends the HANDLE
specifications of the calling program (with an EXEC CICS PUSH HANDLE).
v The default actions for HANDLE apply until the called program issues its own
HANDLE commands.
v As part of program termination, the run time reinstates the HANDLE specifications
of the calling program (with an EXEC CICS POP HANDLE).
When CBLPSHPOP is OFF, the run time does not perform the CICS PUSH or POP on
a call to a COBOL subprogram.
Run with CBLPSHPOP(ON) if any of your called COBOL subprograms uses one or
more of the following CICS commands:
CICS
CICS
CICS
CICS
CICS
CICS
HANDLE CONDITION
HANDLE AID
HANDLE ABEND
IGNORE CONDITION
PUSH HANDLE
POP HANDLE
If you use the CICS HANDLE CONDITION or HANDLE AID commands, the LABEL
specified for the CICS HANDLE command must be in the same PROCEDURE DIVISION
as the CICS command that causes branching to the CICS HANDLE label. You cannot
use the CICS HANDLE commands with the LABEL option to handle conditions, aids,
and abends that were caused by another program invoked using the COBOL CALL
statement. Attempts to perform cross-program branching by using the CICS HANDLE
command with the LABEL option result in a transaction abend.
If a condition, aid, or abend occurs in a nested program, the LABEL for the
condition, aid, or abend must be in the same nested program; otherwise
unpredictable results will occur.
“Example: handling errors by using CICS HANDLE”
Example: handling errors by using CICS HANDLE
The following sample code illustrates the use of CICS HANDLE in COBOL
programs. Program A has a CICS HANDLE CONDITION command and program B has
no CICS HANDLE commands. Program A calls program B; program A also calls
nested program A1.
The following shows how a condition is handled in three scenarios.
352
(1)
CBLPSHPOP(ON): If the CICS READ command in program B causes a
condition, the condition will not be handled by program A (the HANDLE
specifications have been suspended because the run time performed a
CICS PUSH HANDLE). The condition will turn into a transaction abend.
(2)
CBLPSHPOP(OFF): If the CICS READ command in program B causes a
Programming Guide
condition, the condition will not be handled by program A (the run time
will diagnose the attempt to perform cross-program branching by using a
CICS HANDLE command with the LABEL option). The condition will turn into
a transaction abend.
(3)
If the CICS READ command in nested program A1 causes a condition, the
flow of control goes to label ERR-1, and unpredictable results will occur.
***********************************************************
* Program A
*
***********************************************************
ID DIVISION.
PROGRAM-ID. A.
. . .
PROCEDURE DIVISION.
EXEC CICS HANDLE CONDITION
ERROR(ERR-1)
END-EXEC.
CALL 'B' USING DFHEIBLK DFHCOMMAREA.
CALL 'A1' USING DFHEIBLK DFHCOMMAREA.
. . .
THE-END.
EXEC CICS RETURN END-EXEC.
ERR-1.
. . .
* Nested program A1.
ID DIVISION.
PROGRAM-ID. A1.
PROCEDURE DIVISION.
EXEC CICS READ
(3)
FILE('LEDGER')
INTO(RECORD)
RIDFLD(ACCTNO)
END-EXEC.
END PROGRAM A1.
END PROGRAM A.
*
***********************************************************
* Program B
*
***********************************************************
ID DIVISION.
PROGRAM-ID. B.
. . .
PROCEDURE DIVISION.
EXEC CICS READ
(1) (2)
FILE('MASTER')
INTO(RECORD)
RIDFLD(ACCTNO)
END-EXEC.
. . .
END PROGRAM B.
Chapter 18. Developing COBOL programs for CICS
353
354
Programming Guide
Chapter 19. Programming for a DB2 environment
In general, the coding for your COBOL program will be the same whether or not
you want it to access a DB2 database. However, to retrieve, update, insert, and
delete DB2 data and use other DB2 services, you must use SQL statements.
To communicate with DB2, you need to do the following:
v Code any SQL statements you need, delimiting them with EXEC SQL and
END-EXEC statements.
v Use the DB2 precompiler or compile with the SQL compiler option if using DB2
for OS/390 Version 7 or later.
RELATED CONCEPTS
“DB2 coprocessor” on page 358
RELATED TASKS
“Coding SQL statements”
“Compiling with the SQL option” on page 356
Coding SQL statements in a COBOL application (IBM DB2 Application Programming
and SQL Guide)
RELATED REFERENCES
IBM DB2 SQL Reference
Coding SQL statements
Delimit SQL statements with EXEC SQL and END-EXEC statements. You also need to
take these special steps:
v Declare an SQL communication area (SQLCA) in the WORKING-STORAGE SECTION.
v Declare all host variables that you use in SQL statements in the WORKING-STORAGE
or LINKAGE sections.
Using SQL INCLUDE
|
|
|
|
An SQL INCLUDE statement is treated identically to a native COBOL COPY statement.
Therefore, the following two lines are treated the same way:
|
|
|
The name in an SQL INCLUDE statement follows the same rules as those for COPY
text-name and is processed identically to a COPY text-name without a REPLACING
clause.
|
|
|
The library search order for SQL INCLUDE statements is the same SYSLIB
concatenation as the compiler uses to resolve COBOL COPY statements that do not
specify a library name.
EXEC SQL INCLUDE name
COPY name
Using binary items
|
|
|
For binary data items that you specify in an SQL statement, use either of these
techniques:
v Declare them as USAGE COMP-5.
© Copyright IBM Corp. 1991, 2000
355
|
|
|
v Use the TRUNC(BIN) option if USAGE BINARY, COMP, or COMP-4 is specified. (This
might have a larger impact on performance than using USAGE COMP-5 on
individual data items.)
|
|
|
|
If you specify a USAGE BINARY, COMP, or COMP-4 item when option TRUNC(OPT) or
TRUNC(STD) or both are in effect, the compiler will accept the item but the data
might not be valid because of the decimal truncation rules. You need to ensure that
truncation does not affect the validity of the data.
Determining the success of SQL statements
When DB2 finishes executing an SQL statement, DB2 sends a return code in the
SQLCA (with one exception on OS/390) to indicate whether the operation
succeeded or failed. Your program should test the return code and take any
necessary action.
The exception on OS/390 occurs when a program runs under DSN from one of the
alternate entry points of the TSO batch mode module IKJEFT01 (IKJEFT1A or
IKJEFT1B). In this case, the return code is passed in register 15.
Because DB2 usually does not pass the return code in register 15, the COBOL
RETURN-CODE special register might contain a value that is not valid. Your COBOL
program should set the RETURN-CODE special register to a meaningful value before
returning to its caller, to keep the COBOL convention of storing its RETURN-CODE
special register into register 15.
RELATED CONCEPTS
“Formats for numeric data” on page 36
Compiling with the SQL option
|
|
|
|
You use the SQL compiler option on OS/390 to enable the DB2 coprocessor
capability and specify the DB2 suboptions. The SQL compiler option works with
embedded SQL statements only if the compiler has access to DB2 for OS/390
Version 7 or later.
|
|
|
|
|
You can specify the SQL option in any of the compiler option sources: compiler
invocation, PROCESS or CBL statements, or installation default. You cannot specify
DB2 suboptions when the SQL option is the COBOL installation default, but you
can specify default DB2 suboptions by customizing the DB2 product installation
defaults.
|
|
|
The DB2 suboption string that you provide on the SQL compiler option is made
available to the DB2 coprocessor. Only the DB2 coprocessor views the contents of
the string.
|
When you use the DB2 coprocessor, you must compile with these options:
|
|
Compiler option
Comment
SQL
If you use also NOLIB, LIB is forced on. If you use also ANALYZE,
SQL is forced off.
|
LIB
Must be specified with SQL
|
|
SIZE(xxx)
xxx is a size value (not MAX) that leaves enough storage in the
user region for the DB2 coprocessor services.
356
Programming Guide
|
|
|
You can use standard JCL procedural statements to compile your program with the
DB2 coprocessor. In addition to specifying the above compiler options, specify the
following items in your JCL:
|
|
|
|
|
v DBRMLIB DD statement with the location for the generated database request
module (DBRM).
v STEPLIB override for the COBOL step, adding the data set that contains the DB2
coprocessor services, unless these services are in the LNKLST. Typically, this data
set is DSN710.SDSNLOAD, but your installation might have changed the name.
For example, you might have the following lines in your JCL:
//DBRMLIB
//STEPLIB
DD
DD
DSN=PAYROLL.MONTHLY.DBRMLIB.DATA(MASTER),DISP=SHR
DSN=DSN710.SDSNLOAD,DISP=SHR
Compiling in batch
|
|
|
|
|
When you use the SQL option to compile a source file that contains a sequence of
COBOL programs (a batch compile sequence), the option must be in effect for the
first program of the batch sequence. If the SQL option is specified on CBL or PROCESS
cards, the CBL or PROCESS cards must precede the first program in the batch
compile sequence.
Separating DB2 suboptions
|
|
|
Because of the concatenation of multiple SQL option specifications, you can
separate DB2 suboptions (which might not fit into single CBL statement) into
multiple CBL statements.
|
|
|
|
|
|
|
|
|
|
|
The DB2 suboptions that you include in the suboption string are cumulative. The
compiler concatenates these suboptions from multiple sources in the order that
they are specified. For example, suppose that your source file has the following
code:
//STEP1 EXEC IGYWC, . . .
// PARM.COBOL='SQL(“DATABASE xxxx”)'
//COBOL.SYSIN DD *
CBL SQL(“PACKAGE USER xxxx”)
CBL SQL(“USING xxxx”)
IDENTIFICATION DIVISION.
PROGRAM-ID. DRIVER1.
|
|
|
During compilation, the compiler passes the following suboption string to the DB2
coprocessor:
|
|
|
|
The concatenated strings are delimited with single spaces. When the compiler finds
multiple instances of the same DB2 suboption, the last specification of the
suboption in the concatenated string will be in effect. The compiler limits the
length of the concatenated DB2 suboption string to 4K bytes.
“DATABASE xxxx PACKAGE USER xxxx USING xxxx”
RELATED CONCEPTS
“DB2 coprocessor” on page 358
RELATED REFERENCES
“SQL” on page 293
IBM DB2 Command Reference
Chapter 19. Programming for a DB2 environment
357
DB2 coprocessor
|
|
|
|
|
|
|
When you use the DB2 coprocessor (called SQL statement coprocessor by DB2), the
compiler handles your source program containing embedded SQL statements
without your having to use a separate precompile step. When the compiler
encounters SQL statements at significant points in the source program, it interfaces
with the DB2 coprocessor. This coprocessor takes appropriate actions on the SQL
statements and indicates to the compiler what native COBOL statements to
generate for them.
|
|
|
|
|
Although the use of a separate precompile step continues to be supported, use of
the coprocessor is recommended. Interactive debugging with Debug Tool is
enhanced when you use the coprocessor because you only see the SQL statements
in the listing (and not the generated COBOL source). However, you must have
DB2 for OS/390 Version 7 or later. The DB2 coprocessor is not supported on VM.
|
|
|
|
|
|
Compiling with the DB2 coprocessor generates a DB2 database request module
(DBRM) along with the usual COBOL compiler outputs such as object module and
listing. The DBRM writes to the data set that you specified on the DBRMLIBB DD
statement in the JCL for the COBOL compile step. As input to the DB2 bind
process, the DBRM data set contains information about the SQL statements and
host variables in the program.
|
|
The COBOL compiler listing includes the error diagnostics (such as syntax errors
in the SQL statements) that the DB2 coprocessor generates.
|
|
Certain restrictions on the use of COBOL language that apply when you use the
precompile step do not apply when you use the DB2 coprocessor:
|
|
|
v You can use SQL statements in any nested program. (With the precompiler, SQL
statements are restricted to the outermost program.)
v You can use SQL statements in copy books.
|
v REPLACE statements work on SQL statements.
RELATED TASKS
“Compiling with the SQL option” on page 356
358
Programming Guide
Chapter 20. Running COBOL programs under IMS
Although much of the coding of a COBOL program will be the same when
running under IMS, be aware of the following recommendations and restrictions.
In COBOL, IMS message processing programs (MPPs) do not use non-IMS input or
output statements such as READ, WRITE, REWRITE, OPEN, and CLOSE.
With COBOL for OS/390 & VM you can invoke IMS facilities using the following
interfaces:
v CBLTDLI call
v Language Environment callable service CEETDLI
You code calls to CEETDLI the same way as calls to CBLTDLI. CEETDLI behaves
essentially the same way as CBLTDLI.
Compiling and linking COBOL programs for running under IMS
For best performance in the IMS environment, use the RENT compiler option. It
causes COBOL to generate reentrant code. You can then run your application
programs in either preloaded mode (the programs remain resident in storage) or
nonpreload mode, without having to recompile with different options.
IMS allows COBOL programs to be preloaded. This preloading can boost
performance because subsequent requests for the program can be handled faster
when the program is already inside the processor (rather than being fetched from a
library each time it is needed).
You must use the RENT compiler option to compile a program that is to be used
only preloaded or in both a preloaded and a nonpreloaded way. When you preload
a load module that contains COBOL programs, all of the COBOL programs in that
load module must be compiled with the RENT option.
In an application with any mixture of COBOL for OS/390 & VM, COBOL for MVS
& VM, VS COBOL II, and OS/VS COBOL programs, the following compiler
options are recommended:
COBOL for OS/390
& VM
COBOL for MVS &
VM
VS COBOL II
OS/VS COBOL
RENT
RENT
RENT and RES
RES and NOENDJOB for
preloaded programs
RES and ENDJOB for
nonpreloaded
programs
You can place programs compiled with the RENT option in the OS/390 link pack
area. There they can be shared among the IMS dependent regions.
To run above the 16-MB line, your application program must be compiled with
either of the following compiler options, depending on your IMS environment:
© Copyright IBM Corp. 1991, 2000
359
RENT
NORENT and RMODE(ANY)
With IMS, the data for IMS application programs can reside above the 16-MB line,
and you can use DATA(31) RENT, or RMODE(ANY) NORENT, for programs that use IMS
services.
The recommended link-edit attributes for proper execution of COBOL programs
under IMS are as follows:
v Link as RENT load modules that contain only COBOL for OS/390 & VM
programs compiled with the RENT compiler option.
v To link load modules that contain a mix of COBOL for OS/390 & VM RENT
programs and other programs, you can use the link-edit attributes recommended
for the other programs.
RELATED TASKS
CEETDLI, and condition handling under IMS (Language Environment Programming
Guide)
RELATED REFERENCES
“DATA” on page 266
“RENT” on page 289
Appendix M. IMS considerations (COBOL for OS/390 & VM Compiler and Run-Time
Migration Guide)
360
Programming Guide
Chapter 21. Running COBOL programs under OS/390 UNIX
|
|
|
|
|
|
To run your COBOL programs in the OS/390 UNIX environment, you must
compile them with the IBM COBOL for OS/390 & VM or the COBOL for MVS &
VM compiler. They must be reentrant: use the compiler and linker option RENT. If
you are going to run them from the HFS, use the linker option AMODE(31). Any
AMODE(24) program that you call from within an OS/390 UNIX application must
reside in an MVS PDS or PDSE.
|
|
|
|
|
The following restrictions apply to running under OS/390 UNIX:
v SORT and MERGE statements are not supported.
v You cannot use the interfaces for preinitialization (run-time option RTEREUS and
functions IGZERRE and ILBOSTP0) to establish a reusable environment in the
OS/390 UNIX environment.
|
|
|
|
|
|
v You cannot run your COBOL program in more than one thread. If you start a
COBOL application in a second thread, you get a software condition from the
COBOL run time. You can run your COBOL programs in the initial process
thread (IPT) or in one non-IPT that you create from a C or PL/I routine.
v You can use Debug Tool to debug your OS/390 UNIX programs using a remote
debugging session from IBM VisualAge COBOL only.
RELATED TASKS
“Chapter 14. Compiling under OS/390 UNIX” on page 235
“Running in OS/390 UNIX environments”
“Setting and accessing environment variables” on page 362
“Calling UNIX/POSIX APIs” on page 364
“Accessing main program parameters” on page 365
Language Environment Programming Guide
RELATED REFERENCE
“RENT” on page 289
Running in OS/390 UNIX environments
|
|
|
|
|
You can run your OS/390 UNIX COBOL programs in any of the OS/390 UNIX
execution environments:
v From a UNIX shell, either:
– The OS/390 shell (OMVS) or
– The OS/390 ISPF shell (ISHELL)
|
Enter the program name at the shell prompt.
|
|
|
The program must be in the current directory or in your search path. When
running your UNIX programs, you can specify run-time options only by setting
the environment variable _CEE_RUNOPTS before starting your program.
|
|
|
You can run your MVS executable program that resides in a cataloged MVS data
set from a shell by using the tso utility. For example:
tso “call 'my.loadlib(myprog)'”
© Copyright IBM Corp. 1991, 2000
361
The ISPF shell can direct stdout and stderr only to an HFS file, not to your
terminal.
v From outside a shell, either:
– TSO/E or
– OS/390 batch
|
|
|
|
|
|
|
|
To call your OS/390 UNIX COBOL program that resides in an HFS file from the
TSO/E ready prompt, use the BPXBATCH utility or a spawn() syscall in a REXX
exec.
|
|
To call your OS/390 UNIX COBOL program that resides in an HFS file with the
JCL EXEC statement, use the BPXBATCH utility.
RELATED TASKS
“Setting and accessing environment variables”
“Calling UNIX/POSIX APIs” on page 364
“Accessing main program parameters” on page 365
Running POSIX-enabled programs using an OS/390 UNIX shell (Language
Environment Programming Guide)
Running POSIX-enabled programs outside the OS/390 UNIX shells (Language
Environment Programming Guide)
“Defining and allocating QSAM files” on page 121
“Defining and allocating line-sequential files” on page 165
“Allocating VSAM files” on page 156
“Displaying values on a screen or in a file (DISPLAY)” on page 29
RELATED REFERENCES
“TEST” on page 295
BPXBATCH utility (OS/390 UNIX System Services User’s Guide)
Language Environment Programming Reference
Setting and accessing environment variables
|
|
|
|
You can set environment variables for your OS/390 UNIX COBOL program in
either of these ways:
|
|
|
Although setting and resetting environment variables from the shell before you
begin to run your program is probably a typical procedure, you can set, reset, and
access environment variables from your program while it is running.
|
|
If you are running your program with BPXBATCH, you can set environment
variables by using an STDENV DD statement.
v From the shell with commands export and set
v From your program
Setting environment variables that affect execution
|
|
|
To set environment variables from a shell, use the export or set command. For
example, to set the environment variable MYFILE:
|
|
Call POSIX functions setenv() and putenv() to set environment variables from your
program.
export MYFILE=/usr/mystuff/notes.txt
362
Programming Guide
Environment variables of interest for COBOL programs
|
|
_CEE_RUNOPTS
Run-time options.
|
|
LIBPATH
Directory paths of your dynamic link libraries.
|
_IGZ_SYSOUT
stdout or stderr to direct your DISPLAY output. These are the only
allowable values.
|
|
STEPLIB
Location of programs not in the LNKLST.
Resetting environment variables
|
|
|
|
You can reset an environment variable from the shell or from your program. To
reset an environment variable as if it had not been set, use the OS/390 UNIX shell
command unset. To reset an environment variable from your COBOL program, call
the setenv() function.
Accessing environment variables
|
|
To see the values of all environment variables, you can use the export command
with no parameters.
|
|
To access the value of an environment variable from your COBOL program, call
the getenv() function.
“Example: accessing environment variables”
RELATED TASKS
“Running in OS/390 UNIX environments” on page 361
“Calling UNIX/POSIX APIs” on page 364
“Accessing main program parameters” on page 365
“Displaying values on a screen or in a file (DISPLAY)” on page 29
RELATED REFERENCES
Language Environment Programming Reference
OS/390 MVS JCL Reference
Example: accessing environment variables
|
|
|
The following example shows how you can access and set environment variables
from your COBOL programs by calling the standard POSIX functions getenv() and
putenv().
|
|
|
|
|
|
|
|
|
|
|
|
|
Because these are C functions, you must pass arguments BY VALUE. Pass character
strings as BY VALUE pointers that point to null-terminated strings.
CBL pgmname(longmixed)
Identification division.
Program-id. “envdemo”.
Data division.
Working-storage section.
01 P pointer.
01 PATH pic x(5) value Z“PATH”.
01 var-ptr pointer.
01 var-len pic 9(4) binary.
01 putenv-arg pic x(14) value Z“MYVAR=ABCDEFG”.
01 rc pic 9(9) binary.
Chapter 21. Running COBOL programs under OS/390 UNIX
363
Linkage section.
01 var pic x(5000).
Procedure division.
* Retrieve and display the PATH environment variable
Set P to address of PATH
Call “getenv” using by value P returning var-ptr
If var-ptr = null then
Display “PATH not set”
Else
Set address of var to var-ptr
Move 0 to var-len
Inspect var tallying var-len
for characters before initial X“00”
Display “PATH = ” var(1:var-len)
End-if
* Set environment variable MYVAR to ABCDEFG
Set P to address of putenv-arg
Call “putenv” using by value P returning rc
If rc not = 0 then
Display “putenv failed”
Stop run
End-if
Goback.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Calling UNIX/POSIX APIs
|
|
|
You can call standard UNIX/POSIX functions from your UNIX programs and from
traditional MVS COBOL programs. These functions are part of Language
Environment.
|
|
|
|
Because these are C functions, you must pass arguments BY VALUE. Pass character
strings as BY VALUE pointers that point to null-terminated strings. You must use the
compiler options NODYNAM and PGMNAME(LONGMIXED) when you compile programs
that call these functions.
fork, exec, and spawn
You can call the fork, exec, and spawn functions from your COBOL program, or
from a non-COBOL program in the same process as COBOL programs. However,
you need to be aware of these restrictions:
v From a forked process you cannot access any COBOL sequential, indexed, or
relative files that were open when you issued the fork. You get a file status code
92 when you attempt such an access (CLOSE, READ, WRITE, REWRITE, DELETE, or
START). You can access line-sequential files that were open at the time of a fork.
v You cannot use the fork function in a process in which any of the following is
true:
|
|
|
|
|
|
|
|
|
|
|
– A COBOL SORT or MERGE is running.
– A declarative is running.
– The process has more than one Language Environment enclave (COBOL run
unit).
– The process has used any of the COBOL reusable environment interfaces.
|
|
|
|
|
|
|
|
|
– The process has ever run an OS/VS COBOL or VS COBOL II program.
v With one exception, MVS DD allocations are not inherited from a parent process
to a child process. The exception is the local spawn, which creates a child
process in the same address space as the parent process. You request a local
spawn by setting the environment variable _BPX_ SHAREAS=YES before you invoke
the spawn function.
364
Programming Guide
|
|
|
|
The exec and spawn functions start a new Language Environment enclave in the
new UNIX process. Therefore, the target program of the exec or spawn is a main
program, and all COBOL programs in the process start in initial state with all files
closed.
Samples
|
|
Sample code is provided with the product for calling some of the POSIX routines.
The sample source code is in the SIGYSAMP data set.
Purpose
Sample
Functions used
Shows how to use some of the file
and directory routines.
IGYTFL1
getcwd
mkdir
rmdir
access
Shows how to use the
iconv routines to convert data.
IGYTCNV
iconv_open
iconv
iconv_close
Shows the use of the exec routine
to run a new program along with
other process related routines.
IGYTEXC
IGYTEXC1
fork
getpid
getppid
execl
perror
wait
Shows how to get the errno
value.
IGYTERNO
IGYTGETE
perror
fopen
Shows the use of the interprocess
communication message routines.
IGYTMSQ
IGYTMSQ2
ftok
msgget
msgsndd
perror
fopen
fclose
msgrcv
msgctl
perror
RELATED TASKS
“Running in OS/390 UNIX environments” on page 361
“Setting and accessing environment variables” on page 362
“Accessing main program parameters”
Language Environment Programming Guide
RELATED REFERENCES
OS/390 C/C++ Run-Time Library Reference
OS/390 UNIX System Services Programming: Assembler Callable Services Reference
Accessing main program parameters
|
|
|
When you run a COBOL program from the OS/390 UNIX shell command line, or
with an exec or spawn function, the parameter list consists of three parameters
passed by reference:
|
|
|
argument count
A binary fullword integer containing the number of elements in each of the
arrays that are passed as the second and third parameters.
Chapter 21. Running COBOL programs under OS/390 UNIX
365
|
|
|
|
argument length list
An array of pointers. The nth entry in the array is the address of a
fullword binary integer containing the length of the nth entry in the
argument list.
|
|
|
|
argument list
An array of pointers. The nth entry in the array is the address of the nth
character string passed as an argument on the spawn or exec functions, or
the command invocation. Each character string is null-terminated.
This array is never empty. The first argument is the character string that
represents the name of the file associated with the process being started.
|
|
You can access these parameters with standard COBOL coding.
|
“Example: accessing main program parameters”
RELATED TASKS
“Running in OS/390 UNIX environments” on page 361
“Setting and accessing environment variables” on page 362
“Calling UNIX/POSIX APIs” on page 364
Example: accessing main program parameters
The following example shows the three parameters that are passed by reference.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Identification division.
Program-id. “EXECED”.
****************************************************************
* This sample program displays arguments received via exec()
*
* function of OS/390 UNIX System Services
*
****************************************************************
Data division.
Working-storage section.
01 curr-arg-count pic 9(9) binary value zero.
Linkage section.
01 arg-count pic 9(9) binary.
(1)
01 arg-length-list.
(2)
05 arg-length-addr pointer occurs 1 to 99999
depending on curr-arg-count.
01 arg-list.
(3)
05 arg-addr pointer occurs 1 to 99999
depending on curr-arg-count.
01 arg-length pic 9(9) binary.
01 arg pic X(65536).
Procedure division using arg-count arg-length-list arg-list.
*****************************************************************
* Display number of arguments received
*
*****************************************************************
Display “Number of arguments received: ” arg-count
*****************************************************************
* Display each argument passed to this program
*
*****************************************************************
Perform arg-count times
Add 1 to curr-arg-count
* *******************************************************
* * Set address of arg-length to address of current
*
* * argument length and display
*
* *******************************************************
Set Address of arg-length
to arg-length-addr(curr-arg-count)
Display
“Length of Arg ” curr-arg-count “ = ” arg-length
* *******************************************************
366
Programming Guide
* * Set address of arg to address of current argument
*
* * and display
*
* *******************************************************
Set Address of arg to arg-addr(curr-arg-count)
Display “Arg ” curr-arg-count “ = ” arg (1:arg-length)
End-Perform
Display “Display of arguments complete.”
Goback.
|
|
|
|
|
|
|
|
|
|
(1)
This count contains the number of elements in each of the arrays that are
passed as the second and third parameters.
|
|
(2)
This array includes a pointer to the length of the nth entry in the argument
list.
|
|
(3)
This array includes a pointer to the nth character string passed as an
argument on the spawn or exec function or the command invocation.
Chapter 21. Running COBOL programs under OS/390 UNIX
367
368
Programming Guide
Chapter 22. Running COBOL programs under CMS
You can code and compile COBOL programs under both CMS and OS/390, but
you should be aware of certain differences in how programs run in the CMS
environment, including file handling and other run-time restrictions.
Run-time restrictions under CMS
|
|
|
|
|
The following restrictions apply when you run COBOL programs under CMS:
v SORT and MERGE verbs are supported on XA-mode machines if DFSORT/CMS
Version 2 Release 1 or an equivalent is installed.
v The RERUN phrase is tolerated, but no checkpoints are taken because CMS has no
checkpoint/restart feature.
v Only if you use the CMS LKED command to generate independent load modules
for each program in the object deck does CMS support the following code:
CANCEL, dynamic CALL literal, and CALL identifier targeting a subprogram
compiled into the same object program as the calling program using the batch
compile facility.
v You cannot use the Debug Tool with programs compiled with the
TEST(SEPARATE) compiler option.
v You cannot run COBOL programs in the VM/ESA OpenEdition environment.
v You cannot use files defined as ORGANIZATION LINE SEQUENTIAL.
CMS does not support using the following COBOL code:
v User label-handling functions. Therefore, the label user-handling format of USE
and the data-name option of the LABEL RECORDS clause are invalid. USER
DECLARATIVE is never invoked for label processing.
v IGZBRDGE macro for call conversions.
v Object-oriented COBOL language extensions (references to objects, methods, or
classes, for example).
v Programs compiled with the DLL compiler option.
Handling QSAM files under CMS
Processing of QSAM files under CMS is slightly different than under OS/390.
QSAM unblocked files or files with a small block size can slow performance under
CMS. To improve performance, use files with a block size 50 to 100 times larger
than the logical record length.
Also, CMS does not diagnose as errors any conflicts in fixed file attributes when
opening an existing QSAM file for output (not update). These attributes refer to:
v Record format (RECFM)
v Logical record length (LRECL)
v Data set organization (DSORG)
v Attribute indicating that ASCII or EBCDIC translation is requested (OPTCD=Q)
Conflicts in these attributes can occur on an OPEN of an existing QSAM file when
the COBOL program (DCB) and the data set label for the file or the CMS FILEDEF
command specify different values for any of them. However, because CMS does
© Copyright IBM Corp. 1991, 2000
369
not diagnose these conflicts as errors, Language Environment does not return a file
status code 39 to the COBOL program, although such a code is what COBOL
expects for such errors.
Certain VM/ESA rules govern the precedence of sources for CMS file attributes
(sources include the DCB for the program, CMS FILEDEF command, and existing
data set label). These rules affect the behavior of the file status code 39.
Run-time message IGZ0002S
Language Environment issues COBOL run-time message IGZ0002S when a SYNAD
error has occurred on a QSAM file, and no invalid key clause, file status key, or
user error declarative was specified in the COBOL program for the output
operation tried. The text of IGZ0002S is provided by the system SYNADAF
routine. Under CMS the format of message IGZ0002S is:
IGZ0002S
'120S INPUT/OUTPUT ERROR nnn ON ddname'
where
120S
Is the CMS message number for SYNAD errors
INPUT
Indicates an input operation was tried
OUTPUT Indicates an output operation was tried
nnn
Is the associated error code
ddname
Is the ddname of the related file
A CMS SYNAD error also occurs when there is not enough minidisk space
available for a CMS output file. When this SYNAD error occurs on QSAM files
used by COBOL programs, and no invalid key clause, file status key, or user error
declarative was specified in the COBOL program for the output operation tried,
Language Environment issues COBOL run-time message IGZ0002S as follows:
IGZ0002S '120S OUTPUT ERROR 013 ON ddname'
After issuing message IGZ0002S, the COBOL program ends.
RELATED REFERENCES
Precedence rules for CMS file attributes (VM/ESA CMS Application Development
Guide)
370
Programming Guide
Chapter 23. Accessing COBOL programs interactively with
ISPF
If you code your application program using ISPF panels, you can interactively
access your COBOL program.
Under CMS, you must specify the CMS option when you use the ISPF command
ISPEXEC SELECT PGM to invoke a COBOL program in order to pass user arguments
or run-time options specified and have them take effect. Under OS/390, you
cannot pass any user arguments or run-time options when you use the ISPEXEC
SELECT PGM command to invoke a COBOL program.
You can run COBOL programs concurrently in both screens of the ISPF split-screen
mode.
One of the sample programs that is shipped with COBOL for OS/390 & VM,
IGYTCARB, runs under ISPF.
RELATED CONCEPTS
“IGYTCARB: interactive program” on page 592
© Copyright IBM Corp. 1991, 2000
371
372
Programming Guide
Part 4. Developing object-oriented programs
Chapter 24. Writing object-oriented programs
Example: mail-order catalog . . . . . . . .
Subclasses . . . . . . . . . . . . .
Defining a class . . . . . . . . . . . .
CLASS-ID paragraph for defining a class . . .
REPOSITORY paragraph for defining a class
WORKING-STORAGE SECTION for defining a
class . . . . . . . . . . . . . . .
Example: defining a class . . . . . . . .
Defining a class method . . . . . . . . . .
METHOD-ID paragraph for defining a class
method . . . . . . . . . . . . . .
Overriding a method . . . . . . . . . .
INPUT-OUTPUT SECTION for defining a
method . . . . . . . . . . . . . .
DATA DIVISION for defining a method . . .
PROCEDURE DIVISION for defining a method
Coding special methods . . . . . . . . .
Attribute methods . . . . . . . . . .
Method somInit for customizing object
creation . . . . . . . . . . . . .
Method somUninit for customizing object
destruction . . . . . . . . . . . .
Example: defining a method . . . . . . .
Defining a client program . . . . . . . . .
REPOSITORY paragraph for defining a client
WORKING-STORAGE SECTION for defining a
client . . . . . . . . . . . . . . .
Creating and freeing instances of classes . . .
Manipulating object references . . . . . .
Invoking methods . . . . . . . . . . .
Example: defining a client . . . . . . . .
Defining a subclass . . . . . . . . . . .
CLASS-ID paragraph for defining a subclass
REPOSITORY paragraph for defining a subclass
WORKING-STORAGE SECTION for defining a
subclass . . . . . . . . . . . . . .
Defining a subclass method . . . . . . .
METHOD-ID paragraph for defining a
subclass method . . . . . . . . . .
Example: defining a subclass (with methods)
Defining a metaclass . . . . . . . . . . .
CLASS-ID paragraph for defining a metaclass
REPOSITORY paragraph for defining a
metaclass . . . . . . . . . . . . . .
WORKING-STORAGE SECTION for defining a
metaclass . . . . . . . . . . . . . .
Defining a metaclass method . . . . . . .
Invoking a metaclass constructor method . .
Changing the definition of a class or subclass
Changing a client program . . . . . . . .
Example: defining a metaclass (with methods)
375
375
377
378
378
379
379
380
381
381
381
382
382
383
383
383
384
384
384
389
389
390
390
391
391
392
393
394
394
395
395
395
396
405
406
406
406
406
407
407
407
408
Chapter 25. System Object Model . . . . . . 415
SOM Interface Repository . . . . . . . . . 415
Accessing the SOM Interface Repository . . . 415
© Copyright IBM Corp. 1991, 2000
Populating the SOM Interface Repository . .
SOM environment variables . . . . . . .
Example: sample JCL for an object-oriented
application . . . . . . . . . . . .
Notes to sample JCL . . . . . . . .
SOM services . . . . . . . . . . . .
SOM methods and functions . . . . . .
Compiling and linking programs that call
SOM functions . . . . . . . . . .
Class initialization . . . . . . . . . .
Changing SOM class interfaces . . . . .
Chapter 26. Using SOM IDL-based class
libraries . . . . . . . . . . . . . .
SOM objects . . . . . . . . . . . . .
SOM IDL . . . . . . . . . . . . . .
Mapping IDL to COBOL . . . . . . . .
Using IDL operations. . . . . . . . .
Expressing IDL attributes . . . . . . .
Common IDL types . . . . . . . . .
Examples: common IDL types . . . . .
enum . . . . . . . . . . . . .
interface . . . . . . . . . . . .
long (signed and unsigned). . . . . .
short (signed and unsigned) . . . . .
string . . . . . . . . . . . . .
Complex IDL types . . . . . . . . .
any . . . . . . . . . . . . . .
array . . . . . . . . . . . . .
sequence . . . . . . . . . . . .
struct . . . . . . . . . . . . .
union . . . . . . . . . . . . .
Passing COBOL arguments and return values
Passing literal arguments . . . . . .
Passing arguments of complex types . .
Conventions for passing arguments and
return values . . . . . . . . . .
Passing enumerated arguments . . . .
Passing string arguments . . . . . .
Example: passing string arguments . . .
Example: using a SOM IDL-based class library
Handling errors and exceptions . . . . . .
Passing environment variables. . . . . .
Checking the exception type field . . . .
Handling exceptions . . . . . . . . .
Example: checking SOM exceptions . . . .
Creating and initializing object instances . . .
Looking at the IDL file . . . . . . . . .
Avoiding memory leaks . . . . . . . . .
Example: COBOL variable-length string class
Source code for helper routines . . . . . .
. 416
. 417
.
.
.
.
418
419
420
420
. 421
. 421
. 422
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
425
425
426
427
427
428
429
429
430
430
430
431
431
432
432
433
433
434
434
435
. 435
. 435
.
.
.
.
.
.
.
.
.
.
.
.
.
436
437
437
439
440
442
443
443
443
443
445
446
447
448
450
Chapter 27. Wrapping or converting
procedure-oriented programs . . . . . . . 451
OO view of COBOL programs. . . . . . . . 451
Wrapping procedure-oriented programs . . . . 452
373
Coordinating procedural code with interface
actions . . . . . . . . . . . . .
Integrating procedural code into OO systems
Changing procedural code . . . . . . .
Converting from procedure-oriented to OO
programs . . . . . . . . . . . . . .
Identifying objects . . . . . . . . . .
Analyzing data flow and usage . . . . .
Reallocating code to objects . . . . . .
Writing the object-oriented code . . . . .
374
Programming Guide
. 452
452
. 453
.
.
.
.
.
453
454
454
454
455
Chapter 24. Writing object-oriented programs
When you write an object-oriented (OO) program, you need to determine the
classes and the methods that the classes need to do their work. OO programs are
based on classes and methods for objects. A class is a template that defines the
data structure and capabilities of an object. The data structure is commonly called
instance data and the capabilities are commonly called methods. Usually, a
program creates and works with multiple object instances of a class. Each instance
has its own instance data and uses the methods defined for its class.
“Example: mail-order catalog”
RELATED TASKS
“Defining a class” on page 378
“Defining a class method” on page 381
Example: mail-order catalog
Consider a mail-order catalog business in which customers call service
representatives to place orders. The service representatives are working with a user
interface on the computer and creating an order. Therefore, in this situation there
are two classes: UserInterface and Orders. Because there are many service
representatives each processing a different customer’s order, there are multiple
instances of the two classes existing simultaneously.
Once classes are determined, the next step is to determine the methods the classes
need to do their work. The Orders class must provide the following services:
v Add items to the order
v Delete items from the order
v Compute the cost of the order
v Provide the order number to the service representative
v Write the final order for later processing
The following methods for the Orders class meet the above need:
AddItem
Add an item to the order
DeleteItem
Delete an item from the order
ComputeCost
Compute the cost of the order
getOrderNumber
Provide the order number
WriteOrder
Write the final order
As you design your class and its methods, you discover the need for the class to
keep some instance data. Typically, an orders class needs the following instance
data:
v Order number
© Copyright IBM Corp. 1991, 2000
375
v Order date
v Number of items in the order
v Table of items ordered
Diagrams are very helpful when designing classes and their methods. The
following diagrams depict the Orders and UserInterface classes.
The words in parentheses are instance data and the words after the number and
colon are methods.
The class structure of this object-oriented system is a tree structure. This structure
shows how classes are related to each other and is known as the inheritance
hierarchy. Orders and UserInterface are basic classes, so they inherit directly from
the System Object Model (SOM) base class, SOMObject.
All classes in COBOL inherit directly or indirectly from SOMObject. When multiple
inheritance is used, the class structure might not be a tree; it could be a graph.
However, the SOMObject class will always be at the root of the tree or graph.
The complete class structure for the mail-order catalog system is shown below:
376
Programming Guide
Subclasses
In the mail-order catalog example, Orders is a general class. One of the first things
you discover working with Orders is that there are two kinds of orders: new
orders and back orders. Although both NewOrders and BackOrders have all the
characteristics of Orders, BackOrders must also read the order from the file, and
check the status of its items. It might make sense to make NewOrders and
BackOrders subclasses of Orders, as shown below:
A number and colon with nothing after them represent a method inherited from a
superclass.
RELATED TASKS
“Defining
“Defining
“Defining
“Defining
a
a
a
a
class” on page 378
class method” on page 381
subclass” on page 393
metaclass” on page 405
Chapter 24. Writing object-oriented programs
377
Defining a class
A COBOL class definition consists of four divisions (like a COBOL program),
followed by an END CLASS header.
Division
Purpose
Syntax
IDENTIFICATION
(required)
Name a class. Provide
inheritance information
for it.
“CLASS-ID paragraph for defining a class”
(required)
AUTHOR paragraph (optional)
INSTALLATION paragraph (optional)
DATE-WRITTEN paragraph (optional)
DATE-COMPILED paragraph (optional)
ENVIRONMENT
(required)
Describe the computing
environment. Relate class
names to external SOM
names.
CONFIGURATION section (required)
“REPOSITORY paragraph for defining a
class” on page 379 (required)
SOURCE-COMPUTER paragraph (optional)
OBJECT-COMPUTER paragraph (optional)
SPECIAL-NAMES paragraph (optional)
DATA (optional)
Describe instance data the “WORKING-STORAGE SECTION for
class needs.
defining a class” on page 379 (optional)
PROCEDURE
(optional)
Define methods.
“Defining a class method” on page 381
If you specify the SOURCE-COMPUTER, OBJECT-COMPUTER, or SPECIAL-NAMES paragraphs
in a class CONFIGURATION SECTION, they apply to the entire class definition,
including all methods that the class introduces.
A class CONFIGURATION SECTION can consist of the same entries as a program
CONFIGURATION SECTION except the INPUT-OUTPUT SECTION.
Any application containing class definitions needs to be prelinked.
“Example: mail-order catalog” on page 375
“Example: defining a class” on page 380
RELATED TASKS
“Defining a subclass” on page 393
“Defining a metaclass” on page 405
“Changing the definition of a class or subclass” on page 407
“Describing the computing environment” on page 7
CLASS-ID paragraph for defining a class
You use the CLASS-ID paragraph, within the IDENTIFICATION DIVISION, to name a
class and provide inheritance information for it. For example:
Identification Division.
Class-Id. Orders INHERITS SOMObject.
Required
Required
Use the CLASS-ID paragraph to:
v Name a class.
In the example above, Orders is the class name.
v Specify the System Object Model (SOM) base class or user-written class from
which this class inherits its characteristics.
378
Programming Guide
In the example above, INHERITS SOMObject indicates Orders inherits its basic
characteristics from the base SOM class SOMObject.
v Name a metaclass.
You must specify SOMObject in the REPOSITORY paragraph in the ENVIRONMENT
DIVISION. Optionally, you can specify Orders in the REPOSITORY paragraph.
REPOSITORY paragraph for defining a class
The REPOSITORY paragraph declares to the compiler that the specified user-defined
word is a class name and optionally relates the class name to an external class
name in the SOM interface repository. For example:
Environment Division.
Configuration Section.
Repository.
Class SOMObject is 'SOMObject'
Class Orders is 'Orders'.
Required
Required
Required
You must specify, in the REPOSITORY paragraph, any class name that you explicitly
reference in your class definition. For example:
v SOM base classes.
In the example above, CLASS SOMObject IS ’SOMObject’ indicates that what you
are calling SOMObject in your COBOL program is also called SOMObject in the
SOM interface repository. All SOM names are mixed case, so SOMObject spelled
in mixed case is required to properly handle SOM case sensitivity.
v The classes from which your class is inheriting.
v The metaclass to which your class belongs.
v Any class referenced in methods introduced by the class.
You can optionally include the name of the class that you are defining. If you do
not include the name of your class, it is treated as all uppercase regardless of how
you typed it in the CLASS-ID paragraph. In the above example, Orders is stored in
the SOM interface repository in mixed case.
WORKING-STORAGE SECTION for defining a class
You use the WORKING-STORAGE SECTION, within the DATA DIVISION, to describe the
instance data the class needs. For example:
Data Division.
Working-Storage Section.
01 order-number PIC 9(5).
01 order-date
PIC X(8).
01 order-count
PIC 99.
01 order-table.
02 order-entry OCCURS 10 TIMES.
03 order-item PIC X(5).
A class WORKING-STORAGE SECTION describes instance data that is statically allocated
when the instance is created and exists until the instance is freed. By default, the
data is global to all the methods that the class introduces. Instance data in a
COBOL class is private. Therefore, no other class or subclass can reference it
directly.
The syntax of the class WORKING-STORAGE SECTION is generally the same as in a
program, with these exceptions:
v You cannot use the VALUE clause to initialize the data.
Class instance data is initialized by overriding the somInit method.
Chapter 24. Writing object-oriented programs
379
You can have level-88 numbers with the VALUE clause.
v You cannot use the EXTERNAL attribute.
v You can use the GLOBAL attribute, but it has no effect.
Example: defining a class
The class definition (except the method definitions) for the Orders class:
IDENTIFICATION DIVISION.
*
*
*
*
Orders is the name of the class
Orders inherits from SOMObject (SOM base class)
CLASS-ID. Orders INHERITS SOMObject.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
REPOSITORY.
*
*
*
*
SOMObject is known as SOMObject in SOM repository
CLASS SOMObject IS 'SOMObject'
Orders is known as Orders in SOM repository
CLASS Orders IS 'Orders'.
DATA DIVISION.
WORKING-STORAGE SECTION.
*
*
*
Instance data for Orders class
*
*
*
method definitions in here
01
01
01
01
order-number PIC 9(5).
order-date
PIC X(8).
order-count
PIC 99.
order-table.
02 order-entry OCCURS 10 TIMES.
03 order-item PIC X(5).
PROCEDURE DIVISION.
END CLASS Orders.
The class definition (except the method definitions) for the UserInterface class:
IDENTIFICATION DIVISION.
*
*
*
*
UserInterface is the name of the class
UserInterface inherits from SOMObject (SOM base class)
CLASS-ID. UserInterface INHERITS SOMObject.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
REPOSITORY.
*
*
*
*
SOMObject is known as SOMObject in SOM repository
CLASS SOMObject IS 'SOMObject'
UserInterface is known as UserInterface in SOM repository
CLASS UserInterface IS 'UserInterface'.
DATA DIVISION.
WORKING-STORAGE SECTION.
*
*
*
Instance data for UserInterface class
01
uif-action PIC
88 uif-add
88 uif-delete
88 uif-quit
01 uif-item
PIC
380
Programming Guide
X(10).
VALUE 'AddItem'.
VALUE 'DeleteItem'.
VALUE 'Quit'.
X(5).
PROCEDURE DIVISION.
*
*
*
method definitions in here
END CLASS UserInterface.
Defining a class method
You can define a COBOL method only inside the PROCEDURE DIVISION of a class
definition. You must make each method name within a class unique. A COBOL
method definition consists of four divisions (like a COBOL program), followed by
an END METHOD header.
Division
Purpose
Syntax
IDENTIFICATION
(required)
Name a method. Say
“METHOD-ID paragraph for defining a
whether it overrides a
class method” (required)
method from a superclass. AUTHOR paragraph (optional)
INSTALLATION paragraph (optional)
DATE-WRITTEN paragraph (optional)
DATE-COMPILED paragraph (optional)
ENVIRONMENT
(optional)
Relate the method files to
the external file names
known by the operating
system.
“INPUT-OUTPUT SECTION for defining a
method” on page 382 (optional)
DATA (optional)
Define external files.
Allocate a copy of the
data.
“DATA DIVISION for defining a method”
on page 382 (optional)
PROCEDURE
(optional)
Code the executable
statements to complete
the service provided by
the method.
“PROCEDURE DIVISION for defining a
method” on page 383 (optional)
“Example: mail-order catalog” on page 375
“Example: defining a method” on page 384
RELATED TASKS
“Defining a subclass method” on page 395
“Defining a metaclass method” on page 406
“Overriding a method”
“Invoking methods” on page 391
“Coding special methods” on page 383
METHOD-ID paragraph for defining a class method
Use the METHOD-ID paragraph to name the method. For example:
Identification Division.
Method-Id. WriteOrder.
In this example, WriteOrder is the method name. Other methods or programs use
this name to invoke the method.
Overriding a method
Occasionally, a class defines a method whose name exists in a superclass. In this
case, you need to override the superclass method with the OVERRIDE clause on the
METHOD-ID. System Object Model (SOM) provides two methods designed to be
overridden. These SOM methods allow you to customize the creation and disposal
Chapter 24. Writing object-oriented programs
381
of an object instance. For example, you can initialize instance data when an
instance is created, or save instance data when an instance is freed. The methods
are called somInit and somUninit respectively.
To override somInit, code the IDENTIFICATION DIVISION as follows:
Identification Division.
Method-Id. “somInit” Override.
Required
Required
INPUT-OUTPUT SECTION for defining a method
The method ENVIRONMENT DIVISION has only one section, the INPUT-OUTPUT
SECTION. For example:
Environment Division.
Input-Output Section.
File-Control.
Select order-file Assign OrdrFile.
The INPUT-OUTPUT SECTION relates your method files to the external file names
known by the operating system. The syntax for a method INPUT-OUTPUT SECTION is
the same as for a program INPUT-OUTPUT SECTION.
RELATED TASKS
“Describing the computing environment” on page 7
DATA DIVISION for defining a method
A method DATA DIVISION consists of any of four sections:
FILE SECTION
The same as a program FILE SECTION except that a method FILE SECTION
can define only EXTERNAL files.
LOCAL-STORAGE SECTION
Allocates a separate copy of the data defined in the method LOCAL-STORAGE
SECTION for each invocation of the method and frees it on return from the
method.
If you specify the VALUE clause, the data item is initialized to the value on
every invocation of the method.
The method LOCAL-STORAGE SECTION is similar to a program LOCAL-STORAGE
SECTION, except that the GLOBAL attribute has no effect.
WORKING-STORAGE SECTION
Allocates a single copy of the data defined in the method WORKING-STORAGE
SECTION when the run unit begins and persists in its last-used state until
the run unit terminates. Uses the same single copy of the WORKING-STORAGE
data whenever the method is invoked, regardless of the invoking object.
If you specify the VALUE clause, the data item is initialized to the value on
the first invocation of the method. You may specify the EXTERNAL clause for
method WORKING-STORAGE data items.
A method WORKING-STORAGE SECTION is similar to a program
WORKING-STORAGE SECTION except that the GLOBAL attribute has no effect.
LINKAGE SECTION
The same as a program LINKAGE SECTION except that the GLOBAL attribute
has no effect.
382
Programming Guide
If you define the same data item in both the class DATA DIVISION and the method
DATA DIVISION, a reference in the method to the data name refers to the data item
in the method DATA DIVISION. The method DATA DIVISION takes precedence.
RELATED TASKS
“Describing the data” on page 12
“Sharing data by using the EXTERNAL clause” on page 483
PROCEDURE DIVISION for defining a method
In the PROCEDURE DIVISION of a method, you code the executable statements to
implement the service that the method is expected to provide.
The EXIT METHOD statement returns control to the invoking program or method.
GOBACK has the same effect as EXIT METHOD. If you specify the RETURNING clause
when the method is invoked, the EXIT METHOD or GOBACK returns the value of the
data item to the invoking program or method. You may specify STOP RUN in a
method; however, it terminates the run unit.
An implicit EXIT METHOD is generated as the last statement of every method
PROCEDURE DIVISION.
You can code any COBOL statements in a method except the following:
v ENTRY
v EXIT PROGRAM
v The following obsolete elements of ANSI COBOL-85:
– ALTER
– GOTO without a specified procedure name
– SEGMENTATION
– USE FOR DEBUGGING
You must properly terminate a method definition with an END METHOD statement.
For example, the following statement marks the end of the WriteOrder method:
End Method WriteOrder.
Coding special methods
There are several special methods that you might want to code when defining a
class, as discussed in the sections below.
Attribute methods
Instance variables in COBOL are all private in the sense that the class fully
encapsulates them, and only the methods that are introduced by the class that
defines the instance variables can access them directly. Normally, a well-designed
object-oriented application does not need to access instance variables from outside
the class.
COBOL does not directly support the concept of a public instance variable, as
defined in other object-oriented languages, nor the concept of a class attribute, as
defined by SOM and CORBA. (A CORBA attribute behaves like an instance
variable that has get and set methods to access and modify the value of the
instance variable from outside the class definition.) You can provide this capability
by coding getX and setX methods for any instance variables X for which direct
access from outside the class is required.
Chapter 24. Writing object-oriented programs
383
The recommended naming convention for these methods is either getX and setX or
perhaps get_X and set_X. Direct specification of attribute method names as defined
by the CORBA C language binding (such as _get_X) is not recommended because
such names are not valid in IDL. If you use such method names and specify the
COBOL IDLGEN compiler option, the SOM compiler cannot compile the IDL file.
For example, the following method passes the order number to any program that
invokes getOrderNumber.
Identification Division.
Method-Id. 'getOrderNumber'.
Data Division.
Linkage Section.
01 ord-num PIC 9(5).
Procedure Division returning ord-num.
Move order-number To ord-num.
Exit Method.
End Method 'getOrderNumber'.
Method somInit for customizing object creation
Creating an object instance automatically invokes the somInit method. The default
somInit in SOM does nothing. However, you can override it to customize the way
that your object instances are created. A typical use would be to initialize your
instance variables. For example:
Identification Division.
Method-Id. “somInit” Override.
Procedure Division.
Move Function Current-Date(1:8) To order-date.
Move 0 To order-count.
Initialize order-table.
Exit Method.
End Method “somInit”.
Method somUninit for customizing object destruction
Freeing an object automatically invokes the somUninit method. The default
somUninit in SOM does nothing. However, you can override it to customize the
way that your object instance is freed, perhaps to save the instance data or free any
additional storage that your instance points to. For example:
Identification Division.
Method-Id. “somUninit” Override.
Data Division.
Local-Storage Section.
01 sub Pic 99.
Procedure Division.
Display order-date.
Perform varying sub from 1 by 1 until sub > order-count
Display order-table (sub)
End-Perform.
Exit Method.
End Method “somUninit”.
RELATED CONCEPTS
“How logic is divided in the PROCEDURE DIVISION” on page 17
RELATED TASKS
“Processing the data” on page 17
Example: defining a method
The class definition for the Orders class, including the method definitions:
384
Programming Guide
IDENTIFICATION DIVISION.
CLASS-ID. Orders INHERITS SOMObject.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
* Declare classes used in class definition
REPOSITORY.
CLASS SOMObject IS 'SOMObject'
CLASS Orders IS 'Orders'.
DATA DIVISION.
* Define instance data
WORKING-STORAGE SECTION.
01 order-number PIC 9(5).
01 order-date
PIC X(8).
01 order-count
PIC 99.
01 order-table.
02 order-entry OCCURS 10 TIMES.
03 order-item PIC X(5).
PROCEDURE DIVISION.
* Method to initialize instance data
* - this overrides the default somInit method
IDENTIFICATION DIVISION.
METHOD-ID. 'somInit' OVERRIDE.
PROCEDURE DIVISION.
MOVE FUNCTION CURRENT-DATE(1:8) TO order-date.
COMPUTE order-number = FUNCTION RANDOM ( 99999 ).
MOVE 0 TO order-count.
INITIALIZE order-table.
EXIT METHOD.
END METHOD 'somInit'.
* Method to add an item to an order
IDENTIFICATION DIVISION.
METHOD-ID. AddItem.
DATA DIVISION.
* Use LOCAL-STORAGE for items that should be allocated
* and initialized for each invocation of the method
LOCAL-STORAGE SECTION.
77 sub PIC 99.
01 found-flag PIC 9 VALUE 1.
88 found VALUE 0.
LINKAGE SECTION.
01 in-item
PIC X(5).
01 add-flag PIC 9.
PROCEDURE DIVISION USING in-item
RETURNING add-flag.
MOVE 1 TO add-flag.
PERFORM VARYING sub FROM 1 BY 1
UNTIL (sub > 10) OR (found)
IF order-item (sub) = SPACES
MOVE in-item TO order-item (sub)
ADD 1 TO order-count
MOVE 0 TO add-flag
SET found TO TRUE
END-IF
END-PERFORM.
EXIT METHOD.
END METHOD AddItem.
* Method to delete an item from an order
IDENTIFICATION DIVISION.
METHOD-ID. DeleteItem.
Chapter 24. Writing object-oriented programs
385
DATA DIVISION.
* Use LOCAL-STORAGE for items that should be allocated
* and initialized for each invocation of the method
LOCAL-STORAGE SECTION.
77 sub PIC 99.
01 found-flag PIC 9 VALUE 1.
88 found VALUE 0.
LINKAGE SECTION.
01 out-item
PIC X(5).
01 delete-flag PIC 9.
PROCEDURE DIVISION USING out-item
RETURNING delete-flag.
MOVE 1 TO delete-flag.
PERFORM VARYING sub FROM 1 BY 1
UNTIL (sub > 10) OR (found)
IF order-item (sub) = out-item
MOVE SPACES TO order-item (sub)
SUBTRACT 1 FROM order-count
MOVE 0 TO delete-flag
SET found TO TRUE
END-IF
END-PERFORM.
EXIT METHOD.
END METHOD DeleteItem.
* Method to compute the total cost of an order
IDENTIFICATION DIVISION.
METHOD-ID. ComputeCost.
DATA DIVISION.
* Use LOCAL-STORAGE for items that should be allocated
* and initialized for each invocation of the method
LOCAL-STORAGE SECTION.
77 sub
PIC 99.
77 cost PIC 9(5)V99.
LINKAGE SECTION.
01 total-cost PIC 9(7)V99.
PROCEDURE DIVISION USING total-cost.
MOVE 0 TO total-cost.
PERFORM VARYING sub FROM 1 BY 1
UNTIL sub > order-count
* Call a subroutine
*
NOTE: The subroutine code is not
*
included in this example.
CALL 'InventoryGetCost'
USING order-item (sub) cost
ADD cost TO total-cost
END-PERFORM.
EXIT METHOD.
END METHOD ComputeCost.
* Method to return the order number
IDENTIFICATION DIVISION.
METHOD-ID. 'getOrderNumber'.
DATA DIVISION.
LINKAGE SECTION.
01 ord-num PIC 9(5).
PROCEDURE DIVISION RETURNING ord-num.
MOVE order-number TO ord-num.
EXIT METHOD.
END METHOD 'getOrderNumber'.
386
Programming Guide
* Method to write completed order to file
IDENTIFICATION DIVISION.
METHOD-ID. WriteOrder.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT order-file ASSIGN OrdrFile.
DATA DIVISION.
FILE SECTION.
* Methods support only EXTERNAL files
FD order-file EXTERNAL.
01 order-record PIC X(80).
* Use LOCAL-STORAGE for items that should be allocated
* and initialized for each invocation of the method
LOCAL-STORAGE SECTION.
01 print-line.
02 print-order-number PIC 9(5).
02 print-order-date
PIC X(8).
02 print-order-count
PIC 99.
02 print-order-table.
03 print-order-entry OCCURS 10 TIMES.
04 print-order-item PIC X(5).
PROCEDURE DIVISION.
OPEN OUTPUT order-file.
MOVE order-number TO print-order-number.
MOVE order-date
TO print-order-date.
MOVE order-table TO print-order-table.
MOVE order-count TO print-order-count.
WRITE order-record FROM print-line.
CLOSE order-file.
EXIT METHOD.
END METHOD WriteOrder.
END CLASS Orders.
The class definition for the UserInterface class, including the method definitions:
IDENTIFICATION DIVISION.
CLASS-ID. UserInterface INHERITS SOMObject.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
* Declare classes used in class definition
REPOSITORY.
CLASS SOMObject IS 'SOMObject'
CLASS UserInterface IS 'UserInterface'.
DATA DIVISION.
* Define instance data
WORKING-STORAGE SECTION.
01 uif-action PIC X(10).
88 uif-add
VALUE 'AddItem'.
88 uif-delete VALUE 'DeleteItem'.
88 uif-quit
VALUE 'Quit'.
01 uif-item
PIC X(5).
PROCEDURE DIVISION.
*
Method to get input from customer - action and item
IDENTIFICATION DIVISION.
METHOD-ID. ReadUserInput.
DATA DIVISION.
LINKAGE SECTION.
Chapter 24. Writing object-oriented programs
387
01
01
action PIC X(10).
item
PIC X(5).
PROCEDURE DIVISION USING item action.
DISPLAY 'Enter the action: add, delete, quit'.
ACCEPT action FROM SYSIN.
MOVE FUNCTION UPPER-CASE (action) TO action.
EVALUATE TRUE
WHEN action = 'ADD'
SET uif-add TO TRUE
PERFORM Get-Item
WHEN action = 'DELETE'
SET uif-delete TO TRUE
PERFORM Get-Item
WHEN action = 'QUIT'
SET uif-quit TO TRUE
END-EVALUATE.
MOVE uif-action TO action.
EXIT METHOD.
Get-Item.
DISPLAY 'Enter the item'.
ACCEPT item FROM SYSIN.
MOVE item TO uif-item.
END METHOD ReadUserInput.
* Method to inform customer how action was completed
IDENTIFICATION DIVISION.
METHOD-ID. WriteUserMessage.
DATA DIVISION.
LINKAGE SECTION.
01 flag PIC 9.
PROCEDURE DIVISION USING flag.
IF flag = 0
DISPLAY uif-action
' successfully completed on '
uif-item
ELSE
DISPLAY uif-action
' unsuccessfully completed on '
uif-item
END-IF.
EXIT METHOD.
END METHOD WriteUserMessage.
* Method to display final order information
IDENTIFICATION DIVISION.
METHOD-ID. WriteUserOutput.
DATA DIVISION.
LOCAL-STORAGE SECTION.
77 formated-cost PIC $Z,ZZZ,ZZ9.99.
LINKAGE SECTION.
01 total-cost
PIC 9(7)V99.
01 order-number PIC 9(5).
PROCEDURE DIVISION USING total-cost order-number.
MOVE total-cost TO formated-cost.
DISPLAY 'Your order costs ' formated-cost.
DISPLAY 'Your order number is ' order-number.
EXIT METHOD.
388
Programming Guide
END METHOD WriteUserOutput.
END CLASS UserInterface.
Defining a client program
A program or method that requests services from a class via its methods is called a
client of the class. A client program consists of the usual four divisions:
Division
Purpose
Syntax
IDENTIFICATION
(required)
Name the client.
Coded as usual
ENVIRONMENT
(required)
Describe the computer
environment. Relate class
names to external SOM
names.
CONFIGURATION section (required)
“REPOSITORY paragraph for defining a
client” (required)
DATA (optional)
Describe the data the
client needs (object
references).
“WORKING-STORAGE SECTION for
defining a client” on page 390 (optional)
PROCEDURE
(optional)
Create and free instances
of classes. Manipulate
object reference data
items. Invoke methods.
Code using somNew, somFree, IF statements,
and INVOKE.
A method can request services from another method. Therefore a method can be a
client and use the statements discussed in this section.
“Example: mail-order catalog” on page 375
“Example: defining a client” on page 392
RELATED TASKS
“Creating and freeing instances of classes” on page 390
“Manipulating object references” on page 391
“Invoking methods” on page 391
“Changing a client program” on page 407
REPOSITORY paragraph for defining a client
The REPOSITORY paragraph in the CONFIGURATION SECTION of the ENVIRONMENT
DIVISION declares to the compiler that the specified user-defined word is a class
name and optionally relates the class name to an external class name in the SOM
interface repository. For example:
Environment Division.
Configuration Section.
Source-Computer.
Object-Computer.
Required
Required
IBM-370.
IBM-370.
Repository.
Required
Client UserInterface is 'UserInterface'
Client Orders is 'Orders'.
The SOURCE-COMPUTER and OBJECT-COMPUTER (and SPECIAL-NAMES) paragraphs are
optional as usual.
Chapter 24. Writing object-oriented programs
389
You must specify any class name you explicitly reference in your program in the
REPOSITORY paragraph. In the example above, Orders and UserInterface are the
only two classes this program references.
WORKING-STORAGE SECTION for defining a client
You can use any of the sections of the DATA DIVISION to describe the data that the
client needs. For example:
Data Division.
Working-Storage Section.
01 orderObj Usage Object Reference Orders.
01 userObj Usage Object Reference UserInterface.
01 univObj Usage Object Reference.
Because the client is using classes, it needs one or more special data items called
object references. Object references are handles to instances of classes that the
program creates. All requests to a method are handled through object references to
instances of the class that defined the method.
In the above example, the phrase USAGE OBJECT REFERENCE indicates that the data
item is used as a handle for an object instance. The example defines three object
references. The first two, orderObj and userObj, are typed object references because
a class name appears after the OBJECT REFERENCE phrase. Therefore, orderObj can
be used to reference only instances of the Orders class or one of its subclasses.
Likewise, userObj can be used to reference only instances of the UserInterface
class or one of its subclasses. The other object reference, univObj, does not have a
class name after its OBJECT REFERENCE phrase. It is a universal object reference and
can reference instances of any class.
Remember: You must define, in the REPOSITORY paragraph of the CONFIGURATION
SECTION, class names that you use on the OBJECT REFERENCE phrase.
Creating and freeing instances of classes
Before you can use the methods in a class, you must create an instance of the class.
SOM provides a method, somNew, to create an instance of a class. The following
example creates an instance of the Orders class and assigns its handle to the object
reference orderObj.
Invoke Orders 'somNew' Returning orderObj.
When somNew executes, it automatically invokes somInit, another SOM method,
which you can override to initialize your instance data.
Remember: You must define the class name, in this case Orders, in the REPOSITORY
paragraph of the CONFIGURATION SECTION. You must define the object reference, in
this case orderObj, as USAGE OBJECT REFERENCE in the DATA DIVISION.
When you finish with an instance of a class, you should free it. Again, SOM
provides a method, somFree, to free the instance. The following example frees the
instance of orderObj, after which orderObj has an undefined value.
Invoke orderObj 'somFree'.
When somFree executes, it automatically invokes somUninit, another SOM method
that you can override to customize the way that your instance is freed.
390
Programming Guide
Manipulating object references
You can compare object references in conditional statements. The following
examples are all valid uses of object references in an IF statement:
If orderObj = Null . . .
If orderObj = Nulls . . .
If orderObj = univObj . . .
The first and second IF statements check whether orderObj is a null object
reference (refers to no instance). The third IF statement checks whether orderObj
and univObj refer to the same instance.
In a method there is a fourth form of conditional statement for comparing object
references:
If orderObj = Self . . .
This IF statement checks whether the instance on which the method was invoked,
SELF, refers to the same instance as orderObj.
You may need to make an object reference null or to make one object reference
refer to the same instance as another object reference. The SET statement takes care
of these situations:
Set orderObj To Null.
Set univObj To orderObj.
In the first SET statement, orderObj is set to NULL.
In the second SET statement, univObj is made to refer to the instance to which
orderObj refers. In this syntax, if the receiver (univObj) is a universal object
reference, the sender (orderObj) can be either a universal or typed object reference.
However, if the receiver is a typed object reference, the sender must also be a
typed object reference and typed to the same class or a subclass.
In a method you can use a third form of SET object reference:
Set orderObj To Self.
This SET statement makes the receiver (orderObj) refer to the same instance as that
on which the method was invoked, SELF.
Invoking methods
To use the service defined by a method, you must invoke the method with the
INVOKE statement. For example:
Invoke Orders 'somNew' Returning orderObj.
Invoke orderObj 'AddItem' Using item Returning flag.
In the first INVOKE statement, a class name is used to create a new instance whose
handle is returned in the object reference orderObj. You must define the class
name, Orders, in the REPOSITORY paragraph of the CONFIGURATION SECTION. You
must define the object reference, orderObj, as either a universal object reference or
as an object reference of type class Orders.
In the second INVOKE statement, an object reference, orderObj, is used to invoke the
method AddItem. The general syntax of this form of INVOKE is one of the following:
Invoke objref 'literal-name'.
Invoke objref identifier-name.
Chapter 24. Writing object-oriented programs
391
In both cases you must define the invoked method in the class for which the object
reference (objref) is an instance. If you use the identifier-name form of the
method, the object reference (objref) must be a universal object reference.
Conformance between the invoked method and the object reference is checked at
compile time if the following three items are all true:
1. objref is a typed object reference.
2. The literal form of the method name is used in the INVOKE statement.
3. The TYPECHK compile option is specified.
Otherwise, conformance requirements are checked at run time. Run-time checking,
however, is not as thorough as compile-time checking.
INVOKE has the optional scope terminator END-INVOKE. The USING and RETURNING
phrases on the INVOKE work the same as they do on the CALL statement. Also,
INVOKE has the optional ON EXCEPTION and NOT ON EXCEPTION phrases like the CALL
statement.
The RETURN-CODE special register is not set by a method invocation.
RELATED REFERENCES
INVOKE statement (IBM COBOL Language Reference)
Example: defining a client
The following shows a possible client program for the mail-order catalog using the
Orders and UserInterface classes:
IDENTIFICATION DIVISION.
PROGRAM-ID. 'PhoneOrders'.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
*
*
Declare the classes used in the program
REPOSITORY.
CLASS Orders IS 'Orders'
CLASS UserInterface IS 'UserInterface'.
DATA DIVISION.
WORKING-STORAGE SECTION.
*
*
Declare the object references used in the program
77 orderObj USAGE OBJECT REFERENCE Orders.
77 userObj USAGE OBJECT REFERENCE UserInterface.
*
*
Declare other data items used in the program
77 order-number PIC 9(5).
77 total-cost PIC 9(7)V99.
77 item PIC X(5).
77 action PIC X(10).
77 flag PIC 9.
PROCEDURE DIVISION.
*
*
*
*
*
*
392
Programming Guide
Create an instance of the UserInterface class - userObj
INVOKE UserInterface 'somNew' RETURNING userObj.
Create an instance of the Orders class - orderObj
INVOKE Orders 'somNew' RETURNING orderObj.
Read customer input - action and item
INVOKE userObj 'ReadUserInput' USING item action.
*
*
*
*
Begin customer driven loop based on action
PERFORM UNTIL action = 'Quit'
*
*
Do appropriate action
IF action (1:3) = 'Add'
INVOKE orderObj 'AddItem' USING item
RETURNING flag
ELSE
INVOKE orderObj 'DeleteItem' USING item
RETURNING flag
END-IF
*
*
Display result of action
INVOKE userObj 'WriteUserMessage' USING flag
*
*
Read customer input - action and item
INVOKE userObj 'ReadUserInput' USING item action
END-PERFORM.
End customer driven loop based on action
*
*
*
*
Calculate the total cost of the order
INVOKE orderObj 'ComputeCost' USING total-cost.
*
*
Determine the order number
INVOKE orderObj 'getOrderNumber'
RETURNING order-number.
*
*
Display information about the order
INVOKE userObj 'WriteUserOutput'
USING total-cost order-number.
*
*
Write the order to a file
INVOKE orderObj 'WriteOrder'.
Free the object instances - orderObj and userObj
INVOKE orderObj 'somFree'.
INVOKE userObj 'somFree'.
STOP RUN.
END PROGRAM 'PhoneOrders'.
Defining a subclass
You can make a class (called a subclass or child class) a specialization of another
class (called a superclass or parent class). The subclass is related to its superclass
by an is-a relationship. For example, “Subclass S is a type of superclass P.”
Using subclasses has several advantages:
v Reuse of code. Through inheritance, a subclass can reuse methods that already
exist in another class.
v More specific class. In a subclass you can add new methods to handle specific
instances that the superclass does not handle.
v Change in action. You can override a method that a subclass inherits from its
superclass. Overriding can can vary from a few minor changes in how the
method works to a complete overhaul of what the method does.
Chapter 24. Writing object-oriented programs
393
Division
Purpose
Syntax
IDENTIFICATION
(required)
Name a subclass. Provide
inheritance information
for it.
“CLASS-ID paragraph for defining a
subclass” (required)
ENVIRONMENT
(required)
Relate the subclass and
CONFIGURATION SECTION (required)
subclass names to external REPOSITORY paragraph for defining a
SOM names.
subclass (required)
DATA (optional)
Describe instance data the “WORKING-STORAGE SECTION for
subclass needs.
defining a subclass” on page 395 (optional)
PROCEDURE
(optional)
Define methods.
Method definitions: “Defining a subclass
method” on page 395
You must properly terminate a subclass definition with an END CLASS statement.
“Example: mail-order catalog” on page 375
“Example: defining a subclass (with methods)” on page 396
CLASS-ID paragraph for defining a subclass
The CLASS-ID paragraph in the IDENTIFICATION DIVISION names the subclass and
indicates from what superclass or superclasses the subclass inherits. For example:
Identification Division.
Required
Class-Id. BackOrders INHERITS Orders. Required
Use the CLASS-ID paragraph to name the subclass and indicate from what
superclass (or superclasses) the subclass inherits.
In the above example, BackOrders is the class name. It inherits all the methods
from Orders. Also, it can access Orders instance data if Orders provides methods to
get and set its instance data.
You must specify the names of the superclasses in the REPOSITORY paragraph in the
CONFIGURATION SECTION of the ENVIRONMENT DIVISION. Optionally, you can specify
BackOrders in the REPOSITORY paragraph.
REPOSITORY paragraph for defining a subclass
The REPOSITORY paragraph relates your subclass and class names to the subclass
and class names in the SOM interface repository. For example:
Environment Division.
Required
Configuration Section.
Required
Repository.
Required
Class BackOrders is 'BackOrders'
Class Orders is 'Orders'.
Use the REPOSITORY paragraph to specify:
v The classes from which your subclass is inheriting
v The metaclass to which your subclass belongs
v Any class referenced in methods introduced by the subclass
Optionally, you can include the name of the subclass you are defining. If you do
not include the name of your subclass, it is treated as all uppercase, regardless of
how you typed it in the CLASS-ID paragraph. In the above example, BackOrders is
stored in the SOM interface repository in mixed case.
394
Programming Guide
WORKING-STORAGE SECTION for defining a subclass
You use the WORKING-STORAGE SECTION of the subclass DATA DIVISION to describe
any extra instance data the subclass needs. For example:
Data Division.
Working-Storage Section.
01 order-status PIC X(3).
A subclass WORKING-STORAGE SECTION describes instance data that is statically
allocated when the instance is created and exists until the instance is freed. By
default, the data is global to all the methods that the subclass introduces. Instance
data in a COBOL subclass is private. No other class or subclass can reference it
directly.
Defining a subclass method
A subclass inherits the methods from its superclass. Using the OVERRIDE clause on
the METHOD-ID, you can change, or override, one or more methods that a subclass
inherits from its superclass. Also, you can add new methods that a subclass needs.
In COBOL, instance data is private, and so the superclass must provide methods to
allow the subclass to access superclass instance data, if necessary. Using the
methods that the superclass provides, a subclass can retrieve values from, or store
values in, the superclass instance data.
COBOL allows multiple inheritance, inheriting from more than one superclass. If a
conflict in method names occurs between two superclasses due to multiple
inheritance, the conflict is resolved according to the System Object Model (SOM)
rules discussed in the related reference below.
Division
Purpose
Syntax
IDENTIFICATION
(optional)
Name a method. Give
other identifying
information.
“METHOD-ID paragraph for defining a
subclass method” (optional)
ENVIRONMENT
(optional)
Same as class method
Same as for a class method
DATA (optional)
Same as class method
Same as for a class method
PROCEDURE
(optional)
Same as class method
Same as for a class method
You must properly terminate a subclass method definition with an END METHOD
statement.
“Example: mail-order catalog” on page 375
“Example: defining a subclass (with methods)” on page 396
RELATED REFERENCES
Multiple inheritance (OS/390 SOMobjects Programmer’s Guide)
METHOD-ID paragraph for defining a subclass method
Use the METHOD-ID paragraph to name the method. Other methods or programs use
this name to invoke the method. For example:
Identification Division.
Method-ID. ReadOrder.
Chapter 24. Writing object-oriented programs
395
If the subclass defines a method whose name exists in a superclass, you must
specify the OVERRIDE clause on the METHOD-ID. For example:
Identification Division.
Method-Id. AddItem Override.
When an object reference that is a handle to the BackOrders subclass invokes
AddItem, this method is invoked rather than the method in the superclass Orders.
In a subclass method, you can invoke an overridden method of a superclass by
using the following form of the INVOKE statement:
Invoke Super 'AddItem'.
This example invokes the method AddItem that is defined in the superclass rather
than the method AddItem that is defined in the subclass.
In the case of multiple inheritance, a subclass may inherit several methods with the
same name from different parents. To specify precisely which method from which
parent is invoked, use the following form of the INVOKE statement:
Invoke Class-A of Super 'AddItem'.
This example invokes the method AddItem that is defined in the superclass Class-A
rather than the method AddItem that is defined in any other superclass or in the
subclass.
Example: defining a subclass (with methods)
The new class and method definitions for the UserInterface class:
IDENTIFICATION DIVISION.
CLASS-ID. UserInterface INHERITS SOMObject.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
* Declare classes used in class definition
REPOSITORY.
CLASS SOMObject IS 'SOMObject'
CLASS UserInterface IS 'UserInterface'.
DATA DIVISION.
* Define instance data
WORKING-STORAGE SECTION.
01 uif-action PIC X(10).
88 uif-add
VALUE 'AddItem'.
88 uif-delete VALUE 'DeleteItem'.
88 uif-quit
VALUE 'Quit'.
01 uif-item
PIC X(5).
PROCEDURE DIVISION.
* Method to read customer input - request
IDENTIFICATION DIVISION.
METHOD-ID. ReadUserRequest.
DATA DIVISION.
LINKAGE SECTION.
01 request PIC X(6).
PROCEDURE DIVISION USING request.
DISPLAY 'Enter the request: new, status'.
ACCEPT request FROM SYSIN.
MOVE FUNCTION UPPER-CASE (request) TO request.
EXIT METHOD.
END METHOD ReadUserRequest.
396
Programming Guide
* Method to read customer input for new request - action and item
IDENTIFICATION DIVISION.
METHOD-ID. ReadUserInput1.
DATA DIVISION.
LINKAGE SECTION.
01 action PIC X(10).
01 item
PIC X(5).
PROCEDURE DIVISION USING item action.
DISPLAY 'Enter the action: add, delete, quit'.
ACCEPT action FROM SYSIN.
MOVE FUNCTION UPPER-CASE (action) TO action.
EVALUATE TRUE
WHEN action = 'ADD'
SET uif-add TO TRUE
PERFORM Get-Item
WHEN action = 'DELETE'
SET uif-delete TO TRUE
PERFORM Get-Item
WHEN action = 'QUIT'
SET uif-quit TO TRUE
END-EVALUATE.
MOVE uif-action TO action.
EXIT METHOD.
Get-Item.
DISPLAY 'Enter the item'.
ACCEPT item FROM SYSIN.
MOVE item TO uif-item.
END METHOD ReadUserInput1.
* Method to read customer input for status request - order number
IDENTIFICATION DIVISION.
METHOD-ID. ReadUserInput2.
|
|
|
|
DATA DIVISION.
LINKAGE SECTION.
01 order-numb PIC 9(5).
PROCEDURE DIVISION USING order-numb.
DISPLAY 'Enter the order number'.
ACCEPT order-numb FROM SYSIN.
EXIT METHOD.
END METHOD ReadUserInput2.
* Method to inform customer how action was completed
IDENTIFICATION DIVISION.
METHOD-ID. WriteUserMessage.
DATA DIVISION.
LINKAGE SECTION.
01 flag PIC 9.
PROCEDURE DIVISION USING flag.
IF flag = 0
DISPLAY uif-action
' successfully completed on '
uif-item
ELSE
DISPLAY uif-action
' unsuccessfully completed on '
uif-item
END-IF.
EXIT METHOD.
END METHOD WriteUserMessage.
Chapter 24. Writing object-oriented programs
397
* Method to display order information
IDENTIFICATION DIVISION.
METHOD-ID. WriteUserOutput.
DATA DIVISION.
LOCAL-STORAGE SECTION.
77 formated-cost PIC $Z,ZZZ,ZZ9.99.
LINKAGE SECTION.
01 total-cost
PIC 9(7)V99.
01 order-number PIC 9(5).
PROCEDURE DIVISION USING total-cost order-number.
MOVE total-cost TO formated-cost.
DISPLAY 'Your order costs ' formated-cost.
DISPLAY 'Your order number is ' order-number.
EXIT METHOD.
END METHOD WriteUserOutput.
* Method to display out of stock items
IDENTIFICATION DIVISION.
METHOD-ID. WriteUserStatus.
DATA DIVISION.
LOCAL-STORAGE SECTION.
77 sub PIC 99.
LINKAGE SECTION.
01 out-table.
02 out-entry OCCURS 10 TIMES.
03 out-item PIC X(5).
01 out-count PIC 99.
PROCEDURE DIVISION USING out-table out-count.
IF out-count > 0
PERFORM VARYING sub FROM 1 BY 1
UNTIL sub > out-count
DISPLAY 'Out of stock '
out-item (sub)
END-PERFORM
END-IF.
EXIT METHOD.
END METHOD WriteUserStatus.
END CLASS UserInterface.
The new class and method definitions for the Orders class:
IDENTIFICATION DIVISION.
CLASS-ID. Orders INHERITS SOMObject.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
* Declare classes used in program
REPOSITORY.
CLASS SOMObject IS 'SOMObject'
CLASS Orders IS 'Orders'.
DATA DIVISION.
* Define instance data
WORKING-STORAGE SECTION.
01 order-number PIC 9(5).
01 order-date
PIC X(8).
01 order-count
PIC 99.
01 order-table.
02 order-entry OCCURS 10 TIMES.
03 order-item PIC X(5).
PROCEDURE DIVISION.
* Method to intialize instance data
* - this overrides the default somInit method
398
Programming Guide
IDENTIFICATION DIVISION.
METHOD-ID. 'somInit' OVERRIDE.
PROCEDURE DIVISION.
MOVE FUNCTION CURRENT-DATE(1:8) TO order-date.
COMPUTE order-number = FUNCTION RANDOM ( 99999 ).
MOVE 0 TO order-count.
INITIALIZE order-table.
EXIT METHOD.
END METHOD 'somInit'.
* Method to set instance data read by subclass
IDENTIFICATION DIVISION.
METHOD-ID. 'setInstanceData'.
DATA DIVISION.
LINKAGE SECTION.
01 in-order.
02 in-order-number PIC 9(5).
02 in-order-date
PIC X(8).
02 in-order-count
PIC 99.
02 in-order-table.
03 in-order-entry OCCURS 10 TIMES.
04 in-order-item PIC X(5).
PROCEDURE DIVISION USING in-order.
MOVE in-order-number TO order-number.
MOVE in-order-date
TO order-date.
MOVE in-order-count TO order-count.
MOVE in-order-table TO order-table.
EXIT METHOD.
END METHOD 'setInstanceData'.
* Method to get instance data and give it to subclass
IDENTIFICATION DIVISION.
METHOD-ID. 'getInstanceData'.
DATA DIVISION.
LINKAGE SECTION.
01 out-order.
02 out-order-number PIC 9(5).
02 out-order-date
PIC X(8).
02 out-order-count
PIC 99.
02 out-order-table.
03 out-order-entry OCCURS 10 TIMES.
04 out-order-item PIC X(5).
PROCEDURE DIVISION USING out-order.
MOVE order-number TO out-order-number.
MOVE order-date
TO out-order-date.
MOVE order-count TO out-order-count.
MOVE order-table TO out-order-table.
EXIT METHOD.
END METHOD 'getInstanceData'.
* Method to add an item to an order
IDENTIFICATION DIVISION.
METHOD-ID. AddItem.
DATA DIVISION.
LOCAL-STORAGE SECTION.
77 sub PIC 99.
01 found-flag PIC 9 VALUE 1.
88 found VALUE 0.
LINKAGE SECTION.
01 in-item
PIC X(5).
01 add-flag PIC 9.
Chapter 24. Writing object-oriented programs
399
PROCEDURE DIVISION USING in-item
RETURNING add-flag.
MOVE 1 TO add-flag.
PERFORM VARYING sub FROM 1 BY 1
UNTIL (sub > 10) OR (found)
IF order-item (sub) = SPACES
MOVE in-item TO order-item (sub)
ADD 1 TO order-count
MOVE 0 TO add-flag
SET found TO TRUE
END-IF
END-PERFORM.
EXIT METHOD.
END METHOD AddItem.
* Method to delete an item from an order
IDENTIFICATION DIVISION.
METHOD-ID. DeleteItem.
DATA DIVISION.
LOCAL-STORAGE SECTION.
77 sub PIC 99.
01 found-flag PIC 9 VALUE 1.
88 found VALUE 0.
LINKAGE SECTION.
01 out-item
PIC X(5).
01 delete-flag PIC 9.
PROCEDURE DIVISION USING out-item
RETURNING delete-flag.
MOVE 1 TO delete-flag.
PERFORM VARYING sub FROM 1 BY 1
UNTIL (sub > 10) OR (found)
IF order-item (sub) = out-item
MOVE SPACES TO order-item (sub)
SUBTRACT 1 FROM order-count
MOVE 0 TO delete-flag
SET found TO TRUE
END-IF
END-PERFORM.
EXIT METHOD.
END METHOD DeleteItem.
* Method to compute the total cost of an order
IDENTIFICATION DIVISION.
METHOD-ID. ComputeCost.
DATA DIVISION.
LOCAL-STORAGE SECTION.
77 sub
PIC 99.
77 cost PIC 9(5)V99.
LINKAGE SECTION.
01 total-cost PIC 9(7)V99.
PROCEDURE DIVISION USING total-cost.
MOVE 0 TO total-cost.
PERFORM VARYING sub FROM 1 BY 1
UNTIL sub > order-count
* Call a subroutine
*
NOTE: The subroutine code is not
*
included in this example.
CALL 'InventoryGetCost'
USING order-item (sub) cost
ADD cost TO total-cost
END-PERFORM.
EXIT METHOD.
400
Programming Guide
END METHOD ComputeCost.
* Method to return the order number
IDENTIFICATION DIVISION.
METHOD-ID. 'getOrderNumber'.
DATA DIVISION.
LINKAGE SECTION.
01 ord-num PIC 9(5).
PROCEDURE DIVISION RETURNING ord-num.
MOVE order-number TO ord-num.
EXIT METHOD.
END METHOD 'getOrderNumber'.
* Method to write completed order to a file
IDENTIFICATION DIVISION.
METHOD-ID. WriteOrder.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT order-file ASSIGN OrdrFile.
DATA DIVISION.
FILE SECTION.
FD order-file EXTERNAL.
01 order-record PIC X(80).
LOCAL-STORAGE SECTION.
01 print-line.
02 print-order-number PIC 9(5).
02 print-order-date
PIC X(8).
02 print-order-count
PIC 99.
02 print-order-table.
03 print-order-entry OCCURS 10 TIMES.
04 print-order-item PIC X(5).
PROCEDURE DIVISION.
OPEN OUTPUT order-file.
MOVE order-number TO print-order-number.
MOVE order-date
TO print-order-date.
MOVE order-count TO print-order-count.
MOVE order-table TO print-order-table.
WRITE order-record FROM print-line.
CLOSE order-file.
EXIT METHOD.
END METHOD WriteOrder.
END CLASS Orders.
The subclass and method definitions for the NewOrders subclass:
IDENTIFICATION DIVISION.
CLASS-ID. NewOrders INHERITS Orders.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
* Declare classes used in subclass definition
REPOSITORY.
CLASS NewOrders IS 'NewOrders'
CLASS Orders IS 'Orders'.
DATA DIVISION.
PROCEDURE DIVISION.
Chapter 24. Writing object-oriented programs
401
* All methods are inherited from superclass
END CLASS NewOrders.
The subclass and method definitions for the BackOrders subclass:
IDENTIFICATION DIVISION.
CLASS-ID. BackOrders INHERITS Orders.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
* Declare classes used in subclass definition
REPOSITORY.
CLASS BackOrders IS 'BackOrders'
CLASS Orders IS 'Orders'.
DATA DIVISION.
PROCEDURE DIVISION.
* Method to read back order from file
IDENTIFICATION DIVISION.
METHOD-ID. ReadOrder.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT backorder-file ASSIGN BackFile.
DATA DIVISION.
FILE SECTION.
FD backorder-file EXTERNAL.
01 backorder-record PIC X(80).
LOCAL-STORAGE SECTION.
01 backorder.
02 backorder-number PIC 9(5).
02 backorder-date
PIC X(8).
02 backorder-count
PIC 99.
02 backorder-table.
03 backorder-entry OCCURS 10 TIMES.
04 backorder-item PIC X(5).
77 eof-flag PIC 9 VALUE 1.
88 eof VALUE 0.
LINKAGE SECTION.
01 order-number PIC 9(5).
PROCEDURE DIVISION USING order-number.
OPEN INPUT backorder-file.
PERFORM UNTIL eof
READ backorder-file INTO backorder
AT END
SET eof TO TRUE
NOT AT END
IF order-number = backorder-number
INVOKE SELF 'setInstanceData' USING backorder
END-IF
END-READ
END-PERFORM.
CLOSE backorder-file.
EXIT METHOD.
END METHOD ReadOrder.
* Method to check whether item is still not in stock
IDENTIFICATION DIVISION.
METHOD-ID. CheckItem.
DATA DIVISION.
402
Programming Guide
LOCAL-STORAGE SECTION.
01 backorder.
02 backorder-number PIC 9(5).
02 backorder-date
PIC X(8).
02 backorder-count
PIC 99.
02 backorder-table.
03 backorder-entry OCCURS 10 TIMES.
04 backorder-item PIC X(5).
77 sub PIC 99.
77 status-flag PIC 9.
88 in-stock VALUE 0.
88 out-stock VALUE 1.
LINKAGE SECTION.
01 out-table.
02 out-entry OCCURS 10 TIMES.
03 out-item PIC X(5).
01 out-count PIC 99.
PROCEDURE DIVISION USING out-table out-count.
INVOKE SELF 'getInstanceData' USING backorder.
MOVE 0 TO out-count.
PERFORM VARYING sub FROM 1 BY 1
UNTIL sub > backorder-count
* Call a subroutine
*
NOTE: The subroutine code is not
*
included in this example.
CALL 'InventoryGetItem'
USING backorder-item (sub) status-flag
IF out-stock
ADD 1 TO out-count
MOVE backorder-item (sub) TO out-item (out-count)
END-IF
END-PERFORM.
EXIT METHOD.
END METHOD CheckItem.
END CLASS BackOrders.
A possible new client program:
IDENTIFICATION DIVISION.
PROGRAM-ID. 'PhoneOrders'.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
*
*
Declare the classes used in the program
REPOSITORY.
CLASS NewOrders IS 'NewOrders'
CLASS BackOrders IS 'BackOrders'
CLASS UserInterface IS 'UserInterface'.
DATA DIVISION.
WORKING-STORAGE SECTION.
*
*
*
Declare the object references used in the program
Note: univObj is a universal object reference
77 univObj USAGE OBJECT REFERENCE.
77 userObj USAGE OBJECT REFERENCE UserInterface.
*
*
Declare other data items used in the program
77 order-number PIC 9(5).
77 total-cost PIC 9(7)V99.
77 out-count PIC 9(2).
77 request PIC X(6).
77 action PIC X(10).
77 flag PIC 9.
Chapter 24. Writing object-oriented programs
403
77
01
item PIC X(5).
item-table.
02 item-entry OCCURS 10 TIMES.
03 item-element PIC X(5).
PROCEDURE DIVISION.
*
*
*
*
Create an instance of the UserInterface class - userObj
INVOKE UserInterface 'somNew' RETURNING userObj.
*
*
Read customer input - request
INVOKE userObj 'ReadUserRequest' USING request.
*
*
What is the customer's request?
IF request = 'STATUS'
PERFORM CheckBackOrder
ELSE
PERFORM CreateNewOrder
END-IF.
Free the instance of the UserInterface class - userObj
INVOKE userObj 'somFree'.
STOP RUN.
CreateNewOrder.
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
404
Programming Guide
Create an instance of the NewOrders class - univObj
INVOKE NewOrders 'somNew' RETURNING univObj.
Read customer input - action and item
INVOKE userObj 'ReadUserInput1' USING item action.
Begin customer driven loop based on action
PERFORM UNTIL action = 'Quit'
Do appropriate action
IF action (1:3) = 'Add'
INVOKE univObj 'AddItem' USING item
RETURNING flag
ELSE
INVOKE univObj 'DeleteItem' USING item
RETURNING flag
END-IF
Display result of action
INVOKE userObj 'WriteUserMessage' USING flag
Read customer input - action and item
INVOKE userObj 'ReadUserInput1' USING item action
END-PERFORM.
End customer driven loop based on action
Calculate the total cost of the order
INVOKE univObj 'ComputeCost' USING total-cost.
Determine the order number
INVOKE univObj 'getOrderNumber'
RETURNING order-number.
Display information about the order
INVOKE userObj 'WriteUserOutput'
USING total-cost order-number.
*
*
*
*
Write the order to a file
INVOKE univObj 'WriteOrder'.
Free the NewOrders instance - univObj
INVOKE univObj 'somFree'.
CheckBackOrder.
*
*
*
*
Create an instance of the BackOrders class - univObj
INVOKE BackOrders 'somNew' RETURNING univObj.
*
*
Read customer input - order number
INVOKE userObj 'ReadUserInput2' USING order-number.
*
*
Read the back-ordered information from a file
INVOKE univObj 'ReadOrder' USING order-number.
*
*
Check whether the back-ordered items are now in stock
INVOKE univObj 'CheckItem' USING item-table out-count.
*
*
Display the status of the back-ordered items
INVOKE userObj 'WriteUserStatus' USING item-table out-count.
Free the BackOrders instance - univObj
INVOKE univObj 'somFree'.
END PROGRAM 'PhoneOrders'.
Defining a metaclass
A metaclass is a special type of class whose instances are called class objects. Class
objects are the run-time objects that represent SOM classes. You can provide
explicit metaclass definitions for specialized purposes. Otherwise, object-oriented
COBOL applications use the default metaclasses provided automatically by the
SOM environment.
Metaclasses have their own methods and can have their own instance data. The
most common use of a metaclass is to control how an instance of a class is created.
Metaclasses are also useful when multiple instances of a class are created and data
must be gathered from all the instances.
Division
Purpose
Syntax
IDENTIFICATION
(required)
Name the metaclass.
Provide inheritance
information for it.
“CLASS-ID paragraph for defining a
metaclass” on page 406 (required)
ENVIRONMENT
(required)
Relate the metaclass and
class names to external
SOM names.
CONFIGURATION section (required)
“REPOSITORY paragraph for defining a
metaclass” on page 406 (required)
DATA (optional)
Describe instance data the “WORKING-STORAGE SECTION for
metaclass needs.
defining a metaclass” on page 406 (optional)
PROCEDURE
(optional)
Define methods.
“Defining a metaclass method” on page 406
You must properly terminate a metaclass definition with an END CLASS statement.
“Example: mail-order catalog” on page 375
“Example: defining a metaclass (with methods)” on page 408
Chapter 24. Writing object-oriented programs
405
RELATED CONCEPTS
SOMClass Class Object (OS/390 SOMobjects Programmer’s Guide)
CLASS-ID paragraph for defining a metaclass
The CLASS-ID paragraph names the metaclass and indicates from what base System
Object Model (SOM) class the metaclass inherits. For example:
Identification Division.
Class-Id. MetaBackOrders INHERITS SOMClass.
Required
Required
In the above example, MetaBackOrders is the class name. It inherits from the base
SOM class SOMClass.
All metaclasses inherit directly or indirectly from SOMClass.
You must specify SOMClass in the REPOSITORY paragraph of the ENVIRONMENT
DIVISION. Optionally, you can specify MetaBackOrders in the REPOSITORY paragraph.
REPOSITORY paragraph for defining a metaclass
The REPOSITORY paragraph relates your metaclass and class names to the metaclass
and class names in the SOM interface repository. For example:
Environment Division.
Required
Configuration Section.
Required
Repository.
Required
Class MetaBackOrders is 'MetaBackOrders'
Class SOMClass is 'SOMClass'.
You must include the following classes:
v SOM base classes.
In the above example, CLASS SOMClass IS ’SOMClass’ indicates what you are
calling SOMClass in your COBOL program is also called SOMClass in the SOM
repository.
v The classes from which your metaclass is inheriting.
v Any class referenced in methods introduced by the metaclass.
You can optionally include the name of the metaclass that you are defining. If you
do not include the name of your metaclass, it is treated as all uppercase regardless
of how you typed it in the CLASS-ID paragraph. In the above example,
MetaBackOrders is stored in the SOM interface repository in mixed case.
WORKING-STORAGE SECTION for defining a metaclass
A metaclass WORKING-STORAGE SECTION describes instance data that is statically
allocated when the first instance of an object in the metaclass is created and exists
until the COBOL run unit terminates. For example:
Data Division.
Working-Storage Section.
01 total-orders PIC X(3).
By default, the data is global to all the methods that the metaclass introduces.
Instance data in a COBOL metaclass is private. No other class or metaclass can
reference it.
Defining a metaclass method
You define metaclass methods the same way that you define regular class methods.
The only real difference is that metaclass methods are focused on object creation
406
Programming Guide
and initialization, or class-wide information, whereas ordinary class methods are
instance-specific.
Division
Purpose
Syntax
IDENTIFICATION
(optional)
Same as subclass method
“METHOD-ID paragraph for defining a
subclass method” on page 395 (optional)
ENVIRONMENT
(optional)
Same as class method
Same as for a class method
DATA (optional)
Same as class method
Same as for a class method
PROCEDURE
(optional)
Same as class method
Same as for a class method
You must properly terminate a metaclass method definition with an END METHOD
statement.
“Example: mail-order catalog” on page 375
“Example: defining a metaclass (with methods)” on page 408
RELATED TASKS
“Invoking a metaclass constructor method”
“Defining a class method” on page 381
“Defining a subclass method” on page 395
Invoking a metaclass constructor method
A metaclass method that creates an instance of a class is called a constructor
method. A metaclass constructor method is usually invoked with a class name.
Therefore, use the following form of the INVOKE statement in the constructor
method to create an instance of the class:
Invoke Self 'somNew' Returning anObj.
This example creates an instance of the class on which the method was invoked,
Self, and returns the handle to that instance in the object reference anObj.
Changing the definition of a class or subclass
When a class or subclass uses an explicit metaclass, you must specify the name of
the metaclass with the METACLASS IS clause in the CLASS-ID paragraph. For
example:
Identification Division.
Class-Id. BackOrders Inherits Orders
Metaclass is MetaBackOrders.
Also, you must specify the name of the metaclass in the REPOSITORY paragraph of
the CONFIGURATION SECTION. For example:
Environment Division.
Configuration Section.
Repository.
Class MetaBackOrders Is 'MetaBackOrders'
Class BackOrders Is 'BackOrders'
Class Orders Is 'Orders'.
Changing a client program
To use the metaclass constructor method, the client program invokes the
constructor method instead of somNew. For example:
|
Invoke BackOrders 'CreateBackOrders' Using order-number Returning anObj.
Chapter 24. Writing object-oriented programs
407
The method CreateBackOrders is defined in the metaclass for BackOrders. This
method invokes somNew to create an instance, reads the data from the file using the
order number, and returns the handle to the instance in the object reference anObj.
You can invoke any method in a metaclass with the class name. For example:
Invoke BackOrders 'CountBackOrders' Returning out-count.
|
Or you can define a metaclass object reference as a handle to the metaclass. For
example:
Working-Storage Section.
01 metaObj Usage Object Reference Metaclass BackOrders.
The object reference metaObj is a handle to the metaclass for BackOrders, not a
handle to BackOrders itself.
The metaclass object reference is used as follows:
Procedure Division.
. . .
Invoke backObj 'somGetClass' Returning metaObj.
Invoke metaObj 'CountBackOrders' Returning out-count.
|
The first INVOKE statement invokes a SOM method somGetClass which takes an
object reference, backObj, to an instance and returns an object reference, metaObj, to
the metaclass to which backObj belongs.
The second INVOKE statement uses the object reference to the metaclass, metaObj to
invoke the method CountBackOrders which is defined in the metaclass.
“Example: defining a metaclass (with methods)”
Example: defining a metaclass (with methods)
BackOrders requires the reading of a file to establish its instance data. Reading the
file cannot be done by somInit because an order number is needed as a parameter.
This is a good place to use a metaclass with a constructor method to create the
instance of BackOrders and read the file.
The metaclass and method definitions for the BackOrders subclass:
IDENTIFICATION DIVISION.
CLASS-ID. MetaBackOrders INHERITS SOMClass.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
* Declare classes used in metaclass definition
REPOSITORY.
CLASS MetaBackOrders IS 'MetaBackOrders'
CLASS BackOrders IS 'BackOrders'
CLASS SOMClass IS 'SOMClass'.
DATA DIVISION.
* Define instance data
WORKING-STORAGE SECTION.
01 status-count PIC 99.
PROCEDURE DIVISION.
* Method to initialize instance data
IDENTIFICATION DIVISION.
METHOD-ID. 'somInit' OVERRIDE.
PROCEDURE DIVISION.
408
Programming Guide
MOVE 0 TO status-count.
EXIT METHOD.
END METHOD 'somInit'.
* Method to create and initialize instances of BackOrders
IDENTIFICATION DIVISION.
METHOD-ID. CreateBackOrders.
DATA DIVISION.
LINKAGE SECTION.
01 order-number PIC 9(5).
01 anObj USAGE OBJECT REFERENCE.
PROCEDURE DIVISION USING order-number RETURNING anObj.
INVOKE SELF 'somNew' RETURNING anObj.
INVOKE anObj 'ReadOrder' USING order-number.
ADD 1 TO status-count.
EXIT METHOD.
END METHOD CreateBackOrders.
* Method to return the number of back orders processed
IDENTIFICATION DIVISION.
METHOD-ID. CountBackOrders.
DATA DIVISION.
LINKAGE SECTION.
01 out-count PIC 9(2).
PROCEDURE DIVISION RETURNING out-count.
MOVE status-count TO out-count.
EXIT METHOD.
END METHOD CountBackOrders.
END CLASS MetaBackOrders.
The new subclass and method definitions for the BackOrders subclass:
IDENTIFICATION DIVISION.
CLASS-ID. BackOrders INHERITS Orders
METACLASS MetaBackOrders.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
* Declare classes used in subclass definition
REPOSITORY.
CLASS MetaBackOrders IS 'MetaBackOrders'
CLASS BackOrders IS 'BackOrders'
CLASS Orders IS 'Orders'.
DATA DIVISION.
PROCEDURE DIVISION.
* Method to read back order from file
IDENTIFICATION DIVISION.
METHOD-ID. ReadOrder.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT backorder-file ASSIGN BackFile.
DATA DIVISION.
FILE SECTION.
FD backorder-file EXTERNAL.
01 backorder-record PIC X(80).
LOCAL-STORAGE SECTION.
Chapter 24. Writing object-oriented programs
409
01
backorder.
02 backorder-number PIC 9(5).
02 backorder-date
PIC X(8).
02 backorder-count
PIC 99.
02 backorder-table.
03 backorder-entry OCCURS 10 TIMES.
04 backorder-item PIC X(5).
77 eof-flag PIC 9 VALUE 1.
88 eof VALUE 0.
LINKAGE SECTION.
01 order-number PIC 9(5).
PROCEDURE DIVISION USING order-number.
OPEN INPUT backorder-file.
PERFORM UNTIL eof
READ backorder-file INTO backorder
AT END
SET eof TO TRUE
NOT AT END
IF order-number = backorder-number
INVOKE SELF 'setInstanceData' USING backorder
END-IF
END-READ
END-PERFORM.
CLOSE backorder-file.
EXIT METHOD.
END METHOD ReadOrder.
* Method to check whether item is still not in stock
IDENTIFICATION DIVISION.
METHOD-ID. CheckItem.
DATA DIVISION.
LOCAL-STORAGE SECTION.
01 backorder.
02 backorder-number PIC 9(5).
02 backorder-date
PIC X(8).
02 backorder-count
PIC 99.
02 backorder-table.
03 backorder-entry OCCURS 10 TIMES.
04 backorder-item PIC X(5).
77 sub PIC 99 VALUE 0.
77 status-flag PIC 9.
88 in-stock
VALUE 0.
88 out-stock VALUE 1.
LINKAGE SECTION.
01 out-table.
02 out-entry OCCURS 10 TIMES.
03 out-item PIC X(5).
01 out-count PIC 99.
PROCEDURE DIVISION USING out-table out-count.
INVOKE SELF 'getInstanceData' USING backorder.
MOVE 0 TO out-count.
PERFORM VARYING sub FROM 1 BY 1
UNTIL sub > backorder-count
* Call a subroutine
*
NOTE: The subroutine code is not
*
included in this example.
CALL 'InventoryGetItem'
USING backorder-item (sub) status-flag
IF out-stock
ADD 1 TO out-count
MOVE backorder-item (sub) TO out-item (out-count)
END-IF
END-PERFORM.
410
Programming Guide
EXIT METHOD.
END METHOD CheckItem.
END CLASS BackOrders.
A possible new client program:
IDENTIFICATION DIVISION.
PROGRAM-ID. 'PhoneOrders'.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
*
*
Declare the classes used in the program
REPOSITORY.
CLASS NewOrders IS 'NewOrders'
CLASS BackOrders IS 'BackOrders'
CLASS UserInterface IS 'UserInterface'.
DATA DIVISION.
WORKING-STORAGE SECTION.
*
*
Declare the object references used in the program
77 univObj USAGE OBJECT REFERENCE.
* Note: metaObj is an object reference to a metaclass
77 metaObj USAGE OBJECT REFERENCE METACLASS BackOrders.
77 userObj USAGE OBJECT REFERENCE UserInterface.
*
* Declare other data items used in the program
77 order-number PIC 9(5).
77 total-cost PIC 9(7)V99.
77 out-count PIC 9(2).
77 request PIC X(6).
77 action PIC X(10).
77 flag PIC 9.
77 item PIC X(5).
01 item-table.
02 item-entry OCCURS 10 TIMES.
03 item-element PIC X(5).
PROCEDURE DIVISION.
*
*
*
*
Create an instance of the UserInterface class - userObj
INVOKE UserInterface 'somNew' RETURNING userObj.
*
*
Read customer input - request
INVOKE userObj 'ReadUserRequest' USING request.
*
*
What is the customer's request?
IF request = 'STATUS'
PERFORM CheckBackOrder
ELSE
PERFORM CreateNewOrder
END-IF.
Free the instance of the UserInterface class - userObj
INVOKE userObj 'somFree'.
STOP RUN.
CreateNewOrder.
*
*
*
*
Create an instance of the NewOrders class - univObj
INVOKE NewOrders 'somNew' RETURNING univObj.
Read customer input - action and item
INVOKE userObj 'ReadUserInput1' USING item action.
Chapter 24. Writing object-oriented programs
411
*
*
*
*
Begin customer driven loop based on action
PERFORM UNTIL action = 'Quit'
*
*
Do appropriate action
IF action (1:3) = 'Add'
INVOKE univObj 'AddItem' USING item
RETURNING flag
ELSE
INVOKE univObj 'DeleteItem' USING item
RETURNING flag
END-IF
*
*
Display result of action
INVOKE userObj 'WriteUserMessage' USING flag
*
*
Read customer input - action and item
INVOKE userObj 'ReadUserInput1' USING item action
END-PERFORM.
End customer driven loop based on action
*
*
*
*
Calculate the total cost of the order
INVOKE univObj 'ComputeCost' USING total-cost.
*
*
Determine the order number
INVOKE univObj 'getOrderNumber'
RETURNING order-number.
*
*
Display information about the order
INVOKE userObj 'WriteUserOutput'
USING total-cost order-number.
*
*
Write the order to a file
INVOKE univObj 'WriteOrder'.
Free the NewOrders instance - univObj
INVOKE univObj 'somFree'.
CheckBackOrder.
*
*
*
*
|
*
*
*
*
*
*
*
*
*
412
Programming Guide
Read customer input - order number
INVOKE userObj 'ReadUserInput2' USING order-number.
Begin customer driven loop based order number
PERFORM UNTIL order-number = 0
Create an instance of the BackOrders class (univObj) and
read the back order from a file using a metaclass method
INVOKE BackOrders 'CreateBackOrders'
USING order-number RETURNING univObj
Check whether the back-ordered items are now in stock
INVOKE univObj 'CheckItem'
USING item-table out-count
Display the status of the back-ordered items
INVOKE userObj 'WriteUserStatus'
USING item-table out-count
Read customer input - order number
INVOKE userObj 'ReadUserInput2'
*
*
USING order-number
END-PERFORM.
End customer driven loop based on order number
*
*
*
*
*
Get an object reference to the metaclass
Note: somGetClass is a SOM method
INVOKE univObj 'somGetClass' RETURNING metaObj.
|
*
*
*
How many back orders were processed?
Note: Metaclass object reference to invoke metaclass method
INVOKE metaObj 'CountBackOrders' RETURNING out-count.
DISPLAY out-count ' back orders were processed.'.
Free the metaclass instance - metaObj
Note: This also frees all BackOrders instances
INVOKE metaObj 'somFree'.
END PROGRAM 'PhoneOrders'.
Chapter 24. Writing object-oriented programs
413
414
Programming Guide
Chapter 25. System Object Model
The System Object Model (SOM) is an object-oriented programming technology for
building, packaging, and using class libraries. With SOM, class implementers can
describe the interface to a class in a standard language called the Interface Definition
Language (IDL). Unlike the object model found in most object-oriented
programming languages, SOM is language-neutral. It provides encapsulation,
inheritance, and polymorphism without requiring both the implementer and the
user of a SOM class to use the same programming language.
The object-oriented COBOL language support is based on OS/390 SOMobjects.
This support is not available on VM/CMS.
RELATED CONCEPTS
“SOM Interface Repository”
“SOM services” on page 420
RELATED TASKS
“Defining a class” on page 378
“Chapter 26. Using SOM IDL-based class libraries” on page 425
OS/390 SOMobjects Programmer’s Guide
RELATED REFERENCES
“SOM methods and functions” on page 420
SOM Interface Repository
The SOM Interface Repository (IR) is a database in which the SOM compiler
optionally creates and maintains class interface definitions. The COBOL compiler
uses the SOM IR when compiling object-oriented COBOL programs. When you
compile a class definition or client program with the IDLGEN or the TYPECHK option,
the interface information for referenced classes must be present in the IR. (You
declare all referenced classes in the REPOSITORY paragraph of the CONFIGURATION
SECTION.)
RELATED TASKS
“Accessing the SOM Interface Repository”
“Compiling and linking programs that call SOM functions” on page 421
“Populating the SOM Interface Repository” on page 416
Accessing the SOM Interface Repository
You specify which interface repository (IR) files to use by setting the SOM
environment variable SOMIR to the names of the files. For example:
SOMIR=//’prefix.class.SOMIR’;
prefix.class.SOMIR is the data set name (DSN) of the IR file. Substitute your OS/390
user ID for prefix, and a meaningful name for class.
You set this and other SOM environment variables in a SOM configuration file. See
the cross-references below for further information on setting up configuration files
and on SOM environment variables.
© Copyright IBM Corp. 1991, 2000
415
SOM provides a predefined interface repository data set called somhlq.SGOSIR,
which contains the interfaces of all the SOM system classes. (somhlq represents the
high-level qualifiers of the data sets where SOM is installed on your system.) Do
not add your class interfaces to this IR. Define your own IR files and set SOMIR to
an ordered list of IR files. SOM reads IR files in the list from left to right, but
updates only the rightmost IR file. So specify your development IR file as the
rightmost in the list. You can of course have application IR files (which are not
subject to change) earlier in the list. For example:
SOMIR=//'somhlq.SGOSIR';//'prefix.app.SOMIR';//'prefix.user.IR';
In this case, somhlq.SGOSIR and prefix.app.SOMIR are the SOM and application IR
files, respectively, and are not changed. prefix.user.IR is the working IR file, which
is updated.
When you compile an application with the IDLGEN or TYPECHK compiler options,
you must:
1. Define an IR file.
2. Create a SOM configuration file whose SOMIR setting specifies the IR as the
rightmost in the list of IR files.
3. Provide a SOMENV DD statement (or equivalent TSO ALLOCATE command) that
refers to the configuration file.
RELATED CONCEPTS
“SOM Interface Repository” on page 415
“SOM services” on page 420
RELATED TASKS
Setting up configuration files (OS/390 SOMobjects Programmer’s Guide)
RELATED REFERENCES
“SOM environment variables” on page 417
“SOM methods and functions” on page 420
Populating the SOM Interface Repository
To populate the IR with interface information from COBOL classes:
1. Compile the COBOL class definition with the COBOL compiler, specifying the
IDLGEN compiler option.
2. Compile the IDL source files with the SOM compiler, using the IR emitter.
You might have to compile COBOL class definitions that have complex
interdependencies in two steps. For example, there could be circular compilation
order dependencies, such as when two class definitions each contain references to
the other. To compile such complex configurations:
1. Compile all of the COBOL class definition source files using the IDLGEN,
NOTYPECHK, and NOCOMPILE compiler options. This compile generates IDL files for
the class interfaces, but does not perform type checking or generate an object
file.
2. Compile the IDL files with the SOM compiler, using the IR emitter. This
compilation populates the IR with the class interface information. For example,
this TSO command:
sc -usir myclass.idl
416
Programming Guide
starts the SOM compiler, sc, against the file myclass.idl with the -usir option,
which updates the rightmost file in the list of IR files specified for the SOMIR
environment variable.
3. Compile the COBOL class definitions again, using the NOIDLGEN and TYPECHK
compiler options. This final compile performs full type checking and generates
object files.
“Example: sample JCL for an object-oriented application” on page 418
RELATED CONCEPTS
“SOM Interface Repository” on page 415
RELATED REFERENCES
“Class initialization” on page 421
SOM environment variables
|
|
|
Environment variables provide information needed by the COBOL compiler and
run-time environment and the SOM compiler and run-time environment. You
specify the environment variables in a SOM configuration file (also known as a SOM
profile).
|
|
|
The configuration file is organized into stanzas that contain specific environment
variables. Each stanza is headed by the name of the stanza in brackets. For
example, [somc] introduces the stanza for the SOM compiler.
|
Set the following environment variables, within the proper stanza, as shown:
|
SOM kernel stanza:
SMLANG
Specifies the language for SOM messages.
For example:
|
|
|
[somk]
SMLANG=EnUs
SOM compiler stanza:
SMEMIT
Specifies which emitters the SOM compiler runs.
For a COBOL class, the most frequently used emitters are the ir
emitter, which populates the interface repository, and the .h
emitter, which produces a header file for use by a C client of the
COBOL class.
SMINCLUDE
Specifies where the SOM compiler looks for #include files referred
to by the IDL file being compiled.
For example:
|
|
|
|
[somc]
SMEMIT=ir:h
SMINCLUDE=//'somhlq.SGOSIDL';//'prefix.MYCLASS.IDL';
SOM interface repository stanza:
Chapter 25. System Object Model
417
SOMIR
Specifies the location of the interface repository files.
For example:
[somir]
SOMIR=//'somhlq.SGOSIR';//'prefix.LOCAL.SOMIR';
|
|
See a complete sample SOM configuration file in note (6) to the JCL in the example
below (“Example: sample JCL for an object-oriented application”).
RELATED TASKS
Setting up configuration files (OS/390 SOMobjects Programmer’s Guide)
Example: sample JCL for an object-oriented application
The following series of JCL statements compiles a COBOL class definition with
type checking and IDL generation, and then prelinks and link-edits the class to
create a DLL. The generated IDL for the class is compiled with the SOM compiler
to populate the interface repository. The COBOL client program is then compiled
with type checking, validating that its use of the class interface is correct, and the
client code is prelinked and linked to form the main load module. Finally the
application is run, and the client load module accesses both the COBOL class and
the SOM kernel from DLLs.
The example uses standard cataloged procedures, augmented by additional DD
statements required for processing object-oriented programs.
//OOSAMPLE JOB ,
// TIME=(1),MSGLEVEL=(1,1),MSGCLASS=H,CLASS=A,NOTIFY=&SYSUID
// SET SOMPFX='SOMMVS'
// SET LEPFX='CEE.V2R10M0'
//*------------------------------------------------------------------//* Compile class definition with type checking and IDL generation,
//* and exporting external symbols needed for a SOM DLL, then
//* prelink and link-edit the class to form a DLL.
//*------------------------------------------------------------------//STEP1 EXEC IGYWCPL,REGION=16M,GOPGM=classnm,
//
PARM.COBOL='RENT,PGMN(LM),TYPECHK,IDLGEN,DLL,EXPORTALL',(1)
//
PARM.PLKED='DLLNAME(classnm)',(2)
//
PARM.LKED='RENT,LIST,XREF,LET,MAP'
//COBOL.SYSIN
DD DSN=user.COBOL.SOURCE(classnm),DISP=SHR
//COBOL.SYSIDL
DD DSN=user.COBOL.IDL(classnm),DISP=SHR (3)
//COBOL.STEPLIB DD
//
DD DSN=&LEPFX..SCEERUN,DISP=SHR (4)
//
DD DSN=&SOMPFX..SGOSLOAD,DISP=SHR (5)
//COBOL.SOMENV
DD DSN=user.SOM.PROFILE(myprof),DISP=SHR (6)
//PLKED.SYSIN
DD
//
DD DSN=&SOMPFX..SGOSIMP(GOSSOMK),DISP=SHR (7)
//PLKED.SYSDEFSD DD DSN=&&SIDEDECK,UNIT=SYSDA,DISP=(NEW,PASS),
//
SPACE=(TRK,(1,1)) (8)
//LKED.SYSIN
DD DUMMY
//*------------------------------------------------------------------//* SOM compile the IDL for the class, updating interface repository
//*------------------------------------------------------------------//STEP2 EXEC PGM=SC,REGION=80M,
//
PARM=('-V -usir ''user.COBOL.IDL(classnm)''')
//STEPLIB DD DSN=&LEPFX..SCEERUN,DISP=SHR
//
DD DSN=&SOMPFX..SGOSLOAD,DISP=SHR
//SOMENV
DD DSN=user.SOM.PROFILE(myprof),DISP=SHR (6)
//SYSOUT
DD SYSOUT=*
//*-------------------------------------------------------------------
|
418
Programming Guide
//* Compile the client program with type checking, prelink and link
//* the client program importing the class DLL and the SOM kernel DLL
//*------------------------------------------------------------------//STEP3 EXEC IGYWCPL,REGION=16M,GOPGM=clientnm,
//
PARM.COBOL='RENT,PGMNAME(LM),TYPECHK,DLL', (9)
//
PARM.LKED='RENT,LIST,XREF,LET,MAP'
//COBOL.SYSIN
DD DSN=user.COBOL.SOURCE(clientnm),DISP=SHR
//COBOL.STEPLIB DD
//
DD DSN=&LEPFX..SCEERUN,DISP=SHR (4)
//
DD DSN=&SOMPFX..SGOSLOAD,DISP=SHR (5)
//COBOL.SOMENV DD DSN=user.SOM.PROFILE(myprof),DISP=SHR (6)
//PLKED.SYSIN
DD
//
DD DSN=&&SIDEDECK,DISP=(OLD,DELETE) (10)
//
DD DSN=&SOMPFX..SGOSIMP(GOSSOMK),DISP=SHR
//LKED.SYSIN
DD DUMMY
//*------------------------------------------------------------------//* Execute the client program, accessing the class and SOM from DLLs.
//*------------------------------------------------------------------//STEP4 EXEC PGM=clientnm,REGION=16M
//STEPLIB DD DSN=&&GOSET,DISP=(OLD,DELETE) (11)
//
DD DSN=&LEPFX..SCEERUN,DISP=SHR
//
DD DSN=&SOMPFX..SGOSLOAD,DISP=SHR
//SOMENV DD DSN=user.SOM.PROFILE(myprof),DISP=SHR (6)
//SYSOUT DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
Notes to sample JCL
(1)
Type check the class definition, generate IDL for use in setting up type
checking of the client, enable DLL support, and export the SOM external
symbols needed to make the class a DLL.
(2)
Indicate to the prelinker the name of the DLL that will be created, and that
will appear on generated IMPORT control statements.
(3)
Data set to hold the IDL generated from the compilation of the COBOL
class.
(4)
The Language Environment SCEERUN data set is needed during
compilation of object-oriented COBOL programs (as well as during the
SOM compilation of the IDL file and during the execution of the program).
(5)
The SOMobjects kernel data set SGOSLOAD is needed during compilation
of object-oriented COBOL programs and for SOM compile of IDL.
(6)
The SOM profile data set is needed in each of the job steps. At the
minimum, the profile contains environment variables specifying the
language for SOM messages, the location of #include files referenced in
IDL, and the location of the interface repository files. A sample profile for
this example might be:
[somk]
SMLANG=ENUS
[somc]
SMINCLUDE=//'somhlq.SGOSIDL';//'somhlq.SGOSEFW';//'user.COBOL.IDL';
[somir]
SOMIR=//'somhlq.SGOSIR';//'user.SOM.IR';
|
|
(7)
DLL definition side deck containing IMPORT statements for the SOM kernel
DLL.
(8)
Data set for the prelinker to write the generated DLL definition side deck
containing IMPORT statements for the COBOL class definition DLL.
Chapter 25. System Object Model
419
(9)
Type check the client usage of the COBOL class definition using the
information in the interface repository created in the previous step, and
enable DLL support for the client.
(10)
DLL definition side deck containing IMPORT statements for the COBOL class
DLL (created via item (8) above), indicating to the prelinker that the class
is accessed from the DLL rather than being linked together with the client.
(11)
Include the data sets containing referenced DLL load modules in the
STEPLIB. In this case, the COBOL class DLL is in &&GOSET together with
the client module, and the SOM kernel DLL is in the &SOMPFX..SGOSLOAD
data set.
RELATED TASKS
“Chapter 13. Compiling under OS/390” on page 203
“Populating the SOM Interface Repository” on page 416
SOM services
IBM COBOL implements a subset of the ANSI Object-Oriented COBOL syntax,
based on the SOM object-oriented engine. Not all essential object-oriented
capabilities are implemented in native COBOL syntax. Instead, IBM COBOL uses
SOM application programming interfaces, methods, and functions. For example,
native COBOL syntax is available for class definitions, object-reference data type,
and method invocation. However, you accomplish object creation, destruction,
initialization, and termination by invoking SOM methods provided by the
SOMObject and SOMClass classes. Many other SOM facilities are available to you
either for direct use or for overriding and customizing.
RELATED TASKS
OS/390 SOMobjects Programmer’s Guide
RELATED REFERENCES
“SOM methods and functions”
“Class initialization” on page 421
SOM methods and functions
The following SOM methods and functions are especially important to COBOL
programmers:
somNew A method in SOMClass to create a new object instance of a class. During
creation, somInit is invoked for customized initialization of the object.
somFree
A method in SOMObject to free an object instance releasing the storage
used. Prior to freeing storage, somUninit is invoked for customized
uninitialization.
somFree must not be invoked to destroy an active object, that is, an object
upon which a method has been invoked that has not yet returned control
to the invoker.
somInit
A method in SOMObject that has no default function, but can be overridden
explicitly in a COBOL class definition to perform customized initializations
when an object is created.
somUninit
A method in SOMObject that has no default function, but can be overridden
420
Programming Guide
explicitly in a COBOL class definition to perform customized
uninitialization (typically the inverse of the function performed by a
customized somInit).
somGetClass
A method in SOMObject that returns an object reference to the class object
of an object instance. The class of an object is useful for obtaining
information about the object.
|
|
|
somIsObj
A function that determines whether an object-reference refers to a valid
object.
somIsObj returns a result of type Boolean. Though COBOL has no BOOLEAN
data type, COBOL programmers can declare the return value as PIC X and
test the value using a symbolic character or hex literal.
Data Division.
Working-Storage Section.
01 somBoolean Pic X.
88 invalid-obj Value X'00'.
88 valid-obj
Value X'01'.
Procedure Division.
. . .
Call 'somIsObj' Using by Value anObj Returning somBoolean.
If invalid-obj
Display 'Object reference does not refer to a valid object'
End-if.
. . .
Compiling and linking programs that call SOM functions
When you compile a program that calls a SOM function (such as somIsObj), specify
these compiler options:
|
|
|
v PGMNAME(MIXED), because API names are case sensitive. Otherwise, the compiler
will translate somIsObj to SOMISOBJ, and you will get an unresolved external
reference.
v DLL, because the SOM functions are packaged in dynamic load libraries. You will
get an unresolved reference when you link your program unless you specify this
option.
When you link your program, specify the SOM kernel side deck as input to the
binder. The data set name of the side deck is somhlq.SGOSIMP(GOSSOMK), where
somhlq represents the high-level qualifiers of the data sets where SOM is installed
on your system.
Your invocations of SOM methods do not require any special considerations. The
correct linkage conventions are used automatically for method invocations.
RELATED TASKS
“Chapter 30. Creating a DLL or a DLL application” on page 489
Class initialization
Every SOM class provides an initialization function <classname>NewClass.
Normally COBOL programmers do not use this function directly, but the function
is available in all COBOL classes. The COBOL run-time system automatically
initializes all classes referenced within a COBOL program by calling their class
initialization functions before the first user-written COBOL statement in the
PROCEDURE DIVISION is executed.
Chapter 25. System Object Model
421
The class initialization function has a case-sensitive name. Therefore, you must use
PGMNAME(LONGMIXED) when compiling a COBOL program that explicitly calls a class
initialization function.
If you specify an external class-name in the REPOSITORY paragraph for a class,
COBOL uses this class-name to form the initialization function name. If you do not
specify an external class-name, COBOL uses the class-name to form a
CORBA-compliant external class name for the class initialization function. The
translation to a CORBA-compliant external class-name follows these rules:
v The name becomes uppercase.
v Hyphens in the name become zeros.
v If the first character in the name is a digit, 1 through 9 become A through I and
0 becomes J.
The following example includes an external name for the class:
Identification Division.
Class-Id. Employee inherits SOMObject.
Environment Division.
Configuration Section.
Repository.
Class Employee is “Employee”
Class SOMObject is “SOMObject”.
. . .
End Class Employee.
The class initialization function names in the above cases are:
v EmployeeNewClass
v SOMObjectNewClass
The following example does not include an external name and so the class name is
adapted:
Identification Division.
Class-Id. Employee inherits SOMObject.
Environment Division.
Configuration Section.
Repository.
Class SOMObject is “SOMObject”.
. . .
End Class Employee.
The class initialization function names in the above cases are:
v EMPLOYEENewClass
v SOMObjectNewClass
RELATED CONCEPTS
“SOM services” on page 420
RELATED REFERENCES
“SOM methods and functions” on page 420
Changing SOM class interfaces
One of the benefits of SOM is that classes can change over time and yet retain
backward binary compatibility. You need not recompile programs and classes that
refer to a changed class. You can make the following changes to classes without
having to recompile the clients of the classes:
v Add new methods.
v Change the size of an object by adding or deleting instance data.
422
Programming Guide
v Insert new parent classes above a class in the inheritance hierarchy.
v Relocate methods upward in the class hierarchy.
The SOM engine provides several alternatives for method resolution. IBM COBOL
uses SOM name-lookup resolution to invoke methods. Therefore, when COBOL
code invokes COBOL methods, the somewhat more stringent recompilation
requirements of the SOM offset-resolution mechanism do not apply. For example,
you can relocate a COBOL method anywhere in a class hierarchy without having
to recompile the COBOL programs that invoke the method.
You can invoke methods defined in COBOL classes from other languages (such as
C code built with the SOM C emitter) that use offset resolution. In this case, the
standard SOM requirements apply. COBOL does not provide language comparable
to the SOM “release-order” mechanism, which is used to ensure methods can be
added to a class definition without requiring recompilation of code that invokes
the methods using offset resolution. When you add methods to an existing COBOL
class, add them at the end of the PROCEDURE DIVISION of the class definition, after
existing methods. This placement ensures that any existing client code invoking the
original methods does not require recompilation.
RELATED REFERENCES
Method resolution (OS/390 SOMobjects Programmer’s Guide)
Chapter 25. System Object Model
423
424
Programming Guide
Chapter 26. Using SOM IDL-based class libraries
You can use SOM IDL-based class libraries, either as a client of the library as is, or
by specializing the library classes using subclassing.
There are several forms of Interface Definition Language (IDL), such as those for
the Distributed Computing Environment (DCE) or the Object Management Group’s
Common Object Request Broker Architecture (OMG CORBA). This information
concerns only IBM’s System Object Model Interface Definition Language (SOM
IDL). SOM IDL is consistent with CORBA but allows some additional data types
such as pointers.
You need to understand the System Object Model (SOM), at least conceptually, and
know where to find more detailed documentation about SOM when you need it.
You also need access to the documentation for the class library that you are
intending to use.
To get started, you need one of the object-enabled IBM COBOL products, together
with the executables for the class library and its documentation.
“Example: using a SOM IDL-based class library” on page 440
RELATED CONCEPTS
“SOM objects”
“SOM IDL” on page 426
RELATED TASKS
Understanding Somobjects programming (OS/390 SOMobjects Programmer’s Guide)
“Mapping IDL to COBOL” on page 427
“Handling errors and exceptions” on page 442
“Creating and initializing object instances” on page 445
“Avoiding memory leaks” on page 447
RELATED REFERENCES
“Common IDL types” on page 429
SOM objects
A SOM class library consists of:
v Executable code
v Interface information that defines the operations that the library supports,
including the parameters for invoking the operations (known as the operation
signatures)
When the library is being used at run time, the components that are present in
memory are shown below:
© Copyright IBM Corp. 1991, 2000
425
RELATED TASKS
“Using IDL operations” on page 427
SOM IDL
The interface information for a SOM class library can be in various forms:
v IDL files
v An Interface Repository (IR), a machine-readable form of IDL used during
compilation
v Documentation defining the method interfaces in IDL, and describing the
semantics and rules for using the methods
IDL expresses the contract between the provider of object services (in this case the
class library) and the user of these services (COBOL program, method, or
subclass). The interface description is formally independent of the language in
which either the user of the service or the service itself is implemented. This
property is known as language neutrality. The separation of the interface from the
implementation also allows flexibility in the deployment of the objects on the
nodes of a network.
IDL data types have their origins in the C and C++ data model. Because many of
them do not have an exact counterpart in the COBOL language, there needs to be
a translation (or mapping) between IDL and COBOL. The mapping recommended
here assumes that the data structures can be passed directly between the COBOL
and C/C++ mappings to SOM IDL.
The standard CORBA model presumes a stub routine between the invoking and
invoked object to do argument translation, marshalling, and so on. Passing the
structures directly yields very significant gains in efficiency, but some of the
mappings might not seem as natural to the COBOL programmer as they would if
the transfer were mediated by a stub routine. Passing directly also means that you
must have the correct alignment and padding of structures that are passed across
an interface. In general the recommended way to achieve this for IDL-based
interfaces is to specify the SYNCHRONIZED clause for COBOL mappings to any IDL
structs or arrays that directly contain structs.
RELATED TASKS
“Mapping IDL to COBOL” on page 427
RELATED REFERENCES
“Common IDL types” on page 429
“Complex IDL types” on page 432
426
Programming Guide
Mapping IDL to COBOL
To use an IDL-based class library from COBOL, you must map the elements of IDL
in which the interface to the library is expressed into the COBOL language.
Typically, you find the description of the class library in a user’s guide and
reference, along with guidelines for using the class library and the calling
sequences for each method.
You need to map IDL identifiers, operations, and attributes to their COBOL
counterparts. Some of the IDL types (such as boolean, long, and string) occur very
commonly in interfaces, while complex IDL types (such as array and struct) are
quite rare. You might be able to avoid knowing about the complex IDL types. Refer
to the related references below for each category of IDL types. You do need to
know the conventions for passing arguments and return values.
The only IDL names that must be identical in COBOL are the class (IDL interface)
and method (IDL operation) names. You specify these names exactly with literals:
v For a class, in the CLASS IS clause of the REPOSITORY paragraph.
v For a method, by using the literal form of the method name in the METHOD-ID
paragraph. When you invoke a method, you use either the literal form of the
name or a data name initialized with the exact method name.
The other identifiers, such as parameter, constant, and exception names, are
internal to your program or class, and do not have to be identical to the IDL.
However, it is a good practice to keep these names close to the IDL originals to
enhance the readability and maintainability of your programs.
RELATED TASKS
“Using IDL operations”
“Expressing IDL attributes” on page 428
“Passing COBOL arguments and return values” on page 435
RELATED REFERENCES
“Common IDL types” on page 429
“Complex IDL types” on page 432
Using IDL operations
IDL operations correspond to COBOL methods and represent the services that an
IDL interface provides.
To use an operation, you code an INVOKE statement with the appropriate USING and
RETURNING phrases that correspond to the parameters and the return value of the
operation. If these parameters are simple scalar types, the operation definition is
self-contained. But if an operation uses a “constructed” type, you might need the
definition of the parameter type to specify your INVOKE statement completely.
Consider the IDL operation definition:
void addColor(in color that);
The single input argument is of type color, which is not a basic scalar IDL type.
Suppose that color is an IDL enum (enumerated item) with the following definition
(typically found in a different section of the library documentation):
typedef enum color{red, white, blue};
Chapter 26. Using SOM IDL-based class libraries
427
Then you would write the COBOL code to map the operation, adding the color
blue to an object, as follows:
1 color binary pic 9(9).
88 red value 1.
88 white value 2.
88 blue value 3.
. . .
Set blue to true
Invoke anobject 'addColor' using by value evp color
The evp argument is the environment pointer, which precedes the explicit operation
arguments. It is used for communicating to the caller any exceptions that the
operation encounters.
RELATED TASKS
“Passing COBOL arguments and return values” on page 435
“Handling errors and exceptions” on page 442
RELATED REFERENCES
“Common IDL types” on page 429
Expressing IDL attributes
An IDL attribute behaves like instance data that you can see outside the class
definition (but there need not be any actual instance variable corresponding to it).
SOM models attributes as a pair of operations, one to set and one to get the
attribute value. Attribute operations return errors by means of standard exceptions.
Consider the following IDL specification:
interface foo {
struct position_t {
float x, y;
};
attribute float radius;
readonly attribute position_t position;
};
This is exactly equivalent to the following IDL specification (which is illegal
because IDL identifiers are not permitted to start with an underscore):
interface foo {
struct position_t {
float x, y;
};
float _get_radius();
void _set_radius(in float r);
position_t _get_position();
};
The COBOL code to use these operations is straightforward:
1 radius comp-1.
1 position-t.
2 x comp-1.
2 y comp-1.
. . .
Invoke a-foo '_get_radius' using by value evp returning radius
Invoke a-foo '_set_radius' using by value evp radius
Invoke a-foo '_get_position' using by value evp
returning position-t
428
Programming Guide
RELATED TASKS
“Passing COBOL arguments and return values” on page 435
“Handling errors and exceptions” on page 442
Common IDL types
These are the IDL types that you normally encounter in SOM IDL interfaces.
IDL type
COBOL equivalent
Data item
boolean
DISPLAY PICTURE X
[+ level-88s. . .]
1-byte alphanumeric; level-88 condition names are
recommended
char
DISPLAY PICTURE X
1-byte alphanumeric
double
COMPUTATIONAL-2
64-bit floating point
“enum” on page 430
COMPUTATIONAL-5 PICTURE 9(9)
[+ level-88s]
Unsigned binary fullwords followed by a
condition-name entry for each enumeration
member
float
COMPUTATIONAL-1
32-bit floating point
“interface” on page 430
OBJECT REFERENCE
“long (signed and
unsigned)” on page 430
COMPUTATIONAL-5 PICTURE S9(9)
Unsigned forms of binary data
octet
DISPLAY PICTURE X
8-bit quantity that is guaranteed to be unchanged
during transmission between objects; most closely
matched to a 1-byte alphanumeric data item
pointer
POINTER
“short (signed and
unsigned)” on page 431
COMPUTATIONAL-5 PICTURE S9(4)
“string” on page 431
DISPLAY PIC X(n+1), Z’value’ or
variable-length alphanumeric
table
void
Omit the RETURNING phrase in the
corresponding INVOKE statements
or PROCEDURE DIVISION headers
Unsigned forms of binary data
“Examples: common IDL types”
Examples: common IDL types
The following table shows examples of the common IDL types and the COBOL
equivalent.
|
IDL type
IDL example
COBOL equivalent
boolean
boolean that;
1 that display pic x.
88 that-false value x'00'.
88 that-true value x'01' thru x'ff'.
char
char that;
1 that display pic x.
double
double that;
1 that comp-2.
enum
enum that
{red, white,
blue, green};
1 that comp-5 pic 9(9).
88 that-red value 1.
88 that-white value 2.
88 that-blue value 3.
88 that-green value 4.
float
float that;
1 that comp-1.
Chapter 26. Using SOM IDL-based class libraries
429
IDL type
IDL example
COBOL equivalent
interface
interface that
{. . .}
Repository.
class that 'that'.
. . .
1 a-that object reference that.
(You pass the instance of the class according to the rules for
passing arguments.)
long
long that;
1 that comp-5 pic s9(9).
octet
octet that;
1 that displays pic x.
pointer
pointer that;
1 that pointer.
short
short that;
1 that comp-5 pic s9(4).
|
|
string (bounded)
string<100> that;
1 that-l-max comp-5 pic 9(9) value 101.
1 that-l comp-5 pic 9(9).
1 that.
2 that-v pic x occurs 1 to 101 depending that-l.
|
|
string (unbounded)
string that;
1 that-l-max comp-5 pic 9(9) value 4096.
1 that-l comp-5 pic 9(9).
1 that.
2 that-v pic x occurs 1 to 4096 depending that-l.
unsigned long
unsigned long that;
1 that comp-5 pic 9(9).
unsigned short
unsigned short that;
1 that comp-5 pic 9(4).
enum
The closest COBOL equivalent to a SOM IDL enum is an unsigned binary fullword,
together with condition-name entries for each of the enumeration members.
A SOM IDL enum is different from a C/C++ enum:
1. It is always exactly 4 bytes long, whereas a C/C++ enum is 1, 2, or 4 bytes long,
depending on the maximum enum value and on compiler options.
2. The members are numbered sequentially starting from one, whereas a C/C++
enum starts at zero by default, or can optionally have specific values assigned to
the enumeration members.
The way that you refer to a particular enum value in your PROCEDURE DIVISION
depends on whether the value is supplied to an operation or returned by it.
RELATED TASKS
“Passing enumerated arguments” on page 437
interface
The use of an IDL interface as an argument to, or result of, an operation denotes
an object reference to an instance of the class to which the interface has been
mapped. Therefore, if a method has an interface type as one of its parameters,
specify an OBJECT REFERENCE to an instance of a class that supports that interface.
long (signed and unsigned)
The SOM IDL long type describes 32-bit signed binary quantities, and is mapped
by a USAGE COMPUTATIONAL-5 data item with a PICTURE clause of (S9(5) through)
S9(9).
430
Programming Guide
The unsigned form of binary data is mapped as for the SOM IDL long type, except
that the PICTURE clause does not specify the character S. If you map this IDL type
to USAGE BINARY, you must either know that the PICTURE clause accommodates the
expected range of values, or use the TRUNC(BIN) compiler option and (on the
workstation) ensure that the BINARY(NATIVE) compiler option is in effect.
|
|
|
Also be aware that there are significant performance effects associated with the use
of COMP-5 data items or the TRUNC(BIN) compiler option (primarily, though, for
doubleword binary data items, that is for items declared USAGE BINARY with a
PICTURE clause containing 10 or more 9s).
short (signed and unsigned)
The SOM IDL short type defines 16-bit signed binary data, and is mapped by a
USAGE COMPUTATIONAL-5 data item with a PICTURE clause of (S9(1) through) S9(4).
The unsigned form of binary data is mapped as for the SOM IDL short type,
except that the PICTURE clause does not specify the character S.
string
The SOM IDL type string is one of the most important types, because it is widely
used in operations and interfaces. It is also one of the most difficult to match in
COBOL, because SOM IDL strings are modeled on those of C and C++. These have
a null terminator to determine the length of the string, and are passed by a typed
pointer. IBM COBOL does not support such null-terminated strings as a native
data type. However, the null-terminated literal Z’string-value’ alleviates some of
the problems and, when it can be passed BY CONTENT, is an exact match to a SOM
IDL in string. (For inout and out strings, you must pass a pointer to the string
data or buffer BY REFERENCE.) You can also use a null-terminated literal to set the
initial VALUE of a data item to be used as a string argument.
In general, IDL strings are mapped to pointers to the appropriate character string
data or buffer. With the exception of in strings, however, just the pointer is actually
passed in a method invocation. But, for this to work operationally, the pointer
must be set to the address of the underlying character string data or buffer in
PICTURE X format. There are several styles of data definition, depending on
whether the parameter is an in, inout, or out argument, or a return value. The
declarations described below can be used to represent both the COBOL and SOM
IDL view of a variable-length string simultaneously.
The main cases to distinguish are bounded and unbounded strings. Bounded
strings have a fixed upper limit on their size. The following IDL declaration
represents a SOM IDL string of no more than 100 characters in length:
string<100> that;
This IDL declaration can be approximated by the following COBOL data
declarations:
1 that-l-max binary pic 9(9) value 101.
1 that-l binary pic 9(9).
1 that.
2 that-v pic x occurs 1 to 101 depending that-l.
The -l suffix denotes the length of the string, the -v its value. The extra position
allows for the null terminator. The data item that, in addition to being a valid
SOM IDL string, is also variable length in COBOL, because of the OCCURS
DEPENDING clause.
Chapter 26. Using SOM IDL-based class libraries
431
For unbounded strings, the maximum length must be inferred from ancillary
information about the interface and the semantics of its operations. The following
IDL declaration represents an unbounded SOM IDL string:
string that;
You might, for example, know that the strings that are passed across the interface
do not in practice exceed 4095 characters. Then the following COBOL declarations
would be appropriate:
1 that-l-max binary pic 9(9) value 4096.
1 that-l binary pic 9(9).
1 that.
2 that-v pic x occurs 1 to 4096 depending that-l.
You can use a pair of helper routines (see the related references below) to
synchronize the two representations, for example, either the bounded or
unbounded that, above:
’IDLStringToCOBOL’ using that that-l
This routine sets the COBOL OCCURS object that-l from the position of the
mandatory null terminator.
If you prefer, you can achieve the same result in COBOL:
Move that-l-max to that-l
Move zero to tally
Inspect that tallying tally for characters before x'00'
Move tally to that-l
’IDLStringFromCOBOL’ using that that-l
This routine inserts the null terminator at the string position indicated by
the COBOL OCCURS object.
If you prefer, you can do this quite easily yourself in COBOL:
Move x'00' to that-v(that-l)
RELATED TASKS
“Passing string arguments” on page 437
RELATED REFERENCES
“Source code for helper routines” on page 450
Complex IDL types
Although defined in SOM IDL, complex IDL types are rarely found as a type
definition or as an argument to or result of an operation.
IDL type
COBOL equivalent
“any”
Group + COBOL type
“array” on page 433
Table
“sequence” on page 433
Group + variable-length table
“struct” on page 434
Group
“union” on page 434
Group + redefinitions
any
The IDL any type is a self-describing representation of any of the IDL types,
including another IDL any. The descriptor is mapped to COBOL as a group item,
which includes a pointer to the actual data item of the particular type. Suppose
you want to map the following IDL declaration:
432
Programming Guide
any that;
In COBOL, this declaration is represented by the following group item:
1 that.
2 that-type pointer.
2 that-value pointer.
The that-type field is a pointer to a TypeCode structure whose actual
representation is opaque. SOM provides a set of functions to create and interrogate
TypeCodes. A simple numeric type code is insufficient to describe an IDL type,
because some types have additional information. For example, the type
information for an IDL bounded string includes the size of the upper bound.
The that-value field points to the start of the data for the item that the any
represents.
array
IDL arrays map to COBOL tables—groups whose subordinate items contain the
OCCURS clause. The underlying IDL type can be any of the IDL types, including
array itself, and is mapped according to the rules for the individual IDL type.
A simple instance of the IDL array type is:
long that[4][5];
This array is represented in COBOL as:
1 that.
2 occurs 4.
3 that-v binary pic s9(9) occurs 5.
The -v suffix denotes the individual element values. The unsuffixed name is used
to pass the entire array as an argument to a method; the suffixed name is used to
refer to individual elements of the array.
If any level of the array contains a struct or union, then you must specify the
SYNCHRONIZED clause on the group item. This is to ensure that the subordinate items
are aligned on their natural boundaries, in conformance with the default alignment
of SOM IDL structures.
sequence
An IDL sequence is a one-dimensional array with a descriptor that specifies a
maximum and current size for the sequence. If the maximum size is explicitly
declared, the sequence is said to be bounded. Otherwise, the sequence is unbounded,
and the maximum size is determined at run time (in an application-specific way)
and is set prior to passing the sequence to an operation.
There are no restrictions on the element type of a sequence. It is possible to have a
sequence of another sequence type.
Here is a simple example, a bounded sequence of IDL type long:
sequence<long,10> that;
The descriptor for the maximum and current size and address of this sequence is
represented in COBOL as a group item:
1 that.
2 that-maximum binary pic 9(9).
2 that-length binary pic 9(9).
2 that-buffer pointer.
Chapter 26. Using SOM IDL-based class libraries
433
Then the element data is mapped as a variable-length table of the appropriate
type, in this case, an array of IDL longs:
1 that-t.
2 that-v comp-5 pic s9(9) occurs 1 to 10
depending that-length.
|
struct
An IDL struct type corresponds to a COBOL group item containing the
individually mapped components of the struct as subordinate data items.
Consider the following IDL struct:
struct that {
long x;
double y;
};
The struct could be represented in COBOL as:
1 that sync.
2 x binary pic s9(9).
2 y comp-2.
The SYNCHRONIZED clause is required so that the alignment of the subordinate items
approximates the default alignment of SOM IDL structures. In most practical cases,
the alignment would be correct either way, but specifying SYNCHRONIZED is a
sensible precaution.
union
A SOM IDL union has a discriminator that indicates which format variant to use.
In COBOL, this type is mapped to a group item containing the discriminator, plus
the union itself represented by using the REDEFINES clause. Then, in the procedure
division, use an EVALUATE statement to determine which format is currently in
effect.
Suppose you have the following IDL:
union that switch (long) {
case 2:char x;
case 5:long y;
default:float z;
};
The data declaration part of the COBOL mapping could be written as follows:
1 that sync.
2 that-d binary pic s9(9).
2 that-u display pic x(4).
2 that-x redefines that-u display pic x.
2 that-y redefines that-u binary pic s9(9).
2 that-z redefines that-u comp-1.
The SYNCHRONIZED clause makes sure that COBOL mimics the default SOM IDL
alignment rules. Thus, in the unlikely event that any IDL structures have “holes,”
COBOL would insert slack bytes in the record as appropriate.
The size of the extra member of the union, that-u, is the maximum of the sizes of
the explicit union members. This extra data item is needed because of the COBOL
restriction that a data item being redefined must be at least as large as the item
redefining it. Alternatively, you could declare the union members in order of
decreasing size, but that might lose the correspondence between the COBOL
declaration and the original IDL.
434
Programming Guide
Whichever style you adopt, you can use an EVALUATE construct such as the
following to determine which of the union members is in effect:
Evaluate that-d
When 2
Display 'case 2:IDL-char: ' that-x
When 5
Display 'case 5:IDL-long: ' that-y
When other
Display 'default case:IDL-float: ' that-z
End-evaluate
Passing COBOL arguments and return values
The way you write COBOL argument-passing constructs (such as BY REFERENCE or
BY VALUE) must comply with the IDL access intent specifiers in, inout, and out.
These specifiers do not correspond exactly to COBOL BY VALUE, BY CONTENT, and BY
REFERENCE phrases. The IDL access intent determines only the semantics of the
parameter, without necessarily implying a particular mechanism for passing
arguments. In COBOL, both BY VALUE and BY CONTENT have input-only semantics
but use different mechanisms, whereas BY REFERENCE parameters could have either
input-output or output-only semantics, depending on how they are used. Some
kinds of output parameters (IDL strings, for example) cannot be expressed
directly in COBOL, but must be mapped to pointers.
Passing literal arguments
For return values and for inout and out arguments, you must pass a data item.
For input arguments however, you might be able to specify a literal, passed BY
VALUE:
v Integer-valued fixed-point numeric literals and the figurative constant ZERO are
formally equivalent to fullword binary data items, and thus match signed or
unsigned long IDL types.
v Floating-point literals are formally equivalent to doubleword floating-point
(COMPUTATIONAL-2) data items, and thus match the IDL double type.
v Single-byte alphanumeric literals, symbolic characters, and figurative constants
other than ZERO match boolean, char, and octet.
You can specify null-terminated literals of the form Z’value’ (which match the IDL
string type), passed BY CONTENT.
Literal arguments are not supported for the enum type because of the risk of the
source getting out of sync with the enumeration list.
Passing arguments of complex types
For the complex types, not including string, you pass the level-1 group item. In
the examples above, this is always the COBOL data name that. Where the
conventions expect a pointer, this is set:
v For an argument, prior to executing the INVOKE statement
v For a return value, on return from the method
The rules for passing these types are quite involved. Generally, you provide the
storage for all in and inout arguments, all modes of struct and union parameters,
and, curiously enough, for out array arguments. The called method allocates some
or all of the storage for all other out arguments and return values. You are not
allowed to modify this returned storage, though you can of course use it otherwise
(to copy it, for example). You must free it using OMMFree when you have finished
with it.
Chapter 26. Using SOM IDL-based class libraries
435
If you have to supply inout arguments of any of the complex types, you would do
well to allocate the storage dynamically using OMMAllocate, and declare the
COBOL equivalent type in the LINKAGE SECTION. This recommendation is because
later versions of CORBA allow the called routine to reallocate inout arguments
when the output value is inconsistent with the type or size of the input data item.
For this reallocation to work, both the caller and the called routine must use a
standard memory management protocol.
RELATED TASKS
“Passing enumerated arguments” on page 437
“Passing string arguments” on page 437
RELATED REFERENCES
“Conventions for passing arguments and return values”
“Source code for helper routines” on page 450
OS/390 SOMobjects Programmer’s Guide (rules for passing arguments of complex
types)
Conventions for passing arguments and return values
IDL type
436
Programming Guide
in
inout/out
Return value
any
content
reference
type3
array
content1
reference1
pointer4
boolean
value
reference1
type3
char
value
reference1
type3
double
value
reference1
type3
enum
value
reference1
type3
float
value
reference1
type3
long
value
reference1
type3
object ref
value
reference1
type3
octet
value
reference1
type3
pointer
value
reference1
type3
short
value
reference1
type3
sequence
content1
reference1
type3
string
content1
pointer2
pointer4
struct
content1
reference1
type3
union
content1
reference1
type3
unsigned long
value
reference1
type3
unsigned short
value
reference1
type3
1
1
IDL type
in
inout/out
Return value
1. For IBM COBOL for OS/390 & VM you can use BY CONTENT or BY REFERENCE only if the
argument is not the last. This limitation is due to the System/390 linkage conventions
of the high-order bit of the last argument address being set on to indicate the end of
the argument list. This convention confuses C and C++ programs that attempt to
manipulate the address as a pointer. An alternative to BY REFERENCE (for this situation
and in general) is to pass BY VALUE a pointer that has previously been set to the address
of the data item.
2. For inout and out strings, you must pass a pointer to the string data or buffer BY
REFERENCE.
3. The term type here means the COBOL equivalent of the IDL type, specified directly in
the RETURNING phrase of the INVOKE statement.
4. The term pointer here means a COBOL POINTER that has been set to the address of the
equivalent data item or output buffer.
Passing enumerated arguments
The access intent of an enum parameter affects the way you refer to its value, not
just on the INVOKE statement, but also elsewhere in your program. Consider an
operation that expects an enum to be passed in both directions, as an input value
and as the operation result:
that changeColor(in that hue);
typedef enum that{red, white, blue};
To supply a particular color to the operation, you use the corresponding
condition-name in a SET statement. For example, to pass the input value white,
specify:
1 that-input binary pic 9(9).
88 that-red-input value 1.
88 that-white-input value 2.
88 that-blue-input value 3.
. . .
Set that-white-input to true
Invoke anObject 'changeColor' using by value evp that-input
returning that-output
Then, to inspect the returned color, use conditional statements:
1 that-output binary pic 9(9).
88 that-red-output value 1.
88 that-white-output value 2.
88 that-blue-output value 3.
. . .
Evaluate true
When that-red-output
Perform red-stuff
. . .
End-evaluate
Passing string arguments
The examples in this section all presume this SOM IDL declaration:
string<100> that;
For in string types: You pass in string types in several ways. Where you know
the content, you can specify it as a null-terminated literal, either directly or as the
value of a data item:
1 that pic x(101) value z'initial value'.
. . .
Invoke anObject 'method'
Chapter 26. Using SOM IDL-based class libraries
437
using by value evp by content z'this or that'
. . .
Invoke anObject 'method' using by value evp by content that
For variable-content strings, you might find it convenient to use a plain (PICTURE
X) alphanumeric data declaration for the string buffer. You can use reference
modification if you want to see the valid part of the string:
1 that-l binary pic 9(9).
1 that pic x(101).
. . .
Display 'Content of “that” = “' that(1:that-l) '”'
However, if you want the string to behave naturally as a variable-length string in
both COBOL and the SOM IDL-based library, use the dual representations:
1 that-l binary pic 9(9).
1 that.
2 that-v pic x occurs 1 to 101 depending that-l.
You can synchronize either the reference-modified or the OCCURS DEPENDING form of
the COBOL string representation with the IDL representation by using the
IDLStringToCOBOL and IDLStringFromCOBOL helper routines.
For inout and out strings: You must pass the string buffer with an extra level of
indirection. The way that you express the extra level of indirection in COBOL is to
pass a pointer that for inout strings has previously been set to the address of the
string data. As usual, you have a choice of passing this pointer BY REFERENCE, or
declaring a second pointer that you have set to the address of the first and passing
this second pointer BY VALUE:
1 ptr1 pointer.
1 ptr2 pointer.
1 that-l binary pic 9(9).
. . .
Linkage section.
1 that.
2 that-v pic x occurs 1 to 101 depending that-l.
. . .
Set ptr1 to address of that
Invoke anObject 'method' using by value evp by reference ptr1 . . .
. . .
Set ptr2 to address of ptr1
Invoke anObject 'method' using by value evp ptr2
The extra level of indirection is needed for out strings, because they are allocated
by the method and can be arbitrarily long. But the output size of an inout string is
limited by the input size: the upper bound for a bounded string; or the actual
input size for an unbounded string.
For a return value: Specify a pointer, which the method sets to the address of the
output string before it returns.
For all the output modes of string, including inout: Declare the string buffer
itself in the LINKAGE SECTION to allow the method to allocate, or reallocate, the
storage for the string. You should acquire storage for an inout string calling
OMMAllocate, so that (in future) methods can resize the string if necessary.
You can look at the storage by declaring appropriate LINKAGE SECTION data items
as usual, but do not attempt to modify it. The storage might be protected, and you
cannot assume that you have appropriate write privileges. Instead, make a copy
438
Programming Guide
and modify the copy. Also, you are responsible for freeing the storage for the
original returned string when you have finished with it, by calling the OMMFree
routine.
“Example: passing string arguments”
“Example: using a SOM IDL-based class library” on page 440
RELATED REFERENCES
“Source code for helper routines” on page 450
Example: passing string arguments
This example assumes the following IDL definition:
interface this {
string that (
in string in_string,
inout string inout_string,
out string out_string
);
};
Assuming an arbitrary limit of 99 characters on the string sizes, the following
COBOL fragments illustrate the techniques for passing strings. This code is written
in a very simple style, does not check for errors, and might not be complete.
Data division.
LOCAL-/WORKING-STORAGE section.
1 inout-string-p pointer.
1 out-string-p pointer.
1 return-string-p pointer.
. . .
1 work-string-l binary pic 9(9).
1 inout-string-l binary pic 9(9).
1 out-string-l binary pic 9(9).
1 return-string-l binary pic 9(9).
. . .
1 work-string pic x(100).
1 in-string pic(100) value z'Nothing strange for in strings'.
1 evp pointer.
. . .
Linkage section.
1 inout-string.
2 inout-string-v pic x occurs 1 to 100 depending inout-string-l.
1 out-string.
2 out-string-v pic x occurs 1 to 100 depending out-string-l.
1 return-string.
2 return-string-v pic x occurs 1 to 100 depending return-string-l.
1 ev.
2 major binary pic 9(9).
88 no-exception value 0.
. . .
Procedure division.
. . .
* Acquire storage for, and initialize, inout-string:
Move 100 to inout-string-l
Call 'OMMAllocate' using content length of inout-string
returning inout-string-p
Set address of inout-string to inout-string-p
Move z'Initial value for inout-string' to inout-string
Call 'IDLStringToCOBOL' using inout-string inout-string-l
* Invoke method 'that' on an instance of the 'this' class:
Invoke a-this 'that' using by value evp
by reference in-string inout-string-p out-string-p
returning return-string-p
* De-reference the returned pointers and copy one string:
Set address of inout-string to inout-string-p
Chapter 26. Using SOM IDL-based class libraries
439
Call 'IDLStringToCOBOL' using inout-string inout-string-l
Set address of out-string to out-string-p
Call 'IDLStringToCOBOL' using out-string out-string-l
Set address of return-string to return-string-p
Call 'IDLStringToCOBOL' using return-string return-string-l
Move out-string to work-string
* Operate on copy, and free allocated storage when done:
Move function reverse(work-string) to work-string
If work-string = out-string then
Display '“' out-string '” is palindromic.'
End-if
. . .
Call 'OMMFree' using inout-string-p
Call 'OMMFree' using out-string-p
Call 'OMMFree' using return-string-p
. . .
Example: using a SOM IDL-based class library
This example shows the COBOL coding to use a very simple class library.
Let us begin by looking at the documentation for our class library, which provides
a bucket class. A bucket is a container that lets you add or remove objects, and
that can report the number of objects it contains. Buckets have no special initializer
methods, and can thus be created and initialized correctly just by invoking the
somNew method on the class. Normally, the documentation would define and
describe each operation separately, but for this simple example, we will give the
complete interface definition of a bucket:
interface Bucket {
readonly attribute unsigned long count;
void add(in SOMObject element) raises(BucketFull);
SOMObject remove() raises(BucketEmpty);
};
The raises clause specifies the exceptions that the operation can incur.
The things that we put into our buckets have no external behavior beyond their
existence. That is, they can be created and destroyed, and are identifiable by their
object references, but they have no methods or attributes.
The COBOL program in this example shows how you might use this class library.
The COBOL coding is very simplistic. For example, it does not check for errors
realistically or free all the objects that it creates. But it does cover most of the
things that you have to do to start using a class library. It performs the following
steps:
1. Create an instance of a bucket.
2. Create and add some things to the bucket.
3. Print the number of things in the bucket.
4. Remove a thing from the bucket.
5. Print the number of things in the bucket.
(1)
440
Programming Guide
Process pgmname(longmixed),dll
******************************************************************
* Client program for Bucket.
*
******************************************************************
Identification division.
Program-id. 'TryBucket'.
Environment division.
Configuration section.
Repository.
class thing 'Thing'
(2)
(3)
(4)
(5)
(6)
(7)
(8)
(9)
(10)
class bucket 'Bucket'
class somobject 'SOMobject'.
Data division.
Working-Storage section.
1 evp pointer.
1 abucket object reference bucket.
1 athing object reference thing.
1 asomobject redefines athing object reference somobject.
1 cntnts binary pic 9(9).
Linkage section.
1 ev.
2 major binary pic 9(9).
88 no-exception value 0.
88 any-exception value 1 thru 999999999.
Procedure division.
display 'Trying Bucket. . .'
call 'somGetGlobalEnvironment' returning evp
set address of ev to evp
invoke bucket 'somNew' returning abucket
perform 5 times
invoke thing 'somNew' returning athing
invoke abucket 'add' using by value evp athing
perform chkxcp
end-perform
invoke abucket '_get_count' using by value evp returning cntnts
perform chkxcp
display 'Our bucket now has ' cntnts ' things in it.'
invoke abucket 'remove' using by value evp returning asomobject
perform chkxcp
invoke abucket '_get_count' using by value evp returning cntnts
perform chkxcp
display 'We took one out, so now it has only ' cntnts
' things in it.'
invoke abucket 'somFree'
display 'Done with Bucket.'
stop run.
chkxcp.
if any-exception
display 'An exception occurred; quitting the program!'
stop run
end-if.
End program 'TryBucket'.
Notes:
(1)
Regardless of what you call your program, you need to specify the
PGMNAME(LONGMIXED) and the DLL compiler options to be able to call SOM
APIs such as somGetGlobalEnvironment. The options do not affect INVOKE
statements, but they do apply to program names in CALL statements.
(2), (3), and (4)
If not stated otherwise, SOM IDL class libraries use callstyle idl. With this
convention, every operation has an implicit environment pointer preceding
the explicit IDL arguments for the operation. Although this argument is
implicit in the IDL, you code it explicitly on your INVOKE statements.
You must, at a minimum, define the environment pointer in the
WORKING-STORAGE or LOCAL-STORAGE SECTION. If you want to examine any
exceptions that are returned, you must also define the exception type in the
Chapter 26. Using SOM IDL-based class libraries
441
LINKAGE SECTION, and set its base address to the value returned by
somGetGlobalEnvironment. In the example, the exception type field is
named major.
(5)
The somNew method creates an instance of the bucket class, and returns an
object reference to the instance. Notice that this method does not take an
environment pointer as its first argument.
(6)
Each time through the loop, a new thing is returned in the same variable.
This is acceptable for the example, but normally it would be very bad
practice to lose addressability to one’s objects. Among other reasons, the
storage they use remains allocated and, without the object reference,
cannot be freed.
(7)
For the methods that correspond to the IDL operations, the environment
pointer is included as the first argument, evp, in the argument list. It’s
important to check for exceptions after invoking these methods. The
ensuing PERFORM statement shows one way to do that.
(8)
This statement shows how attributes are mapped to get and set methods.
In this case, the attribute is read-only, so only the get method is defined.
(9)
A problem peculiar to container classes is that they must allow arbitrary
types for the elements that they contain. Thus the return type of the remove
operation is specified as a SOMObject. We want to use the returned element
with its proper description, to assure type safety. But coding a thing as the
RETURNING value on the INVOKE statement would be a type violation. So the
returned value, asomobject, is specified as a redefinition of athing. This
redefinition allows the INVOKE statement to match the signature of the IDL
operation. By using the redefined variable, athing, for subsequent
operations on the object, we can ensure that these operations are type safe.
(10)
This statement reminds us that all object instances that the program creates
should be freed to avoid memory leaks. However, in this example none of
the things in the bucket are freed.
Handling errors and exceptions
SOM uses two error or exception mechanisms: SOMError and CORBA-style
exceptions.
SOMError is used for internal errors in the kernel classes, and is not relevant to the
average user. Methods of the kernel classes create an object (somNew and
somNewNoInit) or destroy it (somFree). The main implication of SOMError for these
methods is that you do not need to provide an environment argument when you
invoke them, and you do not need to check for exceptions after they return.
However you do need to know how to use the SOM exception mechanism, which
is used for most other methods. Exceptions are not necessarily errors, but errors do
use the SOM exception mechanism.
SOM exceptions are not the same as C++ exceptions, but instead set the value of
an exception structure, which you can think of as a special kind of return code,
accessed through the environment variable.
442
Programming Guide
Passing environment variables
There are two ways of passing the environment variable, depending on the call
style of the method you want to invoke, and check. For each of them, provide a
global (per thread) environment variable:
v For callstyle oidl methods, there is no explicit environment variable parameter.
Such methods use the global environment variable implicitly.
v Callstyle idl methods use the same global environment variable, but pass it
explicitly, as the first argument to the method.
The environment variable is opaque, except for the exception type field (major) at
the beginning of the structure. This is a 4-byte C/C++ enum, origin zero, with three
values: NO_EXCEPTION, USER_EXCEPTION, and SYSTEM_EXCEPTION. It is coded in
COBOL as BINARY PIC 9(9), with suitable level-88 condition-names.
Checking the exception type field
Every callstyle idl operation (that is, a method whose first parameter is an
environment structure) can return one of the standard system exceptions. A
callstyle idl operation can return a standard system exception even if it does not
declare any explicit exceptions with a raises expression in the operation
declaration. Therefore you must check the exception type field of the environment
variable after every invocation of a method of a class defined with callstyle idl. Do
not assume that a method completed successfully. You will not get a reliable
implementation of your application unless you do check.
Handling exceptions
When a callstyle idl method that you have invoked detects a condition that is to
be expressed as an exception, it uses the somSetException function to supply the
exception name and an exception structure.
If you decide to handle the exception, perhaps by printing a message and
continuing, you must reset the environment variable and free the associated
exception structure by using the somExceptionFree function. Of course, there are
other ways to handle exceptions. You might change the state of one of the input
arguments to the method and retry it, or you might terminate your program rather
than attempt to continue.
“Example: checking SOM exceptions”
RELATED REFERENCES
CORBA standard exceptions (OS/390 SOMobjects Programmer’s Guide)
Example: checking SOM exceptions
The program fragments in this example show in some detail how you can handle
SOM exceptions in IBM COBOL. The data names are only suggestions and are not
mandatory.
In the WORKING-STORAGE or LOCAL-STORAGE section:
******************************************************************
* Declare the environment variable pointer:
*
******************************************************************
1 evp pointer.
In the LINKAGE SECTION:
Chapter 26. Using SOM IDL-based class libraries
443
******************************************************************
* Declare the environment variable itself:
*
******************************************************************
1 ev.
2 major binary pic 9(9).
88 no-exception value 0.
88 any-exception value 1 thru 999999999.
88 user-exception value 1.
88 system-exception value 2.
In the PROCEDURE DIVISION:
******************************************************************
* Acquire a global environment variable
*
******************************************************************
Call 'somGetGlobalEnvironment' returning evp
Set address of ev to evp
. . .
******************************************************************
* Check environment after invoking a method
*
******************************************************************
Invoke anObject 'op1' using by value evp other-args . . .
If any-exception then
*
respond to exception appropriately, perhaps by using:
Call 'Print-ev' using evp by content z'op1 on anObject'
End-if
. . .
Here is a sample subroutine for printing exceptions:
******************************************************************
* Subroutine for printing exceptions
*
******************************************************************
Identification division.
Program-id.
'Print-ev'.
Data division.
WORKING-STORAGE section.
1 counter binary pic 9(9) value 0.
Local-storage section.
1 d pic x(130).
1 eip pointer.
1 i binary pic 9(9).
1 p binary pic 9(9).
1 s pic 9(9).
Linkage section.
1 evp pointer.
1 kind pic x(40).
1 ev global.
2 major binary pic 9(9).
88 user-exception value 1.
88 system-exception value 2.
1 ei pic x(100).
Procedure division using evp kind.
Add 1 to counter
Set address of ev to evp
Call 'SLZ' using counter s i
Move 1 to p
String 'Check #' s(i : ) ': method invocation “'
delimited size into d pointer p
Move 0 to i
Inspect kind tallying i for characters before initial x'00'
String kind(1 : i) '” returned '
delimited size into d pointer p
Evaluate true
When user-exception
String 'a user' delimited size into d pointer p
When system-exception
444
Programming Guide
String 'a system' delimited size into d pointer p
When other
String 'an unknown' delimited size into d pointer p
End-evaluate
Call 'SLZ' using major s i
String ' exception (major = ' s(i : ) ')'
delimited size into d pointer p
Display d(1 : p - 1)
Call 'somExceptionId' using by value evp returning eip
Set address of ei to eip
Move 0 to i
Inspect ei tallying i for characters before initial x'00'
Display ' Exception ID: <' ei(1 : i) '>'
Call 'somExceptionFree' using by value evp
Goback
. . .
End program 'Print-ev'.
******************************************************************
* Subroutine to strip leading zeroes
*
******************************************************************
Identification division.
Program-id.
'SLZ'.
Data division.
Linkage section.
1 uint binary pic 9(9).
1 str pic x(9).
1 pos binary pic 9(9).
Procedure division using uint str pos.
Move uint to str
Move 0 to pos
Inspect str(1 : length str - 1)
tallying pos for leading '0'
Add 1 to pos
Goback
. . .
End program 'SLZ'.
Creating and initializing object instances
IBM COBOL directly supports the existing somInit and somUninit protocols. For
classes that use somInit (these include all pure COBOL classes), the somNew method
both creates and initializes an object instance. This technique is appropriate when
all instances have the same initial value or do not have an explicit initial value. If,
however, you want each instance to have a unique initial value, you might prefer
to use a metaclass.
You can execute the nondefault initializer methods (as a client) of a class by
invoking first somNewNoInit and then the appropriate initializer method. This is the
recommended way to create an instance of one of the SOM-enabled collections, for
example.
You do need to specify the somInitCtrl structure that is used to control the
progress of the initializer as it traverses the class hierarchy. For a client of a class
initializer method (as opposed to a subclass that provides its own initializer
methods), this structure is initially null, represented in COBOL as an OMITTED
argument. Suppose that the IDL for the initialization method is:
void ISHeap_withNumber(inout somInitCtrl ctrl, in long number);
COBOL code for invoking this initializer might be:
Chapter 26. Using SOM IDL-based class libraries
445
1 a-heap object reference isheap.
. . .
Invoke isheap 'somNewNoInit' returning a-heap
Invoke a-heap 'ISHeap_withNumber'
using by value evp by reference omitted by value 10000
For COBOL subclasses of classes that use explicit initializers, use metaclass
methods to instantiate and initialize the COBOL object. After creating the instance,
the metaclass method invokes the initializer for each parent (with multiple
inheritance, there could be several). It then initializes any instance data that the
subclass introduced. You could create and initialize these objects directly in the
client code. However, encapsulating the logic in a metaclass method is more
reliable and convenient, especially when the subclass inherits from multiple
parents.
Using a metaclass method is also a good way to create and initialize your own
pure COBOL objects in a single step, particularly where each object has a unique
initial value.
Looking at the IDL file
Generally, the documentation for a class library has all the information you need to
use (as a client) or specialize (subclass) the classes. In particular, you would expect
to find the following information:
v Interfaces (types and operations or methods) expressed in IDL
v Semantics of the operations including the required data types and conventions
for passing arguments
v Descriptions of the rules for using the library such as which objects must be
instantiated and in what order; what methods must be invoked to initialize the
classes; and what the relation is between the classes
Sometimes, you might need more detailed information about a class library, as
when you specialize the library by subclassing. To get this additional information,
you might need to look at the IDL or header files. It is helpful to know their
structure: what is relevant and what you can ignore. Typically, the IDL file consists
of some IDL definitions, guarded so that they are processed only once per IDL
compilation, plus some implementation-specific information, also guarded so that
it is conditionally included.
Consider the sample IDL file spred from the collection class library.
#ifndef _ISPRED_IDL (1)
#define _ISPRED_IDL
#include <somobj.idl> (2)
interface ISPredicate : SOMObject { (3)
boolean evaluateFor (in SOMObject element); (4)
#ifdef __SOMIDL__ (5)
implementation {
releaseorder: evaluateFor;
somDefaultInit: override,init;
somDestruct:
override;
callstyle
majorversion
minorversion
446
Programming Guide
= idl;
= 1;
= 0;
filestem
= spred;
dllname
= “sccl.dll”;
functionprefix = sISPredicate_;
#ifdef __PRIVATE__ (6)
passthru C_xh_before = “#include <ssglobal.xih>”;
#endif
};
#endif
};
#endif
(1)
One of three conditional sections in the file; its purpose is to ensure that
the IDL definitions in the file are processed no more than once during the
IDL compilation. The matching #endif statement is at the end of the file.
(2)
The #include statement incorporates another IDL file that you might have
to refer to.
(3)
The compound statement specifies the IDL element that this file defines,
the ISPredicate interface.
(4)
This definition is for the (single) new operation evaluateFor that
ISPredicate introduces.
(5)
The start of some SOM-specific implementation information, which needn’t
concern you; its matching #endif is the second to last.
(6)
A directive that is needed only by the implementation itself. Again it is not
relevant to you, as a client of the class.
Avoiding memory leaks
Typically, many individual object instances are created and destroyed during
execution of an object-oriented application. It is important to ensure that, when an
object is destroyed or assigned, all of its associated storage is also freed. The source
code is provided for two C routines that you can use to allocate and free dynamic
storage for data that an object points to, for an inout argument to a method, and
so on:
v ’OMMAllocate’ using storage-size returning a-pointer
to allocate storage, where storage-size is the 4-byte unsigned binary number of
bytes to allocate
v ’OMMFree’ using a-pointer
to free the previously allocated storage element that a-pointer addresses
You must use OMMFree to free output storage allocated and returned to you by
SOM class libraries.
You can also use these routines to manage dynamic storage (as opposed to instance
data) for your own classes.
“Example: COBOL variable-length string class” on page 448
RELATED TASKS
“Passing COBOL arguments and return values” on page 435
RELATED REFERENCES
“Source code for helper routines” on page 450
Chapter 26. Using SOM IDL-based class libraries
447
Example: COBOL variable-length string class
Let’s look at an example of a variable-length string class, where the string data is
not an explicit part of the instance, but is instead a separate storage area that the
instance refers to.
Here’s the COBOL definition for the class:
******************************************************************
* COBOL variable-length string class definition.
*
******************************************************************
Identification division.
Class-id.
varstring inherits somobject.
Environment division.
Configuration section.
Repository.
Class varstring 'VarString'
Class somobject 'SOMObject'
. . .
******************************************************************
* Variable-length string class instance data.
*
******************************************************************
Data division.
Working-storage section.
1 vstlen binary pic 9(9).
1 vstptr pointer.
(1)
(2)
448
Programming Guide
******************************************************************
* Variable-length string class method: default initialization; *
* set the instance to a predictable state.
*
******************************************************************
Identification division.
Method-id.
'somInit' override.
Procedure division.
Set vstptr to null
Move 0 to vstlen
Goback
. . .
End method 'somInit'.
******************************************************************
* Variable-length string class method: assignment from a literal*
******************************************************************
Identification division.
Method-id.
'SetVarstring'.
Data division.
Local-Storage section.
1 strsze pic 9(9) binary.
Linkage section.
1 valptr pointer.
1 setval pic x(100).
1 vstval pic x(100).
Procedure division using by value valptr.
If vstptr not = null then
Call 'OMMFree' using vstptr
End-if
Move 0 to vstlen
Set address of setval to valptr
Inspect setval tallying vstlen
for characters before initial x'00'
Add 1 to vstlen giving strsze
Call 'OMMAllocate' using strsze returning vstptr
Set address of vstval to vstptr
Move setval(1:strsze) to vstval(1:strsze)
Goback
. . .
End method 'SetVarstring'.
******************************************************************
* Variable-length string class method: return string (pointer). *
******************************************************************
Identification division.
Method-id.
'GetVarstring'.
Data division.
Linkage section.
1 valptr pointer.
Procedure division returning valptr.
Set valptr to vstptr
Goback
. . .
End method 'GetVarstring'.
(3)
(4)
******************************************************************
* Variable-length string class method: assign from another string*
******************************************************************
Identification division.
Method-id.
'AssignVarstring'.
Data division.
Local-Storage section.
1 strsze binary pic 9(9).
1 valptr pointer.
Linkage section.
1 str object reference varstring.
Procedure division using by value str.
If self not = str then
Invoke str 'GetVarstring' returning valptr
Invoke self 'SetVarstring' using by value valptr
End-if
Goback
. . .
End method 'AssignVarstring'.
******************************************************************
* Variable-length string class method: free associated storage. *
******************************************************************
Identification division.
Method-id.
'somUninit' override.
Procedure division.
If vstptr not = null then
Call 'OMMFree' using vstptr
Set vstptr to null
Move 0 to vstlen
End-if
Goback
. . .
End method 'somUninit'.
End class varstring.
(1)
All VarString instances are created in a predictable initial state, with the
length set to zero and the string pointer set to null.
(2)
Before a new value is assigned to an instance, the storage allocated for the
current value is freed. If this storage were not freed, it would be
“orphaned,” causing a memory leak.
(3)
When assigning one string to another, you have to check whether the
Chapter 26. Using SOM IDL-based class libraries
449
sender is identical to the receiver before doing the assignment and thereby
prematurely freeing the sender’s storage.
(4)
Although somFree deallocates the storage for the instance data, it does not
free storage that the instance refers to. Thus it is critical to free any such
storage when the instance is uninitialized.
Source code for helper routines
You can use the following C source to implement the helper functions for
representing strings and avoiding memory leaks. You can either statically link the
functions into your application or generate a dynamic load library (DLL) for the
functions and bind your application to the DLL.
/**********************************************************************/
/* Helper functions for using SOM IDL-based class libraries.
*/
/**********************************************************************/
450
/* OS/390 pragma to generate long, mixed-case names
#pragma longname
*/
/* Macro to clear the high-order bit of the argument address
#define Clean(p,q) p=(void*)((int)q&0x7fffffff)
#include <som.h>
*/
/* Object Memory Management: allocate memory.
somToken OMMAlloc(size_t *sze){
size_t *s;
Clean(s,sze);
return SOMMalloc(*s);
}
*/
/* Object Memory Management:
void OMMFree(somToken *ptr){
somToken *p;
Clean(p,ptr);
SOMFree(*p);
return;
}
*/
free allocated memory.
/* Set COBOL representation (ODO object) from IDL string length
void IDLStringToCOBOL(char *str, long *len) {
char *s;
long *l;
Clean(s,str);
Clean(l,len);
(*l)=strlen(s);
return;
}
*/
/* Set IDL string length (null byte) from COBOL (ODO) representation
void IDLStringFromCOBOL(char *str, long *len) {
char *s;
long *l;
Clean(s,str);
Clean(l,len);
s[*l]=0;
return;
}
*/
Programming Guide
Chapter 27. Wrapping or converting procedure-oriented
programs
If you use wrappers (objects that provide an interface between object-oriented and
procedure-oriented code), the object-oriented and procedure-oriented parts of your
system can exist quite well together. Certainly, you want to reuse your existing
code as long as it continues to meet your needs. You can add new function to your
system using object-oriented enhancements.
Only if your existing code no longer meets your needs or its maintenance cost is
too high should you consider converting the entire procedure-oriented system to
an object-oriented system. Then the conversion entails identifying objects,
analyzing the data flow and usage, reallocating code to objects, and writing the
object-oriented code.
RELATED CONCEPTS
“OO view of COBOL programs”
RELATED TASKS
“Wrapping procedure-oriented programs” on page 452
“Converting from procedure-oriented to OO programs” on page 453
OO view of COBOL programs
Conventional COBOL programs belong to one of three types:
v Batch
v Online
v Subprogram
Batch programs are often constructed to access files or databases or both, and to
produce reports. The file or database is the object of the accessing action (UPDATE,
INSERT, DELETE), which determines the structure of the program. The report
produced by a batch program can be viewed as an object, but the structure of the
batch program reflects the structure of the report.
Online programs are built around the transactions which they process, and which
are reflected in user interface maps and panels. Online transactions can access
several files or databases from one panel. There is a one-to-many relationship
between the source of the action and the targets of the action, all of which can be
viewed as objects.
Subprograms typically provide a function too large or complex to include in the
main program. Some subprograms provide reusable code by implementing
general-purpose functions that many programs require. Subprograms can provide
actions such as:
v Changing the values of some parameters based on the values of other
parameters
v Accessing files or databases
v Printing reports
In the last two cases, the parameter list can be viewed as a message to trigger an
action on a file or database object.
© Copyright IBM Corp. 1991, 2000
451
Wrapping procedure-oriented programs
You can use wrapping to integrate existing procedure-oriented code with new
object-oriented code. Two of the definitions for wrap are:
v To enclose as if with a protective covering
v To conceal as if by enveloping
Wrappers are objects that provide an interface between object-oriented code and
procedure-oriented code. They enclose the procedure-oriented code in a package,
concealing its true nature and making it seem like object-oriented code. Wrappers
are useful in coordinating actions on the user interface, and integrating
procedure-oriented code into OO systems.
Coordinating procedural code with interface actions
You can use wrappers to integrate old and new code at the user interface or
“glass-top” level. As user interfaces move toward an object-oriented approach, they
use direct manipulation more. Users can, for example, drag and drop objects onto
other objects, and the objects must work together to take the appropriate action,
such as updating or printing. If one of the objects is implemented by
procedure-oriented code, the wrapper is an interface to this underlying
implementation.
Suppose you have a stable set of procedural code for updating a database, but you
want to include the database as part of a graphical user interface. You want users
to be able to drop a list object representing an update to the database on the
database object and have the update performed. To achieve this, you need to write
a wrapper class to accept messages from the list object; that is, the list object
invokes methods in the wrapper. The methods in the wrapper class interpret the
information from the list object and use the CALL statement to call the appropriate
subprogram in the old procedural code, as shown in the figure:
Integrating procedural code into OO systems
Boundary interface wrappers create objects for procedural code outside the
boundaries of the new object-oriented subsystem. These wrappers allow the
object-oriented part of the system to use the procedure-oriented part of the system
as if it too were object-oriented.
By using wrappers, you can phase in new object-oriented code and continue to use
your existing procedure-oriented code. You can, for example, write a wrapper for
each subprogram in the procedural code. Or if several subprograms are working
with the same object, processing the same file, or producing the same report, you
can write a single wrapper for all the related subprograms. A true object invokes
452
Programming Guide
the appropriate method in the wrapper, and the method in turn calls the
appropriate subprogram, as shown in the figure:
Changing procedural code
If you decide to use wrappers, there is one change that you must make to your
procedural code. Because methods are always recursive, the following series of
events is possible:
1. Method A is invoked and calls program B.
2. While program B is executing, method A is invoked again and calls program B
again.
The second call is a recursive call. Therefore, any procedural code that a method
invokes should have the RECURSIVE clause on the PROGRAM-ID statement. For
example:
Identification Division.
Program-Id. ProgB Recursive.
Environment Division.
. . .
RELATED TASKS
“Converting from procedure-oriented to OO programs”
Converting from procedure-oriented to OO programs
If you use a typical procedure-oriented COBOL batch or online program as the
starting point, your aim is to produce a formal specification of the program in
object-oriented form. The conversion involves four steps:
1. “Identifying objects” on page 454: create a list of objects with instance data for
each object.
2. “Analyzing data flow and usage” on page 454: create an object relationship
table that lists all the inheritance and collaboration relationships between
objects.
3. “Reallocating code to objects” on page 454: complete the method definitions.
4. “Writing the object-oriented code” on page 455: write a class definition and
client program.
RELATED CONCEPTS
“OO view of COBOL programs” on page 451
RELATED TASKS
“Defining a class” on page 378
“Defining a class method” on page 381
“Defining a client program” on page 389
Chapter 27. Wrapping or converting procedure-oriented programs
453
Identifying objects
1. Partition the DATA DIVISION into potential objects. Identify every record as an
object and every field in the record as its instance data.
For example, you can organize different record structures as follows, using
names of your choosing for the first five letters:
Potential objects
Object names
Record structures that define files
FffffFile
Record structures that define database views
VvvvvView
Map or panel record structures
UuuuuInterface
Record structures in the WORKING-STORAGE SECTION not related
to files, databases, maps, or panels
WwwwwWork
Record structures in the LINKAGE SECTION
PppppParameter
2. Now you have many potential objects, some of which are redundant. Study the
potential objects and decide whether two or more are slight variations of the
same object.
3. Where possible, combine two potential objects into one object. Maybe you have
two detail lines as potential objects that differ in only one or two of their fields.
If possible, use REDEFINES or some other technique to combine the two detail
lines into one.
As a result of identifying objects, you have an object list with the name of each
object and its instance data.
Analyzing data flow and usage
1. Analyze the file and database accesses to collect the access operations (such as
SELECT, UPDATE, INSERT, DELETE, READ, and WRITE) for each object. Use the access
sequence to look for the relationships between objects.
For example, if a record is read from the input file and then results in a detail
line written to a report, a relationship exists between the file object (the source)
and the report object (the target).
2. Trace the data flow between objects to identify the objects that use instance
data from another object.
If the two objects have a superclass-subclass (parent-child) relationship, the
subclass inherits methods from the superclass and can share instance data
through get and set methods defined in the superclass.
If the two objects are separate and distinct, they are collaborators. Collaborators
do not inherit anything from each other. Instance data that needs to be shared
between two collaborators is typically passed by means of parameters on an
INVOKE statement.
As a result of analyzing the data flow and usage, you have an object relationship
table that lists all the inheritance and collaboration relationships between objects.
Reallocating code to objects
For each object you identified, collect all references to it from the PROCEDURE
DIVISION. Look for procedural code that changes the state of the object’s instance
data. If a statement affects several data items in different objects, you must change
or duplicate the statement to associate the intended actions with the correct objects.
For example:
454
Programming Guide
Move 0 To input-z output-z.
Change this statement to:
Move 0 To input-z.
Move 0 To output-z.
The first MOVE statement is associated with an input object and the second with an
output object.
Now couple the procedural statements from the PROCEDURE DIVISION with the
objects to form methods. Take the code you pulled from the program and organize
it into task-oriented methods.
Refer to the object relationship table from step two (analyzing data flow and
usage) and determine if you must write any new methods to facilitate passing data
between objects.
The result of this step is completed method definitions.
RELATED TASKS
“Identifying objects” on page 454
“Analyzing data flow and usage” on page 454
“Defining a class method” on page 381
Writing the object-oriented code
Write a class definition using the object list from step one (identifying objects) and
the methods from step three (reallocating code to objects).
Also, write the client program to create instances of the classes and invoke
methods.
Your client program might be a modification of your original procedure-oriented
program, but with added method invocations and manipulation of object
references where needed. (This is the case when all the procedure-oriented code
was not placed into methods.) However, if all the procedure-oriented code was
placed into methods, then your client program is a new program that you write
from scratch.
RELATED TASKS
“Identifying objects” on page 454
“Reallocating code to objects” on page 454
“Defining a class” on page 378
“Defining a client program” on page 389
Chapter 27. Wrapping or converting procedure-oriented programs
455
456
Programming Guide
Part 5. Working with more complex applications
Chapter 28. Using subprograms . . . . . .
Main programs, subprograms, and calls . . . .
Ending and reentering main programs or
subprograms . . . . . . . . . . . . .
Transferring control to another program . . . .
Making static calls. . . . . . . . . . .
Making dynamic calls . . . . . . . . .
Canceling a subprogram. . . . . . . .
When to use a dynamic call . . . . . .
Performance considerations of static and
dynamic calls . . . . . . . . . . . .
Making both static and dynamic calls . . . .
Example: static and dynamic CALL statements
NODYNAM restriction (CMS only) . . . . .
Example: mixing static and dynamic calls to
the same subprogram under CMS . . . .
Example: mixing static and dynamic calls
that can cause a protection exception under
CMS . . . . . . . . . . . . . .
Calling nested COBOL programs . . . . . .
Nested programs . . . . . . . . . .
Example: structure of nested programs . . .
Scope of names. . . . . . . . . . .
Making recursive calls . . . . . . . . . .
Calling to and from object-oriented programs . .
Using procedure pointers . . . . . . . . .
Calling a C function-pointer . . . . . . .
Calling to alternate entry points . . . . . .
Making programs reentrant . . . . . . . .
459
459
Chapter 29. Sharing data . . . . . . . . .
Passing data . . . . . . . . . . . . . .
Describing arguments in the calling program
Describing parameters in the called program
Coding the LINKAGE SECTION . . . . . . .
Coding the PROCEDURE DIVISION for passing
arguments . . . . . . . . . . . . . .
Grouping data to be passed . . . . . . .
Handling null-terminated strings . . . . . .
Using pointers to process a chained list . . .
Example: using pointers to process a chained
list . . . . . . . . . . . . . . .
Passing return code information . . . . . . .
Understanding the RETURN-CODE special
register . . . . . . . . . . . . . .
Using PROCEDURE DIVISION RETURNING . .
.. . . . . . . . . . . . . . . . .
Specifying CALL . . . RETURNING . . . . . .
Sharing data by using the EXTERNAL clause. . .
Sharing files between programs (external files) . .
Example: using external files . . . . . . .
475
475
477
477
477
Chapter 30. Creating a DLL or a DLL application
Dynamic link libraries (DLLs) . . . . . . . .
Compiling programs to create DLLs . . . . . .
Linking DLLs . . . . . . . . . . . . .
489
489
490
491
© Copyright IBM Corp. 1991, 2000
460
461
462
462
463
463
464
465
465
467
467
468
468
469
470
471
472
472
472
473
473
474
478
478
478
479
480
482
482
482
483
483
483
484
Prelinking certain DLLs . . . . . . . .
Example: sample JCL for a procedural DLL
application . . . . . . . . . . .
Using CALL identifier with DLLs . . . .
Search order for DLLs in HFS . . . . .
Using DLL linkage and dynamic calls together
Using procedure-pointers with DLLs . .
Calling DLLs from non-DLLs . . . . .
Example: calling DLLs from non-DLLs . .
Using COBOL DLLs with C/C++ programs .
Using DLLs in OO COBOL applications . .
.
. 492
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
492
493
494
494
495
496
496
498
498
Chapter 31. Interrupts and checkpoint/restart
Setting checkpoints . . . . . . . . . . .
Designing checkpoints . . . . . . . . .
Testing for a successful checkpoint . . . . .
DD statements for defining checkpoint data sets
Examples: defining checkpoint data sets . .
Messages generated during checkpoint . . . .
Restarting programs . . . . . . . . . . .
Requesting automatic restart . . . . . . .
Requesting deferred restart . . . . . . . .
Formats for requesting deferred restart . . . .
Example: requesting a deferred restart . . .
Resubmitting jobs for restart . . . . . . .
Example: restarting a job at a specific
checkpoint step. . . . . . . . . . . .
Example: requesting a step restart . . . . .
Example: resubmitting a job for a step restart
Example: resubmitting a job for a checkpoint
restart . . . . . . . . . . . . . . .
501
501
502
502
503
503
504
504
505
505
506
506
507
507
507
507
508
Chapter 32. Processing two-digit-year dates
509
Millennium language extensions (MLE) . . . . 510
Principles and objectives of these extensions . . 510
Resolving date-related logic problems . . . . . 511
Using a century window . . . . . . . . 512
Example: century window . . . . . . . 513
Using internal bridging . . . . . . . . . 513
Example: internal bridging . . . . . . . 514
Moving to full field expansion. . . . . . . 514
Example: converting files to expanded date
form . . . . . . . . . . . . . . 515
Using year-first, year-only, and year-last date fields 516
Compatible dates . . . . . . . . . . . 517
Example: comparing year-first date fields . . . 518
Using other date formats . . . . . . . . 518
Example: isolating the year . . . . . . . . 518
Manipulating literals as dates . . . . . . . . 519
Assumed century window . . . . . . . . 520
Treatment of nondates . . . . . . . . . 521
Setting triggers and limits . . . . . . . . . 521
Example: using limits . . . . . . . . . 522
Using sign conditions . . . . . . . . . 523
Sorting and merging by date . . . . . . . . 523
Example: sorting by date and time . . . . . 524
457
Performing arithmetic on date fields. . . . . .
Allowing for overflow from windowed date
fields . . . . . . . . . . . . . . .
Specifying the order of evaluation . . . . .
Controlling date processing explicitly . . . . .
Using DATEVAL . . . . . . . . . . .
Using UNDATE . . . . . . . . . . .
Example: DATEVAL . . . . . . . . .
Example: UNDATE . . . . . . . . .
Analyzing and avoiding date-related diagnostic
messages . . . . . . . . . . . . . . .
Avoiding problems in processing dates . . . . .
Avoiding problems with packed-decimal fields
Moving from expanded to windowed date fields
458
Programming Guide
525
525
526
527
527
527
528
528
528
530
530
530
Chapter 28. Using subprograms
Many applications consist of several separately compiled programs linked together.
A run unit (the COBOL term synonymous with enclave in Language Environment)
includes one or more object programs and can include object programs written in
other Language Environment member languages.
Language Environment provides interlanguage support that allows your COBOL
for OS/390 & VM programs to call and be called by programs that meet the
requirements of Language Environment. Full details on interlanguage
communication (ILC) and information on the register conventions required for
assembler calls are documented in the Language Environment information.
Attention: Do not use program names that start with prefixes used by IBM
products. If you try to use programs whose names start with any of the following,
your CALL statements might resolve to IBM library or compiler routines rather than
to your intended program:
AFB
IBM
AFH
IFY
CBC
IGY
CEE
IGZ
EDC
ILB
RELATED CONCEPTS
“Main programs, subprograms, and calls”
RELATED TASKS
“Ending and reentering main programs or subprograms” on page 460
“Transferring control to another program” on page 461
“Making recursive calls” on page 472
“Calling to and from object-oriented programs” on page 472
“Using procedure pointers” on page 472
“Making programs reentrant” on page 474
Language Environment Writing ILC Applications
RELATED REFERENCES
Register conventions (Language Environment Programming Guide)
Main programs, subprograms, and calls
If a COBOL program is the first program in the run unit, that COBOL program is
the main program. Otherwise, it and all other COBOL programs in the run unit are
subprograms. No specific source code statements or options identify a COBOL
program as a main program or a subprogram.
Whether a COBOL program is a main program or a subprogram can be significant
for either of two reasons:
v Effect of program termination statements
v State of the program when it is reentered after returning
In the PROCEDURE DIVISION, a program can call another program (generally called a
subprogram in COBOL terms), and this called program can itself call other
programs. The program that calls another program is referred to as the calling
program, and the program it calls is referred to as the called program. When the
© Copyright IBM Corp. 1991, 2000
459
called program processing is completed, the program can either transfer control
back to the calling program or end the run unit.
The called COBOL program starts running at the top of the PROCEDURE DIVISION.
RELATED TASKS
“Ending and reentering main programs or subprograms”
“Making recursive calls” on page 472
“Transferring control to another program” on page 461
RELATED REFERENCES
Language Environment Programming Guide
Ending and reentering main programs or subprograms
You can use any of three termination statements in a main program or
subprogram, but they have different effects, as shown in the table below:
Termination
statement
Main program
Subprogram
EXIT PROGRAM
No action taken.
Return to calling program without
ending the run unit. An implicit
EXIT PROGRAM statement is
generated if the called program
has no next executable statement.
STOP RUN
Return to calling program.1 (Might Return directly to the program that
be the operating system, and job
called the main program.1 (Might
be the operating system, and job
will end.)
will end.)
STOP RUN terminates the run unit,
and deletes all dynamically called
programs in the run unit and all
programs link-edited with them. (It
does not delete the main program.)
GOBACK
Return to calling program.1 (Might Return to calling program.
be the operating system, and job
will end.)
Same effect as STOP RUN.
1. If the main program is called by a program written in another language that does not
follow Language Environment linkage conventions, return will be to this calling
program.
A subprogram is usually left in its last-used state when it terminates with EXIT
PROGRAM or GOBACK. The next time it is called in the run unit, its internal values will
be as they were left, except that return values for PERFORM statements will be reset
to their initial values. (In contrast, a main program is initialized each time it is
called.)
There are some cases where programs will be in their initial state:
v A subprogram that is dynamically called and then canceled will be in the initial
state the next time it is called.
v A program with the INITIAL attribute will be in the initial state each time it is
called.
460
Programming Guide
v Data defined in the LOCAL-STORAGE SECTION will be in the initial state each time
the outermost containing program is called. (For nested programs,
LOCAL-STORAGE is in the initial state each time the nested program is called.)
RELATED CONCEPTS
“Comparison of WORKING-STORAGE and LOCAL-STORAGE” on page 15
RELATED TASKS
“Calling nested COBOL programs” on page 468
“Making recursive calls” on page 472
Transferring control to another program
You can use several different methods to transfer control to another program:
v Static calls
v Dynamic calls
v Calls to nested programs
v Calls to dynamic link libraries (DLLs)
In addition to making calls between COBOL for OS/390 & VM programs, you can
also make static and dynamic calls between COBOL for OS/390 & VM, COBOL for
MVS & VM, and VS COBOL II programs in all environments (including CICS).
|
Exception: You cannot call VS COBOL II in the OS/390 UNIX environment.
When you want to use OS/VS COBOL with COBOL for OS/390 & VM, there are
differences in support between non-CICS and CICS:
In a non-CICS environment
You can make static and dynamic calls between COBOL for OS/390 & VM,
COBOL for MVS & VM, and OS/VS COBOL programs.
|
|
Exception: You cannot call OS/VS COBOL in the OS/390 UNIX
environment.
In a CICS environment
You must use EXEC CICS LINK to transfer control between OS/VS COBOL
programs and COBOL for OS/390 & VM, COBOL for MVS & VM, and
OS/VS COBOL programs.
Calls to nested programs allow you to create applications using structured
programming techniques. You can use nested programs in place of PERFORM
procedures to prevent unintentional modification of data items. Call nested
programs using either the CALL literal or CALL identifier statement.
|
|
Calls to dynamic link libraries (DLLs) are an alternative to COBOL dynamic CALL,
and are well suited to object-oriented COBOL applications, OS/390 UNIX
programs, and applications that interoperate with C/C++
Under OS/390, linking two load modules together results logically in a single
program with a primary entry point and an alternate entry point, each with its
own name. Each name by which a subprogram is to be dynamically called must be
known to the system. You must specify each such name in linkage editor control
statements as either a NAME or an ALIAS of the load module that contains the
subprogram.
Chapter 28. Using subprograms
461
RELATED CONCEPTS
“Nested programs” on page 469
RELATED TASKS
“Making static calls”
“Making dynamic calls”
“Making both static and dynamic calls” on page 465
“Calling nested COBOL programs” on page 468
Making static calls
When you use the CALL literal statement in a program that is compiled using the
NODYNAM and NODLL compiler options, a static call occurs. With these options, all
calls of the CALL literal format are handled as static calls.
In the static CALL statement, the COBOL program and all called programs are part
of the same load module. When control is transferred, the called program already
resides in storage, and a branch to it takes place. Subsequent executions of the CALL
statement make the called program available in its last-used state, unless the called
program has the INITIAL attribute. In that case, the called program and each
program directly or indirectly contained within it are placed into its initial state
every time the called program is called within a run unit.
If you specify alternate entry points, a static CALL statement can use any alternate
entry point to enter the called subprogram.
“Example: static and dynamic CALL statements” on page 465
RELATED CONCEPTS
“Performance considerations of static and dynamic calls” on page 464
RELATED TASKS
“Calling to and from object-oriented programs” on page 472
“Making dynamic calls”
“Making both static and dynamic calls” on page 465
RELATED REFERENCES
“NODYNAM restriction (CMS only)” on page 467
“DYNAM” on page 272
“DLL” on page 270
CALL statement (IBM COBOL Language Reference)
Making dynamic calls
When you use the CALL literal statement in a program that is compiled using the
DYNAM and the NODLL compiler options, or when you use the CALL identifier
statement in a program that is compiled using the NODLL compiler option, a
dynamic call occurs. The program name in the PROGRAM-ID paragraph or ENTRY
statement must be identical to the corresponding load module name or load
module alias of the load module that contains it.
In this form of the CALL statement, the called COBOL subprogram is not link-edited
with the main program, but is instead link-edited into a separate load module,
and, at run time, is loaded only when it is required (that is, when called).
Each subprogram that is called with a dynamic CALL statement can be part of a
different load module that is a member of either the system link library or a
462
Programming Guide
|
|
user-supplied private library. In either case it must be in an OS/390 load library; it
cannot reside in the hierarchical file system. When a dynamic CALL statement calls
a subprogram that is not resident in storage, the subprogram is loaded from
secondary storage into the region or partition containing the main program and a
branch to the subprogram is performed.
The first dynamic call to a subprogram within a run unit obtains a fresh copy of
the subprogram. Subsequent calls to the same subprogram (by either the original
caller or any other subprogram within the same run unit) result in a branch to the
same copy of the subprogram in its last-used state, provided the subprogram does
not possess the INITIAL attribute. Therefore, the reinitialization of either of the
following items is your responsibility:
v GO TO statements that have been altered
v Data items
If the same COBOL program is called under different run units, a separate copy of
working storage is allocated for each run unit.
Restriction: Dynamic calls are not permitted to:
v COBOL DLL programs
v COBOL programs compiled with the PGMNAME(LONGMIXED) option, unless the
program name is less than or equal to eight characters in length and is all
uppercase
v COBOL programs compiled with the PGMNAME(LONGUPPER) option, unless the
program name is less than or equal to eight characters in length
v More than one entry point in the same COBOL program (unless an intervening
CANCEL statement has been executed)
Canceling a subprogram
When a CANCEL statement is issued for a subprogram, the storage occupied by the
subprogram is freed, and a subsequent call to the subprogram functions as though
it were the first call. You can cancel a subprogram from a program other than the
original caller.
If the called subprogram has more than one entry point, ensure an intervening
CANCEL statement is issued before you specify different entry points in the dynamic
CALL statement.
After a CANCEL statement is processed for a dynamically called contained program,
the program will be in the first-used state. However, the program is not loaded
with the initial call, and storage is not freed after the program is canceled.
When to use a dynamic call
Use a dynamic CALL statement in any of the following circumstances:
|
|
v The load module that you want to dynamically call is in an OS/390 load library
rather than in the hierarchical file system.
v You are concerned about ease of maintenance. Applications do not have to be
link-edited again when dynamically called subprograms are changed.
v The subprograms called are used infrequently or are very large.
If the subprograms are called on only a few conditions, dynamic calls can bring
in the subprogram only when needed.
If the subprograms are very large or there are many of them, using static calls
might require too much main storage. Less total storage might be required to
call and cancel one, then call and cancel another, than to statically call both.
Chapter 28. Using subprograms
463
v You want to call subprograms in their unused state, and you cannot use the
INITIAL attribute.
When you cannot use the INITIAL attribute to ensure that a subprogram is
placed in its unused state each time it is called, you can set the unused state by
using a combination of dynamic CALL and CANCEL statements. When you cancel
the subprogram that was first called by a COBOL program, the next call will
cause the subprogram to be reinitialized to its unused state.
Using the CANCEL statement to explicitly cancel a subprogram that was
dynamically loaded and branched to by a non-COBOL program does not result
in any action being taken to release the subprogram’s storage or to delete the
subprogram.
v You have an OS/VS COBOL or other AMODE(24) program in the same run unit
with COBOL for OS/390 & VM programs that you want to run in 31-bit
addressing mode. OS/VS COBOL, VS COBOL II, COBOL for MVS & VM, and
COBOL for OS/390 & VM dynamic call processing include AMODE switching for
AMODE(24) programs calling AMODE(31) programs, and vice versa. To have this
implicit AMODE switching done, you must use the Language Environment
run-time option ALL31(OFF). AMODE switching is not performed when ALL31(ON)
is set.
When AMODE switching is performed, control is passed from the caller to a
Language Environment library routine. After the switching is performed, control
passes to the called program; the save area for the library routine will be
positioned between the save area for the caller program and the save area for
the called program.
v You do not know the program name to be called until run time. Here, use the
format CALL identifier, where the identifier is a data item that will contain the
name of the called program at run time. In terms of practical application, you
might use CALL identifier when the program to be called is variable, depending
on conditional processing in your program. CALL identifier is always dynamic,
even if you use the NODYNAM compiler option.
“Example: static and dynamic CALL statements” on page 465
RELATED CONCEPTS
“Performance considerations of static and dynamic calls”
RELATED TASKS
“Making both static and dynamic calls” on page 465
RELATED REFERENCES
“NODYNAM restriction (CMS only)” on page 467
“DYNAM” on page 272
CALL statement (IBM COBOL Language Reference)
ENTRY statement (IBM COBOL Language Reference)
Language Environment Programming Reference
Performance considerations of static and dynamic calls
Because a statically called program is link-edited into the same load module as the
calling program, a static call is faster than a dynamic call. A static call is the
preferred method if your application does not require the services of the dynamic
call.
464
Programming Guide
Statically called programs cannot be deleted (using CANCEL), so static calls might
take more main storage. If storage is a concern, think about using dynamic calls.
Storage usage of calls depends on whether:
v The subprogram is called only a few times. Regardless of whether it is called, a
statically called program is loaded into storage; a dynamically called program is
loaded only when it is called.
v You subsequently delete the dynamically called subprogram with a CANCEL
statement.
You cannot delete a statically called program, but you can delete a dynamically
called program. Using a dynamic call and then a CANCEL statement to delete the
dynamically called program after it is no longer needed in the application (and
not after each call to it) might require less storage than using a static call.
RELATED TASKS
“Making static calls” on page 462
“Making dynamic calls” on page 462
Making both static and dynamic calls
You can specify both static and dynamic CALL statements in the same program if
you compile the program with the NODYNAM compiler option. In this case, with the
CALL literal statement the called subprogram will be link-edited with the main
program into one load module. The CALL identifier statement results in the dynamic
invocation of a separate load module.
When a dynamic CALL statement and a static CALL statement to the same
subprogram are issued within one program, a second copy of the subprogram is
loaded into storage. Because this arrangement does not guarantee that the
subprogram will be left in its last-used state, results can be unpredictable.
RELATED REFERENCES
“NODYNAM restriction (CMS only)” on page 467
“DYNAM” on page 272
Example: static and dynamic CALL statements
This example has three parts:
v Code that uses a static call to call a subprogram
v Code that uses a dynamic call to call the same subprogram
v The subprogram that is called by the two types of calls
The following example shows how you would code a static call:
PROCESS NODYNAM NODLL
IDENTIFICATION DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 RECORD-2
PIC X.
01 RECORD-1.
05 PAY
PICTURE S9(5)V99.
05 HOURLY-RATE
PICTURE S9V99.
05 HOURS
PICTURE S99V9.
. . .
PROCEDURE DIVISION.
CALL “SUBPROG” USING RECORD-1.
CALL “PAYMASTR” USING RECORD-1 RECORD-2.
STOP RUN.
(6)
(2)
(1)
(5)
The following example shows how you would code a dynamic call:
Chapter 28. Using subprograms
465
DATA DIVISION.
WORKING-STORAGE SECTION.
77 PGM-NAME
PICTURE X(8).
01 RECORD-2
PIC x.
01 RECORD-1.
05 PAY
PICTURE S9(5)V99.
05 HOURLY-RATE
PICTURE S9V99.
05 HOURS
PICTURE S99V9.
. . .
PROCEDURE DIVISION.
. . .
MOVE “SUBPROG” TO PGM-NAME.
CALL PGM-NAME USING RECORD-1.
CANCEL PGM-NAME.
MOVE “PAYMASTR” TO PGM-NAME.
CALL PGM-NAME USING RECORD-1 RECORD-2.
STOP RUN.
(6)
(2)
(1)
(4)
(5)
The following example shows a called subprogram that is called by each of the
two preceding calling programs:
IDENTIFICATION DIVISION.
PROGRAM-ID. SUBPROG.
DATA DIVISION.
LINKAGE SECTION.
01 PAYREC.
10 PAY
PICTURE S9(5)V99.
10 HOURLY-RATE
PICTURE S9V99.
10 HOURS
PICTURE S99V9.
77 PAY-CODE
PICTURE 9.
PROCEDURE DIVISION USING PAYREC. (1)
. . .
EXIT PROGRAM.
ENTRY “PAYMASTR” USING PAYREC PAY-CODE.
. . .
GOBACK.
(1)
(2)
(6)
(3)
(5)
(7)
Processing begins in the calling program. When the first CALL statement is
executed, control is transferred to the first statement of the PROCEDURE
DIVISION in SUBPROG, which is the called program.
In each of the CALL statements, the operand of the first USING option is
identified as RECORD-1.
(2)
When SUBPROG receives control, the values within RECORD-1 are made
available to SUBPROG; however, in SUBPROG they are referred to as PAYREC.
The PICTURE character-strings within PAYREC and PAY-CODE contain the same
number of characters as RECORD-1 and RECORD-2, although the descriptions
are not identical.
466
(3)
When processing within SUBPROG reaches the EXIT PROGRAM statement,
control is returned to the calling program. Processing continues in that
program until the second CALL statement is issued.
(4)
In the example of a dynamically called program, because the second CALL
statement refers to another entry point within SUBPROG, a CANCEL statement
is issued before the second CALL statement.
(5)
With the second CALL statement in the calling program, control is again
transferred to SUBPROG, but this time processing begins at the statement
following the ENTRY statement in SUBPROG.
(6)
The values within RECORD-1 are again made available to PAYREC. In
addition, the value in RECORD-2 is now made available to SUBPROG through
the corresponding USING operand PAY-CODE.
Programming Guide
When control is transferred the second time from the statically linked
program, SUBPROG is made available in its last-used state (that is, if any
values in SUBPROG storage were changed during the first execution, those
changed values are still in effect). When control is transferred from the
dynamically linked program, however, SUBPROG is made available in its
initial state, because of the CANCEL statement that has been executed.
(7)
When processing reaches the GOBACK statement, control is returned to the
calling program at the statement immediately following the second CALL
statement.
In any given execution of the called program and either of the two calling
programs, if the values within RECORD-1 are changed between the time of the first
CALL and the second, the values passed at the time of the second CALL statement
will be the changed, not the original, values. If you want to use the original values,
they must be saved.
NODYNAM restriction (CMS only)
The following restriction applies only under CMS if you are using TEXT, TXTLIB,
or nonrelocatable modules.
When you use the NODYNAM option, do not mix a dynamic CALL identifier and a static
CALL literal for the same subprogram. Under CMS, certain combinations can cause
unpredictable results; some of these combinations are illustrated below.
Example: mixing static and dynamic calls to the same
subprogram under CMS
This example shows a mix of a static CALL with a dynamic CALL and CANCEL of
subprograms under CMS. Prog-MAIN and Prog-SUB1 are available as TEXT files
and Prog-SUB2 is a load module in a CMS LOADLIB (created with the LKED
command) that is link-edited with a copy of Prog-SUB1.
In this example, the following process occurs:
1. Prog-MAIN statically calls Prog-SUB1, which causes it to be loaded with
Prog-MAIN.
2. Prog-MAIN dynamically calls Prog-SUB2, which causes a separate load module
to be loaded.
3. Prog-SUB2 statically calls Prog-SUB1, which was link-edited with Prog-SUB2.
Now there are two copies of Prog-SUB1. Its last-used state will depend on which
program called which version of Prog-SUB1.
Chapter 28. Using subprograms
467
Example: mixing static and dynamic calls that can cause a
protection exception under CMS
This example shows a mix of a static CALL with a dynamic CALL and CANCEL of
subprograms under CMS that can cause a protection exception. Here all of the
programs are available as TEXT files; no load modules are used.
In this example, the following process occurs:
1. Prog-MAIN statically calls Prog-SUB1, which causes it to be loaded with
Prog-MAIN.
2. Prog-MAIN dynamically calls Prog-SUB2 but does not also load another copy
of Prog-SUB1 because the user did not create a load module with Prog-SUB1
link-edited to Prog-SUB2.
3. Prog-SUB2 statically calls Prog-SUB1, maybe causing the CMS system to use
the copy previously loaded for Prog-MAIN, instead of a separate copy.
4. When CMS uses the copy of Prog-SUB1 that was loaded for Prog-MAIN and
Prog-MAIN issues a CANCEL for Prog-SUB2, Prog-SUB1 is also deleted.
5. Prog-MAIN again statically calls Prog-SUB1.
The run unit fails because the run unit control blocks still have pointers to
Prog-SUB1 (because Prog-MAIN has not yet completed), but Prog-SUB1 is no
longer in dynamic storage.
Calling nested COBOL programs
By calling nested programs you can create applications using structured
programming techniques. You can also use them in place of PERFORM procedures to
prevent unintentional modification of data items.
Use either the CALL literal or CALL identifier statement to make calls to nested
programs.
You can call a contained program only from its directly containing program, unless
you identify the contained program as COMMON in its PROGRAM-ID clause. In that case,
you can call the common program from any program that is contained (directly or
indirectly) in the same program as the common program. Only contained
programs can be identified as COMMON. Recursive calls are not allowed.
Follow these guidelines when using nested program structures:
v Use the IDENTIFICATION DIVISION in each program. All other divisions are
optional.
v Make the name of a contained program unique. You can use any valid COBOL
word or a nonnumeric literal.
v In the outermost program set any CONFIGURATION SECTION options that might be
required. Contained programs cannot have a CONFIGURATION SECTION.
468
Programming Guide
v Include each contained program in the containing program immediately before
its End Program header.
v Use an End Program header to terminate contained and containing programs.
RELATED CONCEPTS
“Nested programs”
RELATED REFERENCES
“Scope of names” on page 471
CALL statement (IBM COBOL Language Reference)
Nested programs
A COBOL program can “nest,” or contain, other COBOL programs. The nested
programs can themselves contain yet other programs. A nested program can be
directly or indirectly contained in a program.
There are four main advantages to nesting called programs:
1. Nested programs give you a method to create modular functions for your
application and maintain structured programming techniques. They can be
used analogously to PERFORM procedures, but with more structured control flow
and with the ability to protect local data-items.
2. Nested programs allow for debugging a program before including it in the
application.
3. Nested programs allow you to compile your application with a single
invocation of the compiler.
4. Calls to nested programs have the best performance of all the forms of COBOL
CALL statements.
The following example describes a nested program structure with directly and
indirectly contained programs:
Chapter 28. Using subprograms
469
“Example: structure of nested programs”
RELATED TASKS
“Calling nested COBOL programs” on page 468
RELATED REFERENCES
“Scope of names” on page 471
Example: structure of nested programs
The following example shows a nested structure with some contained programs
identified as COMMON.
470
Programming Guide
The following table describes the calling hierarchy for the structure that is shown
in the example above. Programs A12, A2, and A3 are identified as COMMON, and the
calls associated with them differ.
This program
Can call these programs
And can be called by these programs
A
A1, A2, A3
None
A1
A11, A12, A2, A3
A
A11
A111, A12, A2, A3
A1
A111
A12, A2, A3
A11
A12
A2, A3
A1, A11, A111
A2
A3
A, A1, A11, A111, A12, A3
A3
A2
A, A1, A11, A111, A12, A2
Note that:
v A2 cannot call A1 because A1 is not common and is not contained in A2.
v A1 can call A2 because A2 is common.
Scope of names
Names in nested structures are divided into two classes: local and global. The class
determines whether a name is known beyond the scope of the program that
declares it. A specific search sequence locates the declaration of a name after it is
referenced in a program.
Local names: Names (except the program name) are local unless declared to be
otherwise. Local names are visible or accessible only within the program in which
they were declared. They are not visible or accessible to contained and containing
programs.
Global names: A name that is global (indicated using the GLOBAL clause) is visible
and accessible to the program in which it is declared, and to all the programs that
are directly and indirectly contained in that program. Therefore, the contained
programs can share common data and files from the containing program, simply
by referencing the name of the item.
Any item that is subordinate to a global item (including condition-names and
indexes) is automatically global.
You can declare the same name with the GLOBAL clause more than one time,
providing that each declaration occurs in a different program. Be aware that you
can mask, or hide, a name in a nested structure by having the same name occur in
different programs of the same containing structure. However, this masking could
cause problems during a search for a name declaration.
Searching for name declarations: When a name is referenced in a program, a
search is made to locate the declaration for that name. The search begins in the
program that contains the reference and continues outward to containing programs
until a match is found. The search follows this process:
1. Declarations in the program are searched first.
2. If no match is found, only global declarations are searched in successive outer
containing programs.
3. The search ends when the first matching name is found; otherwise, an error
exists if no match is found.
Chapter 28. Using subprograms
471
The search is for a global name, not for a particular type of object associated with
the name, such as a data item or file connector. The search stops when any match
is found, regardless of the type of object. If the object declared is of a different type
than that expected, an error condition exists.
Making recursive calls
A called program can directly or indirectly execute its caller. For example, program
X calls program Y, program Y calls program Z, and program Z then calls program X.
This type of call is recursive.
To make a recursive call, you must code the RECURSIVE clause on the PROGRAM-ID
paragraph of the recursively called program. If you try to recursively call a
COBOL program that does not have the RECURSIVE clause coded on its PROGRAM-ID
paragraph, a condition is signaled. If the condition remains unhanded, the run unit
will end.
RELATED TASKS
“Identifying a program as recursive” on page 6
RELATED REFERENCES
RECURSIVE attribute (IBM COBOL Language Reference)
Calling to and from object-oriented programs
When you create applications that contain object-oriented programs (programs that
contain class definitions or INVOKE statements), the object-oriented COBOL
programs are COBOL DLL programs and can be in one or more dynamic link
libraries (DLLs). Calls to or from COBOL DLL programs must either use DLL
linkage or be static calls. COBOL dynamic calls to or from COBOL DLL programs
are not supported.
If you must call a COBOL DLL program from a COBOL non-DLL program, other
methods, which ensure the DLL linkage mechanism is followed, are available.
Using procedure pointers
Procedure pointers are data items defined with the USAGE IS PROCEDURE-POINTER
clause. You can set procedure-pointer data items to contain entry addresses of (or
pointers to) these entry points:
v Another COBOL program that is not nested. For example, to have a user-written
error-handling routine take control when an exception condition occurs, you
must first pass the entry address of the routine to CEEHDLR, a condition
management Language Environment callable service, to have it registered.
v A program written in another language. For example, to receive the entry
address of a C function, call the function with the CALL RETURNING format of the
CALL statement. It will return a pointer that you can convert to a procedure
pointer by using a form of the SET statement.
v An alternate entry point in another COBOL program (as defined in an ENTRY
statement).
You can set a procedure-pointer data item only by using format-6 of the SET
statement. The SET statement sets the procedure pointer to refer either to an entry
point in the same load module as your program, to a separate load module, or to
472
Programming Guide
an entry point exported from a DLL, depending on the DYNAM|NODYNAM and
DLL|NODLL compiler options. Therefore, think about these factors when using
procedure-pointer data items:
|
|
|
|
|
|
|
|
|
|
|
|
v If you compile your program with the NODYNAM and NODLL options and set your
procedure-pointer item to a literal value (to an actual name of an entry point),
the value must refer to an entry point in the same load module as your
program. Otherwise the reference cannot be resolved.
v If you compile your program with the NODLL option and either set your
procedure-pointer item to an identifier that will contain the name of the entry
point at run time or set your procedure-pointer item to a literal and compile
with the DYNAM option, then your procedure-pointer item, whether a literal or
variable, must point to an entry point in a separate load module. The entry
point can be either the primary entry point or an alternate entry point named in
an ALIAS linkage editor statement.
v If you compile with the NODYNAM and DLL options and set your procedure-pointer
item to a literal value (the actual name of an entry point), the value must refer
to an entry point in the same load module as your program or to an entry point
name that is exported from a DLL module. In the latter case you must include
the DLL side deck for the target DLL module in the link edit of your program
load module.
v If you compile with the NODYNAM and DLL options and set your procedure-pointer
item to an identifier (a data item that contains the entry point name at run time),
the identifier value must refer to the entry point name that is exported from a
DLL module. In this case the DLL module name must match the name of the
exported entry point.
If you set your procedure-pointer item to an entry address in a dynamically called
load module and your program subsequently cancels that dynamically called
module, then your procedure-pointer item becomes undefined. Reference to it
thereafter is not reliable.
Calling a C function-pointer
Many callable services written in C return function-pointers. Your COBOL program
can call such a C function-pointer by the following technique:
IDENTIFICATION DIVISION.
PROGRAM-ID. DEMO.
ENVIRONMENT DIVISION.
DATA DIVISION.
******
WORKING-STORAGE SECTION.
01 FP USAGE POINTER
01 PP USAGE PROCEDURE-POINTER
******
PROCEDURE DIVISION.
CALL “c-function” RETURNING FP.
SET
PP TO FP.
CALL PP.
. . .
Calling to alternate entry points
You can specify another entry point where the program will begin running by
using the ENTRY label in the called program. However, this is not recommended in
a structured program.
Static calls to alternate entry points work without restriction.
Chapter 28. Using subprograms
473
Dynamic calls to alternate entry points require:
v NAME or ALIAS linkage editor control statements.
v The NAME compiler option.
v An intervening CANCEL for dynamic calls to the same module at differing entry
points. CANCEL causes the program to be invoked in initial state when it is called
at a new entry point.
“Example: static and dynamic CALL statements” on page 465
RELATED TASKS
“Using procedure-pointers with DLLs” on page 495
RELATED REFERENCES
“DYNAM” on page 272
“NAME” on page 282
CANCEL statement (IBM COBOL Language Reference)
Procedure pointer (IBM COBOL Language Reference)
ENTRY statement (IBM COBOL Language Reference)
Making programs reentrant
If more than one user will run an application program at the same time (for
example, users in different address spaces accessing the same program residing in
the link pack area), you must make the program reentrant by using the RENT option
when you compile it. You do not need to worry about multiple copies of variables.
The compiler creates the necessary reentrancy controls in your object module.
The following COBOL for OS/390 & VM programs must be reentrant:
v
v
v
v
|
Programs
Programs
Programs
Programs
to
to
to
to
be
be
be
be
used with CICS
preloaded with IMS
used as DB2 stored procedures
run in the OS/390 UNIX environment
For reentrant programs, use the DATA(24|31) compiler option and the HEAP and
ALL31 run-time options to control whether dynamic data areas, such as
WORKING-STORAGE, are obtained from storage below 16 MB or from unrestricted
storage.
RELATED REFERENCES
“RENT” on page 289
“DATA” on page 266
ALL31 run-time option (Language Environment Programming Reference)
HEAP run-time option (Language Environment Programming Reference)
474
Programming Guide
Chapter 29. Sharing data
When a run unit consists of several separately compiled programs that call each
other, the programs must be able to communicate with each other. They also
usually need to have access to common data.
This material describes how you can write programs that can share data with other
programs. For the purposes of this discussion, a subprogram is any program called
by another program.
RELATED TASKS
“Passing data”
“Coding the LINKAGE SECTION” on page 477
“Coding the PROCEDURE DIVISION for passing arguments” on page 478
“Passing return code information” on page 482
“Specifying CALL . . . RETURNING” on page 483
“Sharing data by using the EXTERNAL clause” on page 483
“Sharing files between programs (external files)” on page 483
Passing data
You can choose among three ways of passing data between programs:
BY REFERENCE
The subprogram refers to and processes the data items in storage of the
calling program rather than working on a copy of the data.
BY CONTENT
The calling program passes only the contents of the literal, or identifier.
With a CALL . . . BY CONTENT, the called program cannot change the value
of the literal or identifier in the calling program, even if it modifies the
variable in which it received the literal or identifier.
BY VALUE
The calling program or method passes the value of the literal, or identifier,
not a reference to the sending data item.
The called program or invoked method can change the parameter in the
called program or invoked method. However, because the subprogram or
method has access only to a temporary copy of the sending data item,
these changes do not affect the argument in the calling program.
Determine which of these three data-passing methods to use based on what you
want your program to do with the data:
Code
Purpose
Comments
CALL . . . BY REFERENCE
identifier.
To have the definition of the argument
of the CALL statement in the calling
program and the definition of the
parameter in the called program share
the same memory
Any changes made by the subprogram
to the parameter affect the argument in
the calling program.
© Copyright IBM Corp. 1991, 2000
475
Code
Purpose
Comments
CALL . . . BY REFERENCE.
To pass data control blocks to
assembler programs
Use EXTERNAL or GLOBAL files to share
files between COBOL programs.
If the file-name is for a QSAM
sequential file, the COBOL compiler
passes the address of the data control
block (DCB) as this entry of the
parameter list. The file-name cannot be
a VSAM file-name or a line-sequential
file-name.1
CALL . . . BY CONTENT ADDRESS
OF record-name.
To pass the address of a record area to
a called program
The subprogram receives the ADDRESS
special register for the record-name
that you specify.
You must define the record-name as a
level-01 or level-77 item in the LINKAGE
SECTION of the called and calling
programs. The compiler provides a
separate ADDRESS special register for
each record in the LINKAGE SECTION.
CALL . . . BY CONTENT
identifier.
To prevent the contents of the
argument of the CALL statement in the
calling program and the contents of the
parameter in the called subprogram
from sharing the same memory
CALL . . . BY CONTENT literal.
To pass a literal value to a called
program
The called program cannot change the
value of the literal.
CALL . . . BY CONTENT LENGTH
OF identifier.
To pass the length of a data item
The calling program passes the length
of the identifier from its LENGTH special
register.
A combination of BY REFERENCE
and BY CONTENT such as:
To pass both a data item and its length
to a subprogram
CALL 'ERRPROC'
USING BY REFERENCE A
BY CONTENT LENGTH OF A
CALL . . . BY VALUE
To pass data to a C program that
expects the value of the argument
CALL . . . BY REFERENCE
To pass data to a C program that
expects a reference (pointer) to the
argument and that you want to modify
the value of the argument
CALL . . . BY CONTENT
To pass data to a C program that
expects a reference (pointer) to the
argument and that you do not want to
modify the value of the argument
CALL . . . RETURNING
To call a C/C++ function with a
function return value
Parameters must be of certain data
types to be passed BY VALUE.
1. File-names as CALL operands are allowed as an IBM extension to COBOL. Any use of the extension generally
depends on the specific internal implementation of the compiler. Control block field settings might change in
future releases. Any changes made to the control block are the user’s responsibility and not supported by IBM.
476
Programming Guide
Describing arguments in the calling program
In the calling program, describe arguments in the DATA DIVISION in the same
manner as other data items in the DATA DIVISION. Describe these data items in the
LINKAGE SECTION of all the programs that it calls directly or indirectly.
Storage for arguments is allocated only in the highest outermost program. For
example, program A calls program B, which calls program C. Data items are
allocated in program A and are described in the LINKAGE sections of programs B
and C, making the one set of data available to all three programs.
If you reference data in a file, the file must be open when the data is referenced.
Code the USING clause of the CALL statement to pass the arguments.
Do not pass parameters allocated in storage above 16 MB to AMODE(24)
subprograms. Use the DATA(24) option if the RENT option is in effect, or the
RMODE(24) option if the NORENT option is in effect.
Describing parameters in the called program
You must know what is being passed from the calling program and describe it in
the LINKAGE SECTION of the called program.
Code the USING clause after the PROCEDURE-DIVISION header to receive the
parameters.
RELATED TASKS
“Specifying CALL . . . RETURNING” on page 483
“Sharing data by using the EXTERNAL clause” on page 483
“Sharing files between programs (external files)” on page 483
RELATED REFERENCES
CALL statement (IBM COBOL Language Reference)
INVOKE statement (IBM COBOL Language Reference)
Coding the LINKAGE SECTION
Code the same number of data-names in the identifier list of the calling program as
the number of data-names in the identifier list of the called program. Synchronize
them by position because the compiler passes the first identifier of the calling
program to the first identifier of the called program, and so on.
You will introduce errors if the number of data-names in the identifier list of a called
program is greater than the number of data-names in the identifier list of the calling
program. The compiler does not try to match arguments and parameters.
The following figure shows a data item being passed from one program to another.
Chapter 29. Sharing data
477
In the calling program, the code for parts (PARTCODE) and the part number (PARTNO)
are referred to separately. In the called program, by contrast, the code for parts and
the part number are combined into one data item (PART-ID). A reference in the
called program to PART-ID is the only valid reference to these items.
Coding the PROCEDURE DIVISION for passing arguments
If you pass an argument BY VALUE, use the USING BY VALUE clause on the PROCEDURE
DIVISION header of the subprogram:
PROCEDURE DIVISION USING BY VALUE
If you pass an argument BY REFERENCE or BY CONTENT, you do not need to indicate
how the argument was passed on the PROCEDURE DIVISION.
You can code the header in either of the following ways:
PROCEDURE DIVISION USING
PROCEDURE DIVISION USING BY REFERENCE
RELATED REFERENCES
The procedure division header (IBM COBOL Language Reference)
Grouping data to be passed
Consider grouping all the data items you want to pass between programs and
putting them under one level-01 item. If you do this, you can pass a single level-01
record between programs.
To make the possibility of mismatched records even smaller, put the level-01 record
into a copy library and copy it in both programs. That is, copy it in the
WORKING-STORAGE SECTION of the calling program and in the LINKAGE SECTION of the
called program.
RELATED TASKS
“Coding the LINKAGE SECTION” on page 477
Handling null-terminated strings
COBOL supports null-terminated strings when you use null-terminated literals, the
hexadecimal literal X’00’, and string-handling verbs.
478
Programming Guide
You can manipulate null-terminated strings (passed from a C program, for
example) by using string-handling mechanisms such as those shown for the
following code:
01
01
01
01
01
L
M
N
N-Length
Y
pic
pic
pic
pic
pic
X(20) value
X(20) value
X(20).
99
value
X(13) value
z'ab'.
z'cd'.
zero.
'Hello, World!'.
To display a null-terminated string, you can inspect N by tallying N-length for
characters before the initial X’00’:
Display 'N: ' N(1:N-length) ' Length: ' N-length
To move a null-terminated string to alphanumeric and strip null:
Unstring N
delimited by X'00'
into X
To create a null-terminated string:
String Y
delimited by size
X'00' delimited by size
into N.
To concatenate two null-terminated strings:
String L
delimited by x'00'
M
delimited by x'00'
X'00' delimited by size
into N.
RELATED TASKS
“Manipulating null-terminated strings” on page 85
RELATED REFERENCES
Null-terminated nonnumeric literals (IBM COBOL Language Reference)
Using pointers to process a chained list
When you want to pass and receive addresses of record areas, you can manipulate
pointer data items, which are a special type of data item to hold addresses. Pointer
data items are data items that either are defined with the USAGE IS POINTER clause
or are ADDRESS special registers. A typical application for using pointer data items
is in processing a chained list (a series of records where each record points to the
next).
When you pass addresses between programs in a chained list, you can use NULL to
assign the value of an address that is not valid (nonnumeric 0) to pointer items.
You can assign the value NULL to a pointer data item in two ways:
v Use a VALUE IS NULL clause in its data definition.
v Use NULL as the sending field in a SET statement.
In the case of a chained list in which the pointer data item in the last record
contains a null value, the code to check for the end of the list is as follows:
IF PTR-NEXT-REC = NULL
. . .
(logic for end of chain)
If the program has not reached the end of the list, the program can process the
record and move on to the next record.
Chapter 29. Sharing data
479
The data passed from a calling program might contain header information that you
want to ignore. Because pointer data items are not numeric, you cannot directly
perform arithmetic on them. However, to bypass header information, you can use
the SET statement to increment the passed address.
“Example: using pointers to process a chained list”
RELATED TASKS
“Coding the LINKAGE SECTION” on page 477
“Coding the PROCEDURE DIVISION for passing arguments” on page 478
RELATED REFERENCES
SET statement (IBM COBOL Language Reference)
Example: using pointers to process a chained list
For this example, picture a chained list of data that consists of individual salary
records. The following figure shows one way to visualize how these records are
linked in storage:
The first item in each record points to the next record, except for the last record.
The first item in the last record contains a null value instead of an address, to
indicate that it is the last record.
The high-level logic of an application that processes these records might look as
follows:
OBTAIN ADDRESS OF FIRST RECORD IN CHAINED LIST FROM ROUTINE
CHECK FOR END OF THE CHAINED LIST
DO UNTIL END OF THE CHAINED LIST
PROCESS RECORD
GO ON TO THE NEXT RECORD
END
The following code contains an outline of the calling program, LISTS, used in this
example of processing a chained list.
IDENTIFICATION DIVISION.
PROGRAM-ID. LISTS.
ENVIRONMENT DIVISION.
DATA DIVISION.
******
WORKING-STORAGE SECTION.
77 PTR-FIRST
POINTER VALUE IS NULL.
77 DEPT-TOTAL
PIC 9(4) VALUE IS 0.
******
LINKAGE SECTION.
01 SALARY-REC.
02 PTR-NEXT-REC
POINTER.
02 NAME
PIC X(20).
02 DEPT
PIC 9(4).
02 SALARY
PIC 9(6).
01 DEPT-X
PIC 9(4).
480
Programming Guide
(1)
(2)
******
PROCEDURE DIVISION USING DEPT-X.
******
* FOR EVERYONE IN THE DEPARTMENT RECEIVED AS DEPT-X,
* GO THROUGH ALL THE RECORDS IN THE CHAINED LIST BASED ON THE
* ADDRESS OBTAINED FROM THE PROGRAM CHAIN-ANCH
* AND CUMULATE THE SALARIES.
* IN EACH RECORD, PTR-NEXT-REC IS A POINTER TO THE NEXT RECORD
* IN THE LIST; IN THE LAST RECORD, PTR-NEXT-REC IS NULL.
* DISPLAY THE TOTAL.
******
CALL “CHAIN-ANCH” USING PTR-FIRST
(3)
SET ADDRESS OF SALARY-REC TO PTR-FIRST
(4)
******
PERFORM WITH TEST BEFORE UNTIL ADDRESS OF SALARY-REC = NULL (5)
IF DEPT = DEPT-X
THEN ADD SALARY TO DEPT-TOTAL
ELSE CONTINUE
END-IF
SET ADDRESS OF SALARY-REC TO PTR-NEXT-REC
(6)
END-PERFORM
******
DISPLAY DEPT-TOTAL
GOBACK.
(1)
PTR-FIRST is defined as a pointer data item with an initial value of NULL.
On a successful return from the call to CHAIN-ANCH, PTR-FIRST contains the
address of the first record in the chained list. If something goes amiss with
the call, however, and PTR-FIRST never receives the value of the address of
the first record in the chain, a null value remains in PTR-FIRST and,
according to the logic of the program, the records will not be processed.
(2)
The LINKAGE SECTION of the calling program contains the description of the
records in the chained list. It also contains the description of the
department code that is passed, using the USING clause of the CALL
statement.
(3)
To obtain the address of the first SALARY-REC record area, the LISTS
program calls the program CHAIN-ANCH:
(4)
The SET statement bases the record description SALARY-REC on the address
contained in PTR-FIRST.
(5)
The chained list in this example is set up so that the last record contains an
address that is not valid. This check for the end of the chained list is
accomplished with a DO WHILE structure where the value NULL is assigned
to the pointer data item in the last record.
(6)
The address of the record in the LINKAGE-SECTION is set equal to the
address of the next record by means of the pointer data item sent as the
first field in SALARY-REC. The record-processing routine repeats, processing
the next record in the chained list.
To increment addresses received from another program, you could set up the
LINKAGE SECTION and PROCEDURE DIVISION like this:
LINKAGE SECTION.
01 RECORD-A.
02 HEADER
PIC X(12).
02 REAL-SALARY-REC PIC X(30).
. . .
01 SALARY-REC.
02 PTR-NEXT-REC
POINTER.
Chapter 29. Sharing data
481
02 NAME
PIC X(20).
02 DEPT
PIC 9(4).
02 SALARY
PIC 9(6).
. . .
PROCEDURE DIVISION USING DEPT-X.
. . .
SET ADDRESS OF SALARY-REC TO ADDRESS OF REAL-SALARY-REC
The address of SALARY-REC is now based on the address of REAL-SALARY-REC, or
RECORD-A + 12.
RELATED TASKS
“Using pointers to process a chained list” on page 479
Passing return code information
Use the RETURN-CODE special register to pass and receive return codes between
programs. Methods do not return information in the RETURN-CODE special register,
but they can check the register after a call to a program.
You can also use the RETURNING phrase on the PROCEDURE DIVISION header in your
method to return information to an invoking program or method. If you use
PROCEDURE DIVISION . . . RETURNING with CALL . . . RETURNING, the RETURN-CODE
register will not be set.
Understanding the RETURN-CODE special register
When a COBOL program returns to its caller, the contents of the RETURN-CODE
special register are stored into register 15. When control is returned to a COBOL
program or method from a call, the contents of register 15 are stored into the
RETURN-CODE special register of the calling program or method. When control is
returned from a COBOL program to the operating system, the special register
contents are returned as a user return code.
You might need to think about this handling of the RETURN-CODE when control is
returned to a COBOL program from a non-COBOL program. If the non-COBOL
program does not use register 15 to pass back the return code, then the
RETURN-CODE special register of the COBOL program might be updated with a
value that is not valid. Unless you set this special register to a meaningful value
before your COBOL for OS/390 & VM program returns to the operating system, a
return code that is not valid will be passed back to the system.
For equivalent function between COBOL and C programs, have your COBOL
program call the C program with the RETURNING option. If the C program (function)
correctly declares a function value, the RETURNING value of the calling COBOL
program will be set.
You cannot set the RETURN-CODE special register by using the INVOKE statement.
Using PROCEDURE DIVISION RETURNING . . .
Use the RETURNING phrase on the PROCEDURE DIVISION header of your program to
return information to the calling program:
PROCEDURE DIVISION RETURNING dataname2
When the called program successfully returns to its caller, the value in dataname2 is
stored into the identifier that you specified in the RETURNING phrase of the CALL
statement:
482
Programming Guide
CALL . . . RETURNING dataname2
Specifying CALL . . . RETURNING
You can specify the RETURNING phrase of the CALL statement for calls to functions in
C/C++ or to subroutines in COBOL.
It has the following format:
CALL . . . RETURNING dataname2
The return value of the called program is stored into dataname2.
You must define dataname2 in the DATA DIVISION of the calling COBOL program.
The data type of the return value that is declared in the target function must be
identical to the data type of dataname2.
Sharing data by using the EXTERNAL clause
Use the EXTERNAL clause to allow separately compiled programs and methods
(including programs in a batch sequence) to share data items.
Code EXTERNAL on the 01-level data description in the WORKING-STORAGE SECTION of
your program or method. The following rules apply:
v Items that are subordinate to an EXTERNAL group item are themselves EXTERNAL.
v You cannot use the name for the data item as the name for another EXTERNAL
item in the same program.
v You cannot code the VALUE clause for any group item, or subordinate item, that
is EXTERNAL.
In the run unit, any COBOL program or method that has the same data description
for the item as the program containing the item can access and process the data
item. For example, suppose program A has the following data description:
01 EXT-ITEM1
EXTERNAL
PIC 99.
Program B could access that data item by having the identical data description in
its WORKING-STORAGE SECTION.
Remember, any program that has access to an EXTERNAL data item can change its
value. Do not use this clause for data items that you need to protect.
Sharing files between programs (external files)
Use the EXTERNAL clause for files to allow separately compiled programs or
methods in the run unit to access common files. It is recommended that you follow
these guidelines:
v Use the same data-name in the FILE STATUS clause of all the programs that
check the file status code.
v For all programs that check the same file status field, code the EXTERNAL clause
on the level-01 data definition for the file status field in each program.
Using external files has these benefits:
v Your main program can reference the record area of the file, although the main
program does not contain any input or output statements.
v Each subprogram can control a single input or output function, such as OPEN or
READ.
Chapter 29. Sharing data
483
v Each program has access to the file.
“Example: using external files”
RELATED REFERENCES
EXTERNAL clause (IBM COBOL Language Reference)
Example: using external files
The table below describes the main program and subprograms used in the example
that follows.
Name
Function
ef1
The main program, which calls all the subprograms and then verifies the
contents of a record area
ef1openo
Opens the external file for output and checks the file status code
ef1write
Writes a record to the external file and checks the file status code
ef1openi
Opens the external file for input and checks the file status code
ef1read
Reads a record from the external file and checks the file status code
ef1close
Closes the external file and checks the file status code
Additionally, COPY statements ensure that each subprogram contains an identical
description of the file.
Each program in the example declares a data item with the EXTERNAL clause in its
WORKING-STORAGE SECTION. This item is used for checking file status codes and is
also placed using the COPY statement.
Each program uses three copy library members:
v The first is named efselect and is placed in the FILE-CONTROL paragraph.
Select ef1
Assign To ef1
File Status Is efs1
Organization Is Sequential.
v The second is named effile and is placed in the FILE SECTION.
Fd ef1 Is External
Record Contains 80 Characters
Recording Mode F.
01 ef-record-1.
02 ef-item-1
Pic X(80).
v The third is named efwrkstg and is placed in the WORKING-STORAGE SECTION.
01
efs1
Pic 99 External.
Input-output using external files
Identification Division.
Program-Id.
ef1.
*
* This is the main program that controls the external file
* processing.
*
Environment Division.
Input-Output Section.
File-Control.
Copy efselect.
Data Division.
484
Programming Guide
File Section.
Copy effile.
Working-Storage Section.
Copy efwrkstg.
Procedure Division.
Call “ef1openo”
Call “ef1write”
Call “ef1close”
Call “ef1openi”
Call “ef1read”
If ef-record-1 = “First record” Then
Display “First record correct”
Else
Display “First record incorrect”
Display “Expected: ” “First record”
Display “Found
: ” ef-record-1
End-If
Call “ef1close”
Goback.
End Program ef1.
Identification Division.
Program-Id.
ef1openo.
*
* This program opens the external file for output.
*
Environment Division.
Input-Output Section.
File-Control.
Copy efselect.
Data Division.
File Section.
Copy effile.
Working-Storage Section.
Copy efwrkstg.
Procedure Division.
Open Output ef1
If efs1 Not = 0
Display “file status ” efs1 “ on open output”
Stop Run
End-If
Goback.
End Program ef1openo.
Identification Division.
Program-Id.
ef1write.
*
* This program writes a record to the external file.
*
Environment Division.
Input-Output Section.
File-Control.
Copy efselect.
Data Division.
File Section.
Copy effile.
Working-Storage Section.
Copy efwrkstg.
Procedure Division.
Move “First record” to ef-record-1
Write ef-record-1
If efs1 Not = 0
Display “file status ” efs1 “ on write”
Stop Run
End-If
Goback.
End Program ef1write.
Chapter 29. Sharing data
485
Identification Division.
Program-Id.
ef1openi.
*
* This program opens the external file for input.
*
Environment Division.
Input-Output Section.
File-Control.
Copy efselect.
Data Division.
File Section.
Copy effile.
Working-Storage Section.
Copy efwrkstg.
Procedure Division.
Open Input ef1
If efs1 Not = 0
Display “file status ” efs1 “ on open input”
Stop Run
End-If
Goback.
End Program ef1openi.
Identification Division.
Program-Id.
ef1read.
*
* This program reads a record from the external file.
*
Environment Division.
Input-Output Section.
File-Control.
Copy efselect.
Data Division.
File Section.
Copy effile.
Working-Storage Section.
Copy efwrkstg.
Procedure Division.
Read ef1
If efs1 Not = 0
Display “file status ” efs1 “ on read”
Stop Run
End-If
Goback.
End Program ef1read.
Identification Division.
Program-Id.
ef1close.
*
* This program closes the external file.
*
Environment Division.
Input-Output Section.
File-Control.
Copy efselect.
Data Division.
File Section.
Copy effile.
Working-Storage Section.
Copy efwrkstg.
Procedure Division.
Close ef1
If efs1 Not = 0
Display “file status ” efs1 “ on close”
486
Programming Guide
Stop Run
End-If
Goback.
End Program ef1close.
Chapter 29. Sharing data
487
488
Programming Guide
Chapter 30. Creating a DLL or a DLL application
Creating a dynamic link library (DLL) or a DLL application is similar to creating a
regular COBOL application. It involves writing, compiling, and linking your source
code.
Special considerations when writing a DLL or a DLL application include:
v Determining how the parts of the load module or the application relate to each
other or to other DLLs
v Deciding what linking or calling mechanisms to use
Depending on whether you want a DLL load module or a load module that
references a separate DLL, you need to use slightly different compiling and linking
options.
RELATED CONCEPTS
Dynamic link libraries (DLLs)
RELATED TASKS
“Using CALL identifier with DLLs” on page 493
“Using DLL linkage and dynamic calls together” on page 494
“Using COBOL DLLs with C/C++ programs” on page 498
“Using DLLs in OO COBOL applications” on page 498
“Compiling programs to create DLLs” on page 490
“Linking DLLs” on page 491
“Using procedure pointers” on page 472
Dynamic link libraries (DLLs)
A DLL is a load module or a program object that can be accessed from other
separate load modules. A DLL differs from a traditional load module in that it
exports definitions of programs, functions, or variables to DLLs, DLL applications,
or non-DLLs. Therefore, you do not need to link the target routines into the same
load module as the referencing routine. When an application references a separate
DLL for the first time, the system automatically loads the DLL into memory. In
other words, calling a program in a DLL is similar to calling a load module with a
dynamic CALL.
© Copyright IBM Corp. 1991, 2000
489
A DLL application is an application that references imported definitions of
programs, functions, or variables.
Although some functions of OS/390 DLLs overlap the functions provided by
COBOL dynamic CALL statements, DLLs have several advantages over regular
OS/390 load modules and dynamic calls:
v DLLs are common across COBOL, C, and C++, thus providing better
interoperation for applications that use multiple programming languages.
Reentrant COBOL and C/C++ DLLs can also interoperate smoothly.
v You can make calls to programs in separate DLL modules that have long
program names. (Dynamic call resolution truncates program names to eight
characters.) Using the COBOL option PGMNAME(LONGUPPER) or PGMNAME(LONGMIXED)
and the COBOL DLL support, you can make calls between load modules with
names of up to 160 characters.
v DLLs are the primary means for packaging SOM class libraries, both those
provided by IBM and those written by users. The OS/390 SOMobjects product is
shipped as a set of DLLs. The COBOL DLL support enables object-oriented
COBOL applications to access SOM from the DLLs. You do not have to statically
link a copy of the SOM kernel into OO COBOL application load modules.
DLLs are supported by IBM Language Environment, based on function provided
by the OS/390 DFSMS program management binder. DLL support is available for
applications running under OS/390 in batch or in TSO, CICS, UNIX, or IMS
environments. DLL support is not available under VM.
|
|
|
RELATED TASKS
Building class libraries (OS/390 SOMobjects Programmer’s Guide)
RELATED REFERENCES
“PGMNAME” on page 287
Binder support for DLLs (OS/390 DFSMS: Program Management)
Compiling programs to create DLLs
When you compile a COBOL program with the DLL option, it becomes enabled for
DLL support. Applications that use DLL support must be reentrant. Therefore, you
must compile them with the RENT compiler option and link them with the RENT
binder option.
|
In an application with DLL support, use the following compiler options depending
on where the programs or classes are:
Programs or classes in:
Compile with:
Root load module
DLL, RENT, NOEXPORTALL
DLL load modules used by other load modules
DLL, RENT, EXPORTALL
If a DLL load module includes some programs or classes that are used only from
within the DLL module, you can hide these routines inside the DLL by compiling
them with NOEXPORTALL.
“Example: sample JCL for a procedural DLL application” on page 492
RELATED TASKS
“Linking DLLs” on page 491
490
Programming Guide
“Prelinking certain DLLs” on page 492
“Chapter 30. Creating a DLL or a DLL application” on page 489
RELATED REFERENCES
“DLL” on page 270
“EXPORTALL” on page 272
“RENT” on page 289
Linking DLLs
You can link your DLL-enabled object modules into separate DLL load modules, or
you can link them together statically. You can decide whether to package the
application as one module or as several DLL modules at link time.
|
|
|
|
|
Use of the DLL support in the DFSMS binder is recommended for linking DLL
applications. The DFSMS binder can now directly receive the output of the COBOL
compilers, thus eliminating the prelink step. However, you must use the prelinker
if your DLL must reside in a PDS load library or you will deploy the DLL on a
CICS system at a level lower than CICS Transaction Server 1.3.
|
A binder-based DLL must reside in a PDSE or in an HFS file, rather than in a PDS.
|
|
When linking a DLL application by using the DFSMS binder, use the following
binder options:
Type of code
Link using binder parameters:
|
|
DLL applications
DYNAM(DLL), RENT, COMPAT(PM3) or
COMPAT(CURRENT)
|
|
Applications that use mixed-case exported
program names
CASE(MIXED)
|
Class definitions or INVOKE statements
You must specify a SYSDEFSD DD statement to indicate the data set where the binder
should create a DLL definition side file. This side file contains IMPORT control
statements for each symbol exported by a DLL. The binder SYSLIN input (the
binding code that references the DLL code) must include the DLL definition side
files for the DLLs that are to be referenced from the module being linked.
If there are programs in the module that you do not want to make available with
DLL linkage, you can edit the definition side file to remove these programs.
|
|
|
|
If a DLL must reside in a PDS load library or if the output will be deployed on a
CICS system at a level lower than CICS Transaction Server 1.3, you must prelink
the application by using the Language Environment prelinker before standard
linkage editing.
“Example: sample JCL for a procedural DLL application” on page 492
RELATED TASKS
“Chapter 30. Creating a DLL or a DLL application” on page 489
“Compiling programs to create DLLs” on page 490
“Prelinking certain DLLs” on page 492
OS/390 DFSMS: Program Management
Chapter 30. Creating a DLL or a DLL application
491
RELATED REFERENCES
Binder support for DLLs (OS/390 DFSMS: Program Management)
Prelinking certain DLLs
You need to use the Language Environment prelinker before standard linkage
editing in the following cases:
v The DLL must reside in a PDS load library, rather than in a PDSE or an HFS file.
v The output will be deployed on a CICS system at a level lower than CICS
Transaction Server 1.3.
|
|
|
|
|
After compiling your source DLL, prelink the object modules to form a single
object module:
1. Specify a SYSDEFSD DD statement for the prelink step to indicate the data set
where the prelinker should create a DLL definition side file for the DLL. This
side file contains IMPORT prelinker control statements for each symbol exported
by the DLL. The prelinker uses this side file to prelink other modules that
reference the new DLL.
2. Specify the DLLNAME(xxx) prelinker option to indicate the DLL load module
name for the prelinker to use in constructing the IMPORT control statements in
the side file. Alternatively, the prelinker can obtain the DLL load module name
from the NAME prelinker control statement or from the PDS member name in the
SYSMOD DD statement for the prelink step.
3. If this DLL references any other DLLs, include the definition side files for these
DLLs together with the object decks that are input to this prelink step. These
side files instruct the prelinker to resolve the symbolic references in the current
module to the symbols exported from the other DLLs.
Use the linkage editor or binder as usual to create the DLL load module from the
object module produced by the prelinker. Specify the RENT option of the linkage
editor or binder.
“Example: sample JCL for a procedural DLL application”
RELATED TASKS
“Compiling programs to create DLLs” on page 490
“Linking DLLs” on page 491
Example: sample JCL for a procedural DLL application
The following sample shows how to create an application that consists of a main
program calling a DLL subprogram. The first step creates the DLL load module
containing the subprogram DemoDLLSubprogram. The second step creates the main
load module containing the program MainProgram. The third step runs the
application.
//DLLSAMP JOB ,
// TIME=(1),MSGLEVEL=(1,1),MSGCLASS=H,CLASS=A,
// NOTIFY=&SYSUID,USER=&SYSUID
// SET LEPFX='SYS1'
//*--------------------------------------------------------------------//* Compile COBOL subprogram, bind to form a DLL.
//*--------------------------------------------------------------------//STEP1 EXEC IGYWCL,REGION=80M,GOPGM=DEMODLL,
//
PARM.COBOL='RENT,PGMN(LM),DLL,EXPORTALL',
//
PARM.LKED='RENT,LIST,XREF,LET,MAP,DYNAM(DLL),CASE(MIXED)'
//COBOL.SYSIN
DD *
Identification division.
Program-id. “DemoDLLSubprogram”.
|
|
492
Programming Guide
Procedure division.
Display “Hello from DemoDLLSubprogram!”.
End program “DemoDLLSubprogram”.
|
|
|
|
|
/*
//LKED.SYSDEFSD DD DSN=&&SIDEDECK,UNIT=SYSDA,DISP=(NEW,PASS),
//
SPACE=(TRK,(1,1))
//LKED.SYSLMOD
DD DSN=&&GOSET(&GOPGM),DSNTYPE=LIBRARY,DISP=(MOD,PASS)
//LKED.SYSIN
DD DUMMY
//*--------------------------------------------------------------------//* Compile and bind COBOL main program
//*--------------------------------------------------------------------//STEP2 EXEC IGYWCL,REGION=80M,GOPGM=MAINPGM,
//
PARM.COBOL='RENT,PGMNAME(LM),DLL',
//
PARM.LKED='RENT,LIST,XREF,LET,MAP,DYNAM(DLL),CASE(MIXED)'
//COBOL.SYSIN
DD *
Identification division.
Program-id. “MainProgram”.
Procedure division.
Call “DemoDLLSubprogram”
Stop Run.
End program “MainProgram”.
/*
//LKED.SYSIN
DD DSN=&&SIDEDECK,DISP=(OLD,DELETE)
//*--------------------------------------------------------------------//* Execute the main program, calling the subprogram DLL.
//*--------------------------------------------------------------------//STEP3 EXEC PGM=MAINPGM,REGION=80M
//STEPLIB DD DSN=&&GOSET,DISP=(OLD,DELETE)
//
DD DSN=&LEPFX..SCEERUN,DISP=SHR
//SYSOUT DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
Using CALL identifier with DLLs
|
|
|
In a COBOL program that has been compiled with the DLL option, you can use
CALL identifier statements as well as CALL literal statements to make calls to DLLs.
However, there are a few additional considerations for the CALL identifier case.
|
|
|
|
|
|
|
For the contents of the identifier or for the literal in the CALL statement, use the
name of either of the following programs:
v A nested program in the same compilation unit as is eligible to be called from
the program containing the CALL identifier statement.
v A program in a separately bound DLL module. The target program name must
be exported from the DLL, and the DLL module name must match the exported
name of the target program.
|
|
|
|
|
In the nonnested case, the run-time environment interprets the program name in
the identifier according to the setting of the PGMNAME compiler option of the program
containing the CALL statement, and interprets the program name that is exported
from the target DLL according to the setting of the PGMNAME option used when the
target program was compiled.
|
|
|
|
The search for the target DLL in the hierarchical file system (HFS) is case sensitive.
If the target DLL is a PDS or PDSE member, then the DLL member name must be
eight characters or less. For the purpose of the search for the DLL as a PDS or
PDSE member, the run time automatically converts the name to uppercase.
|
|
|
|
If the run-time environment cannot resolve the CALL statement in either of these
cases, control is transferred to the ON EXCEPTION or ON OVERFLOW phrase of the CALL
statement. If the CALL statement does not specify one of these phrases in this
situation, Language Environment raises a severity-3 condition.
Chapter 30. Creating a DLL or a DLL application
493
RELATED TASKS
“Using DLL linkage and dynamic calls together”
“Compiling programs to create DLLs” on page 490
“Linking DLLs” on page 491
RELATED REFERENCES
“DLL” on page 270
“PGMNAME” on page 287
CALL statement (IBM COBOL Language Reference)
“Search order for DLLs in HFS”
Search order for DLLs in HFS
|
|
|
When you use the hierarchical file system (HFS), the search order for resolving a
DLL reference in a CALL statement depends on the setting of the Language
Environment POSIX run-time option.
|
|
|
|
|
|
|
|
|
If the POSIX run-time option is set to ON, the search order is as follows:
1. The run-time environment looks for the DLL in the HFS. If the LIBPATH
environment variable is set, the run time searches each directory listed.
Otherwise, it searches just the current directory. The search for the DLL in the
HFS is case sensitive.
2. If the run-time environment does not find the DLL in the HFS, it tries to load
the DLL from the MVS load library search order of the caller. In this case, the
DLL name must be eight characters or less. The run time automatically
converts the DLL name to uppercase for this search.
|
|
|
|
|
If the POSIX run-time option is set to OFF, the search order is reversed:
1. The run-time environment tries to load the DLL from the search order for the
load library of the caller.
2. If the run-time environment cannot load the DLL from this load library, it tries
to load the DLL from the HFS.
RELATED TASKS
“Using CALL identifier with DLLs” on page 493
RELATED REFERENCES
POSIX (Language Environment Programming Reference)
Using DLL linkage and dynamic calls together
|
|
|
|
|
|
For applications (that is, Language Environment enclaves) that are structured as
multiple, separately bound modules, you should use exclusively one form of
linkage between modules: either dynamic call linkage or DLL linkage. DLL linkage
refers to a call in a program that is compiled with the DLL and NODYNAM options
where the call resolves to an exported name in a separate module. DLL linkage can
also refer to an invocation of a method that is defined in a separate module.
|
|
|
However, some applications require more flexibility. In these cases, you can use
both DLL linkage and COBOL dynamic call linkage within a Language
Environment enclave if the programs are compiled as follows:
ProgramA
ProgramB
Compile both with:
|
Contains dynamic call
Target of dynamic call
NODLL
|
Uses DLL linkage
Contains target program or method
DLL
494
Programming Guide
|
|
Important: This support is available only in Language Environment V2R9 and
higher.
|
|
|
|
If a program contains a CALL statement for a separately compiled program and you
compile one program with the DLL compiler option and the other program with
NODLL, then the CALL is supported only if you bind the two programs together in
the same module.
The following diagram shows several separately bound modules that mix dynamic
calls and DLL linkage:
You cannot cancel programs that are called using DLL linkage.
All components of a DLL application must have the same AMODE. The automatic
AMODE switching normally provided by COBOL dynamic calls is not available for
DLL linkages.
Using procedure-pointers with DLLs
|
|
|
|
|
|
|
|
|
|
|
|
|
|
In run units that contain a mix of DLLs and non-DLLs, use procedure-pointers
with care. When you use the SET procedure-pointer-1 TO ENTRY entryname
statement in a program that is compiled with the NODLL option, you must not pass
the procedure-pointer to a program that is compiled with the DLL option. However,
when you use this statement in a program that is compiled with the DLL option,
you can pass the procedure-pointer to a program that is in a separately bound DLL
module.
If you compile with the NODYNAM and DLL options and entryname is an identifier, the
identifier value must refer to the entry point name that is exported from a DLL
module. The DLL module name must match the name of the exported entry point.
The following are further considerations in this case:
v The program name that is contained in the identifier is interpreted according to
the setting of the PGMNAME(COMPAT|LONGUPPER|LONGMIXED) compiler option of the
program containing the CALL statement.
v The program name that is exported from the target DLL is interpreted according
to the setting of the PGMNAME option used when compiling the target program.
v The search for the target DLL in the HFS is case sensitive.
Chapter 30. Creating a DLL or a DLL application
495
v If the target DLL is a PDS or PDSE member, then the DLL member name must
be eight characters or less. For the purpose of the search for the DLL as a PDS or
PDSE member, the name is automatically converted to uppercase.
|
|
|
Calling DLLs from non-DLLs
It is possible to call a DLL from a COBOL program that is compiled with the NODLL
option, but there are restrictions. You can use the following methods to ensure that
the DLL linkage is followed:
v Put the COBOL DLL programs that you want to call from the COBOL non-DLL
programs in the load module that contains the main program. Use static calls
from the COBOL non-DLL programs to call the COBOL DLL programs.
The COBOL DLL programs in the load module that contains the main program
can call COBOL DLL programs in other DLLs.
v Put the COBOL DLL programs in DLLs and call them from COBOL non-DLL
programs with CALL procedure-pointer, where the procedure-pointer is set to a
function descriptor of the program to be called. You can obtain the address of
the function descriptor for the program in the DLL by calling a C routine that
uses dllload and dllqueryfn.
“Example: calling DLLs from non-DLLs”
RELATED CONCEPTS
“Dynamic link libraries (DLLs)” on page 489
RELATED TASKS
“Using CALL identifier with DLLs” on page 493
“Using procedure pointers” on page 472
“Compiling programs to create DLLs” on page 490
“Linking DLLs” on page 491
RELATED REFERENCES
“DLL” on page 270
“EXPORTALL” on page 272
Example: calling DLLs from non-DLLs
The following sample code shows how a COBOL program that is not in a DLL
(COBOL1) can call a COBOL program that is in a DLL (program ooc05R in DLL
OOC05R):
CBL NODYNAM
IDENTIFICATION DIVISION.
PROGRAM-ID. 'COBOL1'.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
DATA DIVISION.
FILE SECTION.
WORKING-STORAGE SECTION.
01 DLL-INFO.
03 DLL-LOADMOD-NAME PIC X(12).
03 DLL-PROGRAM-NAME PIC X(160).
03 DLL-PROGRAM-HANDLE POINTER.
77 DLL-RC
PIC S9(9) BINARY.
77 DLL-PROGRAM-PTR
PROCEDURE-POINTER.
77 DLL-STATUS
88 DLL-LOADED
88 DLL-NOT-LOADED
496
Programming Guide
PIC X(1) VALUE 'N'.
VALUE 'Y'.
VALUE 'N'.
PROCEDURE DIVISION.
*
IF DLL-NOT-LOADED
THEN
Move the names in. They must be null terminated.
MOVE Z'OOC05R' TO DLL-LOADMOD-NAME
MOVE Z'ooc05r' TO DLL-PROGRAM-NAME
*
*
Call the C routine to load the DLL and to get the
function descriptor address.
CALL 'A1CCDLGT' USING BY REFERENCE DLL-INFO
BY REFERENCE DLL-RC
IF DLL-RC = 0
THEN
SET DLL-LOADED TO TRUE
ELSE
DISPLAY 'A1CCLDGT failed with rc = '
DLL-RC
MOVE 16 TO RETURN-CODE
STOP RUN
END-IF
END-IF
*
*
*
Move the function pointer to a procedure pointer
so that we can use the call statement to call the
program in the DLL.
SET DLL-PROGRAM-PTR TO DLL-PROGRAM-HANDLE
*
Call the program in the DLL.
CALL DLL-PROGRAM-PTR
GOBACK.
#include <stdio.h>
#include <dll.h>
#pragma linkage (A1CCDLGT,COBOL)
typedef struct
char
char
void
} dll_lm;
dll_lm {
dll_loadmod">